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

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,
    }
}
Previousjson-rpc NV >= 1.3.0NextSubchain

Last updated

Was this helpful?