ERC-4337 Lifecycle and Client Rules

This page defines the MegaFuel Bundler behavior that a wallet needs for safe polling, retries, nonce handling, and replacement.

Lifecycle

Status	Meaning	Client action
`queued`	The Bundler accepted the operation and is waiting to submit it.	Continue bounded polling. Do not send another unrelated operation at the same nonce.
`inflight`	At least one outer `handleOps` transaction has been submitted and is being watched.	Continue bounded polling. The latest outer transaction may be visible from `eth_getUserOperationByHash`.
`included`	EntryPoint emitted the UserOperation event.	Read `eth_getUserOperationReceipt`; this is terminal.
`rejected`	The Bundler determined that the accepted operation is no longer valid.	Terminal. Read `failureReason`, rebuild from current inputs, request new paymaster data, and re-sign.
`expired`	The paymaster authorization or bounded UserOperation age elapsed.	Terminal. Request fresh paymaster data and re-sign.
`dropped`	The Bundler released the operation’s local nonce reservation, for example after displacement or stale chain state.	Terminal for this hash. Re-query nonce and build a new operation.

eth_getUserOperationReceipt is intentionally an inclusion receipt: it returns null before included, including for an unknown or terminal operation without an inclusion receipt. Do not interpret null by itself as “still pending.” Use nr_getUserOperationStatus.

`nr_getUserOperationStatus`

This NodeReal extension returns a durable local lifecycle record, or null only when the Bundler has never admitted the hash.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nr_getUserOperationStatus",
  "params": ["0x<USER_OP_HASH>"]
}

Example terminal response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "userOpHash": "0x...",
    "entryPoint": "0x...",
    "status": "expired",
    "failureReason": "paymaster validUntil elapsed"
  }
}

For included, the response also includes the persisted UserOperation receipt and outer transactionHash.

Polling and timeout

Poll the receipt and status together with exponential backoff (for example 2, 3, 5, 8, then up to 15 seconds). Stop normal polling as soon as status is terminal.

If status remains queued or inflight beyond your product’s user-facing timeout, keep the userOpHash and show a pending/recoverable state rather than declaring failure. A recommended wallet experience is to show pending after 120 seconds and continue background polling to a terminal state. Do not resubmit a changed operation with the same nonce until you have applied the replacement rule below.

Same nonce, idempotency, and replacement

Sending byte-for-byte identical signed content is idempotent: the Bundler returns the existing userOpHash and does not create a second lifecycle record.
A different operation at the same (EntryPoint, sender, nonceKey, sequence) is accepted as a replacement only while the old operation is queued.
A replacement must increase both maxFeePerGas and maxPriorityFeePerGas by at least 10%. A higher fee cap alone is insufficient.
inflight operations keep their nonce reservation. Wait for a terminal state or use a fresh nonce lane; do not assume a private-builder attempt is visible in the chain node’s pending transaction count.
rejected, expired, and dropped operations are terminal. A new signed operation may reuse the now-released nonce when the EntryPoint’s confirmed nonce permits it.

Gas and estimation contract

The wallet owns maxFeePerGas, maxPriorityFeePerGas, and UserOperation gas limits. MegaFuel enforces configured service-side safety ceilings before sponsorship. Treat a cap rejection as final for that payload; lower the declared values or obtain a fresh estimate.

eth_estimateUserOperationGas is a Bundler estimate, not a guarantee that every account ABI or application branch has been fully simulated. For supported SimpleAccount execute calls, it estimates the target call and applies a safety buffer. For unsupported/unknown call encodings, the Bundler uses conservative fallback values; policy sponsorship still fails closed if the policy decoder cannot identify the inner action.

Use the returned account and paymaster gas limits unchanged in the final paymaster-data request. The paymaster authorization binds the relevant operation fields; changing any bound gas, fee, nonce, factory, or call field requires fresh paymaster data and a new account signature.

For the current numeric caps, authorization validity, batch behavior, and the
absence of a public inclusion SLA, see ERC-4337 operating limits and policy
funding.