# Miners

The chapter Become A Miner has introduced how to become a TOP Network miner. This chapter introduces more information about miners, including how to query and claim miner rewards, how miners stop mining, exit the TOP Network network, etc.

The mining command is shown in the following table.

Command Description
topio mining registerMiner Register as a miner.
topio mining setMinerKey Set the miner key, and the miner uses its private key to sign when working.
topio mining getMinerInfo Get miner information.
topio mining queryMinerReward Query miner reward.
topio mining claimMinerReward Claim miner reward.
topio mining updateMinerInfo Update miner information: miner name, miner type, miner deposit, dividend ratio, etc.
topio mining setDividendRatio Advance miner can set dividend ratio for voters support them.
topio mining setMinerName Set miner name.
topio mining addDeposit Add miner deposit.
topio mining reduceDeposit Reduce miner deposit.
topio mining changeMinerType Change miner type.
topio mining terminate Unregister miner and the nodes exit the network.
topio mining withdrawDeposit Withdraw miner deposit after unregistering the miner.

# Register Miner

There are five types of miners in TOP Network: edge, validator, advance, archive, and exchange node. You can register as one of the first three types of miners.

Advanced miners can serve as two different types of nodes in different networks at the same time: validator and auditor.

The minimum registration deposit for each type of miner is shown in the table below.

Miner Type Minimum Registration Deposit
edge 200,000 TOP
validator 500,000 TOP
advance 1,000,000 TOP

WARNING

After the miner has successfully registered (including the first registration and re-registration after deregistration), the node needs to be started before joining the TOP Network physical network and entering the candidate pool waiting for election. Please refer to Node to start the node.

Request

topio mining registerMiner

Request Parameters

Parameter Name Required Default Value Type Description
top_num Yes - Uint64 Miner registration deposit, the unit is TOP.
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 miner 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 with command topio mining addDeposit, 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.

Options

Option Name Default Value Type Description
--dividend_ratio 0 Uint64 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].
--miner_key The public key of the passwordless work key automatically generated by the system. 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.
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status.

Request Sample

topio mining registerMiner 1000000 advance qiqi --miner_key BK40p+6EYFYLZfXoGBIxt5FsXThg1OZ8LLeP6GuWQG6rhzgKb3IvLSUA9PGGeMqxI3Qrfqn/ExSdXu8WiFDWuQI= --dividend_ratio 20

Response Sample

  • Successful

    T800002276a7d58218ac4978733e5cca927a7d86cb7c87 has been set as the default account.
    Miner account address: T800002276a7d58218ac4978733e5cca927a7d86cb7c87
    Miner public_key: BK40p+6EYFYLZfXoGBIxt5FsXThg1OZ8LLeP6GuWQG6rhzgKb3IvLSUA9PGGeMqxI3Qrfqn/ExSdXu8WiFDWuQI=
    Transaction hash: 0x4d4005243a3088c093d584dc2eda7beb93d0bb0695b06c5dbf1ed64d9bd20a25
    Please use command 'topio querytx' to query transaction status later on!!!
    Miner registering..., 1
    Miner registering..., 2
    Miner registering..., 3
    Successfully registering to the mining pool.
    
  • Failed

    Register as "Validator" miner, but do not pledge enough deposit.

    Transaction hash: 0x4c15361b82a5717962327d88ab017f0e64e849c4f7db1ae45e3fa75229ee3fa2
    Please use command 'topio querytx' to query transaction status later on!!!
    

Execute topio querytx to query the transaction by transaction hash, the consensus final status is a "failure", then the registration is failed

# Set Miner Key

Miner uses the private key of the miner key to sign the block when working.

If you have one and only one owner key without a password in your wallet, and you set this owner key to miner key when registering a miner, you can skip this step.

The following scenarios require you to set the miner key:

  • When there are multiple keys in the wallet, one of the keys needs to be set as the miner key to sign the block.

  • When there is only one key (owner key or miner key) with a password in the wallet.

WARNING

Please use the same miner key as the miner registration, otherwise the process of starting the node will fail.

Request

topio mining setMinerKey

Request Parameters

Parameter Name Required Default Value Type Description
public_key Yes - String The public key of the miner key when the miner registered. When the miner is successfully registered, the public key field "Miner public_key" of the miner key will be returned.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.
-p, -password - String The keystore file password of the miner key.

Response Parameters

None.

Request Sample

topio mining setMinerKey BBYTqmkmNksMjX/ydgnixYP1fVmd0zHQGqW1xCBo4zXNrWf3H/XXqe+NsUkvrSuZ4wtDbJqdE7NDU752gMFd5+g=

Response Sample

  • Successful

    Set miner key successfully.
    
  • Failed

    The key does not exist in wallet.
    

# Get Miner Information

Get miner's registration information.

Request

topio mining getMinerInfo

Request Parameters

Parameter Name Required Default Value Type Description
account_addr No The default miner account you set. String Miner account address. If not specified, query the default miner account you set.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Parameter Type Description
account_addr String Node account address.
auditor_credit String Auditor credit.
auditor_stake Number Auditor stake: auditor stake=(node deposit+vote amount/2)*auditor credit
dividend_ratio Number Dividend ratio, percentage %, value [0,100].
network_id String A value of 0 indicates that the node joins the mainchain network.
node_deposit Number Node deposit(uTOP).
miner_type String Node type: edge, validator, advance, exchange.
In which, edge, validator, and advance are genesis nodes.
nodename String Node name.
rec_stake String Beacon stake.
registered_node_type String Registered node type: edge, validator, advance.
node_sign_key String Public key used in registering node.
validator_credit String Validator credit.
validator_stake Number Validator stake: validator stake=(node deposit+vote amount/2)*validator credit
vote_amount Number Total number of votes received from voting.
zec_stake String Sub-beacon stake.
genesis String Whether it is a genesis node.

Request Sample

topio mining getMinerInfo T800002276a7d58218ac4978733e5cca927a7d86cb7c87

Response Sample

  • Successful

     {
        "data": {
           "account_addr": "T00000Lhacc8ecibdjYozdZtwEdinSpL5zwAn3K5",
           "auditor_credit": "0.000000",
           "auditor_stake": 0,
           "dividend_ratio": 0,
           "genesis": "false",
           "miner_type": "validator",
           "network_id": "0 ",
           "node_deposit": 3000000000000,
           "node_sign_key": "BOBtgYod1934eW5G60dppbT+m5hi/1pP5tf+lXineOaiig2l0/gYuIQtf18SosgiPnCg5skgwS2xd6dsUq+tEf0=",
           "nodename": "bitpool",
           "rec_stake": 0,
           "registered_node_type": "validator",
           "validator_credit": "1.000000",
           "validator_stake": 1732,
           "vote_amount": 0,
           "zec_stake": 0
        },
        "errmsg": "OK",
        "errno": 0,
        "sequence_id": "49"
     }
    
  • Failed

    The miner is not registered.

    No data!
    

# Query Miner Reward

Miner reward includes workload reward and votes reward.

The system issues miner rewards every 24 hours.

Request

topio mining queryMinerReward

Request Parameters

Parameter Name Required Default Value Type Description
account_addr No - String Miner account address.
If not specified, all miners' reward information will be queried by default.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
accumulated Uint64 The integer part of the total miner reward, in uTOP.
accumulated_decimals Uint32 The decimal part of the total miner reward, in uTOP.
issue_time Uint64 The clock height when each miner's reward is issued
last_claim_time Uint64 Clock height of the last time to claim miner reward.
unclaimed Uint64 The integer part of the unclaimed reward, in uTOP.
unclaimed_decimals Uint64 The decimal part of the unclaimed reward, in uTOP.

Request Sample

topio mining queryMinerReward T8000085a8e8acd53c72dca85dcb002a6710796975b4ba

Response Sample

  • Successful

    {
       "data" : {
             "accumulated" : 188072630515731,
             "accumulated_decimals" : 209604,
             "issue_time" : 3533760,
             "last_claim_time" : 0,
             "unclaimed" : 188072630515731,
             "unclaimed_decimals" : 209604
       },
       "errmsg" : "ok",
       "errno" : 0,
       "sequence_id" : "49"
    }
    
  • Failed

    No data!
    

# Claim Miner Reward

You can use topio mining queryMinerReward to query the miner reward before you claim the miner reward.

Miner reward can be received at most once every 24 hours.

Request

topio mining claimMinerReward

Request Parameters

None.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Request Sample

topio mining claimMinerReward

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status.

Response Sample

  • Successful

    Transaction hash: 0x8e65078e0c78fc44528d641f6c2a91c9611012fc9cc74693247f3de42cd54a33
    Please use command 'topio querytx' to query transaction status later on!!!
    
  • Failed

    Execute topio querytx to query the transaction by transaction hash, the consensus final status is a "failure", then failed to claim miner reward.

# Update Miner Information

Supports simultaneous update of miner type, miner nickname, miner's deposit, dividend ratio and miner key information in the registration contract.

Request

topio mining updateMinerInfo

Request Parameters

Parameter Name Required Default Value Type Description
miner_type Yes - String Updated miner type: edge, validator, advance.
miner_name Yes - String Updated miner name.
increase_or_decrease Yes - Uint64 1--Increase miner deposit. 2--Decrease miner deposit.
top_num Yes - Double Miner deposit, in TOP.
dividend_ratio Yes - Uint64 Updated dividend ratio. Value∈[0,100]
miner_key Yes - String The updated miner key. Here, please pass in the public key of the miner key.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status.

Request Sample

An "edge" type miner is updated to a "validator" type miner, with an increase of 300,000 TOP deposit, a dividend ratio set to 0, and the miner key is updated at the same time.

topio mining updateMinerInfo validator ee55 1 300000 60 BJL6rIirL1m7ox+hKHymSISULh8HPYI8772Wq7h0oUga8exzuRrTR599inROGNkGK5O8buwFhe+E2WKyYD3l8tE=

Response Sample

  • Successful

    Transaction hash: 0x34ca8f317107ce6b01c933b017f28e6cf0f84f2e31627a8349f167c1aa9ade10
    Please use command 'topio querytx' to query transaction status later on!!!
    
  • Failed

    When the reduced miner's deposit is lower than the minimum deposit required for the updated miner type, the update of the miner information fails.

    Transaction hash: 0xc73f6295bc5b6be1ace273d59504f4c97d1b01cd2d3301c47cf042e28795e35b
    Please use command 'topio querytx' to query transaction status later on!!!
    

# Set Dividend Ratio

If you register as an advance miner, you can set the dividend ratio. All rewards you receive (including but not limited to workload rewards and votes rewards) will be distributed to the voter that support you in accordance with the dividend ratio.

Request

topio mining setDividendRatio 

Request Parameters

Parameter Name Required Default Value Type Description
percent Yes - Uint64 Dividend ratio, value∈[0,100].

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.
-t, --tx_deposit 100,000 Double Transaction deposit, in TOP. The default is 0.1 TOP token.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status.

Request Sample

topio mining setDividendRatio 60

Response Sample

  • Successful

    Transaction hash: 0x3586caae6a3871b48209beda70c7617b0cd51dcc07f1116cd63d537b377c278c
    Please use command 'topio querytx' to query transaction status later on!!!
    

    Execute topio querytx to query the transaction by transaction hash, the consensus final status is a "success", then succeed to set dividend ratio.

  • Failed

    Execute topio querytx to query the transaction by transaction hash, the consensus final status is a "failure", then failed to set dividend ratio.

# Set Miner Name

Request

topio mining setMinerName

Request Parameters

Parameter Name Required Default Value Type Description
miner_name Yes - String New miner name.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status

Request Sample

topio mining setMinerName dd44

Response Sample

  • Successful

    Transaction hash: 0x631c785ce9462ff6c7951f1a5e941af6d6910d54b29ccdc8f4fc388dc513b770
    Please use command 'topio querytx' to query transaction status later on!!!
    

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "success", execute topio mining getMinerInfo , the miner name is updated successfully.

  • Failed

    Transaction hash: 0x3a4ac388896178c50ab777fb7947ac3028abe5298535800ecd918236f2c36c17
    Please use command 'topio querytx' to query transaction status later on!!!
    

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "failure", then failed to set miner name.

# Add Miner Deposit

You can increase the miner's deposit at any time, thereby increasing the comprehensive stake of your node.

Increasing the miner deposit will not change the type of miner you have registered.

Request

topio mining addDeposit

Request Parameters

Parameter Name Required Default Value Type Description
top_num Yes - Double Increased miner deposit, in TOP.

Options

Option Name Default Value Type Description
-h,--help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status

Request Sample

Increase of 400,000 TOP deposit.

topio mining addDeposit 400000

Response Sample

  • Successful

    Transaction hash: 0xf8a59907230c19f78dc194d1d724c3ab3306702a85d860219e7300304b294546
    Please use command 'topio querytx' to query transaction status later on!!!
    

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "success", execute topio mining getMinerInfo , succeed to add the miner deposit.

  • Failed

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "failure", failed to add miner deposit.

# Reduce Miner Deposit

You can reduce the miner deposit at any time. The reduction of the deposit will not change the type of miner you registered. However, if the pledged deposit is lower than the minimum requirement for the registration deposit of the current type of miner, the reduction of the deposit will fail.

Request

topio mining reduceDeposit 

Request Parameters

Parameter Name Required Default Value Type Description
top_num Yes - Double Reduced miner’s deposit, in TOP.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status

Request Sample

Reduce 600,000 TOP miner deposit.

topio mining reduceDeposit 600000

Response Sample

  • Successful

    Transaction hash: 0xce9275be9176c53dadb445149e702a8c408f7007f3cb22e263483e6f30f2997d
    Please use command 'topio querytx' to query transaction status later on!!!
    

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "success", execute topio mining getMinerInfo , succeed to reduce the miner deposit.

  • Failed

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "failure", failed to reduce miner deposit.

# Change Miner Type

Support changing the miner type:

  • If the current registration deposit is higher than or equal to the minimum deposit requirement for the new type of miner, it is recommended that you use this command to change the miner type.

  • If the current registration deposit is lower than the minimum deposit requirement for the new type of miner, you need to increase the miner's deposit. In order to save Beacon transaction fees, it is recommended that you use topio mining updateMinerInfo to update the deposit and miner type at the same time.

Request

topio mining changeMinerType

Request Parameters

Parameter Name Required Default Value Type Description
miner_type Yes - String Changed miner type: edge, validator, advance.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status.

Request Sample

Change from "advance" type miners to "edge" type miners.

topio mining changeMinerType edge

Response Sample

  • Successful

    Transaction hash: 0xcf612c66a8b33f0976e316f5002b49ca3cdbb7e854107b15c81c7ed04836a982
    Please use command 'topio querytx' to query transaction status later on!!!
    

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "success", execute topio mining getMinerInfo , succeed to change the miner type.

  • Failed

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "failure", failed to change miner type.

# Terminate

After executing the terminate command, the miner will stop mining.

The miner’s registration deposit and the later increased deposit will not be returned to the miner’s account immediately, and will be locked for 72 hours.

After the locked deposit expires, the miner's account needs to actively redeem the deposit, and the system will not automatically return it.

Request

topio mining terminate

Request Parameters

None.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status.

Request Sample

topio mining terminate

Response Sample

  • Successful

    Transaction hash: 0x8159071ec087303cf673ed67e19d448826af0797c3030c9e77c6d081f5e09a87
    Please use command 'topio querytx' to query transaction status later on!!!
    

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "success", succeed to terminate.

  • Failed

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "failure", failed to terminate.

# Withdraw Miner Deposit

The miner’s registration deposit and the later increased deposit will not be returned to the miner’s account immediately, and will be locked for 72 hours.

After the locked deposit expires, the miner's account needs to actively redeem the deposit, and the system will not automatically return it.

Request

topio mining withdrawDeposit

Request Parameters

None.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameter Name Type Description
Transaction hash String The transaction hash that can be used to query the transaction consensus status.

Request Sample

topio mining withdrawDeposit

Response Sample

  • Successful

    Transaction hash: 0xcf612c66a8b33f0976e316f5002b49ca3cdbb7e854107b15c81c7ed04836a982
    Please use command 'topio querytx' to query transaction status later on!!!
    

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "success", execute topio chain queryAccount to query account balance has changed, then succeed to withdraw deposit.

  • Failed

    Execute topio querytx to query the transaction by transaction hash, when the consensus final status is a "failure", failed to withdraw deposit.