# 矿工
本章将为您介绍矿工更多信息，包括如何更安全的成为矿工、矿工开始挖矿后如何查看、领取矿工奖以及矿工如何停止挖矿，退出TOP Network网络等。
mining 命令如下表所示。
| 命令 | 说明 |
|---|---|
| topio mining registerMiner | 注册矿工。 |
| topio mining setMinerKey | 设置 miner key，矿工工作时使用其私钥签名。 |
| topio mining getMinerInfo | 查询矿工信息。 |
| topio mining queryMinerReward | 查询矿工奖励。 |
| topio mining claimMinerReward | 领取矿工奖励。 |
| topio mining updateMinerInfo | 更新矿工信息，包括矿工类型、矿工昵称、分红比例等。 |
| topio mining setDividendRatio | 高级矿工设置分红比例。 |
| topio mining setMinerName | 设置矿工昵称。 |
| topio mining addDeposit | 增加矿工保证金。 |
| topio mining reduceDeposit | 减少矿工保证金。 |
| topio mining changeMinerType | 改变矿工类型。 |
| topio mining terminate | 注销矿工，节点退出网络。 |
| topio mining withdrawDeposit | 矿工注销后，赎回矿工保证金。 |
# 注册矿工
TOP Network 目前有五种类型的矿工：边缘矿工（edge）、验证矿工（validator）、高级矿工（advance）、存档矿工（archive）和交易所矿工（exchange）。您可以注册成为前三种矿工类型的其中一种。
高级矿工可在不同的网络里同时担任两种不同类型的节点：验证节点（validator）和审计节点（auditor）。
各类型矿工注册最低保证金如下表所示。
| 矿工类型 | 最低注册保证金 |
|---|---|
| 边缘矿工（edge） | 200,000 TOP |
| 验证矿工（validator） | 500,000 TOP |
| 高级矿工（advance） | 1,000,000 TOP |
注意
矿工注册成功后（包括第一次注册和注销后重新注册），需要启动节点，才会加入TOP Network物理网络，进入候选池等待选举。启动节点请参见节点中相关内容。
请求方式
topio mining registerMiner
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| top_num | 是 | - | Uint64 | 矿工注册保证金，单位 TOP。 |
| miner_type | 是 | - | String | 矿工类型，包括 edge（边缘矿工）、validator（验证矿工）、advance（高级矿工）、archive（存档矿工）和 exchange（交易所矿工）。 您可以注册成为前三种矿工类型的其中一种。 注册成为高级矿工后，高级矿工被选举为何种节点取决于高级矿工的选票： 高级矿工被选举为 auditor 节点，矿工所获得的选票需要大于等于矿工实际质押的保证金。 当选票低于实际质押保证金时，高级矿工只能被选为 validator 节点。 说明： 矿工选票须由接受投票而得，可以由其他矿工投票，也可由本矿工自己投给自己。 提醒： 高级矿工注册后，如使用 topio mining addDeposit 提高保证金，则矿工想被选举为 auditor 节点，需要增加与提高的保证金相同数目的票数。 |
| miner_name | 是 | - | String | 矿工昵称，4-16 字符，支持字母、数字或下划线。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| --dividend_ratio | 0 | Uint64 | 高级矿工可以为给自己投票的账户设置分红比例，高级矿工收到的所有奖励（工作奖励、选票奖励），会按照设置的分红比例分到支持自己的投票者账户上。分红比例 ∈[0,100]。 |
| --miner_key | 默认账户的公钥。 | String | worker key 或者 owner key 的公钥。将此公钥信息登记到区块链系统中，其他节点可使用此公钥对该矿工的签名区块验签。 注册矿工时，如果您没有添加此选项，TOPIO 默认使用账户 owner key 注册矿工。 |
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Miner account address | String | 矿工账户地址。 |
| Miner public_key | String | 注册矿工时使用的 miner key 的公钥。 |
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
请求样例
topio mining registerMiner 1000000 advance qiqi --miner_key BK40p+6EYFYLZfXoGBIxt5FsXThg1OZ8LLeP6GuWQG6rhzgKb3IvLSUA9PGGeMqxI3Qrfqn/ExSdXu8WiFDWuQI= --dividend_ratio 20
返回样例
成功返回
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.失败返回
注册成为"validator"类型矿工，但是没有质押足够的保证金，返回：
Transaction hash: 0x4c15361b82a5717962327d88ab017f0e64e849c4f7db1ae45e3fa75229ee3fa2 Please use command 'topio querytx' to query transaction status later on!!!
根据交易hash，使用 topio querytx 查询交易，交易最终共识失败，则注册矿工失败。
# 设置miner key
设置 miner key，矿工工作时使用其私钥为区块签名。
钱包中有多个 key 时，需要将其中一个 key 设置为矿工 miner key，以用来给区块签名。
注意
请使用与矿工注册相同的 miner key，否则交易发送后，网络中的其他节点将验签失败！
请求方式
topio mining setMinerKey
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| public_key | 是 | - | String | 请使用矿工注册时设置的 miner_key 的公钥。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -f, --pwd_file_path | - | - | 以密码文件的方式设置 miner_key |
| -h, --help | - | - | 查看命令帮助。 |
返回参数
无。
请求样例
topio mining setMinerKey BK40p+6EYFYLZfXoGBIxt5FsXThg1OZ8LLeP6GuWQG6rhzgKb3IvLSUA9PGGeMqxI3Qrfqn/ExSdXu8WiFDWuQI=
运行命令后，根据提示输入keystore的密码。
Please input password.
返回样例
成功返回
Set miner key successfully.失败返回
设置的 key 在钱包中不存在。
The key does not exist in wallet.
# 查询矿工信息
查询矿工注册信息。
请求方式
topio mining getMinerInfo
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| account_addr | 否 | 您设置的默认矿工账户。 | String | 矿工账户地址。如不指定，则查询您设置的默认矿工账户。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| account_addr | String | 矿工账户地址。 |
| auditor_credit | String | auditor 节点信誉分。 |
| auditor_stake | Number | auditor 节点权益：auditor stake =（矿工保证金+矿工得票总数/2）*信誉分 |
| dividend_ratio | Number | 分红率，百分比 %，值为 [0,100]。 |
| network_id | String | 值为 0，证明节点加入的是主链网络。 |
| node_deposit | Number | 矿工保证金，单位 uTOP。 |
| miner_type | String | 矿工类型：
|
| nodename | String | 矿工昵称。 |
| rec_stake | String | 主信标权益。 |
| registered_node_type | String | 矿工注册类型：
|
| node_sign_key | String | 注册矿工时使用的公钥。 |
| validator_credit | String | validator 节点信誉分。 |
| validator_stake | Number | validator 节点权益：validator stake=（矿工保证金+矿工得票总数/2）*validator 信誉分 |
| vote_amount | Number | 矿工得票总数。 |
| zec_stake | String | 子信标权益。 |
| genesis | String | 是否为创世节点。 |
请求样例
topio mining getMinerInfo T800002276a7d58218ac4978733e5cca927a7d86cb7c87
返回样例
成功返回
{ "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" }失败返回
矿工未注册。
No data!
# 查询矿工奖励
矿工奖励包括矿工工作奖励及选票奖励。
系统每 24 小时发放一次矿工奖励。
请求方式
topio mining queryMinerReward
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| account_addr | 否 | - | String | 如不指定，默认查询所有矿工奖励。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| accumulated | Uint64 | 奖励总额的整数部分。单位 uTOP。 |
| accumulated_decimals | Uint32 | 奖励总额的小数部分。单位 10^-6 uTOP。 |
| issue_time | Uint64 | 每个矿工奖励发放时的时钟高度。 |
| last_claim_time | Uint64 | 上次领取奖励的时钟高度。 |
| unclaimed | Uint64 | 未领取奖励的整数部分。单位 uTOP。 |
| unclaimed_decimals | Uint64 | 未领取奖励的小数部分。单位 10^-6 uTOP。 |
请求样例
topio mining queryMinerReward T8000085a8e8acd53c72dca85dcb002a6710796975b4ba
返回样例
成功返回
{ "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" }失败返回
No data!
# 领取矿工奖励
领取矿工奖励之前可使用 topio mining queryMinerReward 查询矿工奖励信息。
每 24 小时最多领取一次。
请求方式
topio mining claimMinerReward
请求参数
无。
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
请求样例
topio mining claimMinerReward
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
返回样例
成功返回
Transaction hash: 0x8e65078e0c78fc44528d641f6c2a91c9611012fc9cc74693247f3de42cd54a33 Please use command 'topio querytx' to query transaction status later on!!!失败返回
根据交易hash，使用
topio querytx查询交易，交易最终共识失败，则领取矿工奖励失败。
# 更新矿工信息
支持同时更新矿工类型、矿工昵称、矿工保证金、分红比例和注册合约中的miner key信息。
请求方式
topio mining updateMinerInfo
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| miner_type | 是 | - | String | 更新后的矿工类型：edge（边缘矿工）、validator（验证矿工）、advance（高级矿工）。 |
| miner_name | 是 | - | String | 更新后的矿工名称。 |
| increase_or_decrease | 是 | - | Uint64 | 1：增加节点保证金；2：减少节点保证金。 |
| top_num | 是 | - | Double | 增加或减少的节点保证金，单位 TOP。 |
| dividend_ratio | 是 | - | Uint64 | 更新后的分红比例。取值范围 [0,100]。 |
| miner_key | 是 | - | String | 更新后的 miner key。此处请传入 miner key 的公钥。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易hash，可用于查询交易结果。 |
请求样例
一个"edge"类型的矿工更新为”validator"类型的矿工，增加了300,000TOP的保证金，分红比例设置为60，并同时更新了miner key。
topio mining updateMinerInfo validator ee55 1 300000 60 BJL6rIirL1m7ox+hKHymSISULh8HPYI8772Wq7h0oUga8exzuRrTR599inROGNkGK5O8buwFhe+E2WKyYD3l8tE=
返回样例
成功返回
Transaction hash: 0x34ca8f317107ce6b01c933b017f28e6cf0f84f2e31627a8349f167c1aa9ade10 Please use command 'topio querytx' to query transaction status later on!!!失败返回
当减少后的矿工保证金低于更新后的矿工类型所需最低保证金，则更新矿工信息失败。
Transaction hash: 0xc73f6295bc5b6be1ace273d59504f4c97d1b01cd2d3301c47cf042e28795e35b Please use command 'topio querytx' to query transaction status later on!!!
# 设置分红比例
如果您注册成为高级矿工，可设置分红比例，您收到的全部奖励（包括但不限于工作量奖励和矿工选票奖励），将按照分红比例分到支持您的投票者账户。
请求方式
topio mining setDividendRatio
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| percent | 是 | - | Uint64 | 分红百比例，取值范围 [0,100]。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
| -t, --tx_deposit | 100,000 | Double | 交易保证金，单位：TOP。如不填，默认为 0.1 TOP token。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
请求样例
topio mining setDividendRatio 60
返回样例
成功返回
Transaction hash: 0x3586caae6a3871b48209beda70c7617b0cd51dcc07f1116cd63d537b377c278c Please use command 'topio querytx' to query transaction status later on!!!根据交易 hash，使用
topio querytx查询交易，交易最终共识成功，则设置分红比例成功。失败返回
根据交易 hash，使用
topio querytx查询交易，交易最终共识失败，则设置分红比例失败。
# 设置矿工昵称
支持更新矿工昵称。
请求方式
topio mining setMinerName
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| miner_name | 是 | - | String | 新的矿工昵称。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
请求样例
topio mining setMinerName dd44
返回样例
成功返回
Transaction hash: 0x631c785ce9462ff6c7951f1a5e941af6d6910d54b29ccdc8f4fc388dc513b770 Please use command 'topio querytx' to query transaction status later on!!!根据交易 hash，使用
topio querytx查询交易，交易最终共识成功，topio mining getMinerInfo查询矿工昵称有更新，则成功更新矿工名称。失败返回
Transaction hash: 0x3a4ac388896178c50ab777fb7947ac3028abe5298535800ecd918236f2c36c17 Please use command 'topio querytx' to query transaction status later on!!!根据交易 hash，使用
topio querytx查询交易，交易最终共识失败，使用topio mining getMinerInfo查询矿工名称未更新，则矿工名称更新失败。
# 增加矿工保证金
您可以随时增加矿工保证金，从而提高您节点的综合权益(Comprehensive Stake)。
增加矿工保证金不会改变您注册的矿工类型。
请求方式
topio mining addDeposit
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| top_num | 是 | - | Double | 增加的矿工保证金，单位 TOP。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h,--help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
请求样例
增加 400,000 TOP 保证金。
topio mining addDeposit 400000
返回样例
成功返回
Transaction hash: 0xf8a59907230c19f78dc194d1d724c3ab3306702a85d860219e7300304b294546 Please use command 'topio querytx' to query transaction status later on!!!根据交易 hash，使用
topio querytx查询交易，最终共识成功，使用topio mining getMinerInfo查询矿工保证金(node_deposit)余额有相应变化，成功增加矿工保证金。失败返回
根据交易hash，使用
topio querytx查询交易，最终共识失败，增加矿工保证金失败。
# 减少矿工保证金
您可以随时减少质押的保证金，减少保证金不会改变您注册的矿工类型，但是如果质押的保证金低于当前类型矿工注册保证金最低要求，减少保证金将失败。
请求方式
topio mining reduceDeposit
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| top_num | 是 | - | Double | 减少的矿工保证金，单位 TOP。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
请求样例
减少 600,000 TOP 保证金。
topio mining reduceDeposit 600000
返回样例
成功返回
Transaction hash: 0xce9275be9176c53dadb445149e702a8c408f7007f3cb22e263483e6f30f2997d Please use command 'topio querytx' to query transaction status later on!!!根据交易 hash，使用
topio querytx查询交易，交易最终共识成功，topio mining getMinerInfo查询矿工保证金(node_deposit)余额有相应变化，成功减少矿工保证金。失败返回
根据交易 hash，使用
topio querytx查询交易，交易最终共识失败，减少矿工保证金失败。
# 改变矿工类型
支持改变矿工类型：
如当前注册保证金高于或等于新类型矿工最低保证金要求，建议您使用此命令改变矿工类型。
如当前注册保证金低于新类型矿工最低保证金要求，则需要增加矿工保证金，为了节省 Beacon 交易手续费，建议您使用
topio mining updateMinerInfo同时更新保证金和矿工类型。
请求方式
topio mining changeMinerType
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| miner_type | 是 | - | String | 改变后的矿工类型：edge（边缘矿工）、validator（验证矿工）、advance（高级矿工）。 |
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
请求样例
由"advance"类型的矿工改变为”edge"类型的矿工。
topio mining changeMinerType edge
返回样例
成功返回
Transaction hash: 0xcf612c66a8b33f0976e316f5002b49ca3cdbb7e854107b15c81c7ed04836a982 Please use command 'topio querytx' to query transaction status later on!!!根据交易 hash，使用
topio querytx查询交易，交易最终共识成功，使用topio minging getMinerInfo查询矿工类型成功更新。失败返回
根据交易 hash，使用
topio querytx查询交易，交易最终共识失败，则更新矿工类型失败。
# 注销矿工
执行注销矿工命令后，矿工将停止挖矿。
矿工注册保证金和后期增加的保证金不会立刻退回到矿工账户，会被锁定 72 小时。
锁定的保证金到期后需要矿工账户主动赎回保证金，系统不会自动退回。
请求方式
topio mining terminate
请求参数
无。
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
请求样例
topio mining terminate
返回样例
成功返回
Transaction hash: 0x8159071ec087303cf673ed67e19d448826af0797c3030c9e77c6d081f5e09a87 Please use command 'topio querytx' to query transaction status later on!!!根据交易 hash，使用
topio querytx查询交易，交易最终共识成功，则成功注销矿工。失败返回
返回交易 hash 及交易大小，根据交易 hash，使用
topio querytx查询交易，交易最终共识失败，则注销矿工失败。
# 赎回矿工保证金
矿工注销后保证金不会立刻退回到矿工账户，会被锁定 72 小时。
锁定的保证金到期后需要矿工账户主动赎回保证金，系统不会自动退回。
请求方式
topio mining withdrawDeposit
请求参数
无。
选项
| 选项名称 | 默认值 | 类型 | 说明 |
|---|---|---|---|
| -h, --help | - | - | 查看命令帮助信息。 |
返回参数
| 参数名称 | 类型 | 说明 |
|---|---|---|
| Transaction hash | String | 本次交易 hash，可用于查询交易结果。 |
请求样例
topio mining withdrawDeposit
返回样例
成功返回
Transaction hash: 0xcf612c66a8b33f0976e316f5002b49ca3cdbb7e854107b15c81c7ed04836a982 Please use command 'topio querytx' to query transaction status later on!!!根据交易 hash，使用
topio querytx查询交易，交易最终共识成功，使用topio chain queryAccount查询账户余额有相应变化，则成功赎回矿工保证金。失败返回
根据交易 hash，使用
topio querytx查询交易，交易最终共识失败，赎回矿工保证金失败。