fc_rpc_v2_api/eth/
mod.rs

1// This file is part of Frontier.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19/// (Non-standard) Ethereum pubsub interface.
20pub mod pubsub;
21
22use ethereum_types::{Address, H256, U256, U64};
23use jsonrpsee::{core::RpcResult, proc_macros::rpc};
24
25pub use self::pubsub::*;
26use crate::types::{
27	access_list::AccessListResult,
28	block::Block,
29	block_id::{BlockNumberOrTag, BlockNumberOrTagOrHash},
30	bytes::Bytes,
31	fee::FeeHistoryResult,
32	filter::{Filter, FilterChanges},
33	index::Index,
34	log::Log,
35	proof::AccountProof,
36	state::StateOverrides,
37	sync::SyncingStatus,
38	transaction::{Transaction, TransactionReceipt, TransactionRequest},
39};
40
41/// Ethereum RPC client interfaces.
42pub trait EthApiClient:
43	EthBlockApiClient
44	+ EthClientApiClient
45	+ EthExecuteApiClient
46	+ EthFeeMarketApiClient
47	+ EthFilterApiClient
48	+ EthSignApiClient
49	+ EthStateApiClient
50	+ EthSubmitApiClient
51	+ EthTransactionApiClient
52	+ EthPubSubApiClient
53{
54}
55
56impl<T> EthApiClient for T where
57	T: EthBlockApiClient
58		+ EthClientApiClient
59		+ EthExecuteApiClient
60		+ EthFeeMarketApiClient
61		+ EthFilterApiClient
62		+ EthSignApiClient
63		+ EthStateApiClient
64		+ EthSubmitApiClient
65		+ EthTransactionApiClient
66		+ EthPubSubApiClient
67{
68}
69
70/// Ethereum RPC server interfaces.
71pub trait EthApiServer:
72	EthBlockApiServer
73	+ EthClientApiServer
74	+ EthExecuteApiServer
75	+ EthFeeMarketApiServer
76	+ EthFilterApiServer
77	+ EthSignApiServer
78	+ EthStateApiServer
79	+ EthSubmitApiServer
80	+ EthTransactionApiServer
81	+ EthPubSubApiServer
82{
83}
84
85impl<T> EthApiServer for T where
86	T: EthBlockApiServer
87		+ EthClientApiServer
88		+ EthExecuteApiServer
89		+ EthFeeMarketApiServer
90		+ EthFilterApiServer
91		+ EthSignApiServer
92		+ EthStateApiServer
93		+ EthSubmitApiServer
94		+ EthTransactionApiServer
95		+ EthPubSubApiServer
96{
97}
98
99/// Ethereum (block) RPC interface.
100#[rpc(client, server, namespace = "eth")]
101#[async_trait]
102pub trait EthBlockApi {
103	/// Returns information about a block by hash.
104	#[method(name = "getBlockByHash")]
105	async fn block_by_hash(&self, hash: H256, full: bool) -> RpcResult<Option<Block>>;
106
107	/// Returns information about a block by number.
108	#[method(name = "getBlockByNumber")]
109	async fn block_by_number(
110		&self,
111		block: BlockNumberOrTag,
112		full: bool,
113	) -> RpcResult<Option<Block>>;
114
115	/// Returns the number of transactions in a block from a block matching the given block hash.
116	#[method(name = "getBlockTransactionCountByHash")]
117	async fn block_transaction_count_by_hash(&self, block_hash: H256) -> RpcResult<Option<U256>>;
118
119	/// Returns the number of transactions in a block matching the given block number.
120	#[method(name = "getBlockTransactionCountByNumber")]
121	async fn block_transaction_count_by_number(
122		&self,
123		block: BlockNumberOrTag,
124	) -> RpcResult<Option<U256>>;
125
126	/// Returns the number of uncles in a block from a block matching the given block hash.
127	#[method(name = "getUncleCountByBlockHash")]
128	async fn block_uncles_count_by_hash(&self, block_hash: H256) -> RpcResult<U256>;
129
130	/// Returns the number of uncles in a block matching the given block number.
131	#[method(name = "getUncleCountByBlockNumber")]
132	async fn block_uncles_count_by_number(&self, block: BlockNumberOrTag) -> RpcResult<U256>;
133
134	/// Returns the receipts of a block by number or hash.
135	#[method(name = "getBlockReceipts")]
136	async fn block_transaction_receipts(
137		&self,
138		number_or_hash: BlockNumberOrTagOrHash,
139	) -> RpcResult<Option<Vec<TransactionReceipt>>>;
140}
141
142/// Ethereum (client) RPC interface.
143#[rpc(client, server, namespace = "eth")]
144#[async_trait]
145pub trait EthClientApi {
146	/// Returns the chain ID of the current network.
147	#[method(name = "chainId")]
148	async fn chain_id(&self) -> RpcResult<U64>;
149
150	/// Returns an object with data about the sync status or false.
151	#[method(name = "syncing")]
152	async fn syncing(&self) -> RpcResult<SyncingStatus>;
153
154	/// Returns the client coinbase address.
155	#[method(name = "coinbase")]
156	async fn author(&self) -> RpcResult<Address>;
157
158	/// Returns a list of addresses owned by client.
159	#[method(name = "accounts")]
160	async fn accounts(&self) -> RpcResult<Vec<Address>>;
161
162	/// Returns the number of most recent block.
163	#[method(name = "blockNumber")]
164	async fn block_number(&self) -> RpcResult<U64>;
165}
166
167/// Ethereum (execute) RPC interface.
168#[rpc(client, server, namespace = "eth")]
169#[async_trait]
170pub trait EthExecuteApi {
171	/// Executes a new message call immediately without creating a transaction on the blockchain.
172	#[method(name = "call")]
173	async fn call(
174		&self,
175		request: TransactionRequest,
176		number_or_hash: Option<BlockNumberOrTagOrHash>,
177		state_overrides: Option<StateOverrides>,
178		// block_overrides: Option<BlockOverrides>,
179	) -> RpcResult<Bytes>;
180
181	/// Generates and returns an estimate of hou much gas is necessary to allow the transaction to complete.
182	#[method(name = "estimateGas")]
183	async fn estimate_gas(
184		&self,
185		request: TransactionRequest,
186		number_or_hash: Option<BlockNumberOrTag>,
187		state_overrides: Option<StateOverrides>,
188	) -> RpcResult<U256>;
189
190	/// Generates an access list for a transaction.
191	#[method(name = "createAccessList")]
192	async fn create_access_list(
193		&self,
194		request: TransactionRequest,
195		number_or_hash: Option<BlockNumberOrTag>,
196	) -> RpcResult<AccessListResult>;
197}
198
199/// Ethereum (fee market) RPC interface.
200#[rpc(client, server, namespace = "eth")]
201#[async_trait]
202pub trait EthFeeMarketApi {
203	/// Returns the current price per gas in wei.
204	#[method(name = "gasPrice")]
205	async fn gas_price(&self) -> RpcResult<U256>;
206
207	/// Returns the current maxPriorityFeePerGas per gas in wei, which introduced in EIP-1159.
208	#[method(name = "maxPriorityFeePerGas")]
209	async fn max_priority_fee_per_gas(&self) -> RpcResult<U256>;
210
211	/// Returns transaction base fee per gas and effective priority fee per gas for the requested/supported block range.
212	///
213	/// Transaction fee history, which is introduced in EIP-1159.
214	#[method(name = "feeHistory")]
215	async fn fee_history(
216		&self,
217		block_count: U256,
218		newest_block: BlockNumberOrTag,
219		reward_percentiles: Option<Vec<f64>>,
220	) -> RpcResult<FeeHistoryResult>;
221}
222
223/// Ethereum (filter) RPC interface.
224#[rpc(client, server, namespace = "eth")]
225#[async_trait]
226pub trait EthFilterApi {
227	/// Creates a filter object, based on filter options, to notify when the state changes (logs).
228	#[method(name = "newFilter")]
229	async fn new_filter(&self, filter: Filter) -> RpcResult<U256>;
230
231	/// Creates a filter in the node, to notify when a new block arrives.
232	#[method(name = "newBlockFilter")]
233	async fn new_block_filter(&self) -> RpcResult<U256>;
234
235	/// Creates a filter in the node, to notify when new pending transactions arrive.
236	#[method(name = "newPendingTransactionFilter")]
237	async fn new_pending_transaction_filter(&self, full: Option<bool>) -> RpcResult<U256>;
238
239	/// Uninstalls a filter with given id.
240	#[method(name = "uninstallFilter")]
241	async fn uninstall_filter(&self, filter_id: Index) -> RpcResult<bool>;
242
243	/// Polling method for a filter, which returns an array of logs which occurred since last poll.
244	#[method(name = "getFilterChanges")]
245	async fn filter_changes(&self, filter_id: Index) -> RpcResult<FilterChanges>;
246
247	/// Returns an array of all logs matching filter with given id.
248	#[method(name = "getFilterLogs")]
249	async fn filter_logs(&self, filter_id: Index) -> RpcResult<Vec<Log>>;
250
251	/// Returns an array of all logs matching filter with given id.
252	#[method(name = "getLogs")]
253	async fn logs(&self, filter: Filter) -> RpcResult<Vec<Log>>;
254}
255
256/// Ethereum (sign) RPC interface.
257#[rpc(client, server, namespace = "eth")]
258#[async_trait]
259pub trait EthSignApi {
260	/// Returns an EIP-191 signature over the provided data.
261	#[method(name = "sign")]
262	async fn sign(&self, address: Address, message: Bytes) -> RpcResult<Bytes>;
263
264	/// Returns an RLP encoded transaction signed by the specified account.
265	#[method(name = "signTransaction")]
266	async fn sign_transaction(&self, request: TransactionRequest) -> RpcResult<Bytes>;
267}
268
269/// Ethereum (state) RPC interface.
270#[rpc(client, server, namespace = "eth")]
271#[async_trait]
272pub trait EthStateApi {
273	/// Returns the balance of the account of given address.
274	#[method(name = "getBalance")]
275	async fn balance(
276		&self,
277		address: Address,
278		block: Option<BlockNumberOrTagOrHash>,
279	) -> RpcResult<U256>;
280
281	/// Returns the value from a storage position at a given address.
282	#[method(name = "getStorageAt")]
283	async fn storage_at(
284		&self,
285		address: Address,
286		slot: U256,
287		block: Option<BlockNumberOrTagOrHash>,
288	) -> RpcResult<H256>;
289
290	/// Returns the number of transactions sent from an address.
291	#[method(name = "getTransactionCount")]
292	async fn transaction_count(
293		&self,
294		address: Address,
295		block: Option<BlockNumberOrTagOrHash>,
296	) -> RpcResult<U256>;
297
298	/// Returns the code at a given address.
299	#[method(name = "getCode")]
300	async fn code(
301		&self,
302		address: Address,
303		block: Option<BlockNumberOrTagOrHash>,
304	) -> RpcResult<Bytes>;
305
306	/// Returns the merkle proof for a given account and optionally some storage keys.
307	#[method(name = "getProof")]
308	async fn proof(
309		&self,
310		address: Address,
311		storage_keys: H256,
312		block: Option<BlockNumberOrTagOrHash>,
313	) -> RpcResult<AccountProof>;
314}
315
316/// Ethereum (submit) RPC interface.
317#[rpc(client, server, namespace = "eth")]
318#[async_trait]
319pub trait EthSubmitApi {
320	/// Signs and submits a transaction; will block waiting for signer to return the transaction hash.
321	#[method(name = "eth_sendTransaction")]
322	async fn send_transaction(&self, request: TransactionRequest) -> RpcResult<H256>;
323
324	/// Submits a raw signed transaction, returning its hash.
325	#[method(name = "eth_sendRawTransaction")]
326	async fn send_raw_transaction(&self, bytes: Bytes) -> RpcResult<H256>;
327}
328
329/// Ethereum (transaction) RPC interface.
330#[rpc(client, server, namespace = "eth")]
331#[async_trait]
332pub trait EthTransactionApi {
333	/// Returns the information about a transaction requested by transaction hash.
334	#[method(name = "getTransactionByHash")]
335	async fn transaction_by_hash(&self, transaction_hash: H256) -> RpcResult<Option<Transaction>>;
336
337	/// Returns information about a transaction by block hash and transaction index position.
338	#[method(name = "getTransactionByBlockHashAndIndex")]
339	async fn transaction_by_block_hash_and_index(
340		&self,
341		block_hash: H256,
342		transaction_index: Index,
343	) -> RpcResult<Option<Transaction>>;
344
345	/// Returns information about a transaction by block number and transaction index position.
346	#[method(name = "getTransactionByBlockNumberAndIndex")]
347	async fn transaction_by_block_number_and_index(
348		&self,
349		block: BlockNumberOrTag,
350		transaction_index: Index,
351	) -> RpcResult<Option<Transaction>>;
352
353	/// Returns the receipt of a transaction by transaction hash.
354	#[method(name = "getTransactionReceipt")]
355	async fn transaction_receipt(
356		&self,
357		transaction_hash: H256,
358	) -> RpcResult<Option<TransactionReceipt>>;
359}