4.2.1. TDPoS类使用

4.2.1.1. 共识状态查看

4.2.1.1.1. 共识状态查询

1. 通用共识状态查询

  1. ./bin/xchain-cli consensus status

2. TDPoS存储字段查询

  1. // 若装载Chained-BFT组件,--type后需填写xpos
  2. ./bin/xchain-cli consensus invoke --type tdpos --method getTdposInfos --fee ${1000_IF_NEED}

重要

后续提及的合约变更操作之后,并不会立即生效,必须在下一个term生效。同时,从下一个term的第一个区块被生产开始,到下一个term的最后一个区块生产结束,这期间的候选人集合不变。

4.2.1.2. 创世块配置介绍

Tdpos类共识的创世块示例在上述 /data/genesis/tdpos.json 中,下面简要介绍:

  1. "genesis_consensus":{
  2. "name": "tdpos", // 共识名称,TDPoS和XPoS的统称
  3. "config": {
  4. "timestamp": "1559021720000000000", // 开始时间,可忽略
  5. "proposer_num": "2", // 【重要】候选人集合总人数,配置后只能通过【共识升级修改】
  6. "period": "3000", // 【重要】每个块生产固定时间,单位为毫秒,示例所示为3s一个块
  7. "alternate_interval": "3000", // 同一轮矿工切换间隙时间
  8. "term_interval": "6000", // term切换间隙时间
  9. "block_num": "20", // 【重要】每个候选人在一轮轮数中需要出块的数目
  10. "vote_unit_price": "1", // 计票单位
  11. "init_proposer": {
  12. "1": ["TeyyPLpp9L7QAcxHangtcHTu7HUZ6iydY", "SmJG3rH2ZzYQ9ojxhbRCPwFiE9y6pD1Co"] // 【重要】数组中记录了全部初始候选人节点的address
  13. },
  14. // , "bft_config":{} // 可选项,即加载chained-bft组件,加载后共识实际上为XPoS。
  15. }
  16. }

4.2.1.3. TDPoS投票流程整体介绍

TDPoS整体“提名候选人-投票候选人”流程详细介绍请见 TDPoS流程

1. 整体流程

TDPoS类命令行操作,仅限变更候选人集合地址信息,主要需要以下流程:

  • 某节点发起 候选人提名nominate ,发起需要是一个ACL账户,该ACL账户需包含被提名人的地址,走多签流程完成候选人池的修改。完成之后,指定节点加入候选人池。

  • 节点对候选人池进行 投票vote ,对候选人池中显示的节点地址投票。

  • 计票 ,在每轮term开始时,会检查候选人投票池的 TopK名候选人(即创世块 proposer_num 字段)并指定为该轮候选人集合。

重要

若投票的目标候选人池数量小于创世块 proposer_num 字段,投票并不会生效。

2. 治理Token生成

TDPoS的先决条件是 必须先生成相关代币 ,通过下述命令生成。治理Token的生成在任意节点皆可触发,但只会按照创世块的配置分配。具体可见 治理Token

重要

下述提案投票时必须确保ACL或者节点账户拥有Token,即先向账户发起transfer,否则会报失败错误。

4.2.1.3.1. 候选人流程

1. 提名候选人流程

  • ACL账户准备

提名候选人需要通过合约ACL实现(若A提名B,则需要建立A、B的ACL账户,并保证两者均签名才能通过提案)。合约ACL多签流程如下:

  1. ./bin/xchain-cli account new --desc account.des --fee 1000
  2. ./bin/xchain-cli transfer --to XC1111111111111111@xuper --amount 1000000000

具体account.des示例如下:

  1. // account.des
  2. {
  3. "module_name": "xkernel",
  4. "method_name": "NewAccount",
  5. "contract_name": "$acl",
  6. "args" : {
  7. "account_name": "1111111111111111",
  8. "acl": "{\"pm\": {\"rule\": 1,\"acceptValue\": 0.6},\"aksWeight\": {\"TeyyPLpp9L7QAcxHangtcHTu7HUZ6iydY\": 0.5, \"SmJG3rH2ZzYQ9ojxhbRCPwFiE9y6pD1Co\": 0.5}}"}
  9. }

重要

注意应有文件data/acl/addrs。

  1. // addr
  2. XC1111111111111111@xuper/TeyyPLpp9L7QAcxHangtcHTu7HUZ6iydY
  3. XC1111111111111111@xuper/SmJG3rH2ZzYQ9ojxhbRCPwFiE9y6pD1Co
  • 提名候选人

提名候选人的命令行如下:

  1. ./bin/xchain-cli consensus invoke --type tdpos --method nominateCandidate --isMulti --account ${ACL_ACCOUNT} --fee ${1000_IF_NEED} --desc ${NOMINATE_FILE} -H:${PORT}
  2. // default: 后续会生成一个tx.out在当前目录下
  3. // default: 注意需要在建立/data/acl/addrs,标明提名人和被提名人信息
  4. // default: 上述走多签流程
  5. ./bin/xchain-cli multisig sign --tx=./tx.out --output=./key1.sign
  6. ./bin/xchain-cli multisig sign --tx=./tx.out --keys ${被提名人keys地址} --output=./key2.sign
  7. ./bin/xchain-cli multisig send --tx ./tx.out ./key1.sign,./key2.sign ./key1.sign,./key2.sign -H:${PORT}
  8. // 成功后会生成txid

nominate_file文件示例如下:

  1. // nominate_file
  2. {
  3. "candidate": "SmJG3rH2ZzYQ9ojxhbRCPwFiE9y6pD1Co",
  4. "amount": "100"
  5. }

2. 撤销候选人流程

撤销候选人流程将候选人池中指定候选人删除,抵押Token将会归还给投票的原所属人:

  1. ./bin/xchain-cli consensus invoke --type tdpos --method revokeNominate --account ${ACCOUNT_IF_NEED} --isMulti --fee ${1000_IF_NEED} --desc ${REVOKE_NOMINATE_FILE} -H:${PORT}
  2. // default: 会生成一个tx.out在当前目录下,操作内容和nominate一样
  3. // default: 注意需要在建立/data/acl/addrs,标明提名人和被提名人信息
  4. // default: 上述走多签流程
  5. ./bin/xchain-cli multisig sign --tx=./tx.out --output=./key1.sign
  6. ./bin/xchain-cli multisig sign --tx=./tx.out --keys ${acl keys地址} --output=./key2.sign
  7. ./bin/xchain-cli multisig send --tx ./tx.out ./key1.sign,./key2.sign ./key1.sign,./key2.sign -H:${PORT}
  8. // 成功后会生成txid

revoke_nominate_file文件示例如下。

  1. // revoke_nominate_file
  2. {
  3. "candidate": "iYjtLcW6SVCiousAb5DFKWtWroahhEj4u"
  4. }

4.2.1.3.2. 投票流程

1. 向候选人池进行投票

  1. ./bin/xchain-cli consensus invoke --type tdpos --method voteCandidate --isMulti --account ${ACL_ACCOUNT} --fee ${1000_IF_NEED} --desc ${NOMINATE_FILE} -H:${PORT}
  2. // default: 后续会生成一个tx.out在当前目录下
  3. // default: 注意需要在建立/data/acl/addrs,标明提名人和被提名人信息
  4. // default: 上述走多签流程
  5. ./bin/xchain-cli multisig sign --tx=./tx.out --output=./key1.sign
  6. ./bin/xchain-cli multisig sign --tx=./tx.out --keys ${被提名人keys地址} --output=./key2.sign
  7. ./bin/xchain-cli multisig send --tx ./tx.out ./key1.sign,./key2.sign ./key1.sign,./key2.sign -H:${PORT}
  8. // 成功后会生成txid

vote_file示例如下:

  1. // vote_file
  2. {
  3. "candidate": "iYjtLcW6SVCiousAb5DFKWtWroahhEj4u",
  4. "amount": "10"
  5. }

2. 撤销投票

投票人可将自己的票数撤销,撤销后原先被抵押的Token将会归还给投票人,同时将会影响下一term候选人。

重要

若在投票时使用了ACL多签账户进行了投票,在撤销时也需要进行多签撤销,撤销流程和上述 撤销候选人流程 一致,下面也会进行介绍。

  1. // 走默认流程还是走多签流程,取决于vote时是否使用acl账户
  2. // 默认流程,使用当前节点地址进行投票,在当前节点上进行撤销。
  3. ./bin/xchain-cli consensus invoke --type tdpos --method revokeVote --fee ${1000_IF_NEED} --desc ${REVOKE_VOTE_FILE} -H:${PORT}
  4. // default: 成功后会生成txid
  1. // 多签流程
  2. ./bin/xchain-cli consensus invoke --type tdpos --method revokeVote --fee ${1000_IF_NEED} --desc ${REVOKE_VOTE_FILE} -H:${PORT} --account ${ACCOUNT_IF_NEED} --isMulti
  3. // 后续会生成一个tx.out在当前目录下,操作内容和nominate时多签的过程一样。
  4. // 注意需要在建立/data/acl/addrs,标明提名人和被提名人信息。
  5. ./bin/xchain-cli multisig sign --tx=./tx.out --output=./key1.sign
  6. ./bin/xchain-cli multisig sign --tx=./tx.out --keys ${acl keys地址} --output=./key2.sign
  7. ./bin/xchain-cli multisig send --tx ./tx.out ./key1.sign,./key2.sign ./key1.sign,./key2.sign -H:${PORT}
  8. // 成功后会生成txid

revoke_vote_file示例文件如下:

  1. // revoke_vote_file
  2. {
  3. "candidate": "iYjtLcW6SVCiousAb5DFKWtWroahhEj4u",
  4. "amount": "1"
  5. }