add eth_simulateV1
#484
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,226 @@ | ||
| # Multicall | ||
| This document contains some extra information that couldn't be fit to the specification document directly. | ||
|
|
||
| ## Default block values | ||
| Unlike `eth_call`, `eth_multicallV1`'s calls are conducted inside blocks. We don't require user to define all the fields of the blocks so here are the defaults that are assumed for blocks parameters: | ||
|
|
||
| | parameter name | default value | | ||
| -----------------|----------------------- | ||
| | prevRandao | `0x0000000000000000000000000000000000000000000000000000000000000000` | | ||
| | feeRecipient | `0x0000000000000000000000000000000000000000` | | ||
| | mixHash | `0x0000000000000000000000000000000000000000000000000000000000000000` | | ||
| | nonce | `0x0` | | ||
| | extraData | `0x0000000000000000000000000000000000000000000000000000000000000000` | | ||
| | difficulty | The same as the base block defined as the second parameter in the call | | ||
| | gasLimit | The same as the base block defined as the second parameter in the call | | ||
| | hash | Calculated normally, except for phantom blocks, see below Phantom block section | | ||
| | parentHash | Previous blocks hash (the real hash, or phantom blocks hash) | | ||
| | timestamp | The timestamp of previous block + 1 | | ||
| | baseFeePerGas | Calculated on what it should be according to ethereum's spec. Note: baseFeePerGas is not adjusted in the phantom blocks. | | ||
| | sha3Uncles | Empty trie root | | ||
| | withdrawals | Empty array | | ||
| | uncles | Empty array | | ||
| | number | Previous block number + 1 | | ||
| | logsBloom | Calculated normally. ETH logs are not part of the calculation | | ||
| | receiptsRoot | Calculated normally | | ||
| | transactionsRoot | Calculated normally | | ||
| | size | Calculated normally | | ||
| | withdrawalsRoot | Calculated normally | | ||
| | gasUsed | Calculated normally | | ||
| | stateRoot | Calculated normally | | ||
|
|
||
| An interesting note here is that we decide timestamp as `previous block timestamp + 1`, while `previous block timestamp + 12` could also be an assumed default. The reasoning to use `+1` is that it's the minimum amount we have to increase the timestamp to keep them valid. While `+12` is what Mainnet uses, there are other chains that use some other values, and we didn't want to complicate the specification to consider all networks. | ||
|
|
||
| ### Phantom blocks | ||
| The multicall allows you to define on what block number your calls or transactions are being executed on. E.g, consider following call: | ||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 1, | ||
| "method": "eth_multicallV1", | ||
| "params": [ | ||
| { | ||
| "blockStateCalls": [ | ||
| { | ||
| "blockOverrides": { | ||
| "number": "0x64" | ||
| }, | ||
| }, | ||
| { | ||
| "blockOverrides": { | ||
| "number": "0xc8" | ||
| }, | ||
| } | ||
| ] | ||
| }, | ||
| "0xa" | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Here we want our calls to be executed in blocks 100 (`0x64`) and in 200 (`0xc8`). The block numbers can be anything as long as they are increasing and higher than the block we are building from 10 (`0xa`). Now we end up in a situation where there exists block ranges 11-99 and 101-199 that are not defined anywhere. These blocks are called "phantom blocks". What happens if you try to request block hash of any of such blocks in the EVM? How can we calculate the block hash of future blocks when we don't know the block hash of the previous block? | ||
|
|
||
| Our solution to this problem is to define block hash of a phantom block to be: | ||
|
|
||
| ``` | ||
| keccak(rlp([hash_of_previous_non_phantom_block, phantom_block_number])) | ||
| ``` | ||
|
|
||
| So for example in our example, you could get block hash of block 142 as follows: | ||
| ``` | ||
| keccak(rlp([hash of block 12, 142])) | ||
| ``` | ||
|
|
||
| The phantom blocks other properties are set to their default properties as defined by the multicall specification. We came to this definition by wanting phantom block hashes to be unique if things prior to the phantom block changes, so if tooling is storing block hashes somewhere, they should remain unique if things change in the simulation. | ||
|
|
||
| One other approach to this problem would be to really calculate the real block hashes for all the phantom blocks, but this would make generating blocks far in future really expensive, as to generate 100 phantom blocks, you would need to calculate 100 block hashes that all depend on each other. And in most cases, no one really cares about these blocks. | ||
|
|
||
| Base fee per gas is not adjusted in the phantom blocks, their base fee remains constant. | ||
|
|
||
| ## Default values for transactions | ||
| As multicall is an extension to `eth_call` we want to enable the nice user experience that the user does not need to provide all required values for a transaction. We are assuming following defaults if the variable is not provided by the user: | ||
| | parameter name | description | | ||
| -----------------|----------------------- | ||
| | type | `0x2` | | ||
| | nonce | Defaults to correct nonce | | ||
| | to | `null` | | ||
| | from | `0x0000000000000000000000000000000000000000` | | ||
| | gas limit | Remaining gas in the current block. This is calculated dynamically one by one for each transaction that is being processed. | | ||
| | value | `0x0` | | ||
| | input | no data | | ||
| | gasPrice | `0x0` | | ||
| | maxPriorityFeePerGas | `0x0` | | ||
| | maxFeePerGas | `0x0` | | ||
| | accessList | empty array | | ||
|
|
||
| ## Overriding default values | ||
| The default values of blocks and transactions can be overriden. For Transactions we allow overriding of variables `type`, `nonce`, `to`, `from`, `gas limit`, `value`, `input`, `gasPrice`, `maxPriorityFeePerGas`, `maxFeePerGas`, `accessList`, and for blocks we allow modifications of `number`, `time`, `gasLimit`, `feeRecipient`, `prevRandao` and `baseFeePerGas`: | ||
|
There was a problem hiding this comment. Slight nit: for completeness, |
||
| ```json | ||
| "blockOverrides": { | ||
| "number": "0x14", | ||
| "time": "0xc8", | ||
| "gasLimit": "0x2e631", | ||
| "feeRecipient": "0xc100000000000000000000000000000000000000", | ||
| "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000001234", | ||
| "baseFeePerGas": "0x14" | ||
| }, | ||
| ``` | ||
| All the other fields are computed automatically (eg, `stateRoot` and `gasUsed`) or kept as their default values (eg. `uncles` or `withdrawals`). When overriding `number` and `time` variables for blocks, we automatically check that the block numbers and time fields are strictly increasing (we don't allow decreasing, or duplicated block numbers or times). If the block number is increased more than `1` compared to the previous block, phantom blocks are created to fill the gaps. | ||
|
|
||
| An interesting note here is that an user can specify block numbers and times of some blocks, but not for others. When block numbers of times are left unspecified, the default values will be used. After the blocks have been constructed, and default values are calculated, the blocks are checked that their block numbers and times are still valid. | ||
|
|
||
| ## ETH transfer logs | ||
| When `traceTransfers` setting is enabled on `eth_multicallV1` The multical will return logs for ethereum transfers along with the normal logs sent by contracts. The ETH transfers are identical to ERC20 transfers, except the "sending contract" is address `0x0`. | ||
|
There was a problem hiding this comment. I'd suggest using Here's a simple sourcegraph search showing usage: https://sourcegraph.com/search?q=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&groupBy=repo There was a problem hiding this comment. I suspect if you were to do a similar search of If we ignore any past precedence, I feel like That being said, I don't have a strong argument against 0xEeee..., only that I think 0x000... is marginally better and I suspect more widely used. There was a problem hiding this comment. I agree a search for the zero address would yield more results, but only because the zero address is used for a much wider range of cases, whereas Personally, if I didn't know about the special ETH logs, seeing There was a problem hiding this comment.
Sorry, I meant if you could somehow limit the search of
For what it is worth, this feature is disabled by default and you need to set a flag to turn it on. I'm not sure that is a meaningful argument though. There was a problem hiding this comment.
I agree with @mds1 that There was a problem hiding this comment. I believe the spec has since been updated to use There was a problem hiding this comment. The notes still mentions Aside: It still feels "unclean" to me using a specific non-reserved address, but in researching this I was surprised to learn that EIP-1352 was never officially adopted. There was a problem hiding this comment.
having it as Edit: this is a purely aesthetic choice, though I would find it helpful There was a problem hiding this comment. I and others have argued against EIP-1191 in the discussion for it: ethereum/EIPs#1121 My position is still largely the same. It is backward incompatible with EIP-55 checksumming, so I generally don't recommend apps checksum to 1191 until long after almost all tooling supports reading 1191 checksums. |
||
|
|
||
| For example, here's a query that will simply send ether from one address to another (with a state override that gives us the ETH initially): | ||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 1, | ||
| "method": "eth_multicallV1", | ||
| "params": [ | ||
| { | ||
| "blockStateCalls": [ | ||
| { | ||
| "stateOverrides": { | ||
| "0xc000000000000000000000000000000000000000": { | ||
| "balance": "0x7d0" | ||
| } | ||
| }, | ||
| "calls": [ | ||
| { | ||
| "from": "0xc000000000000000000000000000000000000000", | ||
| "to": "0xc100000000000000000000000000000000000000", | ||
| "value": "0x3e8" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "traceTransfers": true | ||
| }, | ||
| "latest" | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| The output of this query is: | ||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 1, | ||
| "result": [ | ||
| { | ||
| "number": "0x4", | ||
| "hash": "0x859c932c5cf0dabf8d12eb2518e063966ac1a25e2fc49f1f02574a37f358d0b5", | ||
| "timestamp": "0x1f", | ||
| "gasLimit": "0x4c4b40", | ||
| "gasUsed": "0x5208", | ||
| "feeRecipient": "0x0000000000000000000000000000000000000000", | ||
| "baseFeePerGas": "0x2310a91d", | ||
| "prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000", | ||
| "calls": [ | ||
| { | ||
| "returnData": "0x", | ||
| "logs": [ | ||
| { | ||
| "address": "0x0000000000000000000000000000000000000000", | ||
| "topics": [ | ||
| "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", | ||
| "0x000000000000000000000000c000000000000000000000000000000000000000", | ||
| "0x000000000000000000000000c100000000000000000000000000000000000000" | ||
| ], | ||
| "data": "0x00000000000000000000000000000000000000000000000000000000000003e8", | ||
| "blockNumber": "0x4", | ||
| "transactionHash": "0xa4d41019e71335f8567e17746b708ddda8b975a9a61f909bd3df55f4866cc913", | ||
| "transactionIndex": "0x0", | ||
| "blockHash": "0x859c932c5cf0dabf8d12eb2518e063966ac1a25e2fc49f1f02574a37f358d0b5", | ||
| "logIndex": "0x0", | ||
| "removed": false | ||
| } | ||
| ], | ||
| "gasUsed": "0x5208", | ||
| "status": "0x1" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Here the interesting part is: | ||
| ```json | ||
| "address": "0x0000000000000000000000000000000000000000", | ||
| "topics": [ | ||
| "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", | ||
| "0x000000000000000000000000c000000000000000000000000000000000000000", | ||
| "0x000000000000000000000000c100000000000000000000000000000000000000" | ||
| ], | ||
| "data": "0x00000000000000000000000000000000000000000000000000000000000003e8", | ||
| ``` | ||
| In the observed event, the sender address is denoted as the zero address (`0x0`). The first topic (`0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef`) aligns with the event signature `Transfer(address,address,uint256)`, while the second topic (`0x000000000000000000000000c000000000000000000000000000000000000000`) corresponds to the sending address, and the third topic (`0x000000000000000000000000c100000000000000000000000000000000000000`) represents the receiving address. The quantity of ETH transacted is stored in the data field. | ||
|
|
||
| The ETH logs will contain following types of ETH transfers: | ||
| - Transfering ETH from EOA | ||
| - Transfering ETH via contract | ||
| - Selfdestructing contract sending ETH | ||
|
|
||
| But not following ones: | ||
| - Gas fees | ||
| - Multicalls eth balance override | ||
|
|
||
| ETH logs are not part of the calculation for logs bloom filter. Also, similar to normal logs, if the transaction sends ETH but the execution reverts, no log gets issued. | ||
|
|
||
| ## Validation | ||
| The multicall has a feature to enable or disable validation with setting `Validation`, by default, the validation is off, and the multicall mimics `eth_call` with reduced number of checks. Validation enabled mode is intended to give as close as possible simulation of real EVM block creation, except there's no checks for transaction signatures and we also allow one to send a direct transaction from a contract. | ||
|
There was a problem hiding this comment. I am not entirely sure what this would remove/add. If I turn this on, in what situation would this be useful, and what would change if I would have kept it off? 🤔 There was a problem hiding this comment. For instance, if validation is set to off, are tx gas limits not checked? (So I can include a tx with gas limit higher than the block gas limit?). There was a problem hiding this comment. Never mind, it is in There was a problem hiding this comment. This is bit ill defined (as discussed in todays call). Because Nethermind and Geth behave bit differently with There was a problem hiding this comment. Then I think this spec should explicitly state what should be not be validated if the validation is off. For instance, currently it only seems that you can override the sender (so you can create unsigned txs). But, it also seems that it is possible to set base fee to zero (so do not validate this as well). It should be clearly defined what should be validated and what not. (And this is non-trivial since there is a huge ruleset of what should be validated in transactions/blocks) There was a problem hiding this comment. For validation mode, I'm fine with base fee not being allowed to go below 7. There was a problem hiding this comment. I don't think it makes sense that much to validate base fee in validation mode if the user specifically sets the base fee to something. Otherwise we could remove all overrides for validation mode, as none of them can happen on mainnet. There was a problem hiding this comment.
Please no! In fact I want to argue that we should remove That said, we should still define exactly what is not validated in relax-mode. So I think that convo is important to have. And I will share here exactly what geth is validating: For block validation, only these fields are validated:
As for tx validation, these are NOT validated:
There was a problem hiding this comment. I'd like to add that these relaxations are all cause for a transaction not to go through. I.e. if I have a call that works in the relax-mode, sign it and submit it to a node, it will not be gossiped to the network at all. I'd argue if there is any danger to a user it's from all of the flexibility we're providing through state and precompile overrides. E.g. they assume in the simulation to be in a certain condition by using overrides, and submit the transaction when that is not met. That tx will be mined and will revert (most probably). There was a problem hiding this comment.
Our team would like it because it allows us to verify that the transaction is properly constructed and will execute against mainnet without error. In some cases we ship a set of transactions as a "bundle" to searchers, and they need to all execute properly in sequence (including things like balance checks), and in other cases we ship a single transaction to a signer and we want a high degree of confidence that it will execute on-chain just like it did during simulation. |
||
|
|
||
| ## Failures | ||
| It is possible that user defines a transaction that cannot be included in the Ethereum block as it breaks the rules of EVM. For example, if transactions nonce is too high or low, baseFeePerGas is too low etc. In these situations the execution of multicall ends and an error is returned. | ||
|
|
||
| ## Version number | ||
| The method name for multicall `eth_multicallV1` the intention is that after release of multicall, if new features are wanted the `eth_multicallV1` is kept as it is, and instead `eth_multicallV2` is published with the new wanted features. | ||
|
|
||
| ## Clients can set their own limits | ||
| Clients may introduce their own limits to prevent DOS attacks using the method. We have thought of three such standard limits | ||
| - How many blocks can be defined in `BlockStateCalls`. The suggested default for this is 256 blocks | ||
| - A global gas limit (similar to the same limit for `eth_call`). The multicall cannot exceed the global gas limit over its lifespan | ||
| - The clients can set their own limit on how big the input JSON payload can be. A suggested default for this is 30mb | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These default values will crash, since baseFeePerGas is always 7 or higher. These default values will be rejected by blockchain spec, since tx is not willing to pay base fee. Note that the default block
baseFeePerGasis calculated according to spec, so this will be 7 or higher always.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestion: change
maxFeePerGasandgasPrice(in case of tx type 0/1) tobaseFeePerGasof the block and keepmaxPriorityFeePerGas0.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, this will crash on validation mode. On non-validation mode, we will allow you to make transactions that have zero basefee (similar to eth_call)