fc_rpc_core/
eth.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//! Eth rpc interface.
20
21use ethereum_types::{H160, H256, H64, U256, U64};
22use jsonrpsee::{core::RpcResult, proc_macros::rpc};
23use std::collections::BTreeMap;
24
25use crate::types::*;
26
27/// Eth rpc interface.
28#[rpc(server)]
29#[async_trait]
30pub trait EthApi {
31	// ########################################################################
32	// Client
33	// ########################################################################
34
35	/// Returns protocol version encoded as a string (quotes are necessary).
36	#[method(name = "eth_protocolVersion")]
37	fn protocol_version(&self) -> RpcResult<u64>;
38
39	/// Returns an object with data about the sync status or false. (wtf?)
40	#[method(name = "eth_syncing")]
41	async fn syncing(&self) -> RpcResult<SyncStatus>;
42
43	/// Returns block author.
44	#[method(name = "eth_coinbase")]
45	fn author(&self) -> RpcResult<H160>;
46
47	/// Returns accounts list.
48	#[method(name = "eth_accounts")]
49	fn accounts(&self) -> RpcResult<Vec<H160>>;
50
51	/// Returns highest block number.
52	#[method(name = "eth_blockNumber")]
53	fn block_number(&self) -> RpcResult<U256>;
54
55	/// Returns the chain ID used for transaction signing at the
56	/// current best block. None is returned if not
57	/// available.
58	#[method(name = "eth_chainId")]
59	fn chain_id(&self) -> RpcResult<Option<U64>>;
60
61	// ########################################################################
62	// Block
63	// ########################################################################
64
65	/// Returns block with given hash.
66	#[method(name = "eth_getBlockByHash")]
67	async fn block_by_hash(&self, hash: H256, full: bool) -> RpcResult<Option<RichBlock>>;
68
69	/// Returns block with given number.
70	#[method(name = "eth_getBlockByNumber")]
71	async fn block_by_number(
72		&self,
73		number_or_hash: BlockNumberOrHash,
74		full: bool,
75	) -> RpcResult<Option<RichBlock>>;
76
77	/// Returns the number of transactions in a block with given hash.
78	#[method(name = "eth_getBlockTransactionCountByHash")]
79	async fn block_transaction_count_by_hash(&self, hash: H256) -> RpcResult<Option<U256>>;
80
81	/// Returns the number of transactions in a block with given block number.
82	#[method(name = "eth_getBlockTransactionCountByNumber")]
83	async fn block_transaction_count_by_number(
84		&self,
85		number_or_hash: BlockNumberOrHash,
86	) -> RpcResult<Option<U256>>;
87
88	/// Returns the receipts of a block by number or hash.
89	#[method(name = "eth_getBlockReceipts")]
90	async fn block_transaction_receipts(
91		&self,
92		number_or_hash: BlockNumberOrHash,
93	) -> RpcResult<Option<Vec<Receipt>>>;
94
95	/// Returns the number of uncles in a block with given hash.
96	#[method(name = "eth_getUncleCountByBlockHash")]
97	fn block_uncles_count_by_hash(&self, hash: H256) -> RpcResult<U256>;
98
99	/// Returns the number of uncles in a block with given block number.
100	#[method(name = "eth_getUncleCountByBlockNumber")]
101	fn block_uncles_count_by_number(&self, number_or_hash: BlockNumberOrHash) -> RpcResult<U256>;
102
103	/// Returns an uncles at given block and index.
104	#[method(name = "eth_getUncleByBlockHashAndIndex")]
105	fn uncle_by_block_hash_and_index(
106		&self,
107		hash: H256,
108		index: Index,
109	) -> RpcResult<Option<RichBlock>>;
110
111	/// Returns an uncles at given block and index.
112	#[method(name = "eth_getUncleByBlockNumberAndIndex")]
113	fn uncle_by_block_number_and_index(
114		&self,
115		number_or_hash: BlockNumberOrHash,
116		index: Index,
117	) -> RpcResult<Option<RichBlock>>;
118
119	// ########################################################################
120	// Transaction
121	// ########################################################################
122
123	/// Get transaction by its hash.
124	#[method(name = "eth_getTransactionByHash")]
125	async fn transaction_by_hash(&self, hash: H256) -> RpcResult<Option<Transaction>>;
126
127	/// Returns transaction at given block hash and index.
128	#[method(name = "eth_getTransactionByBlockHashAndIndex")]
129	async fn transaction_by_block_hash_and_index(
130		&self,
131		hash: H256,
132		index: Index,
133	) -> RpcResult<Option<Transaction>>;
134
135	/// Returns transaction by given block number and index.
136	#[method(name = "eth_getTransactionByBlockNumberAndIndex")]
137	async fn transaction_by_block_number_and_index(
138		&self,
139		number_or_hash: BlockNumberOrHash,
140		index: Index,
141	) -> RpcResult<Option<Transaction>>;
142
143	/// Returns transaction receipt by transaction hash.
144	#[method(name = "eth_getTransactionReceipt")]
145	async fn transaction_receipt(&self, hash: H256) -> RpcResult<Option<Receipt>>;
146
147	// ########################################################################
148	// State
149	// ########################################################################
150
151	/// Returns balance of the given account.
152	#[method(name = "eth_getBalance")]
153	async fn balance(
154		&self,
155		address: H160,
156		number_or_hash: Option<BlockNumberOrHash>,
157	) -> RpcResult<U256>;
158
159	/// Returns content of the storage at given address.
160	#[method(name = "eth_getStorageAt")]
161	async fn storage_at(
162		&self,
163		address: H160,
164		index: U256,
165		number_or_hash: Option<BlockNumberOrHash>,
166	) -> RpcResult<H256>;
167
168	/// Returns the number of transactions sent from given address at given time (block number).
169	#[method(name = "eth_getTransactionCount")]
170	async fn transaction_count(
171		&self,
172		address: H160,
173		number_or_hash: Option<BlockNumberOrHash>,
174	) -> RpcResult<U256>;
175
176	/// Returns the code at given address at given time (block number).
177	#[method(name = "eth_getCode")]
178	async fn code_at(
179		&self,
180		address: H160,
181		number_or_hash: Option<BlockNumberOrHash>,
182	) -> RpcResult<Bytes>;
183
184	// ########################################################################
185	// Execute
186	// ########################################################################
187
188	/// Call contract, returning the output data.
189	#[method(name = "eth_call")]
190	async fn call(
191		&self,
192		request: TransactionRequest,
193		number_or_hash: Option<BlockNumberOrHash>,
194		state_overrides: Option<BTreeMap<H160, CallStateOverride>>,
195	) -> RpcResult<Bytes>;
196
197	/// Estimate gas needed for execution of given contract.
198	#[method(name = "eth_estimateGas")]
199	async fn estimate_gas(
200		&self,
201		request: TransactionRequest,
202		number_or_hash: Option<BlockNumberOrHash>,
203	) -> RpcResult<U256>;
204
205	/// Returns all pending transactions.
206	#[method(name = "eth_pendingTransactions")]
207	async fn pending_transactions(&self) -> RpcResult<Vec<Transaction>>;
208
209	// ########################################################################
210	// Fee
211	// ########################################################################
212
213	/// Returns current gas_price.
214	#[method(name = "eth_gasPrice")]
215	fn gas_price(&self) -> RpcResult<U256>;
216
217	/// Introduced in EIP-1159 for getting information on the appropriate priority fee to use.
218	#[method(name = "eth_feeHistory")]
219	async fn fee_history(
220		&self,
221		block_count: BlockCount,
222		newest_block: BlockNumberOrHash,
223		reward_percentiles: Option<Vec<f64>>,
224	) -> RpcResult<FeeHistory>;
225
226	/// Introduced in EIP-1159, a Geth-specific and simplified priority fee oracle.
227	/// Leverages the already existing fee history cache.
228	#[method(name = "eth_maxPriorityFeePerGas")]
229	fn max_priority_fee_per_gas(&self) -> RpcResult<U256>;
230
231	// ########################################################################
232	// Mining
233	// ########################################################################
234
235	/// Returns true if client is actively mining new blocks.
236	#[method(name = "eth_mining")]
237	fn is_mining(&self) -> RpcResult<bool>;
238
239	/// Returns the number of hashes per second that the node is mining with.
240	#[method(name = "eth_hashrate")]
241	fn hashrate(&self) -> RpcResult<U256>;
242
243	/// Returns the hash of the current block, the seedHash, and the boundary condition to be met.
244	#[method(name = "eth_getWork")]
245	fn work(&self) -> RpcResult<Work>;
246
247	/// Used for submitting mining hashrate.
248	#[method(name = "eth_submitHashrate")]
249	fn submit_hashrate(&self, hashrate: U256, id: H256) -> RpcResult<bool>;
250
251	/// Used for submitting a proof-of-work solution.
252	#[method(name = "eth_submitWork")]
253	fn submit_work(&self, nonce: H64, pow_hash: H256, mix_digest: H256) -> RpcResult<bool>;
254
255	// ########################################################################
256	// Submit
257	// ########################################################################
258
259	/// Sends transaction; will block waiting for signer to return the
260	/// transaction hash.
261	#[method(name = "eth_sendTransaction")]
262	async fn send_transaction(&self, request: TransactionRequest) -> RpcResult<H256>;
263
264	/// Sends signed transaction, returning its hash.
265	#[method(name = "eth_sendRawTransaction")]
266	async fn send_raw_transaction(&self, bytes: Bytes) -> RpcResult<H256>;
267}
268
269/// Eth filters rpc api (polling).
270#[rpc(server)]
271pub trait EthFilterApi {
272	/// Returns id of new filter.
273	#[method(name = "eth_newFilter")]
274	fn new_filter(&self, filter: Filter) -> RpcResult<U256>;
275
276	/// Returns id of new block filter.
277	#[method(name = "eth_newBlockFilter")]
278	fn new_block_filter(&self) -> RpcResult<U256>;
279
280	/// Returns id of new block filter.
281	#[method(name = "eth_newPendingTransactionFilter")]
282	fn new_pending_transaction_filter(&self) -> RpcResult<U256>;
283
284	/// Returns filter changes since last poll.
285	#[method(name = "eth_getFilterChanges")]
286	async fn filter_changes(&self, index: Index) -> RpcResult<FilterChanges>;
287
288	/// Returns all logs matching given filter (in a range 'from' - 'to').
289	#[method(name = "eth_getFilterLogs")]
290	async fn filter_logs(&self, index: Index) -> RpcResult<Vec<Log>>;
291
292	/// Uninstalls filter.
293	#[method(name = "eth_uninstallFilter")]
294	fn uninstall_filter(&self, index: Index) -> RpcResult<bool>;
295
296	/// Returns logs matching given filter object.
297	#[method(name = "eth_getLogs")]
298	async fn logs(&self, filter: Filter) -> RpcResult<Vec<Log>>;
299}