ERC-4337 UserOperation Reverts at EntryPoint

To resolve ERC-4337 UserOperation Reverts at EntryPoint, resolve ERC-4337 UserOperation reverts and paymaster rejections. Debug validatePaymasterUserOp signature checks, gas prefunds, and EntryPoint simulation drops. Ensure all derivation paths, environment parameters, and cryptographic signatures are verified client-side using deterministic tools before broadcasting live transactions.

If your bundler returns a UserOperation reverted error at the EntryPoint, the failure is typically localized within the Paymaster validation logic or a deposit imbalance. To resolve this immediately, verify that your paymaster has a sufficient ETH balance deposited in the EntryPoint contract and that the validatePaymasterUserOp function is returning a valid signature.

Immediate Diagnostic JSON

A standard revert stack trace will look like this:

{
  "code": -32602,
  "message": "UserOperation reverted during simulation",
  "data": {
    "revertReason": "AA31 paymaster deposit too low",
    "entryPoint": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"
  }
}

Fix: Ensure the paymaster address has topped up its stake via EntryPoint.depositTo(paymasterAddress, {value: amount}). If the error code is AA33, the paymaster signature is invalid; verify your signing key and the hash being signed.

Architectural Context: The EntryPoint v0.6/v0.7 State Machine

Account Abstraction (ERC-4337) introduces a pseudo-mempool that operates outside the standard Ethereum transaction flow. The EntryPoint contract acts as a central singleton that orchestrates the verification and execution of UserOperations (UserOps). Understanding the nuances of this singleton is key to resolving complex reverts, such as those encountered during coinbase smart wallet passkey recovery.

Phase 1: The Validation Loop (Off-Chain Simulation)

Before a bundler includes a UserOp in a bundle, it must simulate the validation. This is a “dry run” executed via eth_estimateUserOperationGas or debug_traceCall.

The EntryPoint executes:

1. Account Validation: Calls sender.validateUserOp. The account must check the signature and pay the requiredPrefund to the EntryPoint.
2. Paymaster Validation: If a paymaster address is provided, the EntryPoint calls paymaster.validatePaymasterUserOp.

The Paymaster Trap: If the Paymaster’s validation logic consumes too much gas (exceeding the verificationGasLimit), or if it relies on “forbidden state” (like a timestamp or a block hash that might change between simulation and execution), the bundler will drop the UserOp to avoid being slashed. This results in the “Paymaster Declined” error without a clear on-chain trace.

Phase 2: The Execution Loop (On-Chain)

If the simulation passes, the bundler submits the bundle to the handleOps function.

• Inner Reverts: If the actual transaction logic (the callData) fails, the EntryPoint does not revert the whole bundle. Instead, it emits a UserOperationRevertReason event. This is crucial for gas accounting; the bundler still gets paid even if the user’s intent fails, provided the validation was successful.

Production-Grade Prevention: Bundler Tuning and Gas Buffering

Operating an ERC-4337 infrastructure at scale requires more than just smart contracts; it requires a “tuned” bundler configuration that can handle network volatility and signature latency (especially when using WebAuthn/Passkeys).

1. Dynamic Gas Estimation Manual

Standard eth_estimateGas is insufficient for UserOps. You must use the specialized eth_estimateUserOperationGas endpoint.

Gas Calculation Schema:

• preVerificationGas: Covers the overhead of the bundler submitting the transaction.
• verificationGasLimit: Covers the validation logic (Signature check + Paymaster logic).
• callGasLimit: Covers the actual execution of the callData.

Production Buffer Policy: Always inject a multiplier buffer of at least 1.15x for preVerificationGas on L2s like Base or Optimism, as L1 data publication costs can spike between the time of estimation and the time of inclusion.

2. Paymaster Monitoring and Autoscale YAML

Implement a monitoring service that checks paymaster health. If the paymaster deposit drops below a threshold, the service should automatically trigger a “Top-up” transaction from a treasury wallet.

# Paymaster Monitoring Schema
paymaster_config:
  address: "0x..."
  min_deposit_threshold: "0.5 ETH"
  emergency_topup_amount: "2.0 ETH"
  max_gas_price_bid: "50 Gwei"
  simulation_timeout_ms: 5000
  retry_strategy:
    max_attempts: 3
    backoff: exponential

3. Signature Validation with ERC-1271

If your account uses a Multi-Sig or a Passkey (WebAuthn), ensure your validateUserOp function correctly implements the ERC-1271 isValidSignature check. A common cause of AA23 reverts is a mismatch between the userOpHash generated by the EntryPoint and the hash being verified by the smart account’s signature library (e.g., noble-curves or p256-verify).

Maintenance Manual: Quarterly Account Abstraction Health Check

Advanced FAQ Layer

Q1: What is the difference between AA21 and AA31 errors?

AA21 means the Account (sender) has insufficient funds in the EntryPoint to pay for the UserOp. AA31 means the Paymaster has insufficient funds. If you are using a paymaster, you should never see an AA21; if you do, it means your UserOp was incorrectly constructed to not use the paymaster field.

Q2: Why does my UserOp fail on-chain after succeeding in simulation?

This is usually due to State Contention. For example, if your UserOp relies on a specific DEX price that changes before the bundler’s transaction is mined, the callData execution might revert. To prevent this, implement “Slippage Protection” within the callData itself, rather than relying on the EntryPoint’s validation.

Q3: Can I use a Paymaster to pay for gas in ERC-20 tokens?

Yes. This is the “ERC-20 Paymaster” pattern. The paymaster contract must have a price feed (e.g., Chainlink) to calculate the ETH-equivalent cost of the gas. The validatePaymasterUserOp will then include a call to transferFrom on the ERC-20 contract to pull the tokens from the user’s account. Ensure the user has “Approved” the paymaster to spend their tokens before submitting the UserOp.

ERC-4337 EntryPoint Error Code Reference Matrix

Cross-reference standard ERC-4337 EntryPoint revert codes across account abstraction and smart wallet layers:

[!TIP] Unpack packed UserOperations, calculate prefund requirements, and isolate simulation hazards in our air-gapped /tools/erc4337-calldata-decoder/.