# ERC-4337 Simple Whitelist Alt-Mempool

## Problem

The [ERC-4337 spec calls](https://eips.ethereum.org/EIPS/eip-4337#alternative-mempools) for the use of "Alternative Mempools" in order to whitelist entities (paymasters, factories, aggregators, accounts) and allow them to bypass simulation violations. Bundlers are expected to coordinate (off-chain) to construct these whitelists and adopt them as an alternative mempool. In the p2p network this alt-mempool is [assigned an ID](https://github.com/eth-infinitism/bundler-spec/blob/main/p2p-specs/p2p-interface.md#mempool-id) and bundlers can communicate user operations meant for this mempool to other bundlers that support it by ID.

The cost of adding to a whitelist is high. Entities that wish to get added do the whitelist must create an entirely new mempool ID and convince a set of bundlers to adopt it. This can lead to centralization and rent-extraction from entities that manage to get their address whitelisted.

An example of this issue today is an ERC-20 paymaster that wishes to transfer USDC in its validation function. USDC transfers access non-paymaster associated storage, which is banned by the spec. Thus, a paymaster that wishes to use USDC must get added to a whilelist and adopted by bundlers.

## Solution

As of 06/23/23 an updated version of the ERC-4337 specifictaion is being worked on to expand the alt-mempool definition above to include whitelisting specific simulation rule violations in a way that should make the alternative mempool more accessible.

For example, we can whitelist that any paymaster is able to access the "paused" flag on the USDC contract. Any bundler that is willing to take the (small) risk that the paused flag will not change in between simulation and execution, can adopt the mempool with this whitelist.

We have identified the following simulation rules as those that could be added to a whitelist in certain situations. We'd love to hear from other bundlers to know if we should consider other rules! See [here](https://eips.ethereum.org/EIPS/eip-4337#specification-1) for a list of simulation violations.

### Definitions:

**Entity**: In the following rules an entity can refer to one of three things:

1. A particular entity type. One of paymaster, factory, aggregator, account.
2. A particular entity address
3. Any address (denoted by *)

**Contract:** A contract address calling/containing the corresponding opcode, precompile, or slot.

**Opcode:** An EVM opcode from the [specification’s forbidden list](https://eips.ethereum.org/EIPS/eip-4337#simulation).

**Precompile:** A precompile address other than [those supported by L1 Ethereum](https://www.evm.codes/precompiled?fork=shanghai).

**Slot:** A storage slot on a contract.

### Rules

**Forbidden Opcode**

---

This rule allows an entity to use a forbidden opcode while running a particular contract.

**Inputs**:

- Entity
- Contract
- Opcode

**Reason**: An entity may use a forbidden opcode in a contract in a way that can be deemed safe via visual inspection by bundlers.

**Forbidden Precompile**

---

This rule allows an entity to use a forbidden precompile while running a particular contract.

**Inputs**:

- Entity
- Contract
- Precompile

**Reason**: An entity may use a forbidden precompile in a contract in a way that can be deemed safe via visual inspection by bundlers.

**Invalid Storage Access**

---

This rule allows an entity to access a particular, non-associated storage slot on a contract.

**Inputs**:

- Entity
- Contract
- Slot

**Reason**: An entity may require reading some external, non-associated state. Bundlers can deem this read safe by visual inspection.

**Not Staked**

---

This rule allows an entity to bypass staking rules. Thus allowing it to access self-storage without stake.

**Inputs**:

- Entity

**Reason**: They may be reasons why an entity cannot stake (i.e. an autonomous "public-good" singleton contract without an owner), but still needs access to associated storage.

## Schema

In order to facilitate sharing this whitelist we've codified the rules above into a JSON-schema. The resulting whitelists can thus be shared in JSON format, and checked against the schema for correctness. Bundlers can then use the JSON file programmatically in their configuration for the alt-mempool.

As per the p2p spec, this file would be uploaded to IPFS and used to determine the mempool ID.

{
  "$id": "<https://alchemy.com/mempool.schema.json>",
  "$schema": "<https://json-schema.org/draft/2020-12/schema>",
  "description": "JSON Schema for a 4337 Alternative Mempool",
  "type": "object",
  "properties": {
    "description": {
      "type": "string"
    },
    "chainIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "allowlist": {
      "type": "array",
      "additionalItems": false,
      "items": {
        "type": "object",
        "properties": {
          "rule": {
            "type": "string",
            "enum": [
              "forbiddenOpcode",
              "forbiddenPrecompile",
              "invalidStorageAccess",
              "notStaked"
            ]
          },
          "entity": { "$ref": "#/$defs/entity" },
          "contract": { "$ref": "#/$defs/address" },
          "opcode": { "$ref": "#/$defs/opcode" },
          "precompile": { "$ref": "#/$defs/address" },
          "slot": { "$ref": "#/$defs/slot" }
        },
        "additionalProperties": true,
        "oneOf": [
          {
            "properties": {
              "rule": { "const": "forbiddenOpcode" }
            },
            "required": ["rule", "entity", "contract", "opcode"]
          },
          {
            "properties": {
              "rule": { "const": "forbiddenPrecompile" }
            },
            "required": ["rule", "entity", "contract", "precompile"]
          },
          {
            "properties": {
              "rule": { "const": "invalidStorageAccess" }
            },
            "required": ["rule", "entity", "contract", "slot"]
          },
          {
            "properties": {
              "rule": { "const": "notStaked" }
            },
            "required": ["rule", "entity"]
          }
        ]
      }
    }
  },
  "required": ["description", "chainIds", "allowlist"],
  "additionalProperties": true,
  "$defs": {
    "entity": {
      "type": "string",
      "pattern": "^\\\\*|account|paymaster|factory|aggregator|0x[a-fA-F0-9]{40}$"
    },
    "address": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$"
    },
    "opcode": {
      "type": "string"
    },
    "slot": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{2,64}$"
    }
  }
}

## Example

On Polygon Mumbai the USDC contract accesses multiple non-associated storage slots and uses the `GAS` opcode in was that can be visually deemed as safe, or at least safe enough for a Bundler’s risk tolerance. A super-conservative bundler may inspect the rule set and deem it too risky to adopt.

**This whitelist allows any paymaster entity to bypass these simulation violations and transfer USDC in its validation function.**

This whitelist has been tested with the [deployed Pimlico paymaster](https://docs.pimlico.io/reference/erc20-paymaster-contracts).

(The deployed Pimlico USDC paymaster is not staked, added here for testing purposes.)

{
  "description": "USDC paymaster whitelist - Mumbai",
  "chainIds": ["0x013881"],
  "allowlist": [
    {
      "description": "USDC token _paused slot",
      "rule": "invalidStorageAccess",
      "entity": "paymaster",
      "contract": "0x0fa8781a83e46826621b3bc094ea2a0212e71b23",
      "slot": "0x0d"
    },
    {
      "description": "USDC token IMPLEMENTATION_SLOT slot",
      "rule": "invalidStorageAccess",
      "entity": "paymaster",
      "contract": "0x0fa8781a83e46826621b3bc094ea2a0212e71b23",
      "slot": "0xbaab7dbf64751104133af04abc7d9979f0fda3b059a322a8333f533d3f32bf7f"
    },
    {
      "description": "USDC token uses GAS opcode",
      "rule": "forbiddenOpcode",
      "entity": "paymaster",
      "contract": "0x0fa8781a83e46826621b3bc094ea2a0212e71b23",
      "opcode": "GAS"
    },
    {
      "description": "Pimlico USDC paymaster",
      "rule": "notStaked",
      "entity": "0x32acdfea07a614e52403d2c1feb747aa8079a353"
    }
  ]
}

## Feedback

Alchemy would love for this proposal to turn into the first alternative mempool supported by the p2p network, and would like for it to be supported as soon as the network is live. USDC paymasters will likely be the first whitelisted.

The schema above can be used as a framework for defining other mempools with similar rules. This isn't meant to be restrictive of other mempool definitions/frameworks, as there will likely be desired pools that don't fit this schema.

We'd love feedback from other bundlers! If you have ideas for other simulation rules that should be whitelisted please let us know. If you have other known violations that are broadly applicable, we'd love to add them to the whitelist.

Adding additional entries to the whitelist will require publishing a new mempool ID and this requires bundler coordination. We'd love to capture many important use cases before going live.

### Open Questions

- Is the `Entity::type` portion of the schema overkill? Would just supporting all or a specific address be enough? Is there a reason why you’d want to allow a particular entity type to be whitelisted where others cannot?
- Are we missing any violations that should be considered?