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: 上述走多签流程
  6. ./bin/xchain-cli multisig sign --tx=./tx.out --output=./key1.sign
  7. ./bin/xchain-cli multisig sign --tx=./tx.out  --keys ${被提名人keys地址}  --output=./key2.sign
  8. ./bin/xchain-cli multisig send --tx ./tx.out ./key1.sign,./key2.sign ./key1.sign,./key2.sign -H:${PORT}
  9. // 成功后会生成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}
  3. // default: 会生成一个tx.out在当前目录下，操作内容和nominate一样
  4. // default: 注意需要在建立/data/acl/addrs，标明提名人和被提名人信息
  5. // default: 上述走多签流程
  6. ./bin/xchain-cli multisig sign --tx=./tx.out --output=./key1.sign
  7. ./bin/xchain-cli multisig sign --tx=./tx.out  --keys ${acl keys地址}  --output=./key2.sign
  8. ./bin/xchain-cli multisig send --tx ./tx.out ./key1.sign,./key2.sign ./key1.sign,./key2.sign -H:${PORT}
  9. // 成功后会生成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: 上述走多签流程
  7. ./bin/xchain-cli multisig sign --tx=./tx.out --output=./key1.sign
  8. ./bin/xchain-cli multisig sign --tx=./tx.out  --keys ${被提名人keys地址}  --output=./key2.sign
  9. ./bin/xchain-cli multisig send --tx ./tx.out ./key1.sign,./key2.sign ./key1.sign,./key2.sign -H:${PORT}
  10. // 成功后会生成txid

vote_file示例如下：

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

2. 撤销投票

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

重要

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

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

revoke_vote_file示例文件如下:

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