# 系统智能合约 API
# 概述
TOP AI Network系统合约提供的功能包括节点注册、节点投票、节点入网、节点选举、链上治理等。
系统合约函数如下表所示。
| 方法名 | 说明 |
|---|---|
| nodeJoinNetwork | 节点入网，调用入网合约。 |
| submitProposal | 提交提案。 |
| withdrawProposal | 撤销提案。 |
| tccVote | TCC委员表决提案。 |
| registerNode | 矿工注册。 |
| unregisterNode | 注销矿工。 |
| setDividendRatio | 设置矿工分红比例。 |
| setNodeName | 设置矿工昵称。 |
| redeemNodeDeposit | 赎回矿工注册保证金。 |
| updateNodeInfo | 支持同时更新矿工类型、矿工名称、矿工保证金和分红比例。 |
| updateNodeType | 更新矿工类型。 |
| stakeDeposit | 增加矿工保证金。 |
| unstakeDeposit | 减少矿工保证金。 |
| voteNode | 给矿工投票。 |
| unvoteNode | 取消矿工投票。 |
| claimNodeReward | 领取矿工奖励。 |
| claimVoterDividend | 领取投票者分红。 |
# 节点入网
方法名
nodeJoinNetwork
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| node_account_addr | 是 | - | String | 矿工账户地址。 |
返回参数
无。
# 提交提案
方法名
submitProposal
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| proposal_type | 是 | - | Uint8 | 提案类型：1--修改链上治理参数提案；2--社区基金管理提案。 |
| target | 是 | - | String | 当提案类型为修改链上治理参数提案时，target为链上治理参数名称，链上治理参数请参见链上治理参数； 当提案类型为社区基金管理提案时，target为接受转账账户地址，销毁账户地址为：T!0001Ebj8hBvoLdvcEEUwNZ423zM3Kh9d4nL1Ug。 |
| value | 是 | - | String | 当target为链上治理参数时，value为修改后的值。 当target为接受转账账户地址，value为转账金额，单位uTOP。 |
| proposal_deposit | 是 | - | Uint64 | 提案保证金，单位uTOP。 |
| effective_timer_height | 是 | - | Uint64 | 提案通过后生效时钟高度。如生效始终高度小于提案通过时的始终高度，那么提案在通过后会立刻生效。 |
返回参数
无。
# 撤销提案
方法名
withdrawProposal
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| proposal_id | 是 | - | String | 提案ID。 |
返回参数
无。
# TCC委员表决提案
方法名
tccVote
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| proposal_id | 是 | - | String | 提案ID。 |
| opinion | 是 | - | Bool | true: 赞成， false: 反对。 |
返回参数
无。
# 矿工注册
方法名
registerNode
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| node_type | 是 | - | String | 矿工类型，包括edge（边缘矿工）、validator（验证矿工）、advance（高级矿工）、archive（存档矿工）和 exchange（交易所矿工），其中高级矿工兼具validator（验证）、auditor（审计）节点。 您可以注册成为前三种矿工类型的其中一种。 注册成为高级矿工后，advance矿工被选举为何种节点取决于矿工的选票： advance矿工被选举为auditor节点，矿工所获得的选票需要大于等于矿工实际质押的保证金（此处节点保证金以TOP计算，非uTOP）。 当选票低于实际质押保证金时，advance矿工只能被选为validator。 说明： 矿工选票须由接受投票而得，可以由其他矿工投票，也可由本账户投票。 |
| nodename | 是 | - | String | 矿工昵称，4-16字符，字母、数字或下划线。 |
| node_sign_key | 是 | - | String | 系统默认使用账户Key作为矿工的工作时使用的key。 为了更好地保护您的账户资产，建议您创建一对无资产的公私钥对，节点工作时使用其私钥对区块进行签名。 此处请传入对应的公钥，其他节点可使用该公钥进行验签。 |
| dividend_ratio | 是 | - | Uint32 | 高级矿工可以为给自己投票的账户设置分红比例，高级矿工收到的所有奖励（工作奖励、选票奖励），会按照设置的分红比例分到支持自己的投票者账户上。 |
返回参数
无。
# 注销矿工
方法名
unregisterNode
请求参数
无。
返回参数
无。
# 设置矿工分红比例
方法名
setDividendRatio
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| dividend_ratio | 是 | 无 | Integer | 分红比例，取值范围 [0,100]。 |
返回参数
无。
# 设置矿工昵称
方法名
setNodeName
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| nodename | 是 | 无 | String | 矿工昵称。 |
返回参数
无。
# 赎回矿工注册保证金
方法名
redeemNodeDeposit
请求参数
无。
返回参数
无。
# 更新矿工信息
方法名
updateNodeInfo
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| node_name | 是 | 无 | String | 更新后的矿工名称。 |
| updated_deposit_type | 是 | 无 | Int | 1：增加矿工保证金；2：减少矿工保证金。 |
| node_deposit | 是 | 无 | Uint64 | 增加或减少的矿工保证金。 |
| dividend_ratio | 是 | 无 | Uint32 | 更新后的分红比例。 |
| node_type | 是 | 无 | String | 更新后的矿工类型：edge（边缘矿工）、validator（验证矿工）、advance（高级矿工）。 |
返回参数 无。
# 更新矿工类型
方法名
updateNodeType
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| node_type | 是 | 无 | String | 矿工类型。 |
返回参数
无。
# 增加矿工保证金
方法名
stakeDeposit
请求参数
无。
返回参数
无。
# 减少矿工保证金
方法名
unstakeDeposit
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| unstake_deposit | 是 | - | Uint64 | 减少的保证金金额，单位uTOP。 |
返回参数
无。
# 给矿工投票
方法名
voteNode
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| vote_info | 是 | - | Map<std::String, uint64> | 接受投票的矿工账户(String)；投票数量(Uint64)。 |
返回参数
无。
# 取消矿工投票
方法名
unvoteNode
请求参数
| 参数名称 | 是否必选 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|
| vote_info | 是 | 无 | Map<std::String, uint64> | <矿工账户, 票数> map |
返回参数
无。
# 领取矿工奖励
方法名
claimNodeReward
请求参数
无。
返回参数
无。
# 领取投票者分红
方法名
claimVoterDividend
请求参数
无。
返回参数
无。