ERC-4337

ERC-4337 enables Instance Vault Contracts to execute operations without requiring direct wallet signatures. Your backend creates UserOperations off-chain, a bundler submits them to the EntryPoint, and the IVC validates permissions before execution. Users never pay gas—the paymaster sponsors all transactions.

​

How It Works

Account Abstraction separates transaction validation from execution. Traditional transactions require the sender to hold ETH and sign with their private key. ERC-4337 moves this logic into smart contracts where validation rules become programmable and gas payment moves to a separate paymaster contract. Instance Vault Contracts implement the BaseAccount interface from the ERC-4337 specification. This gives them the ability to validate UserOperations through custom logic checking backend signatures, session expiry, function allowlists, and rate limits all on-chain before execution.

​

UserOperation Structure

A UserOperation contains everything needed for the EntryPoint to validate and execute your request. Your backend generates these fields, signs the UserOperation hash with the authorized backend key, and submits to a bundler service or directly to the EntryPoint.

​

Validation Flow

The EntryPoint calls the IVC’s validation function before execution. The IVC performs multiple checks in sequence.

1. First, verify the contract isn’t paused and the session hasn’t expired. Both conditions result in immediate validation failure with no execution.
2. Second, recover the signer address from the signature and confirm it matches the authorized backend signer. Invalid signatures fail validation instantly.
3. Third, decode the calldata to extract the target contract and function selector. Verify the target matches the configured commodity token address and the function selector is enabled in the IVC’s configuration.
4. Fourth, check rate limits by comparing the current day against the last reset day and verifying remaining calls haven’t exceeded the daily limit. Increment the call counter if validation succeeds.
5. Return zero for successful validation or a failure code for any check that fails. The EntryPoint only executes operations that pass all validation checks.

​

Execution Phase

6. After successful validation, the EntryPoint calls the execute function on the IVC with the decoded target, value, and calldata. The IVC performs final safety checks including target verification, function enablement confirmation, and reentrancy protection before forwarding the call to the target contract.
7. The target contract executes the function and returns success or failure. The IVC increments its execution nonce, emits an event with the execution details, and returns the result to the EntryPoint. Failed executions revert the entire UserOperation including validation state changes.

​

Gas Sponsorship

The InstanceVaultPaymaster handles all gas payments for IVC operations. Before validation, the EntryPoint queries the paymaster to confirm it will sponsor the transaction. The paymaster checks the vault has sufficient balance, hasn’t exceeded daily spending limits, and the contract isn’t paused. If approved, the paymaster reserves the maximum gas cost from the vault’s balance and returns validation success to the EntryPoint. After execution completes, the EntryPoint calls the paymaster’s postOp function with the actual gas used. The paymaster refunds the difference between reserved and actual cost back to the vault balance. This two-phase approach ensures gas is paid even if execution fails while preventing overpayment for successful operations. Vaults maintain separate balances in the paymaster with independent daily spending limits.

​

Bundler Integration

Bundlers are services that collect UserOperations from multiple sources, validate them off-chain, and submit batches to the EntryPoint. Using a bundler reduces gas costs through batch submission and provides infrastructure for UserOperation propagation. Your backend submits UserOperations to a bundler’s RPC endpoint. The bundler validates the operation locally, adds it to a pending pool, and includes it in the next bundle submitted to the EntryPoint. Popular bundler implementations include Stackup, Alchemy, and Pimlico. Alternatively, submit UserOperations directly to the EntryPoint if you prefer to manage your own bundle submission and MEV protection. Direct submission gives more control but requires running bundler infrastructure.

​

Session Management

Sessions define how long a backend signer remains authorized. Set session duration during initial authorization—typically 30 to 90 days for production operations. The IVC checks block.timestamp against session expiry during every validation. Expired sessions fail all validations automatically. Renew sessions before expiry by calling renewSession from the owner account. This extends the session by the specified duration without changing the authorized backend signer. Revoke backend access instantly through revokeBackend for emergency response. This sets the backend signer to zero address and session expiry to zero, failing all future UserOperation validations until a new backend is authorized.

​

Nonce Management

The EntryPoint maintains a nonce system preventing replay attacks. Each IVC has a sequential nonce incremented after successful execution. UserOperations must specify the current nonce or validation fails. The IVC also maintains an internal executionNonce for tracking total operations executed. This nonce increments on every successful execute or executeBatch call regardless of EntryPoint nonce. Use executionNonce for monitoring and analytics while relying on EntryPoint nonce for security.

​

Error Handling

Validation failures return specific codes indicating the reason. The EntryPoint interprets these codes and reverts the UserOperation without execution. Execution failures revert with custom errors including InvalidTarget for wrong contract address, FunctionNotEnabled for disabled selectors, and ExecutionFailed for target contract reverts. Monitor these errors in your backend to handle failures appropriately.

​

Security Considerations

UserOperations are signed by the backend signer, not the owner. Protect backend private keys with HSMs or secure key management services. Compromise of the backend key allows unauthorized operations within configured function limits. Rate limits provide defense against compromised backend keys. Even with a valid signature, attackers cannot exceed daily call limits configured per function. Set conservative limits for high-risk operations like minting or force transfers. Session expiry forces periodic re-authorization. Stolen backend keys become useless after session expiry. Short sessions increase security but require more frequent renewal. Balance security needs against operational convenience when setting session duration. The owner retains ultimate control through direct execution bypassing all ERC-4337 validation. Owner keys should remain offline in cold storage used only for configuration changes and emergency response.