ERC-7796: Conditional send transaction RPC

JSON-RPC API for block builders allowing users to express preconditions for transaction inclusion

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

{
    "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 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.

Citation

Please cite this document as:

Dror Tirosh (@drortirosh), Yoav Weiss (@yoavw), Alex Forshtat (@forshtat), Shahaf Nacson (@shahafn), "ERC-7796: Conditional send transaction RPC [DRAFT]," Ethereum Improvement Proposals, no. 7796, April 2024. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7796.