Skip to content

Commit bc259dc

Browse files
bgravenorstalexandratran
bgravenorst
and
alexandratran
authored
Document eth_simulateV1 (#1798)
* Document eth_simulateV1 Signed-off-by: bgravenorst <[email protected]> * Add what's new. Signed-off-by: bgravenorst <[email protected]> * Apply suggestions from code review Co-authored-by: Alexandra Carrillo <[email protected]> --------- Signed-off-by: bgravenorst <[email protected]> Co-authored-by: Alexandra Carrillo <[email protected]>
1 parent 33b57e9 commit bc259dc

File tree

3 files changed

+263
-0
lines changed

3 files changed

+263
-0
lines changed

‎docs/whats-new.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ of the [MetaMask developer page](https://metamask.io/developer/).
1111

1212
## January 2025
1313

14+
- Documented [`eth_simulateV1`](/services/reference/ethereum/json-rpc-methods/eth_simulatev1). ([#1798](https://github.com/MetaMask/metamask-docs/pull/1798))
1415
- Added new [MetaMask SDK documentation section](/sdk).
1516
([#1766](https://github.com/MetaMask/metamask-docs/pull/1766))
1617
- Documented Snaps [`Banner`](/snaps/features/custom-ui/#banner), [`Container`](/snaps/features/custom-ui/#container), [`Footer`](/snaps/features/custom-ui/#footer), [`Skeleton`](/snaps/features/custom-ui/#skeleton), and [`Value`](/snaps/features/custom-ui/#value) UI components.

‎services/get-started/pricing/credit-cost.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ a specific network, then use the default Ethereum method's credit cost.
7878
| `eth_protocolVersion` | 5 |
7979
| `eth_sendRawTransaction` | 80 |
8080
| `eth_sign` | 80 |
81+
| `eth_simulateV1 | 300 |
8182
| `eth_submitWork` | 80 |
8283
| `eth_subscribe` | 5 |
8384
| `eth_syncing` | 5 |

‎services/reference/ethereum/json-rpc-methods/eth_simulatev1.mdx

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
---
2+
title: "eth_simulateV1"
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
Simulates transactions across multiple blocks. Allows you to test transactions with custom state and
9+
block parameters without submitting them to the network.
10+
11+
:::info important
12+
This method is only supported on Mainnet and Sepolia.
13+
14+
A maximum of 16 block state calls can be simulated in a single request. This is determined by
15+
assessing the `blockStateCalls` array of objects.
16+
:::
17+
18+
## Parameters
19+
20+
- `BLOCK STATE CALL OBJECT`:
21+
- `blockStateCalls`: _\[required]_ Array of block, state, and call objects:
22+
- `blockOverrides`: _\[optional]_ Object to override block parameters:
23+
- `baseFeePerGas`: (string) Hexadecimal value for the base fee per gas for the block.
24+
- `blobBaseFee`: (string) Hexadecimal value for the base fee per unit of blob gas.
25+
- `feeRecipient`: (string) Address of the fee recipient for the block proposal.
26+
- `gasLimit`: (string) Hexadecimal value that represents the maximum amount of gas that transactions
27+
are allowed to consume.
28+
- `number`: (string) Hexadecimal block number.
29+
- `prevRandao`: (string) The previous value of randomness, which is
30+
used as a source of randomness for various protocol operations.
31+
- `time`: (string) Hexadecimal value representing the Unix epoch time in seconds.
32+
- `stateOverrides`: _\[optional]_ Object to override account states:
33+
- `balance`: (string) Hexadecimal value representing the account balance.
34+
- `nonce`: (string) Hexadecimal temporary nonce value for the call execution.
35+
- `code`: (string) Bytecode to inject into the account.
36+
- `state`: Object of key-value mappings to override all slots in the account storage
37+
before executing the call.
38+
- `stateDiff`: Object of key-value mappings to override individual slots in the account
39+
storage before executing the call.
40+
- `movePrecompileToAddress`: (string) Moves the precompile to the supplied address.
41+
- `calls`: _\[required]_ Array of transaction call objects:
42+
- `from`: _\[optional]_ 20 bytes - The address the transaction is sent from.
43+
- `to`: _\[optional]_ 20 bytes - The address the transaction is directed to.
44+
- `gas`: _\[optional]_ Hexadecimal value of the gas provided for the transaction execution.
45+
- `gasPrice`: _\[optional]_ Hexadecimal value of the gas price used for each paid gas.
46+
- `maxPriorityFeePerGas`: _\[optional]_ Maximum fee, in wei, the sender is willing to pay per gas above the base fee.
47+
- `maxFeePerGas`: _\[optional]_ Maximum total fee (base fee + priority fee), in wei, the sender is willing to pay per gas.
48+
- `value`: _\[optional]_ Hexadecimal value of the value sent with this transaction.
49+
- `data`: _\[optional]_ Hash of the method signature and encoded parameters. See the
50+
[Ethereum contract ABI specification](https://docs.soliditylang.org/en/latest/abi-spec.html).
51+
- `returnFullTransactionObjects`: _\[optional]_ Boolean value which when `true`, returns full transaction
52+
objects, otherwise, just hashes are returned. The default is `false`.
53+
- `traceTransfers`: _\[optional]_ Boolean value which when `true`, adds ETH transfers as ERC20 transfer
54+
events to the logs, allowing you to trace value transfers. The default is `false`.
55+
- `validation`: _\[optional]_ Boolean value which when `true`, does all the validation that a
56+
normal EVM would do, except contract sender and signature checks. When `false`, `eth_simulateV1` behaves like `eth_call`.
57+
The default is `false`.
58+
- `blockParameter`: (string) [_optional_] A hexadecimal block number, or one of the tags `latest`, `earliest`, `pending` or `finalized`. See the [default block parameter](https://ethereum.org/en/developers/docs/apis/json-rpc/#default-block).
59+
60+
## Returns
61+
62+
An array of simulation result objects:
63+
64+
- `baseFeePerGas`: Hexadecimal value for the base fee per gas for the block.
65+
- `blobGasUsed`: Hexadecimal value for the amount of blob gas used.
66+
- `calls`: Array of call results:
67+
- `returnData`: Data returned for the call.
68+
- `logs`: Array of logs generated during the call.
69+
- `address`: Address of the contract that generated the log.
70+
- `blockHash`: Hash of the block.
71+
- `blockNumber`: Hexadecimal block number.
72+
- `data`: Non-indexed log parameters.
73+
- `logIndex`: Index of the log in the block.
74+
- `removed`: Whether the log was removed due to chain reorganization.
75+
- `topics`: Array of indexed log parameters.
76+
- `transactionHash`: Hash of the transaction.
77+
- `transactionIndex`: Index of the transaction in the block.
78+
- `error`: Object containing error information:
79+
- `message`: The error message.
80+
- `code`: The error status code.
81+
- `data`: Error-related information.
82+
- `gasUsed`: Hexadecimal value representing the amount of gas used.
83+
- `status`: Status indicating whether the transaction succeeded (`0x1`). `0x0` indicates that a transaction has failed.
84+
- `difficulty`: A hexadecimal of the difficulty for this block.
85+
- `excessBlobGas`: A hexadecimal of the excess blob gas.
86+
- `extraData`: The "extra data" field of this block.
87+
- `gasLimit`: Maximum gas allowed in this block.
88+
- `gasUsed`: Total used gas by all transactions in this block.
89+
- `hash`: Hash of the block. `Null` when the returned block is the pending block.
90+
- `logsBloom`: The bloom filter for the logs of the block. `Null` when the returned block is the pending block.
91+
- `miner`: Address of the beneficiary to whom the mining rewards were given.
92+
- `mixHash`: Hexadecimal mix hash.
93+
- `nonce`: Hash of the generated proof-of-work. `Null` when the returned block is the pending block.
94+
- `number`: Block number. `Null` when the returned block is the pending block.
95+
- `parentBeaconBlockRoot`: Parent beacon block root.
96+
- `parentHash`: Hash of the parent block.
97+
- `receiptsRoot`: The root of the receipts trie of the block. Also see [Tries in Ethereum](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/#tries-in-ethereum).
98+
- `sha3Uncles`: The SHA3 of the uncles data in the block.
99+
- `size`: A hexadecimal of the size of this block in bytes.
100+
- `stateRoot`: The root of the final state trie of the block.
101+
- `timestamp`: The unix timestamp for when the block was collated.
102+
- `totalDifficulty`: A hexadecimal of the total difficulty of the chain until this block.
103+
- `transactions`: (Array) An array of transaction objects, or 32 bytes transaction hashes depending on the last given parameter.
104+
- `transactionsRoot`: The root of the transaction trie of the block.
105+
- `uncles`: (Array) An array of uncle hashes.
106+
- `withdrawals`: (Array) Withdrawal objects.
107+
- `withdrawalsRoot`: Withdrawals trie root.
108+
109+
## Example
110+
111+
Replace `<YOUR-API-KEY>` with an API key from your [MetaMask Developer dashboard](https://developer.metamask.io/).
112+
113+
### Request
114+
115+
<Tabs>
116+
<TabItem value="curl">
117+
118+
```bash
119+
curl https://mainnet.infura.io/v3/<YOUR-API-KEY> \
120+
-X POST \
121+
-H "Content-Type: application/json" \
122+
-d '{
123+
"jsonrpc": "2.0",
124+
"id": 1,
125+
"method": "eth_simulateV1",
126+
"params": [
127+
{
128+
"blockStateCalls": [
129+
{
130+
"blockOverrides": {
131+
"baseFeePerGas": "0x9"
132+
},
133+
"stateOverrides": {
134+
"0xc000000000000000000000000000000000000000": {
135+
"balance": "0x4a817c800"
136+
}
137+
},
138+
"calls": [
139+
{
140+
"from": "0xc000000000000000000000000000000000000000",
141+
"to": "0xc000000000000000000000000000000000000001",
142+
"maxFeePerGas": "0xf",
143+
"value": "0x1"
144+
},
145+
{
146+
"from": "0xc000000000000000000000000000000000000000",
147+
"to": "0xc000000000000000000000000000000000000002",
148+
"maxFeePerGas": "0xf",
149+
"value": "0x1"
150+
}
151+
]
152+
}
153+
],
154+
"validation": true,
155+
"traceTransfers": true
156+
},
157+
"latest"
158+
]
159+
}'
160+
```
161+
162+
</TabItem>
163+
<TabItem value="WSS">
164+
165+
```bash
166+
wscat -c wss://mainnet.infura.io/ws/v3/<YOUR-API-KEY> -x '{"jsonrpc":"2.0","id":1,"method":"eth_simulateV1","params":[{"blockStateCalls":[{"blockOverrides":{"baseFeePerGas":"0x9"},"stateOverrides":{"0xc000000000000000000000000000000000000000":{"balance":"0x4a817c800"}},"calls":[{"from":"0xc000000000000000000000000000000000000000","to":"0xc000000000000000000000000000000000000001","maxFeePerGas":"0xf","value":"0x1"},{"from":"0xc000000000000000000000000000000000000000","to":"0xc000000000000000000000000000000000000002","maxFeePerGas":"0xf","value":"0x1"}]}],"validation":true,"traceTransfers":true},"latest"]}'
167+
```
168+
169+
</TabItem>
170+
</Tabs>
171+
172+
### Response
173+
174+
<Tabs>
175+
<TabItem value="JSON">
176+
177+
```JSON
178+
{
179+
"jsonrpc": "2.0",
180+
"id": 1,
181+
"result": [
182+
{
183+
"baseFeePerGas": "0x9",
184+
"blobGasUsed": "0x0",
185+
"calls": [
186+
{
187+
"gasUsed": "0x5208",
188+
"logs": [
189+
{
190+
"address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
191+
"blockHash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f",
192+
"blockNumber": "0x1496e50",
193+
"data": "0x0000000000000000000000000000000000000000000000000000000000000001",
194+
"logIndex": "0x0",
195+
"removed": false,
196+
"topics": [
197+
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
198+
"0x000000000000000000000000c000000000000000000000000000000000000000",
199+
"0x000000000000000000000000c000000000000000000000000000000000000001"
200+
],
201+
"transactionHash": "0xe7217784e0c3f7b35d39303b1165046e9b7e8af9b9cf80d5d5f96c3163de8f51",
202+
"transactionIndex": "0x0"
203+
}
204+
],
205+
"returnData": "0x",
206+
"status": "0x1"
207+
},
208+
{
209+
"gasUsed": "0x5208",
210+
"logs": [
211+
{
212+
"address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
213+
"blockHash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f",
214+
"blockNumber": "0x1496e50",
215+
"data": "0x0000000000000000000000000000000000000000000000000000000000000001",
216+
"logIndex": "0x1",
217+
"removed": false,
218+
"topics": [
219+
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
220+
"0x000000000000000000000000c000000000000000000000000000000000000000",
221+
"0x000000000000000000000000c000000000000000000000000000000000000002"
222+
],
223+
"transactionHash": "0xf0182201606ec03701ba3a07d965fabdb4b7d06b424f226ea7ec3581802fc6fa",
224+
"transactionIndex": "0x1"
225+
}
226+
],
227+
"returnData": "0x",
228+
"status": "0x1"
229+
}
230+
],
231+
"difficulty": "0x0",
232+
"excessBlobGas": "0x4920000",
233+
"extraData": "0x",
234+
"gasLimit": "0x1c9c380",
235+
"gasUsed": "0xa410",
236+
"hash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f",
237+
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
238+
"miner": "0x7e2a2fa2a064f693f0a55c5639476d913ff12d05",
239+
"mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
240+
"nonce": "0x0000000000000000",
241+
"number": "0x1496e50",
242+
"parentBeaconBlockRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
243+
"parentHash": "0xddd47e7383c8ced495e85e053f898d7a333feb0432fa9098306f6f563cde4984",
244+
"receiptsRoot": "0x75308898d571eafb5cd8cde8278bf5b3d13c5f6ec074926de3bb895b519264e1",
245+
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
246+
"size": "0x29c",
247+
"stateRoot": "0xd6da11fae4ab94ddba2c4c71206962f7c6eaec6e5fabf00f3f7540c4ed7ad8f1",
248+
"timestamp": "0x67803e64",
249+
"transactions": [
250+
"0xe7217784e0c3f7b35d39303b1165046e9b7e8af9b9cf80d5d5f96c3163de8f51",
251+
"0xf0182201606ec03701ba3a07d965fabdb4b7d06b424f226ea7ec3581802fc6fa"
252+
],
253+
"transactionsRoot": "0x9bdb74f3ce41f5893a02a631e904ae0d21ae8c4e416786d8dbd9cb5c54f1dc0f",
254+
"uncles": [],
255+
"withdrawals": [],
256+
"withdrawalsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"
257+
}
258+
```
259+
260+
</TabItem>
261+
</Tabs>

0 commit comments

Comments
 (0)