Skip to main content

ChainRpc

ckb_rpc::module

Trait ChainRpc 

Source 
pub trait ChainRpc {

Show 23 methods    // Required methods
    fn get_block(
        &self,
        block_hash: H256,
        verbosity: Option<Uint32>,
        with_cycles: Option<bool>,
    ) -> Result<Option<BlockResponse>>;
    fn get_block_by_number(
        &self,
        block_number: BlockNumber,
        verbosity: Option<Uint32>,
        with_cycles: Option<bool>,
    ) -> Result<Option<BlockResponse>>;
    fn get_header(
        &self,
        block_hash: H256,
        verbosity: Option<Uint32>,
    ) -> Result<Option<ResponseFormat<HeaderView>>>;
    fn get_header_by_number(
        &self,
        block_number: BlockNumber,
        verbosity: Option<Uint32>,
    ) -> Result<Option<ResponseFormat<HeaderView>>>;
    fn get_block_filter(&self, block_hash: H256) -> Result<Option<BlockFilter>>;
    fn get_transaction(
        &self,
        tx_hash: H256,
        verbosity: Option<Uint32>,
        only_committed: Option<bool>,
    ) -> Result<TransactionWithStatusResponse>;
    fn get_block_hash(&self, block_number: BlockNumber) -> Result<Option<H256>>;
    fn get_tip_header(
        &self,
        verbosity: Option<Uint32>,
    ) -> Result<ResponseFormat<HeaderView>>;
    fn get_live_cell(
        &self,
        out_point: OutPoint,
        with_data: bool,
        include_tx_pool: Option<bool>,
    ) -> Result<CellWithStatus>;
    fn get_tip_block_number(&self) -> Result<BlockNumber>;
    fn get_current_epoch(&self) -> Result<EpochView>;
    fn get_epoch_by_number(
        &self,
        epoch_number: EpochNumber,
    ) -> Result<Option<EpochView>>;
    fn get_block_economic_state(
        &self,
        block_hash: H256,
    ) -> Result<Option<BlockEconomicState>>;
    fn get_transaction_proof(
        &self,
        tx_hashes: Vec<H256>,
        block_hash: Option<H256>,
    ) -> Result<TransactionProof>;
    fn verify_transaction_proof(
        &self,
        tx_proof: TransactionProof,
    ) -> Result<Vec<H256>>;
    fn get_transaction_and_witness_proof(
        &self,
        tx_hashes: Vec<H256>,
        block_hash: Option<H256>,
    ) -> Result<TransactionAndWitnessProof>;
    fn verify_transaction_and_witness_proof(
        &self,
        tx_proof: TransactionAndWitnessProof,
    ) -> Result<Vec<H256>>;
    fn get_fork_block(
        &self,
        block_hash: H256,
        verbosity: Option<Uint32>,
    ) -> Result<Option<ResponseFormat<BlockView>>>;
    fn get_consensus(&self) -> Result<Consensus>;
    fn get_block_median_time(
        &self,
        block_hash: H256,
    ) -> Result<Option<Timestamp>>;
    fn estimate_cycles(&self, tx: Transaction) -> Result<EstimateCycles>;
    fn get_fee_rate_statics(
        &self,
        target: Option<Uint64>,
    ) -> Result<Option<FeeRateStatistics>>;
    fn get_fee_rate_statistics(
        &self,
        target: Option<Uint64>,
    ) -> Result<Option<FeeRateStatistics>>;

}
Expand description

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.

Required Methods§

Source

fn get_block( &self, block_hash: H256, verbosity: Option<Uint32>, with_cycles: Option<bool>, ) -> Result<Option<BlockResponse>>

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": []
    }
}
Source

fn get_block_by_number( &self, block_number: BlockNumber, verbosity: Option<Uint32>, with_cycles: Option<bool>, ) -> Result<Option<BlockResponse>>

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
§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": []
    }
}
Source

fn get_header( &self, block_hash: H256, verbosity: Option<Uint32>, ) -> Result<Option<ResponseFormat<HeaderView>>>

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..."
}
Source

fn get_header_by_number( &self, block_number: BlockNumber, verbosity: Option<Uint32>, ) -> Result<Option<ResponseFormat<HeaderView>>>

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
§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..."
}
Source

fn get_block_filter(&self, block_hash: H256) -> Result<Option<BlockFilter>>

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..."
  }
}
Source

fn get_transaction( &self, tx_hash: H256, verbosity: Option<Uint32>, only_committed: Option<bool>, ) -> 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",
      "tx_index": null,
      "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",
      "tx_index": null,
      "reason": null
    }
  }
}
Source

fn get_block_hash(&self, block_number: BlockNumber) -> Result<Option<H256>>

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"
}
Source

fn get_tip_header( &self, verbosity: Option<Uint32>, ) -> Result<ResponseFormat<HeaderView>>

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..."
}
Source

fn get_live_cell( &self, out_point: OutPoint, with_data: bool, include_tx_pool: Option<bool>, ) -> 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.
  • include_tx_pool - Whether the RPC check live cell in TxPool, default is false.
§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"
  }
}
Source

fn get_tip_block_number(&self) -> Result<BlockNumber>

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"
}
Source

fn get_current_epoch(&self) -> 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"
  }
}
Source

fn get_epoch_by_number( &self, epoch_number: EpochNumber, ) -> Result<Option<EpochView>>

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"
  }
}
Source

fn get_block_economic_state( &self, block_hash: H256, ) -> Result<Option<BlockEconomicState>>

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"
  }
}
Source

fn get_transaction_proof( &self, tx_hashes: Vec<H256>, block_hash: Option<H256>, ) -> 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"
  }
}
Source

fn verify_transaction_proof( &self, tx_proof: TransactionProof, ) -> Result<Vec<H256>>

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"
  ]
}
Source

fn get_transaction_and_witness_proof( &self, tx_hashes: Vec<H256>, block_hash: Option<H256>, ) -> 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
}
Source

fn verify_transaction_and_witness_proof( &self, tx_proof: TransactionAndWitnessProof, ) -> Result<Vec<H256>>

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"
  ]
}
Source

fn get_fork_block( &self, block_hash: H256, verbosity: Option<Uint32>, ) -> Result<Option<ResponseFormat<BlockView>>>

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..."
}
Source

fn get_consensus(&self) -> 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": "0x3005" },
            { "rfc": "0049", "epoch_number": "0x3005" }
         ],
        "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"
    }
}
Source

fn get_block_median_time(&self, block_hash: H256) -> Result<Option<Timestamp>>

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"
}
Source

fn estimate_cycles(&self, 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
§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"
  }
}
Source

fn get_fee_rate_statics( &self, target: Option<Uint64>, ) -> Result<Option<FeeRateStatistics>>

👎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
  • 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"
   }
}
Source

fn get_fee_rate_statistics( &self, target: Option<Uint64>, ) -> Result<Option<FeeRateStatistics>>

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"
   }
}

Implementors§