reth_rpc_api/
engine.rs

1//! Server traits for the engine API
2//!
3//! This contains the `engine_` namespace and the subset of the `eth_` namespace that is exposed to
4//! the consensus client.
5
6use alloy_eips::{
7    eip4844::{BlobAndProofV1, BlobAndProofV2},
8    eip7685::RequestsOrHash,
9    BlockId, BlockNumberOrTag,
10};
11use alloy_json_rpc::RpcObject;
12use alloy_primitives::{Address, BlockHash, Bytes, B256, U256, U64};
13use alloy_rpc_types_engine::{
14    ClientVersionV1, ExecutionPayloadBodiesV1, ExecutionPayloadInputV2, ExecutionPayloadV1,
15    ExecutionPayloadV3, ExecutionPayloadV4, ForkchoiceState, ForkchoiceUpdated, PayloadId,
16    PayloadStatus,
17};
18use alloy_rpc_types_eth::{
19    state::StateOverride, BlockOverrides, EIP1186AccountProofResponse, Filter, Log, SyncStatus,
20};
21use alloy_serde::JsonStorageKey;
22use jsonrpsee::{core::RpcResult, proc_macros::rpc, RpcModule};
23use reth_engine_primitives::EngineTypes;
24
25/// Helper trait for the engine api server.
26///
27/// This type-erases the concrete [`jsonrpsee`] server implementation and only returns the
28/// [`RpcModule`] that contains all the endpoints of the server.
29pub trait IntoEngineApiRpcModule {
30    /// Consumes the type and returns all the methods and subscriptions defined in the trait and
31    /// returns them as a single [`RpcModule`]
32    fn into_rpc_module(self) -> RpcModule<()>;
33}
34
35// NOTE: We can't use associated types in the `EngineApi` trait because of jsonrpsee, so we use a
36// generic here. It would be nice if the rpc macro would understand which types need to have serde.
37// By default, if the trait has a generic, the rpc macro will add e.g. `Engine: DeserializeOwned` to
38// the trait bounds, which is not what we want, because `Types` is not used directly in any of the
39// trait methods. Instead, we have to add the bounds manually. This would be disastrous if we had
40// more than one associated type used in the trait methods.
41
42#[cfg_attr(not(feature = "client"), rpc(server, namespace = "engine"), server_bounds(Engine::PayloadAttributes: jsonrpsee::core::DeserializeOwned))]
43#[cfg_attr(feature = "client", rpc(server, client, namespace = "engine", client_bounds(Engine::PayloadAttributes: jsonrpsee::core::Serialize + Clone), server_bounds(Engine::PayloadAttributes: jsonrpsee::core::DeserializeOwned)))]
44pub trait EngineApi<Engine: EngineTypes> {
45    /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/paris.md#engine_newpayloadv1>
46    /// Caution: This should not accept the `withdrawals` field
47    #[method(name = "newPayloadV1")]
48    async fn new_payload_v1(&self, payload: ExecutionPayloadV1) -> RpcResult<PayloadStatus>;
49
50    /// See also <https://github.com/ethereum/execution-apis/blob/584905270d8ad665718058060267061ecfd79ca5/src/engine/shanghai.md#engine_newpayloadv2>
51    #[method(name = "newPayloadV2")]
52    async fn new_payload_v2(&self, payload: ExecutionPayloadInputV2) -> RpcResult<PayloadStatus>;
53
54    /// Post Cancun payload handler
55    ///
56    /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_newpayloadv3>
57    #[method(name = "newPayloadV3")]
58    async fn new_payload_v3(
59        &self,
60        payload: ExecutionPayloadV3,
61        versioned_hashes: Vec<B256>,
62        parent_beacon_block_root: B256,
63    ) -> RpcResult<PayloadStatus>;
64
65    /// Post Prague payload handler
66    ///
67    /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/prague.md#engine_newpayloadv4>
68    #[method(name = "newPayloadV4")]
69    async fn new_payload_v4(
70        &self,
71        payload: ExecutionPayloadV3,
72        versioned_hashes: Vec<B256>,
73        parent_beacon_block_root: B256,
74        execution_requests: RequestsOrHash,
75    ) -> RpcResult<PayloadStatus>;
76
77    /// Post Amsterdam payload handler
78    ///
79    /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_newpayloadv5>
80    #[method(name = "newPayloadV5")]
81    async fn new_payload_v5(
82        &self,
83        payload: ExecutionPayloadV4,
84        versioned_hashes: Vec<B256>,
85        parent_beacon_block_root: B256,
86        execution_requests: RequestsOrHash,
87    ) -> RpcResult<PayloadStatus>;
88
89    /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/paris.md#engine_forkchoiceupdatedv1>
90    ///
91    /// Caution: This should not accept the `withdrawals` field in the payload attributes.
92    #[method(name = "forkchoiceUpdatedV1")]
93    async fn fork_choice_updated_v1(
94        &self,
95        fork_choice_state: ForkchoiceState,
96        payload_attributes: Option<Engine::PayloadAttributes>,
97    ) -> RpcResult<ForkchoiceUpdated>;
98
99    /// Post Shanghai forkchoice update handler
100    ///
101    /// This is the same as `forkchoiceUpdatedV1`, but expects an additional `withdrawals` field in
102    /// the `payloadAttributes`, if payload attributes are provided.
103    ///
104    /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/shanghai.md#engine_forkchoiceupdatedv2>
105    ///
106    /// Caution: This should not accept the `parentBeaconBlockRoot` field in the payload
107    /// attributes.
108    #[method(name = "forkchoiceUpdatedV2")]
109    async fn fork_choice_updated_v2(
110        &self,
111        fork_choice_state: ForkchoiceState,
112        payload_attributes: Option<Engine::PayloadAttributes>,
113    ) -> RpcResult<ForkchoiceUpdated>;
114
115    /// Post Cancun forkchoice update handler
116    ///
117    /// This is the same as `forkchoiceUpdatedV2`, but expects an additional
118    /// `parentBeaconBlockRoot` field in the `payloadAttributes`, if payload attributes
119    /// are provided.
120    ///
121    /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_forkchoiceupdatedv3>
122    #[method(name = "forkchoiceUpdatedV3")]
123    async fn fork_choice_updated_v3(
124        &self,
125        fork_choice_state: ForkchoiceState,
126        payload_attributes: Option<Engine::PayloadAttributes>,
127    ) -> RpcResult<ForkchoiceUpdated>;
128
129    /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/paris.md#engine_getpayloadv1>
130    ///
131    /// Returns the most recent version of the payload that is available in the corresponding
132    /// payload build process at the time of receiving this call.
133    ///
134    /// Caution: This should not return the `withdrawals` field
135    ///
136    /// Note:
137    /// > Provider software MAY stop the corresponding build process after serving this call.
138    #[method(name = "getPayloadV1")]
139    async fn get_payload_v1(
140        &self,
141        payload_id: PayloadId,
142    ) -> RpcResult<Engine::ExecutionPayloadEnvelopeV1>;
143
144    /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/shanghai.md#engine_getpayloadv2>
145    ///
146    /// Returns the most recent version of the payload that is available in the corresponding
147    /// payload build process at the time of receiving this call. Note:
148    /// > Provider software MAY stop the corresponding build process after serving this call.
149    #[method(name = "getPayloadV2")]
150    async fn get_payload_v2(
151        &self,
152        payload_id: PayloadId,
153    ) -> RpcResult<Engine::ExecutionPayloadEnvelopeV2>;
154
155    /// Post Cancun payload handler which also returns a blobs bundle.
156    ///
157    /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_getpayloadv3>
158    ///
159    /// Returns the most recent version of the payload that is available in the corresponding
160    /// payload build process at the time of receiving this call. Note:
161    /// > Provider software MAY stop the corresponding build process after serving this call.
162    #[method(name = "getPayloadV3")]
163    async fn get_payload_v3(
164        &self,
165        payload_id: PayloadId,
166    ) -> RpcResult<Engine::ExecutionPayloadEnvelopeV3>;
167
168    /// Post Prague payload handler.
169    ///
170    /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/prague.md#engine_getpayloadv4>
171    ///
172    /// Returns the most recent version of the payload that is available in the corresponding
173    /// payload build process at the time of receiving this call. Note:
174    /// > Provider software MAY stop the corresponding build process after serving this call.
175    #[method(name = "getPayloadV4")]
176    async fn get_payload_v4(
177        &self,
178        payload_id: PayloadId,
179    ) -> RpcResult<Engine::ExecutionPayloadEnvelopeV4>;
180
181    /// Post Osaka payload handler.
182    ///
183    /// See also <https://github.com/ethereum/execution-apis/blob/15399c2e2f16a5f800bf3f285640357e2c245ad9/src/engine/osaka.md#engine_getpayloadv5>.
184    ///
185    /// Returns the most recent version of the payload that is available in the corresponding
186    /// payload build process at the time of receiving this call. Note:
187    /// > Provider software MAY stop the corresponding build process after serving this call.
188    #[method(name = "getPayloadV5")]
189    async fn get_payload_v5(
190        &self,
191        payload_id: PayloadId,
192    ) -> RpcResult<Engine::ExecutionPayloadEnvelopeV5>;
193
194    /// Post Amsterdam payload handler.
195    ///
196    /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/amsterdam.md#engine_getpayloadv6>
197    ///
198    /// Returns the most recent version of the payload that is available in the corresponding
199    /// payload build process at the time of receiving this call. Note:
200    /// > Provider software MAY stop the corresponding build process after serving this call.
201    #[method(name = "getPayloadV6")]
202    async fn get_payload_v6(
203        &self,
204        payload_id: PayloadId,
205    ) -> RpcResult<Engine::ExecutionPayloadEnvelopeV6>;
206
207    /// See also <https://github.com/ethereum/execution-apis/blob/6452a6b194d7db269bf1dbd087a267251d3cc7f8/src/engine/shanghai.md#engine_getpayloadbodiesbyhashv1>
208    #[method(name = "getPayloadBodiesByHashV1")]
209    async fn get_payload_bodies_by_hash_v1(
210        &self,
211        block_hashes: Vec<BlockHash>,
212    ) -> RpcResult<ExecutionPayloadBodiesV1>;
213
214    /// See also <https://github.com/ethereum/execution-apis/blob/6452a6b194d7db269bf1dbd087a267251d3cc7f8/src/engine/shanghai.md#engine_getpayloadbodiesbyrangev1>
215    ///
216    /// Returns the execution payload bodies by the range starting at `start`, containing `count`
217    /// blocks.
218    ///
219    /// WARNING: This method is associated with the `BeaconBlocksByRange` message in the consensus
220    /// layer p2p specification, meaning the input should be treated as untrusted or potentially
221    /// adversarial.
222    ///
223    /// Implementers should take care when acting on the input to this method, specifically
224    /// ensuring that the range is limited properly, and that the range boundaries are computed
225    /// correctly and without panics.
226    #[method(name = "getPayloadBodiesByRangeV1")]
227    async fn get_payload_bodies_by_range_v1(
228        &self,
229        start: U64,
230        count: U64,
231    ) -> RpcResult<ExecutionPayloadBodiesV1>;
232
233    /// This function will return the [`ClientVersionV1`] object.
234    /// See also:
235    /// <https://github.com/ethereum/execution-apis/blob/03911ffc053b8b806123f1fc237184b0092a485a/src/engine/identification.md#engine_getclientversionv1>
236    ///
237    ///
238    /// - When connected to a single execution client, the consensus client **MUST** receive an
239    ///   array with a single `ClientVersionV1` object.
240    /// - When connected to multiple execution clients via a multiplexer, the multiplexer **MUST**
241    ///   concatenate the responses from each execution client into a single,
242    /// flat array before returning the response to the consensus client.
243    #[method(name = "getClientVersionV1")]
244    async fn get_client_version_v1(
245        &self,
246        client_version: ClientVersionV1,
247    ) -> RpcResult<Vec<ClientVersionV1>>;
248
249    /// See also <https://github.com/ethereum/execution-apis/blob/6452a6b194d7db269bf1dbd087a267251d3cc7f8/src/engine/common.md#capabilities>
250    #[method(name = "exchangeCapabilities")]
251    async fn exchange_capabilities(&self, capabilities: Vec<String>) -> RpcResult<Vec<String>>;
252
253    /// Fetch blobs for the consensus layer from the blob store.
254    #[method(name = "getBlobsV1")]
255    async fn get_blobs_v1(
256        &self,
257        versioned_hashes: Vec<B256>,
258    ) -> RpcResult<Vec<Option<BlobAndProofV1>>>;
259
260    /// Fetch blobs for the consensus layer from the blob store.
261    ///
262    /// Returns a response only if blobs and proofs are present for _all_ of the versioned hashes:
263    ///     2. Client software MUST return null in case of any missing or older version blobs.
264    #[method(name = "getBlobsV2")]
265    async fn get_blobs_v2(
266        &self,
267        versioned_hashes: Vec<B256>,
268    ) -> RpcResult<Option<Vec<BlobAndProofV2>>>;
269
270    /// Fetch blobs for the consensus layer from the blob store.
271    ///
272    /// Returns a response of the same length as the request. Missing or older-version blobs are
273    /// returned as `null` elements.
274    ///
275    /// Returns `null` if syncing.
276    #[method(name = "getBlobsV3")]
277    async fn get_blobs_v3(
278        &self,
279        versioned_hashes: Vec<B256>,
280    ) -> RpcResult<Option<Vec<Option<BlobAndProofV2>>>>;
281
282    /// Returns the Block Access Lists for the given block hashes.
283    ///
284    /// See also <https://eips.ethereum.org/EIPS/eip-7928>
285    #[method(name = "getBALsByHashV1")]
286    async fn get_bals_by_hash_v1(&self, block_hashes: Vec<BlockHash>) -> RpcResult<Vec<Bytes>>;
287
288    /// Returns the Block Access Lists for the given block range.
289    ///
290    /// See also <https://eips.ethereum.org/EIPS/eip-7928>
291    #[method(name = "getBALsByRangeV1")]
292    async fn get_bals_by_range_v1(&self, start: U64, count: U64) -> RpcResult<Vec<Bytes>>;
293}
294
295/// A subset of the ETH rpc interface: <https://ethereum.github.io/execution-apis/api-documentation>
296///
297/// This also includes additional eth functions required by optimism.
298///
299/// Specifically for the engine auth server: <https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md#underlying-protocol>
300#[cfg_attr(not(feature = "client"), rpc(server, namespace = "eth"))]
301#[cfg_attr(feature = "client", rpc(server, client, namespace = "eth"))]
302pub trait EngineEthApi<TxReq: RpcObject, B: RpcObject, R: RpcObject> {
303    /// Returns an object with data about the sync status or false.
304    #[method(name = "syncing")]
305    fn syncing(&self) -> RpcResult<SyncStatus>;
306
307    /// Returns the chain ID of the current network.
308    #[method(name = "chainId")]
309    async fn chain_id(&self) -> RpcResult<Option<U64>>;
310
311    /// Returns the number of most recent block.
312    #[method(name = "blockNumber")]
313    fn block_number(&self) -> RpcResult<U256>;
314
315    /// Executes a new message call immediately without creating a transaction on the block chain.
316    #[method(name = "call")]
317    async fn call(
318        &self,
319        request: TxReq,
320        block_id: Option<BlockId>,
321        state_overrides: Option<StateOverride>,
322        block_overrides: Option<Box<BlockOverrides>>,
323    ) -> RpcResult<Bytes>;
324
325    /// Returns code at a given address at given block number.
326    #[method(name = "getCode")]
327    async fn get_code(&self, address: Address, block_id: Option<BlockId>) -> RpcResult<Bytes>;
328
329    /// Returns information about a block by hash.
330    #[method(name = "getBlockByHash")]
331    async fn block_by_hash(&self, hash: B256, full: bool) -> RpcResult<Option<B>>;
332
333    /// Returns information about a block by number.
334    #[method(name = "getBlockByNumber")]
335    async fn block_by_number(&self, number: BlockNumberOrTag, full: bool) -> RpcResult<Option<B>>;
336
337    /// Returns all transaction receipts for a given block.
338    #[method(name = "getBlockReceipts")]
339    async fn block_receipts(&self, block_id: BlockId) -> RpcResult<Option<Vec<R>>>;
340
341    /// Sends signed transaction, returning its hash.
342    #[method(name = "sendRawTransaction")]
343    async fn send_raw_transaction(&self, bytes: Bytes) -> RpcResult<B256>;
344
345    /// Returns the receipt of a transaction by transaction hash.
346    #[method(name = "getTransactionReceipt")]
347    async fn transaction_receipt(&self, hash: B256) -> RpcResult<Option<R>>;
348
349    /// Returns logs matching given filter object.
350    #[method(name = "getLogs")]
351    async fn logs(&self, filter: Filter) -> RpcResult<Vec<Log>>;
352
353    /// Returns the account and storage values of the specified account including the Merkle-proof.
354    /// This call can be used to verify that the data you are pulling from is not tampered with.
355    #[method(name = "getProof")]
356    async fn get_proof(
357        &self,
358        address: Address,
359        keys: Vec<JsonStorageKey>,
360        block_number: Option<BlockId>,
361    ) -> RpcResult<EIP1186AccountProofResponse>;
362}
reth_rpc_api/engine.rs

reth_rpc_api/
engine.rs
