Skip to content

Commit f841f45

Browse files
nhussein11eshaben
nhussein11
and
eshaben
committed
Create "JSON-RPC APIs (Eth Compatibility)" page (#349)
* fix: json rpc apis page * fix: feedback * Update develop/smart-contracts/json-rpc-apis.md Co-authored-by: Erin Shaben <[email protected]> * Update develop/smart-contracts/json-rpc-apis.md Co-authored-by: Erin Shaben <[email protected]> * Update develop/smart-contracts/json-rpc-apis.md Co-authored-by: Erin Shaben <[email protected]> * fix: json spaces * Update develop/smart-contracts/json-rpc-apis.md Co-authored-by: Erin Shaben <[email protected]> * fix: `code` type admonition --------- Co-authored-by: Erin Shaben <[email protected]>
1 parent 36a1c6c commit f841f45

File tree

2 files changed

+389
-0
lines changed

2 files changed

+389
-0
lines changed

‎develop/smart-contracts/.pages

+1
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ nav:
66
- 'Native EVM Contracts': native-evm-contracts.md
77
- 'Parachain Contracts': parachain-contracts.md
88
- evm-toolkit
9+
- 'JSON-RPC APIs': json-rpc-apis.md

‎develop/smart-contracts/json-rpc-apis.md

+388
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,388 @@
1+
---
2+
title: JSON-RPC APIs
3+
description: JSON-RPC APIs guide for Asset Hub, covering supported methods, parameters, and examples for interacting with the Asset Hub chain.
4+
---
5+
6+
# JSON-RPC APIs
7+
8+
## Introduction
9+
10+
Asset Hub provides Ethereum compatibility through its JSON-RPC interface, allowing developers to interact with the chain using familiar Ethereum tooling and methods. This document outlines the supported Ethereum JSON-RPC methods and provides examples of how to use them.
11+
12+
This article uses the Westend Asset Hub endpoint to interact with:
13+
14+
```text
15+
https://westend-asset-hub-eth-rpc.polkadot.io
16+
```
17+
18+
## Available Methods
19+
20+
### Chain Information
21+
22+
- [`eth_chainId`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_chainid){target=\_blank} - returns the chain ID used for signing transactions
23+
24+
???- code "Query Example"
25+
26+
```bash title="eth_chainId"
27+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
28+
-H "Content-Type: application/json" \
29+
--data '{
30+
"jsonrpc":"2.0",
31+
"method":"eth_chainId",
32+
"params":[],
33+
"id":1
34+
}'
35+
```
36+
37+
- [`net_version`](https://ethereum.org/en/developers/docs/apis/json-rpc/#net_version){target=\_blank} - returns the current network ID as a string
38+
39+
???- code "Query Example"
40+
41+
```bash title="net_version"
42+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
43+
-H "Content-Type: application/json" \
44+
--data '{
45+
"jsonrpc":"2.0",
46+
"method":"net_version",
47+
"params":[],
48+
"id":1
49+
}'
50+
```
51+
52+
### Block Information
53+
54+
- [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber){target=\_blank} - returns the number of the most recent block
55+
56+
???- code "Query Example"
57+
58+
```bash title="eth_blockNumber"
59+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
60+
-H "Content-Type: application/json" \
61+
--data '{
62+
"jsonrpc":"2.0",
63+
"method":"eth_blockNumber",
64+
"params":[],
65+
"id":1
66+
}'
67+
```
68+
69+
- [`eth_getBlockByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbyhash){target=\_blank} - returns information about a block by its hash
70+
71+
- Parameters
72+
- Block Hash - The block hash of the block to retrieve
73+
- Boolean - `true` returns full transaction details, while `false` provides only transaction hashes
74+
75+
???- code "Query Example"
76+
77+
```bash title="eth_getBlockByHash"
78+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
79+
-H "Content-Type: application/json" \
80+
--data '{
81+
"jsonrpc":"2.0",
82+
"method":"eth_getBlockByHash",
83+
"params":["INSERT_BLOCK_HASH", INSERT_BOOLEAN],
84+
"id":1
85+
}'
86+
```
87+
88+
Ensure to replace the `INSERT_BLOCK_HASH` and `INSERT_BOOLEAN` with the proper values.
89+
90+
- [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber){target=\_blank} - returns information about a block by its number
91+
92+
- Parameters
93+
- Block Value - quantity or tag of the block value to be fetched
94+
- Boolean - `true` returns full transaction details, while `false` provides only transaction hashes
95+
96+
???- code "Query Example"
97+
98+
```bash title="eth_getBlockByNumber"
99+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
100+
-H "Content-Type: application/json" \
101+
--data '{
102+
"jsonrpc":"2.0",
103+
"method":"eth_getBlockByNumber",
104+
"params":["INSERT_BLOCK_VALUE", INSERT_BOOLEAN],
105+
"id":1
106+
}'
107+
```
108+
109+
Ensure to replace the `INSERT_BLOCK_VALUE` and `INSERT_BOOLEAN` with the proper values.
110+
111+
### Account Information
112+
113+
- [`eth_accounts`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_accounts){target=\_blank} - returns a list of addresses owned by the client
114+
115+
???- code "Query Example"
116+
117+
```bash
118+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
119+
-H "Content-Type: application/json" \
120+
--data '{
121+
"jsonrpc":"2.0",
122+
"method":"eth_accounts",
123+
"params":[],
124+
"id":1
125+
}'
126+
```
127+
128+
- [`eth_getBalance`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getbalance){target=\_blank} - returns the balance of a given address
129+
130+
- Parameters
131+
- Address - address to query balance
132+
- Block Value - quantity or tag of the block value to be fetched
133+
134+
???- code "Query Example"
135+
136+
```bash title="eth_getBalance"
137+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
138+
-H "Content-Type: application/json" \
139+
--data '{
140+
"jsonrpc":"2.0",
141+
"method":"eth_getBalance",
142+
"params":["INSERT_ADDRESS", "INSERT_BLOCK_VALUE"],
143+
"id":1
144+
}'
145+
```
146+
147+
Ensure to replace the `INSERT_ADDRESS` and `INSERT_BLOCK_VALUE` with the proper values.
148+
149+
### Transaction Operations
150+
151+
- [`eth_sendTransaction`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendtransaction){target=\_blank} - creates and sends a new transaction
152+
153+
- Parameters
154+
- From - address sending the transaction
155+
- To - (optional when deploying a contract) recipient address
156+
- Gas - (optional, default: 90000) gas limit for execution
157+
- Gas Price - (optional) gas price per unit
158+
- Value - (optional) amount of Ether to send
159+
- Input - contract bytecode or encoded method call
160+
- Nonce - (optional) transaction nonce
161+
162+
???- code "Query Example"
163+
164+
```bash title="eth_sendtransaction"
165+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
166+
-H "Content-Type: application/json" \
167+
--data '{
168+
"jsonrpc":"2.0",
169+
"method":"eth_sendTransaction",
170+
"params":[{
171+
"from": "INSERT_SENDER_ADDRESS",
172+
"to": "INSERT_RECIPIENT_ADDRESS",
173+
"gas": "INSERT_GAS_LIMIT",
174+
"gasPrice": "INSERT_GAS_PRICE",
175+
"value": "INSERT_VALUE",
176+
"input": "INSERT_INPUT_DATA",
177+
"nonce": "INSERT_NONCE"
178+
}],
179+
"id":1
180+
}'
181+
```
182+
183+
Ensure to replace the `INSERT_SENDER_ADDRESS`, `INSERT_RECIPIENT_ADDRESS`, `INSERT_GAS_LIMIT`, `INSERT_GAS_PRICE`, `INSERT_VALUE`, `INSERT_INPUT_DATA` and `INSERT_NONCE` with the proper values.
184+
185+
- [`eth_sendRawTransaction`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendrawtransaction){target=\_blank} - submits a raw transaction
186+
187+
- Parameters
188+
- Call Data - signed transaction data
189+
190+
???- code "Query Example"
191+
192+
```bash title="eth_sendRawTransaction"
193+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
194+
-H "Content-Type: application/json" \
195+
--data '{
196+
"jsonrpc":"2.0",
197+
"method":"eth_sendRawTransaction",
198+
"params":["INSERT_CALL_DATA"],
199+
"id":1
200+
}'
201+
```
202+
203+
Ensure to replace the `INSERT_CALL_DATA` with the proper values.
204+
205+
- [`eth_getTransactionCount`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactioncount){target=\_blank} - returns the number of transactions sent from an address (nonce)
206+
207+
- Parameters
208+
- Address - address to query balance
209+
- Block Value - quantity or tag of the block value to be fetched
210+
211+
???- code "Query Example"
212+
213+
```bash title="eth_getTransactionCount"
214+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
215+
-H "Content-Type: application/json" \
216+
--data '{
217+
"jsonrpc":"2.0",
218+
"method":"eth_getTransactionCount",
219+
"params":["INSERT_ADDRESS", "INSERT_BLOCK_VALUE"],
220+
"id":1
221+
}'
222+
```
223+
224+
Ensure to replace the `INSERT_ADDRESS` and `INSERT_BLOCK_VALUE` with the proper values.
225+
226+
### Smart Contract Interaction
227+
228+
- [`eth_call`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call){target=\_blank} - executes a new message call immediately without creating a transaction
229+
230+
- Parameters
231+
- From (optional) - address initiating the call
232+
- To - recipient address of the call
233+
- Gas (optional) - gas limit for execution (not consumed by `eth_call`)
234+
- Gas Price (optional) - gas price for execution
235+
- Value (optional) - amount of token sent with the call
236+
- Input (optional) - hash of the method signature and encoded parameters
237+
- Block Value - quantity or tag of the block value to be fetched
238+
239+
???- code "Query Example"
240+
241+
```bash title="eth_call"
242+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
243+
-H "Content-Type: application/json" \
244+
--data '{
245+
"jsonrpc":"2.0",
246+
"method":"eth_call",
247+
"params":[{
248+
"to": "INSERT_RECIPIENT_ADDRESS",
249+
"data": "INSERT_ENCODED_CALL"
250+
}, "INSERT_BLOCK_VALUE"],
251+
"id":1
252+
}'
253+
```
254+
255+
Ensure to replace the `INSERT_RECIPIENT_ADDRESS`, `INSERT_ENCODED_CALL` and `INSERT_BLOCK_VALUE` with the proper values.
256+
257+
- [`eth_estimateGas`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_estimategas){target=\_blank} - estimates gas required for a transaction
258+
259+
- Parameters
260+
- From (optional) - address initiating the call
261+
- To (optional) - recipient address of the call
262+
- Gas (optional) - gas limit for execution
263+
- Gas Price (optional) - gas price for execution
264+
- Value (optional) - amount of token sent with the call
265+
- Input (optional) - hash of the method signature and encoded parameters
266+
- Block Value (optional) - quantity or tag of the block value to be fetched
267+
268+
???- code "Query Example"
269+
270+
```bash title="eth_estimateGas"
271+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
272+
-H "Content-Type: application/json" \
273+
--data '{
274+
"jsonrpc":"2.0",
275+
"method":"eth_estimateGas",
276+
"params":[{
277+
"to": "INSERT_RECIPIENT_ADDRESS",
278+
"data": "INSERT_ENCODED_FUNCTION_CALL"
279+
}],
280+
"id":1
281+
}'
282+
```
283+
284+
Ensure to replace the `INSERT_RECIPIENT_ADDRESS` and `INSERT_ENCODED_CALL` with the proper values.
285+
286+
### Gas and Fees
287+
288+
- [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice){target=\_blank} - returns the current gas price in wei
289+
290+
???- code "Query Example"
291+
292+
```bash title="eth_gasPrice"
293+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
294+
-H "Content-Type: application/json" \
295+
--data '{
296+
"jsonrpc":"2.0",
297+
"method":"eth_gasPrice",
298+
"params":[],
299+
"id":1
300+
}'
301+
```
302+
303+
- [`eth_maxPriorityFeePerGas`](){target=\_blank} - returns the current maxPriorityFeePerGas in wei
304+
305+
???- code "Query Example"
306+
307+
```bash title="eth_maxPriorityFeePerGas"
308+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
309+
-H "Content-Type: application/json" \
310+
--data '{
311+
"jsonrpc":"2.0",
312+
"method":"eth_maxPriorityFeePerGas",
313+
"params":[],
314+
"id":1
315+
}'
316+
```
317+
318+
### State and Storage
319+
320+
- [`eth_getCode`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getcode){target=\_blank} - returns the code at a given address
321+
322+
- Parameters
323+
- Address - contract or account address to query code
324+
- Block Value (optional) - quantity or tag of the block value to be fetched
325+
326+
???- code "Query Example"
327+
328+
```bash title "eth_getCode"
329+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
330+
-H "Content-Type: application/json" \
331+
--data '{
332+
"jsonrpc":"2.0",
333+
"method":"eth_getCode",
334+
"params":["INSERT_ADDRESS", "INSERT_BLOCK_VALUE"],
335+
"id":1
336+
}'
337+
```
338+
339+
Ensure to replace the `INSERT_ADDRESS` and `INSERT_BLOCK_VALUE` with the proper values.
340+
341+
- [`eth_getStorageAt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat){target=\_blank} - returns the value from a storage position at a given address
342+
343+
- Parameters
344+
- Address - contract or account address to query storage
345+
- Storage Key - position in storage to retrieve data from
346+
- Block Value (optional) - quantity or tag of the block value to be fetched
347+
348+
???- code "Query Example"
349+
350+
```bash title="eth_getStorageAt"
351+
curl -X POST https://westend-asset-hub-eth-rpc.polkadot.io \
352+
-H "Content-Type: application/json" \
353+
--data '{
354+
"jsonrpc":"2.0",
355+
"method":"eth_getStorageAt",
356+
"params":["INSERT_ADDRESS", "INSERT_STORAGE_KEY", "INSERT_BLOCK_VALUE"],
357+
"id":1
358+
}'
359+
```
360+
361+
Ensure to replace the `INSERT_ADDRESS`, `INSERT_STORAGE_KEY` and `INSERT_BLOCK_VALUE` with the proper values.
362+
363+
## Response Format
364+
365+
All responses follow the standard JSON-RPC 2.0 format:
366+
367+
```json
368+
{
369+
"jsonrpc": "2.0",
370+
"id": 1,
371+
"result": ... // The return value varies by method
372+
}
373+
```
374+
375+
## Error Handling
376+
377+
If an error occurs, the response will include an error object:
378+
379+
```json
380+
{
381+
"jsonrpc": "2.0",
382+
"id": 1,
383+
"error": {
384+
"code": -32000,
385+
"message": "Error message here"
386+
}
387+
}
388+
```

0 commit comments

Comments
 (0)