# Interact with Chain

This guide introduces how to interact with the chain, including: Query account, Query block, Get chain information, Deploy contract, etc.

chain commands are shown as below:

Command Description
topio chain queryAccount Query account on chain.
topio chain queryBlock Query block.
topio chain chainInfo Query chain information.
topio chain syncStatus Check data synchronization status.
topio chain autoPruneData Enable or disable automatic cleanup of invalid data.

# Query Account

Request

topio chain queryAccount

Request Parameters

Parameter Name Required Default Value Type Description
account_addr No The default account. String Query specified account. If not specified, query the default account.

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

Parameters Name Parameter Type Description
account_addr String Normal user account address or contract account address.
available_gas Uint64 The available gas of the account address. The unit is Tgas. If the return value is negative, there may be two reasons: 1. The account balance after obtaining free gas is less than 100*10^6 uTOP; 2. Unlock the TOP Token after running out the gas exchanged.
balance Uint64 The balance of the account address. The unit is uTOP.
burned_token Uint64 All burned TOP tokens of the account address. The unit is uTOP.
cluster_id Uint8 cluster ID.
contract_address List If an application contract is deployed by a ordinary account, the application contract account address will be returned.
created_time Uint64 The clock height when the account created on the blockchain.
disk_staked_token Uint64 The amount of locked TOP tokens to exchange disk. The unit is uTOP.
gas_staked_token Uint64 The amount of locked TOP tokens to exchange gas. The unit is uTOP.
group_id Uint8 group ID.
latest_tx_hash String The hash of the latest successful transaction.
latest_tx_hash_xxhash64 String The xx64hash of the latest successful transaction.
latest_unit_height Uint64 The unit block height of the latest successful transaction.
lock_balance Uint64 Locked TOP tokens used for application contract transactions. Unit of measurement is uTOP When running application contract, the transaction sender can transfer TOP tokens to the contract account at the same time. If the contract fails to execute, the transferred TOP tokens needs to be returned to the sender. Therefore, the transferred money should be locked before running the contract successfully.
lock_deposit_balance Uint64 Application contract transaction costs are related to the CPU time and transaction size. The costs of the application contract transactions cannot be determined at the beginning of the transaction. The method is to lock part of the transaction deposit of the transaction sender. At the third round of consensus of the transaction, according to the final execution of the application contract, the transaction deposit of the sender is deducted to pay for the costs. Measured in uTOP.
lock_gas Uint64 Application contract transaction costs are related to the CPU time and transaction size. The costs of the application contract transactions cannot be determined at the beginning of the transaction. The method adopted is to freeze part of the gas of the transaction sender. At the third round of consensus of the transaction, according to the final execution of the application contract, the gas of the sender is deducted to pay for the costs. Measured in Tgas.
nonce Uint64 The nonce of the latest successful transaction. Unique in the global network.
total_free_gas Uint64 Total free gas of the account address. Measured in Tgas. At present, when the account balance ≥100*10^6 uTOP, the system will give the account 25,000 Tgas for free. This value changes along with the on-chain governance parameters changes.
total_gas Uint64 Total gas of the account address. Measured in Tgas.
total_stake_gas Uint64 Total gas obtained by locking TOP Tokens. Measured in Tgas.
unlock_disk_staked Uint64 TOP tokens to exchange disk in unlock. After initiating the unlock, we need to wait 24 hours for the unlocked amount to arrive in the account.
unlock_gas_staked Uint64 TOP tokens to exchange gas in unlock. After initiating the unlock, we need to wait 24 hours for the unlocked amount to arrive in the account.
unused_vote_amount Uint64 Unused vote amount of the account.
vote_staked_token Uint64 TOP tokens to exchange votes in lock.
zone_id Uint8 zone ID.

Shard to which the account belongs:

ID Shard
zone_id, cluster_id, group_id, are 1, 0, 0 Beacon Network
zone_id, cluster_id, group_id, are 2, 0, 0 Beacon Network
zone_id, cluster_id, group_id, are 14, 1, 1 Archive Network
zone_id, cluster_id, group_id, are 15, 1, 1 Edge Network
zone_id, cluster_id, are 0, 1, group_id∈[1,63] Audit Network
zone_id, cluster_id, are 0, 1, group_id∈[64,126] Validate Network

To query application contract account information, return the following two parameters in addition to the above parameters.

Parameter Name Parameter Name Description
contract_code String Application contract code.
contract_parent_account String Contract parent account that deployed the application contract.

Request Sample

topio chain queryAccount T800002276a7d58218ac4978733e5cca927a7d86cb7c87

Response Sample

  • Successful

    {
   "data" : {
      "account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
      "available_gas" : 25000,
      "balance" : 100000000000000,
      "burned_token" : 0,
      "cluster_id" : 1,
      "contract_address" : [T30000MaSkcvg2iyqMRDRMFnTQ8o5237Xs1dT9TR],
      "created_time" : 1596520429,
      "disk_staked_token" : 0,
      "group_id" : 64,
      "gas_staked_token" : 0,
      "latest_tx_hash" : "0xfcd8843c36b1c8fee81bcac7e7cf2b38682deef723e9a237918b70b3a6dfc4c9",
      "latest_tx_hash_xxhash64" : "0xdb73d04d0f5daa84",
      "latest_unit_height" : 1,
      "lock_balance" : 0,
      "lock_deposit_balance" : 0,
      "lock_gas" : 0,
      "nonce" : 1,
      "total_free_gas" : 25000,
      "total_gas" : 25000,
      "total_stake_gas" : 0,
      "unlock_disk_staked" : 0, 
      "unlock_gas_staked" : 0,
      "unused_free_gas" : 25000,
      "unused_stake_gas" : 0,
      "unused_vote_amount" : 0,
      "vote_staked_token" : 0,
      "zone_id" : 0
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "5"
}

  • Failed

    Account information not found on chain.

    Errmsg: account not found on chain

# Query Block

Get block by account address.

The premise of retrieving block information is that the account has sent the transaction and the transaction was consensused successfully.

Request

topio chain queryBlock

Request Parameters

Parameter Name Required Default Value Type Description
height Yes - String/Integer The latest block height(String) or the specific block height(Uint64).
account_addr No - String Use the normal account address to retrieve the unit block，such as"T800002276a7d58218ac4978733e5cca927a7d86cb7c87".
Use the table block account address to retrieve the unit block，such as"Ta0000gRD2qVpp2S7UpjAsznRiRhbE1qNnhMbEDp@0".

Options

Option Name Default Value Type Description
-h, --help - - Check the command's help information.

Response Parameters

  • unit block

    Parameter Name Parameter Name Description
    body Object
    fullunit Object To save data storage space, every 21 lightunits are packaged as a fullunit.
    account_balance Number Account balance, in uTOP.
    account_create_time Number Clock height when the account is created on the chain.
    burned_amount_change Number All TOP tokens that have been destroyed in this account, in uTOP.
    latest_full_unit_hash String Latest fullunit transaction hash.
    latest_full_unit_number Number Height of the latest fullunit block.
    latest_recv_trans_number Number Number of received transactions.
    latest_send_trans_hash String Hash of the latest sent transaction.
    latest_send_trans_number Number Number of sent transactions.
    txs Object The transaction information packaged in this block, in map array format, and the key of the map is a transaction hash.
    tx_consensus_phase String Transaction consensus phase: 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 Transaction hash.
    lightunit Object Data of lightunit.
    txs Object The transaction information packaged in this block, in map array format, and the key of the map is a transaction hash.
    tx_consensus_phase String Transaction consensus phase: 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 Transaction hash.
    hash String The hexadecimal String of this block hash.
    header Object
    auditor_xip String Auditor leader node of this block (xip).
    timerblock_height Number Clock block height.
    validator String The validator leader miner account address that generated this block.
    The validator and auditor nodes take turns as the consensus leader node. When the returned field contains account address information, for example, in the following response example, the value of the validator field is "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba", which proves that the block generated is the validator node and the miner account address is " T8000085a8e8acd53c72dca85dcb002a6710796975b4ba".
    validator_xip String Validator leader node of this block (xip).
    version Number Protocol version.
    height Number Block height.
    owner String The unit block owner.
    prev_hash String The hexadecimal of the hash of the previous block.
    table_height Number Table height.
    timestamp Number Block time stamp.
    status String Block status.

Account Native Property

Property Code Field Property Name Property Type Description
XPROPERTY_CONTRACT_CODE "@1" String The specific code for contract execution.
XPROPERTY_LOCK_TOKEN_KEY "@4" Map Set of locked TOP tokens by transactions under an account.
XPROPERTY_LOCK_TOKEN_SUM_KEY "@5" String Total amount of locked TOP tokens.
XPORPERTY_SUB_ACCOUNT_KEY "@13" List List of sub account.
XPORPERTY_CONTRACT_SUB_ACCOUNT_KEY "@14" List List of contract sub account.
XPORPERTY_CONTRACT_PARENT_ACCOUNT_KEY "@15" String Parent account of contract account.
XPROPERTY_USED_TGAS_KEY "@30" String Value of gas attenuation.
XPROPERTY_LAST_TX_HOUR_KEY "@32" String The logical clock at @30 was last updated.
XPROPERTY_USED_DISK_KEY "@34" String Disk used, which is useless temporarily this period.
XPROPERTY_CONTRACT_TGAS_LIMIT_KEY "@37" String gas_limit: The upper limit of the gas fee that the user is willing to pay for the transaction.
XPROPERTY_PLEDGE_VOTE_KEY "@45" List Used for exchanging votes, unlocking the TOP tokens used for exchanging votes, storing all votes exchanging transactions of account.
XPROPERTY_EXPIRE_VOTE_TOKEN_KEY "@46" String All the TOP tokens that have expired when exchanging votes.

  • table block

    Parameter Name Parameter Type Description
    tableblock Object The tableblock contains multiple units. When there is no new transaction on the chain for a long time, the latest height data of the tableblock is "null".
    txs Object The transaction information packaged in this block, in map array format, and the key of the map is a transaction hash.
    tx_consensus_phase String Transaction consensus phase: 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 Transaction hash.
    units Object Tableblock stores information of unit blocks.
    lightunit_state Object Please refer to the unit block parameter description.
    unit_height Integer Unit block height.
    hash String The hexadecimal String of this block hash.
    header Object
    auditor_xip String Auditor leader node of this block (xip).
    timerblock_height Number Clock block height.
    validator String The validator leader miner account address that generated this block.
    The validator and auditor nodes take turns as the consensus leader node. When the returned field contains account address information, for example, in the following response example, the value of the validator field is "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba", which proves that the block generated is the validator node and the miner account address is " T8000085a8e8acd53c72dca85dcb002a6710796975b4ba".
    validator_xip String Validator leader node of this block (xip).
    version Number Protocol version.
    height Number Block height.
    owner String The table block owner.
    prev_hash String The hexadecimal of the hash of the previous block.
    table_height Number Table height.
    timestamp Number Block time stamp.
    status String Block status.

Request Sample

  • unit block

    topio chain queryBlock latest T8000085a8e8acd53c72dca85dcb002a6710796975b4ba

  • table block

    topio chain queryBlock 9 Ta0000gRD2qVpp2S7UpjAsznRiRhbE1qNnhMbEDp@146

Response Sample

  • Successful

    • 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"
}

  • Failed

    No block information was found:

    No data!

# Query Chain Information

Request

topio chain chainInfo

Request Parameters

None.

Options

Option Name Default Value Type Description
-h,--help - - Check the command's information.

Response Parameters

Parameter Name Parameter Type Description
first_timerblock_hash String Hash of the first clock block.
first_timerblock_stamp Uint64 Generation time of the first clock block.
init_total_locked_token Uint64 Total TOP Token initially locked by the system. The system initializes the exchange rate of gas = total gas/ total locked amount of the system to avoid the system initialized exchange rate of gas to be 0.
token_price Uint64 Exchange rate of locking TOP Token for gas, measured in tgas/top, which changes dynamically with the change of locked TOP token in the system.
total_gas_shard Uint32 Total gas per shard for 24 hours.
validator_group_count Uint32 Number of validator group.
network_activate_time Uint32 Network activate time.

Request Sample

topio chain chainInfo

Response Sample

  • Successful

    {
   "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"
}

  • Failed

    None.

# Check Data Synchronization Status

After the node is successfully connected to the network, TOPIO automatically synchronize the data from the chain to local database. You can run a command to view the data synchronization status of the node.

Request

topio chain syncStatus

Returned Messages

  • full-sync-mode: Full synchronization mode, which will synchronize all data in the network, applicable to edge nodes, exchange nodes, archive nodes, validator nodes and audit nodes. If the progress is 100%, it indicates that the data on the chain has been synchronized. If the synchronization is not completed, please execute the command again later.
  • fast-sync-mode: Fast synchronization mode, which will synchronize the data in previous several full tables in the current network to complete fast synchronization, applicable to validator nodes and audit nodes. If the progress is 100%, it indicates that the data on the chain has been synchronized. If the synchronization is not completed, please execute the command again later.
  • checkpoint-sync-mode: Checkpoint synchronization mode, which will synchronize all data after the trusted hard-coded checkpoint time in the network, applicable to audit nodes. If the progress is 100%, it indicates that the data on the chain has been synchronized. If the synchronization is not completed, please execute the command again later.
  • root-beacon chains: Root beacon chain, which stores all data on the chain.
  • sub-beacon chains: Sub-beacon chains, which store data generated on their respective chains.
  • shard chains: Shard chains are responsible for processing transaction information on the chain and storing transaction data.
  • index: The table ID in the network.
  • cur_height: The height of the synchronized table chain of the current node.
  • max_height: The highest height of the table chain on the neighbour nodes of the current node.
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%

# Enable or Disable Automatic Cleanup of Invalid Data

After enabling this function, the system can automatically clean up invalid historical data to reduce DB space occupation.

Support Advance, Edge, and Validator miners.

Request

topio chain autoPruneData

Request Parameters

Parameter Name Required Example Description
account_addr Yes on or off Enable or disable automatic cleanup of invalid data.

Request Sample

  • Turn on auto cleanup

    topio chain autoPruneData on

  • Turn off auto cleanup

    topio chain autoPruneData off

Response Sample

  • Turn on auto cleanup

    Set auto prune data On successfully.

  • Turn off auto cleanup

    Set auto prune data Off successfully.

← Manage Account Resource →

Last Updated: 7/1/2022, 3:53:07 AM