Fix: ERC-4337 AA33 Reverted: Paymaster PostOp Execution Failure

When integrating gasless transactions or ERC20 gas payments (paying network fees in USDC/USDT) into Web3 dApps using ERC-4337 Account Abstraction, developers frequently hit an evasive on-chain failure mode:

RPC Error: -32500: EntryPoint simulation failed: AA33 reverted (or empty return data)
    at EntryPoint.handleOps (contracts/core/EntryPoint.sol:184:12)
    at TokenPaymaster.postOp (contracts/paymasters/TokenPaymaster.sol:92:9)
[FATAL]: UserOperation execution reverted in postOp phase. Bundler penalty applied.

The UserOperation simulates smoothly in the bundler’s pre-verification phase (validatePaymasterUserOp returns a valid context), and the user’s primary contract call executes. However, during transaction finalization inside the EntryPoint’s postOp hook, the transaction reverts with AA33.

The root cause of this failure mode is post-execution settlement insolvency or gas starvation: in ERC20 Token Paymasters, the user’s primary execution consumes the tokens or revokes the approval required for fee reimbursement. In Verifying Paymasters, an under-allocated postOpGasLimit causes an out-of-gas condition during the paymaster’s internal accounting reconciliation.

If you are diagnosing pre-verification validation errors (such as timestamp expiration or signature mismatches), consult our companion guide on ERC-4337 UserOperation Reverts at Paymaster: PostOp & Validation Failures.

Architectural Deep-Dive: EntryPoint Execution vs PostOp Phase

The ERC-4337 EntryPoint executes UserOperations in a strict four-stage lifecycle:

$$\text{Validation} \longrightarrow \text{Execution (User Call)} \longrightarrow \text{PostOp Hook} \longrightarrow \text{Gas Settlement}$$

The Two Primary AA33 Revert Vectors

Vector 1: ERC20 Token Paymaster Insolvency

// Inside TokenPaymaster.sol
function postOp(PostOpMode mode, bytes calldata context, uint256 actualGasCost) external override {
    (address sender, uint256 tokenPrice) = abi.decode(context, (address, uint256));
    uint256 tokenAmount = (actualGasCost * tokenPrice) / 1e18;
    
    // CRITICAL FAILURE POINT:
    // If sender balance < tokenAmount or allowance < tokenAmount, transferFrom reverts!
    SafeERC20.safeTransferFrom(token, sender, address(this), tokenAmount);
}

If the user’s callData transacted their entire USDC balance or approved another spender, safeTransferFrom fails, causing EntryPoint to emit AA33.

Vector 2: postOpGasLimit Exhaustion in EntryPoint v0.7

In EntryPoint v0.7, gas parameters are divided into separate slots within paymasterAndData:

• verificationGasLimit (Gas for validatePaymasterUserOp)
• postOpGasLimit (Gas allocated specifically for postOp)

If postOpGasLimit is set too tight (e.g. 15,000 gas) and the paymaster writes state updates, emits events, or queries an on-chain oracle (such as Chainlink), the transaction exhausts its gas budget and reverts with AA33.

Step-by-Step Resolution Protocol

To eliminate AA33 reverts across both Verifying and Token Paymasters, implement this three-phase defensive protocol.

1. Enforce a 35,000 Minimum postOpGasLimit in Bundler Client

In your permissionless.js or Viem client, explicitly configure an adequate postOpGasLimit buffer when constructing the UserOperation:

// src/paymaster/safePaymasterClient.ts
import { type UserOperation } from 'permissionless';

export function padPostOpGasLimit(userOp: any): any {
  const MIN_POST_OP_GAS = 45000n; // Safe baseline for Oracle & SafeERC20 transfers

  // If bundler estimated lower than baseline, apply safety pad
  if (!userOp.postOpGasLimit || BigInt(userOp.postOpGasLimit) < MIN_POST_OP_GAS) {
    console.log(`[PaymasterGuard] Upgrading postOpGasLimit from ${userOp.postOpGasLimit} to ${MIN_POST_OP_GAS}`);
    userOp.postOpGasLimit = MIN_POST_OP_GAS;
  }

  return userOp;
}

2. Pre-Flight Token Balance and Allowance Verification

Before signing a UserOperation that utilizes an ERC20 token paymaster, assert that the smart account will retain sufficient tokens after the transaction executes:

// src/paymaster/verifyTokenSolvency.ts
import { type PublicClient, parseUnits, formatUnits } from 'viem';
import { erc20Abi } from 'viem';

export async function assertTokenPaymasterSolvency(
  client: PublicClient,
  accountAddress: `0x${string}`,
  paymasterAddress: `0x${string}`,
  tokenAddress: `0x${string}`,
  estimatedGasCostUsdc: bigint
) {
  const [balance, allowance] = await Promise.all([
    client.readContract({
      address: tokenAddress,
      abi: erc20Abi,
      functionName: 'balanceOf',
      args: [accountAddress],
    }),
    client.readContract({
      address: tokenAddress,
      abi: erc20Abi,
      functionName: 'allowance',
      args: [accountAddress, paymasterAddress],
    }),
  ]);

  // Buffer gas cost by 25% for market volatility
  const requiredBuffer = (estimatedGasCostUsdc * 125n) / 100n;

  if (balance < requiredBuffer) {
    throw new Error(
      `PAYMASTER_SOLVENCY_ERROR: Insufficient token balance for postOp fee. ` +
      `Have ${formatUnits(balance, 6)} USDC, require ${formatUnits(requiredBuffer, 6)} USDC.`
    );
  }

  if (allowance < requiredBuffer) {
    throw new Error(
      `PAYMASTER_ALLOWANCE_ERROR: Token paymaster lacks approval for postOp transferFrom. ` +
      `Current allowance: ${formatUnits(allowance, 6)}, needed: ${formatUnits(requiredBuffer, 6)}.`
    );
  }

  console.log('[PaymasterGuard] Account verified solvent for postOp settlement.');
  return true;
}

3. Implement Atomic Allowance Batches

If your application executes token operations, batch the paymaster approval inside the same atomic UserOperation using multi-call:

// Call 1: Approve Paymaster for max gas tokens
// Call 2: Execute Primary DeFi Action
const batchedCalls = [
  {
    to: USDC_ADDRESS,
    data: encodeFunctionData({
      abi: erc20Abi,
      functionName: 'approve',
      args: [TOKEN_PAYMASTER_ADDRESS, parseUnits('100', 6)],
    }),
    value: 0n,
  },
  {
    to: DEX_ROUTER_ADDRESS,
    data: swapCalldata,
    value: 0n,
  },
];

Paymaster Diagnostic & Verification Matrix

Frequently Asked Questions

Q: Why does the EntryPoint penalize the bundler if postOp reverts?

Under ERC-4337 rules, if postOp reverts, the bundler still pays the block builder for the execution gas consumed by the user’s transaction. If the paymaster fails to reimburse the EntryPoint, the bundler loses money. As a result, bundlers drop transactions with borderline postOpGasLimit parameters.

Q: Can a Paymaster contract choose not to implement postOp?

Yes. Simple verifying paymasters (which sponsor gas 100% using their own deposited ETH) do not require a postOp hook. In EntryPoint v0.7, such paymasters configure postOpGasLimit: 0 and omit postOp execution entirely, avoiding AA33 risks.

Q: What is the difference between PostOpMode.opSucceeded and PostOpMode.opReverted?

EntryPoint passes PostOpMode as the first argument to postOp. If the user’s primary execution reverted (opReverted), the paymaster is still called to collect gas fees for the wasted execution, but it knows the state changes in the main call did not persist.