kona_rpc/
jsonrpsee.rs

1//! The Optimism RPC API using `jsonrpsee`
2
3use crate::{OutputResponse, SafeHeadResponse};
4use alloy_eips::BlockNumberOrTag;
5use alloy_primitives::B256;
6use core::net::IpAddr;
7use ipnet::IpNet;
8use jsonrpsee::{
9    core::{RpcResult, SubscriptionResult},
10    proc_macros::rpc,
11};
12use kona_genesis::RollupConfig;
13use kona_p2p::{PeerCount, PeerDump, PeerInfo, PeerStats};
14use kona_protocol::SyncStatus;
15use op_alloy_rpc_types_engine::OpExecutionPayloadEnvelope;
16
17#[cfg_attr(all(target_arch = "wasm32", target_os = "unknown"), allow(unused_imports))]
18use getrandom as _; // required for compiling wasm32-unknown-unknown
19
20// Re-export apis defined in upstream `op-alloy-rpc-jsonrpsee`
21pub use op_alloy_rpc_jsonrpsee::traits::{MinerApiExtServer, OpAdminApiServer};
22
23/// Optimism specified rpc interface.
24///
25/// https://docs.optimism.io/builders/node-operators/json-rpc
26/// https://github.com/ethereum-optimism/optimism/blob/8dd17a7b114a7c25505cd2e15ce4e3d0f7e3f7c1/op-node/node/api.go#L114
27#[cfg_attr(not(feature = "client"), rpc(server, namespace = "optimism"))]
28#[cfg_attr(feature = "client", rpc(server, client, namespace = "optimism"))]
29pub trait RollupNodeApi {
30    /// Get the output root at a specific block.
31    #[method(name = "outputAtBlock")]
32    async fn op_output_at_block(&self, block_number: BlockNumberOrTag)
33    -> RpcResult<OutputResponse>;
34
35    /// Gets the safe head at an L1 block height.
36    #[method(name = "safeHeadAtL1Block")]
37    async fn op_safe_head_at_l1_block(
38        &self,
39        block_number: BlockNumberOrTag,
40    ) -> RpcResult<SafeHeadResponse>;
41
42    /// Get the synchronization status.
43    #[method(name = "syncStatus")]
44    async fn op_sync_status(&self) -> RpcResult<SyncStatus>;
45
46    /// Get the rollup configuration parameters.
47    #[method(name = "rollupConfig")]
48    async fn op_rollup_config(&self) -> RpcResult<RollupConfig>;
49
50    /// Get the software version.
51    #[method(name = "version")]
52    async fn op_version(&self) -> RpcResult<String>;
53}
54
55/// The opp2p namespace handles peer interactions.
56#[cfg_attr(not(feature = "client"), rpc(server, namespace = "opp2p"))]
57#[cfg_attr(feature = "client", rpc(server, client, namespace = "opp2p"))]
58pub trait OpP2PApi {
59    /// Returns information of node
60    #[method(name = "self")]
61    async fn opp2p_self(&self) -> RpcResult<PeerInfo>;
62
63    /// Returns information of peers
64    #[method(name = "peerCount")]
65    async fn opp2p_peer_count(&self) -> RpcResult<PeerCount>;
66
67    /// Returns information of peers. If `connected` is true, only returns connected peers.
68    #[method(name = "peers")]
69    async fn opp2p_peers(&self, connected: bool) -> RpcResult<PeerDump>;
70
71    /// Returns statistics of peers
72    #[method(name = "peerStats")]
73    async fn opp2p_peer_stats(&self) -> RpcResult<PeerStats>;
74
75    /// Returns the discovery table
76    #[method(name = "discoveryTable")]
77    async fn opp2p_discovery_table(&self) -> RpcResult<Vec<String>>;
78
79    /// Blocks the given peer
80    #[method(name = "blockPeer")]
81    async fn opp2p_block_peer(&self, peer: String) -> RpcResult<()>;
82
83    /// Unblocks the given peer
84    #[method(name = "unblockPeer")]
85    async fn opp2p_unblock_peer(&self, peer: String) -> RpcResult<()>;
86
87    /// Lists blocked peers
88    #[method(name = "listBlockedPeers")]
89    async fn opp2p_list_blocked_peers(&self) -> RpcResult<Vec<String>>;
90
91    /// Blocks the given address
92    #[method(name = "blocAddr")]
93    async fn opp2p_block_addr(&self, ip: IpAddr) -> RpcResult<()>;
94
95    /// Unblocks the given address
96    #[method(name = "unblockAddr")]
97    async fn opp2p_unblock_addr(&self, ip: IpAddr) -> RpcResult<()>;
98
99    /// Lists blocked addresses
100    #[method(name = "listBlockedAddrs")]
101    async fn opp2p_list_blocked_addrs(&self) -> RpcResult<Vec<IpAddr>>;
102
103    /// Blocks the given subnet
104    #[method(name = "blockSubnet")]
105    async fn opp2p_block_subnet(&self, subnet: IpNet) -> RpcResult<()>;
106
107    /// Unblocks the given subnet
108    #[method(name = "unblockSubnet")]
109    async fn opp2p_unblock_subnet(&self, subnet: IpNet) -> RpcResult<()>;
110
111    /// Lists blocked subnets
112    #[method(name = "listBlockedSubnets")]
113    async fn opp2p_list_blocked_subnets(&self) -> RpcResult<Vec<IpNet>>;
114
115    /// Protects the given peer
116    #[method(name = "protectPeer")]
117    async fn opp2p_protect_peer(&self, peer: String) -> RpcResult<()>;
118
119    /// Unprotects the given peer
120    #[method(name = "unprotectPeer")]
121    async fn opp2p_unprotect_peer(&self, peer: String) -> RpcResult<()>;
122
123    /// Connects to the given peer
124    #[method(name = "connectPeer")]
125    async fn opp2p_connect_peer(&self, peer: String) -> RpcResult<()>;
126
127    /// Disconnects from the given peer
128    #[method(name = "disconnectPeer")]
129    async fn opp2p_disconnect_peer(&self, peer: String) -> RpcResult<()>;
130}
131
132/// Websockets API for the node.
133#[cfg_attr(not(feature = "client"), rpc(server, namespace = "ws"))]
134#[cfg_attr(feature = "client", rpc(server, client, namespace = "ws"))]
135#[async_trait]
136pub trait Ws {
137    /// Subscribes to the stream of finalized head updates.
138    #[subscription(name = "subscribe_finalized_head", item = kona_protocol::L2BlockInfo)]
139    async fn ws_finalized_head_updates(&self) -> SubscriptionResult;
140
141    /// Subscribes to the stream of safe head updates.
142    #[subscription(name = "subscribe_safe_head", item = kona_protocol::L2BlockInfo)]
143    async fn ws_safe_head_updates(&self) -> SubscriptionResult;
144
145    /// Subscribes to the stream of unsafe head updates.
146    #[subscription(name = "subscribe_unsafe_head", item = kona_protocol::L2BlockInfo)]
147    async fn ws_unsafe_head_updates(&self) -> SubscriptionResult;
148}
149
150/// Development RPC API for engine state introspection.
151#[cfg_attr(not(feature = "client"), rpc(server, namespace = "dev"))]
152#[cfg_attr(feature = "client", rpc(server, client, namespace = "dev"))]
153#[async_trait]
154pub trait DevEngineApi {
155    /// Subscribe to engine queue length updates.
156    #[subscription(name = "subscribe_engine_queue_size", item = usize)]
157    async fn dev_subscribe_engine_queue_length(&self) -> SubscriptionResult;
158
159    /// Get the current number of tasks in the engine queue.
160    #[method(name = "taskQueueLength")]
161    async fn dev_task_queue_length(&self) -> RpcResult<usize>;
162}
163
164/// The admin namespace for the consensus node.
165#[cfg_attr(not(feature = "client"), rpc(server, namespace = "admin"))]
166#[cfg_attr(feature = "client", rpc(server, client, namespace = "admin"))]
167pub trait AdminApi {
168    /// Posts the unsafe payload.
169    #[method(name = "postUnsafePayload")]
170    async fn admin_post_unsafe_payload(&self, payload: OpExecutionPayloadEnvelope)
171    -> RpcResult<()>;
172
173    /// Checks if the sequencer is active.
174    #[method(name = "sequencerActive")]
175    async fn admin_sequencer_active(&self) -> RpcResult<bool>;
176
177    /// Starts the sequencer.
178    #[method(name = "startSequencer")]
179    async fn admin_start_sequencer(&self) -> RpcResult<()>;
180
181    /// Stops the sequencer.
182    #[method(name = "stopSequencer")]
183    async fn admin_stop_sequencer(&self) -> RpcResult<B256>;
184
185    /// Checks if the conductor is enabled.
186    #[method(name = "conductorEnabled")]
187    async fn admin_conductor_enabled(&self) -> RpcResult<bool>;
188
189    /// Sets the recover mode.
190    #[method(name = "setRecoverMode")]
191    async fn admin_set_recover_mode(&self, mode: bool) -> RpcResult<()>;
192
193    /// Overrides the leader in the conductor.
194    #[method(name = "overrideLeader")]
195    async fn admin_override_leader(&self) -> RpcResult<()>;
196}
kona_rpc/jsonrpsee.rs

kona_rpc/
jsonrpsee.rs
