json-subchain-rpc

JSON is a lightweight data exchange format. It can represent numbers, strings, ordered value sequences and key-value pairs.
JSON-RPC is a stateless, lightweight Remote Procedure Call (RPC) protocol. It defines several data structures and the relevant rules to handle them. JSON-RPC is transmission-agnostic, because it can be used in situations like process, socket, HTTP, or different message transmission environments. It uses JSON(RFC 4627) as the data format.
Curl Examples Explained
The curl options below might return a response where the node complains about the content type, this is because the --data option sets the content type to application/x-www-form-urlencoded .
JSON-RPC Support
Type
Supported?
JSON-RPC 1.0
✓
JSON-RPC 2.0
✓
Batch Requests
✓
HTTP
✓
WS
✓
JSON-RPC Port
Default port:
Client
Type
Address
Go
jsonrpc-2.0
​http://localhost:8027​
Go
http
​http://localhost:8037​
Go
websocket
​http://localhost:8047​
JSON-RPC Contents
​subchain​
Command
Full
Light
public
private
​GetBlockCreator​
✓
​
✓
​
​GetBalanceTreeRoot​
✓
​
✓
​
​GetTxTreeRoot​
✓
​
✓
​
​GetBlockSignature​
✓
​
✓
​
​GetBlockInfoForStem​
✓
​
✓
​
​GetTxMerkleInfo​
✓
​
✓
​
​GetBalanceMerkleInfo​
✓
​
✓
​
​GetRecentTxTreeRoot​
✓
​
✓
​
​GetRecentTxMerkleInfo​
✓
​
✓
​
​GetAccountTx​
✓
​
✓
​
​GetUpdatedAccountInfo​
✓
​
✓
​
​GetFee​
✓
​
✓
​
​GetRelayInterval​
✓
​
✓
​
subchain
This RPC collection provides information of the subchain.
GetBlockCreator
This method returns the creator of a block.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getBlockCreator","params":[int64],"id":1}
Parameters
height:int64 - block height. Set to current block height if the given height is negative
Returns
result: string - the creator of the block
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBlockCreator","params":[10],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":"0xc78995a18569baf5e0f787c3d8d55a858602e381"
}
GetBalanceTreeRoot
This method returns the root hash of the balance merkle tree of a block.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getBalanceTreeRoot","params":[int64],"id":1}
Parameters
height:int64 - block height. Set to current block height if the given height is negative
Returns
result: string - the root hash of the balance merkle tree
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBalanceTreeRoot","params":[5],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":"0x9f42c64b532f232abf470901aaec90c464e03c1c42f62c1cab98980ba7e270cd"
}
GetTxTreeRoot
This method returns the root hash of the transaction merkle tree of a block.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getTxTreeRoot","params":[int64],"id":1}
Parameters
height:int64 - block height. Set to current block height if the given height is negative
Returns
result: string - the root hash of the transaction merkle tree
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getTxTreeRoot","params":[5],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":"0x0000000000000000000000000000000000000000000000000000000000000000"
}
GetBlockSignature
This method returns the signature of a block.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getBlockSignature","params":[int64],"id":1}
Parameters
height:int64 - block height. Set to current block height if the given height is negative
Returns
result: string - the signature of a block
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBlockSignature","params":[5],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":"gnNE0tY4xh7bHSlPHwmYfynpiCEWww1Heh/fxPGgUDMbLF0zS5Aps7GYN74H96SFZzpaFD7VPqwDYLCtMDEVBAE="
}
GetBlockInfoForStem
This method returns some information of a block including the block creator, the root hash of tx tree and the root hash of balance tree.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getBlockInfoForStem","params":[int64],"id":1}
Parameters
height:int64 - block height. Set to current block height if the given height is negative
Returns
result: string - the RLP string of [block creator, block height, the root hash of tx tree, the root hash of balance tree]
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBlockInfoForStem","params":[5],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":"+FiUx4mVoYVpuvXg94fD2NVahYYC44EFoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAoJ9CxktTLyMqv0cJAarskMRk4DwcQvYsHKuYmAun4nDN"
}
GetTxMerkleInfo
This method returns the index and merkle proof of a transaction on the transaction merkle tree.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getTxMerkleInfo","params":[string],"id":1}
Parameters
hexHash:string - hex form of a transaction hash
Returns
merkle index: int - the index of the input transaction at the leaf level of the transaction merkle tree
merkle proof: string - the merkle proof of the input transaction
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getTxMerkleInfo","params":["0x35504bd889343dac8c4d6a3fbb23ae3ee63929ee6555bf17a9e8e2fc007db6de"],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":
    {
        "merkle index":0,
        "merkle proof":"wA=="
    }
}
GetBalanceMerkleInfo
This method returns the index and merkle proof of an account on the balance merkle tree at a given height.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getBalanceMerkleInfo","params":[string, int64],"id":1}
Parameters
account:string - account
height:int64 - block height. Set to current block height if the given height is negative
Returns
account: string - account
balance: big.Int - account balance
merkle index: int - the index of the input account at the leaf level of the balance merkle tree
merkle proof: string - the merkle proof of the input account
nonce: uint64 - account nonce
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBalanceMerkleInfo","params":["0x8cd42eebf7ccc855b303e8bba75674c8f3d0f1e1", 100],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,"result":
    {
        "account":"0xeeedb76e23cd27988543832f7a09ca8e80b7dc11",
        "balance":17499999999971922,
        "merkle index":1,
        "merkle proof":"+EKgn0LGS1MvIyq/RwkBquyQxGTgPBxC9iwcq5iYC6ficM2gfzJ8t/g1LaYrX8+NFCa1E3bwdHKQLs+BMDHrLAWTQvg=",
        "nonce":1}
    }
GetRecentTxTreeRoot
This method returns the root hash of the recent transaction merkle tree.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getRecentTxTreeRoot","params":[int64],"id":1}
Parameters
height:int64 - block height. Set to current block height if the given height is negative
Returns
result: string - the root hash of the recent transaction merkle tree; return empty hash if this block is not a relay block
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getRecentTxTreeRoot","params":[80],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":"0x07c0f93a6ddff59831c6975fd39b5a3eb048775c2c10fcfd8801c512078bbd6a"
}
GetRecentTxMerkleInfo
This method returns the index and merkle proof of an account on the recent transaction merkle tree at a given height.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getRecentTxMerkleInfo","params":[string, int64],"id":1}
Parameters
account:string - account
height:int64 - block height. Set to current block height if the given height is negative
Returns
account: string - account
merkle index: int - the index of the input account at the leaf level of the recent transaction merkle tree
merkle proof: string - the merkle proof of the input account
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getRecentTxMerkleInfo","params":["0x8cd42eebf7ccc855b303e8bba75674c8f3d0f1e1", 80],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":
    {
        "account":"0x8cd42eebf7ccc855b303e8bba75674c8f3d0f1e1",
        "merkle index":1,
        "merkle proof":"4aCr4Xf+YSGbnph4GbrIHmWWT33zlCGFSE1zDEl8HtZw4w=="
    }
}
GetAccountTx
This method returns the transactions and stem signatures(used in Stem contract) of an account between two blocks(inclusive).
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getAccountTx","params":[string, int64, int64],"id":1}
Parameters
account:string - account
startHeight:int64 - start height. Set to current block height if the given height is negative
endHeight:int64 - end height. Set to current block height if the given height is negative
Returns
account: string - account
txs: string - the RLP string of the transaction array of the input account from startHeight to endHeight
signatures: string - the RLP string of the Stem signature array corresponding to the transaction array
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getAccountTx","params":["0x8cd42eebf7ccc855b303e8bba75674c8f3d0f1e1", 60, 80],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":
    {
        "account":"0x8cd42eebf7ccc855b303e8bba75674c8f3d0f1e1",
        "signatures":"+EO4QRJt2rePmjk3Elw97AP5jsg0KJNWSxtK/7cD46+tsVEWGWXjb/jD6VaHj1/PiwPLr+5ZE8Rc2gvZj4aP2q9VOhIA",
        "txs":"87LxlO7tt24jzSeYhUODL3oJyo6At9wRlIzULuv3zMhVswPou6dWdMjz0PHhAoABgx6EgA=="
    }
}
GetUpdatedAccountInfo
This method returns the recent updated accounts.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getUpdatedAccountInfo","params":[int64],"id":1}
Parameters
height:uint64 - block height
Returns
updated accounts: string - the RLP string of the array of recent updated accounts from height - relayInterval + 1 to height
balances: string - the RLP string of the balance array corresponding to updated accounts
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getUpdatedAccountInfo","params":[80],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":
    {
        "balances":"yoCHPiwoQ5FSUgI=",
        "updated accounts":"+D+Ux4mVoYVpuvXg94fD2NVahYYC44GU7u23biPNJ5iFQ4MvegnKjoC33BGUjNQu6/fMyFWzA+i7p1Z0yPPQ8eE="
    }
}
GetFee
This method returns the number of verifers and their fee income given the height of relay block.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getFee","params":[uint64],"id":1}
Parameters
height:uint64 - block height, should be the height of a relay block
Returns
fee: big.Int - the fee income of each verifier from height - relayInterval + 1 to height
verNum: big.Int - the number of verifiers from height - relayInterval + 1 to height
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getFee","params":[40],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":
    {
        "fee":9358,
        "verNum":3
    }
}
GetRelayInterval
This method returns the relay interval of the subchain.
Type
Template
RPC
{"jsonrpc":"2.0","method":"subchain_getRelayInterval","params":[],"id":1}
Parameters
None
Returns
Result: uint64 - relay block interval
Example
Request
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getRelayInterval","params":[],"id":1}' localhost:8031
Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result":
    {
        "result":20,
    }
}
Last modified 2yr ago
Type	Supported?
JSON-RPC 1.0	✓
JSON-RPC 2.0	✓
Batch Requests	✓
HTTP	✓
WS	✓
Client	Type	Address
Go	jsonrpc-2.0	http://localhost:8027
Go	http	http://localhost:8037
Go	websocket	http://localhost:8047
Command	Full	Light	public	private
GetBlockCreator	✓		✓
GetBalanceTreeRoot	✓		✓
GetTxTreeRoot	✓		✓
GetBlockSignature	✓		✓
GetBlockInfoForStem	✓		✓
GetTxMerkleInfo	✓		✓
GetBalanceMerkleInfo	✓		✓
GetRecentTxTreeRoot	✓		✓
GetRecentTxMerkleInfo	✓		✓
GetAccountTx	✓		✓
GetUpdatedAccountInfo	✓		✓
GetFee	✓		✓
GetRelayInterval	✓		✓
Type	Template
RPC	`{"jsonrpc":"2.0","method":"subchain_getBlockCreator","params":[int64],"id":1}`