ERC-7769 JSON-RPC API for ERC-4337

Draft · Accounts & wallets · created 2024-08-23

Defines common JSON-RPC methods used by smart account wallets to communicate with ERC-4337 bundlers. It allows submitting UserOperations, estimating gas, and querying results, much like regular transactions.

Why it is needed

In ERC-4337 account abstraction, a user's request is represented not as a regular Ethereum transaction but as a separate object called a UserOperation. However, existing Ethereum JSON-RPC methods are built to handle transactions and are not suited to submitting or querying UserOperation objects. Without a common specification, wallets and apps would have to integrate differently for each bundler implementation, and it would also be difficult for multiple implementations to jointly operate a separate UserOperation mempool. This standard redefines the submission, gas estimation, and query functions that existed for transactions to fit UserOperations, so that all ERC-4337 implementations can be used interchangeably through the same API. It also defines a set of debug methods to aid development, testing, and debugging.

What to implement

In depth

The bundler's role

A bundler is a node that exposes this standard's API. It collects one or more UserOperations into a bundle and submits them to the network with a single call to the EntryPoint contract's handleOps. Instead of sending a transaction directly, a wallet passes the UserOperation to the bundler through this API, and the bundler performs the actual on-chain execution on its behalf.

Validation rules for eth_sendUserOperation

The client must validate the received UserOperation, and must return a userOpHash only if it passes simulation and is accepted into the pool. If it fails, it must return the failure reason instead of a userOpHash. All fields must be set as hexadecimal values, and empty bytes must be written as "0x". factory and factoryData must both be provided or both omitted, and the four fields paymaster, paymasterData, paymasterValidationGasLimit, and paymasterPostOpGasLimit must likewise all be provided or all omitted. The entryPoint address must be one of the addresses returned by a call to supportedEntryPoints.

Standard error codes

On failure, an error object containing code and message is returned. -32602 indicates an invalid UserOperation struct or field. -32500 indicates the EntryPoint's simulateValidation rejected it, and message must contain the AAxx error message from the FailedOp event. -32501 indicates the paymaster's validatePaymasterUserOp rejected it, and data must contain the paymaster value. -32502 indicates a violation of ERC-7562 opcode validation rules, -32503 indicates the validUntil and validAfter time range has been exceeded, -32504 indicates the paymaster has been throttled or banned under reputation rules, and -32505 indicates the paymaster's stake or unstake delay is too low. -32507 indicates wallet signature verification failure, and -32508 indicates the paymaster balance cannot cover all pending UserOperations.

Support for EIP-7702 delegated accounts

On a network where EIP-7702 is active, a UserOperation can include an eip7702Auth tuple. This tuple is only needed when changing the delegation address, and once it is stored on-chain, it does not need to be included again in subsequent UserOperations. When using a sender delegated via EIP-7702, the factory field must be set to the INITCODE_EIP7702_MARKER = 0x7702 flag, and in that case factoryData is passed directly to the sender contract rather than to a factory. This call happens separately before validateUserOp, so the sender is called twice during validation. If factoryData is left empty, the call is skipped. The purpose of this call is to give the sender contract an opportunity to initialize storage before it accepts the UserOperation via validateUserOp.

Gas estimation method

eth_estimateUserOperationGas takes a UserOperation without gas limits or gas prices and returns the required gas values. The signature field is ignored, so no user approval is needed, though a stub signature of the correct length may need to be provided. maxFeePerGas and maxPriorityFeePerGas default to 0, so no payment from the account or paymaster is required. It also optionally accepts the same State Override Set as eth_call. The return values are preVerificationGas, verificationGasLimit, and callGasLimit, and paymasterVerificationGasLimit is additionally returned only if a paymaster address is specified. The actual postOpGasLimit cannot be reliably estimated, so the paymaster must propose a value to the account and require that value during on-chain validation. An error may be returned if the account's internal call or the paymaster's postOp call reverts.

Query methods and receipts

eth_getUserOperationByHash looks up a UserOperation by userOpHash. If it has been included in a block, it returns the full object with entryPoint, blockNumber, blockHash, and transactionHash appended. If it is pending in the mempool, it may return null or an object with null block-related values, and if it is neither, it returns null. eth_getUserOperationReceipt includes userOpHash, entryPoint, sender, nonce, paymaster, along with actualGasCost (the amount actually paid by the account or paymaster), actualGasUsed (total gas including pre-verification, creation, validation, and execution), success (whether it completed without reverting), reason (the revert reason), and logs. logs does not include logs from other UserOperations in the same bundle, but the accompanying receipt's TransactionReceipt covers the entire bundle, not just this UserOperation.

The debug namespace and test suite

debug_bundler_* methods must only be provided in test mode, and the compatibility test suite requires them. clearState clears the mempool as well as reputation data for paymasters, accounts, and factories. dumpMempool dumps the current mempool, and sendBundleNow immediately forms a bundle and executes it as a handleOps transaction. Setting manual mode with setBundlingMode requires explicitly calling sendBundleNow to send a bundle. setReputation and dumpReputation set and query per-address reputation (opsSeen, opsIncluded, status), and addUserOps injects UserOperations directly into the mempool, skipping validation. The reason debug functions are explicitly required is to verify an implementation's spec compliance using the bundler specification test suite.

Compatibility and proposal status

Since this standard only defines a new JSON-RPC API, the source states there are no backward compatibility issues. However, this proposal is still in Draft status, so its contents may change going forward. When implementing or integrating, it is safest to check the latest source.

Things to watch out for

Original ERC · ← ERCs