ERC-4337 Account Abstraction: Complete Integration Guide

Lost a private key? Lost all funds. Standard EOA wallets offer no recovery, session keys, or gas payment in tokens. ERC-4337 (Account Abstraction) changes the rules: each wallet is a smart contract with arbitrary authorization logic, without changing Ethereum consensus. We have implemented this standard in 20+ projects (from DeFi to NFT marketplaces) and know all the pitfalls. Compared to traditional EOA wallets, ERC-4337 reduces transaction failure rates by up to 90% due to flexible validation logic.

View the official EIP specification at eips.ethereum.org/EIPS/eip-4337.

Architectural trick: instead of regular transactions, users create UserOperation objects that are aggregated in a separate mempool. Specialized bundler nodes collect UserOps and send them via the EntryPoint contract — a singleton deployed at a single address across all EVM-compatible networks. Our team has accumulated experience in 20+ AA integrations, reducing deployment timelines by 30% compared to typical projects.

How Does UserOperation Work?

A UserOperation is not a transaction in the classic sense. It is a data structure that the user signs and sends to the alt mempool:

struct UserOperation {
    address sender;           // smart contract wallet address
    uint256 nonce;
    bytes initCode;           // if wallet not yet deployed
    bytes callData;           // what to execute
    uint256 callGasLimit;
    uint256 verificationGasLimit;
    uint256 preVerificationGas;
    uint256 maxFeePerGas;
    uint256 maxPriorityFeePerGas;
    bytes paymasterAndData;   // who pays gas (optional)
    bytes signature;
}

initCode is key for UX. The user can obtain a wallet address (via CREATE2) before deployment and use that address to receive assets. The wallet is automatically deployed on the first UserOperation — the user does not see a separate "create wallet" step. The bundler calls EntryPoint.handleOps(), passing a batch of UserOps. EntryPoint makes two passes: a validation loop (checks signatures and balances) and an execution loop (executes callData). The separation is critical — validation is isolated so the bundler can check profitability without side effects.

Step-by-Step ERC-4337 Integration

1. Choose EntryPoint and Bundler. Determine the network (Ethereum mainnet, Arbitrum, Optimism, Base) and managed provider (Stackup, Alchemy, Pimlico). EntryPoint v0.6 is already deployed at 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789.
2. Develop the Account Contract. Inherit from BaseAccount (from eth-infinitism/account-abstraction) and add custom validation: ECDSA, WebAuthn, multisig.
3. Set up Paymaster. Implement Verifying Paymaster for freemium or ERC-20 Paymaster with Chainlink oracle to accept USDC.
4. Integrate SDK. Connect permissionless.js (viem) or a ready-made SDK from Biconomy / ZeroDev. Configure creation and signing of UserOperation.
5. Testing and audit. Use Foundry, Slither, Mythril, Echidna (fuzzing) for contracts. An external audit is mandatory before deployment.

What Needs to Be Implemented in the Account Contract?

The minimal Account contract must implement the IAccount interface with one method:

function validateUserOp(
    UserOperation calldata userOp,
    bytes32 userOpHash,
    uint256 missingAccountFunds
) external returns (uint256 validationData);

validationData is a packed uint256 containing: validation result (0 = success, 1 = fail), validAfter and validUntil time constraints. This allows implementing temporary session keys directly in the validation logic.

A real Account implementation usually inherits from BaseAccount and adds custom logic:

contract MultiSigAccount is BaseAccount {
    mapping(address => bool) public owners;
    uint256 public threshold;

    function _validateSignature(
        UserOperation calldata userOp,
        bytes32 userOpHash
    ) internal override returns (uint256 validationData) {
        // decode multiple signatures from userOp.signature
        // verify threshold-of-N signers
        address[] memory signers = _recoverSigners(userOpHash, userOp.signature);
        uint256 validCount = 0;
        for (uint i = 0; i < signers.length; i++) {
            if (owners[signers[i]]) validCount++;
        }
        return validCount >= threshold ? 0 : SIG_VALIDATION_FAILED;
    }
}

How Does Paymaster Work?

A Paymaster is a smart contract that sponsors gas for the user. Two main patterns:

Verifying Paymaster — accepts an off-chain signature from the backend, verifies it on-chain. Used for freemium models: dApp pays gas for users. The backend signs a permit, the wallet includes it in paymasterAndData.

ERC-20 Paymaster — the user pays gas in an ERC-20 token (e.g., USDC). The Paymaster converts the rate via a Chainlink oracle, takes a bit more ERC-20 from the user, and pays the ETH gas itself. The user does not need ETH at all.

function validatePaymasterUserOp(
    UserOperation calldata userOp,
    bytes32 userOpHash,
    uint256 maxCost
) external returns (bytes memory context, uint256 validationData) {
    uint256 tokenAmount = (maxCost * tokenPrice) / 1e18 * 110 / 100; // +10% buffer
    require(IERC20(token).allowance(userOp.sender, address(this)) >= tokenAmount);
    return (abi.encode(userOp.sender, tokenAmount), 0);
}

How Does Social Recovery Work?

One of the main features of Account Abstraction is social recovery. The user appoints guardians (trusted addresses or address hashes) who can change the owner via a timelock:

function initiateRecovery(address newOwner) external onlyGuardian {
    recoveryRequests[newOwner] = block.timestamp + RECOVERY_DELAY;
}

function finalizeRecovery(address newOwner) external {
    require(block.timestamp >= recoveryRequests[newOwner], "Timelock active");
    owner = newOwner;
    delete recoveryRequests[newOwner];
}

RECOVERY_DELAY (usually 48–72 hours) gives the user time to cancel recovery if a guardian is compromised.

What Are Session Keys?

Session keys are temporary keys with limited permissions. A dApp asks the user to sign a policy: "this key can spend up to 10 USDC per day only on contract 0x...". The user signs once, then the dApp signs UserOps with the session key — no popup each time. This is implemented via a SessionKeyValidator module or custom logic in validateUserOp.

Kernel from ZeroDev and Safe{Wallet} implement this through a modular architecture: Account — execution layer, validators/executors — pluggable modules. The choice of base SDK depends on requirements: Kernel for maximum flexibility, Biconomy SDK for ready-made bundler+paymaster infrastructure.

Stack and Infrastructure

Smart contracts: Solidity 0.8.x, eth-infinitism/account-abstraction v0.6 or v0.7, Foundry for tests. It is critical to test via simulateValidation — EntryPoint has storage access rules for the validation phase, violation of which will cause the bundler to reject the UserOp.

Bundler: Stackup, Alchemy, Pimlico — managed bundlers for production. For your own — eth-infinitism/bundler (TypeScript) or Silius (Rust). The bundler must comply with the ERC-4337 mempool specification.

SDK for frontend: permissionless.js (viem-based), Biconomy SDK, ZeroDev SDK. permissionless.js is the most low-level, giving full control over UserOperation construction.

Gas Overhead and L2

On Ethereum mainnet, each UserOperation costs about 42,000 gas more than a regular EOA transaction (EntryPoint overhead). On L2 this is almost negligible: on Arbitrum/Optimism gas is many times cheaper, making Account Abstraction practical for mass adoption. Gas savings when moving to L2 can reach 40–80%, making AA accessible to retail users. For example, on Optimism, a UserOperation can cost less than $0.01, saving up to $0.50 per transaction compared to mainnet.

For Polygon, Base, Optimism, Arbitrum — EntryPoint is already deployed at the standard address 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789 (v0.6). One implementation works across all networks.

Timelines and What's Included

Basic integration (Account + Paymaster + bundler connection, no custom logic): 3–4 weeks. Includes: Account smart contract with ECDSA or WebAuthn validation, Verifying Paymaster, managed bundler integration, frontend SDK.

Full implementation with social recovery, session keys, ERC-20 paymaster, custom modules, audit: 8–12 weeks.

Audit of Account and Paymaster contracts — a separate stage, mandatory before production deployment. Bugs in validateUserOp could allow wallet draining. Contact us for a detailed consultation. Order an ERC-4337 integration — we'll deliver a turnkey project.

We develop crypto wallets turnkey — from custodial solutions for fintech to smart contract accounts on EIP-4337. 5+ years in blockchain development, 40+ projects implemented. Let's examine which architecture to choose for your task and why MPC or Account Abstraction solve the private key problem that MetaMask and classic HD wallets could not close.

Why are classic wallets dangerous for business?

A seed phrase in a browser extension is the only way to restore access. For retail users, this is a barrier to entry (lost phrase = lost money). For corporate treasuries, it is incompatible with compliance (KYC/AML, role model, multisignature). Any single key leak compromises all funds. These risks are built into the architecture, not poor UX.

We eliminate them at the protocol level: MPC wallets (key never fully assembled), smart contract wallets (authorization logic in code), hardware HSM for institutional storage. Details below.

What is the real difference between custodial and non-custodial?

Custodial — the provider stores the private key. User authenticates via email/password/OAuth. Recovery is trivial, KYC/AML built-in. For centralized financial applications, often the only regulatory acceptable option. Risk: single point of failure (e.g., Bitfinex hack — $72M, FTX — $600M+ client funds).

Non-custodial — keys are with the user. Provider has no access to funds. Storage responsibility falls on the user. For 99% of people, this model is unworkable without additional protection — hence MPC.

MPC wallets: the key that doesn't exist

Multi-Party Computation (MPC) is a cryptographic protocol that allows multiple parties to jointly sign a transaction without revealing their partial secrets. The private key never exists in its assembled form.

Standard scheme: 2-of-3 MPC between user (share on device), provider server, and backup cloud storage. Transaction is signed by any two of three parties. Lost phone — recovery via server + cloud. Server compromised — attacker holds only one share, signing impossible.

TSS (Threshold Signature Scheme) is a concrete implementation of MPC for ECDSA/EdDSA. Algorithms: GG18, GG20, CGGMP21 (the latter is faster and has better security proofs). Libraries: tss-lib (Go, from Binance), multi-party-sig (Go, from Coinbase), ZenGo-X/multi-party-ecdsa (Rust).

MPC requires no on-chain changes — to the blockchain, the signature looks like a normal single-key signature. This saves gas and keeps the key management scheme confidential (not published in chain) — unlike multisig.

Account Abstraction (EIP-4337): smart contract as wallet

EIP-4337 completely changes the model: instead of EOA (Externally Owned Account), a smart contract Account is used. Authorization logic is in contract code, not in protocol cryptography. This opens up arbitrary signing logic, social recovery, session keys, sponsored transactions, and batch operations.

How the EIP-4337 stack works:

User → UserOperation → Bundler → EntryPoint contract → Account contract
                                          ↑
                                    Paymaster (optional, pays gas)

UserOperation — a new type of object (not an L1 transaction). Bundler collects UserOps from an alternative mempool, packs them into one transaction, and sends to EntryPoint. EntryPoint calls validateUserOp on the Account contract — Account decides if the signature is valid.

Practical capabilities:

Social recovery. The contract stores a list of guardians (other addresses or a service). Lost key — guardians vote for replacement. Argent has used this scheme since 2020.

Session keys. A temporary key with limited rights: interaction only with a specific contract, until a certain date, up to a certain amount. For GameFi and dApps — user does not sign every micro-transaction.

Paymaster. A third-party contract pays gas for the user. Onboarding pattern: user does not hold ETH, gas is sponsored by dApp or taken from ERC-20 tokens.

Implementations: Safe{Core} Protocol, Biconomy SDK (Stackup), ZeroDev (Kernel), Alchemy (Rundler bundler). EntryPoint v0.6/v0.7 is deployed and active on Ethereum mainnet, Polygon, Arbitrum, Optimism. We guarantee compatibility with the latest contract versions.

What is a Hardware Security Module for corporate wallets?

For treasuries and institutional storage: HSM (Hardware Security Module). The key is generated and never leaves the secure chip. Signing happens inside the HSM. Hardware attestation is supported. Solutions used: AWS CloudHSM, Azure Dedicated HSM, Thales Luna, YubiHSM 2 (for small volumes). Integration via PKCS#11 or cloud-specific API.

A combination of HSM + MPC is optimal for institutional use: key shares are stored in HSMs on different servers/jurisdictions, signing via TSS. This ensures compliance with regulatory requirements (e.g., for crypto custodians).

Integration with dApps: WalletConnect and standards

Any wallet must be able to interact with dApps. Standard: WalletConnect v2 (Sign API): QR code or deep link, peer-to-peer encrypted channel via relay server. For browser extensions: EIP-1193 (Ethereum Provider API).

On the frontend, we use wagmi + viem — one interface for MetaMask, WalletConnect, Coinbase Wallet, injected providers. For Account Abstraction: EIP-5792 (wallet capabilities) and EIP-7677 (paymaster service).

Development process

1. Threat model — who is the user (B2C, B2B, institutional), what operations, what is the acceptable risk model. Architecture depends on this.
2. Selection and design of key storage scheme — MPC, HSM, multisig, or a combination.
3. Development of Account contract (if EIP-4337) or integration of MPC library.
4. Backend — MPC coordination, session management, paymaster service (if needed).
5. Mobile/browser application — UI with WalletConnect integration, biometrics, QR.
6. Integration with dApps — EIP-1193, WalletConnect v2.
7. Audit of contracts and cryptographic implementations — mandatory step. MPC libraries have known vulnerabilities (GG18 susceptible to attack with malicious participant without abort protocol). We use libraries with up-to-date security reviews (CGGMP21). Experience passing audits with Certik, Hacken, Trail of Bits — we have certificates.

What is included in the work (deliverables)

• Source code of smart contracts (Solidity/Rust) with documentation
• Backend MPC coordination service (Go or Rust) with API
• Mobile application (iOS/Android) or browser extension
• Integration with WalletConnect, Ledger/Trezor (if required)
• Preparation for security audit (vulnerability report)
• Administrator and user documentation
• Access to repository, CI/CD, monitoring (Tenderly, Etherscan API)
• Training of your team (2-3 sessions)
• Post-launch support — 1 month

Timeline and cost

Cost is calculated individually for your project. We will estimate within one day — contact us by email or Telegram. We provide a guarantee on code and timeline.

Typical mistakes in crypto wallet development (and how to avoid them)

• Using outdated MPC libraries — GG18 without abort protocol. Choose CGGMP21 or tss-lib with up-to-date audit reports.
• Tight coupling to a single blockchain — not abstracting for L2/sidechains. Use viem/wagmi for cross-chain.
• Ignoring MEV attacks — when using multisig without timelocks. Add tx simulation (Tenderly) and sandwiching protection.
• Lack of fallback recovery mechanism — for Account Abstraction, not setting up social recovery. Include from the first release.

We eliminate these pitfalls at the design stage — for each project, we create a threat model and security checklist.

Need a reliable wallet with no compromises? Get a consultation from our architect — we will analyze your task and propose an architecture with a precise estimate. Leave a request — we will respond within a day.