diff --git a/ERCS/erc-7796.md b/ERCS/erc-7796.md new file mode 100644 index 0000000000..1bf7cb636c --- /dev/null +++ b/ERCS/erc-7796.md @@ -0,0 +1,158 @@ +--- +eip: 7796 +title: Conditional send transaction RPC +description: JSON-RPC API for block builders allowing users to express preconditions for transaction inclusion +author: Dror Tirosh (@drortirosh), Yoav Weiss (@yoavw), Alex Forshtat (@forshtat), Shahaf Nacson (@shahafn) +discussions-to: https://ethereum-magicians.org/t/send-transaction-conditional-rpc-api/21480 +status: Draft +type: Standards Track +category: ERC +created: 2024-04-16 +--- + +## Abstract + +This EIP proposes a new JSON-RPC API method `eth_sendRawTransactionConditional` for block builders and sequencers, +enhancing transaction integration by allowing users to express preconditions for transaction inclusion. + +This method aims to improve efficiency by reducing the need for transaction simulation, +thereby improving the computational efficiency of transaction ordering. + +## Motivation + +Current private block builder APIs, such as the Flashbots API, +require block builders to simulate transactions to determine eligibility for inclusion, +a process that is CPU-intensive and inefficient. + +The proposed RPC method addresses this by enabling transactions to specify preconditions, +thus reducing computational overhead and potentially lowering transaction costs. + +Moreover, the flashbots API does not provide the block builder with a mechanism to determine the +cross-dependencies of different transactions. + +The only way to guarantee that another transaction does not interfere with a given one is by placing +it as the first transaction in the block. +This makes this placement very lucrative, and disproportionately expensive. + +In addition, since there is no way to give any guarantee on other slots, their pricing has to be low accordingly. + +Since there is no easy way to detect cross-dependencies of different transactions, +it is CPU-intensive to find an optimal ordering of transactions. + +## Specification + +* Method: `eth_sendRawTransactionConditional` + +* Parameters: + +1. `transaction`: The raw, signed transaction data. Similar to `eth_sendRawTransaction`. +2. `options`: An object containing conditions under which the transaction must be included. +* The `options` parameter may include any of the following optional members: + * **knownAccounts**: a mapping of accounts with their expected storage slots' values. + * The key of the mapping is account address. + * A special key `balance` defines the expected balance of the account. + * A special key `code` defines the expected code of the account. + Use `""` to indicate that address is expected not to have any code. + Use `"0xef01…"` to indicate a specific [EIP-7702](./eip-7702.md) delegation. + * A special key `nonce` defines the expected nonce of the account. + * If the value is **hex string**, it is the known storage root hash of that account. + * If the value is an **object**, then it is a mapping where each member is in the format of `"slot": "value"`. + The `value` fields are explicit slot values of the account's storage. + Both `slot` and `value` are hex-encoded strings. + * **blockNumberMin**: minimal block number for inclusion. + * **blockNumberMax**: maximum block number for inclusion. + * **timestampMin**: minimum block timestamp for inclusion. + * **timestampMax**: maximum block timestamp for inclusion. + * **paysCoinbase**: the caller declares the minimum amount paid to the `coinbase` by this transaction, + including gas fees and direct payment. + +Before accepting the request, the block builder or sequencer SHOULD: + +* Check that the block number is within the block range if the block range value was specified. +* Check that the block timestamp is within the timestamp range if the timestamp range was specified. +* For all addresses with a specified storage root hash, validate the current root is unmodified. +* For all addresses with a specified slot values mapping, validate that all these slots hold the exact value specified. + +The sequencer should REJECT the request if any address does not pass the above rules. + +### Return value + +In case of a successful inclusion, the call should return a hash of the newly submitted transaction. +This behaviour is equivalent to the `eth_sendRawTransaction` JSON-RPC API method. + +In case of an immediate failure to validate the transaction's conditions, +the block builder SHOULD return an error with indication of failure reason. + +The error code SHOULD be "-32003 transaction rejected" with reason string describing the cause: +i.e. storage error, out of block/time range, etc. + +In case of repeated failures or `knownAccounts` mapping being too large for the current block builder to handle, +the error code SHOULD be "-32005 limit exceeded" with a description of the error. + +**NOTE:** Same as with the `eth_sendRawTransaction` method, +even if the RPC method call does not resul in an error and the transaction is +initially accepted into the internal block builder's mempool, +the caller MUST NOT assume that a transaction will be included in a block and should monitor the blockchain. + +### Sample request +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_sendRawTransactionConditional", + "params": [ + "0x2815c17b00...", + { + "blockNumberMax": 12345, + "knownAccounts": { + "0xadd1": "0xfedc....", + "0xadd2": { + "0x1111": "0x1234...", + "0x2222": "0x4567..." + } + } + } + ] +} +``` + +### Limitations + +- Callers should not assume that a successful response means the transaction is included. + Specifically, it is possible that a block re-order might remove the transaction or cause it to fail. + +## Rationale + +The `knownAccounts` only allows specifying the exact values for storage slots. +While in some cases specifying `minValue` or `maxValue` for a slot could be useful, +it would significantly increase complexity of the proposed API. +Additionally, determining the validity range for a slot value is a non-trivial task for the sender of a transaction. + +One way to provide a more complex rule for a transaction condition is by specifying the `paysCoinbase` parameter, +and issuing a transfer to the `coinbase` address on some condition. + +## Backwards Compatibility + +This is a proposal for a new API method so no backward compatibility issues are expected. +Existing non-standard implementations of `eth_sendRawTransactionConditional` API may need to be modified in order to +become compatible with the standard. + +## Security Considerations + +The block builder should protect itself against abuse of the API. +Namely, a malicious actor submitting a large number of requests which are known to fail may lead to a denial of service. + +Following is the list of suggested potential mitigation mechanisms: + +* **Throttling**: the block builder should allow a maximum rate of RPC calls per sender. + The block builder may increase that rate after a successful inclusion. + Repeated rejections of transactions should reduce the allowed rate. +* **Arbitrum**-style protection: Arbitrum implemented this API, but they run the storage validation not only + against the current block, but also into past 2 seconds. + This prevents abusing the API for MEV, while making it viable for [ERC-4337](./eip-4337.md) account validation. +* **Fastlane on Polygon** uses it explicitly for ERC-4337, + by checking the submitted UserOperations exist on the public mempool and rejecting the transaction otherwise. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE.md).