ckb_rpc/module/
mod.rs

1//! CKB RPC modules
2//!
3//! This RPC document is generated by Rust Doc, so it will take some concept conversions to map
4//! from the Rust structures to the JSONRPC.
5//!
6//! ## JSONRPC Methods
7//!
8//! The section [Traits](#traits) lists all the RPC modules. CKB allows enabling and disabling RPC
9//! methods by modules. The default enabled ones are enabled modules are "Net", "Pool", "Miner",
10//! "Chain", "Stats", "Subscription", "Experiment". As you can see, the `Rpc` suffix is removed in
11//! the config file.
12//!
13//! The section *Required methods* lists all the RPC methods in the module. See module
14//! [PoolRpc](trait.PoolRpc.html#required-methods).
15//!
16//! Use the RPC [`send_transaction`](trait.PoolRpc.html#tymethod.send_transaction) in the module `PoolRpc` as an example.
17//!
18//! ```text
19//! fn send_transaction(
20//!    ^^^^^^^^^^^^^^^^
21//!                `-- JSONRPC method name
22//!     &self,
23//!     ^^^^^
24//!       `-- ignore this
25//!
26//!   ,--------------------------------------------
27//!   | tx: Transaction,
28//!   | outputs_validator: Option<OutputsValidator>
29//!   `--------------------------------------------
30//!       `-- Request params list as pairs of "name: Type"
31//!
32//! ) -> Result<H256>;
33//!             ^^^^
34//!              `-- Response Type
35//! ```
36//!
37//! * `send_transaction` - The JSONRPC method name.
38//! * `tx: Transaction` - The first param in the request params list which name is `tx` and type is `Transaction`. The type links to the JSON object definition of a CKB transaction.
39//! * `outputs_validator: Option<OutputsValidator>` - The second param. The `Option` shows that this argument is optional. The document for `OutputsValidator` shows that `outputs_validator` is an enum type which possible values include "well_known_scripts_only" and "passthrough".
40//! * `-> Result<H256>` - The type inside the `Result` after `->` is the response type. In this example, it is `H256` which is a 32-bytes binary encoded as a hex string.
41//!
42//! The RPC errors are documented in [`RPCError`](../enum.RPCError.html).
43//!
44//! ## JSONRPC Deprecation Process
45//!
46//! A CKB RPC method is deprecated in three steps.
47//!
48//! First, the method is marked as deprecated in the CKB release notes and RPC document. However,
49//! the RPC method is still available. The RPC document will have the suggestion of alternative
50//! solutions.
51//!
52//! The CKB dev team will disable any deprecated RPC methods starting from the next minor version
53//! release. Users can enable the deprecated methods via the config file option `rpc.enable_deprecated_rpc`.
54//!
55//! Once a deprecated method is disabled, the CKB dev team will remove it in a future minor version release.
56//!
57//! For example, a method is marked as deprecated in 0.35.0, it can be disabled in 0.36.0 and
58//! removed in 0.37.0. The minor versions are released monthly, so there's at least a two-month
59//! buffer for a deprecated RPC method.
60//!
61//! ## JSON Cheatsheet
62//!
63//! CKB uses a framework to serialize into and deserialize from JSON. Some Rust std-lib
64//! structures will be used in requests and responses. The following cheatsheet shows how to
65//! map them into JSON values.
66//!
67//! | Rust        | JSON                 |
68//! | ----------- | -------------------- |
69//! | `()`        | `null`               |
70//! | `bool`      | `boolean`            |
71//! | `String`    | `string`             |
72//! | `Option<T>` | either `null` or `T` |
73//! | `Vec<T>`    | array of `T`         |
74//!
75//! CKB RPC does not use JSON numbers because of the precision problem. Float point numbers are not
76//! used in the RPC, and integers are encoded as 0x-prefixed hex string such as `0x10` for decimal
77//! value 16.
78//!
79//! The other types will have their own documentation pages. Unless the JSON format is explicitly
80//! described in the documentation page, the rust Struct is serialized as a JSON object, and Enum is
81//! serialized as a JSON string.
82//!
83//! For example, `OutPoint` is a struct having the following fields
84//!
85//! ```text
86//! tx_hash: H256
87//! index: Uint32
88//! ```
89//!
90//! An example `OutPoint` JSON looks like
91//!
92//! ```json
93//! {
94//!   "index": "0xffffffff",
95//!    "tx_hash": "0x0000000000000000000000000000000000000000000000000000000000000000"
96//! }
97//! ```
98//!
99//! `Status` is a Rust enum
100//!
101//! ```text
102//! pub enum Status {
103//!     Pending,
104//!     Proposed,
105//!     Committed,
106//! }
107//! ```
108//!
109//! The enum values are represented as JSON strings in the lowercase, underscore-concatenated form. So, in
110//! JSON, `Status` can be one of "pending", "proposed" or "committed".
111#![allow(deprecated)]
112
113mod alert;
114pub(crate) mod chain;
115mod debug;
116mod experiment;
117mod indexer;
118mod miner;
119mod net;
120pub(crate) mod pool;
121mod rich_indexer;
122mod stats;
123mod subscription;
124mod terminal;
125mod test;
126
127pub(crate) use self::alert::AlertRpcImpl;
128pub(crate) use self::chain::ChainRpcImpl;
129pub(crate) use self::debug::DebugRpcImpl;
130pub(crate) use self::experiment::ExperimentRpcImpl;
131pub(crate) use self::indexer::IndexerRpcImpl;
132pub(crate) use self::miner::MinerRpcImpl;
133pub(crate) use self::net::NetRpcImpl;
134pub(crate) use self::pool::PoolRpcImpl;
135pub(crate) use self::rich_indexer::RichIndexerRpcImpl;
136pub(crate) use self::stats::StatsRpcImpl;
137pub(crate) use self::subscription::SubscriptionRpcImpl;
138pub(crate) use self::terminal::TerminalRpcImpl;
139pub(crate) use self::test::IntegrationTestRpcImpl;
140
141pub use self::alert::{AlertRpc, add_alert_rpc_methods, alert_rpc_doc};
142pub use self::chain::{ChainRpc, add_chain_rpc_methods, chain_rpc_doc};
143pub use self::debug::{DebugRpc, add_debug_rpc_methods, debug_rpc_doc};
144pub use self::experiment::{ExperimentRpc, add_experiment_rpc_methods, experiment_rpc_doc};
145pub use self::indexer::{IndexerRpc, add_indexer_rpc_methods, indexer_rpc_doc};
146pub use self::miner::{MinerRpc, add_miner_rpc_methods, miner_rpc_doc};
147pub use self::net::{NetRpc, add_net_rpc_methods, net_rpc_doc};
148pub use self::pool::{PoolRpc, add_pool_rpc_methods, pool_rpc_doc};
149pub use self::rich_indexer::{RichIndexerRpc, add_rich_indexer_rpc_methods, rich_indexer_rpc_doc};
150pub use self::stats::{StatsRpc, add_stats_rpc_methods, stats_rpc_doc};
151pub use self::subscription::{SubscriptionRpc, add_subscription_rpc_methods, subscription_rpc_doc};
152pub use self::terminal::{TerminalCache, TerminalRpc, add_terminal_rpc_methods, terminal_rpc_doc};
153pub use self::test::{
154    IntegrationTestRpc, add_integration_test_rpc_methods, integration_test_rpc_doc,
155};
ckb_rpc/module/mod.rs

ckb_rpc/module/
mod.rs
