# Integration API for EIP-4337 bundler with an Ethereum Rollup Sequencer

###### tags: `rollup` `aa` `eip4337` `sequencer`

## Introduction

An EIP-4337 "bundler" is a server that handles multiple UserOperations, and submit them as a single transaction to the network.

The bundler validates each UserOperation, and makes sure it is capable (and willing) to pay.

(Each UserOperation has separate "validation" and "execution" phases. the bundler only validates the "validation" phase, since payment is guaranteed even if "execution" reverts, like normal ethereum transcations)

There is a slight chance that the aggregated transaction would fail, and that can only happen if an account happen to modify its own storage between the time the bundler validated the transaction and the time it was submitted.

We need a way for a bundler to guarantee that no change was made to the network that could cause the transaction to revert.

## Specification

* A new RPC request which is an extension to normal "sendRawTransaction"
* The Method and first param have the same meaning as in normal sendRawTransaction.
* Added a second parameter which is "options"
* within the "options" param, add the following members:
* **knownAccounts**: a map of accounts with expected storage
* The key is account address
* If the value is **hex string**, it is the known storage root hash of that account.
* If the value is an **object**, then each member is in the format of `"slot": "value"`, which are explicit slot values within that account storage.
* **blockNumberMin**: [optional] minimal block number for inclusion
* **blockNumberMax**: [optional] maximum block number for inclusion
* **timestampMin**: [optional] minimum block timestamp for inclusion
* **timestampMax**: [optional] maximum block timestamp for inclusion
* Before accepting the request, the sequencer should:
* If block range was given, check that the block number is within the range.
* If timestamps range was given, check that the block's timestamp is within the range.
* For an address with a storage root hash, validate the current root is unmodified.
* For an address with a list of slots, it should verify that all these slots hold the exact value specified.
* The sequencer should REJECT the request if any address is doesn't pass the above rules.
* The number of the slots/accounts in the knownAccounts structure is known to be below 1000 (TBD) entries.

### Return value

In case of successful inclusion, the call should return the same value as `sendRawTransaction` (namely, the transaction-hash)
In case of failure, it SHOULD return an error with indication of failure reason.
The error code SHOULD be -32003 (transaction rejected) with reason string describing the cause: storage error, out of block/time range,
In case of repeated failures or knownAccounts too large, the error code SHOULD be -32005 (Limit exceeded) with a description of the error

**NOTE:** Even if the transaction was accepted (into the internal mempool), the application MUST NOT assume it actually gets included, and must 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..."
                }
            }     
        } 
    ]
}