diff --git a/docs/developers/evm-tracing/built-in-tracers.md b/docs/developers/evm-tracing/built-in-tracers.md index 6d8217cf5f..8e78d1bc8d 100644 --- a/docs/developers/evm-tracing/built-in-tracers.md +++ b/docs/developers/evm-tracing/built-in-tracers.md @@ -497,42 +497,6 @@ Returns: } ``` -## State overrides {#state-overrides} - -It is possible to give temporary state modifications to Geth in order to simulate the effects of `eth_call` or `debug_traceCall`. For example, some new bytecode could be deployed to some address _temporarily just for the duration of the execution_ and then a transaction interacting with that address can be traced. This can be used for scenario testing or determining the outcome of some hypothetical transaction before executing for real. - -Available state overrides are: - -- `nonce`: `hexdecimal`. The nonce of the account. -- `code`: `string`. The bytecode of the account. -- `balance`: `hexdecimal`. The balance of the account in Wei. -- `state`: `map[common.Hash]common.Hash`. Clear all storage slots of the account and insert the ones given in the dictionary. -- `stateDiff`: `map[common.Hash]common.Hash`. Update the given storage slots with new values. - -Note, `state` and `stateDiff` can't be specified at the same time. If `state` is -set, message execution will only use the data in the given state. Otherwise if `statDiff` is set, all diff will be applied first and then execute the call. - -To do this, the tracer is written as normal, but the parameter `stateOverrides` is passed an address and some bytecode. - -```js -var code = //contract bytecode -var tracer = //tracer name -debug.traceCall({from: , to: , input: }, 'latest', {stateOverrides: {'0x...': {code: code}}, tracer: tracer}) -``` - -## Block overrides {#block-overrides} - -Similar to [State overrides](#state-overrides), it is also possible to override some of the execution's block context to simulate the effects of `eth_call` or `debug_traceCall`, we support the following override options: - -- `number`: `hexdecimal`. The block number. -- `difficulty`: `hexdecimal`. The block difficulty. -- `time`: `hexdecimal`. The block timestamp. -- `gasLimit`: `hexdecimal`. The block gas limit. -- `coinbase`: `common.Address`. The block coinbase. -- `random`: `common.Hash`. The block PREVRANDAO. -- `baseFee`: `hexdecimal`. The block base fee. -- `blobBaseFee`: `hexdecimal`. The block blob base fee. - ## Summary {#summary} This page showed how to use the tracers that come bundled with Geth. There are a set written in Go and a set written in Javascript. They are invoked by passing their names when calling an API method. State overrides can be used in combination with tracers to examine precisely what the EVM will do in some hypothetical scenarios. diff --git a/docs/interacting-with-geth/rpc/ns-debug.md b/docs/interacting-with-geth/rpc/ns-debug.md index 4d614efa66..9c37a9bba2 100644 --- a/docs/interacting-with-geth/rpc/ns-debug.md +++ b/docs/interacting-with-geth/rpc/ns-debug.md @@ -591,8 +591,8 @@ The `debug_traceCall` method lets you run an `eth_call` within the context of th TraceCallConfig is a superset of [TraceConfig](#traceconfig), providing additional arguments in addition to those provided by [TraceConfig](#traceconfig): -- `stateOverrides`: `StateOverride`. Overrides for the state data (accounts/storage) for the call, see [StateOverride](/docs/developers/evm-tracing/built-in-tracers#state-overrides) for more details. -- `blockOverrides`: `BlockOverrides`. Overrides for the block data (number, timestamp etc) for the call, see [BlockOverrides](/docs/developers/evm-tracing/built-in-tracers#block-overrides) for more details. +- `stateOverrides`: `StateOverride`. Overrides for the state data (accounts/storage) for the call, see [StateOverride](/docs/interacting-with-geth/rpc/objects#state-override-set) for more details. +- `blockOverrides`: `BlockOverrides`. Overrides for the block data (number, timestamp etc) for the call, see [BlockOverrides](/docs/interacting-with-geth/rpc/objects#block-overrides) for more details. - `txIndex`: `NUMBER`. If set, the state at the given transaction index will be used to tracing (default = the last transaction index in the block). **Example:** diff --git a/docs/interacting-with-geth/rpc/ns-eth.md b/docs/interacting-with-geth/rpc/ns-eth.md index b5d447cf19..32e253525f 100644 --- a/docs/interacting-with-geth/rpc/ns-eth.md +++ b/docs/interacting-with-geth/rpc/ns-eth.md @@ -5,6 +5,195 @@ description: Documentation for the JSON-RPC API "eth" namespace Documentation for the API methods in the `eth` namespace can be found on [ethereum.org](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_protocolversion). Geth provides several extensions to the standard "eth" JSON-RPC namespace that are defined below. +### eth_simulateV1 {#eth-simulate-v1} +The `eth_simulateV1` method allows the simulation of multiple blocks and transactions without creating transactions or blocks on the blockchain. It functions similarly to `eth_call`, but offers more control. Like `eth_call`, `eth_simulateV1` has a maximum gas limit for the entire simulation, this limit can be adjusted with command line parameter `--rpc.gascap`. + +**Parameters:** +The method takes two parameters: +1) `Object` - `eth_simulate` payload +2) `Quantity | Tag` - The block number or the string `latest`, specifying the parent block for the simulation. The simulated blocks will be built on top of this. + +The `eth_simulate` payload structure: + | Field | Type | Optional | Default | Description | + | :----------------------- | :---------------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | `blockStateCalls` | `BlockStateCalls` | False | N/A | Definition of blocks that can contain calls and overrides | + | `traceTransfers` | `bool` | Yes | False | Adds ETH transfers as ERC20 transfer events to the logs. These transfers have emitter contract parameter set as address(`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`). This allows you to track movements of ETH in your calls. | + | `validation` | `bool` | Yes | False | When true, the `eth_simulateV1` does all the validation that a normal EVM would do, except contract sender and signature checks. When false, `eth_simulateV1` behaves like `eth_call`. | + | `returnFullTransactions` | `bool` | Yes | False | When true, the method returns full transaction objects, otherwise, just hashes are returned. | + +`BlockStateCalls` is an array of objects, the single object definition is described below. The total number of blocks for a single request is limited to 256. This includes any gap blocks that client generated. + | Field | Type | Description | + | :--------------- | :------------------------- | :----------------------------------------------------------------------------------------------------------- | + | `blockOverrides` | `BlockOverrides` | Overrides fields such as block number or time in a simulated block. | + | `stateOverrides` | `StateOverrides` | State overrides can be used to replace existing blockchain state with new state. | + | `calls` | `GenericCallTransaction[]` | An aray of transaction call objects. Please see [Transaction Call Object](/docs/interacting-with-geth/rpc/objects#transaction-call-object) for details. | + +The optional `BlockOverrides` object modifies the context in which the transactions of that given block are executed. Refer to [Block overrides](/docs/interacting-with-geth/rpc/objects#block-overrides) for a list of modifiable fields. When overriding multiple blocks, block numbers must increment. Skipping numbers is allowed and skipped blocks are included in the response. When overriding time across multiple blocks, time need to be increasing. If time is not specified, it's incremented by one for each block. + +The StateOverrides is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing each block. Please see [State Override Set](/docs/interacting-with-geth/rpc/objects#state-override-set) for details. + +**Output** +On a succesfull `eth_simulateV1` call, an array of generated full blocks is returned (the same object that you would get with `eth_getBlockByHash`, except with an added `calls` field), otherwise an error is returned. The blocks contain `calls` field that is defined as follows: + +On failure: + | Field | Type | Description | + | :----------- | :----------------------------------------------- | :-------------------------------------------- | + | `status` | `"0x0"` | Status indicating that the transaction failed | + | `returnData` | `bytes` | Transactions return data | + | `gasUsed` | `uint64` | Gas used by the transaction | + | `error` | `{ code: uint64, message: string, data: bytes }` | Error code, data and message | + +On success: + | Field | Type | Description | + | :----------- | :---------------- | :------------------------------------------------------------------------------------- | + | `status` | `"0x1"` | Status indicating that the transaction succeeded | + | `returnData` | `bytes` | Transactions return data | + | `gasUsed` | `uint64` | Gas used by the transaction | + | `logs` | `CallResultLog[]` | Log events emitted during call. This includes ETH logs, if `traceTransfers` is enabled | + +the `CallResultLog` is object of form: + | Field | Type | Description | + | :----------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------- | + | `logIndex` | `uint256` | Log index | + | `blockHash` | `hash32` | Block hash | + | `blockNumber` | `uint64` | Block number | + | `transactionHash` | `hash32` | Transaction hash | + | `transactionIndex` | `uint256` | Transaction index | + | `address` | `address` | Contract that sent the log. When trace transfers is enabled, this field is `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` for ETH transfers. | + | `data` | `bytes` | Event data | + | `topics` | `bytes32[]` | Array of topics | + | `removed` | `bool` | Always false. A flag indicating if a log was removed in a chain reorganization, which cannot happen in eth_simulateV1. | + +**Example:** +Here's an simple `eth_simulateV1` call that sets blocks `baseFeePerGas` to `9`, gives us `0.00000002` ETH and then we send ETH to two addresses. You can find that the output has two logs produced by these ETH sends. This is because we have set `traceTransfers` to true. +```json +{ + "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" + ] +} +``` + +**Example response:** +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "baseFeePerGas": "0x9", + "blobGasUsed": "0x0", + "calls": [ + { + "returnData": "0x", + "logs": [ + { + "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "topics": [ + "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "0x000000000000000000000000c000000000000000000000000000000000000000", + "0x000000000000000000000000c000000000000000000000000000000000000001" + ], + "data": "0x0000000000000000000000000000000000000000000000000000000000000001", + "blockNumber": "0x13d2747", + "transactionHash": "0xe7217784e0c3f7b35d39303b1165046e9b7e8af9b9cf80d5d5f96c3163de8f51", + "transactionIndex": "0x0", + "blockHash": "0x5e28f54a56dc9df973a058cd54b3eeef8c67a1a613cb5db1df8a0a434c931d56", + "logIndex": "0x0", + "removed": false + } + ], + "gasUsed": "0x5208", + "status": "0x1" + }, + { + "returnData": "0x", + "logs": [ + { + "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "topics": [ + "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "0x000000000000000000000000c000000000000000000000000000000000000000", + "0x000000000000000000000000c000000000000000000000000000000000000002" + ], + "data": "0x0000000000000000000000000000000000000000000000000000000000000001", + "blockNumber": "0x13d2747", + "transactionHash": "0xf0182201606ec03701ba3a07d965fabdb4b7d06b424f226ea7ec3581802fc6fa", + "transactionIndex": "0x1", + "blockHash": "0x5e28f54a56dc9df973a058cd54b3eeef8c67a1a613cb5db1df8a0a434c931d56", + "logIndex": "0x1", + "removed": false + } + ], + "gasUsed": "0x5208", + "status": "0x1" + } + ], + "difficulty": "0x0", + "excessBlobGas": "0x0", + "extraData": "0x", + "gasLimit": "0x1c9c380", + "gasUsed": "0xa410", + "hash": "0x5e28f54a56dc9df973a058cd54b3eeef8c67a1a613cb5db1df8a0a434c931d56", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "miner": "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "nonce": "0x0000000000000000", + "number": "0x13d2747", + "parentBeaconBlockRoot": "0x0000000000000000000000000000000000000000000000000000000000000000", + "parentHash": "0xd24222b93a05a066cf79dc20e333f5aa6bb06d36eb50eb2b6b0b744b937e7975", + "receiptsRoot": "0x75308898d571eafb5cd8cde8278bf5b3d13c5f6ec074926de3bb895b519264e1", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "size": "0x298", + "stateRoot": "0xbb0740745211507e2a2a6cdb627dfa171ef5050ad2a01e5401c2e3df4be5b919", + "timestamp": "0x66ec2853", + "totalDifficulty": "0xc70d815d562d3cfa955", + "transactions": [ + "0xe7217784e0c3f7b35d39303b1165046e9b7e8af9b9cf80d5d5f96c3163de8f51", + "0xf0182201606ec03701ba3a07d965fabdb4b7d06b424f226ea7ec3581802fc6fa" + ], + "transactionsRoot": "0x9bdb74f3ce41f5893a02a631e904ae0d21ae8c4e416786d8dbd9cb5c54f1dc0f", + "uncles": [], + "withdrawals": [], + "withdrawalsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421" + } + ] +} +``` + ### eth_subscribe, eth_unsubscribe {#eth-subscribe-unsubscribe} These methods are used for real-time events through subscriptions. See the [subscription documentation](/docs/interacting-with-geth/rpc/pubsub) for more information. @@ -27,52 +216,11 @@ The method takes 4 parameters: an unsigned transaction object to execute in read 3. `Object` - State override set - The _state override set_ is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. Each address maps to an object containing: - - | Field | Type | Bytes | Optional | Description | - | :---------- | :--------- | :---- | :------- | :-------------------------------------------------------------------------------------------------------- | - | `balance` | `Quantity` | <32 | Yes | Fake balance to set for the account before executing the call. | - | `nonce` | `Quantity` | <8 | Yes | Fake nonce to set for the account before executing the call. | - | `code` | `Binary` | any | Yes | Fake EVM bytecode to inject into the account before executing the call. | - | `state` | `Object` | any | Yes | Fake key-value mapping to override **all** slots in the account storage before executing the call. | - | `stateDiff` | `Object` | any | Yes | Fake key-value mapping to override **individual** slots in the account storage before executing the call. | - - The goal of the _state override set_ is manyfold: - - - It can be used by DApps to reduce the amount of contract code needed to be deployed on chain. Code that simply returns internal state or does pre-defined validations can be kept off chain and fed to the node on-demand. - - It can be used for smart contract analysis by extending the code deployed on chain with custom methods and invoking them. This avoids having to download and reconstruct the entire state in a sandbox to run custom code against. - - It can be used to debug smart contracts in an already deployed large suite of contracts by selectively overriding some code or state and seeing how execution changes. Specialized tooling will probably be necessary. - - **Example:** - - ```json - { - "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3": { - "balance": "0xde0b6b3a7640000" - }, - "0xebe8efa441b9302a0d7eaecc277c09d20d684540": { - "code": "0x...", - "state": { - "" - } - } - } - ``` + The _state override set_ is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. Please see [State Override Set](/docs/interacting-with-geth/rpc/objects#state-override-set) for details. 4. `Object` - Block override set - The fields of this optional object customize the block as part of which the call is simulated. The object contains the following fields: - - | Field | Type | Bytes | Optional | Description | - |---------------|----------|-------|----------|----------------------------------------------------------| - | `number` | Quantity | <32 | Yes | Fake block number | - | `difficulty` | Quantity | <32 | Yes | Fake difficulty. Note post-merge difficulty should be 0. | - | `time` | Quantity | <8 | Yes | Fake block timestamp | - | `gasLimit` | Quantity | <8 | Yes | Block gas capacity | - | `coinbase` | String | 20 | Yes | Block fee recipient | - | `random` | Binary | 32 | Yes | Fake PrevRandao value | - | `baseFee` | Quantity | <32 | Yes | Block base fee (see EIP-1559) | - | `blobBaseFee` | Quantity | <32 | Yes | Block blob base fee (see EIP-4844) | + The _block override set_ is an optional object with the purpose of modifying the context in which the call is executed. Refer to [Block overrides](/docs/interacting-with-geth/rpc/objects#block-overrides) for a rundown of the fields. **Response:** @@ -154,7 +302,7 @@ Just for the sake of completeness, decoded the response is: `2`. ### eth_createAccessList {#eth-createaccesslist} -This method creates an [EIP2930](https://eips.ethereum.org/EIPS/eip-2930) type `accessList` based on a given `Transaction`. The `accessList` contains all storage slots and addresses read and written by the transaction, except for the sender account and the precompiles. This method uses the same `transaction` call [object](/docs/interacting-with-geth/rpc/objects#transaction-call-object) and `blockNumberOrTag` object as `eth_call`. An `accessList` can be used to unstuck contracts that became inaccessible due to gas cost increases. +This method creates an [EIP2930](https://eips.ethereum.org/EIPS/eip-2930) type `accessList` based on a given `Transaction`. The `accessList` contains all storage slots and addresses read and written by the transaction, except for the sender account and the precompiles. This method uses the same `transaction` call [Transaction Call Object](/docs/interacting-with-geth/rpc/objects#transaction-call-object) and `blockNumberOrTag` object as `eth_call`. An `accessList` can be used to unstuck contracts that became inaccessible due to gas cost increases. **Parameters:** diff --git a/docs/interacting-with-geth/rpc/objects.md b/docs/interacting-with-geth/rpc/objects.md new file mode 100644 index 0000000000..3546a37c27 --- /dev/null +++ b/docs/interacting-with-geth/rpc/objects.md @@ -0,0 +1,137 @@ +--- +title: Objects +description: Data structures used for RPC methods +--- + +The following are data structures which are used for various RPC methods. + +## Transaction call object {#transaction-call-object} + +The _transaction call object_ contains all the necessary parameters for executing an EVM contract method. + +| Field | Type | Bytes | Optional | Description | +| :--------------------- | :----------- | :---- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `Address` | 20 | Yes | Address the transaction is simulated to have been sent from. Defaults to first account in the local keystore or the `0x00..0` address if no local accounts are available. | +| `to` | `Address` | 20 | No | Address the transaction is sent to. | +| `gas` | `Quantity` | <8 | Yes | Maximum gas allowance for the code execution to avoid infinite loops. Defaults to `2^63` or whatever value the node operator specified via `--rpc.gascap`. | +| `gasPrice` | `Quantity` | <32 | Yes | Number of `wei` to simulate paying for each unit of gas during execution. Defaults to `1 gwei`. | +| `maxFeePerGas` | `Quantity` | <32 | Yes | Maximum fee per gas the transaction should pay in total. Relevant for type-2 transactions. | +| `maxPriorityFeePerGas` | `Quantity` | <32 | Yes | Maximum tip per gas that's given directly to the miner. Relevant for type-2 transactions. | +| `value` | `Quantity` | <32 | Yes | Amount of `wei` to simulate sending along with the transaction. Defaults to `0`. | +| `nonce` | `Quantity` | <8 | Yes | Nonce of sender account. | +| `input` | `Binary` | any | Yes | Binary data to send to the target contract. Generally the 4 byte hash of the method signature followed by the ABI encoded parameters. For details please see the [Ethereum Contract ABI](https://docs.soliditylang.org/en/v0.7.0/abi-spec.html). This field was previously called `data`. | +| `accessList` | `AccessList` | any | Yes | A list of addresses and storage keys that the transaction plans to access. Used in non-legacy, i.e. type 1 and 2 transactions. | +| `chainId` | `Quantity` | <32 | Yes | Transaction only valid on networks with this chain ID. Used in non-legacy, i.e. type 1 and 2 transactions. | +| `maxFeePerBlobGas` | `Quantity` | <32 | Yes | Max fee per blob gas the transaction should pay in total. Relevant for blob transactions. | +| `blobVersionedHashes` | `Array` | any | Yes | Blob versioned hashes that can be accessed from EVM. They will be validated in case `blobs` also provided. Relevant for blob transactions. | +| `blobs` | `Array` | any | Yes | EIP-4844 Blobs. | +| `commitments` | `Array` | any | Yes | Commitments to EIP-4844 Blobs. They will be generated if only `blobs` are present and validated if both `blobs` and `commitments` are provided. | +| `proofs` | `Array` | any | Yes | Proofs for EIP-4844 Blobs. They must be provided along with `commitments`. Else they will be generated. | + +Example for a legacy transaction: + +```json +{ + "from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3", + "to": "0xebe8efa441b9302a0d7eaecc277c09d20d684540", + "gas": "0x1bd7c", + "data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628" +} +``` + +Example for a type-1 transaction: + +```json +{ + "from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3", + "to": "0xebe8efa441b9302a0d7eaecc277c09d20d684540", + "gas": "0x1bd7c", + "data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628", + "chainId": "0x1", + "accessList": [ + { + "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + "storageKeys": ["0xda650992a54ccb05f924b3a73ba785211ba39a8912b6d270312f8e2c223fb9b1", "0x10d6a54a4754c8869d6886b5f5d7fbfa5b4 + 522237ea5c60d11bc4e7a1ff9390b"] + }, { + "address": "0xa2327a938febf5fec13bacfb16ae10ecbc4cbdcf", + "storageKeys": [] + }, + ] +} +``` + +Example for a type-2 transaction: + +```json +{ + "from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3", + "to": "0xebe8efa441b9302a0d7eaecc277c09d20d684540", + "gas": "0x1bd7c", + "maxFeePerGas": "0x6b44b0285", + "maxPriorityFeePerGas": "0x6b44b0285", + "data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628", + "chainId": "0x1", + "accessList": [] +} +``` + +## State override set {#state-override-set} + +The _state override set_ is an optional address-to-state mapping, used in `eth_call` and `eth_simulateV1`, where each entry specifies some state to be ephemerally overridden prior to executing the call. Each address maps to an object containing: + +| Field | Type | Bytes | Optional | Description | +| :------------------------ | :--------- | :---- | :------- | :-------------------------------------------------------------------------------------------------------- | +| `balance` | `Quantity` | <32 | Yes | Fake balance to set for the account before executing the call. | +| `nonce` | `Quantity` | <8 | Yes | Fake nonce to set for the account before executing the call. | +| `code` | `Binary` | any | Yes | Fake EVM bytecode to inject into the account before executing the call. | +| `state` | `Object` | any | Yes | Fake key-value mapping to override **all** slots in the account storage before executing the call. | +| `stateDiff` | `Object` | any | Yes | Fake key-value mapping to override **individual** slots in the account storage before executing the call. | +| `movePrecompileToAddress` | `address` | 20 | Yes | Moves precompile to given address | | + +The goal of the _state override set_ is manyfold: + +- It can be used by websites to reduce the amount of contract code needed to be deployed on chain. Code that simply returns internal state or does pre-defined validations can be kept off chain and fed to the node on-demand. +- It can be used for smart contract analysis by extending the code deployed on chain with custom methods and invoking them. This avoids having to download and reconstruct the entire state in a sandbox to run custom code against. +- It can be used to debug smart contracts in an already deployed large suite of contracts by selectively overriding some code or state and seeing how execution changes. Specialized tooling will probably be necessary. +- It can be used to override `ecrecover` precompile to spoof signatures + +**Example:** + +```json +{ + "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3": { + "balance": "0xde0b6b3a7640000" + }, + "0xebe8efa441b9302a0d7eaecc277c09d20d684540": { + "code": "0x...", + "state": { + "" + } + } +} +``` + +## Block overrides + +The fields of this object customize the block as part of which a call is simulated. This object can be passed to eth_call, eth_simulateV1 as well as debug_traceCall methods and contains the following fields: + +| Field | Type | Description | +| :-------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------- | +| `number` | `uint64` | Block number. | +| `prevRandao` | `uint256` | The previous value of randomness beacon. | +| `time` | `uint64` | Block timestamp. | +| `gasLimit` | `uint64` | Gas limit. | +| `feeRecipient` | `address` | Fee recipient (also known as coinbase). | +| `withdrawals` | `Withdrawals` | Withdrawals made by validators. | +| `baseFeePerGas` | `uint256` | Base fee per unit of gas (see EIP-1559). | +| `blobBaseFee` | `uint64` | Base fee per unit of blob gas (see EIP-4844). | + +The object `withdrawals` is an array of withdrawal objects: + +| Field | Type | Description | +| :--------------- | :-------- | :-------------- | +| `index` | `uint64` | index | +| `validatorIndex` | `uint64` | validator index | +| `address` | `address` | address | +| `amount` | `uint64` | amount | diff --git a/src/data/documentation-links.yaml b/src/data/documentation-links.yaml index f190724ec1..ced92aa8e8 100644 --- a/src/data/documentation-links.yaml +++ b/src/data/documentation-links.yaml @@ -72,6 +72,8 @@ to: /docs/interacting-with-geth/rpc/ns-personal - id: txpool to: /docs/interacting-with-geth/rpc/ns-txpool + - id: objects + to: /docs/interacting-with-geth/rpc/objects - id: JS Console to: /docs/interacting-with-geth/javascript-console - id: 'JS Console 2: Contracts'