v0.9.0

ERC-4337 Version v0.9

Deployment

WARNING! Always verify the EntryPoint deployment address and code hash with the official security audit report before updating. The EntryPoint is a privileged singleton contract that controls the Accounts and Paymasters.

EntryPoint v0.9
0x433709009B8330FDa32311DF1C2AFA402eD8D009

SenderCreator v0.9
0x0A630a99Df908A81115A3022927Be82f9299987e

Summary

1. Compatibility

This version is ABI-compatible with v0.8 and v0.7, and does not require changes in Accounts and Paymasters, unless they want to use any of the new features.
All changes in this version are made without breaking changes to the EntryPoint ABI.

The bundlers need to be aware of the new features in order to join the v0.9 EntryPoint UserOp mempool.

2. Enable parallelizable Paymaster signing with paymasterSignature field.

Previously, the entire paymasterAndData field was included in the userOpHash, forcing users to wait for it to be ready.
When using a signature-based Paymaster service, this created a noticeable and unnecessary delay for the users between taking action and seeing the confirmation UI.

Now, you can use the paymasterSignature parameter to pass the data to your Paymaster even after the UserOperation is signed by the Wallet.

See the documentation for this feature for more details: https://docs.erc4337.io/paymasters/paymaster-signature.html

3. Enable specifying the UserOperation validity range using block numbers.

Previously, the validAfter and validUntil parameters could only specify the timestamps.
However, in some cases the actual smart contracts, dapps or protocols being used rely on block numbers to specify validity ranges for some actions, and this prevented the efficient use of UserOperation’s validity range in those dapps.

Now, setting the highest bit of both validAfter and validUntil parameters indicates to bundlers and the EntryPoint that these values specify the UserOperation’s validity range using block numbers.

4. Ignore the initCode without reverting if the Account already exists.

Enable use of a two-dimensional nonce in UserOperations with initCode.

Previously, the initCode parameter was only allowed to be present in the UserOperation that performs the deployment of the Account.
However, in practice this prevented the undeployed Accounts from using the two-dimensional nonce feature, as only one of the parallel UserOperations could succeed and the rest would revert.

Now, the initCode will be silently ignored if the sender Account already exists, and the UserOperation will execute as usual.
This emits the IgnoredInitCode event for the purpose of observability and debugging.

WARNING: Previously, a contract could make an assumption that if a UserOperation has nonzero initCode, then it's the first UserOperation seen by the account. This assumption is no longer correct. If your Account contracts’ code relies on the old behaviour of the initCode field, this change may affect the security of your Account. As long as your Account does not currently have any logic specific for this case, it is safe to update it.

5. Enable querying the current UserOperation hash during execution.

We have identified a number of use-cases where a third-party contract may benefit from knowing the current UserOperation's userOpHash value.
In order to expose this value, we have added the getCurrentUserOpHash function to the EntryPoint contract.

Note: This function is only available during the execution frame.

6. Better error messages.

Some error messages in the contracts were improved with additional parameters added.

Note: Most error structures remain unchanged in this version of the EntryPoint contract. However, we intend to improve error handling and debugging in ERC-4337 in the future. The FailedOp and AAxx error format may change in a future revision of the ERC-4337.

7. Emit the address of the initialized EIP-7702 Account implementation delegation target.

We have added the EIP7702AccountInitialized event to expose the EIP-7702 delegation target.

8. Make BasePaymaster accept the owner as a parameter instead of using msg.sender

Previously, the msg.sender was hardcoded to become the owner of the BasePaymaster contract upon deployment.

However, this poses a problem when deploying a Paymaster using any kind of a factory contract. With this version, the owner parameter becomes an explicit part of the constructor.

v0.8.0

Release v0.8

EntryPoint 0.8 address

0x4337084d9e255ff0702461cf8895ce9e3b5ff108

Summary

• Native support for EIP-7702 authorizations in the EntryPoint contract

• Native support for ERC-712 based UserOperation hash and signatures

• The unused gas penalty no longer applies if unused gas is below 40,000 gas

• Native Go implementation of ERC-7562 tracer for ERC-4337 bundlers (expected to be merged in Pectra mainnet)

• Minor relaxations to ERC-7562 validation rules

• Bug fixes for issues discovered as part of the AA Bug Bounty Program

  • Prevent initCode front-running
  • Fix errors in calculating Paymaster postOp actualGasUsed value
  • Prevent explicitly setting Paymaster as zero address

Contract changes

1. Native support for EIP-7702 authorizations in the EntryPoint contract (AA-521)

Native EIP-7702 support is added to the Entrypoint contract, reference bundler implementation and ERC-7562 validation rules.
See this document for full description of the EIP-7702 changes to ERC-4337.
Short summary:

a. The UserOperation hash includes the EIP-7702 delegation address
b. The EntryPoint contract checks the delegation address is set correctly
c. The eth_sendUserOperation API accepts the eip7702Auth parameter
d. ERC-7562 validation rules includes a new category called AUTH

2. Introducing the Simple7702Account contract (AA-525)

As part of the v0.8 focus on EIP-7702, we are adding the Simple7702Account contract to the core of the ERC-4337 smart contract distribution. This is a fully audited minimalist smart contract wallet that can be safely authorized by any Externally Owned Account (EOA) and adds full support for all the major features of SmartContract Accounts.

The following ERCs are supported:

• ERC-165
• ERC-721
• ERC-1155
• ERC-1271
• ERC-4337 v0.8

3. Native support for ERC-712 based UserOperation hash and signatures (AA-508)

In order to better support signing with external signers, including hardware wallets, the UserOperation hash and signature calculation is now compatible with ERC-712.

4. Update contract licenses

In order to simplify the use of the framework contracts in commercial products, we changed the license of all interface and utility functions to use the MIT license. The core EntryPoint contract continues to use the GPL license.

5. Prevent initCode front-run (AA-466)

First reported by: @ICARUS as part of the AA Bug Bounty Program

In prior versions, the initCode from a UserOperation can be extracted from a UserOperation in the mempool and executed by front-running the actual UserOperation. The result is that the attacker pays for the account deployment, instead of the account owner. This is problematic because this will cause the already submitted UserOperation to fail
unexpectedly for the wallet, and because users will be required to re-sign and re-submit a new UserOperation. This issue is resolved by the following change in the EntryPoint contract:

Require use of EntryPoint in the SenderCreator helper function, which prevents an execution of initCode outside a context of a UserOperation.
In order to prevent a front-run, the Factory contract now SHOULD perform the following check: require(msg.sender == entryPoint.senderCreator());

6. Fix errors in calculating Paymaster postOp actualGasUsed value (AA-467)

First reported by: 0xdeadbeef and Elwin Chua from the OKX wallet team as part of the AA Bug Bounty Program

Reminder: the “unused gas penalty” mechanism was added in ERC-4337 v0.7 and includes a 10% of unused gas being charged for the UserOperation to avoid DoS attacks that are based on artificially high gas limits (AA-217).

The Paymaster’s postOp method allows a paymaster to calculate how much to charge a user, in case it wants to charge the user, either using ERC-20 tokens or in any other way. However, the value passed to postOp includes the gas used by execution, but neglected to take into account the gas penalty for unused gas.

As a result, the Paymaster doesn’t know the actual payment it will have to make back to the bundler, and will charge the user for less than the actual amount of gas used.

7. Don’t penalize unused gas below threshold (AA-507)

UserOp pays 10% of unused gas. With this change, the account (or paymaster) doesn’t pay below 40,000 gas. That is, if the account defines callGasLimit of 80,000, but end up using only 60,000.

8. Prevent explicitly setting Paymaster as zero address (AA-534)

First reported by: [email protected] as part of the AA Bug Bounty Program and taek from the ZeroDev team

Previously, it was sometimes possible to set the Paymaster address value in the UserOperation to zero address (0x0000000000000000000000000000000000000000) but still provide the paymasterData.
The EntryPoint contract treated zero address as “no paymaster” but a common way to check whether a Paymaster contract is being used is paymasterData.length > 0 and this presents a risk of undefined behaviour in some contracts, wallets and applications.

Now EntryPoint contract will not allow zero address as a Paymaster contract and will require paymasterData to be empty for UserOperations without a paymaster contract.

9. Update IAggregator interface by making validateSignatures function non-view (AA-518)

There is no need to require the aggregator’s validateSignatures method to be immutable.
The aggregator is required to be staked, and thus is “accountable” for any revert, regardless if it
uses its own state or not.

10. Make SenderCreator address public (AA-470)

The SenderCreator is a helper contract that is deployed from the EntryPoint constructor.
It was impossible to read this address as it was a private immutable field which made testing ERC-43337 deployment tedious.
Now this address is exposed by the senderCreator() function.

11. Use transient storage for reentrancy guard (AA-465)

This change makes the gas cost of reentrancy guards in the EntryPoint contract noticeably better. However, note that this requires the underlying network to have activated the EIP-1153 TSTOREand TLOAD opcodes.

12. Better handling of validateUserOp returning wrong data size (AA-527)

Previously, two common invalid states, undeployed sender and reverted validateUserOp function resulted in the same error code AA23 reverted. Now these two are split into AA20 account not deployed and AA23 reverted accordingly.

13. ERC-7562 validation rule changes

The purpose of the validation rules was always to prevent denial of service against the mempool by malicious entities, mainly by preventing inter-dependencies by different UserOperations.
We keep trying to find new ways to relax those rules to allow more use-cases, as long as they don’t open new attack vectors.

a. Allow CREATE/CREATE2 opcodes during sender deployment

We identified some scenarios during contract deployment that we can allow the use of CREATE/CREATE2 contracts

b. Allow storage access for all staked entities

Staked paymasters are allowed arbitrary storage read. We extend that rule to any staked entity.

c. EIP-7702 related rules added

14. Make BasePaymaster use "Ownable2Step" instead of "Ownable” (AA-541)

The BasePaymaster contract has been updated to use the Ownable2Step pattern rather than the Ownable implementation. With Ownable2Step, the current owner must first nominate a new owner. The nominated party then has to explicitly accept the ownership, which adds a confirmation step that prevents accidental transfers.

15. Remove legacy support for chains without "basefee"

This change removes complexity and allows for a consistent fee structure without having to handle alternative scenarios for networks without a base fee.

Release v0.7

ERC-4337 Version 0.7.0

EntryPoint 0.7 address

0x0000000071727De22E5E9d8BAf0edAc6f37da032

Contract changes:

• Simulation functions removed from deployed EntryPoint.
  The simulation methods are meant for off-chain usage, and always revert on-chain. They’re meant to be used only by bundlers. Due to their limited usability, we moved them to a different contract and allowed bundlers to use different methods (e.g. state overrides parameter in eth_call) to simulate the transactions.
• Added delegateAndRevert() helper in EntryPoint to accommodate nodes without state overrides in eth_call and eth_estimateGas
  This allows validation and gas estimation on networks without “state overrides” parameter
• Added ERC-165 "supportsInterface" to the EntryPoint.
• Added a sample TokenPaymaster.
• Added a 10% penalty charge for unused execution gas limit.
  This change is meant to prevent apps from putting transactions with unnecessarily high gas limits, thereby causing the bundler to pack fewer operations into a bundle, losing potential gain. See a more detailed discussion here.
• Removed paymaster’s second call to postOp.
  The second call to paymaster’s postOp function was deprecated as it wasn’t necessary anymore, and now officially removed.
  Now postOp() is called just once. If it reverts, the account’s callData also reverts, but the paymaster still pays for the cost of the execution.
• Added validatePaymasterUserOp and postOp gas limits.
  These gas limits help both the client to better estimate gas for the user operation, and prevent potential security issues.
• Added “gasPrice” parameter to paymaster’s postOp
  This parameter simplifies the work for a token paymaster, to calculate the charge in different currencies..
• Separated offchain UserOperation and packed UserOperation onchain struct.
  To save calldata when calling without a paymaster and to accommodate the new gas limits added to the onchain struct, we decoupled onchain representation of a UserOperation from the offchain one, similar to the initial eth_sendTransaction rpc request and the eventual encoded transaction that’s put onchain.
  This also aligns the structure of ERC-4337 and the future native EIP-7560
• Removed deprecated DepositPaymaster.
• Removed obsolete gnosis safe modules implementation as it was added here.
• Added a new optional account contract api method executeUserOp().
  This addition allows the account to get the full user operation on execution, instead of the original execution, where the account is called directly with the user operation calldata, without having access to the UserOperation metadata during execution phase.
• Minor bug fixes
• EntryPoint better OOG revert handling in userOp execution.
• Various small fixes in the sample contracts
• Minor gas optimizations

ERC changes:

• Separated validation rules into its own separate doc, instead of having a section in the EIP, clearly marking each validation rule <RULE_TYPE>-<RULE_NUMBER>.
  where RULE_TYPE is one of:
  OP - opcode rules
  COD - code rules
  STO - storage rules
  SREP - staked entity reputation rules
  UREP - unstaked entity reputation rules
  EREP - entity-specific reputation rules
  ALT - alternative mempools rules

• Validation rules changes from 0.6.0:
  OP-013 Banning unassigned opcodes to prevent future vulnerabilities via new opcodes.
  OP-051 Allow calling EXTCODESIZE ISZERO to allow calling depositTo().
  OP-054 Forbidding calls to EntryPoint besides depositTo().
  STO-033 Allowing staked entity reading storage on non-entity contracts.
  This relaxation simplifies and extends the usability of paymasters.
  EREP-020 Staked factory is accountable for account breaking validation rules.
  UREP-* Unstaked reputation rules.
  These rules prevent unstaked paymasters from invalidating many user operations at once.
  ALT-* Alt mempools/canonical mempool interactions rules.
  OP-070 Transient storage rules.

Release v0.6

EntryPoint 0.6 address

0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789

Contract changes

Following feedback from the community, we have pushed and deployed a new version of the EntryPoint contract, with a few modifications:

• new userOpHash algorithm (#245)
• nonce managed by EntryPoint (#247)
• prevent recursion of handleOps (#257)

Together, they guarantee that now there is a consistent view of the UserOperation :

• The UserOperation hash is always unique
• Events emitted by the execution of a UserOperation are now uniquely mapped to a UserOperation

This is primarily relevant to external entities (block explorers, wallets, and anyone processing events).

We also asked OpenZeppelin to update the audit to include these changes

The announcement

Effect on Bundlers

If a bundler has an "off-chain" calculation of the hash, it should be updated to the new implementation of the getUserOpHash() helper method in the EntryPoint.

Effect on Wallets

• Existing account contracts can use the new EntryPoint as is, but they can improve their performance by REMOVING the nonce check, as EntryPoint already verifies the nonce uniqueness.
• BaseAccount was updated, so accounts should be recompiled against it.
• the nonce() method was renamed to getNonce(). This is in part for reflecting the new mechanism (it references EntryPoint to read the nonce), but also since in a "[Gnosis] Safe" account we can no longer use the nonce method, as Safe uses nonce for non-AA transactions, and getNonce (and EntryPoint) for AA-based transactions. There is no conflict between the two.
• In order to verify the account is working with a new EntryPoint, it can actively call the entryPoint.getNonce() method (this method is already called from the BaseAccount.
• Wallets should read the next nonce to use in a UserOperation using the getNonce() method, instead of nonce.
• Wallets should also decide if they want to use the "two-dimensional" nonce, by using different values for the key part. (Note that the default GnosisSafeAccount currently enforces sequential nonces, just like a normal safe)

Effect on Block Explorers

Block explorers are not affected directly. They can now safely assume that userOpHash has a unique value.

In conclusion

Even though these changes were not critical, as there were no security implications, we felt that it is better to push such changes now, before wallets get widespread adoption.

version 0.5.0

Account-Abstraction release 0.5.0

This version contains several important changes to the account and entrypoint.
It is also audited by OpenZeppelin (see the audits in the audits folder)

Below are the Major Changes:

Changes to IAccount

• IAccount.validateUserOp changes:
  • removed the "aggregator" parameter.
  • No longer revert on signature error, but report it as a return value.
  • The return value from it is time-range, signature success/failure and (possibly) aggregator.

Changes to Paymaster

• IPaymaster.validateUserOp changes:
  • Like the Account, the return value defines a time-range and signature success/failure
  • Note that in case of signature failure (as in a case of VerifyingPaymaster, it is flagged through return value, and not revert.

Changes to IEntryPoint

• added simulateHandleOp, to simulate a full UserOperation execution (not only validation)
• (and all the API changes required by the above interface changes)

v0.4.0

ERC-4337 Contracts 0.4.0 Release Notes

1. Simulated execution indistinguishable from on-chain execution for contracts (AA-92)
   EntryPoint security improvement. Previously, the 'simulateExection' was defined as a view call to ‘validateUserOperation’ method with 'from' address set to 'address(0)'. This meant that contracts (Account, Paymaster, Aggregator, Factory) could check if their code is running in a simulation or not and behave differently in simulation and execution. It was also impossible to simulate the target call within the context of account-abstraction call, for instance we could not estimate gas for a call on an undeployed wallet. This is solved by adding a separate 'estimateExecution' method to the EntryPoint.

2. Default SimpleAccount now deployed as an upgradeable proxy (AA-74)
   While ERC-4337 does not have a "canonical" wallet, we aim to provide the best-practices example as part of the contracts package. SimpleAccount is now deployed as an ERC-1967 Proxy, making accounts both upgradeable and cheaper to deploy out-of-the-box.

3. Use standard proxy factories or Create2Factory for Gnosis Safe deployments (AA-91)
   Used a non-standard approach previously. Now the only difference in a Gnosis Safe deployed by ERC-4337 is the added ‘Eip4337Manager’ module.

4. Enforce 'verificationGasLimit' and revert with meaningful error messages(AA-85)
   Previously, the 'verificationGasLimit' was not enforced on-chain.

Note: the following changes were made in version 0.3.1 but were not published

5. Implement optional staking and reputation for all contract types - Accounts, Paymasters, Aggregators, Factories (AA-73)
   As each contract in the UserOperation's life cycle has an opportunity to revert, causing the Bundler to have wasted the computation resources spent on verification, without a reputation system the Bundlers become susceptible to denial-of-service and sybil attacks. Requiring some stake to be locked first to create a new contract in the ERC-4337 system prevents that and allows the Bundlers to track these contracts' reputation.
   Note that If a contract does not need to access any storage slots at all it does not need to have a stake.

6. Relax storage rules in opcode banning (AA-67)
   Previously it was forbidden for contracts to access any external contracts' storage slots. This, however, prevented many important use-cases. For instance, a Paymaster that uses an ERC-20 token to pay for UserOperation gas was not feasible. With this new set of rules, the contracts can access the storage slots that are a mapping of the UserOperation Account address or a 'msg.sender' value. Thanks to zkSync for their contribution. They explain this change here: https://v2-docs.zksync.io/dev/developer-guides/aa.html#extending-eip4337