Skip to content

Document eth_simulateV1 #1803

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
Open

Document eth_simulateV1 #1803

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
3363795
Document truststore options
Feb 4, 2025
102db87
Merge branch 'main' into main
alexandratran Feb 4, 2025
9fce770
add more context to descriptions
Feb 4, 2025
ce839ac
Merge branch 'main' of github.com:hyperledger/besu-docs
Feb 19, 2025
ec910de
Merge branch 'main' of github.com:hyperledger/besu-docs
Feb 21, 2025
6c2361b
Merge branch 'main' of github.com:hyperledger/besu-docs
Mar 11, 2025
c618eb1
Merge branch 'main' of github.com:hyperledger/besu-docs
Mar 18, 2025
6fe59f1
Merge branch 'main' of github.com:hyperledger/besu-docs
Apr 2, 2025
3809ad1
Merge branch 'main' of github.com:hyperledger/besu-docs
Apr 15, 2025
4610a43
Merge branch 'main' of github.com:hyperledger/besu-docs
Apr 22, 2025
70510bc
Document `eth_simulateV1`
Apr 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 185 additions & 0 deletions docs/public-networks/reference/api/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6067,6 +6067,191 @@ mutation {

</Tabs>

### `eth_simulateV1`

Simulates transactions across multiple blocks. Allows you to test transactions with custom state and
block parameters without submitting them to the network.

#### Parameters

- `payload`: _object_ - transaction simulation payload object containing the following fields:

- `blockStateCalls`: _array_ of _objects_ - list of block state call objects, each containing the following fields:

- `blockOverrides`: _array_ of _objects_ - list of [block override objects](objects.md#block-override-object)

- `stateOverrides`: _array_ of _objects_ - list of [state override objects](objects.md#state-override-object)

- `calls`: _array_ of _objects_ - list of [transaction call objects](objects.md#transaction-call-object)

- `traceTransfers`: _boolean_ - (optional) if `true`, ETH transfers are added as ERC-20 transfer
events to the logs, allowing you to trace value transfers. The default is `false`.

- `validation`: _boolean_ - (optional) If `true`, `eth_simulateV1` does all the validation that a
normal EVM would do, except contract sender and signature checks. If `false`, `eth_simulateV1` behaves like `eth_call`.
The default is `false`.

- `returnFullTransactionObjects`: _boolean_ - (optional) If `true`, `eth_simulateV1` returns full transaction
objects. If `false`, `eth_simulateV1` returns only hashes. The default is `false`.

- `blockNumber` or `blockHash`: _string_ - hexadecimal or decimal integer representing a block number,
block hash, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as
described in [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter)

#### Returns

`result`: _array_ of _objects_ - list of simulation result objects, each containing the following fields:

- all the fields of a [block object](objects.md#block-object)

- `calls`: _array_ of _objects_ - list of [call result objects](objects.md#call-result-object)

<Tabs>

<TabItem value="curl HTTP request" label="curl HTTP request" default>

```bash
curl -X POST --data '{"jsonrpc":"2.0", "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"],"id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"
```

</TabItem>

<TabItem value="wscat WS request" label="wscat WS request">

```json
{
"jsonrpc": "2.0",
"method": "eth_simultateV1",
"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"
],
"id": 1
}
```

</TabItem>

<TabItem value="JSON result" label="JSON result">

```json
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"baseFeePerGas": "0x9",
"blobGasUsed": "0x0",
"calls": [
{
"gasUsed": "0x5208",
"logs": [
{
"address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"blockHash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f",
"blockNumber": "0x1496e50",
"data": "0x0000000000000000000000000000000000000000000000000000000000000001",
"logIndex": "0x0",
"removed": false,
"topics": [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x000000000000000000000000c000000000000000000000000000000000000000",
"0x000000000000000000000000c000000000000000000000000000000000000001"
],
"transactionHash": "0xe7217784e0c3f7b35d39303b1165046e9b7e8af9b9cf80d5d5f96c3163de8f51",
"transactionIndex": "0x0"
}
],
"returnData": "0x",
"status": "0x1"
},
{
"gasUsed": "0x5208",
"logs": [
{
"address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"blockHash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f",
"blockNumber": "0x1496e50",
"data": "0x0000000000000000000000000000000000000000000000000000000000000001",
"logIndex": "0x1",
"removed": false,
"topics": [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x000000000000000000000000c000000000000000000000000000000000000000",
"0x000000000000000000000000c000000000000000000000000000000000000002"
],
"transactionHash": "0xf0182201606ec03701ba3a07d965fabdb4b7d06b424f226ea7ec3581802fc6fa",
"transactionIndex": "0x1"
}
],
"returnData": "0x",
"status": "0x1"
}
],
"difficulty": "0x0",
"excessBlobGas": "0x4920000",
"extraData": "0x",
"gasLimit": "0x1c9c380",
"gasUsed": "0xa410",
"hash": "0xc98388385b0dbfc15ad5c6a0f4b19f7abd94efb4618ced05e3eb320ee30b1e7f",
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"miner": "0x7e2a2fa2a064f693f0a55c5639476d913ff12d05",
"mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"nonce": "0x0000000000000000",
"number": "0x1496e50",
"parentBeaconBlockRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
"parentHash": "0xddd47e7383c8ced495e85e053f898d7a333feb0432fa9098306f6f563cde4984",
"receiptsRoot": "0x75308898d571eafb5cd8cde8278bf5b3d13c5f6ec074926de3bb895b519264e1",
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"size": "0x29c",
"stateRoot": "0xd6da11fae4ab94ddba2c4c71206962f7c6eaec6e5fabf00f3f7540c4ed7ad8f1",
"timestamp": "0x67803e64",
"transactions": [
"0xe7217784e0c3f7b35d39303b1165046e9b7e8af9b9cf80d5d5f96c3163de8f51",
"0xf0182201606ec03701ba3a07d965fabdb4b7d06b424f226ea7ec3581802fc6fa"
],
"transactionsRoot": "0x9bdb74f3ce41f5893a02a631e904ae0d21ae8c4e416786d8dbd9cb5c54f1dc0f",
"uncles": [],
"withdrawals": [],
"withdrawalsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"
}
]
}
```

</TabItem>

</Tabs>

### `eth_submitHashrate` (Deprecated)

Submits the mining hashrate. This is used by mining software such as [Ethminer](https://github.com/ethereum-mining/ethminer).
Expand Down
40 changes: 35 additions & 5 deletions docs/public-networks/reference/api/objects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ This reference contains API objects that apply to both public and private networ

## Block object

Returned by [`eth_getBlockByHash`](index.md#eth_getblockbyhash) and [`eth_getBlockByNumber`](index.md#eth_getblockbynumber).
Returned by [`eth_getBlockByHash`](index.md#eth_getblockbyhash), [`eth_getBlockByNumber`](index.md#eth_getblockbynumber), and [`eth_simulateV1`](index.md#eth_simulatev1).

| Key | Type | Value |
| --- | :-: | --- |
Expand All @@ -43,6 +43,35 @@ Returned by [`eth_getBlockByHash`](index.md#eth_getblockbyhash) and [`eth_getBlo
| `uncles` | Array | Array of uncle hashes. |
| `baseFeePerGas` | Quantity | The block's [base fee per gas](../../concepts/transactions/types.md#eip1559-transactions). This field is empty for blocks created before [EIP-1559](https://github.com/ethereum/EIPs/blob/2d8a95e14e56de27c5465d93747b0006bd8ac47f/EIPS/eip-1559.md). |

## Block override object

Parameter for [`eth_simulateV1`](index.md#eth_simulatev1).
Override the following block parameters temporarily before making the call.
This allows you to make ephemeral block changes, for the purposes of transaction simulation, without affecting the actual blockchain.

| Key | Type | Value |
|-----------------|:-------------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `baseFeePerGas` | Quantity | Base fee per gas for the block. |
| `blobBaseFee` | Quantity | Base fee per unit of blob gas. |
| `feeRecipient` | Data, 20&nbsp;bytes | Address of the fee recipient for the block proposal. |
| `gasLimit` | Quantity | Maximum gas allowed in this block. |
| `number` | Quantity | Block number. When overriding block numbers across multiple blocks, block number must be increasing. By default, it's incremented by one for each block. |
| `prevRandao` | Data, 32&nbsp;bytes | Previous value of randomness. |
| `time` | Quantity | Unix epoch time in seconds. Time must increase or remain constant relative to the previous block. By default, it's incremented by one for each block. |
| `withdrawals` | Array | Array of withdrawals made by validators. This array can have a maximum length of 16. |

## Call result object

Returned by [`eth_simulateV1`](index.md#eth_simulatev1).
All fields are required.

| Key | Type | Value |
|--------------|:--------:|-----------------------------------------------------------------------------------------------|
| `returnData` | Data | Data returned for the call. |
| `logs` | Array | Array of [log objects](#log-object) generated during the call. |
| `gasUsed` | Quantity | Amount of gas used by the call. |
| `status` | Quantity | Status indicating whether the call succeeded (`0x1`). `0x0` indicates that a call has failed. |

## Fee history results object

Returned by [`eth_feeHistory`](index.md#eth_feehistory) for the requested block range. If blocks in the specified block range are not available, then only the fee history for available blocks is returned.
Expand Down Expand Up @@ -75,7 +104,8 @@ Parameter for [`eth_newFilter`](index.md#eth_newfilter), [`eth_getLogs`](index.m

## Log object

Returned by [`eth_getFilterChanges`](index.md#eth_getfilterchanges) and [`priv_getLogs`](../../../private-networks/reference/api/index.md#priv_getlogs). [`Transaction receipt objects`](#transaction-receipt-object) can contain an array of log objects.
Returned by [`eth_getFilterChanges`](index.md#eth_getfilterchanges) and [`priv_getLogs`](../../../private-networks/reference/api/index.md#priv_getlogs).
[Transaction receipt objects](#transaction-receipt-object) and [call result objects](#call-result-object) can contain an array of log objects.

| Key | Type | Value |
| --- | :-: | --- |
Expand Down Expand Up @@ -138,12 +168,11 @@ Returned by [`debug_storageRangeAt`](index.md#debug_storagerangeat).

## State override object

Optional parameter for [`eth_call`](./index.md#eth_call) and [`eth_estimateGas`](./index.md#eth_estimategas).
Parameter for [`eth_call`](./index.md#eth_call), [`eth_estimateGas`](./index.md#eth_estimategas), and [`eth_simulateV1`](index.md#eth_simulatev1).
Override an account with the following state values temporarily before making the call. This allows you
to make ephemeral state changes, for the purposes of transaction simulation, without affecting the actual
blockchain state.


| Key | Type | Value |
|---------------------------|:-------------------:|--------------------------------------------------------------------------------------------------------------------------------------------|
| `balance` | Quantity | Temporary account balance for the call execution. |
Expand Down Expand Up @@ -221,7 +250,8 @@ Returned by [`eth_getTransactionByHash`](index.md#eth_gettransactionbyhash), [`e

## Transaction call object

Parameter for [`eth_call`](index.md#eth_call), [`eth_createAccessList`](index.md#eth_createaccesslist), and [`eth_estimateGas`](index.md#eth_estimategas).
Parameter for [`eth_call`](index.md#eth_call), [`eth_createAccessList`](index.md#eth_createaccesslist), [`eth_estimateGas`](index.md#eth_estimategas),
and [`eth_simulateV1`](index.md#eth_simulatev1).

All transaction call object parameters are optional.

Expand Down
Loading