Add ERC: Conditional send transaction RPC

Merged by EIP-Bot.

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).