89 releases (25 breaking)
new 0.120.0-rc4 | Dec 4, 2024 |
---|---|
0.120.0-rc2 | Nov 20, 2024 |
0.117.0 | Jul 29, 2024 |
0.115.0-rc2 | Mar 20, 2024 |
0.1.0 | Nov 2, 2018 |
#257 in Magic Beans
385 downloads per month
Used in 4 crates
(2 directly)
4.5MB
70K
SLoC
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
-
-
- 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
- Method
-
- 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
EntryCompleted
- Type
EpochNumber
- Type
EpochNumber
- Type
EpochNumberWithFraction
- Type
EpochView
- Type
EstimateCycles
- Type
EstimateMode
- Type
ExtraLoggerConfig
- Type
FeeRateStatistics
- Type
H256
- Type
HardForkFeature
- Type
HardForks
- Type
Header
- Type
HeaderView
- Type
IndexerCell
- Type
IndexerCellType
- Type
IndexerCellsCapacity
- Type
IndexerOrder
- Type
IndexerPagination<IndexerCell>
- Type
IndexerPagination<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
ResponseFormat<BlockView>
- Type
ResponseFormat<HeaderView>
- Type
ResponseFormat<TransactionView>
- 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
- Type
RPC Modules
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
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 inalert.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
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)
- 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)
- 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)
- result:
ResponseFormat<HeaderView>
|
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)
- result:
ResponseFormat<HeaderView>
|
null
Returns the block header in the canonical chain with the specific block number.
Params
block_number
- Number of a blockverbosity
- 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)
- 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 transactionverbosity
- 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
}
}
}
Method get_block_hash
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:
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..."
}
Method get_live_cell
get_live_cell(out_point, with_data, include_tx_pool)
out_point
:OutPoint
with_data
:boolean
include_tx_pool
:boolean
|
null
- 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 tofalse
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"
}
}
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
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)
- 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 blockblock_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 byget_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)
- 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 blockblock_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 byget_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)
- result:
ResponseFormat<BlockView>
|
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
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
👎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"
}
}
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
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 nameconfig_opt
- Adds a new logger or update an existing logger when this is not null. Removes the logger when this is null.
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
dry_run_transaction(tx)
tx
:Transaction
- result:
EstimateCycles
👎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
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": "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
calculate_dao_maximum_withdraw(out_point, kind)
out_point
:OutPoint
kind
:DaoWithdrawingCalculationKind
- result:
Uint64
Calculates the maximum withdrawal one can get, given a referenced DAO cell, and a withdrawing block hash.
Params
out_point
- Reference to the DAO cell, the depositing transaction's output.kind
- Two kinds of dao withdrawal amount calculation option.
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
DaoError (-5)
- The given out point is not a valid cell for DAO computation.CKBInternalError (-1)
- Mathematics overflow.
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"
}
Method estimate_fee_rate
estimate_fee_rate(estimate_mode, enable_fallback)
estimate_mode
:EstimateMode
|
null
enable_fallback
:boolean
|
null
- result:
Uint64
Get fee estimates.
Params
-
estimate_mode
- The fee estimate mode.Default:
no_priority
. -
enable_fallback
- True to enable a simple fallback algorithm, when lack of historical empirical data to estimate fee rates with configured algorithm.Default:
true
.
####### The fallback algorithm
Since CKB transaction confirmation involves a two-step process—1) propose and 2) commit, it is complex to predict the transaction fee accurately with the expectation that it will be included within a certain block height.
This algorithm relies on two assumptions and uses a simple strategy to estimate the transaction fee: 1) all transactions in the pool are waiting to be proposed, and 2) no new transactions will be added to the pool.
In practice, this simple algorithm should achieve good accuracy fee rate and running performance.
Returns
The estimated fee rate in shannons per kilobyte.
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "estimate_fee_rate",
"params": []
}
Response
{
"id": 42,
"jsonrpc": "2.0",
"result": "0x3e8"
}
Module Indexer
RPC Module Indexer.
Method get_indexer_tip
-
get_indexer_tip()
-
result:
IndexerTip
|
null
Returns the indexed tip
Returns
- block_hash - indexed tip block hash
- block_number - indexed tip block number
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
get_cells(search_key, order, limit, after)
search_key
:IndexerSearchKey
order
:IndexerOrder
limit
:Uint32
after
:JsonBytes
|
null
- result:
IndexerPagination<IndexerCell>
Returns the live cells collection by the lock or type script.
Params
- search_key:
- script - Script, supports prefix search
- script_type - enum, lock | type
- script_search_mode - enum, prefix | exact
- filter - filter cells by following conditions, all conditions are optional
- script: if search script type is lock, filter cells by type script prefix, and vice versa
- script_len_range: [u64; 2], filter cells by script len range, [inclusive, exclusive]
- output_data: filter cells by output data
- output_data_filter_mode: enum, prefix | exact | partial
- output_data_len_range: [u64; 2], filter cells by output data len range, [inclusive, exclusive]
- output_capacity_range: [u64; 2], filter cells by output capacity range, [inclusive, exclusive]
- block_range: [u64; 2], filter cells by block number range, [inclusive, exclusive]
- with_data - bool, optional default is
true
, if with_data is set to false, the field of returning cell.output_data is null in the result
- order: enum, asc | desc
- limit: result size limit
- after: pagination parameter, optional
Returns
If the number of objects is less than the requested limit
, it indicates that these are the last page of get_cells.
- objects:
- output: the fields of an output cell
- output_data: the cell data
- out_point: reference to a cell via transaction hash and output index
- block_number: the number of the transaction committed in the block
- tx_index: the position index of the transaction committed in the block
- last_cursor: pagination parameter
Examples
- get cells by lock script
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
}
- get cells by lock script and filter by type script
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
}
- get cells by lock script and filter empty type script by setting script_len_range to [0, 1), script_len is calculated by (code_hash + hash_type + args).len
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
}
- get cells by lock script and filter capacity range
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
get_transactions(search_key, order, limit, after)
search_key
:IndexerSearchKey
order
:IndexerOrder
limit
:Uint32
after
:JsonBytes
|
null
- result:
IndexerPagination<IndexerTx>
Returns the transactions collection by the lock or type script.
- search_key:
- script - Script, supports prefix search when group_by_transaction is false
- script_type - enum, lock | type
- script_search_mode - enum, prefix | exact
- filter - filter cells by following conditions, all conditions are optional
- script: if search script type is lock, filter cells by type script, and vice versa
- block_range: [u64; 2], filter cells by block number range, [inclusive, exclusive]
- group_by_transaction - bool, optional default is
false
, if group_by_transaction is set to true, the returning objects will be grouped by the tx hash
- order: enum, asc | desc
- limit: result size limit
- after: pagination parameter, optional
Returns
If the number of objects is less than the requested limit
, it indicates that these are the last page of get_transactions.
- objects - enum, ungrouped TxWithCell | grouped TxWithCells
- TxWithCell:
- tx_hash: transaction hash,
- block_number: the number of the transaction committed in the block
- tx_index: the position index of the transaction committed in the block
- io_type: enum, input | output
- io_index: the position index of the cell in the transaction inputs or outputs
- TxWithCells:
- tx_hash: transaction hash,
- block_number: the number of the transaction committed in the block
- tx_index: the position index of the transaction committed in the block
- cells: Array [[io_type, io_index]]
- TxWithCell:
- last_cursor - pagination parameter
Examples
- get transactions by lock script
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
}
- get transactions by lock script and group by tx hash
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
get_cells_capacity(search_key)
search_key
:IndexerSearchKey
- result:
IndexerCellsCapacity
|
null
Returns the live cells capacity by the lock or type script.
Parameters
- search_key:
- script - Script
- script_type - enum, lock | type
- script_search_mode - enum, prefix | exact
- filter - filter cells by following conditions, all conditions are optional
- script: if search script type is lock, filter cells by type script prefix, and vice versa
- script_len_range: [u64; 2], filter cells by script len range, [inclusive, exclusive]
- output_data: filter cells by output data
- output_data_filter_mode: enum, prefix | exact | partial
- output_data_len_range: [u64; 2], filter cells by output data len range, [inclusive, exclusive]
- output_capacity_range: [u64; 2], filter cells by output capacity range, [inclusive, exclusive]
- block_range: [u64; 2], filter cells by block number range, [inclusive, exclusive]
Returns
- capacity - total capacity
- block_hash - indexed tip block hash
- block_number - indexed tip block number
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 Integration_test
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"
}
Method truncate
truncate(target_tip_hash)
target_tip_hash
:H256
- result:
null
Truncate chain to specified tip hash, can only truncate less then 50000 blocks each time.
Params
target_tip_hash
- specified header hash
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "truncate",
"params": [
"0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40"
]
}
Response
{
"id": 42,
"jsonrpc": "2.0",
"result": null
}
Method generate_block
-
generate_block()
-
result:
H256
Generate block(with verification) and broadcast the block.
Note that if called concurrently, it may return the hash of the same block.
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "generate_block",
"params": []
}
Response
{
"id": 42,
"jsonrpc": "2.0",
"result": "0x60dd3fa0e81db3ee3ad41cf4ab956eae7e89eb71cd935101c26c4d0652db3029"
}
Method generate_epochs
Generate epochs during development, can be useful for scenarios like testing DAO-related functionalities.
Returns the updated epoch number after generating the specified number of epochs.
Params
num_epochs
- The number of epochs to generate.
Examples
Request
Generating 2 epochs:
{
"id": 42,
"jsonrpc": "2.0",
"method": "generate_epochs",
"params": ["0x2"]
}
The input parameter "0x2" will be normalized to "0x10000000002"(the correct
EpochNumberWithFraction
type) within the method.
Therefore, if you want to generate epochs as integers, you can simply pass an integer
as long as it does not exceed 16777215 (24 bits).
Generating 1/2 epoch:
{
"id": 42,
"jsonrpc": "2.0",
"method": "generate_epochs",
"params": ["0x20001000000"]
}
Response
{
"id": 42,
"jsonrpc": "2.0",
"result": "0xa0001000003"
}
Method notify_transaction
notify_transaction(transaction)
transaction
:Transaction
- result:
H256
Add transaction to tx-pool.
Params
transaction
- specified transaction to add
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"
}
Method generate_block_with_template
generate_block_with_template(block_template)
block_template
:BlockTemplate
- result:
H256
Generate block with block template, attach calculated dao field to build new block,
then process block and broadcast the block.
Params
block_template
- specified transaction to add
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": "0xb0a0079f3778c0ba0d89d88b389c602cc18b8a0355d16c0713f8bfcee64b5f84",
"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"
}
Method calculate_dao_field
calculate_dao_field(block_template)
block_template
:BlockTemplate
- result:
Byte32
Return calculated dao field according to specified block template.
Params
block_template
- specified block template
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": "0xb0a0079f3778c0ba0d89d88b389c602cc18b8a0355d16c0713f8bfcee64b5f84",
"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"
}
Method send_test_transaction
send_test_transaction(tx, outputs_validator)
tx
:Transaction
outputs_validator
:OutputsValidator
|
null
- result:
H256
Submits a new test local transaction into the transaction pool, only for testing. If the transaction is already in the pool, rebroadcast it to peers.
Params
transaction
- The transaction.outputs_validator
- Validates the transaction outputs before entering the tx-pool. (Optional, default is "passthrough").
Errors
PoolRejectedTransactionByOutputsValidator (-1102)
- The transaction is rejected by the validator specified byoutputs_validator
. If you really want to send transactions with advanced scripts, please setoutputs_validator
to "passthrough".PoolRejectedTransactionByMinFeeRate (-1104)
- The transaction fee rate must be greater than or equal to the config optiontx_pool.min_fee_rate
.PoolRejectedTransactionByMaxAncestorsCountLimit (-1105)
- The ancestors count must be greater than or equal to the config optiontx_pool.max_ancestors_count
.PoolIsFull (-1106)
- Pool is full.PoolRejectedDuplicatedTransaction (-1107)
- The transaction is already in the pool.TransactionFailedToResolve (-301)
- Failed to resolve the referenced cells and headers used in the transaction, as inputs or dependencies.TransactionFailedToVerify (-302)
- Failed to verify the transaction.
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "send_test_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"
}
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
get_block_template(bytes_limit, proposals_limit, max_version)
- result:
BlockTemplate
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
bytes_limit
- the max serialization size in bytes of the block. (Optional: the default is the consensus limit.)proposals_limit
- the max count of proposals. (Optional: the default is the consensus limit.)max_version
- the max block version. (Optional: the default is one configured in the current client version.)
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": "0xb0a0079f3778c0ba0d89d88b389c602cc18b8a0355d16c0713f8bfcee64b5f84",
"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
work_id
- The same work ID returned fromget_block_template
.block
- The assembled block from the block template and which PoW puzzle has been resolved.
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "submit_block",
"params": [
"work_id_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
-
local_node_info()
-
result:
LocalNode
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
-
get_peers()
-
result:
Array<
RemoteNode
>
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
-
get_banned_addresses()
-
result:
Array<
BannedAddr
>
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
-
clear_banned_addresses()
-
result:
null
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
set_ban(address, command, ban_time, absolute, reason)
address
:string
command
:string
ban_time
:Uint64
|
null
absolute
:boolean
|
null
reason
:string
|
null
- result:
null
Inserts or deletes an IP/Subnet from the banned list
Params
address
- The IP/Subnet with an optional netmask (default is /32 = single IP). Examples:- "192.168.0.2" bans a single IP
- "192.168.0.0/24" bans IP from "192.168.0.0" to "192.168.0.255".
command
-insert
to insert an IP/Subnet to the list,delete
to delete an IP/Subnet from the list.ban_time
- Time in milliseconds how long (or until when if [absolute] is set) the IP is banned, optional parameter, null means using the default time of 24habsolute
- If set, theban_time
must be an absolute timestamp in milliseconds since epoch, optional parameter.reason
- Ban reason, optional parameter.
Errors
InvalidParams (-32602)
- Expected
address
to be a valid IP address with an optional netmask. - Expected
command
to be in the list [insert, delete].
- Expected
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
-
sync_state()
-
result:
SyncState
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": {
"assume_valid_target": "0x0000000000000000000000000000000000000000000000000000000000000000",
"assume_valid_target_reached": true,
"best_known_block_number": "0x400",
"best_known_block_timestamp": "0x5cd2b117",
"fast_time": "0x3e8",
"ibd": true,
"inflight_blocks_count": "0x0",
"low_time": "0x5dc",
"min_chain_work": "0x0",
"min_chain_work_reached": true,
"normal_time": "0x4e2",
"orphan_blocks_count": "0x0",
"tip_hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40",
"tip_number": "0x400",
"unverified_tip_hash": "0xa5f5c85987a15de25661e5a214f2c1449cd803f071acc7999820f25246471f40",
"unverified_tip_number": "0x400"
}
}
Method set_network_active
set_network_active(state)
state
:boolean
- result:
null
Disable/enable all p2p network activity
Params
state
- true to enable networking, false to disable
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "set_network_active",
"params": [
false
]
}
Response
{
"id": 42,
"jsonrpc": "2.0",
"result": null
}
Method add_node
add_node(peer_id, address)
peer_id
:string
address
:string
- result:
null
Attempts to add a node to the peers list and try connecting to it.
Params
peer_id
- The node id of the node.address
- The address of the node.
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,
peer_id
isQmUsZHPbjjzU627UZFt4k8j6ycEcNvXRnVGxCPKqwbAfQS
,- and
address
is/ip4/192.168.2.100/tcp/8114
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
remove_node(peer_id)
peer_id
:string
- result:
null
Attempts to remove a node from the peers list and try disconnecting from it.
Params
peer_id
- The peer id of the node.
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
-
ping_peers()
-
result:
null
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
send_transaction(tx, outputs_validator)
tx
:Transaction
outputs_validator
:OutputsValidator
|
null
- result:
H256
Submits a new transaction into the transaction pool. If the transaction is already in the pool, rebroadcast it to peers.
Please note that send_transaction
is an asynchronous process.
The return of send_transaction
does NOT indicate that the transaction have been fully verified.
If you want to track the status of the transaction, please use the get_transaction
rpc.
Params
transaction
- The transaction.outputs_validator
- Validates the transaction outputs before entering the tx-pool. (Optional, default is "passthrough").
Errors
PoolRejectedTransactionByOutputsValidator (-1102)
- The transaction is rejected by the validator specified byoutputs_validator
. If you really want to send transactions with advanced scripts, please setoutputs_validator
to "passthrough".PoolRejectedTransactionByMinFeeRate (-1104)
- The transaction fee rate must be greater than or equal to the config optiontx_pool.min_fee_rate
.PoolRejectedTransactionByMaxAncestorsCountLimit (-1105)
- The ancestors count must be greater than or equal to the config optiontx_pool.max_ancestors_count
.PoolIsFull (-1106)
- Pool is full.PoolRejectedDuplicatedTransaction (-1107)
- The transaction is already in the pool.TransactionFailedToResolve (-301)
- Failed to resolve the referenced cells and headers used in the transaction, as inputs or dependencies.TransactionFailedToVerify (-302)
- Failed to verify the transaction.
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 test_tx_pool_accept
test_tx_pool_accept(tx, outputs_validator)
tx
:Transaction
outputs_validator
:OutputsValidator
|
null
- result:
EntryCompleted
Test if a transaction can be accepted by the transaction pool without inserting it into the pool or rebroadcasting it to peers.
The parameters and errors of this method are the same as send_transaction
.
Params
transaction
- The transaction.outputs_validator
- Validates the transaction outputs before entering the tx-pool. (Optional, default is "passthrough").
Errors
PoolRejectedTransactionByOutputsValidator (-1102)
- The transaction is rejected by the validator specified byoutputs_validator
. If you really want to send transactions with advanced scripts, please setoutputs_validator
to "passthrough".PoolRejectedTransactionByMinFeeRate (-1104)
- The transaction fee rate must be greater than or equal to the config optiontx_pool.min_fee_rate
.PoolRejectedTransactionByMaxAncestorsCountLimit (-1105)
- The ancestors count must be greater than or equal to the config optiontx_pool.max_ancestors_count
.PoolIsFull (-1106)
- Pool is full.PoolRejectedDuplicatedTransaction (-1107)
- The transaction is already in the pool.TransactionFailedToResolve (-301)
- Failed to resolve the referenced cells and headers used in the transaction, as inputs or dependencies.TransactionFailedToVerify (-302)
- Failed to verify the transaction.
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "test_tx_pool_accept",
"params": [
{
"cell_deps": [
{
"dep_type": "code",
"out_point": {
"index": "0x0",
"tx_hash": "0xa4037a893eb48e18ed4ef61034ce26eba9c585f15c9cee102ae58505565eccc3"
}
}
],
"header_deps": [
"0x7978ec7ce5b507cfb52e149e36b1a23f6062ed150503c85bbf825da3599095ed"
],
"inputs": [
{
"previous_output": {
"index": "0x0",
"tx_hash": "0x075fe030c1f4725713c5aacf41c2f59b29b284008fdb786e5efd8a058be51d0c"
},
"since": "0x0"
}
],
"outputs": [
{
"capacity": "0x2431ac129",
"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": {
"cycles": "0x219",
"fee": "0x2a66f36e90"
}
}
The response looks like below if the transaction pool check fails
{
"id": 42,
"jsonrpc": "2.0",
"result": null,
"error": {
"code": -1107,
"data": "Duplicated(Byte32(0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3))",
"message": "PoolRejectedDuplicatedTransaction: Transaction(Byte32(0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3)) already exists in transaction_pool"
}
}
Method remove_transaction
remove_transaction(tx_hash)
tx_hash
:H256
- result:
boolean
Removes a transaction and all transactions which depends on it from tx pool if it exists.
Params
tx_hash
- Hash of a transaction.
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
-
tx_pool_info()
-
result:
TxPoolInfo
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",
"min_rbf_rate": "0x5dc",
"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",
"verify_queue_size": "0x0"
}
}
Method clear_tx_pool
-
clear_tx_pool()
-
result:
null
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 clear_tx_verify_queue
-
clear_tx_verify_queue()
-
result:
null
Removes all transactions from the verification queue.
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "clear_tx_verify_queue",
"params": []
}
Response
{
"id": 42,
"jsonrpc": "2.0",
"result": null
}
Method get_raw_tx_pool
get_raw_tx_pool(verbose)
verbose
:boolean
|
null
- result:
RawTxPool
Returns all transaction ids in tx pool as a json array of string transaction ids.
Params
verbose
- True for a json object, false for array of transaction ids, default=false
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"
}
},
"conflicted": [],
"proposed": {}
}
}
Method get_pool_tx_detail_info
get_pool_tx_detail_info(tx_hash)
tx_hash
:H256
- result:
PoolTxDetailInfo
Query and returns the details of a transaction in the pool, only for trouble shooting
Params
tx_hash
- Hash of a transaction
Examples
Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "get_pool_tx_detail_info",
"params": [
"0xa0ef4eb5f4ceeb08a4c8524d84c5da95dce2f608e0ca2ec8091191b0f330c6e3"
]
}
Response
{
"jsonrpc": "2.0",
"result": {
"ancestors_count": "0x0",
"descendants_count": "0x0",
"entry_status": "pending",
"pending_count": "0x1",
"proposed_count": "0x0",
"rank_in_pending": "0x1",
"score_sortkey": {
"ancestors_fee": "0x16923f7dcf",
"ancestors_weight": "0x112",
"fee": "0x16923f7dcf",
"weight": "0x112"
},
"timestamp": "0x18aa1baa54c"
},
"id": 42
}
Method tx_pool_ready
-
tx_pool_ready()
-
result:
boolean
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 Rich_indexer
RPC Module Rich Indexer.
Method get_indexer_tip
-
get_indexer_tip()
-
result:
IndexerTip
|
null
Returns the indexed tip.
Returns
- block_hash - indexed tip block hash
- block_number - indexed tip block number
Examples
Same as CKB Indexer.
Method get_cells
get_cells(search_key, order, limit, after)
search_key
:IndexerSearchKey
order
:IndexerOrder
limit
:Uint32
after
:JsonBytes
|
null
- result:
IndexerPagination<IndexerCell>
Returns the live cells collection by the lock or type script.
The difference from the original CKB Indexer is that the script_search_mode
parameter accepts the partial
enumeration value. This implies that a partial search can be conducted on the args
of the script
.
Params
- search_key:
- script - Script, supports prefix search
- script_type - enum, lock | type
- script_search_mode - enum, prefix | exact | partial
- filter - filter cells by following conditions, all conditions are optional
- script: if search script type is lock, filter cells by type script prefix, and vice versa
- script_len_range: [u64; 2], filter cells by script len range, [inclusive, exclusive]
- output_data: filter cells by output data
- output_data_filter_mode: enum, prefix | exact | partial
- output_data_len_range: [u64; 2], filter cells by output data len range, [inclusive, exclusive]
- output_capacity_range: [u64; 2], filter cells by output capacity range, [inclusive, exclusive]
- block_range: [u64; 2], filter cells by block number range, [inclusive, exclusive]
- with_data - bool, optional default is
true
, if with_data is set to false, the field of returning cell.output_data is null in the result
- order: enum, asc | desc
- limit: result size limit
- after: pagination parameter, optional
Returns
If the number of objects is less than the requested limit
, it indicates that these are the last page of get_cells.
- objects:
- output: the fields of an output cell
- output_data: the cell data
- out_point: reference to a cell via transaction hash and output index
- block_number: the number of the transaction committed in the block
- tx_index: the position index of the transaction committed in the block
- last_cursor: pagination parameter
Examples
Same as CKB Indexer.
Method get_transactions
get_transactions(search_key, order, limit, after)
search_key
:IndexerSearchKey
order
:IndexerOrder
limit
:Uint32
after
:JsonBytes
|
null
- result:
IndexerPagination<IndexerTx>
Returns the transactions collection by the lock or type script.
The difference from the original CKB Indexer is that both the script_search_mode
and output_data_filter_mode
in filter
can accept the partial
enumeration value. This implies that a partial search can be conducted on both the args
of the script
and the cell output_data
.
- search_key:
- script - Script, supports prefix search when group_by_transaction is false
- script_type - enum, lock | type
- script_search_mode - enum, prefix | exact | partial
- filter - filter cells by following conditions, all conditions are optional
- script: if search script type is lock, filter cells by type script, and vice versa
- script_len_range: [u64; 2], filter cells by script len range, [inclusive, exclusive]
- output_data: filter cells by output data
- output_data_filter_mode: enum, prefix | exact | partial
- output_data_len_range: [u64; 2], filter cells by output data len range, [inclusive, exclusive]
- output_capacity_range: [u64; 2], filter cells by output capacity range, [inclusive, exclusive]
- block_range: [u64; 2], filter cells by block number range, [inclusive, exclusive]
- group_by_transaction - bool, optional default is
false
, if group_by_transaction is set to true, the returning objects will be grouped by the tx hash
- order: enum, asc | desc
- limit: result size limit
- after: pagination parameter, optional
Returns
If the number of objects is less than the requested limit
, it indicates that these are the last page of get_transactions.
- objects - enum, ungrouped TxWithCell | grouped TxWithCells
- TxWithCell:
- tx_hash: transaction hash,
- block_number: the number of the transaction committed in the block
- tx_index: the position index of the transaction committed in the block
- io_type: enum, input | output
- io_index: the position index of the cell in the transaction inputs or outputs
- TxWithCells:
- tx_hash: transaction hash,
- block_number: the number of the transaction committed in the block
- tx_index: the position index of the transaction committed in the block
- cells: Array [[io_type, io_index]]
- TxWithCell:
- last_cursor - pagination parameter
Examples
Same as CKB Indexer.
Method get_cells_capacity
get_cells_capacity(search_key)
search_key
:IndexerSearchKey
- result:
IndexerCellsCapacity
|
null
Returns the live cells capacity by the lock or type script.
The difference from the original CKB Indexer is that the script_search_mode
parameter accepts the partial
enumeration value. This implies that a partial search can be conducted on the args
of the script
.
Parameters
- search_key:
- script - Script
- script_type - enum, lock | type
- script_search_mode - enum, prefix | exact | partial
- filter - filter cells by following conditions, all conditions are optional
- script: if search script type is lock, filter cells by type script prefix, and vice versa
- script_len_range: [u64; 2], filter cells by script len range, [inclusive, exclusive]
- output_data: filter cells by output data
- output_data_filter_mode: enum, prefix | exact | partial
- output_data_len_range: [u64; 2], filter cells by output data len range, [inclusive, exclusive]
- output_capacity_range: [u64; 2], filter cells by output capacity range, [inclusive, exclusive]
- block_range: [u64; 2], filter cells by block number range, [inclusive, exclusive]
Returns
- capacity - total capacity
- block_hash - indexed tip block hash
- block_number - indexed tip block number
Examples
Same as CKB Indexer.
Module Stats
RPC Module Stats for getting various statistic data.
Method get_blockchain_info
-
get_blockchain_info()
-
result:
ChainInfo
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
-
get_deployments_info()
-
result:
DeploymentsInfo
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"
}
}
}
}
}
RPC Module Subscription that CKB node will push new messages to subscribers, support with WebSocket or TCP.
RPC subscriptions require a full duplex connection. CKB offers such connections in the form of
TCP (enable with rpc.tcp_listen_address
configuration option) and WebSocket (enable with
rpc.ws_listen_address
).
Examples
TCP RPC subscription:
telnet localhost 18114
> {"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["new_tip_header"]}
< {"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
topic
- Subscription topic (enum: new_tip_header | new_tip_block | new_transaction | proposed_transaction | rejected_transaction)
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
- the first item type is
PoolTransactionEntry
, and - the second item type is
PoolTransactionReject
.
Examples
Subscribe Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "subscribe",
"params": [
"new_tip_header"
]
}
Subscribe Response
{
"id": 42,
"jsonrpc": "2.0",
"result": "0xf3"
}
Method unsubscribe
unsubscribe(id)
id
:string
- result:
boolean
Unsubscribes from a subscribed topic.
Params
id
- Subscription ID
Examples
Unsubscribe Request
{
"id": 42,
"jsonrpc": "2.0",
"method": "unsubscribe",
"params": [
"0xf3"
]
}
Unsubscribe Response
{
"id": 42,
"jsonrpc": "2.0",
"result": true
}
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.
-
cancel
:Uint32
- Cancel a previous sent alert. -
id
:Uint32
- The identifier of the alert. Clients use id to filter duplicated alerts. -
message
:string
- Alert message. -
notice_until
:Uint64
- The alert is expired after this timestamp. -
priority
:Uint32
- Alerts are sorted by priority, highest first. -
signatures
:Array<
JsonBytes
>
- The list of required signatures.
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 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.
-
id
:Uint32
- The unique alert ID. -
message
:string
- Alert message. -
notice_until
:Uint64
- The alert is expired after this timestamp. -
priority
:Uint32
- Alerts are sorted by priority, highest first.
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 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 AncestorsScoreSortKey
A struct as a sorted key for tx-pool
Fields
AncestorsScoreSortKey
is a JSON object with the following fields.
-
ancestors_fee
:Uint64
- Ancestors fee -
ancestors_weight
:Uint64
- Ancestors weight -
fee
:Uint64
- Fee -
weight
:Uint64
- Weight
Type BannedAddr
A banned P2P address.
Fields
BannedAddr
is a JSON object with the following fields.
-
address
:string
- The P2P address.Example: "/ip4/192.168.0.2/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS"
-
ban_reason
:string
- The reason. -
ban_until
:Uint64
- The address is banned until this time. -
created_at
:Uint64
- When this address is banned.
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.
-
header
:Header
- The block header. -
proposals
:Array<
ProposalShortId
>
- The proposal IDs in the block body. -
transactions
:Array<
Transaction
>
- The transactions in the block body. -
uncles
:Array<
UncleBlock
>
- The uncles blocks in the block body.
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.
-
finalized_at
:H256
- The block hash of the block which creates the rewards as cells in its cellbase transaction. -
issuance
:BlockIssuance
- Block base rewards. -
miner_reward
:MinerReward
- Block rewards for miners. -
txs_fee
:Uint64
- The total fees of all transactions committed in the block.
Type BlockFilter
Block filter data and hash.
Fields
BlockFilter
is a JSON object with the following fields.
-
data
:JsonBytes
- The hex-encoded filter data of the block -
hash
:Byte32
- The filter hash, blake2b hash of the parent block filter hash and the filter data, blake2b(parent_block_filter_hash | current_block_filter_data)
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.
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.
-
bytes_limit
:Uint64
- The block serialized size limit.Miners must keep the block size below this limit, otherwise, the CKB node will reject the block submission.
It is guaranteed that the block does not exceed the limit if miners do not add new transaction commitments.
-
cellbase
:CellbaseTemplate
- Provided cellbase transaction template.Miners must use it as the cellbase transaction without changes in the assembled block.
-
compact_target
:Uint32
- The compacted difficulty target for the new block.Miners must use it unchanged in the assembled block.
-
current_time
:Uint64
- The timestamp for the new block.CKB node guarantees that this timestamp is larger than the median of the previous 37 blocks.
Miners can increase it to the current time. It is not recommended to decrease it, since it may violate the median block timestamp consensus rule.
-
cycles_limit
:Uint64
- The cycles limit.Miners must keep the total cycles below this limit, otherwise, the CKB node will reject the block submission.
It is guaranteed that the block does not exceed the limit if miners do not add new transactions to the block.
-
dao
:Byte32
- Reference DAO field.This field is only valid when miners use all and only use the provided transactions in the template. Two fields must be updated when miners want to select transactions:
S_i
, bytes 16 to 23U_i
, bytes 24 to 31
See RFC Deposit and Withdraw in Nervos DAO.
-
epoch
:Uint64
- The epoch progress information for the new block.Miners must use it unchanged in the assembled block.
-
number
:Uint64
- The block number for the new block.Miners must use it unchanged in the assembled block.
-
parent_hash
:H256
- The parent block hash of the new block.Miners must use it unchanged in the assembled block.
-
proposals
:Array<
ProposalShortId
>
- Provided proposal ids list of transactions for the new block. -
transactions
:Array<
TransactionTemplate
>
- Provided valid transactions which can be committed in the new block.Miners must include the transactions marked as
required
in the assembled new block. -
uncles
:Array<
UncleTemplate
>
- Provided valid uncle blocks candidates for the new block.Miners must include the uncles marked as
required
in the assembled new block. -
uncles_count_limit
:Uint64
- The uncle count limit.Miners must keep the uncles count below this limit, otherwise, the CKB node will reject the block submission.
-
version
:Uint32
- Block version.Miners must use it unchanged in the assembled block.
-
work_id
:Uint64
- Work ID. The miner must submit the new assembled and resolved block using the same work ID.
Type BlockView
The JSON view of a Block including header and body.
Fields
BlockView
is a JSON object with the following fields.
-
header
:HeaderView
- The block header. -
proposals
:Array<
ProposalShortId
>
- The proposal IDs in the block body. -
transactions
:Array<
TransactionView
>
- The transactions in the block body. -
uncles
:Array<
UncleBlockView
>
- The uncles blocks in the block body.
Type BlockWithCyclesResponse
BlockResponse with cycles format wrapper
Fields
BlockWithCyclesResponse
is a JSON object with the following fields.
block
:ResponseFormat<BlockView>
- The block structure
Type Buried
Represent soft fork deployments where the activation epoch is hard-coded into the client implementation
Fields
Buried
is a JSON object with the following fields.
-
active
:boolean
- Whether the rules are active -
epoch
:Uint64
- The first epoch which the rules will be enforced -
status
:SoftForkStatus
- SoftFork status
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.
output
:CellOutput
- Cell fields appears in the transactionoutputs
array.
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.
-
previous_output
:OutPoint
- Reference to the input cell. -
since
:Uint64
- Restrict when the transaction can be committed into the chain.See the RFC Transaction valid since.
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.
-
capacity
:Uint64
- The cell 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.
-
lock
:Script
- The lock script.
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.
-
status
:string
- Status of the cell.Allowed values: "live", "dead", "unknown".
live
- The transaction creating this cell is in the chain, and there are no transactions found in the chain that uses this cell as an input.dead
- (Deprecated: the dead status will be removed since 0.36.0, please do not rely on the logic that differentiates dead and unknown cells.) The transaction creating this cell is in the chain, and a transaction is found in the chain which uses this cell as an input.unknown
- CKB does not know the status of the cell. Either the transaction creating this cell is not in the chain yet, or it is no longer live.
Type CellbaseTemplate
The cellbase transaction template of the new block for miners.
Fields
CellbaseTemplate
is a JSON object with the following fields.
-
data
:Transaction
- The cellbase transaction. -
hash
:H256
- The cellbase transaction hash.
Type ChainInfo
Chain information.
Fields
ChainInfo
is a JSON object with the following fields.
-
alerts
:Array<
AlertMessage
>
- Active alerts stored in the local node. -
chain
:string
- The network name.Examples:
- "ckb" - Mirana the mainnet.
- "ckb_testnet" - Pudge the testnet.
-
difficulty
:string
- Current difficulty.Decoded from the epoch
compact_target
. -
epoch
:Uint64
- The epoch information of tip block in the chain. -
is_initial_block_download
:boolean
- Whether the local node is in IBD, Initial Block Download.When a node starts and its chain tip timestamp is far behind the wall clock, it will enter the IBD until it catches up the synchronization.
During IBD, the local node only synchronizes the chain with one selected remote node and stops responding the most P2P requests.
-
median_time
:Uint64
- The median time of the last 37 blocks, including the tip block.
Type Consensus
Consensus defines various parameters that influence chain consensus
Fields
Consensus
is a JSON object with the following fields.
-
block_version
:Uint32
- The block version number supported -
cellbase_maturity
:Uint64
- The Cellbase maturity -
dao_type_hash
:H256
- The dao type hash -
epoch_duration_target
:Uint64
- The expected epoch_duration -
genesis_hash
:H256
- The genesis block hash -
hardfork_features
:HardForks
- Hardfork features -
id
:string
- Names the network. -
initial_primary_epoch_reward
:Uint64
- The initial primary_epoch_reward -
max_block_bytes
:Uint64
- Maximum number of bytes to use for the entire block -
max_block_cycles
:Uint64
- Maximum cycles that all the scripts in all the commit transactions can take -
max_block_proposals_limit
:Uint64
- The Limit to the number of proposals per block -
max_uncles_num
:Uint64
- The maximum amount of uncles allowed for a block -
median_time_block_count
:Uint64
- This parameter indicates the count of past blocks used in the median time calculation -
orphan_rate_target
:string
- The expected orphan_rate -
permanent_difficulty_in_dummy
:boolean
- Keep difficulty be permanent if the pow is dummy -
primary_epoch_reward_halving_interval
:Uint64
- Primary reward is cut in half every halving_interval epoch -
proposer_reward_ratio
:string
- The two-step-transaction-confirmation proposer reward ratio -
secondary_epoch_reward
:Uint64
- The secondary primary_epoch_reward -
softforks
: -HashMap<DeploymentPos, SoftFork>
- Softforks -
tx_proposal_window
:ProposalWindow
- The two-step-transaction-confirmation proposal window -
tx_version
:Uint32
- The tx version number supported -
type_id_code_hash
:H256
- The "TYPE_ID" in hex
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
.
Type DepType
The dep cell type. Allowed values: "code" and "dep_group".
It's an enum value from one of:
- code : Type "code".
Use the cell itself as the dep cell.
- dep_group : Type "dep_group".
The cell is a dep group which members are cells. These members are used as dep cells instead of the group itself.
The dep group stores the array of OutPoint
s serialized via molecule in the cell data. Each OutPoint
points to one cell member.
Type Deployment
RFC0043 deployment params
Fields
Deployment
is a JSON object with the following fields.
-
bit
:integer
- Determines which bit in theversion
field of the block is to be used to signal the softfork lock-in and activation. It is chosen from the set {0,1,2,...,28}. -
min_activation_epoch
:Uint64
- Specifies the epoch at which the softfork is allowed to become active. -
period
:Uint64
- Specifies length of epochs of the signalling period. -
start
:Uint64
- Specifies the first epoch in which the bit gains meaning. -
threshold
:Ratio
- Specifies the minimum ratio of block perperiod
, which indicate the locked_in of the softfork during theperiod
. -
timeout
:Uint64
- Specifies an epoch at which the miner signaling ends. Once this epoch has been reached, if the softfork has not yet locked_in (excluding this epoch block's bit state), the deployment is considered failed on all descendants of the block.
Type DeploymentInfo
An object containing various state info regarding deployments of consensus changes
Fields
DeploymentInfo
is a JSON object with the following fields.
-
bit
:integer
- determines which bit in theversion
field of the block is to be used to signal the softfork lock-in and activation. It is chosen from the set {0,1,2,...,28}. -
min_activation_epoch
:Uint64
- specifies the epoch at which the softfork is allowed to become active. -
period
:Uint64
- the length in epochs of the signalling period -
since
:Uint64
- The first epoch which the current state applies -
start
:Uint64
- specifies the first epoch in which the bit gains meaning. -
state
:DeploymentState
- With each epoch and softfork, we associate a deployment state. The possible states are:DEFINED
is the first state that each softfork starts. The blocks of 0 epoch is by definition in this state for each deployment.STARTED
for all blocks reach or past the start_epoch.LOCKED_IN
for one period after the first period with STARTED blocks of which at least threshold has the associated bit set in version.ACTIVE
for all blocks after the LOCKED_IN period.FAILED
for all blocks after the timeout_epoch, if LOCKED_IN was not reached.
-
threshold
:Ratio
- the ratio of blocks with the version bit set required to activate the feature -
timeout
:Uint64
- specifies an epoch at which the miner signaling ends. Once this epoch has been reached, if the softfork has not yet locked_in (excluding this epoch block's bit state), the deployment is considered failed on all descendants of the block.
Type DeploymentState
The possible softfork deployment state
It's an enum value from one of:
- defined : First state that each softfork starts. The 0 epoch is by definition in this state for each deployment.
- started : For epochs past the
start
epoch. - locked_in : For one epoch after the first epoch period with STARTED epochs of which at least
threshold
has the associated bit set inversion
. - active : For all epochs after the LOCKED_IN epoch.
- failed : For one epoch period past the
timeout_epoch
, if LOCKED_IN was not reached.
Type DeploymentsInfo
Chain information.
Fields
DeploymentsInfo
is a JSON object with the following fields.
-
deployments
: -{ [ key:
DeploymentPos
]:
DeploymentInfo
}
deployments info -
epoch
:Uint64
- requested block epoch -
hash
:H256
- requested block hash
Type EntryCompleted
Transaction's verify result by test_tx_pool_accept
Fields
EntryCompleted
is a JSON object with the following fields.
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 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):
- The highest 16 bits represent the epoch length
- The next 16 bits represent the current block index in the epoch, starting from 0.
- The lowest 24 bits represent the current epoch number.
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.
-
compact_target
:Uint32
- The difficulty target for any block in this epoch. -
length
:Uint64
- The number of blocks in this epoch. -
number
:Uint64
- Consecutive epoch number starting from 0. -
start_number
:Uint64
- The block number of the first block in the epoch.It also equals the total count of blocks in all the epochs which epoch number is less than this epoch.
Type EstimateCycles
Response result of the RPC method estimate_cycles
.
Fields
EstimateCycles
is a JSON object with the following fields.
cycles
:Uint64
- The count of cycles that the VM has consumed to verify this transaction.
Type EstimateMode
The fee estimate mode.
It's an enum value from one of:
- no_priority : No priority, expect the transaction to be committed in 1 hour.
- low_priority : Low priority, expect the transaction to be committed in 30 minutes.
- medium_priority : Medium priority, expect the transaction to be committed in 10 minutes.
- high_priority : High priority, expect the transaction to be committed as soon as possible.
Type ExtraLoggerConfig
Runtime logger config for extra loggers.
Fields
ExtraLoggerConfig
is a JSON object with the following fields.
-
filter
:string
- Sets log levels for different modules.Examples
Set the log level to info for all modules
info
Set the log level to debug for listed modules and info for other modules.
info,ckb-rpc=debug,ckb-sync=debug,ckb-relay=debug,ckb-tx-pool=debug,ckb-network=debug
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 HardForkFeature
The information about one hardfork feature.
Fields
HardForkFeature
is a JSON object with the following fields.
rfc
:string
- The related RFC ID.
Type HardForks
Hardfork information
Fields
HardForks
is a JSON object with the following fields.
inner
:Array<
HardForkFeature
>
Type Header
The block header.
Refer to RFC CKB Block Structure.
Fields
Header
is a JSON object with the following fields.
-
compact_target
:Uint32
- The block difficulty target.It can be converted to a 256-bit target. Miners must ensure the Eaglesong of the header is within the target.
-
dao
:Byte32
- DAO fields.See RFC Deposit and Withdraw in Nervos DAO.
-
epoch
:Uint64
- The epoch information of this block.See
EpochNumberWithFraction
for details. -
extra_hash
:H256
- The hash onuncles
and extension in the block body.The uncles hash is all zeros when
uncles
is empty, or the hash on all the uncle header hashes concatenated together. The extension hash is the hash of the extension. The extra hash is the hash on uncles hash and extension hash concatenated together.Notice
This field is renamed from
uncles_hash
since 0.100.0. More details can be found in CKB RFC 0031. -
nonce
:Uint128
- Miner can modify this field to find a proper value such that the Eaglesong of the header is within the target encoded fromcompact_target
. -
number
:Uint64
- The consecutive block number starting from 0. -
parent_hash
:H256
- The header hash of the parent block. -
proposals_hash
:H256
- The hash onproposals
in the block body.It is all zeros when
proposals
is empty, or the hash on all the bytes concatenated together. -
timestamp
:Uint64
- The block timestamp.It is a Unix timestamp in milliseconds (1 second = 1000 milliseconds).
Miners should put the time when the block is created in the header, however, the precision is not guaranteed. A block with a higher block number may even have a smaller timestamp.
-
transactions_root
:H256
- The commitment to all the transactions in the block.It is a hash on two Merkle Tree roots:
- The root of a CKB Merkle Tree, which items are the transaction hashes of all the transactions in the block.
- The root of a CKB Merkle Tree, but the items are the transaction witness hashes of all the transactions in the block.
-
version
:Uint32
- The block version.It must equal to 0 now and is reserved for future upgrades.
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.
-
compact_target
:Uint32
- The block difficulty target.It can be converted to a 256-bit target. Miners must ensure the Eaglesong of the header is within the target.
-
dao
:Byte32
- DAO fields.See RFC Deposit and Withdraw in Nervos DAO.
-
epoch
:Uint64
- The epoch information of this block.See
EpochNumberWithFraction
for details. -
extra_hash
:H256
- The hash onuncles
and extension in the block body.The uncles hash is all zeros when
uncles
is empty, or the hash on all the uncle header hashes concatenated together. The extension hash is the hash of the extension. The extra hash is the hash on uncles hash and extension hash concatenated together.Notice
This field is renamed from
uncles_hash
since 0.100.0. More details can be found in CKB RFC 0031. -
hash
:H256
- The header hash. It is also called the block hash. -
nonce
:Uint128
- Miner can modify this field to find a proper value such that the Eaglesong of the header is within the target encoded fromcompact_target
. -
number
:Uint64
- The consecutive block number starting from 0. -
parent_hash
:H256
- The header hash of the parent block. -
proposals_hash
:H256
- The hash onproposals
in the block body.It is all zeros when
proposals
is empty, or the hash on all the bytes concatenated together. -
timestamp
:Uint64
- The block timestamp.It is a Unix timestamp in milliseconds (1 second = 1000 milliseconds).
Miners should put the time when the block is created in the header, however, the precision is not guaranteed. A block with a higher block number may even have a smaller timestamp.
-
transactions_root
:H256
- The commitment to all the transactions in the block.It is a hash on two Merkle Tree roots:
- The root of a CKB Merkle Tree, which items are the transaction hashes of all the transactions in the block.
- The root of a CKB Merkle Tree, but the items are the transaction witness hashes of all the transactions in the block.
-
version
:Uint32
- The block version.It must equal to 0 now and is reserved for future upgrades.
Type IndexerCell
Live cell
Fields
IndexerCell
is a JSON object with the following fields.
-
block_number
:Uint64
- the number of the transaction committed in the block -
out_point
:OutPoint
- reference to a cell via transaction hash and output index -
output
:CellOutput
- the fields of an output cell -
tx_index
:Uint32
- the position index of the transaction committed in the block
Type IndexerCellType
Cell type
It's an enum value from one of:
- input : Input
- output : Output
Type IndexerCellsCapacity
Cells capacity
Fields
IndexerCellsCapacity
is a JSON object with the following fields.
-
block_hash
:H256
- indexed tip block hash -
block_number
:Uint64
- indexed tip block number -
capacity
:Uint64
- total capacity
Type IndexerOrder
Order Desc | Asc
It's an enum value from one of:
- desc : Descending order
- asc : Ascending order
Type IndexerPagination<IndexerCell>
IndexerPagination wraps objects array and last_cursor to provide paging
Fields
IndexerPagination<IndexerCell>
is a JSON object with the following fields.
-
last_cursor
:JsonBytes
- pagination parameter -
objects
:Array<
IndexerCell
>
- objects collection
Type IndexerPagination<IndexerTx>
IndexerPagination wraps objects array and last_cursor to provide paging
Fields
IndexerPagination<IndexerTx>
is a JSON object with the following fields.
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 IndexerScriptType
ScriptType Lock
| Type
It's an enum value from one of:
- lock : Lock
- type : Type
Type IndexerSearchKey
SearchKey represent indexer support params
Fields
IndexerSearchKey
is a JSON object with the following fields.
-
script
:Script
- Script -
script_type
:IndexerScriptType
- Script Type
Type IndexerSearchKeyFilter
IndexerSearchKeyFilter represent indexer params filter
Fields
IndexerSearchKeyFilter
is a JSON object with the following fields.
block_range
:IndexerRange
|
null
filter cells by block number rangeoutput_capacity_range
:IndexerRange
|
null
filter cells by output capacity rangeoutput_data
:JsonBytes
|
null
filter cells by output dataoutput_data_filter_mode
:IndexerSearchMode
|
null
output data filter mode, optional default isprefix
output_data_len_range
:IndexerRange
|
null
filter cells by output data len rangescript
:Script
|
null
if search script type is lock, filter cells by type script prefix, and vice versascript_len_range
:IndexerRange
|
null
filter cells by script len range
Type IndexerSearchMode
IndexerSearchMode represent search mode, default is prefix search
It's an enum value from one of:
- prefix : Mode
prefix
search with prefix - exact : Mode
exact
search with exact match - partial : Mode
partial
search with partial match
Type IndexerTip
Indexer tip information
Fields
IndexerTip
is a JSON object with the following fields.
Type IndexerTx
Indexer Transaction Object
Type IndexerTxWithCell
Ungrouped Tx inner type
Fields
IndexerTxWithCell
is a JSON object with the following fields.
-
block_number
:Uint64
- the number of the transaction committed in the block -
io_index
:Uint32
- the position index of the cell in the transaction inputs or outputs -
io_type
:IndexerCellType
- io type -
tx_hash
:H256
- transaction hash -
tx_index
:Uint32
- the position index of the transaction committed in the block
Type IndexerTxWithCells
Grouped Tx inner type
Fields
IndexerTxWithCells
is a JSON object with the following fields.
-
block_number
:Uint64
- the number of the transaction committed in the block -
cells
:Array<
(IndexerCellType
,Uint32
)>
- Array [(io_type, io_index)] -
tx_hash
:H256
- transaction hash -
tx_index
:Uint32
- the position index of the transaction committed in the block
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.
-
active
:boolean
- Whether this node is active.An inactive node ignores incoming p2p messages and drops outgoing messages.
-
addresses
:Array<
NodeAddress
>
- P2P addresses of this node.A node can have multiple addresses.
-
connections
:Uint64
- Count of currently connected peers. -
node_id
:string
- The unique node ID derived from the p2p private key.The private key is generated randomly on the first boot.
-
protocols
:Array<
LocalNodeProtocol
>
- Supported protocols. -
version
:string
- CKB node version.Example: "version": "0.34.0 (f37f598 2020-07-17)"
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.
-
id
:Uint64
- Unique protocol ID. -
name
:string
- Readable protocol name. -
support_versions
:Array<
string
>
- Supported versions.See Semantic Version about how to specify a version.
Type MainLoggerConfig
Runtime logger config.
Fields
MainLoggerConfig
is a JSON object with the following fields.
-
color
:boolean
|
null
Whether using color when printing the logs to the process stdout.null
means keeping the current option unchanged. -
filter
:string
|
null
Sets log levels for different modules.null
means keeping the current option unchanged.Examples
Set the log level to info for all modules
info
Set the log level to debug for listed modules and info for other modules.
info,ckb-rpc=debug,ckb-sync=debug,ckb-relay=debug,ckb-tx-pool=debug,ckb-network=debug
-
to_file
:boolean
|
null
Whether appending the logs to the log file.null
means keeping the current option unchanged. -
to_stdout
:boolean
|
null
Whether printing the logs to the process stdout.null
means keeping the current option unchanged.
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.
-
indices
:Array<
Uint32
>
- Leaves indices in the CBMT that are proved present in the block.These are indices in the CBMT tree not the transaction indices in the block.
-
lemmas
:Array<
H256
>
- Hashes of all siblings along the paths to root.
Type MinerReward
Block rewards for miners.
Fields
MinerReward
is a JSON object with the following fields.
-
committed
:Uint64
- The transaction fees that are rewarded to miners because the transaction is committed in the block.Miners get 60% of the transaction fee for each transaction committed in the block.
-
primary
:Uint64
- The primary base block reward allocated to miners. -
proposal
:Uint64
- The transaction fees that are rewarded to miners because the transaction is proposed in the block or its uncles.Miners get 40% of the transaction fee for each transaction proposed in the block and committed later in its active commit window.
-
secondary
:Uint64
- The secondary base block reward allocated to miners.
Type NodeAddress
Node P2P address and score.
Fields
NodeAddress
is a JSON object with the following fields.
-
address
:string
- P2P address.This is the same address used in the whitelist in ckb.toml.
Example: "/ip4/192.168.0.2/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS"
-
score
:Uint64
- Address score.A higher score means a higher probability of a successful connection.
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.
-
index
:Uint32
- The output index of the cell in the transaction specified bytx_hash
. -
tx_hash
:H256
- Transaction hash in which the cell is an output.
Type OutputsValidator
Transaction output validators that prevent common mistakes.
It's an enum value from one of:
- passthrough : the default validator, bypass output checking, thus allow any kind of transaction outputs.
- well_known_scripts_only : restricts the lock script and type script usage, see more information on https://github.com/nervosnetwork/ckb/wiki/Transaction-%C2%BB-Default-Outputs-Validator
Type PeerSyncState
The chain synchronization state between the local node and a remote node.
Fields
PeerSyncState
is a JSON object with the following fields.
-
can_fetch_count
:Uint64
- The count of blocks are available for concurrency download. -
inflight_count
:Uint64
- The count of concurrency downloading blocks. -
unknown_header_list_size
:Uint64
- The total size of unknown header list.Deprecated: this is an internal state and will be removed in a future release.
Type PoolTransactionReject
TX reject message, PoolTransactionReject
is a JSON object with following fields.
type
: the Reject type with following enum valuesdescription
:string
- Detailed description about why the transaction is rejected.
An enum value from one of:
LowFeeRate
: Transaction fee lower than configExceededMaximumAncestorsCount
: Transaction exceeded maximum ancestors count limitExceededTransactionSizeLimit
: Transaction exceeded maximum size limitFull
: Transaction are replaced because the pool is fullDuplicated
: Transaction already exists in transaction_poolMalformed
: Malformed transactionDeclaredWrongCycles
: Declared wrong cyclesResolve
: Resolve failedVerification
: Verification failedExpiry
: Transaction expiredRBFRejected
: RBF rejectedInvalidated
: Invalidated rejected
Type PoolTxDetailInfo
A Tx details info in tx-pool.
Fields
PoolTxDetailInfo
is a JSON object with the following fields.
-
ancestors_count
:Uint64
- The ancestors count of tx -
descendants_count
:Uint64
- The descendants count of tx -
entry_status
:string
- The detailed status in tx-pool,pending
,gap
,proposed
-
pending_count
:Uint64
- The pending(pending
andgap
) count -
proposed_count
:Uint64
- The proposed count -
rank_in_pending
:Uint64
- The rank in pending, starting from 0 -
score_sortkey
:AncestorsScoreSortKey
- The score key details, useful to debug -
timestamp
:Uint64
- The time added into tx-pool
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 conditi