Instance Management

dx module

Information query module, query information on blockchain

dx.overview

Return the overview infomation about blockchain.

Endpoint: /api?req=dx.overview

Returns:

VersionName:Sting - version name of blockchain / type of network
DeployName: string - name of the blockchain deployment network
ChainVersion: uint8 - blockchain version
Time: uint64 - current network time
BlockTime: uint64 - The block timestamp of the current chainhead
ShardOrder: uint32 - shard order, (number of shard) = 1+(1<<ShardOrder)
ShardOnDuty: array - [shard_index_start，number_of_shard]
BlackListSize: uint64 - number of block blacklists (blocks corresponding to this hash value are not accepted)
ScalingOut: bool - scale out (sharding extension) being executed
Rebase: bool - the rebase operation being performed
BlockFallBehind: uint32 - The difference between the current node height and the height of the latest block received from the blockchain network
BaseHeight: uint64 - base height of blockchain
HeadHash: string - hash (base32 encoding) of the consensus_header on the latest height
HeadHeight: uint64 - The latest height of the main chain
FinalizedBlock:array - [block hash of the latest finalized block，block height of the latest finalized block]
ArchivedHeight: array - [block hash of the latest archived block，block height of the latest archived block]
AvgGasPrice: string - average gas fee for block transactions
TxnCount: array - [ScheduledTxnCount，ConfirmedTxnCount，IntraRelayTxnCount，InboundRelayTxnCount，OutboundRelayTxnCount，DeferredTxnCount]
IdAllocated: array - [The block id allocated，maximum block id allowed for allocation]，block id is the index of the block in memory
Throughput: float - throughput
BlockInterval: float - block interval(ms)
HashRate: uint64 - hash rate
ForkRate: float - fork rate
FinalityDistance: uint64 - The difference between the height of the last finalized block and the latest height
Difficulty: uint64: pow difficulty
Global: object - global shard info
Shard: array - per shard info

Sample request:

http://{ip}:{rpc_port}/api?req=dx.overview

Sample response:

{
    "rsp": "dx.overview",
    "ret": {
        "VesionName": "Pyrolusite/DevNet",
        "DeployName": "pyrolusite@xxxx",
        "ChainVersion": 64,
        "Time": 1702372771595,
        "BlockTime": 1702372768106,
        "ShardOrder": 2,
        "ShardOnDuty": [0,4],
        "BlackListSize": 0,
        "ScalingOut": false,
        "Rebase": false,
        "BlockFallBehind": 0,
        "BaseHeight": 54,
        "HeadHash": "2wfpbhaxd75pk2k98zzdnmeq0crjr3fr402738sne1kk5wdftf7g",
        "HeadHeight": 82,
        "HeadBlockOutWeight": 10000,
        "FinalizedBlock": ["r54md62h2fr7xts39wrhdbt9nq7n2tytwrc8fk42mh7nbk8cht8g",78],
        "ArchivedHeight": ["r54md62h2fr7xts39wrhdbt9nq7n2tytwrc8fk42mh7nbk8cht8g",78],
        "AvgGasPrice": "10000",
        "TxnCount": [189,18,103,8,8,0],
        "IdAllocated": [29,128],
        "HeadOutWeight": 10000,
        "Throughput": 1.01,
        "BlockInterval": 54157.98,
        "HashRate": 34611,
        "ForkRate": 0.00,
        "FinalityDistance": 4,
        "Difficulty": 7497816,
        "Global": {
            "Throughput": 0.50,
            "TxnCount": [85,4,100,4,0,0],
            "MempoolSize": 0,
            "TotalStateSize": 1475
        },
        "Shards": [
            {
                "Throughput": 0.21,
                "TxnCount": [3,10,3,2,6,0],
                "MempoolSize": 0,
                "TotalStateSize": 684
            },
            {
                "Throughput": 0.00,
                "TxnCount": [1,2,0,1,1,0],
                "MempoolSize": 0,
                "TotalStateSize": 186
            },
            {
                "Throughput": 0.51,
                "TxnCount": [99,2,0,1,1,0],
                "MempoolSize": 0,
                "TotalStateSize": 795
            },
            {
                "Throughput": 0.00,
                "TxnCount": [1,0,0,0,0,0],
                "MempoolSize": 0,
                "TotalStateSize": 6
            }
        ]
    }
}

dx.head_height

Return the latest block height.

Endpoint: /api?req=dx.head_height

Returns:

HeadHeight : uint64 - the latest chain height

Sample request:

http://{ip}:{port}/api?req=dx.head_height

Sample response:

{
    "rsp": "dx.head_height",
    "ret": {
        "HeadHeight": 31
    }
}

dx.mining

Return the node mining status

Endpoint: /api?req=dx.mining

Returns:

Mining : uint64 - mining status of node , true : mining in progress

Sample request:

http://{ip}:{port}/api?req=dx.mining

Sample response:

{
    "rsp": "dx.mining",
    "ret": {
        "Mining": true
    }
}

dx.shard_info

Return the overview infomation of shard by shard index.

Endpoint: /api?req=dx.shard_info

Parameters:

Parameter	Description
shard_index	Required parameter, index of shard, `g` or `65535` means to obtain global shard information

Returns:

ShardIndex : uint16 - index of onduty shard
Height : uint64 - current chain head height
SnapshotHeight : uint64 - height of snapshot the node take latest
BlockInMem : uint64 - number of blocks in memory
ResidentTxn : uint64 - number of transactions in mempool
PendingTxn : uint64 - number of pending transactions
RequestingTxn : uint64 - number of transactions requested from other nodes
StateSize : uint64 - size of state (Byte)
AccumTxnCount : array - [ScheduledTxnCount，ConfirmedTxnCount，IntraRelayTxnCount，InboundRelayTxnCount，OutboundRelayTxnCount，DeferredTxnCount]

ScheduledTxn：Transactions automatically generated by the system, such as mining reward transactions, contract deployment transactions, and package transaction fee reward transactions.
ConfirmedTxn：Transactions confirmed to be executed, including user transactions received and inbound transactions
IntraRelayTxn：Relay transactions sent by global shards that require other shards to be executed, such as those generated by mining rewards (waiting to be executed, not counted to the master block), and relay transactions between shards that need to be executed and counted
InboundRelayTxn：relay transactions received
OutboundRelayTxn： relay transactions sent out
DeferredTxn：transaction will execution in a certain future block, (TBD)

Sample request:

http://{ip}:{port}/api?req=dx.shard_info

#<-----request body------->#
{
    "shard_index":0
}

Sample response:

{
    "rsp": "dx.shard_info",
    "ret": {
        "ShardIndex": 0,
        "Height": 2,
        "SnapshotHeight": 0,
        "BlockInMem": 3,
        "ResidentTxn": 0,
        "PendingTxn": 0,
        "RequestingTxn": 0,
        "StateSize": 97,
        "AccumTxnCount": [3,0,2,0,0,0]
    }
}

dx.shard_index

Get shard index which scope_key belongs to under a certain scope.

Endpoint: /api?req=dx.shard_index

Parameters:

Parameter	Description
scope	Required parameter, indicating the scope of the query. The scope can be `global`/`shard`/`address`/`uint32`/`uint64`/`uint96`/`uint128`/`uint160`/`uint256`/`uint512`
scope_key	It is not required only when the scope is `global`, and corresponds to the query key under the scope.

Returns:

ShardIndex : uint16 - shard index where the scopekey is located

Sample request:

http://{ip}:{port}/api?req=dx.shard_index

#<-----request body------->#
{
    "scope":"address",
    "scope_key":"3yx91qpxw5qwbadrdf1t7k2r2bvp0x3b6cdcv23n32knaw8mv9xw6trv34:ed25519"
}

Sample response:

{
    "rsp": "dx.shard_index",
    "ret": {
        "ShardIndex": 1 //indicate that address 3yx...v34:ed25519 in shard#1
    }
}

dx.mempool

return the transacions in node memory pool.

Endpoint: /api?req=dx.mempool

Parameters:

Parameter	Description
shard_index	Optional parameter, if not filled in, get the transactions of all shards, otherwise get the transaction pool transactions of the corresponding shards.
archived	Optional parameter that identifies whether archived transactions are required.if not filled in, only return transactions not archived.

Returns:

if shard_index is not filled in, the return value will be in the following format:

"g" : mempool information corresponding to global shard
- array - set of {transaction hash , transaction state}
"0" : mempool information corresponding to shard 0
- array - set of {transaction hash , transaction state}
"1" : mempool information corresponding to shard 1
- array - set of {transaction hash , transaction state}

...

if shard_index is filled in, the return value will be in the following format:

array(non-key) : set of {transaction hash , transaction state} corresponding to shard index queried

Sample request:

http://{ip}:{port}/api?req=dx.mempool

#<-----request body------->#
{ 
    "shard_index":1, 
    "archived":1
}

Sample response:

//transcations in shard #1
{
    "rsp": "dx.mempool",
    "ret": [
        {
            "TXID": "q3936ekwwfyt04ykjkmmaveh28kknrpamb5bsbq1ns5x8aq27rt0",
            "State": "TXN_ARCHIVED"
        },
        {
            "TXID": "8phdbm09ngmcm052pg8v6786we1ytrxft9ky6ty6hx8gtyyyw080",
            "State": "TXN_ARCHIVED"
        },
        {
            "TXID": "ej9dqwxmfhdw072ekd09ys0sknx1574btyyprrn7vzppqjb4k5dg",
            "State": "TXN_ARCHIVED"
        }
    ]
}
//transcations in all shards
{
    "rsp": "dx.mempool",
    "ret": {
        "g": [
            {
                "TXID": "r2gz8bf7qj5gc0ykt3yt426bkn1vvtzctbs650tngv8rnra4zm10",
                "State": "TXN_ARCHIVED"
            },
            {
                "TXID": "k8kzcyac172k4wcz8c1bg0dpsc2qz5tm0npe9zjr0cjetsmqp54g",
                "State": "TXN_ARCHIVED"
            },
            {
                "TXID": "gs7td370fnq6n6xk0kqvyp6v78f54qmzy4t3f16ep4dhzj9vdwd0",
                "State": "TXN_ARCHIVED"
            }
        ],
        "0": [
            {
                "TXID": "q3936ekwwfyt04ykjkmmaveh28kknrpamb5bsbq1ns5x8aq27rt0",
                "State": "TXN_ARCHIVED"
            },
            {
                "TXID": "8phdbm09ngmcm052pg8v6786we1ytrxft9ky6ty6hx8gtyyyw080",
                "State": "TXN_ARCHIVED"
            },
            {
                "TXID": "ej9dqwxmfhdw072ekd09ys0sknx1574btyyprrn7vzppqjb4k5dg",
                "State": "TXN_ARCHIVED"
            }
        ],
        "1": [],
        "2": [],
        "3": []
    }
}

Tranasction State:
TXN_READY: ready to be confirmed (forward broadcast allowed since then)
TXN_CONFIRMED : at least one block confirmed the txn
TXN_FINALIZED: confirmed by a block which is finalized
TXN_ABORTED: duplicated ISN that another one is confirmed and finalized (normal txn only)
TXN_EXPIRED: when its expiration time < latest finalized block time (normal txn only)
TXN_ARCHIVED: saved to DB after TXN_FINALIZED

dx.state_history

Return variable's historical status under a certain scope_key based on scope

Endpoint: /api?req=dx.state_history

Parameters:

Parameter Description

scope scope can take the following values:

global: global scope, returns the historical status of variables in all contracts (including built-in contracts) on the global scope, scope_key can be empty

shard: shard scope, returns the historical status of variables in all contracts on the shard scope, scope_key is the shard index

address: address scope, returns the historical status of variables in all contracts on the address scope, scope_key is the address

uint32/uint64/uint96/uint128/uint160/uint256/uint512: user define scope,returns the historical status of variables in all contracts on the user-define-scope, scope_key is the key corresponding to uds

scope_key It is not required only when the scope is global, and corresponds to the query key under the scope.

Parameter	Description
scope	scope can take the following values: `global`: global scope, returns the historical status of variables in all contracts (including built-in contracts) on the global scope, scope_key can be empty `shard`: shard scope, returns the historical status of variables in all contracts on the shard scope, scope_key is the shard index `address`: address scope, returns the historical status of variables in all contracts on the address scope, scope_key is the address `uint32`/`uint64`/`uint96`/`uint128`/`uint160`/`uint256`/`uint512`: user define scope,returns the historical status of variables in all contracts on the user-define-scope, scope_key is the key corresponding to uds
scope_key	It is not required only when the scope is `global`, and corresponds to the query key under the scope.

Returns:

object : \<contract_name> : \<state_array> , return modifications to all relevant states corresponding to scope_key queried

Sample request:

http://{ip}:{port}/api?req=dx.state_history

#<-----request body------->#
{
    "scope":"address",
    "scope_key":"cysxfbb3khcym79s2ewd653t7k0s9yvz94qyqfn16362htn8mwem7q8n6w:ed25519"
}

Sample response:

{
    "rsp": "dx.state_history",
    "ret": {
        "core.coin.address": [
            {
                "Size": 21,
                "Contract": "core.coin.address",
                "State": {
                    "Balance": "100000000000000000:BRX"
                },
                "BuildNum": "1",
                "Object": {
                    "SN": 956,
                    "RC": 2
                },
                "Commit": {
                    "Height": 459,
                    "Proof": 0,
                    "Shard": [
                        0,
                        2
                    ]
                },
                "Block": 87
            }
        ],
        "core.stats_issues.address": [
            {
                "Size": 30,
                "Contract": "core.stats_issues.address",
                "State": {
                    "NextIssueSerialNum": 1,
                    "FirstIssued": 459,
                    "LastIssued": 459,
                    "IntegralGasFee": "0",
                    "IntegralGasFeeDecay": "0"
                },
                "BuildNum": "1",
                "Object": {
                    "SN": 958,
                    "RC": 2
                },
                "Commit": {
                    "Height": 459,
                    "Proof": 1,
                    "Shard": [
                        0,
                        2
                    ]
                },
                "Block": 87
            }
        ]
    }
}

dx.contract_state

Returns the latest status of contract variables

Endpoint: /api?req=dx.contract_state

Parameters:

Parameter	Description
contract_with_scope	Required parameters, supports query by contract name with scope or cid. Name query: dappname.contractname.scope cvid query: ContractVersionId.scope
scope_key	corresponds to the query key under the scope.

Returns:

object : contract_name : state , return the current contract status corresponding to scope_key queried

Sample request:

http://{ip}:{port}/api?req=dx.contract_state

//<dappname>.<contractname>.<scope>
{
    "contract_with_scope":"core.coin.address", // BRX balance
    "scope_key":"cysxfbb3khcym79s2ewd653t7k0s9yvz94qyqfn16362htn8mwem7q8n6w:ed25519"
}

Sample response:

{
    "rsp": "dx.contract_state",
    "ret": {
        "Size": 21,
        "Contract": "core.coin.address",
        "State": {
            "Balance": "100000000000000000:BRX"
        },
        "BuildNum": "1",
        "Commit": {
            "Height": 459,
            "Proof": 0,
            "Shard": [
                0,
                2
            ]
        }
    }
}

dx.consensus_header

Returns imformation of consensus header.

Endpoint: /api?req=dx.consensus_header

Parameters:

Parameter	Description
query_type	Required parameter,query type, supports height query, hash query, and range query: `0`: query consensus header by height `1`: query consensus header by hash `2`: query consensus header by range [start,end)
height	Required when query_type=0, query consensus header based on height
hash	Required when query_type=1, query consensus header based on its hash
start	Required when query_type=2, denote the start height of the query
end	Required when query_type=2,denote the end height of the query. The query range is [start,end). If end is greater than the current height, the query will be returned until the latest height, that is, [start,current height]

Sample request:

http://{ip}:{port}/api?req=dx.consensus_header

//query by height
{
    "query_type":0,
    "height":10
}

//query by hash
{
    "query_type":1,
    "hash":"770153k6jt64qkq55d9z33e3ssnw1szeecr8drgrkb2jctjp6q00"
}

//query by range
{
    "query_type":2,
    "start":1,
    "end":2
}

Sample response:

//query by height or hash
{
    "rsp": "dx.consensus_header",
    "ret": {
        "Size": 382,
        "Version": 64,
        "Prev": "cq0faacqw91gdmg1cw26thamny02v7qcnq5ttv43bndwsdgmy090",
        "Height": 10,
        "ShardOrder": 2,
        "Timestamp": 1694969995174,
        "ScheduledTxnCount": 2,
        "UserInitiatedTxnCount": 0,
        "IntraRelayTxnCount": 0,
        "InboundRelayTxnCount": 0,
        "OutboundRelayTxnCount": 0,
        "DeferredRelayTxnCount": 0,
        "ShardBlockMerkle": "87dbegj1d1zpmb500pkgkm8jh8a9hj12pkq2yyvx1y7evy6gvrm0",
        "ShardChainStateMerkle": "b5s0f2jyy2wbtxdvqmq2w256zv3gky837gxg4ez4fr151x2jj0k0",
        "ShardProcessedTxnMerkle": "ysczm14v379n8tn4v73840btrr075nyxz7gcvapg0jrr5xsz7m50",
        "ShardOutboundRelayMerkle": "vdb12kg0zqac3y2wh4nz6pp9n298kaqcp7nx1abcvsg6mx4bbnrg",
        "GlobalBlockMerkleLeaf": "8dh51bx8h5hynqx3s91jmqdp0bjwqztmp3j5vdzp8xjpn3dfw22g",
        "GlobalChainStateMerkle": "b536jccta1ja3hx1swn877brcn76jt0tcspa6052zjr5tjg4j2cg",
        "GlobalProcessedTxnMerkle": "cw2c5726nj5w97fh69f4n8pqsd9991emprnz05qczdwk7yceq1e0",
        "Consensus": "CONSENSUS_SHA256",
        "Miner": "m02asr7pq8sgaf1vxtaxgv05zn9pv47hq5sxf5djjv6wg480x9gh6zcv5r:ed25519",
        "TotalGasFee": "0",
        "AvgGasPrice": "10000",
        "ScalingNext": false,
        "SnapshotCarried": 0,
        "Uncles": [],
        "PowTarget": [
            659708,
            217
        ],
        "PowDifficulty": 3333328,
        "PowNonce": "4424487c0f6b16173e4a567c0f6b16177e5b567c0f6b1617a8375c7c0f6b1617",
        "Hash": "770153k6jt64qkq55d9z33e3ssnw1szeecr8drgrkb2jctjp6q00",
        "BlockInterval": 18021424.00,
        "Throughput": 1.47,
        "ForkRate": 0.00,
        "Stage": "DUS_ARCHIVED",
        "DispatchedRelayTxnCount": 1,
        "Reward": "0"
    }
}

//query by range
{
    "rsp": "dx.consensus_header",
    "ret": {
        "Start": 1,
        "End": 2,
        "Blocks": [
            {
                "Size": 350,
                "Version": 64,
                "Prev": "0pr71k99c75h73cnejfgxtc0z8tnh25n3g1gp8c6p3s5cgt8t490",
                "Height": 1,
                "ShardOrder": 1,
                "Timestamp": 1689369602000,
                "ScheduledTxnCount": 3,
                "UserInitiatedTxnCount": 0,
                "IntraRelayTxnCount": 0,
                "InboundRelayTxnCount": 0,
                "OutboundRelayTxnCount": 0,
                "DeferredRelayTxnCount": 0,
                "ShardBlockMerkle": "y2wyz5ntq038mryxq8vyvam29x1v192c68c8yywhrt866vhwz6y0",
                "ShardChainStateMerkle": "0p3b86y4ybv5ezdy84hx6nx4xq1xpt1dr5tx9jvm9a4wrmzky690",
                "ShardProcessedTxnMerkle": "p67ycrhb7kt6rayab6xckdwca1vqqzss85b0xv0skcvjtb93k26g",
                "ShardOutboundRelayMerkle": "ypjztgphd8g309wrxxqd62cqkd1g0f9343cz1t7ak0rtj9tszd5g",
                "GlobalBlockMerkleLeaf": "51dz9xmre2qbwsy2yejq63yekf0xtncnaz8jprh920xn7gy1ryy0",
                "GlobalChainStateMerkle": "brhhp4thsdnr8f3z9atqk14jkwkscmyrkz9eakv300say1xqyj40",
                "GlobalProcessedTxnMerkle": "e1wb5gvm0tyyer5ws0evs88japmt6pyp73ram14yvpcb7vy3myv0",
                "Consensus": "CONSENSUS_NOOP",
                "Miner": "m00ad46hnbt27hg05vfdpahp1jp8gyfp3vytst9yxhewfv4ws5x4669dr8:ed25519",
                "TotalGasFee": "0",
                "AvgGasPrice": "10000",
                "ScalingNext": true,
                "SnapshotCarried": 0,
                "Uncles": [],
                "PowTarget": [
                    0,
                    0
                ],
                "PowDifficulty": 0,
                "PowNonce": "",
                "Hash": "tn6nsy43fppzet2gmbvxjctfw44jzmt2y21q0wj21mv75q3cqbt0",
                "BlockInterval": 4000.00,
                "Throughput": 0.75,
                "ForkRate": 0.00,
                "Stage": "DUS_ARCHIVED",
                "DispatchedRelayTxnCount": 1,
                "Reward": "0"
            }
        ]
    }
}

dx.transaction_block

Returns imformation of transaction block.

Endpoint: /api?req=dx.transaction_block

Parameters:

Parameter	Description
query_type	Required parameter,query type, supports height query, hash query, and range query: `0`: query consensus header by height `1`: query consensus header by hash `2`: query consensus header by range [start,end)
shard_index	Required parameter，Indicates which shard to obtain the transaction block on.
height	Required when query_type=0, query consensus header based on height
hash	Required when query_type=1, query consensus header based on its hash
start	Required when query_type=2, denote the start height of the query
end	Required when query_type=2,denote the end height of the query. The query range is [start,end). If end is greater than the current height, the query will be returned until the latest height, that is, [start,current height]

Sample request:

http://{ip}:{port}/api?req=dx.transaction_block

//query by height
{
    "query_type":0,
    "shard_index":g,
    "height":10,
}

//query by hash
{
    "query_type":1,
    "shard_index":g,
    "hash":"yy3y5avjb86fjrr5yny8x72jzx4q5mvrwjdbf0sqz4jca7z4k8c0",
}

//query by range
{
    "query_type":2,
    "shard_index":g,
    "start":9,
    "end":10
}

Sample response:

//query by height or hash
{
    "rsp": "dx.transaction_block",
    "ret": {
        "Size": 235,
        "Version": 64,
        "Scope": "global",
        "Shard": [
            65535,
            2
        ],
        "Prev": "1remm447fvw7szkmc18sf03jdqjfp21gqpcn7050hhkv5wh72zvg",
        "ScheduledTxnCount": 1,
        "UserInitiatedTxnCount": 0,
        "IntraRelayTxnCount": 0,
        "InboundRelayTxnCount": 0,
        "OutboundRelayTxnCount": 0,
        "DeferredRelayTxnCount": 0,
        "DispatchedRelayTxnCount": 1,
        "ExecutionCount": 1,
        "ConsensusHeaderHash": "770153k6jt64qkq55d9z33e3ssnw1szeecr8drgrkb2jctjp6q00",
        "BlockMerkleLeaf": "8dh51bx8h5hynqx3s91jmqdp0bjwqztmp3j5vdzp8xjpn3dfw22g",
        "ConfirmedTxnHash": "0000000000000000000000000000000000000000000000000000",
        "ConfirmedTxnMerkle": "0000000000000000000000000000000000000000000000000000",
        "ProcessedTxnMerkle": "cw2c5726nj5w97fh69f4n8pqsd9991emprnz05qczdwk7yceq1e0",
        "ChainStateMerkle": "b536jccta1ja3hx1swn877brcn76jt0tcspa6052zjr5tjg4j2cg",
        "TotalGasFee": "0",
        "AvgGasPrice": "10000",
        "Hash": "yy3y5avjb86fjrr5yny8x72jzx4q5mvrwjdbf0sqz4jca7z4k8c0",
        "Height": 10,
        "Timestamp": 1694969995174,
        "Miner": "m02asr7pq8sgaf1vxtaxgv05zn9pv47hq5sxf5djjv6wg480x9gh6zcv5r:ed25519",
        "State": "DUS_FINALIZED",
        "Transactions": {
            "Scheduled": [
                "cw2c5726nj5w97fh69f4n8pqsd9991emprnz05qczdwk7yceq1e0"
            ],
            "Confirmed": [],
            "DispatchedRelays": [
                "46rzdw92b2sg3yhw7g2666fqfg0fgkfv861fwat56ht5ebh2nz50"
            ],
            "Deferred": []
        }
    }
}
//query by range
{
    "rsp": "dx.transaction_block",
    "ret": {
        "Start": 9,
        "End": 10,
        "Blocks": [
            {
                "Size": 235,
                "Version": 64,
                "Scope": "global",
                "Shard": [
                    65535,
                    2
                ],
                "Prev": "0f6gwn62k4tz34swdn0qckbjsg0bd64537zeqwfzcdcvq0xkffc0",
                "ScheduledTxnCount": 1,
                "UserInitiatedTxnCount": 0,
                "IntraRelayTxnCount": 0,
                "InboundRelayTxnCount": 0,
                "OutboundRelayTxnCount": 0,
                "DeferredRelayTxnCount": 0,
                "DispatchedRelayTxnCount": 1,
                "ExecutionCount": 1,
                "ConsensusHeaderHash": "cq0faacqw91gdmg1cw26thamny02v7qcnq5ttv43bndwsdgmy090",
                "BlockMerkleLeaf": "0q3sdqf7agk7nexbjcje3vpszxkj79he45yb3m8a83tdy0h27ecg",
                "ConfirmedTxnHash": "0000000000000000000000000000000000000000000000000000",
                "ConfirmedTxnMerkle": "0000000000000000000000000000000000000000000000000000",
                "ProcessedTxnMerkle": "3z6748qw98x4s5cbsjh4hyh35rmgg3gvhbymzry62fw8h91b80fg",
                "ChainStateMerkle": "cmv15kbw7kv6xn89ty4n2qyg0zrb6ck42jsyshypbhsmb791fny0",
                "TotalGasFee": "0",
                "AvgGasPrice": "10000",
                "Hash": "1remm447fvw7szkmc18sf03jdqjfp21gqpcn7050hhkv5wh72zvg",
                "Height": 9,
                "Timestamp": 1694969994925,
                "Miner": "m02asr7pq8sgaf1vxtaxgv05zn9pv47hq5sxf5djjv6wg480x9gh6zcv5r:ed25519",
                "State": "DUS_FINALIZED",
                "Transactions": {
                    "Scheduled": [
                        "3z6748qw98x4s5cbsjh4hyh35rmgg3gvhbymzry62fw8h91b80fg"
                    ],
                    "Confirmed": [],
                    "DispatchedRelays": [
                        "mfp577974023n95zzqabm5dc8efgfymfy9hpt0h0s8bxwvq28xx0"
                    ],
                    "Deferred": []
                }
            }
        ]
    }
}

dx.transaction

Returns transaction details by transaction hash.

Endpoint: /api?req=dx.transaction

Parameters:

Parameter	Description
hash	Required parameters, hash of transaction

Returns:

BuildNum : uint16 - tranasction version , always 1
GasOffered : uint64 - Transaction gas limit
GasPrice : bigint - gas price
Grouped : bool - group flag, relay transaction feature
Function : string - name of the invoked function
Input : object - function call args
Invocation : object - function call returns
Hash : String - transaction hash
Height : uint64 - height of the block where it is located
Shard : array - [ shard index , shard order]
State : string - transaction state

Sample request:

http://{ip}:{port}/api?req=dx.transaction

{
    "hash":"3z6748qw98x4s5cbsjh4hyh35rmgg3gvhbymzry62fw8h91b80fg"
}

Sample response:

{
    "rsp": "dx.transaction",
    "ret": {
        "BuildNum": 1,
        "GasOffered": 0,
        "GasPrice": "10000",
        "Grouped": false,
        "uTxnSize": 25,
        "Mode": "ITM_GLOBAL|TGM_PERIODIC_SYSTEM|TMF_ZERO_ARG",
        "OrigExecIdx": [0,37],
        "Function": "core.coin.global.issue",
        "Input": {},
        "Invocation": {
            "Status": "IVKRET_SUCCESS",
            "Return": [0,0],
            "CoinDelta": "0",
            "GasFee": "0",
            "Relays": [
                "6kp0srkskppep8z4q0zgvve9kjmye1m1ymszgbvn4a2egdk57ma0"
            ]
        },
        "Height": 37,
        "Shard": [65535,2],
        "State": "DUS_ARCHIVED",
        "ConfirmState": "TXN_ARCHIVED",
        "ConfirmedBy": "j8r476gahtgtjhpd7kdfb7yxm87a5garbqv5xpndz6yrr05mxvv0:0",
        "Hash": "mv6dk7rn9cpm51n5cgqkvccstf72qqf310a42j8ga2f8c9x6q310",
        "ExecStage": "XTG_SCHEDULED"
    }
}

dx.dapp

Return dapp_id and dapp_address based on dapp name

Endpoint: /api?req=dx.dapp

Parameters:

Parameter	Description
name	Required parameters, dapp's name, limit: 4<=dappname length<=8, only contains numbers, letters, and "_" symbols

Returns:

DAppID : uint32 - dapp id , unique identification of a dapp
Address : string - dapp address

Sample request:

http://{ip}:{port}/api?req=dx.dapp

{
    "name":"core"
}

Sample response:

{
    "rsp": "dx.dapp",
    "ret": {
        "DAppID": 1,
        "Address": "core:dapp"
    }
}

address types include: user address, dapp address, token address, with different naming conventions
user-address: 36bytes
dapp-address:\<dappname>:dapp , **4≤dapp name length≤8, Contains only numbers, letters, and the "" symbol**
token-address: \<token_symbol>:token , 3<=token symbol length<=8, Contains only uppercase letters and the "- #" symbol

dx.contract_info

Return specific information about deployed contracts

Endpoint: /api?req=dx.contract_info

Parameters:

Parameter	Description
contract	Required parameters, \<dapp_name>.\<contract_name>

Returns:

ContractID : uint64 - contract id , unique identification of a deployed contract
ContractVersionID : uint64 - contract id with version
Contract : string - contract name
Hash : string - hash of contract info
ImplmentedInterfaces : array - interface implemented by the contract
StateVariables : array - variables defined in the contract
Functions : array - functions defined in the contract
Interfaces : object - interface defined in the contract

Sample request:

http://{ip}:{port}/api?req=dx.contract_info

{
    "contract":"TestDapp.BitREXE"
}

Sample response:

{
    "rsp": "dx.contract_info",
    "ret": {
        "ContractID": 425202810880,
        "ContractVersionID": 425202810881,
        "Contract": "BitREXE",
        "Hash": "sxkakmtaznqjmc2nzpy7sktndgcddage8q0k3ak0jj1sm0b5z98g",
        "ImplmentedInterfaces": [],
        "StateVariables": [
            {
                "name": "brx",
                "scope": "global",
                "dataType": "token"
            },
            {
                "name": "rxbtc",
                "scope": "global",
                "dataType": "token"
            },
            {
                "name": "owner",
                "scope": "global",
                "dataType": "address"
            },
            {
                "name": "rxbtc_minter",
                "scope": "global",
                "dataType": "address"
            }
        ],
        "Scopes": {
            "global": "HasState|HasFunction",
            "address": "HasFunction"
        },
        "ScatteredMaps": {},
        "Structs": [],
        "Enumerables": [],
        "Interfaces": {},
        "Functions": [
            {
                "name": "on_deploy",
                "flag": "InvokeBySystem|GlobalStateDependency",
                "scope": "global",
                "opcode": 0
            },
            {
                "name": "setRxbtcMinter",
                "flag": "InvokeByNormalTransaction|EmitRelayInGlobalScope|GlobalStateDependency",
                "scope": "address",
                "opcode": 1
            },
            {
                "name": "depositBRX",
                "flag": "InvokeByNormalTransaction|EmitRelayInGlobalScope|GlobalStateDependency",
                "scope": "address",
                "opcode": 2
            },
            {
                "name": "mintRXBTC",
                "flag": "InvokeByNormalTransaction|EmitRelayInAddressScope|GlobalStateDependency",
                "scope": "address",
                "opcode": 3
            },
            {
                "name": "burnRXBTC",
                "flag": "InvokeByNormalTransaction",
                "scope": "address",
                "opcode": 4
            },
            {
                "name": "withdrawRXBTCTo",
                "flag": "InvokeByNormalTransaction|EmitRelayInGlobalScope|GlobalStateDependency",
                "scope": "address",
                "opcode": 5
            },
            {
                "name": "claimBRX",
                "flag": "InvokeByNormalTransaction|EmitRelayInGlobalScope",
                "scope": "address",
                "opcode": 6
            },
            {
                "name": "_deposit",
                "flag": "InvokeByRelayTransaction",
                "scope": "address",
                "opcode": 7
            },
            {
                "name": "__relaylambda_8_setRxbtcMinter",
                "flag": "InvokeByRelayTransaction|GlobalStateDependency",
                "scope": "global",
                "opcode": 8
            },
            {
                "name": "__relaylambda_9_depositBRX",
                "flag": "InvokeByRelayTransaction|GlobalStateDependency",
                "scope": "global",
                "opcode": 9
            },
            {
                "name": "__relaylambda_10_withdrawRXBTCTo",
                "flag": "InvokeByRelayTransaction|EmitRelayInAddressScope|GlobalStateDependency",
                "scope": "global",
                "opcode": 10
            },
            {
                "name": "getBrx",
                "flag": "InvokeByRelayTransaction|EmitRelayInAddressScope|GlobalStateDependency",
                "scope": "global",
                "opcode": 11
            }
        ]
    }
}

dx.generate_key

Generate public and private key pairs and user address

Endpoint: /api?req=dx.generate_key

Parameters:

Parameter	Description
shard_index	Optional parameter, select which shard the user information (address, public key, private key) is generated on. If not filled in or the shard_index is invalid, a random shard will generate the user information.
algo	Optional parameter,select which encryption algorithm will be used. `0`:ed25519 `1`:ethereum `2`:sm2

Returns:

PrivateKey : string - base64 encoded private-key(sk)
PublicKey : string - base64 encoded public-key(pk)
Address : string - base32 encoded address
Shard : uint16 - shard index which address belongs to

Sample request:

http://{ip}:{port}/api?req=dx.generate_key

{
    "shard_index":1,
    "algo":0
}

Sample response:

{
    "rsp": "dx.generate_key",
    "ret": {
        "PrivateKey": "3qys/L1nqhkaBQhvJ8YDMwwHoUwdfa2PKWPGLo1T2r0KVyT4ZLEykh1MN3EUlkTBudnHuJAJsei4got30u51yQ==",
        "PublicKey": "Clck+GSxMpIdTDdxFJZEwbnZx7iQCbHouIKLd9Ludck=",
        "Address": "19bj9y34p4s947ac6xrh95j4r6wxkhxrj04v3t5rga5qfmqeeq4h6vtx0w:ed25519",
        "Shard": 1
    }
}

tx module

Assembly transactions, broadcast transactions to the entire blockchain network

tx.compose

Assemble the transaction and return the base64-encoded transaction

Endpoint: /api?req=tx.compose

Parameters:

Parameter	Description
function	Required parameters, contract calling method, format is \<dapp_name>.\<contract_name>.\<function_name> The method to deploy the contract is: core.delegation.deploy_contracts,it's a built-in contract.
args	Required parameter, input parameter for contract method call, which is a json-object
sender	Required parameter, sender address
delegatee	Optional parameter, the address of the delegatee
gasprice	Optional parameter, default is the current average gasprice
ttl	Optional parameter, transaction's expire time, default 30 minutes,max 8 hours
sigcount	Optional parameter, number of signers, default is 1
tokens	Optional parameter, can carry multiple first-class-assets tokens to invoke contracts , format: [{\<token_symbol1>:\<amount1>},{\<token_symbol2>:<\amount2>}…]
isn	Optional parameter, set isn of transaction

Returns:

TxData : string - base64-encoded transaction
GasOffered : uint64 - gas used

Sample request:

http://{ip}:{port}/api?req=tx.compose

//normal transaction
{
    "sender":"cysxfbb3khcym79s2ewd653t7k0s9yvz94qyqfn16362htn8mwem7q8n6w:ed25519",
    "function":"TestDapp.FCA.transfer",
    "args":{
        "to":"v1yvr90ysmksjkw16sdjk73gq32v2hvz5wkj0amxvj80cy7qz9fk6nkz54:ed25519"
    },
    "tokens":[
        {"BRX":"100"},
        {"DTC":"50"}
    ]
}

//deploy_contracts tranasction
{
     "delegatee":"TestDapp:dapp",
     "function":"core.delegation.deploy_contracts",
     "args":{
        "code":["contract TestScope{\r\n\t@address uint32 storedData;\r\n    @shard uint32 perShardData;\r\n\t@uint256 string str;\r\n\t@uint256 int32 c;\r\n\t@uint32 string gstr;\r\n\t@uint32 int32 d;\r\n\t@address function set() export {\r\n\t\tstoredData = 3u;\r\n\t\trelay@12333423453465667777777777777777u256 f();\r\n\t\trelay@65534u32 g();\r\n\t}\r\n\t@uint256 function f() {\r\n\t\tstr = \"Hello world!\";\r\n\t\tc+=1;\r\n        __debug.print(str,c);\r\n\t}\r\n\t@uint32 function g() {\r\n\t\tgstr = \"yes!\";\r\n\t\td+=1;\r\n        __debug.print(gstr,d);\r\n\t}\r\n}"],
        "cargs":[""]
     }
}

//create token transaction
 {
     "gasprice":10000,
     "sender":"cysxfbb3khcym79s2ewd653t7k0s9yvz94qyqfn16362htn8mwem7q8n6w",
     "function":"core.delegation.create_token",
     "args":{
         "Decimals":4,
         "Deposit":"100000000",
         "InitSupply":"1000000",
         "Minter":0,"MinterFlags":1,
         "Symbol":"NFP",
         "TokenStates":0
     }
 }

Sample response:

{
    "rsp": "tx.compose",
    "ret": {
        "TxData": "QABANV6kigHNzQMAAAACAQoEAL8QJwAAAACghgEAAQIQAEMAAAA=", 
        "GasOffered": 100000
    }
}

How to call the built-in contracts:
core.coin (native token contract)
core.coin.burn
Destroying brx coins
Parameters:
Amount: The number of brx coins destroyed
core.coin.transfer
Transfer brx coins
Parameters
To: destination address
Amount: transfer amount
core.wallet (first-class-assets)
core.wallet.transfer
Transfer tokens created by user
Parameters
To: destination address
TokenId : token symbol
Amount: transfer amount
core.delegation (create dapp, create token, create contract related)
core.delegation.create
Create dapp
Parameters:
Type: 10 (indicates creating dapp)
Name: the name of the dapp, the length of the dapp name is [4,8]
Deposit: How many tokens to deposit into the dapp, it cannot be less than 1000'0000
core.delegation.deploy_contracts
Create contract
Parameters:
code: required parameters, contract source code, string-list
cars: required parameters, contract initialization parameters, jsonstring-list
time: optional parameter, contract compilation time limit, default 20s
core.delegation.create_token
Create Token
Parameters：
MinterFlags：
0：Do not allow tjhe minter to issue additional tokens
1：Allow tjhe minter to issue additional tokens
2：Do not allow tjhe minter to issue additional tokens(irrevocable)
3：Allow tjhe minter to issue additional tokens(irrevocable)
TokenStates：minter immutable flag, 0: minter mutable, 1:minter immutable
Minter：which contract can mint this token
Symbol：name of token, need to be capitalized
InitSupply：The initialization quantity of tokens
Deposit：How many tokens to deposit into the token, it cannot be less than 1000'0000
Decimals: Decimals of token
core.profile
core.profile.set
Set address's metadata
Parameters:
Metadata: Set attribute value

tx.sign

Sign a transaction

Endpoint: /api?req=tx.sign

Parameters:

Parameter	Description
sk	Required parameter, user's base64-encoded private key
txdata	Required parameters, base64 encoded data of the transaction

Returns:

TxData : string - base64-encoded signed transaction

Sample request:

http://{ip}:{port}/api?req=tx.sign

{
    "sk":["WcPIZxOzHa8JvEvG8s+r9FURitRtx7+IkP2kt9H4tldFnLR3kWXOGlbrS7CNcJ2bcRYAWZG2jetBGt7tDOC3gg=="],
    "txdata":"QAABfR+oigHNzQAAAAACAQEA/oYQJwAAAABdKwEAAVRlc3REYXBwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA2rLlUSUBAxQBAAAACAEAAAAAAAAFAZDmAQBdAAAIAAAxm8oZ261iyHRq7rtIfwpb5QSGtAswMIgQn9Wd4dhgOiOh9wthwpg0vg72jhszyJot75EZAXyxj22pw25TAmo/6SBX0F4hdqO/g17ic9VKfORcl6P5cVEbcF8HeV/Cz3RPfFrKmv7Sc6jC/aSvt2JkcfG7nldvRjdh8LqJ6hNgIJYFf/7lPysUlnrJAa//MLbPCVEktJ6bBYrND0luZrdQ7N+7cHyCMgvpsL73Vnj0E6z010rkbNlpXvM6Wl/VUwdNPTnG7UcBOVK3wjTDPYqDC6Du/K4uhc2HSSrn0f8QHpIOZb8Gt86Vsmh4MCvt9i1pdlCbxOTAOBxaDmABAAAAAwAAAAAAAAAAADA=",
}

Sample response:

{
    "rsp": "tx.sign",
    "ret": {
        "TxData": "QADXR0OkjAEAAAAAAQABAACEECcAAAAABwMAAAFEVEMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALtsvv81AGez161jnFnqHTkTuNMUejzBlPt/SS/rvqEwzCjqqKcdQ90VN0RUQwAAAAAAARAnAAAAAAAAA2ez161jnFnqHTkTuNMUejzBlPt/SS/rvqEwzCjqqKcdZ47OPJAMiho2BWsxTriTLxwf8k7k2Zeun4kcYeBIFAiVyEJ5J3z/+YXe/EYbT5htbPSWXBOiQRwO1/yO1nrSBtsgAABfPwAA2ksAAA=="
    }
}

tx.send

Send the signed transaction to the blockchain network and broadcast it to the entire network

Endpoint: /api?req=tx.send

Parameters:

Parameter	Description
txdata	Required parameters, base64-encoded data of signed transaction

Returns:

Hash : string - transaction hash

Sample request:

http://{{local_rpc}}/api?req=tx.send

{
"txdata":"QABANV6kigHNzQMAAAACAQoEAL8QJwAAAACghgEAAQIQAEMAAAADRZy0d5FlzhpW60uwjXCdm3EWAFmRto3rQRre7Qzgt4LxQcJLZ7mxtm8tianqpZgMRf0MEYAeSDeAJS7FTXbi+pysIm3r9lhJx+/3EFNGFUDwr80fUISOpHymzS05vGkMADUAAII/AADERQAA",
}

Sample response:

{
    "rsp": "tx.send",
    "ret": {
        "Hash": "29at0m38p7z6f863xt5avq7hp71jzd1mazxkx52kg4e3wpvzetrg"
    }
}

dx module​

dx.overview​

dx.head_height​

dx.mining​

dx.shard_info​

dx.shard_index​

dx.mempool​

dx.state_history​

dx.contract_state​

dx.consensus_header​

dx.transaction_block​

dx.transaction​

dx.dapp​

dx.contract_info​

dx.generate_key​

tx module​

tx.compose​

tx.sign​

tx.send​

dx module

dx.overview

dx.head_height

dx.mining

dx.shard_info

dx.shard_index

dx.mempool

dx.state_history

dx.contract_state

dx.consensus_header

dx.transaction_block

dx.transaction

dx.dapp

dx.contract_info

dx.generate_key

tx module

tx.compose

tx.sign

tx.send