CKB JSON-RPC Protocols

The RPC interface shares the version of the node version, which is returned in local_node_info. The interface is fully compatible between patch versions, for example, a client for 0.25.0 should work with 0.25.x for any x.

Allowing arbitrary machines to access the JSON-RPC port (using the rpc.listen_address configuration option) is dangerous and strongly discouraged. Please strictly limit the access to only trusted machines.

CKB JSON-RPC only supports HTTP now. If you need SSL, please set up a proxy via Nginx or other HTTP servers.

Subscriptions require a full duplex connection. CKB offers such connections in the form of TCP (enable with rpc.tcp_listen_address configuration option) and WebSockets (enable with rpc.ws_listen_address).

JSONRPC Deprecation Process

A CKB RPC method is deprecated in three steps.

First, the method is marked as deprecated in the CKB release notes and RPC document. However, the RPC method is still available. The RPC document will have the suggestion of alternative solutions.

The CKB dev team will disable any deprecated RPC methods starting from the next minor version release. Users can enable the deprecated methods via the config file option rpc.enabledeprecatedrpc.

Once a deprecated method is disabled, the CKB dev team will remove it in a future minor version release.

For example, a method is marked as deprecated in 0.35.0, it can be disabled in 0.36.0 and removed in 0.37.0. The minor versions are released monthly, so there's at least a two-month buffer for a deprecated RPC method.

Minimum Supported Rust Version policy (MSRV)

The crate ckb-rpc's minimum supported rustc version is 1.67.1.

Table of Contents

RPC Methods

Module Alert

RPC Module Alert for network alerts.

An alert is a message about critical problems to be broadcast to all nodes via the p2p network.

The alerts must be signed by 2-of-4 signatures, where the public keys are hard-coded in the source code and belong to early CKB developers.

Method send_alert

Sends an alert.

This RPC returns null on success.

Errors
Examples

Request

{ "jsonrpc": "2.0", "method": "send_alert", "params": [ { "id": "0x1", "cancel": "0x0", "priority": "0x1", "message": "An example alert message!", "notice_until": "0x24bcca57c00", "signatures": [ "0xbd07059aa9a3d057da294c2c4d96fa1e67eeb089837c87b523f124239e18e9fc7d11bb95b720478f7f937d073517d0e4eb9a91d12da5c88a05f750362f4c214dd0", "0x0242ef40bb64fe3189284de91f981b17f4d740c5e24a3fc9b70059db6aa1d198a2e76da4f84ab37549880d116860976e0cf81cd039563c452412076ebffa2e4453" ] } ], "id": 42 }

Response

{ "error": { "code": -1000, "data": "SigNotEnough", "message":"AlertFailedToVerifySignatures: The count of sigs less than threshold." }, "jsonrpc": "2.0", "result": null, "id": 42 }

Module Chain

RPC Module Chain for methods related to the canonical chain.

This module queries information about the canonical chain.

Canonical Chain

A canonical chain is the one with the most accumulated work. The accumulated work is the sum of difficulties of all the blocks in the chain.

Chain Reorganization

Chain Reorganization happens when CKB found a chain that has accumulated more work than the canonical chain. The reorganization reverts the blocks in the current canonical chain if needed, and switch the canonical chain to that better chain.

Live Cell

A cell is live if

Method get_block

Returns the information about a block by hash.

Params
Returns

The RPC returns a block or null. When the RPC returns a block, the block hash must equal to the parameter block_hash.

If the block is in the canonical chain, the RPC must return the block information. Otherwise, the behavior is undefined. The RPC may return blocks found in local storage or simply returns null for all blocks that are not in the canonical chain. And because of chain reorganization, for the same block_hash, the RPC may sometimes return null and sometimes return the block.

When verbosity is 2, it returns a JSON object as the result. See BlockView for the schema.

When verbosity is 0, it returns a 0x-prefixed hex string as the result. The string encodes the block serialized by molecule using schema table Block.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_block", "params": [ "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "header": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b117", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version": "0x0" }, "proposals": [], "transactions": [ { "cell_deps": [], "hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17", "header_deps": [], "inputs": [ { "previous_output": { "index": "0xffffffff", "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "since": "0x400" } ], "outputs": [ { "capacity": "0x18e64b61cf", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [ "0x450000000c000000410000003500000010000000300000003100000028e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5000000000000000000" ] } ], "uncles": [] } }

The response looks like below when verbosity is 0.

{ "id": 42, "jsonrpc": "2.0", "result": "0x..." }

When specifying with_cycles, the response object will be different like below:

{ "id": 42, "jsonrpc": "2.0", "result": { "block": <Object> or "0x...", "cycles": [] } }

Method get_block_by_number

Returns the block in the canonical chain with the specific block number.

Params
Returns

The RPC returns the block when block_number is less than or equal to the tip block number returned by get_tip_block_number and returns null otherwise.

Because of chain reorganization, the PRC may return null or even different blocks in different invocations with the same block_number.

When verbosity is 2, it returns a JSON object as the result. See BlockView for the schema.

When verbosity is 0, it returns a 0x-prefixed hex string as the result. The string encodes the block serialized by molecule using schema table Block.

Errors
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_block_by_number", "params": [ "0x400" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "header": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b117", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version": "0x0" }, "proposals": [], "transactions": [ { "cell_deps": [], "hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17", "header_deps": [], "inputs": [ { "previous_output": { "index": "0xffffffff", "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "since": "0x400" } ], "outputs": [ { "capacity": "0x18e64b61cf", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [ "0x450000000c000000410000003500000010000000300000003100000028e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5000000000000000000" ] } ], "uncles": [] } }

The response looks like below when verbosity is 0.

{ "id": 42, "jsonrpc": "2.0", "result": "0x..." }

When specifying with_cycles, the response object will be different like below:

{ "id": 42, "jsonrpc": "2.0", "result": { "block": <Object> or "0x...", "cycles": [] } }

Method get_header

Returns the information about a block header by hash.

Params
Returns

The RPC returns a header or null. When the RPC returns a header, the block hash must equal to the parameter block_hash.

If the block is in the canonical chain, the RPC must return the header information. Otherwise, the behavior is undefined. The RPC may return blocks found in local storage or simply returns null for all blocks that are not in the canonical chain. And because of chain reorganization, for the same block_hash, the RPC may sometimes return null and sometimes return the block header.

When verbosity is 1, it returns a JSON object as the result. See HeaderView for the schema.

When verbosity is 0, it returns a 0x-prefixed hex string as the result. The string encodes the block header serialized by molecule using schema table Header.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_header", "params": [ "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b117", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version": "0x0" } }

The response looks like below when verbosity is 0.

{ "id": 42, "jsonrpc": "2.0", "result": "0x..." }

Method get_header_by_number

Returns the block header in the canonical chain with the specific block number.

Params
Returns

The RPC returns the block header when block_number is less than or equal to the tip block number returned by get_tip_block_number and returns null otherwise.

Because of chain reorganization, the PRC may return null or even different block headers in different invocations with the same block_number.

When verbosity is 1, it returns a JSON object as the result. See HeaderView for the schema.

When verbosity is 0, it returns a 0x-prefixed hex string as the result. The string encodes the block header serialized by molecule using schema table Header.

Errors
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_header_by_number", "params": [ "0x400" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b117", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version": "0x0" } }

The response looks like below when verbosity is 0.

{ "id": 42, "jsonrpc": "2.0", "result": "0x..." }

Method get_block_filter

Returns the block filter by block hash.

Params
Returns

The block filter data

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_block_filter", "params": [ "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

The response looks like below when the block have block filter.

{ "id": 42, "jsonrpc": "2.0", "result": { "data": "0x...", "hash": "0x..." } }

Method get_transaction

Returns the information about a transaction requested by transaction hash.

Returns

This RPC returns null if the transaction is not committed in the canonical chain nor the transaction memory pool.

If the transaction is in the chain, the block hash is also returned.

Params
Returns

When verbosity=0, it’s response value is as same as verbosity=2, but it return a 0x-prefixed hex encoded molecule packed::Transaction on transaction field

When verbosity is 1: The RPC does not return the transaction content and the field transaction must be null.

When verbosity is 2: if tx_status.status is pending, proposed, or committed, the RPC returns the transaction content as field transaction, otherwise the field is null.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_transaction", "params": [ "0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "transaction": { "cell_deps": [ { "dep_type": "code", "out_point": { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" } } ], "hash": "0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3", "header_deps": [ "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed" ], "inputs": [ { "previous_output": { "index": "0x0", "tx_hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17" }, "since": "0x0" } ], "outputs": [ { "capacity": "0x2540be400", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [] }, "cycles": "0x219", "time_added_to_pool" : "0x187b3d137a1", "tx_status": { "block_hash": null, "status": "pending", "reason": null } } }

The response looks like below when verbosity is 0.

{ "id": 42, "jsonrpc": "2.0", "result": { "transaction": "0x.....", "cycles": "0x219", "tx_status": { "block_hash": null, "status": "pending", "reason": null } } }

Method get_block_hash

Returns the hash of a block in the canonical chain with the specified block_number.

Params
Returns

The RPC returns the block hash when block_number is less than or equal to the tip block number returned by get_tip_block_number and returns null otherwise.

Because of chain reorganization, the PRC may return null or even different block hashes in different invocations with the same block_number.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_block_hash", "params": [ "0x400" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40" }

Method get_tip_header

Returns the header with the highest block number in the canonical chain.

Because of chain reorganization, the block number returned can be less than previous invocations and different invocations may return different block headers with the same block number.

Params
Returns

When verbosity is 1, the RPC returns a JSON object as the result. See HeaderView for the schema.

When verbosity is 0, it returns a 0x-prefixed hex string as the result. The string encodes the header serialized by molecule using schema table Header.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_tip_header", "params": [] }

Response

{ "jsonrpc": "2.0", "result": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b117", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version": "0x0" }, "id": 42 }

The response looks like below when verbosity is 0.

{ "id": 42, "jsonrpc": "2.0", "result": "0x..." }

Method get_live_cell

Returns the status of a cell. The RPC returns extra information if it is a live cell.

Returns

This RPC tells whether a cell is live or not.

If the cell is live, the RPC will return details about the cell. Otherwise, the field cell is null in the result.

If the cell is live and with_data is set to false, the field cell.data is null in the result.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_live_cell", "params": [ { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" }, true ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "cell": { "data": { "content": "0x7f454c460201010000000000000000000200f3000100000078000100000000004000000000000000980000000000000005000000400038000100400003000200010000000500000000000000000000000000010000000000000001000000000082000000000000008200000000000000001000000000000001459308d00573000000002e7368737472746162002e74657874000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000b000000010000000600000000000000780001000000000078000000000000000a0000000000000000000000000000000200000000000000000000000000000001000000030000000000000000000000000000000000000082000000000000001100000000000000000000000000000001000000000000000000000000000000", "hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5" }, "output": { "capacity": "0x802665800", "lock": { "code_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash_type": "data", "args": "0x" }, "type": null } }, "status": "live" } }

Method get_tip_block_number

Returns the highest block number in the canonical chain.

Because of chain reorganization, the returned block number may be less than a value returned in the previous invocation.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_tip_block_number", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0x400" }

Method get_current_epoch

Returns the epoch with the highest number in the canonical chain.

Pay attention that like blocks with the specific block number may change because of chain reorganization, This RPC may return different epochs which have the same epoch number.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_current_epoch", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "compact_target": "0x1e083126", "length": "0x708", "number": "0x1", "start_number": "0x3e8" } }

Method get_epoch_by_number

Returns the epoch in the canonical chain with the specific epoch number.

Params
Returns

The RPC returns the epoch when epoch_number is less than or equal to the current epoch number returned by get_current_epoch and returns null otherwise.

Because of chain reorganization, for the same epoch_number, this RPC may return null or different epochs in different invocations.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_epoch_by_number", "params": [ "0x0" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "compact_target": "0x20010000", "length": "0x3e8", "number": "0x0", "start_number": "0x0" } }

Method get_block_economic_state

Returns increased issuance, miner reward, and the total transaction fee of a block.

This RPC returns null if the block is not in the canonical chain.

CKB delays CKB creation for miners. The output cells in the cellbase of block N are for the miner creating block N - 1 - ProposalWindow.farthest.

In mainnet, ProposalWindow.farthest is 10, so the outputs in block 100 are rewards for miner creating block 89.

Because of the delay, this RPC returns null if the block rewards are not finalized yet. For example, the economic state for block 89 is only available when the number returned by get_tip_block_number is greater than or equal to 100.

Params
Returns

If the block with the hash block_hash is in the canonical chain and its rewards have been finalized, return the block rewards analysis for this block. A special case is that the return value for genesis block is null.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_block_economic_state", "params": [ "0x02530b25ad0ff677acc365cb73de3e8cc09c7ddd58272e879252e199d08df83b" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "finalized_at": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "issuance": { "primary": "0x18ce922bca", "secondary": "0x7f02ec655" }, "miner_reward": { "committed": "0x0", "primary": "0x18ce922bca", "proposal": "0x0", "secondary": "0x17b93605" }, "txs_fee": "0x0" } }

Method get_transaction_proof

Returns a Merkle proof that transactions are included in a block.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_transaction_proof", "params": [ [ "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" ] ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "block_hash": "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed", "proof": { "indices": [ "0x0" ], "lemmas": [] }, "witnesses_root": "0x2bb631f4a251ec39d943cc238fc1e39c7f0e99776e8a1e7be28a03c70c4f4853" } }

Method verify_transaction_proof

Verifies that a proof points to transactions in a block, returning the transaction hashes it commits to.

Parameters
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "verify_transaction_proof", "params": [ { "block_hash": "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed", "proof": { "indices": [ "0x0" ], "lemmas": [] }, "witnesses_root": "0x2bb631f4a251ec39d943cc238fc1e39c7f0e99776e8a1e7be28a03c70c4f4853" } ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": [ "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" ] }

Method get_transaction_and_witness_proof

Returns a Merkle proof of transactions’ witness included in a block.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_transaction_and_witness_proof", "params": [ [ "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" ] ] }

Response

{ "jsonrpc": "2.0", "result": { "block_hash": "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed", "transactions_proof": { "indices": [ "0x0" ], "lemmas": [] }, "witnesses_proof": { "indices": [ "0x0" ], "lemmas": [] } }, "id": 42 }

Method verify_transaction_and_witness_proof

Verifies that a proof points to transactions in a block, returning the transaction hashes it commits to.

Parameters
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "verify_transaction_and_witness_proof", "params": [ { "block_hash": "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed", "transactions_proof": { "indices": [ "0x0" ], "lemmas": [] }, "witnesses_proof": { "indices": [ "0x0" ], "lemmas": [] } } ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": [ "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" ] }

Method get_fork_block

Returns the information about a fork block by hash.

Params
Returns

The RPC returns a fork block or null. When the RPC returns a block, the block hash must equal to the parameter block_hash.

Please note that due to the technical nature of the peer to peer sync, the RPC may return null or a fork block result on different nodes with same block_hash even they are fully synced to the canonical chain. And because of chain reorganization, for the same block_hash, the RPC may sometimes return null and sometimes return the fork block.

When verbosity is 2, it returns a JSON object as the result. See BlockView for the schema.

When verbosity is 0, it returns a 0x-prefixed hex string as the result. The string encodes the block serialized by molecule using schema table Block.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_fork_block", "params": [ "0xdca341a42890536551f99357612cef7148ed471e3b6419d0844a4e400be6ee94" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "header": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash": "0xdca341a42890536551f99357612cef7148ed471e3b6419d0844a4e400be6ee94", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b118", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version": "0x0" }, "proposals": [], "transactions": [ { "cell_deps": [], "hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17", "header_deps": [], "inputs": [ { "previous_output": { "index": "0xffffffff", "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "since": "0x400" } ], "outputs": [ { "capacity": "0x18e64b61cf", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [ "0x450000000c000000410000003500000010000000300000003100000028e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5000000000000000000" ] } ], "uncles": [] } }

The response looks like below when verbosity is 0.

{ "id": 42, "jsonrpc": "2.0", "result": "0x..." }

Method get_consensus

Return various consensus parameters.

Returns

If any hardfork feature has epoch=null, it means the feature will never be activated.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_consensus", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "block_version": "0x0", "cellbase_maturity": "0x10000000000", "dao_type_hash": null, "epoch_duration_target": "0x3840", "genesis_hash": "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed", "hardfork_features": [ { "rfc": "0028", "epoch_number": "0x1526" }, { "rfc": "0029", "epoch_number": "0x0" }, { "rfc": "0030", "epoch_number": "0x0" }, { "rfc": "0031", "epoch_number": "0x0" }, { "rfc": "0032", "epoch_number": "0x0" }, { "rfc": "0036", "epoch_number": "0x0" }, { "rfc": "0038", "epoch_number": "0x0" }, { "rfc": "0048", "epoch_number": null }, { "rfc": "0049", "epoch_number": null } ], "id": "main", "initial_primary_epoch_reward": "0x71afd498d000", "max_block_bytes": "0x91c08", "max_block_cycles": "0xd09dc300", "max_block_proposals_limit": "0x5dc", "max_uncles_num": "0x2", "median_time_block_count": "0x25", "orphan_rate_target": { "denom": "0x28", "numer": "0x1" }, "permanent_difficulty_in_dummy": false, "primary_epoch_reward_halving_interval": "0x2238", "proposer_reward_ratio": { "denom": "0xa", "numer": "0x4" }, "secondary_epoch_reward": "0x37d0c8e28542", "secp256k1_blake160_multisig_all_type_hash": null, "secp256k1_blake160_sighash_all_type_hash": null, "softforks": { "testdummy": { "status": "rfc0043", "rfc0043": { "bit": 1, "min_activation_epoch": "0x0", "period": "0xa", "start": "0x0", "threshold": { "denom": "0x4", "numer": "0x3" }, "timeout": "0x0" } } }, "tx_proposal_window": { "closest": "0x2", "farthest": "0xa" }, "tx_version": "0x0", "type_id_code_hash": "0x00000000000000000000000000000000000000000000000000545950455f4944" } }

Method get_block_median_time

Returns the past median time by block hash.

Params
Returns

When the given block hash is not on the current canonical chain, this RPC returns null; otherwise returns the median time of the consecutive 37 blocks where the given block_hash has the highest height.

Note that the given block is included in the median time. The included block number range is [MAX(block - 36, 0), block].

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_block_median_time", "params": [ "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0x5cd2b105" }

Method estimate_cycles

estimate_cycles run a transaction and return the execution consumed cycles.

This method will not check the transaction validity, but only run the lock script and type script and then return the execution cycles.

It is used to estimate how many cycles the scripts consume.

Errors
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "estimate_cycles", "params": [ { "cell_deps": [ { "dep_type": "code", "out_point": { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" } } ], "header_deps": [ "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed" ], "inputs": [ { "previous_output": { "index": "0x0", "tx_hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17" }, "since": "0x0" } ], "outputs": [ { "capacity": "0x2540be400", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [] } ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "cycles": "0x219" } }

Method get_fee_rate_statics

👎Deprecated since 0.109.0: Please use the RPC method get_fee_rate_statistics instead

Returns the fee_rate statistics of confirmed blocks on the chain

Params
Returns

If the query finds the corresponding historical data, the corresponding statistics are returned, containing the mean and median, in shannons per kilo-weight. If not, it returns null.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_fee_rate_statics", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "mean": "0xe79d", "median": "0x14a8" } }

Method get_fee_rate_statistics

Returns the fee_rate statistics of confirmed blocks on the chain

Params
Returns

If the query finds the corresponding historical data, the corresponding statistics are returned, containing the mean and median, in shannons per kilo-weight. If not, it returns null.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_fee_rate_statistics", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "mean": "0xe79d", "median": "0x14a8" } }

Module Experiment

RPC Module Experiment for experimenting methods.

EXPERIMENTAL warning

The methods here may be removed or changed in future releases without prior notifications.

Method dry_run_transaction

👎Deprecated since 0.105.1: Please use the RPC method estimate_cycles instead

Dry run a transaction and return the execution cycles.

This method will not check the transaction validity, but only run the lock script and type script and then return the execution cycles.

It is used to debug transaction scripts and query how many cycles the scripts consume.

Errors
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "dry_run_transaction", "params": [ { "cell_deps": [ { "dep_type": "code", "out_point": { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" } } ], "header_deps": [ "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed" ], "inputs": [ { "previous_output": { "index": "0x0", "tx_hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17" }, "since": "0x0" } ], "outputs": [ { "capacity": "0x2540be400", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [] } ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "cycles": "0x219" } }

Method calculate_dao_maximum_withdraw

Calculates the maximum withdrawal one can get, given a referenced DAO cell, and a withdrawing block hash.

Params

option 1, the assumed reference block hash for withdrawing phase 1 transaction, this block must be in the canonical chain, the calculation of occupied capacity will be based on the depositing transaction’s output, assuming the output of phase 1 transaction is the same as the depositing transaction’s output.

option 2, the out point of the withdrawing phase 1 transaction, the calculation of occupied capacity will be based on corresponding phase 1 transaction’s output.

Returns

The RPC returns the final capacity when the cell out_point is withdrawn using the block hash or withdrawing phase 1 transaction out point as the reference.

In CKB, scripts cannot get the information about in which block the transaction is committed. A workaround is letting the transaction reference a block hash so the script knows that the transaction is committed at least after the reference block.

Errors
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "calculate_dao_maximum_withdraw", "params": [ { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" }, "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0x4a8b4e8a4" }

Module Indexer

RPC Module Indexer.

Method get_indexer_tip

Returns the indexed tip

Returns
Examples

Request

{ "id": 2, "jsonrpc": "2.0", "method": "get_indexer_tip" }

Response

{ "jsonrpc": "2.0", "result": { "block_hash": "0x4959d6e764a2edc6038dbf03d61ebcc99371115627b186fdcccb2161fbd26edc", "block_number": "0x5b513e" }, "id": 2 }

Method get_cells

Returns the live cells collection by the lock or type script.

Params
Returns
Examples

Request

{ "id": 2, "jsonrpc": "2.0", "method": "get_cells", "params": [ { "script": { "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223" }, "script_type": "lock" }, "asc", "0x64" ] }

Response

{ "jsonrpc": "2.0", "result": { "last_cursor": "0x409bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8015989ae415bb667931a99896e5fbbfad9ba53a22300000000005b0f8c0000000100000000", "objects": [ { "block_number": "0x5b0e6d", "out_point": { "index": "0x0", "tx_hash": "0xe8f2180dfba0cb15b45f771d520834515a5f8d7aa07f88894da88c22629b79e9" }, "output": { "capacity": "0x189640200", "lock": { "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223", "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type" }, "type": null }, "output_data": "0x", "tx_index": "0x1" }, { "block_number": "0x5b0e90", "out_point": { "index": "0x0", "tx_hash": "0xece3a27409bde2914fb7a1555d6bfca453ee46af73e665149ef549fd46ec1fc6" }, "output": { "capacity": "0x189640200", "lock": { "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223", "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type" }, "type": null }, "output_data": "0x", "tx_index": "0x1" }, { "block_number": "0x5b0ead", "out_point": { "index": "0x1", "tx_hash": "0x5c48768f91e3795b418c53211c76fd038c464a24c4aa7e35bbbb6ac5b219f581" }, "output": { "capacity": "0xe36dceec20", "lock": { "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223", "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type" }, "type": null }, "output_data": "0x", "tx_index": "0x1" }, { "block_number": "0x5b0eeb", "out_point": { "index": "0x0", "tx_hash": "0x90e6981d6a5692d92e54344dc0e12d213447710fa069cc19ddea874619b9ba48" }, "output": { "capacity": "0x174876e800", "lock": { "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223", "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type" }, "type": null }, "output_data": "0x", "tx_index": "0x1" }, { "block_number": "0x5b0f8c", "out_point": { "index": "0x0", "tx_hash": "0x9ea14510219ae97afa0275215fa77c3c015905281c953a3917a7fd036767429c" }, "output": { "capacity": "0x189640200", "lock": { "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223", "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type" }, "type": null }, "output_data": "0x", "tx_index": "0x1" } ] }, "id": 2 }

Request

{ "id": 2, "jsonrpc": "2.0", "method": "get_cells", "params": [ { "script": { "code_hash": "0x58c5f491aba6d61678b7cf7edf4910b1f5e00ec0cde2f42e0abb4fd9aff25a63", "hash_type": "type", "args": "0x2a49720e721553d0614dff29454ee4e1f07d0707" }, "script_type": "lock", "filter": { "script": { "code_hash": "0xc5e5dcf215925f7ef4dfaf5f4b4f105bc321c02776d6e7d52a1db3fcd9d011a4", "hash_type": "type", "args": "0x8462b20277bcbaa30d821790b852fb322d55c2b12e750ea91ad7059bc98dda4b" } } }, "asc", "0x64" ] }

Response

{ "jsonrpc": "2.0", "result": { "last_cursor": "0x4058c5f491aba6d61678b7cf7edf4910b1f5e00ec0cde2f42e0abb4fd9aff25a63012a49720e721553d0614dff29454ee4e1f07d070700000000002adf870000000100000001", "objects": [ { "block_number": "0x2adf87", "out_point": { "index": "0x1", "tx_hash": "0x04ecbc2df39e3682326a3b23c1bd2465e07eae2379ac0cc713834a1f79753779" }, "output": { "capacity": "0x436d81500", "lock": { "args": "0x2a49720e721553d0614dff29454ee4e1f07d0707", "code_hash": "0x58c5f491aba6d61678b7cf7edf4910b1f5e00ec0cde2f42e0abb4fd9aff25a63", "hash_type": "type" }, "type": { "args": "0x8462b20277bcbaa30d821790b852fb322d55c2b12e750ea91ad7059bc98dda4b", "code_hash": "0xc5e5dcf215925f7ef4dfaf5f4b4f105bc321c02776d6e7d52a1db3fcd9d011a4", "hash_type": "type" } }, "output_data": "0x0040d20853d746000000000000000000", "tx_index": "0x1" } ] }, "id": 2 }

Request

{ "id": 2, "jsonrpc": "2.0", "method": "get_cells", "params": [ { "script": { "code_hash": "0x58c5f491aba6d61678b7cf7edf4910b1f5e00ec0cde2f42e0abb4fd9aff25a63", "hash_type": "type", "args": "0x2a49720e721553d0614dff29454ee4e1f07d0707" }, "script_type": "lock", "filter": { "script_len_range": ["0x0", "0x1"] } }, "asc", "0x64" ] }

Response

{ "jsonrpc": "2.0", "result": { "last_cursor": "0x4058c5f491aba6d61678b7cf7edf4910b1f5e00ec0cde2f42e0abb4fd9aff25a63012a49720e721553d0614dff29454ee4e1f07d070700000000002adf830000000200000001", "objects": [ { "block_number": "0x2adf83", "out_point": { "index": "0x1", "tx_hash": "0x23ec897027c1d2a2b39e2446162bac182f18581be048cb3896ad695559b6839e" }, "output": { "capacity": "0x54b42b70b4", "lock": { "args": "0x2a49720e721553d0614dff29454ee4e1f07d0707", "code_hash": "0x58c5f491aba6d61678b7cf7edf4910b1f5e00ec0cde2f42e0abb4fd9aff25a63", "hash_type": "type" }, "type": null }, "output_data": "0x", "tx_index": "0x2" } ] }, "id": 2 }

Request

{ "id": 2, "jsonrpc": "2.0", "method": "get_cells", "params": [ { "script": { "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223" }, "script_type": "lock", "filter": { "output_capacity_range": ["0x0", "0x174876e801"] } }, "asc", "0x64" ] }

Response

{ "jsonrpc": "2.0", "result": { "last_cursor": "0x409bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8015989ae415bb667931a99896e5fbbfad9ba53a22300000000005b59df0000000100000001", "objects": [ { "block_number": "0x5b59df", "out_point": { "index": "0x1", "tx_hash": "0x21c4632a41140b828e9347ff80480b3e07be4e0a0b8d577565e7421fd5473194" }, "output": { "capacity": "0xe815b81c0", "lock": { "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223", "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type" }, "type": null }, "output_data": "0x", "tx_index": "0x1" } ] }, "id": 2 }

Method get_transactions

Returns the transactions collection by the lock or type script.

Returns
Examples

Request

{ "id": 2, "jsonrpc": "2.0", "method": "get_transactions", "params": [ { "script": { "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223" }, "script_type": "lock" }, "asc", "0x64" ] }

Response

{ "jsonrpc": "2.0", "result": { "last_cursor": "0x809bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8015989ae415bb667931a99896e5fbbfad9ba53a22300000000005b59df000000010000000101", "objects": [ { "block_number": "0x5b033a", "io_index": "0x0", "io_type": "output", "tx_hash": "0x556060b62d16386da53f8a4b458314dfa2d1988a7bcc5c96c3bb2a350a3453a1", "tx_index": "0x4" }, { "block_number": "0x5b0671", "io_index": "0x0", "io_type": "input", "tx_hash": "0x8205b2b4cd6380d7e332c7a5b49bf776a0322ba19f46dc6ca1f8c59f7daee08d", "tx_index": "0x1" }, { "block_number": "0x5b0671", "io_index": "0x1", "io_type": "output", "tx_hash": "0x8205b2b4cd6380d7e332c7a5b49bf776a0322ba19f46dc6ca1f8c59f7daee08d", "tx_index": "0x1" }, { "block_number": "0x5b0e6d", "io_index": "0x0", "io_type": "output", "tx_hash": "0xe8f2180dfba0cb15b45f771d520834515a5f8d7aa07f88894da88c22629b79e9", "tx_index": "0x1" }, { "block_number": "0x5b0e90", "io_index": "0x0", "io_type": "output", "tx_hash": "0xece3a27409bde2914fb7a1555d6bfca453ee46af73e665149ef549fd46ec1fc6", "tx_index": "0x1" }, { "block_number": "0x5b0ead", "io_index": "0x0", "io_type": "input", "tx_hash": "0x5c48768f91e3795b418c53211c76fd038c464a24c4aa7e35bbbb6ac5b219f581", "tx_index": "0x1" }, { "block_number": "0x5b0ead", "io_index": "0x1", "io_type": "output", "tx_hash": "0x5c48768f91e3795b418c53211c76fd038c464a24c4aa7e35bbbb6ac5b219f581", "tx_index": "0x1" }, { "block_number": "0x5b0eeb", "io_index": "0x0", "io_type": "output", "tx_hash": "0x90e6981d6a5692d92e54344dc0e12d213447710fa069cc19ddea874619b9ba48", "tx_index": "0x1" }, { "block_number": "0x5b0f8c", "io_index": "0x0", "io_type": "output", "tx_hash": "0x9ea14510219ae97afa0275215fa77c3c015905281c953a3917a7fd036767429c", "tx_index": "0x1" }, { "block_number": "0x5b5638", "io_index": "0x0", "io_type": "input", "tx_hash": "0x9346da4caa846cc035c182ecad0c17326a587983d25fb1e12a388f1a9c5c56b4", "tx_index": "0x1" }, { "block_number": "0x5b5638", "io_index": "0x1", "io_type": "input", "tx_hash": "0x9346da4caa846cc035c182ecad0c17326a587983d25fb1e12a388f1a9c5c56b4", "tx_index": "0x1" }, { "block_number": "0x5b5638", "io_index": "0x1", "io_type": "output", "tx_hash": "0x9346da4caa846cc035c182ecad0c17326a587983d25fb1e12a388f1a9c5c56b4", "tx_index": "0x1" }, { "block_number": "0x5b5638", "io_index": "0x2", "io_type": "input", "tx_hash": "0x9346da4caa846cc035c182ecad0c17326a587983d25fb1e12a388f1a9c5c56b4", "tx_index": "0x1" }, { "block_number": "0x5b59c2", "io_index": "0x0", "io_type": "input", "tx_hash": "0x5b58f90fb3309333bf0bec878f3a05038c7fe816747300ecdac37a9da76c4128", "tx_index": "0x1" }, { "block_number": "0x5b59c2", "io_index": "0x1", "io_type": "output", "tx_hash": "0x5b58f90fb3309333bf0bec878f3a05038c7fe816747300ecdac37a9da76c4128", "tx_index": "0x1" }, { "block_number": "0x5b59cc", "io_index": "0x0", "io_type": "input", "tx_hash": "0x57ca2822c28e02b199424a731b2efd2c9bf752f07b7309f555f2e71abe83ba26", "tx_index": "0x1" }, { "block_number": "0x5b59cc", "io_index": "0x1", "io_type": "input", "tx_hash": "0x57ca2822c28e02b199424a731b2efd2c9bf752f07b7309f555f2e71abe83ba26", "tx_index": "0x1" }, { "block_number": "0x5b59cc", "io_index": "0x1", "io_type": "output", "tx_hash": "0x57ca2822c28e02b199424a731b2efd2c9bf752f07b7309f555f2e71abe83ba26", "tx_index": "0x1" }, { "block_number": "0x5b59df", "io_index": "0x0", "io_type": "input", "tx_hash": "0x21c4632a41140b828e9347ff80480b3e07be4e0a0b8d577565e7421fd5473194", "tx_index": "0x1" }, { "block_number": "0x5b59df", "io_index": "0x1", "io_type": "output", "tx_hash": "0x21c4632a41140b828e9347ff80480b3e07be4e0a0b8d577565e7421fd5473194", "tx_index": "0x1" } ] }, "id": 2 }

Request

{ "id": 2, "jsonrpc": "2.0", "method": "get_transactions", "params": [ { "script": { "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223" }, "script_type": "lock", "group_by_transaction": true }, "asc", "0x64" ] }

Response

{ "jsonrpc": "2.0", "result": { "last_cursor": "0x809bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8015989ae415bb667931a99896e5fbbfad9ba53a22300000000005b59df000000010000000101", "objects": [ { "block_number": "0x5b033a", "cells": [ [ "output", "0x0" ] ], "tx_hash": "0x556060b62d16386da53f8a4b458314dfa2d1988a7bcc5c96c3bb2a350a3453a1", "tx_index": "0x4" }, { "block_number": "0x5b0671", "cells": [ [ "input", "0x0" ], [ "output", "0x1" ] ], "tx_hash": "0x8205b2b4cd6380d7e332c7a5b49bf776a0322ba19f46dc6ca1f8c59f7daee08d", "tx_index": "0x1" }, { "block_number": "0x5b0e6d", "cells": [ [ "output", "0x0" ] ], "tx_hash": "0xe8f2180dfba0cb15b45f771d520834515a5f8d7aa07f88894da88c22629b79e9", "tx_index": "0x1" }, { "block_number": "0x5b0e90", "cells": [ [ "output", "0x0" ] ], "tx_hash": "0xece3a27409bde2914fb7a1555d6bfca453ee46af73e665149ef549fd46ec1fc6", "tx_index": "0x1" }, { "block_number": "0x5b0ead", "cells": [ [ "input", "0x0" ], [ "output", "0x1" ] ], "tx_hash": "0x5c48768f91e3795b418c53211c76fd038c464a24c4aa7e35bbbb6ac5b219f581", "tx_index": "0x1" }, { "block_number": "0x5b0eeb", "cells": [ [ "output", "0x0" ] ], "tx_hash": "0x90e6981d6a5692d92e54344dc0e12d213447710fa069cc19ddea874619b9ba48", "tx_index": "0x1" }, { "block_number": "0x5b0f8c", "cells": [ [ "output", "0x0" ] ], "tx_hash": "0x9ea14510219ae97afa0275215fa77c3c015905281c953a3917a7fd036767429c", "tx_index": "0x1" }, { "block_number": "0x5b5638", "cells": [ [ "input", "0x0" ], [ "input", "0x1" ], [ "output", "0x1" ], [ "input", "0x2" ] ], "tx_hash": "0x9346da4caa846cc035c182ecad0c17326a587983d25fb1e12a388f1a9c5c56b4", "tx_index": "0x1" }, { "block_number": "0x5b59c2", "cells": [ [ "input", "0x0" ], [ "output", "0x1" ] ], "tx_hash": "0x5b58f90fb3309333bf0bec878f3a05038c7fe816747300ecdac37a9da76c4128", "tx_index": "0x1" }, { "block_number": "0x5b59cc", "cells": [ [ "input", "0x0" ], [ "input", "0x1" ], [ "output", "0x1" ] ], "tx_hash": "0x57ca2822c28e02b199424a731b2efd2c9bf752f07b7309f555f2e71abe83ba26", "tx_index": "0x1" }, { "block_number": "0x5b59df", "cells": [ [ "input", "0x0" ], [ "output", "0x1" ] ], "tx_hash": "0x21c4632a41140b828e9347ff80480b3e07be4e0a0b8d577565e7421fd5473194", "tx_index": "0x1" } ] }, "id": 2 }

Method get_cells_capacity

Returns the live cells capacity by the lock or type script.

Parameters
Returns
Examples

Request

{ "id": 2, "jsonrpc": "2.0", "method": "get_cells_capacity", "params": [ { "script": { "code_hash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8", "hash_type": "type", "args": "0x5989ae415bb667931a99896e5fbbfad9ba53a223" }, "script_type": "lock" } ] }

Response

{ "jsonrpc": "2.0", "result": { "block_hash": "0xbc52444952dc5eb01a7826aaf6bb1b660db01797414e259e7a6e6d636de8fc7c", "block_number": "0x5b727a", "capacity": "0xf0e8e4b4a0" }, "id": 2 }

Module IntegrationTest

RPC for Integration Test.

Method process_block_without_verify

process block without any block verification.

Params

* data - block data(in binary).

* broadcast - true to enable broadcast(relay) the block to other peers.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "process_block_without_verify", "params": [ { "header": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b117", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version": "0x0" }, "proposals": [], "transactions": [{ "cell_deps": [], "header_deps": [], "inputs": [{ "previous_output": { "index": "0xffffffff", "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "since": "0x400" }], "outputs": [{ "capacity": "0x18e64b61cf", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null }], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [ "0x450000000c000000410000003500000010000000300000003100000028e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5000000000000000000" ] }], "uncles": [] }, true ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "error": null }

Method truncate

Truncate chain to specified tip hash, can only truncate less then 50000 blocks each time.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "truncate", "params": [ "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

Method generate_block

Generate block with blockassemblerconfig, process the block(with verification)

and broadcast the block.

Params

* block_assembler_script - specified block assembler script

* block_assembler_message - specified block assembler message

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "generate_block", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0x60dd3fa0e81db3ee3ad41cf4ab956eae7e89eb71cd935101c26c4d0652db3029", "error": null }

Method notify_transaction

Add transaction to tx-pool.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "notify_transaction", "params": [ { "cell_deps": [{ "dep_type": "code", "out_point": { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" } }], "header_deps": [ "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed" ], "inputs": [{ "previous_output": { "index": "0x0", "tx_hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17" }, "since": "0x0" }], "outputs": [{ "capacity": "0x2540be400", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null }], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [] } ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3", "error": null }

Method generate_block_with_template

Generate block with block template, attach calculated dao field to build new block,

then process block and broadcast the block.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "generate_block_with_template", "params": [ { "bytes_limit": "0x91c08", "cellbase": { "cycles": null, "data": { "cell_deps": [], "header_deps": [], "inputs": [ { "previous_output": { "index": "0xffffffff", "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "since": "0x401" } ], "outputs": [ { "capacity": "0x18e64efc04", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [ "0x650000000c00000055000000490000001000000030000000310000001892ea40d82b53c678ff88312450bbb17e164d7a3e0a90941aa58839f56f8df20114000000b2e61ff569acf041b3c2c17724e2379c581eeac30c00000054455354206d657373616765" ] }, "hash": "0xbaf7e4db2fd002f19a597ca1a31dfe8cfe26ed8cebc91f52b75b16a7a5ec8bab" }, "compact_target": "0x1e083126", "current_time": "0x174c45e17a3", "cycles_limit": "0xd09dc300", "dao": "0xd495a106684401001e47c0ae1d5930009449d26e32380000000721efd0030000", "epoch": "0x7080019000001", "extension": null, "number": "0x401", "parent_hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "proposals": ["0xa0ef4eb5f4ceeb08a4c8"], "transactions": [], "uncles": [ { "hash": "0xdca341a42890536551f99357612cef7148ed471e3b6419d0844a4e400be6ee94", "header": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b118", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version":"0x0" }, "proposals": [], "required": false } ], "uncles_count_limit": "0x2", "version": "0x0", "work_id": "0x0" } ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0x899541646ae412a99fdbefc081e1a782605a7815998a096af16e51d4df352c75", "error": null }

Method calculate_dao_field

Return calculated dao field according to specified block template.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "calculate_dao_field", "params": [ { "bytes_limit": "0x91c08", "cellbase": { "cycles": null, "data": { "cell_deps": [], "header_deps": [], "inputs": [ { "previous_output": { "index": "0xffffffff", "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "since": "0x401" } ], "outputs": [ { "capacity": "0x18e64efc04", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [ "0x650000000c00000055000000490000001000000030000000310000001892ea40d82b53c678ff88312450bbb17e164d7a3e0a90941aa58839f56f8df20114000000b2e61ff569acf041b3c2c17724e2379c581eeac30c00000054455354206d657373616765" ] }, "hash": "0xbaf7e4db2fd002f19a597ca1a31dfe8cfe26ed8cebc91f52b75b16a7a5ec8bab" }, "compact_target": "0x1e083126", "current_time": "0x174c45e17a3", "cycles_limit": "0xd09dc300", "dao": "0xd495a106684401001e47c0ae1d5930009449d26e32380000000721efd0030000", "epoch": "0x7080019000001", "extension": null, "number": "0x401", "parent_hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "proposals": ["0xa0ef4eb5f4ceeb08a4c8"], "transactions": [], "uncles": [ { "hash": "0xdca341a42890536551f99357612cef7148ed471e3b6419d0844a4e400be6ee94", "header": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b118", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version":"0x0" }, "proposals": [], "required": false } ], "uncles_count_limit": "0x2", "version": "0x0", "work_id": "0x0" } ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0xd495a106684401001e47c0ae1d5930009449d26e32380000000721efd0030000", "error": null }

Module Miner

RPC Module Miner for miners.

A miner gets a template from CKB, optionally selects transactions, resolves the PoW puzzle, and submits the found new block.

Method get_block_template

Returns block template for miners.

Miners can assemble the new block from the template. The RPC is designed to allow miners to remove transactions and adding new transactions to the block.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_block_template", "params": [ null, null, null ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "bytes_limit": "0x91c08", "cellbase": { "cycles": null, "data": { "cell_deps": [], "header_deps": [], "inputs": [ { "previous_output": { "index": "0xffffffff", "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "since": "0x401" } ], "outputs": [ { "capacity": "0x18e64efc04", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [ "0x6a0000000c00000055000000490000001000000030000000310000001892ea40d82b53c678ff88312450bbb17e164d7a3e0a90941aa58839f56f8df20114000000b2e61ff569acf041b3c2c17724e2379c581eeac311000000000000002054455354206d657373616765" ] }, "hash": "0xbaf7e4db2fd002f19a597ca1a31dfe8cfe26ed8cebc91f52b75b16a7a5ec8bab" }, "compact_target": "0x1e083126", "current_time": "0x174c45e17a3", "cycles_limit": "0xd09dc300", "dao": "0xd495a106684401001e47c0ae1d5930009449d26e32380000000721efd0030000", "epoch": "0x7080019000001", "extension": null, "number": "0x401", "parent_hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "proposals": ["0xa0ef4eb5f4ceeb08a4c8"], "transactions": [], "uncles": [ { "hash": "0xdca341a42890536551f99357612cef7148ed471e3b6419d0844a4e400be6ee94", "header": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b118", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version":"0x0" }, "proposals": [], "required": false } ], "uncles_count_limit": "0x2", "version": "0x0", "work_id": "0x0" } }

Method submit_block

Submit new block to the network.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "submit_block", "params": [ "example", { "header": { "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b117", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "version": "0x0" }, "proposals": [], "transactions": [ { "cell_deps": [], "header_deps": [], "inputs": [ { "previous_output": { "index": "0xffffffff", "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "since": "0x400" } ], "outputs": [ { "capacity": "0x18e64b61cf", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [ "0x450000000c000000410000003500000010000000300000003100000028e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5000000000000000000" ] } ], "uncles": [] } ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40" }

Module Net

RPC Module Net for P2P network.

Method local_node_info

Returns the local node information.

The local node means the node itself which is serving the RPC.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "local_node_info", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "active": true, "addresses": [ { "address": "/ip4/192.168.0.2/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS", "score": "0xff" }, { "address": "/ip4/0.0.0.0/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS", "score": "0x1" } ], "connections": "0xb", "node_id": "QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS", "protocols": [ { "id": "0x0", "name": "/ckb/ping", "support_versions": [ "0.0.1" ] }, { "id": "0x1", "name": "/ckb/discovery", "support_versions": [ "0.0.1" ] } ], "version": "0.34.0 (f37f598 2020-07-17)" } }

Method get_peers

Returns the connected peers’ information.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_peers", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": [ { "addresses": [ { "address": "/ip6/::ffff:18.185.102.19/tcp/8115/p2p/QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN", "score": "0x64" }, { "address": "/ip4/18.185.102.19/tcp/8115/p2p/QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN", "score": "0x64" } ], "connected_duration": "0x2f", "is_outbound": true, "last_ping_duration": "0x1a", "node_id": "QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN", "protocols": [ { "id": "0x4", "version": "0.0.1" }, { "id": "0x2", "version": "0.0.1" }, { "id": "0x1", "version": "0.0.1" }, { "id": "0x64", "version": "1" }, { "id": "0x6e", "version": "1" }, { "id": "0x66", "version": "1" }, { "id": "0x65", "version": "1" }, { "id": "0x0", "version": "0.0.1" } ], "sync_state": { "best_known_header_hash": null, "best_known_header_number": null, "can_fetch_count": "0x80", "inflight_count": "0xa", "last_common_header_hash": null, "last_common_header_number": null, "unknown_header_list_size": "0x20" }, "version": "0.34.0 (f37f598 2020-07-17)" }, { "addresses": [ { "address": "/ip4/174.80.182.60/tcp/52965/p2p/QmVTMd7SEXfxS5p4EEM5ykTe1DwWWVewEM3NwjLY242vr2", "score": "0x1" } ], "connected_duration": "0x95", "is_outbound": true, "last_ping_duration": "0x41", "node_id": "QmSrkzhdBMmfCGx8tQGwgXxzBg8kLtX8qMcqECMuKWsxDV", "protocols": [ { "id": "0x0", "version": "0.0.1" }, { "id": "0x2", "version": "0.0.1" }, { "id": "0x6e", "version": "1" }, { "id": "0x66", "version": "1" }, { "id": "0x1", "version": "0.0.1" }, { "id": "0x65", "version": "1" }, { "id": "0x64", "version": "1" }, { "id": "0x4", "version": "0.0.1" } ], "sync_state": { "best_known_header_hash": "0x2157c72b3eddd41a7a14c361173cd22ef27d7e0a29eda2e511ee0b3598c0b895", "best_known_header_number": "0xdb835", "can_fetch_count": "0x80", "inflight_count": "0xa", "last_common_header_hash": "0xc63026bd881d880bb142c855dc8153187543245f0a94391c831c75df31f263c4", "last_common_header_number": "0x4dc08", "unknown_header_list_size": "0x1f" }, "version": "0.30.1 (5cc1b75 2020-03-23)" } ] }

Method get_banned_addresses

Returns all banned IPs/Subnets.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_banned_addresses", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": [ { "address": "192.168.0.2/32", "ban_reason": "", "ban_until": "0x1ac89236180", "created_at": "0x16bde533338" } ] }

Method clear_banned_addresses

Clears all banned IPs/Subnets.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "clear_banned_addresses", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

Method set_ban

Inserts or deletes an IP/Subnet from the banned list

Params
Errors
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "set_ban", "params": [ "192.168.0.2", "insert", "0x1ac89236180", true, "set_ban example" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

Method sync_state

Returns chain synchronization state of this node.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "sync_state", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "best_known_block_number": "0x400", "best_known_block_timestamp": "0x5cd2b117", "fast_time": "0x3e8", "ibd": true, "inflight_blocks_count": "0x0", "low_time": "0x5dc", "normal_time": "0x4e2", "orphan_blocks_count": "0x0" } }

Method set_network_active

Disable/enable all p2p network activity

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "set_network_active", "params": [ false ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

Method add_node

Attempts to add a node to the peers list and try connecting to it.

Params

The full P2P address is usually displayed as address/peer_id, for example in the log

2020-09-16 15:31:35.191 +08:00 NetworkRuntime INFO ckb_network::network Listen on address: /ip4/192.168.2.100/tcp/8114/QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS

And in RPC local_node_info:

{ "addresses": [ { "address": "/ip4/192.168.2.100/tcp/8114/QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS", "score": "0xff" } ] }

In both of these examples,

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "add_node", "params": [ "QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS", "/ip4/192.168.2.100/tcp/8114" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

Method remove_node

Attempts to remove a node from the peers list and try disconnecting from it.

Params

This is the last part of a full P2P address. For example, in address “/ip4/192.168.2.100/tcp/8114/QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS”, the peer_id is QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "remove_node", "params": [ "QmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

Method ping_peers

Requests that a ping is sent to all connected peers, to measure ping time.

Examples

Requests

{ "id": 42, "jsonrpc": "2.0", "method": "ping_peers", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

Module Pool

RPC Module Pool for transaction memory pool.

Method send_transaction

Submits a new transaction into the transaction pool. If the transaction is already in the pool, rebroadcast it to peers.

Params
Errors
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "send_transaction", "params": [ { "cell_deps": [ { "dep_type": "code", "out_point": { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" } } ], "header_deps": [ "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed" ], "inputs": [ { "previous_output": { "index": "0x0", "tx_hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17" }, "since": "0x0" } ], "outputs": [ { "capacity": "0x2540be400", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [] }, "passthrough" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3" }

Method remove_transaction

Removes a transaction and all transactions which depends on it from tx pool if it exists.

Params
Returns

If the transaction exists, return true; otherwise, return false.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "remove_transaction", "params": [ "0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": true }

Method tx_pool_info

Returns the transaction pool information.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "tx_pool_info", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "last_txs_updated_at": "0x0", "min_fee_rate": "0x3e8", "max_tx_pool_size": "0xaba9500", "orphan": "0x0", "pending": "0x1", "proposed": "0x0", "tip_hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "tip_number": "0x400", "total_tx_cycles": "0x219", "total_tx_size": "0x112", "tx_size_limit": "0x7d000" } }

Method clear_tx_pool

Removes all transactions from the transaction pool.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "clear_tx_pool", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": null }

Method get_raw_tx_pool

Returns all transaction ids in tx pool as a json array of string transaction ids.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_raw_tx_pool", "params": [true] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "pending": { "0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3": { "cycles": "0x219", "size": "0x112", "fee": "0x16923f7dcf", "ancestors_size": "0x112", "ancestors_cycles": "0x219", "ancestors_count": "0x1", "timestamp": "0x17c983e6e44" } }, "proposed": {} } }

Method tx_pool_ready

Returns whether tx-pool service is started, ready for request.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "tx_pool_ready", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": true }

Module Stats

RPC Module Stats for getting various statistic data.

Method get_blockchain_info

Returns statistics about the chain.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_blockchain_info", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "alerts": [ { "id": "0x2a", "message": "An example alert message!", "notice_until": "0x24bcca57c00", "priority": "0x1" } ], "chain": "ckb", "difficulty": "0x1f4003", "epoch": "0x7080018000001", "is_initial_block_download": true, "median_time": "0x5cd2b105" } }

Method get_deployments_info

Returns statistics about the chain.

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "get_deployments_info", "params": [] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": { "epoch": "0x1", "hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "deployments": { "testdummy": { "bit": 1, "min_activation_epoch": "0x0", "period": "0xa", "since": "0x0", "start": "0x0", "state": "failed", "timeout": "0x0", "threshold": { "numer": "0x3", "denom": "0x4" } } } } }

Module Subscription

RPC Module Subscription that CKB node will push new messages to subscribers.

RPC subscriptions require a full duplex connection. CKB offers such connections in the form of TCP (enable with rpc.tcplistenaddress configuration option) and WebSocket (enable with rpc.wslistenaddress).

Examples

TCP RPC subscription:

``` telnet localhost 18114

{"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["newtipheader"]} < {"jsonrpc":"2.0","result":"0x0","id":2} < {"jsonrpc":"2.0","method":"subscribe","params":{"result":"...block header json...", "subscription":0}} < {"jsonrpc":"2.0","method":"subscribe","params":{"result":"...block header json...", "subscription":0}} < ... {"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]} < {"jsonrpc":"2.0","result":true,"id":2} ```

WebSocket RPC subscription:

``` let socket = new WebSocket("ws://localhost:28114")

socket.onmessage = function(event) { console.log(Data received from server: ${event.data}); }

socket.send({"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["new_tip_header"]})

socket.send({"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]}) ```

Method subscribe

Subscribes to a topic.

Params
Returns

This RPC returns the subscription ID as the result. CKB node will push messages in the subscribed topics to the current RPC connection. The subscript ID is also attached as params.subscription in the push messages.

Example push message:

{ "jsonrpc": "2.0", "method": "subscribe", "params": { "result": { ... }, "subscription": "0x2a" } }

Topics
new_tip_header

Whenever there’s a block that is appended to the canonical chain, the CKB node will publish the block header to subscribers.

The type of the params.result in the push message is HeaderView.

new_tip_block

Whenever there’s a block that is appended to the canonical chain, the CKB node will publish the whole block to subscribers.

The type of the params.result in the push message is BlockView.

new_transaction

Subscribers will get notified when a new transaction is submitted to the pool.

The type of the params.result in the push message is PoolTransactionEntry.

proposed_transaction

Subscribers will get notified when an in-pool transaction is proposed by chain.

The type of the params.result in the push message is PoolTransactionEntry.

rejected_transaction

Subscribers will get notified when a pending transaction is rejected by tx-pool.

The type of the params.result in the push message is an array contain:

The type of the params.result in the push message is a two-elements array, where

Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "subscribe", "params": [ "new_tip_header" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": "0x2a" }

Method unsubscribe

Unsubscribes from a subscribed topic.

Params
Examples

Request

{ "id": 42, "jsonrpc": "2.0", "method": "unsubscribe", "params": [ "0x2a" ] }

Response

{ "id": 42, "jsonrpc": "2.0", "result": true }

RPC Errors

CKB RPC error codes.

CKB RPC follows the JSON RPC specification about the error object.

Besides the pre-defined errors, all CKB defined errors are listed here.

Here is a reference to the pre-defined errors:

| code | message | meaning | | --- |--- |--- | | -32700 | Parse error | Invalid JSON was received by the server. | | -32600 | Invalid Request | The JSON sent is not a valid Request object. | | -32601 | Method not found | The method does not exist / is not available. | | -32602 | Invalid params | Invalid method parameter(s). | | -32603 | Internal error | Internal JSON-RPC error. | | -32000 to -32099 | Server error | Reserved for implementation-defined server-errors. |

CKB application-defined errors follow some patterns to assign the codes:

Unless otherwise noted, all the errors return optional detailed information as string in the error object data field.

Error CKBInternalError

(-1): CKB internal errors are considered to never happen or only happen when the system resources are exhausted.

Error Deprecated

(-2): The CKB method has been deprecated and disabled.

Set rpc.enable_deprecated_rpc to true in the config file to enable all deprecated methods.

Error Invalid

(-3): Error code -3 is no longer used.

Before v0.35.0, CKB returns all RPC errors using the error code -3. CKB no longer uses -3 since v0.35.0.

Error RPCModuleIsDisabled

(-4): The RPC method is not enabled.

CKB groups RPC methods into modules, and a method is enabled only when the module is explicitly enabled in the config file.

Error DaoError

(-5): DAO related errors.

Error IntegerOverflow

(-6): Integer operation overflow.

Error ConfigError

(-7): The error is caused by a config file option.

Users have to edit the config file to fix the error.

Error P2PFailedToBroadcast

(-101): The CKB local node failed to broadcast a message to its peers.

Error DatabaseError

(-200): Internal database error.

The CKB node persists data to the database. This is the error from the underlying database module.

Error ChainIndexIsInconsistent

(-201): The chain index is inconsistent.

An example of an inconsistent index is that the chain index says a block hash is in the chain but the block cannot be read from the database.

This is a fatal error usually due to a serious bug. Please back up the data directory and re-sync the chain from scratch.

Error DatabaseIsCorrupt

(-202): The underlying database is corrupt.

This is a fatal error usually caused by the underlying database used by CKB. Please back up the data directory and re-sync the chain from scratch.

Error TransactionFailedToResolve

(-301): Failed to resolve the referenced cells and headers used in the transaction, as inputs or dependencies.

Error TransactionFailedToVerify

(-302): Failed to verify the transaction.

Error AlertFailedToVerifySignatures

(-1000): Some signatures in the submit alert are invalid.

Error PoolRejectedTransactionByOutputsValidator

(-1102): The transaction is rejected by the outputs validator specified by the RPC parameter.

Error PoolRejectedTransactionByIllTransactionChecker

(-1103): Pool rejects some transactions which seem contain invalid VM instructions. See the issue link in the error message for details.

Error PoolRejectedTransactionByMinFeeRate

(-1104): The transaction fee rate must be greater than or equal to the config option tx_pool.min_fee_rate

The fee rate is calculated as:

fee / (1000 * tx_serialization_size_in_block_in_bytes)

Error PoolRejectedTransactionByMaxAncestorsCountLimit

(-1105): The in-pool ancestors count must be less than or equal to the config option tx_pool.max_ancestors_count

Pool rejects a large package of chained transactions to avoid certain kinds of DoS attacks.

Error PoolIsFull

(-1106): The transaction is rejected because the pool has reached its limit.

Error PoolRejectedDuplicatedTransaction

(-1107): The transaction is already in the pool.

Error PoolRejectedMalformedTransaction

(-1108): The transaction is rejected because it does not make sense in the context.

For example, a cellbase transaction is not allowed in send_transaction RPC.

Error TransactionExpired

(-1109): The transaction is expired from tx-pool after expiry_hours.

Error PoolRejectedTransactionBySizeLimit

(-1110): The transaction exceeded maximum size limit.

Error Indexer

(-1200): The indexer error.

RPC Types

Type Alert

An alert is a message about critical problems to be broadcast to all nodes via the p2p network.

Examples

An example in JSON

{ "id": "0x1", "cancel": "0x0", "min_version": "0.1.0", "max_version": "1.0.0", "priority": "0x1", "message": "An example alert message!", "notice_until": "0x24bcca57c00", "signatures": [ "0xbd07059aa9a3d057da294c2c4d96fa1e67eeb089837c87b523f124239e18e9fc7d11bb95b720478f7f937d073517d0e4eb9a91d12da5c88a05f750362f4c214dd0", "0x0242ef40bb64fe3189284de91f981b17f4d740c5e24a3fc9b70059db6aa1d198a2e76da4f84ab37549880d116860976e0cf81cd039563c452412076ebffa2e4453" ] }

Fields

Alert is a JSON object with the following fields.

Type AlertId

The alert identifier that is used to filter duplicated alerts.

This is a 32-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint32.

Type AlertMessage

An alert sent by RPC send_alert.

Fields

AlertMessage is a JSON object with the following fields.

Type AlertPriority

Alerts are sorted by priority. Greater integers mean higher priorities.

This is a 32-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint32.

Type BannedAddr

A banned P2P address.

Fields

BannedAddr is a JSON object with the following fields.

Type Block

The JSON view of a Block used as a parameter in the RPC.

Fields

Block is a JSON object with the following fields.

Type BlockEconomicState

Block Economic State.

It includes the rewards details and when it is finalized.

Fields

BlockEconomicState is a JSON object with the following fields.

Type BlockFilter

Block filter data and hash.

Fields

BlockFilter is a JSON object with the following fields.

Type BlockIssuance

Block base rewards.

Fields

BlockIssuance is a JSON object with the following fields.

Type BlockNumber

Consecutive block number starting from 0.

This is a 64-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint64.

Type BlockResponse

The wrapper represent response of get_block | get_block_by_number, return a Block with cycles.

BlockResponse is equivalent to "regular" | "with_cycles".

Type BlockTemplate

A block template for miners.

Miners optional pick transactions and then assemble the final block.

Fields

BlockTemplate is a JSON object with the following fields.

Type BlockView

The JSON view of a Block including header and body.

Fields

BlockView is a JSON object with the following fields.

Type Byte32

The fixed-length 32 bytes binary encoded as a 0x-prefixed hex string in JSON.

Type Capacity

The capacity of a cell is the value of the cell in Shannons. It is also the upper limit of the cell occupied storage size where every 100,000,000 Shannons give 1-byte storage.

This is a 64-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint64.

Type CellData

The cell data content and hash.

Examples

{ "content": "0x7f454c460201010000000000000000000200f3000100000078000100000000004000000000000000980000000000000005000000400038000100400003000200010000000500000000000000000000000000010000000000000001000000000082000000000000008200000000000000001000000000000001459308d00573000000002e7368737472746162002e74657874000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000b000000010000000600000000000000780001000000000078000000000000000a0000000000000000000000000000000200000000000000000000000000000001000000030000000000000000000000000000000000000082000000000000001100000000000000000000000000000001000000000000000000000000000000", "hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5" }

Fields

CellData is a JSON object with the following fields.

Type CellDep

The cell dependency of a transaction.

Examples

{ "dep_type": "code", "out_point": { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" } }

Fields

CellDep is a JSON object with the following fields.

Type CellInfo

The JSON view of a cell combining the fields in cell output and cell data.

Examples

{ "data": { "content": "0x7f454c460201010000000000000000000200f3000100000078000100000000004000000000000000980000000000000005000000400038000100400003000200010000000500000000000000000000000000010000000000000001000000000082000000000000008200000000000000001000000000000001459308d00573000000002e7368737472746162002e74657874000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000b000000010000000600000000000000780001000000000078000000000000000a0000000000000000000000000000000200000000000000000000000000000001000000030000000000000000000000000000000000000082000000000000001100000000000000000000000000000001000000000000000000000000000000", "hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5" }, "output": { "capacity": "0x802665800", "lock": { "args": "0x", "code_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash_type": "data" }, "type": null } }

Fields

CellInfo is a JSON object with the following fields.

Type CellInput

The input cell of a transaction.

Examples

{ "previous_output": { "index": "0x0", "tx_hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17" }, "since": "0x0" }

Fields

CellInput is a JSON object with the following fields.

Type CellOutput

The fields of an output cell except the cell data.

Examples

{ "capacity": "0x2540be400", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null }

Fields

CellOutput is a JSON object with the following fields.

Type CellWithStatus

The JSON view of a cell with its status information.

Examples

{ "cell": { "data": { "content": "0x7f454c460201010000000000000000000200f3000100000078000100000000004000000000000000980000000000000005000000400038000100400003000200010000000500000000000000000000000000010000000000000001000000000082000000000000008200000000000000001000000000000001459308d00573000000002e7368737472746162002e74657874000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000b000000010000000600000000000000780001000000000078000000000000000a0000000000000000000000000000000200000000000000000000000000000001000000030000000000000000000000000000000000000082000000000000001100000000000000000000000000000001000000000000000000000000000000", "hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5" }, "output": { "capacity": "0x802665800", "lock": { "args": "0x", "code_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "hash_type": "data" }, "type": null } }, "status": "live" }

{ "cell": null, "status": "unknown" }

Fields

CellWithStatus is a JSON object with the following fields.

Type CellbaseTemplate

The cellbase transaction template of the new block for miners.

Fields

CellbaseTemplate is a JSON object with the following fields.

Type ChainInfo

Chain information.

Fields

ChainInfo is a JSON object with the following fields.

Type Consensus

Consensus defines various parameters that influence chain consensus

Fields

Consensus is a JSON object with the following fields.

Type Cycle

Count of cycles consumed by CKB VM to run scripts.

This is a 64-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint64.

Type DaoWithdrawingCalculationKind

An enum to represent the two kinds of dao withdrawal amount calculation option. DaoWithdrawingCalculationKind is equivalent to H256 | OutPoint.

DaoWithdrawingCalculationKind is equivalent to "withdrawing_header_hash" | "withdrawing_out_point".

Type DepType

The dep cell type. Allowed values: “code” and “dep_group”.

DepType is equivalent to "code" | "dep_group".

Type DeploymentInfo

An object containing various state info regarding deployments of consensus changes

Fields

DeploymentInfo is a JSON object with the following fields.

Type DeploymentPos

Deployment name

DeploymentPos is equivalent to "testdummy" | "light_client".

Type DeploymentState

The possible softfork deployment state

DeploymentState is equivalent to "defined" | "started" | "locked_in" | "active" | "failed".

Type DeploymentsInfo

Chain information.

Fields

DeploymentsInfo is a JSON object with the following fields.

Type Either

The enum Either with variants Left and Right is a general purpose sum type with two cases.

Either is equivalent to "left" | "right".

Type EpochNumber

Consecutive epoch number starting from 0.

This is a 64-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint64.

Type EpochNumberWithFraction

The epoch indicator of a block. It shows which epoch the block is in, and the elapsed epoch fraction after adding this block.

This is a 64-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint64.

The lower 56 bits of the epoch field are split into 3 parts (listed in the order from higher bits to lower bits):

Assume there’s a block, which number is 11555 and in epoch 50. The epoch 50 starts from block 11000 and have 1000 blocks. The epoch field for this particular block will then be 1,099,520,939,130,930, which is calculated in the following way:

50 | ((11555 - 11000) << 24) | (1000 << 40)

Type EpochView

JSON view of an epoch.

CKB adjusts difficulty based on epochs.

Examples

{ "compact_target": "0x1e083126", "length": "0x708", "number": "0x1", "start_number": "0x3e8" }

Fields

EpochView is a JSON object with the following fields.

Type EstimateCycles

Response result of the RPC method estimate_cycles.

Fields

EstimateCycles is a JSON object with the following fields.

Type FeeRateStatistics

The fee_rate statistics information, includes mean and median, unit: shannons per kilo-weight

Fields

FeeRateStatistics is a JSON object with the following fields.

Type H256

The 256-bit binary data encoded as a 0x-prefixed hex string in JSON.

Type HardForks

Hardfork information

Type Header

The block header.

Refer to RFC CKB Block Structure.

Fields

Header is a JSON object with the following fields.

Type HeaderView

The JSON view of a Header.

This structure is serialized into a JSON object with field hash and all the fields in Header.

Examples

{ "compact_target": "0x1e083126", "dao": "0xb5a3e047474401001bc476b9ee573000c0c387962a38000000febffacf030000", "epoch": "0x7080018000001", "hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40", "nonce": "0x0", "number": "0x400", "parent_hash": "0xae003585fa15309b30b31aed3dcf385e9472c3c3e93746a6c4540629a6a1ed2d", "proposals_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "timestamp": "0x5cd2b117", "transactions_root": "0xc47d5b78b3c4c4c853e2a32810818940d0ee403423bea9ec7b8e566d9595206c", "extra_hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "version": "0x0" }

Fields

HeaderView is a JSON object with the following fields.

Type IndexerCell

Live cell

Fields

IndexerCell is a JSON object with the following fields.

Type IndexerCellsCapacity

Cells capacity

Fields

IndexerCellsCapacity is a JSON object with the following fields.

Type IndexerOrder

Order Desc | Asc

IndexerOrder is equivalent to "desc" | "asc".

Type IndexerRange

A array represent (half-open) range bounded inclusively below and exclusively above [start, end).

Examples

| JSON | range | | --- |--- | | [“0x0”, “0x2”] | [0, 2) | | [“0x0”, “0x174876e801”] | [0, 100000000001) |

Type IndexerScriptSearchMode

IndexerScriptSearchMode represent script search mode, default is prefix search

IndexerScriptSearchMode is equivalent to "prefix" | "exact".

Type IndexerScriptType

ScriptType Lock | Type

IndexerScriptType is equivalent to "lock" | "type".

Type IndexerSearchKey

SearchKey represent indexer support params

Fields

IndexerSearchKey is a JSON object with the following fields.

Type IndexerSearchKeyFilter

IndexerSearchKeyFilter represent indexer params filter

Fields

IndexerSearchKeyFilter is a JSON object with the following fields.

Type IndexerTip

Indexer tip information

Fields

IndexerTip is a JSON object with the following fields.

Type IndexerTx

Indexer Transaction Object

IndexerTx is equivalent to "ungrouped" | "grouped".

Type JsonBytes

Variable-length binary encoded as a 0x-prefixed hex string in JSON.

Example

| JSON | Binary | | --- |--- | | “0x” | Empty binary | | “0x00” | Single byte 0 | | “0x636b62” | 3 bytes, UTF-8 encoding of ckb | | “00” | Invalid, 0x is required | | “0x0” | Invalid, each byte requires 2 digits |

Type LocalNode

The information of the node itself.

Examples

{ "active": true, "addresses": [ { "address": "/ip4/192.168.0.2/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS", "score": "0xff" }, { "address": "/ip4/0.0.0.0/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS", "score": "0x1" } ], "connections": "0xb", "node_id": "QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS", "protocols": [ { "id": "0x0", "name": "/ckb/ping", "support_versions": [ "0.0.1" ] }, { "id": "0x1", "name": "/ckb/discovery", "support_versions": [ "0.0.1" ] } ], "version": "0.34.0 (f37f598 2020-07-17)" }

Fields

LocalNode is a JSON object with the following fields.

Type LocalNodeProtocol

The information of a P2P protocol that is supported by the local node.

Fields

LocalNodeProtocol is a JSON object with the following fields.

Type MerkleProof

Proof of CKB Merkle Tree.

CKB Merkle Tree is a CBMT using CKB blake2b hash as the merge function.

Fields

MerkleProof is a JSON object with the following fields.

Type MinerReward

Block rewards for miners.

Fields

MinerReward is a JSON object with the following fields.

Type NodeAddress

Node P2P address and score.

Fields

NodeAddress is a JSON object with the following fields.

Type OutPoint

Reference to a cell via transaction hash and output index.

Examples

{ "index": "0x0", "tx_hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17" }

Fields

OutPoint is a JSON object with the following fields.

Type OutputsValidator

Transaction output validators that prevent common mistakes.

OutputsValidator is equivalent to "passthrough" | "well_known_scripts_only".

Type PeerSyncState

The chain synchronization state between the local node and a remote node.

Fields

PeerSyncState is a JSON object with the following fields.

Type PoolTransactionEntry

The transaction entry in the pool.

Fields

PoolTransactionEntry is a JSON object with the following fields.

Type PoolTransactionReject

TX reject message

PoolTransactionReject is a JSON object with following fields.

Different reject types:

Type ProposalShortId

The 10-byte fixed-length binary encoded as a 0x-prefixed hex string in JSON.

Example

0xa0ef4eb5f4ceeb08a4c8

Type ProposalWindow

Two protocol parameters closest and farthest define the closest and farthest on-chain distance between a transaction’s proposal and commitment.

A non-cellbase transaction is committed at height h_c if all of the following conditions are met:

ProposalWindow { closest: 2, farthest: 10 } propose \ \ 13 14 [15 16 17 18 19 20 21 22 23] \_______________________/ \ commit

Fields

ProposalWindow is a JSON object with the following fields.

Type Ratio

Represents the ratio numerator / denominator, where numerator and denominator are both unsigned 64-bit integers.

Fields

Ratio is a JSON object with the following fields.

Type RationalU256

The ratio which numerator and denominator are both 256-bit unsigned integers.

Example

{ "denom": "0x28", "numer": "0x1" }

Type RawTxPool

All transactions in tx-pool.

RawTxPool is equivalent to TxPoolIds | TxPoolEntries.

Type RemoteNode

Information of a remote node.

A remote node connects to the local node via the P2P network. It is often called a peer.

Examples

{ "addresses": [ { "address": "/ip6/::ffff:18.185.102.19/tcp/8115/p2p/QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN", "score": "0x64" }, { "address": "/ip4/18.185.102.19/tcp/8115/p2p/QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN", "score": "0x64" } ], "connected_duration": "0x2f", "is_outbound": true, "last_ping_duration": "0x1a", "node_id": "QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN", "protocols": [ { "id": "0x4", "version": "0.0.1" }, { "id": "0x2", "version": "0.0.1" }, { "id": "0x1", "version": "0.0.1" }, { "id": "0x64", "version": "1" }, { "id": "0x6e", "version": "1" }, { "id": "0x66", "version": "1" }, { "id": "0x65", "version": "1" }, { "id": "0x0", "version": "0.0.1" } ], "sync_state": { "best_known_header_hash": null, "best_known_header_number": null, "can_fetch_count": "0x80", "inflight_count": "0xa", "last_common_header_hash": null, "last_common_header_number": null, "unknown_header_list_size": "0x20" }, "version": "0.34.0 (f37f598 2020-07-17)" }

Fields

RemoteNode is a JSON object with the following fields.

Type RemoteNodeProtocol

The information about an active running protocol.

Fields

RemoteNodeProtocol is a JSON object with the following fields.

Type ResponseFormat

This is a wrapper for JSON serialization to select the format between Json and Hex.

Examples

ResponseFormat<BlockView> returns the block in its Json format or molecule serialized Hex format.

Fields

ResponseFormat is a JSON object with the following fields.

Type Script

Describes the lock script and type script for a cell.

Examples

{ "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }

Fields

Script is a JSON object with the following fields.

Type ScriptHashType

Specifies how the script code_hash is used to match the script code and how to run the code.

Allowed kinds: “data”, “type” and “data1”.

Refer to the section Code Locating and Upgradable Script in the RFC CKB Transaction Structure.

ScriptHashType is equivalent to "data" | "type" | "data1" | "data2".

Type SerializedBlock

This is a 0x-prefix hex string. It is the block serialized by molecule using the schema table Block.

Type SerializedHeader

This is a 0x-prefix hex string. It is the block header serialized by molecule using the schema table Header.

Type SoftFork

SoftFork information

SoftFork is equivalent to "buried" | "rfc0043".

Type Status

Status for transaction

Status is equivalent to "pending" | "proposed" | "committed" | "unknown" | "rejected".

Type SyncState

The overall chain synchronization state of this local node.

Fields

SyncState is a JSON object with the following fields.

Type Timestamp

The Unix timestamp in milliseconds (1 second is 1000 milliseconds).

For example, 1588233578000 is Thu, 30 Apr 2020 07:59:38 +0000

This is a 64-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint64.

Type Transaction

The transaction.

Refer to RFC CKB Transaction Structure.

Fields

Transaction is a JSON object with the following fields.

Type TransactionAndWitnessProof

Merkle proof for transactions’ witnesses in a block.

Fields

TransactionAndWitnessProof is a JSON object with the following fields.

Type TransactionProof

Merkle proof for transactions in a block.

Fields

TransactionProof is a JSON object with the following fields.

Type TransactionTemplate

Transaction template which is ready to be committed in the new block.

Fields

TransactionTemplate is a JSON object with the following fields.

Type TransactionView

The JSON view of a Transaction.

This structure is serialized into a JSON object with field hash and all the fields in Transaction.

Examples

{ "cell_deps": [ { "dep_type": "code", "out_point": { "index": "0x0", "tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3" } } ], "hash": "0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3", "header_deps": [ "0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed" ], "inputs": [ { "previous_output": { "index": "0x0", "tx_hash": "0x365698b50ca0da75dca2c87f9e7b563811d3b5813736b8cc62cc3b106faceb17" }, "since": "0x0" } ], "outputs": [ { "capacity": "0x2540be400", "lock": { "code_hash": "0x28e83a1277d48add8e72fadaa9248559e1b632bab2bd60b27955ebc4c03800a5", "hash_type": "data", "args": "0x" }, "type": null } ], "outputs_data": [ "0x" ], "version": "0x0", "witnesses": [] }

Fields

TransactionView is a JSON object with the following fields.

Type TransactionWithStatusResponse

The JSON view of a transaction as well as its status.

Fields

TransactionWithStatusResponse is a JSON object with the following fields.

Type TxPoolEntries

Tx-pool entries object

Fields

TxPoolEntries is a JSON object with the following fields.

Type TxPoolEntry

Transaction entry info

Fields

TxPoolEntry is a JSON object with the following fields.

Type TxPoolIds

Array of transaction ids

Fields

TxPoolIds is a JSON object with the following fields.

Type TxPoolInfo

Transaction pool information.

Fields

TxPoolInfo is a JSON object with the following fields.

Type TxStatus

Transaction status and the block hash if it is committed.

Fields

TxStatus is a JSON object with the following fields.

Type U256

The 256-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON.

Type Uint128

The 128-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON.

Examples

| JSON | Decimal Value | | --- |--- | | “0x0” | 0 | | “0x10” | 16 | | “10” | Invalid, 0x is required | | “0x01” | Invalid, redundant leading 0 |

Type Uint32

The 32-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON.

Examples

| JSON | Decimal Value | | --- |--- | | “0x0” | 0 | | “0x10” | 16 | | “10” | Invalid, 0x is required | | “0x01” | Invalid, redundant leading 0 |

Type Uint64

The 64-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON.

Examples

| JSON | Decimal Value | | --- |--- | | “0x0” | 0 | | “0x10” | 16 | | “10” | Invalid, 0x is required | | “0x01” | Invalid, redundant leading 0 |

Type UncleBlock

The uncle block used as a parameter in the RPC.

The chain stores only the uncle block header and proposal IDs. The header ensures the block is covered by PoW and can pass the consensus rules on uncle blocks. Proposal IDs are there because a block can commit transactions proposed in an uncle.

A block B1 is considered to be the uncle of another block B2 if all the following conditions are met:

Fields

UncleBlock is a JSON object with the following fields.

Type UncleBlockView

The uncle block.

The chain stores only the uncle block header and proposal IDs. The header ensures the block is covered by PoW and can pass the consensus rules on uncle blocks. Proposal IDs are there because a block can commit transactions proposed in an uncle.

A block B1 is considered to be the uncle of another block B2 if all the following conditions are met:

Fields

UncleBlockView is a JSON object with the following fields.

Type UncleTemplate

The uncle block template of the new block for miners.

Fields

UncleTemplate is a JSON object with the following fields.

Type Version

The simple increasing integer version.

This is a 32-bit unsigned integer type encoded as the 0x-prefixed hex string in JSON. See examples of Uint32.