# Table of Contents - [ERC-4337 Documentation – ERC 4337 Documentation](#erc-4337-documentation-erc-4337-documentation) - [UserOperation – ERC 4337 Documentation](#useroperation-erc-4337-documentation) - [EntryPoint Contract – ERC 4337 Documentation](#entrypoint-contract-erc-4337-documentation) - [Architecture – ERC 4337 Documentation](#architecture-erc-4337-documentation) - [Account Factory Contract – ERC 4337 Documentation](#account-factory-contract-erc-4337-documentation) - [Simple Account – ERC 4337 Documentation](#simple-account-erc-4337-documentation) - [Account Contract – ERC 4337 Documentation](#account-contract-erc-4337-documentation) - [Testing a Bundler – ERC 4337 Documentation](#testing-a-bundler-erc-4337-documentation) - [Building a bundler – ERC 4337 Documentation](#building-a-bundler-erc-4337-documentation) - [Introduction – ERC 4337 Documentation](#introduction-erc-4337-documentation) - [Running a Bundler – ERC 4337 Documentation](#running-a-bundler-erc-4337-documentation) - [Paymaster Sol – ERC 4337 Documentation](#paymaster-sol-erc-4337-documentation) - [Running a Paymaster – ERC 4337 Documentation](#running-a-paymaster-erc-4337-documentation) - [Introduction – ERC 4337 Documentation](#introduction-erc-4337-documentation) - [Supporting 4337 – ERC 4337 Documentation](#supporting-4337-erc-4337-documentation) - [Introduction – ERC 4337 Documentation](#introduction-erc-4337-documentation) - [Introduction – ERC 4337 Documentation](#introduction-erc-4337-documentation) - [Reputation scoring and throttling/banning for global entities – ERC 4337 Documentation](#reputation-scoring-and-throttling-banning-for-global-entities-erc-4337-documentation) - [Building for 4337 – ERC 4337 Documentation](#building-for-4337-erc-4337-documentation) - [404: This page could not be found](#404-this-page-could-not-be-found) - [404: This page could not be found](#404-this-page-could-not-be-found) - [404: This page could not be found](#404-this-page-could-not-be-found) --- # ERC-4337 Documentation – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Introduction ERC-4337 Documentation ====================== ### Welcome to the docs! Here you will find guides, references and resources that will help you build with ERC-4337[](#welcome-to-the-docs-here-you-will-find-guides-references-and-resources-that-will-help-you-build-with-erc-4337) What is ERC-4337?[](#what-is-erc-4337) --------------------------------------- [ERC-4337 (opens in a new tab)](https://eips.ethereum.org/EIPS/eip-4337) (Account Abstraction via Entry Point Contract specification) is a specification that aims to use an [entry point contract](/understanding-ERC-4337/entry-point-contract.md) to achieve account abstraction without changing the consensus layer protocol of Ethereum. Instead of modifying the logic of the consensus layer itself, ERC-4337 replicates the functionality of the transaction mempool in a higher-level system. Users send `UserOperation` objects that package up the user’s intent along with signatures and other data for verification. Either miners or bundlers using services such as Flashbots can package up a set of `UserOperation` objects into a single “bundle transaction”, which then gets included into an Ethereum block. ![Diagram of ERC-4337 architecture](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2F4337-diagram.028d7997.png&w=1920&q=75) _[Image source (opens in a new tab)](https://medium.com/infinitism/erc-4337-account-abstraction-without-ethereum-protocol-changes-d75c9d94dc4a) _ ERC-4337 also introduces a paymaster mechanism that can enable users to pay gas fees using ERC-20 tokens (e.g. USDC) instead of ETH or to allow a third party to sponsor their gas fees altogether, all in a decentralized fashion. ERC-4337 is still in draft stage and not finalized yet. However, since ERC-4337 will not change the consensus layer, there are already several implementations available like [eth-infinitsm (opens in a new tab)](https://github.com/eth-infinitism/account-abstraction) and [Stackup (opens in a new tab)](https://github.com/stackup-wallet) . [Architecture](/docs/understanding-ERC-4337/architecture "Architecture") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # UserOperation – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Understanding ERC-4337 UserOperation UserOperation ============= All components of ERC-4337 revolve around a pseudo-transaction object called a `UserOperation` which is used to execute actions through a smart contract account. This isn't to be mistaken for a regular transaction type. | Field | Type | Description | | --- | --- | --- | | `sender` | `address` | The address of the smart contract account | | `nonce` | `uint256` | Anti-replay protection; also used as the salt for first-time account creation | | `initCode` | `bytes` | Code used to deploy the account if not yet on-chain | | `callData` | `bytes` | Data that's passed to the sender for execution | | `callGasLimit` | `uint256` | Gas limit for execution phase | | `verificationGasLimit` | `uint256` | Gas limit for verification phase | | `preVerificationGas` | `uint256` | Gas to compensate the bundler | | `maxFeePerGas` | `uint256` | Maximum fee per gas (similar to [EIP-1559 (opens in a new tab)](https://eips.ethereum.org/EIPS/eip-1559)
`max_fee_per_gas`) | | `maxPriorityFeePerGas` | `uint256` | Maximum priority fee per gas (similar to EIP-1559 `max_priority_fee_per_gas`) | | `paymasterAndData` | `bytes` | Paymaster Contract address and any extra data required for verification and execution (empty for self-sponsored transaction) | | `signature` | `bytes` | Used to validate a UserOperation along with the nonce during verification | UserOperation mempool[](#useroperation-mempool) ------------------------------------------------ Instead of going to the traditional public mempool that hosts pending transactions for EOAs, `UserOperation`s will instead be sent to the `UserOperation` mempool: a dedicated, higher-level mempool specifically for `UserOperation`s. Bundlers listen to the `UserOperation` mempool and bundle multiple `UserOperation`s together into a "classic" transaction. They first verify the validity of the `UserOperation`s using the relevant EntryPoint methods. The bundler then includes that multi-`UserOperation` transaction in the next block they propose to the network. To clarify, that transaction isn't sent to the regular mempool. Bundlers are either block builders themselves, or work together with block builders. [Architecture](/docs/understanding-ERC-4337/architecture "Architecture") [EntryPoint contract](/docs/understanding-ERC-4337/entry-point-contract "EntryPoint contract") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # EntryPoint Contract – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Understanding ERC-4337 EntryPoint contract EntryPoint Contract =================== The EntryPoint contract (which also includes a couple of others, such as StakeManager) is a singleton.  There should only be one implementation because only one instance should exist on each chain. This contract verifies and executes the bundles of UserOperations sent to it. The use of a single EntryPoint contract simplifies the logic used by smart contract wallets, making sure the more complicated smart contract functions needed to ensure safety are tried and battle tested. This allows wallets to focus primarily on the core smart account funcitonality (e.g. signature validation rules). Bundlers/Clients should whitelist their supported EntryPoint contract addresses. [UserOperation](/docs/understanding-ERC-4337/user-operation "UserOperation") [Account contract](/docs/understanding-ERC-4337/account-contract "Account contract") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Architecture – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Understanding ERC-4337 Architecture Architecture ============ There are several main components to ERC-4337: `UserOperation`, `Bundler`, `EntryPoint Contract`, `Account Contract`, `Account Factory Contract` and `Paymaster Contract`. * `UserOperations` are pseudo-transaction objects that are used to execute transactions with contract accounts. These are created by the dapp. Wallets should be able to translate regular transactions into `UserOperations` so dapps' frontends don't need to change anything to support ERC-4337 * `Bundlers` are actors that package UserOperations from a mempool and send them to the EntryPoint contract on the blockchain. For more detailed documentation on bundlers head on to [this part (opens in a new tab)](https://www.erc4337.io/docs/bundlers/introduction) of the documentation. * `EntryPoint` is a smart contract that handles the verification and execution logic for transactions. Account Contracts are smart contract accounts owned by a user. * `Account Contract` is the smart contract wallet of a user. Wallet developers are required to implement at least two custom functions - one to verify signatures, and another to process transactions. * `Factory Contract` - When using a wallet for the first time, the `initCode` field of the `UserOperation` is used to specify creation of the smart contract wallet. This is used concurrently with the first actual operation of the wallet (in the same `UserOperation`). Therefore, wallet developers also need to implement the account factory contract (for example: [`BLSAccountFactory.sol` (opens in a new tab)](https://github.com/eth-infinitism/account-abstraction-samples/blob/master/contracts/bls/BLSAccountFactory.sol) ). Creating new wallets should use the CREATE2 method to ensure the determinacy of generated addresses. * `Paymaster Contracts` are optional smart contract accounts that can sponsor gas fees for Account Contracts, or allow their owners to pay for those fees with ERC-20 tokens instead of ETH. For more detailed documentation on paymasters head on to [this part (opens in a new tab)](https://www.erc4337.io/docs/paymasters/introduction) of the documentation. In practice the process is complex. The typical lifecycle of a transaction looks like this: ![Submit UserOperation to bundler flow](/_next/static/media/4337 Submit UserOperation to bundler.08324fee.svg) [Introduction](/docs "Introduction") [UserOperation](/docs/understanding-ERC-4337/user-operation "UserOperation") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Account Factory Contract – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Understanding ERC-4337 Account Factory contract [Account contract](/docs/understanding-ERC-4337/account-contract "Account contract") [SimpleAccount.sol](/docs/understanding-ERC-4337/simple-account "SimpleAccount.sol") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Simple Account – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Understanding ERC-4337 SimpleAccount.sol [Account Factory contract](/docs/understanding-ERC-4337/account-factory-contract "Account Factory contract") [Introduction](/docs/bundlers/introduction "Introduction") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Account Contract – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Understanding ERC-4337 Account contract Account Contract ================ With EOAs, the address is consistent across all EVM networks. As long as the user has access to the private key they can access the same address on any network. Ideally, we would like to create the same user experience with contract accounts. Users should be able to deterministically know their account address and keep it consistent on every EVM network irrespective of whether the account has been deployed or not. This means that they can generate an account and start sending funds to it with the knowledge that they'll be able to control those funds at any time, provided they have the correct verification method. ERC-4337 does this by using the `CREATE2` opcode through a [Singleton Factory (opens in a new tab)](https://eips.ethereum.org/EIPS/eip-2470) - the [Account Factory contract](/docs/understanding-ERC-4337/account-factory-contract.md) . For example, here is how you can calculate a `CREATE2` address with ethers.js: const accountAddress = ethers.utils.getCreate2Address( fromAddress, salt, initCodeHash ); The contract address would be determined by `fromAddress`, `salt`, and `initCodeHash`. `fromAddress` The fromAddress is the address of the Singleton Factory. This factory receives the `salt` and `initCode` as input and uses CREATE2 to deploy the contract on-chain. Because the Account Factory contract address is the same on every chain, we can rely on it to also deploy our smart contract code on all networks under the same address too. `salt` For an ERC-4337 account, the salt parameter is the first nonce value. This is most likely 0. `initCodeHash` The initCode is passed along as a field on the UserOperation is the smart contract code and arguments used for initializing it. It is hashed using keccak256 to derive the initCodeHash. Authentication and authorization[](#authentication-and-authorization) ---------------------------------------------------------------------- Nonces and replay protection[](#nonces-and-replay-protection) -------------------------------------------------------------- [EntryPoint contract](/docs/understanding-ERC-4337/entry-point-contract "EntryPoint contract") [Account Factory contract](/docs/understanding-ERC-4337/account-factory-contract "Account Factory contract") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Testing a Bundler – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Bundlers Test Coming soon... [Build](/docs/bundlers/building-a-bundler "Build") [Run](/docs/bundlers/running-a-bundler "Run") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Building a bundler – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Bundlers Build Building a bundler ================== If you want to build your own bundler, it's crucial that it passes all the tests covered in our test suite. More on this in the [testing a bundler](/docs/bundlers/testing-a-bundler) section. A good reference point to start with is our basic implementations of a bundler. This bundler focuses on being compliant, not on being fast. Infinitism reference bundler[](#infinitism-reference-bundler) -------------------------------------------------------------- The repo for this bundler can be found here: [https://github.com/eth-infinitism/bundler (opens in a new tab)](https://github.com/eth-infinitism/bundler) This is a reference implementation for a bundler, implementing the full EIP-4337 RPC calls (both production and debug calls), required to pass the [bundler-spec-tests (opens in a new tab)](https://github.com/eth-infinitism/bundler-spec-tests) test suite. To build this bundler on your machine, please follow the instruction of the [repository README (opens in a new tab)](https://github.com/eth-infinitism/bundler#readme) [Introduction](/docs/bundlers/introduction "Introduction") [Test](/docs/bundlers/testing-a-bundler "Test") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Introduction – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Bundlers Introduction Introduction ============ A bundler is the core infrastructure component that allows account abstraction to work on any EVM network without requiring any changes to the protocol. Its purpose is to work with a new mempool of `UserOperations` and get the transaction included on-chain. Security considerations[](#security-considerations) ---------------------------------------------------- When reading the ERC specs, you'll notice that there are many rules a bundler must follow. Each of these rules has been extensively debated and discussed by security researchers and builders within the Ethereum ecosystem. One of the bundler's main jobs is to comply with these rules to prevent all possible DoS attack vectors. These include everything from basic sanity checks that make sure a `UserOperation` is structurally sound to more in-depth tracing for banned opcodes and storage access to make sure bundles cannot be censored once submitted to the network. Similar to Ethereum clients, all bundler implementations are expected to pass a test suite to ensure their compliance and that they won't fragment the mempool. Yoav Weiss wrote [an article (opens in a new tab)](https://notes.ethereum.org/@yoav/unified-erc-4337-mempool) explaining the importance of this point. UserOperation mempool[](#useroperation-mempool) ------------------------------------------------ The canonical mempool for EIP-4337 is decentralized and is made up of a permissionless P2P network of independent bundlers. [SimpleAccount.sol](/docs/understanding-ERC-4337/simple-account "SimpleAccount.sol") [Build](/docs/bundlers/building-a-bundler "Build") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Running a Bundler – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Bundlers Run Verifying `UserOperation` validity[](#verifying-useroperation-validity) ------------------------------------------------------------------------ When a bundler receives a `UserOperation`, it must first run some basic sanity checks, namely that: * Either the `sender` is an existing contract, or the `initCode` is not empty (**but not both**) * If `initCode` is not empty, parse its first 20 bytes as a factory address. Record whether the factory is staked, in case the later simulation indicates that it needs to be. If the factory accesses global state, it must be staked - see [reputation, throttling and banning](/docs/faqs/reputation-throttling-banning.md) section for details. * The `verificationGasLimit` is sufficiently low (`<= MAX_VERIFICATION_GAS`) and the `preVerificationGas` is sufficiently high (enough to pay for the calldata gas cost of serializing the `UserOperation` plus `PRE_VERIFICATION_OVERHEAD_GAS`) * The `paymasterAndData` is either empty, or start with the **paymaster** address, which is a contract that (i) currently has nonempty code on chain, (ii) has a sufficient deposit to pay for the `UserOperation`, and (iii) is not currently banned. During simulation, the paymaster's stake is also checked, depending on its storage usage - see [reputation, throttling and banning](/docs/faqs/reputation-throttling-banning.md) section for details. * The callgas is at least the cost of a `CALL` with non-zero value. The `maxFeePerGas` and `maxPriorityFeePerGas` are above a configurable minimum value that the bundler is willing to accept. At the minimum, they are sufficiently high to be included with the current `block.basefee`. The `sender` doesn't have another `UserOperation` already present in the pool (or it replaces an existing entry with the same `sender` and `nonce`, with a higher `maxPriorityFeePerGas` and an equally increased `maxFeePerGas`). Only one `UserOperation` per `sender` may be included in a single batch. A `sender` is exempt from this rule and may have multiple `UserOperations` in the pool and in a batch if it is staked (see [reputation, throttling and banning](/docs/faqs/reputation-throttling-banning.md) section), but this exception is of limited use to normal accounts. If the UserOperation object passes these sanity checks, the bundler must next run the first op simulation, and if the simulation succeeds, the bundler must add the op to the pool. A second simulation must also happen during bundling to make sure the `UserOperation` is still valid. Simulation[](#simulation) -------------------------- In order to add a `UserOperation` into the UserOp mempool (and later to add it into a bundle) we need to "simulate" its validation to make sure it is valid, and that it is capable of paying for its own execution. In addition, we need to verify that the same will hold true when executed on-chain. For this purpose, a `UserOperation` is not allowed to access any information that might change between simulation and execution, such as current block time, number, hash etc. In addition, a `UserOperation` is only allowed to access data related to this `sender` address: Multiple `UserOperations` should not access the same storage, so that it is impossible to invalidate a large number of `UserOperations` with a single state change. There are 3 special contracts that interact with the account: the factory (`initCode`) that deploys the contract, the paymaster that can pay for the gas, and signature aggregator. Each of these contracts is also restricted in its storage access, to make sure `UserOperation` validations are isolated. Storage associated with an address[](#storage-associated-with-an-address) -------------------------------------------------------------------------- We define storage slots as "associated with an address" as all the slots that uniquely related on this address, and cannot be related with any other address. In solidity, this includes all storage of the contract itself, and any storage of other contracts that use this contract address as a mapping key. An address `A` is associated with: 1. Slots of contract `A` address itself. 2. Slot `A` on any other address. 3. Slots of type `keccak256(A || X) + n` on any other address. (to cover `mapping(address => value)`, which is usually used for balance in ERC-20 tokens). `n` is an offset value up to 128, to allow accessing fields in the format `mapping(address => struct)` [Test](/docs/bundlers/testing-a-bundler "Test") [Introduction](/docs/paymasters/introduction "Introduction") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Paymaster Sol – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Paymasters Paymaster.sol Coming soon... [Introduction](/docs/paymasters/introduction "Introduction") [Running a paymaster](/docs/paymasters/running-a-paymaster "Running a paymaster") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Running a Paymaster – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Paymasters Running a paymaster Coming soon... [Paymaster.sol](/docs/paymasters/paymaster-sol "Paymaster.sol") [Introduction](/docs/wallets/introduction "Introduction") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Introduction – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Paymasters Introduction Introduction ============ One of the main reasons why the user experience of using EOAs is so difficult is because the wallet owner needs to find a way to get some ETH before they can perform any actions on-chain. With paymasters, ERC-4337 allows abstracting gas payments altogether, meaning ​​someone other than the wallet owner can pay for the gas instead. Gas abstraction offers plenty of benefits, such as: * The need to acquire ETH before performing on-chain actions creates a significant friction point for users who are not crypto-savvy. * Users don’t pay AWS fees for using web2 apps, so paying gas fees for using dapps could feel foreign and wrong to them. Paymasters allow dapps to sponsor those fees instead. Alternatively, dapps can instead allow the user to pay for gas in some ERC-20 token other than ETH, for example with USDC. * To preserve privacy, a user can interact with assets in their account (for example, claimed tokens), without having to dox themselves by sending ETH from another KYCed wallet or CEX to pay for gas fees. [Run](/docs/bundlers/running-a-bundler "Run") [Paymaster.sol](/docs/paymasters/paymaster-sol "Paymaster.sol") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Supporting 4337 – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Wallets Supporting 4337 To support ERC-4337, wallets must implement a smart contract that is required to have two functions: * `validateUserOp`, which takes a `UserOperation` as input. This function is supposed to verify the signature and nonce on the `UserOperation`, pay the fee and increment the nonce if verification succeeds, and throw an exception if verification fails. * An op execution function, that interprets calldata as an instruction for the wallet to take actions. How this function interprets the calldata and what it does consequently is completely open-ended. However, we expect the most common behavior would be to parse the calldata as an instruction for the wallet to make one or more calls. The ERC-4337 core team has implemented [`SimpleAccount.sol` (opens in a new tab)](https://github.com/eth-infinitism/account-abstraction/blob/develop/contracts/accounts/SimpleAccount.sol) , a sample minimal account that extends [`BaseAccount.sol` (opens in a new tab)](https://github.com/eth-infinitism/account-abstraction/blob/develop/contracts/core/BaseAccount.sol) , which implements the [`IAccount` (opens in a new tab)](https://github.com/eth-infinitism/account-abstraction/blob/develop/contracts/interfaces/IAccount.sol) interface. [Introduction](/docs/wallets/introduction "Introduction") [Introduction](/docs/dapps/introduction "Introduction") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Introduction – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Dapps Introduction Coming soon... [Supporting 4337](/docs/wallets/supporting-4337 "Supporting 4337") [Building for 4337](/docs/dapps/building-for-4337 "Building for 4337") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Introduction – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Wallets Introduction Coming soon... [Running a paymaster](/docs/paymasters/running-a-paymaster "Running a paymaster") [Supporting 4337](/docs/wallets/supporting-4337 "Supporting 4337") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Reputation scoring and throttling/banning for global entities – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs FAQs Reputation, throttling and banning Reputation scoring and throttling/banning for global entities ============================================================= `UserOperation`'s storage access rules prevent them from interfering with each other. But "global" entities - paymasters, factories and aggregators are accessed by multiple `UserOperations`, and thus might invalidate multiple previously-valid `UserOperations`. Staking[](#staking) -------------------- To prevent abuse, we throttle down (or completely ban for a period of time) an entity that causes invalidation of a large number of `UserOperations` in the mempool. To prevent such entities from carrying out [sybil-attacks (opens in a new tab)](https://en.wikipedia.org/wiki/Sybil_attack) , the protocol requires them to stake with the system, and thus make such DoS attacks very expensive. Note that this stake is never slashed, and can be withdrawn at any time (after an unstake delay period). When staked, an entity is also allowed to use its own associated storage, in addition to sender's associated storage. The stake value is not enforced on-chain, but specifically by each node while simulating a transaction. The stake is expected to be above `MIN_STAKE_VALUE`, and unstake delay above `MIN_UNSTAKE_DELAY`. The value of `MIN_UNSTAKE_DELAY` is 84600 (one day). The value of `MIN_STAKE_VALUE` is determined per chain, and specified in the "bundler specification test suite" Un-staked entities[](#un-staked-entities) ------------------------------------------ Under the following special conditions, unstaked entities still can be used: * An entity that doesn't use any storage at all, or only the sender's storage (not the entity's storage - that does require a stake) * If the `UserOperation` doesn't create a new account (that is `initCode` is empty), then the entity may also use [storage associated with the sender](/docs/bundlers/running-a-bundler.md) * A paymaster that has a `postOp()` method (that is, `validatePaymasterUserOp` returns `“context”`) must be staked [Building for 4337](/docs/dapps/building-for-4337 "Building for 4337") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # Building for 4337 – ERC 4337 Documentation [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) docs Dapps Building for 4337 Coming soon... [Introduction](/docs/dapps/introduction "Introduction") [Reputation, throttling and banning](/docs/faqs/reputation-throttling-banning "Reputation, throttling and banning") ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # 404: This page could not be found [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) 404 === This page could not be found. ----------------------------- ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # 404: This page could not be found [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) 404 === This page could not be found. ----------------------------- ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. --- # 404: This page could not be found [![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg)](/) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) ![](/_next/static/media/menu.77af4908.svg) 404 === This page could not be found. ----------------------------- ![logo](/_next/static/media/ERC-4337-team-logo-color.da15dbff.svg) [Documentation](/docs) [Resources](/resources) [Bundlers](/bundlers) [Paymasters](/paymasters) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ftwitter.cfdd0838.png&w=96&q=75)](https://twitter.com/erc4337) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgithub.84064f7f.png&w=96&q=75)](https://github.com/eth-infinitism/account-abstraction) [![logo](/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fdiscord.f13d78f1.png&w=96&q=75)](https://discord.gg/cXSpMUpWnC) © 2023 Ethereum Foundation. All Rights Reserved. ---