# 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](/wiki/developer/api/subchain_rpc.md#subchain)

| Command                                                                            | Full | Light | public | private |
| ---------------------------------------------------------------------------------- | :--: | :---: | :----: | :-----: |
| [GetBlockCreator](/wiki/developer/api/subchain_rpc.md#getblockcreator)             |   ✓  |       |    ✓   |         |
| [GetBalanceTreeRoot](/wiki/developer/api/subchain_rpc.md#getbalancetreeroot)       |   ✓  |       |    ✓   |         |
| [GetTxTreeRoot](/wiki/developer/api/subchain_rpc.md#gettxtreeroot)                 |   ✓  |       |    ✓   |         |
| [GetBlockSignature](/wiki/developer/api/subchain_rpc.md#getblocksignature)         |   ✓  |       |    ✓   |         |
| [GetBlockInfoForStem](/wiki/developer/api/subchain_rpc.md#getblockinfoforstem)     |   ✓  |       |    ✓   |         |
| [GetTxMerkleInfo](/wiki/developer/api/subchain_rpc.md#gettxmerkleinfo)             |   ✓  |       |    ✓   |         |
| [GetBalanceMerkleInfo](/wiki/developer/api/subchain_rpc.md#getbalancemerkleinfo)   |   ✓  |       |    ✓   |         |
| [GetRecentTxTreeRoot](/wiki/developer/api/subchain_rpc.md#getrecenttxtreeroot)     |   ✓  |       |    ✓   |         |
| [GetRecentTxMerkleInfo](/wiki/developer/api/subchain_rpc.md#getrecenttxmerkleinfo) |   ✓  |       |    ✓   |         |
| [GetAccountTx](/wiki/developer/api/subchain_rpc.md#getaccounttx)                   |   ✓  |       |    ✓   |         |
| [GetUpdatedAccountInfo](/wiki/developer/api/subchain_rpc.md#getupdatedaccountinfo) |   ✓  |       |    ✓   |         |
| [GetFee](/wiki/developer/api/subchain_rpc.md#getfee)                               |   ✓  |       |    ✓   |         |
| [GetRelayInterval](/wiki/developer/api/subchain_rpc.md#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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBlockCreator","params":[10],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBalanceTreeRoot","params":[5],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getTxTreeRoot","params":[5],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBlockSignature","params":[5],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBlockInfoForStem","params":[5],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getTxMerkleInfo","params":["0x35504bd889343dac8c4d6a3fbb23ae3ee63929ee6555bf17a9e8e2fc007db6de"],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getBalanceMerkleInfo","params":["0x8cd42eebf7ccc855b303e8bba75674c8f3d0f1e1", 100],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getRecentTxTreeRoot","params":[80],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getRecentTxMerkleInfo","params":["0x8cd42eebf7ccc855b303e8bba75674c8f3d0f1e1", 80],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getAccountTx","params":["0x8cd42eebf7ccc855b303e8bba75674c8f3d0f1e1", 60, 80],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getUpdatedAccountInfo","params":[80],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getFee","params":[40],"id":1}' localhost:8031
```

* Result

```javascript
{
    "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

```javascript
curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"subchain_getRelayInterval","params":[],"id":1}' localhost:8031
```

* Result

```javascript
{
    "jsonrpc":"2.0",
    "id":1,
    "result":
    {
        "result":20,
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://seeletech.gitbook.io/wiki/developer/api/subchain_rpc.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.