# 与链互动

本章将向您介绍如何使用 chain 命令与链互动,包括查询链上信息,包括查询链上账户信息、区块信息、主链信息、部署/调用用户智能合约等。

chain命令如下表所示。

命令 说明
topio chain queryAccount 查询链上账户信息。
topio chain queryBlock 查询区块信息。
topio chain chainInfo 查询主链信息。
topio chain syncStatus 查看链上数据同步状态。
topio chain autoPruneData 打开/关闭自动清理无效数据功能。

# 查询链上账户信息

请求方式

topio chain queryAccount

请求参数

参数名称 是否必选 默认值 类型 说明
account_addr 默认账户 String 指定查询账户地址,如不指定,则查询默认账户。

选项

选项名称 默认值 类型 说明
-h, --help - - 查看命令帮助信息。

返回参数

参数名称 类型 说明
account_addr String 账户地址。
available_gas Uint64 账户现有可用 gas 的量,单位 Tgas。如返回值为负,可能因为两种原因:
  • 获取了免费 gas 后账户余额不足100*10^6 uTOP。
  • 在用完锁定 TOP token 兑换的 gas 后解锁 TOP token。
balance Uint64 账户余额,单位 uTOP。
burned_token Uint64 该账户所有已经销毁的TOP token,单位 uTOP。
cluster_id Uint8 cluster ID。
created_time Uint64 账户在链上创建的时钟高度。
disk_staked_token Uint64 兑换 disk 锁定的 TOP token,单位 uTOP。
gas_staked_token Uint64 兑换 gas 锁定的 TOP token,单位 uTOP。
group_id Uint8 group ID。
latest_tx_hash String 最新共识成功的交易 hash。
latest_tx_hash_xxhash64 String 最新共识成功的交易 xx64hash。
latest_unit_height Uint64 最新共识成功的交易的 unit block 高度。
lock_balance Uint64 锁定的 TOP token,单位 uTOP,主要用于用户合约交易。
调用用户合约的时候,交易发送方可同时给合约账户转账,如果合约执行失败,转账款需要退还给发送方,所以在合约执行成功前,先将转账款锁定。
nonce Uint64 该账户最新共识成功的交易序号,唯一。
recv_tx_num Uint64 账户作为接收方的交易数量。
table_id Unit16 Table 的 ID。
total_free_gas Uint64 账户免费获取的 gas 总量,单位 Tgas。目前当账户余额 ≥100*10^6 uTOP,系统会免费赠与该账户 25,000 Tgas。该值随着链上参数治理变化而变化。
total_gas Uint64 账户 gas 总量,单位 Tgas。
一个普通账户 24 小时内可以获得的 gas 不超过 200,000 Tgas。
一个合约账户 24 小时内可以获得的 gas 不超过 10,000,000 Tgas。
total_stake_gas Uint64 账户锁定 TOP token 而获得的 gas 总量,单位 Tgas。
unlock_disk_staked Uint64 解锁中的兑换 disk 的 TOP token,发起解锁后,需要等待 24 小时,并由锁定账户发起一笔交易后,解锁的金额才会到账。
unlock_gas_staked Uint64 解锁中的兑换 gas 的 TOP token,发起解锁后,需要等待 24 小时,并由锁定账户发起一笔交易后,解锁的金额才会到账。
unused_free_gas Uint64 免费 gas 余量,单位 Tgas。
unused_stake_gas Uint64 锁定 TOP token 兑换的 gas 余量,单位 Tgas。
unused_vote_amount Uint64 该账户未使用选票数量。
vote_staked_index - 兑票明细,包含以下三个参数:
  • duration:锁定时长,单位为天,参数类型为 Uint16。
  • lock_time:兑票时间,参数类型为 Uint64。
  • lock_token:锁定的 token 数量。
  • vote_num:兑票数量,参数类型为 Uint64。
vote_staked_token Uint64 兑换选票锁定的 TOP token,单位 uTOP。
zone_id Uint8 zone ID。

账户所属分片网络信息:

ID 分片网络
zone_id、cluster_id、group_id,分别为 1、0、0 或者 2、0、0 Beacon Network
zone_id、cluster_id、group_id,分别为 14、1、1 Archive Network
zone_id、cluster_id、group_id,分别为 15、1、1 Edge Network
zone_id、cluster_id,分别为 0、1,group_id 的值为 [1,63] Audit Network
zone_id、cluster_id,分别为 0、1,group_id 的值为 [64,126] Validate Network

请求样例

topio chain queryAccount T800002276a7d58218ac4978733e5cca927a7d86cb7c87

返回样例

  • 成功返回

    {
       "data" : {
          "account_addr" : "T8000037d4fbc08bf4513a68a287ed218b0adbd497ef30",
          "available_gas" : 24189,
          "balance" : 99999075443787,
          "burned_token" : 0,
          "cluster_id" : 1,
          "created_time" : 1639104150,
          "disk_staked_token" : 0,
          "gas_staked_token" : 0,
          "group_id" : 65,
          "latest_tx_hash" : "0x658aae45cf8d580a76b0d967f891349d919533a78e817be91ab1985085f65894",
          "latest_tx_hash_xxhash64" : "0x269a19dbec5077b0",
          "latest_unit_height" : 4,
          "lock_balance" : 0,
          "nonce" : 3,
          "recv_tx_num" : 0,
          "table_id" : 39,
          "total_free_gas" : 25000,
          "total_gas" : 25000,
          "total_stake_gas" : 0,
          "unlock_disk_staked" : 0,
          "unlock_gas_staked" : 0,
          "unused_free_gas" : 24189,
          "unused_stake_gas" : 0,
          "unused_vote_amount" : 0,
          "vote_staked_index" : [
             {
                "duration" : 90,
                "lock_time" : 6591504,
                "lock_token" : 924556213,
                "vote_num" : 1000
             }
          ],
          "vote_staked_token" : 924556213,
          "zone_id" : 0
       },
       "errmsg" : "OK",
       "errno" : 0,
       "sequence_id" : "1"
    }
    
  • 失败返回

    链上没有此账户信息,返回:

    Errmsg: account not found on chain
    

# 查询区块信息

根据账户地址查询区块信息。

查询区块信息的前提是账户已发送交易且交易共识成功。

请求方式

topio chain queryBlock

请求参数

参数名称 是否必选 默认值 类型 说明
height - String/Integer 最新区块高度"latest"(String)或者具体区块高度(Integer)。
account_addr - String 查询 unit block 请使用普通账户地址,如"T800002276a7d58218ac4978733e5cca927a7d86cb7c87"。
查询 table block 请使用table block账户地址,如"Ta0000gRD2qVpp2S7UpjAsznRiRhbE1qNnhMbEDp@0"。
如不指定,查询默认账户的区块信息。

选项

选项名称 默认值 类型 说明
-h, --help - - 查看命令帮助信息。

返回参数

  • unit block

    参数名称 类型 说明
    body Object
    fullunit Object 为了节约数据存储空间,每 21 个 lightunit 会打包成 1 个 fullunit。
    account_balance Number 账户余额,单位 uTOP。
    account_create_time Number 账户在链上创建时的时钟高度。
    burned_amount_change Number 该账户所有已经销毁的 TOP token,单位 uTOP。
    latest_full_unit_hash String 最新 fullunit 交易 hash。
    latest_full_unit_number Number 最新 fullunit 块高度。
    latest_recv_trans_number Number 接收交易笔数。
    latest_send_trans_hash String 最新发送交易的 hash。
    latest_send_trans_number Number 发送交易笔数。
    txs Object 本区块打包的交易信息,结构为 map 数组,map 的 key 为交易 hash。
    tx_consensus_phase String 交易的发送方或接收方:
    • 1:self
    • 2:send
    • 3:recv
    enum_transaction_subtype_self = 1, // self operate
    enum_transaction_subtype_send = 2, // send to other account
    enum_transaction_subtype_recv = 3, // receive from other account
    enum_transaction_subtype_recv_ack = 4(confirm), // receive ack from other account
    tx_hash String 交易 hash 值。
    lightunit Object 轻单元块数据。
    txs Object 本区块打包的交易信息,结构为 map 数组,map 的 key 为交易 hash。
    tx_consensus_phase String 交易的发送方或接收方:
    • 1:self
    • 2:send
    • 3:recv
    enum_transaction_subtype_self = 1, // self operate
    enum_transaction_subtype_send = 2, // send to other account
    enum_transaction_subtype_recv = 3, // receive from other account
    enum_transaction_subtype_recv_ack = 4(confirm), // receive ack from other account
    tx_hash String 交易 hash 值。
    hash String 本块 hash 的十六进制字符串。
    header Object
    auditor_xip String 本块的 auditor leader 节点。(xip 格式)
    timerblock_height Number 时钟块高度。
    validator String 本块的 validator leader 矿工账户地址。
    validator 和 auditor 节点轮流担任共识 leader 节点,当返回的字段中有账户地址信息时,例如以下返回示例中,validator 字段的值为"T8000085a8e8acd53c72dca85dcb002a6710796975b4ba",证明产生此块为 validator 节点,且矿工账户地址为"T8000085a8e8acd53c72dca85dcb002a6710796975b4ba"。
    validator_xip String 本块的 validator leader 节点。(xip 格式)
    version Number 协议版本号。
    height Number 块高度。
    owner String unit block 所属账户地址。
    prev_hash String 前一区块 hash 的十六进制。
    table_height Number 表高度。
    timestamp Number 出块时间戳。
    status String 块状态。

账户原生属性说明

属性代码字段 名称 类型 说明
XPROPERTY_CONTRACT_CODE "@1" String 合约执行的具体代码。
XPROPERTY_LOCK_TOKEN_KEY "@4" Map 账号下交易锁定的 TOP token 集合。
XPROPERTY_LOCK_TOKEN_SUM_KEY "@5" String 锁定的 TOP token 总数。
XPORPERTY_SUB_ACCOUNT_KEY "@13" Llist 子账号的列表。
XPORPERTY_CONTRACT_SUB_ACCOUNT_KEY "@14" List 合约子账号列表。
XPORPERTY_CONTRACT_PARENT_ACCOUNT_KEY "@15" String 合约父账号。
XPROPERTY_USED_TGAS_KEY "@30" String gas 衰减值。
XPROPERTY_LAST_TX_HOUR_KEY "@32" String 最近一次更新 @30 的逻辑时钟。
XPROPERTY_USED_DISK_KEY "@34" String 使用的 disk,本期暂时无用。
XPROPERTY_CONTRACT_TGAS_LIMIT_KEY "@37" String 合约的 tgas_limit,合约为调用自己支付的 gas 上限。
XPROPERTY_PLEDGE_VOTE_KEY "@45" List 用于兑换选票、解锁兑换选票锁定金,存储账户所有兑票交易。
XPROPERTY_EXPIRE_VOTE_TOKEN_KEY "@46" String 兑换选票中,所有锁定期到期的 TOP token 值。
  • table block

    参数名称 类型 说明
    tableblock Object table block 下包含多个 units,当链上长时间没有新交易,查询 tableblock 最新高度数据为"null"。
    txs Object 本区块打包的交易信息,结构为 map 数组,map 的 key 为交易 hash。
    tx_consensus_phase String 交易的发送方或接收方:
    • 1:self
    • 2:send
    • 3:recv
    enum_transaction_subtype_self = 1, // self operate
    enum_transaction_subtype_send = 2, // send to other account
    enum_transaction_subtype_recv = 3, // receive from other account
    enum_transaction_subtype_recv_ack = 4(confirm), // receive ack from other account
    tx_hash String 交易 hash 值。
    units Object tableblock 存储若干 unit 块相关信息。
    account Object 账号地址。
    unit_height Integer unit 块高度。
    hash String 块 hash 的十六进制字符串。
    header Object
    auditor_xip String 本块的 auditor leader 节点(xip)。
    timerblock_height Number 时钟块高度。
    validator String 本块的 validator leader 矿工账户地址。
    validator 和 auditor 节点轮流担任共识 leader 节点,当返回的字段中有账户地址信息时,例如以下返回示例中,validator 字段的值为"T8000085a8e8acd53c72dca85dcb002a6710796975b4ba",证明产生此块为 validator 节点,且矿工账户地址为"T8000085a8e8acd53c72dca85dcb002a6710796975b4ba"。
    validator_xip String 本块的 validator leader 节点(xip)。
    version Number 协议版本号
    height Number 块高度。
    owner String table block 所属账户地址。
    prev_hash String 前一区块 hash 的十六进制。
    table_height Number 表高度。
    timestamp Number 出块时间戳。
    status String 块状态。

请求样例

  • unit block

    topio chain queryBlock latest T8000085a8e8acd53c72dca85dcb002a6710796975b4ba 
    
  • table block

    topio chain queryBlock 9 Ta0000gRD2qVpp2S7UpjAsznRiRhbE1qNnhMbEDp@146
    

返回样例

  • 成功返回

    • unit block

      • lightunit

        {
           "result" : "ok",
           "value" : {
              "body" : {
                 "lightunit" : {
                    "txs" : [
                       {
                          "tx_consensus_phase" : "send",
                          "tx_hash" : "0x36ec1efb79385bc67629a924caf8db41b25dd080f265866c325be43179d76fe1"
                       }
                    ]
                 }
              },
              "hash" : "1f73f5e7d4b8744d9d051a215bb3aeabc08bde93946550988fd744aecfc10d4e",
              "header" : {
                 "auditor" : "T00000LNi53Ub726HcPXZfC4z6zLgTo5ks6GzTUp",
                 "auditor_xip" : "100000000000016:f60000ff00040401",
                 "timerblock_height" : 7301997,
                 "validator_xip" : "100000000000016:f60000ff000503ff",
                 "version" : 196608
              },
              "height" : 2,
              "owner" : "T8000062d241d05334a8bc02dea1e97a5381cbe4885729",
              "prev_hash" : "3a0aa3d2e728b93ce38dac45778579ab08724d3168ac4fb9c381172f91a21d4e",
              "table_height" : 4,
              "timestamp" : 1646209170
           }
        }
        
      • fullunit

        {
            "data": {
                "value": {
                    "body": {
                        "fullunit": {
                            "account_balance": 1875000762900000,
                            "account_create_time": 1609412970,
                            "burned_amount_change": 0,
                            "latest_full_unit_hash": "82a730ec0df3b86260af57c3dad0c511dd30bf4aea813cb0f4e077991b629b61",
                            "latest_full_unit_number": 42,
                            "latest_recv_trans_number": 1,
                            "latest_send_trans_hash": "401e87b7ba6c5b82311c24a886ab3ea9dc98cb4f2e04779424a6f239be95aecf",
                            "latest_send_trans_number": 8,
                            "txs": [{
                                "tx_consensus_phase": "send",
                                "tx_hash": "0x401e87b7ba6c5b82311c24a886ab3ea9dc98cb4f2e04779424a6f239be95aecf"
                            }]
                        }
                    },
                    "hash": "82a730ec0df3b86260af57c3dad0c511dd30bf4aea813cb0f4e077991b629b61",
                    "header": {
                        "auditor": "T00000LR3QHZf1DD1Usn1oEP4THaYhdBJGgxZ1ga",
                        "auditor_xip": "1000000000005652:f60000000004081",
                        "timerblock_height": 7197540,
                        "validator_xip": "2000000000005652:f600000000050ff",
                        "version": 196608
                    },
                    "height": 9,
                    "owner": "T00000LbgaCLnuxnqaqPh8e9EpeNqsRju6MuCr4z",
                    "prev_hash": "c962a4d464dd9a14e0ff337b07bdda3ff1ff79bcf34394e90ffbcd0de02e2bd8",
                    "table_height": 150872,
                    "timestamp": 1645164600
                }
            },
            "errmsg": "OK",
            "errno": 0,
            "sequence_id": "9"
        }
        
    • table block

      {
          "data": {
              "value": {
                  "body": {
                      "tableblock": {
                          "txs": [{
                              "tx_consensus_phase": "send",
                              "tx_hash": "0x2ed974afd473b8188f0601e1956376897d90fc3175c7b5d3a905032275c84860"
                          }],
                          "units": [{
                              "account": "T00000LhEBn4hwcVgiZJWMtZCV3Xz4Qxko2huSSM",
                              "unit_height": 32039
                          }]
                      }
                  },
                  "hash": "c0eac42fe93d39ff6d7339192f4520d3f4b99d6f833b1f7b6143350d97df7955",
                  "header": {
                      "auditor_xip": "1000000000005c3b:f6000000000407f",
                      "multisign_auditor": "740000005f0000000694de06000000002100038b37abb47aed5d1827e01ceae22b4c7292476f17fce4d57a84b1f4c5417170322000fb10f842a1479949715ad57c20606c1ce1ea6fdf0e6219fde622052e8b78111e4000eb65dbeffefffefb",
                      "multisign_validator": "74000000670000000694de060000000021000316f597e2edf094d63d922db06a32895d72beaf54fde3230fd31476e00d6f548020004e257d99224f8462abc7ca8e36d0e28e25a8779573da58e119306a5e36df8bb7800076e6dc7bef4c3eff20f836f9beb6fffd",
                      "timerblock_height": 7760752,
                      "validator": "T00000LTe5A139dZWCtprNUpeVteR23v8rtEDK5K",
                      "validator_xip": "2000000000005c3b:f60000000005007",
                      "version": 196608
                  },
                  "height": 931803,
                  "owner": "Ta0000@1",
                  "prev_hash": "22adcb9e156724c0e79023f02acd64050660d3e3a6cffa8a685eb46be78f7590",
                  "table_height": 931803,
                  "timestamp": 1650796720
              }
          },
          "errmsg": "OK",
          "errno": 0,
          "sequence_id": "1"
      }
      
  • 失败返回

    未查询到区块信息:

    No data!
    

# 查询主链信息

请求方式

topio chain chainInfo

请求参数

无。

选项

选项名称 默认值 类型 说明
-h,--help - - 查看命令帮助信息。

返回参数

参数名称 类型 说明
first_timerblock_hash String 第一个时钟块hash。
first_timerblock_stamp Uint64 第一个时钟块生成时间。
init_total_locked_token Uint64 系统初始化总TOP token锁定金额,系统初始化gas兑换率=系统总gas/总锁定金额,避免系统初始化gas兑换率为0。
token_price Uint64 锁定TOP token兑换gas的兑换率,单位tgas/top。
total_gas_shard Uint32 单片24小时总gas量。
validator_group_count Uint32 validator group 数量,当前默认为4。
network_activate_time Uint32 激活时间。

请求样例

topio chain chainInfo

返回样例

  • 成功返回

    {
       "data" : {
          "first_timerblock_hash" : "0b98350d3e8ec4511ec1720bff0c6d6205519ffa90a879a65eed23e9312b21de",
          "first_timerblock_stamp" : 1573189200,
          "init_total_locked_token" : 10000000000000,
          "network_activate_time":3620325,
          "token_price" : 432000,
          "total_gas_shard" : 2160000000000,
          "validator_group_count" : 2
       },
       "errmsg" : "OK",
       "errno" : 0,
       "sequence_id" : "10"
    }
    
  • 失败返回

    无。

# 查看链上数据同步状态

节点成功入网后,TOPIO 会自动同步链上数据到节点本地数据库,可通过命令行查看节点数据同步状态。

请求方式

topio chain syncStatus

返回信息

  • full-sync-mode:全量同步模式,会同步网络中的全部数据。适用于边缘节点、审计节点、验证节点、交易所和存档节点。若进度为 100%,表明链上数据已同步完成。若未完成同步,请稍后再次执行查询数据同步状态命令。
  • fast-sync-mode:快速同步模式,会同步当前网络中,链上最近数个 full table 的数据,以快速完成同步,并参与共识计算。适用于验证节点和审计节点。若进度为 100%,表明链上数据已同步完成。若未完成同步,请稍后再次执行查询数据同步状态命令。
  • checkpoint-sync-mode:检查点同步模式,会同步网络中的可信硬编码 checkpoint 时间点以后的所有数据。适用于审计节点。若进度为 100%,表明链上数据已同步完成。若未完成同步,请稍后再次执行查询数据同步状态命令。
  • root-beacon chains:根信标链,负责存储链上的所有数据。
  • sub-beacon chains:子信标链,分别存储各自链上产生的数据。
  • shard chains:分片链,负责处理链上的交易信息并存储交易数据。
  • index:网络中的 table ID。
  • cur_height:当前节点已同步的 table 链的高度。
  • max_height:当前节点的邻居节点上该 table 链的最高高度。
full-sync-mode, total:100.00%
			index	cur_height	max_height
root-beacon chains								100.00%
			0		356			356			100.00%

sub-beacon chains								100.00%
			0		2265		2265		100.00%
			1		313			313			100.00%
			2		1139		1139		100.00%

fast-sync-mode, total:100.00%
			index	cur_height	max_height
shard chains									100.00%
			0		0			0			100.00%
			1		4395		4395		100.00%
			2		2965		2965		100.00%
			3		0			0			100.00%
			4		6737		6737		100.00%
			5		6			6			100.00%
			6		2803		2803		100.00%
			7		2766		2766		100.00%
			8		3			3			100.00%
			9		3			3			100.00%
			10		3			3			100.00%
			11		5656		5656		100.00%
			12		0			0			100.00%
			13		2800		2800		100.00%
			14		0			0			100.00%
			15		4461		4461		100.00%
			16		0			0			100.00%
			17		4381		4381		100.00%
			18		19			19			100.00%
			19		3000		3000		100.00%
			20		16			16			100.00%
			21		0			0			100.00%
			22		3			3			100.00%
			23		4878		4878		100.00%
			24		2689		2689		100.00%
			25		2744		2744		100.00%
			26		6			6			100.00%
			27		2833		2833		100.00%
			28		0			0			100.00%
			29		2649		2649		100.00%
			30		2926		2926		100.00%
			31		4786		4786		100.00%
			32		2816		2816		100.00%
			33		2894		2894		100.00%
			34		8			8			100.00%
			35		19			19			100.00%
			36		4897		4897		100.00%
			37		2868		2868		100.00%
			38		5017		5017		100.00%
			39		0			0			100.00%
			40		2536		2536		100.00%
			41		3			3			100.00%
			42		2679		2679		100.00%
			43		78			78			100.00%
			44		6058		6058		100.00%
			45		2860		2860		100.00%
			46		0			0			100.00%
			47		4512		4512		100.00%
			48		3			3			100.00%
			49		0			0			100.00%
			50		4357		4357		100.00%
			51		4070		4070		100.00%
			52		4646		4646		100.00%
			53		5083		5083		100.00%
			54		6			6			100.00%
			55		7445		7445		100.00%
			56		4965		4965		100.00%
			57		2917		2917		100.00%
			58		2663		2663		100.00%
			59		3			3			100.00%
			60		4770		4770		100.00%
			61		35			35			100.00%
			62		2536		2536		100.00%
			63		3			3			100.00%

# 打开/关闭自动清理无效数据功能

打开该功能后,系统可自动清理历史无效数据,减少 DB 空间占用。

支持 Advance、Edge、Validator 类型的矿工。

请求方式

topio chain autoPruneData

请求参数

参数名称 是否必选 示例 说明
action on 或 off 打开或关闭自动清理无效数据功能。

请求样例

  • 打开自动清理

    topio chain autoPruneData on
    
  • 关闭自动清理

    topio chain autoPruneData off
    

返回样例

  • 打开自动清理

    Set auto prune data On successfully.
    
  • 关闭自动清理

    Set auto prune data Off successfully.