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 12 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 12 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.