EIP-4337 UserOperation lifecycle: from client to on-chain execution

EIP-4337 UserOperation lifecycle: client build, bundler mempool, EntryPoint validation and execution. Failure modes and gas fields. Practical notes for IBEx.

5 min read

Who this is for

  • Wallet and dapp engineers
  • Bundler operators
  • Protocol teams shipping smart accounts

Pros / cons

ProsCons
  • Clear separation between user intent and bundler execution
  • Composable paymaster and aggregator fields
  • Batchable validation through handleOps
  • More moving parts than legacy EOAs
  • Simulation must mirror consensus rules
  • Explorer UX can confuse users expecting a single tx hash

Key takeaways

  • Treat each lifecycle stage as an observable event
  • Harden client-side assembly against malformed fields
  • Correlate bundler logs with chain receipts

What a UserOperation is (and what it is not)

Under EIP-4337, a UserOperation is an off-chain message that expresses what a smart contract account wants to do, together with the gas budget and authorization material required for a canonical EntryPoint contract to validate and execute that intent safely. It is not a consensus-layer transaction type in the classic sense; validators see a normal contract call from a bundler into EntryPoint.handleOps, while users and applications reason about UserOperations as the primary user-facing unit of work. Structurally, the format includes the sender address of the smart account, a nonce sequence used to prevent replay, verification gas and call gas limits, the calldata that should be forwarded to the account during execution, and fields that describe how fees should be paid, including optional paymaster contracts that may sponsor gas or pull fees in ERC-20 tokens when supported by the implementation. Signature aggregation hooks allow compatible accounts to use schemes that amortize verification costs across multiple senders when an aggregator contract is trusted by the account implementation. Because the object is richer than a legacy transaction, clients must be disciplined about serialization, field bounds, and defaults; subtle mistakes in gas limits or fee fields produce rejections at the bundler or on-chain validation phases rather than the clearer errors users associate with insufficient native balance on EOAs. Product teams should document that the hash users sometimes see on explorers may correspond to the bundler transaction containing many UserOperations, not a one-to-one mapping with a single user intent. Infrastructure teams should version their UserOperation schemas per chain because opcode pricing, precompile availability, and block limits evolve with hard forks. IBEx Network operators benefit from treating the UserOperation as the contract between wallet UX and backend services: if analytics cannot reconstruct the struct that entered the mempool, debugging production incidents becomes guesswork. Formalizing naming for each field in internal APIs reduces cross-team friction when paymasters, session keys, and modular accounts stack additional metadata alongside the base specification.

Client construction, signing, and submission

Construction begins when the wallet determines the target calls the smart account should perform, including batching patterns that many implementations expose as multicall-style interfaces or module routers. The client chooses a nonce key and sequence consistent with the account contract, which may implement conventional sequential nonces or more advanced keyed nonces to enable parallelizable flows when the account explicitly supports them. Gas estimation is not a single RPC call in the legacy sense; practical integrations combine eth_estimateUserOperationGas or bundler-specific methods with local heuristics and safety margins because validation hooks can touch storage, verify signatures, and consult external contracts within strict opcode budgets imposed by the protocol rules. Signing binds the UserOperation hash defined by the specification to whatever scheme the account uses, which may be ECDSA over secp256k1, passkey-backed signatures, multisig thresholds, or module-specific validators. After signing, the wallet submits the UserOperation to a bundler using standardized JSON-RPC surfaces; the bundler responds with a user operation hash that clients can poll for inclusion status. Robust clients implement exponential backoff, switch bundlers when policy allows, and surface structured errors such as validation reverts, paymaster failures, or insufficient prefund conditions rather than collapsing everything into generic failures. Security reviews should examine how untrusted dapps influence calldata and value fields, especially when session keys or scoped permissions exist, because a malicious site might try to smuggle dangerous calls through an otherwise legitimate account. Telemetry should capture construction time, signing latency, submission status codes, and time-to-inclusion distributions so operators can detect degradations after network upgrades or gas spikes. For IBEx customers, aligning this stage with policy engines and allowlists ensures sponsored transactions remain within commercial and risk constraints without surprising end users at submission time.

Bundler mempool, simulation, and bundle formation

Bundlers implement a specialized mempool that enforces EIP-4337 validation rules before accepting UserOperations, because invalid operations waste on-chain gas and harm reputation with block builders. Simulation typically executes validation logic against a pinned view of state, checking that the account and paymaster contracts do not violate banned opcode patterns during validation, that storage access rules are respected, and that fee payment pathways will succeed if the operation is included under plausible base fee movement. Unlike the public Ethereum transaction pool, UserOperation propagation is often mediated by explicit RPC endpoints and private relay networks, which changes censorship and latency characteristics teams must measure rather than assume parity with legacy mempools. Bundle formation is an optimization problem: bundlers choose subsets of pending UserOperations that fit within block gas limits, respect per-operation gas bounds, and maximize expected revenue from priority fees while accounting for execution risk if later operations in the bundle depend on earlier side effects. Advanced bundlers implement replacement rules, minimum fee bumps, and eviction policies when operations linger too long or when deadlines elapse. Operators should monitor dropped operations, time spent queued, and simulation failure taxonomies because those metrics reveal upstream wallet bugs, misconfigured paymasters, or chain-specific validation regressions after hard forks. When multiple bundlers serve the same application, consistent error code mapping across vendors prevents client fragmentation and improves support workflows. IBEx Network guidance emphasizes redundancy: if a single bundler stalls, applications with failover maintain availability, but failover must preserve nonce ordering assumptions to avoid accidental replacements or double-spend style confusion at the account layer.

On-chain validation, execution, receipts, and operations

When a bundle lands, EntryPoint orchestrates per-operation validation and execution with isolation semantics that allow unrelated UserOperations in the same transaction to proceed even if one fails, subject to the exact implementation details and gas accounting rules of the deployed EntryPoint version in use on a chain. Validation invokes the account contract hooks that prove authorization and prepare any paymaster context; execution then forwards the user-specified calldata to the account implementation, which may perform arbitrary business logic within the gas limit purchased by the user or sponsor. Receipts visible to end users require careful interpretation: the transaction logs and traces belong to the bundler outer call, while the user operation hash and internal events may need bespoke indexing to present human-readable status in dashboards. Debugging production issues often requires replaying validation with the same state root, comparing traces against bundler simulation outputs, and verifying that opcode restriction tables match the node version used by the bundler. Hard forks can change intrinsic costs and precompile behavior, so regression tests pinned to historical blocks help detect drift before users encounter mass rejections. Post-execution analytics should connect on-chain results to off-chain intents, including paymaster budget consumption and module invocations inside modular accounts. IBEx teams recommend runbooks that distinguish validation failures from execution failures, because remediation differs: the former often points to signing, nonce, or policy mistakes, while the latter may indicate target contract bugs or insufficient gas for complex internal calls. Long term, treating lifecycle metrics as first-class SLIs aligns infrastructure investment with user-perceived reliability rather than vanity inclusion rates alone.

Frequently asked questions

Why do users sometimes not see a familiar transaction hash immediately?

UserOperations are included inside a bundler transaction to EntryPoint. The user-visible user operation hash is not identical to the outer transaction hash, so explorers must support AA-aware indexing to show clean status.

Where do most production failures happen in the lifecycle?

Many incidents trace to validation: incorrect nonce keys, paymaster revert during validation, opcode restrictions, or simulation mismatches with on-chain nodes after upgrades.

How should teams estimate gas for complex smart accounts?

Combine bundler estimation RPCs with margins, replay tests on forked state, and continuous monitoring of revert reasons. Modular accounts should be tested with worst-case module combinations.