# Platform Smart Contract API
# Overview
The functions provided by the TOP Network platform contract are node registration, node voting, node access, node election, and chain governance.
The Platform contract functions are shown is the following table.
| Function Name | Description |
|---|---|
| nodeJoinNetwork | Run node joining network contract. |
| submitProposal | Submit proposal. |
| withdrawProposal | Withdraw proposal. |
| tccVote | TCC vote on proposal. |
| registerNode | Register miner. |
| unregisterNode | Unregister miner. |
| setDividendRatio | Set miner dividend ratio. |
| setNodeName | Set miner name. |
| redeemNodeDeposit | Redeem miner registration deposit. |
| updateNodeInfo | Update miner name, miner type, miner deposit and dividend ratio at the same time. |
| updateNodeType | Update miner type. |
| stakeDeposit | Increase miner deposit. |
| unstakeDeposit | Decrease miner deposit. |
| voteNode | Vote on miner. |
| unvoteNode | Unvote on miner. |
| claimNodeReward | Claim miner rewards. |
| claimVoterDividend | Claim voter dividend. |
# Node Join Network
Function Name
nodeJoinNetwork
Request Parameters
| Parameter Name | Required | Default Name | Parameter Type | Description |
|---|---|---|---|---|
| miner_account_addr | Yes | - | String | Miner account address. |
Response Parameters
None.
# Submit Proposal
Function Name
submitProposal
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| proposal_type | Yes | - | Uint8 | Proposal Type：1--on-chain governance parameter modification proposal；2--community fund management proposal. |
| target | Yes | - | String | On-Chain Parameter Modification Proposal:Target is on-chain governance parameter,more about on-chain governance parameter please refer to On-Chain Governance Prarameters . Community Fund Management Proposal:Target is burn account address:target is T!0001Ebj8hBvoLdvcEEUwNZ423zM3Kh9d4nL1Ug. |
| value | Yes | - | String | When target is on-chain governance parameter,value=new parameter value. When target is burn account address,value=transferd amount, the unit is uTOP. |
| proposal_deposit | Yes | - | Uint64 | Proposal deposit, the unit is uTOP. |
| effective_timer_height | Yes | - | Uint64 | Proposal effective clock height. If the clock height is less than the clock height at which the proposal was approved, the proposal will take effect immediately. |
Response Parameters
None.
# Withdraw Proposal
Function Name
withdrawProposal
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| proposal_id | Yes | - | String | Proposal ID. |
Response Parameters
None.
# TCC Vote Proposal
Function Name
tccVote
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| proposal_id | Yes | - | String | Proposal ID. |
| opinion | Yes | - | Bool | true or false. |
Response Parameters
None.
# Register Miner
Function Name
registerNode
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| miner_type | Yes | - | String | There are five types of miners in TOP Network: edge, validator, advance, archive and exchange. You can register as one of the first three types of miners. After registering as an advance miner, what kind of node the mine is elected depends on the votes it receives: If the advance miner is to be elected as auditor node, the votes must be greater than or equal to the actual registration deposit of the miner (Here, the node deposit is calculated by TOP, not uTOP). When the votes falls below the actual staked deposit, the advance miner can only be elected as validator. Caution： Miner's votes must be voted by other nodes or by this node himself. After registering as the advance miner, if you increase the miner deposit, the miner needs to increase the corresponding votes if it wants to be elected as auditor. |
| miner_name | Yes | - | String | Miner nick name，4-16 characters, letters, Numbers or underscores. |
| miner_key | Yes | - | String | The public key of the owner key or worker key. Register this public key information in the blockchain system registration contract, and other nodes can use this public key to verify the miner's signature block. To protect the security of your account, it is recommended that you use the owner key and the worker key separately and save the owner key offline. When registering a miner, if you do not add this option, TOPIO will automatically generate a password-free worker key for the current account. The blockchain system uses this worker key for miner registration by default. |
| dividend_ratio | Yes | - | Uint32 | Advance miner can set dividend ratio for accounts that vote for them. All rewards (work rewards, vote rewards) received by advance miner will be distributed to voters who support them according to the set dividend ratio. dividend ratio ∈[0,100]. |
Response Parameters
None.
# Unregister Miner
Function Name
unregisterNode
Request Parameters
None.
Response Parameters
None.
# Set Dividend Ratio
Function Name
setDividendRatio
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| dividend_ratio | Yes | - | Integer | Dividend ratio, value∈[0,100]. |
Response Parameters
None.
# Set Miner Name
Function Name
setNodeName
Request Parameters
| Parameter Name | Required | Default Name | Parameter Type | Description |
|---|---|---|---|---|
| miner_name | Yes | - | String | Miner name. |
Response Parameters
None.
# Redeem Miner Registration Deposit
Function Name
redeemNodeDeposit
Request Parameters
None.
Response Parameters
None.
# Update Miner Information
Function Name
updateNodeInfo
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| miner_name | Yes | - | String | Updated miner name. |
| increase_or_decrease | - | - | Int | 1--Increase miner deposit. 2--Decrease miner deposit. |
| top_num | Yes | - | Uint64 | Miner deposit，in uTOP. |
| dividend_ratio | Yes | - | Uint32 | Updated dividend ratio. Value∈[0,100] |
| miner_type | Yes | - | String | Updated miner type: edge, validator and advance. |
Response Parameters
None.
# Update Miner Type
Function Name
updateNodeType
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| miner_type | Yes | - | String | Miner type. |
Response Parameters
None.
# Increase Miner Deposit
Function Name
stakeDeposit
Request Parameters
None.
Response Parameters
None.
# Decrease Miner Deposit
Function Name
unstakeDeposit
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| unstake_deposit | Yes | - | Uint64 | Decreased deposit, the unit is uTOP. |
Response Parameters
None.
# Vote For Miner
Function Name
voteNode
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| vote_info | Yes | - | std::map<std::String, uint64> | The target account address for the vote(String), number of votes(Uint64). |
Response Parameters
None.
# Unvote on Miner
Function Name
unvoteNode
Request Parameters
| Parameter Name | Required | Default Value | Parameter Type | Description |
|---|---|---|---|---|
| vote_info | Yes | - | std::map<std::String, uint64> | Account address be voted on(String), number of withdrawn votes.(Uint64). |
Response Parameters
None.
# Claim Miner Reward
Function Name
claimNodeReward
Request Parameters
None.
Response Parameters
None.
# Claim Voter Dividend
Function Name
claimVoterDividend
Request Parameters
None.
Response Parameters
None.