# 与链互动

本章将向您介绍如何使用 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.

← 管理账户资源 →

Last Updated: 2022/7/1 上午3:53:07