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.

See list of projects to setup the proxy for the RPC server.

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.enable_deprecated_rpc.

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.71.1.

Table of Contents

• RPC Methods

  • Module Alert 👉 OpenRPC spec

    • Method send_alert

  • Module Chain 👉 OpenRPC spec

    • Method get_block
    • Method get_block_by_number
    • Method get_header
    • Method get_header_by_number
    • Method get_block_filter
    • Method get_transaction
    • Method get_block_hash
    • Method get_tip_header
    • Method get_live_cell
    • Method get_tip_block_number
    • Method get_current_epoch
    • Method get_epoch_by_number
    • Method get_block_economic_state
    • Method get_transaction_proof
    • Method verify_transaction_proof
    • Method get_transaction_and_witness_proof
    • Method verify_transaction_and_witness_proof
    • Method get_fork_block
    • Method get_consensus
    • Method get_block_median_time
    • Method estimate_cycles
    • Method get_fee_rate_statics
    • Method get_fee_rate_statistics

  • Module Debug 👉 OpenRPC spec

    • Method jemalloc_profiling_dump
    • Method update_main_logger
    • Method set_extra_logger

  • Module Experiment 👉 OpenRPC spec

    • Method dry_run_transaction
    • Method calculate_dao_maximum_withdraw

  • Module Indexer 👉 OpenRPC spec

    • Method get_indexer_tip
    • Method get_cells
    • Method get_transactions
    • Method get_cells_capacity

  • Module Integration_test 👉 OpenRPC spec

    • Method process_block_without_verify
    • Method truncate
    • Method generate_block
    • Method generate_epochs
    • Method notify_transaction
    • Method generate_block_with_template
    • Method calculate_dao_field

  • Module Miner 👉 OpenRPC spec

    • Method get_block_template
    • Method submit_block

  • Module Net 👉 OpenRPC spec

    • Method local_node_info
    • Method get_peers
    • Method get_banned_addresses
    • Method clear_banned_addresses
    • Method set_ban
    • Method sync_state
    • Method set_network_active
    • Method add_node
    • Method remove_node
    • Method ping_peers

  • Module Pool 👉 OpenRPC spec

    • Method send_transaction
    • Method remove_transaction
    • Method tx_pool_info
    • Method clear_tx_pool
    • Method get_raw_tx_pool
    • Method get_pool_tx_detail_info
    • Method tx_pool_ready

  • Module Rich_indexer 👉 OpenRPC spec

    • Method get_indexer_tip
    • Method get_cells
    • Method get_transactions
    • Method get_cells_capacity

  • Module Stats 👉 OpenRPC spec

    • Method get_blockchain_info
    • Method get_deployments_info

  • Module Subscription 👉 OpenRPC spec

    • Method subscribe
    • Method unsubscribe

• RPC Types

  • Type Alert
  • Type AlertId
  • Type AlertId
  • Type AlertMessage
  • Type AlertPriority
  • Type AlertPriority
  • Type AncestorsScoreSortKey
  • Type BannedAddr
  • Type Block
  • Type BlockEconomicState
  • Type BlockFilter
  • Type BlockIssuance
  • Type BlockNumber
  • Type BlockResponse
  • Type BlockTemplate
  • Type BlockView
  • Type BlockWithCyclesResponse
  • Type Buried
  • Type Byte32
  • Type Capacity
  • Type CellData
  • Type CellDep
  • Type CellInfo
  • Type CellInput
  • Type CellOutput
  • Type CellWithStatus
  • Type CellbaseTemplate
  • Type ChainInfo
  • Type Consensus
  • Type Cycle
  • Type DaoWithdrawingCalculationKind
  • Type DepType
  • Type Deployment
  • Type DeploymentInfo
  • Type DeploymentState
  • Type DeploymentsInfo
  • Type EpochNumber
  • Type EpochNumber
  • Type EpochNumberWithFraction
  • Type EpochView
  • Type EstimateCycles
  • Type ExtraLoggerConfig
  • Type FeeRateStatistics
  • Type H256
  • Type HardForkFeature
  • Type Header
  • Type HeaderView
  • Type IndexerCell
  • Type IndexerCellType
  • Type IndexerCellsCapacity
  • Type IndexerOrder
  • Type IndexerPagination_for_IndexerCell
  • Type IndexerPagination_for_IndexerTx
  • Type IndexerRange
  • Type IndexerScriptType
  • Type IndexerSearchKey
  • Type IndexerSearchKeyFilter
  • Type IndexerSearchMode
  • Type IndexerTip
  • Type IndexerTx
  • Type IndexerTxWithCell
  • Type IndexerTxWithCells
  • Type JsonBytes
  • Type LocalNode
  • Type LocalNodeProtocol
  • Type MainLoggerConfig
  • Type MerkleProof
  • Type MinerReward
  • Type NodeAddress
  • Type OutPoint
  • Type OutputsValidator
  • Type PeerSyncState
  • Type PoolTransactionReject
  • Type PoolTxDetailInfo
  • Type ProposalShortId
  • Type ProposalWindow
  • Type Ratio
  • Type RationalU256
  • Type RawTxPool
  • Type RemoteNode
  • Type RemoteNodeProtocol
  • Type Rfc0043
  • Type Script
  • Type ScriptHashType
  • Type SerializedBlock
  • Type SerializedHeader
  • Type SoftFork
  • Type SoftForkStatus
  • Type Status
  • Type SyncState
  • Type Timestamp
  • Type Transaction
  • Type TransactionAndWitnessProof
  • Type TransactionProof
  • Type TransactionTemplate
  • Type TransactionView
  • Type TransactionWithStatusResponse
  • Type TxPoolEntries
  • Type TxPoolEntry
  • Type TxPoolIds
  • Type TxPoolInfo
  • Type TxStatus
  • Type U256
  • Type Uint128
  • Type Uint32
  • Type Uint64
  • Type UncleBlock
  • Type UncleBlockView
  • Type UncleTemplate
  • Type Version

• RPC Errors

RPC Modules

Module Alert

• 👉 OpenRPC spec

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

• send_alert(alert)
  • alert: Alert
• result: null

Sends an alert.

This RPC returns null on success.

Errors

• AlertFailedToVerifySignatures (-1000) - Some signatures in the request are invalid.
• P2PFailedToBroadcast (-101) - Alert is saved locally but has failed to broadcast to the P2P network.
• InvalidParams (-32602) - The time specified in alert.notice_until must be in the future.

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 is less than threshold."
  },
  "jsonrpc": "2.0",
  "result": null,
  "id": 42
}

Module Chain

• 👉 OpenRPC spec

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 revert 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

• it is found as an output in any transaction in the canonical chain, and
• it is not found as an input in any transaction in the canonical chain.

Method get_block

• get_block(block_hash, verbosity, with_cycles)
  • block_hash: H256
  • verbosity: Uint32 | null
  • with_cycles: boolean | null
• result: BlockResponse | null

Returns the information about a block by hash.

Params

• block_hash - the block hash.
• verbosity - result format which allows 0 and 2. (Optional, the default is 2.)
• with_cycles - whether the return cycles of block transactions. (Optional, default false.)

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

• get_block_by_number(block_number, verbosity, with_cycles)
  • block_number: Uint64
  • verbosity: Uint32 | null
  • with_cycles: boolean | null
• result: BlockResponse | null

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

Params

• block_number - the block number.
• verbosity - result format which allows 0 and 2. (Optional, the default is 2.)
• with_cycles - whether the return cycles of block transactions. (Optional, default false.)

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

• ChainIndexIsInconsistent (-201) - The index is inconsistent. It says a block hash is in the main chain, but cannot read it from the database.
• DatabaseIsCorrupt (-202) - The data read from database is dirty. Please report it as a bug.

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

• get_header(block_hash, verbosity)
  • block_hash: H256
  • verbosity: Uint32 | null
• result: Either_for_HeaderView_and_JsonBytes | null

Returns the information about a block header by hash.

Params

• block_hash - the block hash.
• verbosity - result format which allows 0 and 1. (Optional, the default is 1.)

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

• get_header_by_number(block_number, verbosity)
  • block_number: Uint64
  • verbosity: Uint32 | null
• result: Either_for_HeaderView_and_JsonBytes | null

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

Params

• block_number - Number of a block
• verbosity - result format which allows 0 and 1. (Optional, the default is 1.)

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

• ChainIndexIsInconsistent (-201) - The index is inconsistent. It says a block hash is in the main chain, but cannot read it from the database.

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

• get_block_filter(block_hash)
  • block_hash: H256
• result: BlockFilter | null

Returns the block filter by block hash.

Params

• block_hash - the block hash.

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

• get_transaction(tx_hash, verbosity, only_committed)
  • tx_hash: H256
  • verbosity: Uint32 | null
  • only_committed: boolean | null
• result: TransactionWithStatusResponse

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

• tx_hash - Hash of a transaction
• verbosity - result format which allows 0, 1 and 2. (Optional, the defaults to 2.)
• only_committed - whether to query committed transaction only. (Optional, if not set, it will query all status of transactions.)

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",
    "fee": "0x16923f7dcf",
    "min_replace_fee": "0x16923f7f6a",
    "tx_status": {
      "block_hash": null,
      "block_number": 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,
      "block_number": null,
      "status": "pending",
      "reason": null
    }
  }
}

Method get_block_hash

• get_block_hash(block_number)
  • block_number: Uint64
• result: H256 | null

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

Params

• block_number - Block number

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

• get_tip_header(verbosity)
  • verbosity: Uint32 | null
• result: Either_for_HeaderView_and_JsonBytes

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

• verbosity - result format which allows 0 and 1. (Optional, the default is 1.)

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

• get_live_cell(out_point, with_data)
  • out_point: OutPoint
  • with_data: boolean
• result: CellWithStatus

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

• out_point - Reference to the cell by transaction hash and output index.
• with_data - Whether the RPC should return cell data. Cell data can be huge, if the client does not need the data, it should set this to false to save bandwidth.

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

• get_tip_block_number()

• result: Uint64

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

• get_current_epoch()

• result: EpochView

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

• get_epoch_by_number(epoch_number)
  • epoch_number: Uint64
• result: EpochView | null

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

Params

• epoch_number - Epoch number

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

• get_block_economic_state(block_hash)
  • block_hash: H256
• result: BlockEconomicState | null

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

• block_hash - Specifies the block hash which rewards should be analyzed.

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

• get_transaction_proof(tx_hashes, block_hash)
  • tx_hashes: Array< H256 >
  • block_hash: H256 | null
• result: TransactionProof

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

Params

• tx_hashes - Transaction hashes, all transactions must be in the same block
• block_hash - An optional parameter, if specified, looks for transactions in the block with this hash

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

• verify_transaction_proof(tx_proof)
  • tx_proof: TransactionProof
• result: Array< H256 >

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

Parameters

• transaction_proof - proof generated by get_transaction_proof.

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

• get_transaction_and_witness_proof(tx_hashes, block_hash)
  • tx_hashes: Array< H256 >
  • block_hash: H256 | null
• result: TransactionAndWitnessProof

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

Params

• tx_hashes - Transaction hashes, all transactions must be in the same block
• block_hash - An optional parameter, if specified, looks for transactions in the block with this hash

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

• verify_transaction_and_witness_proof(tx_proof)
  • tx_proof: TransactionAndWitnessProof
• result: Array< H256 >

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

Parameters

• tx_proof - proof generated by get_transaction_and_witness_proof.

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

• get_fork_block(block_hash, verbosity)
  • block_hash: H256
  • verbosity: Uint32 | null
• result: Either_for_BlockView_and_JsonBytes | null

Returns the information about a fork block by hash.

Params

• block_hash - the fork block hash.
• verbosity - result format which allows 0 and 2. (Optional, the default is 2.)

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

• get_consensus()

• result: 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": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "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": "0x1526" },
            { "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

• get_block_median_time(block_hash)
  • block_hash: H256
• result: Uint64 | null

Returns the past median time by block hash.

Params

• block_hash - A median time is calculated for a consecutive block sequence. block_hash indicates the highest block of the sequence.

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(tx)
  • tx: Transaction
• result: EstimateCycles

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

• TransactionFailedToResolve (-301) - Failed to resolve the referenced cells and headers used in the transaction, as inputs or dependencies.
• TransactionFailedToVerify (-302) - There is a script returns with an error.

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

• get_fee_rate_statics(target)
  • target: Uint64 | null
• result: FeeRateStatistics | null

Returns the fee_rate statistics of confirmed blocks on the chain

Params

• target - Specify the number (1 - 101) of confirmed blocks to be counted. If the number is even, automatically add one. If not specified, defaults to 21

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

• get_fee_rate_statistics(target)
  • target: Uint64 | null
• result: FeeRateStatistics | null

Returns the fee_rate statistics of confirmed blocks on the chain

Params

• target - Specify the number (1 - 101) of confirmed blocks to be counted. If the number is even, automatically add one. If not specified, defaults to 21

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 Debug

• 👉 OpenRPC spec

RPC Module Debug for internal RPC methods.

This module is for CKB developers and will not guarantee compatibility. The methods here will be changed or removed without advanced notification.

Method jemalloc_profiling_dump

• jemalloc_profiling_dump()

• result: string

Dumps jemalloc memory profiling information into a file.

The file is stored in the server running the CKB node.

The RPC returns the path to the dumped file on success or returns an error on failure.

Method update_main_logger

• update_main_logger(config)
  • config: MainLoggerConfig
• result: null

Changes main logger config options while CKB is running.

Method set_extra_logger

• set_extra_logger(name, config_opt)
  • name: string
  • config_opt: ExtraLoggerConfig | null
• result: null

Sets logger config options for extra loggers.

CKB nodes allow setting up extra loggers. These loggers will have their own log files and they only append logs to their log files.

Params

• name - Extra logger name
• config_opt - Adds a new logger or update an existing logger when this is not null. Removes the logger when this is null.