EIP-4337ERC账户抽象Final（2023-03-01）

账户抽象（Account Abstraction）

不改协议层就实现智能合约钱包：用 UserOperation 替代交易，由 Bundler 代发，Paymaster 可代付 Gas。

适用链：以太坊主网 + Arbitrum / Optimism / Base / Polygon 等（需有 EntryPoint 与 Bundler）

为什么重要：它解决了 EOA 的三个硬伤：私钥丢失即资产全丢、必须持有原生币才能操作、多步操作要多次签名。社交恢复、无 Gas 交易、批量执行、会话密钥（session key）都建立在它之上。

函数签名与选择器

选择器是签名的 keccak256 前 4 字节；事件则是完整的 32 字节 topic0。点一下即可复制。

签名 / 字段	选择器 / topic0	说明
EntryPoint.handleOps(UserOperation[],address)		Bundler 调用的总入口，按顺序执行一批 userOp。
EntryPoint.getUserOpHash(UserOperation,bytes32)		计算 userOp 哈希，签名必须签这个值（而不是 userOp 本身的编码）。
IAccount.validateUserOp(UserOperation,bytes32,uint256)		账户自己验证签名与 Gas 预付款，返回 0 表示验证通过。
EntryPoint.simulateValidation(UserOperation)	—	调试接口：本地模拟验证阶段，定位 AA 系列错误码。
UserOperation.sender	—	发起操作的智能账户地址。
UserOperation.nonce	—	非简单递增：高 192 位是 key（可用多个并行 nonce 通道），低 64 位是序号。
UserOperation.callData	—	账户要执行的实际调用，通常是 execute(dest, value, func) 的编码。
UserOperation.paymasterAndData	—	v0.6：paymaster 地址 + 额外数据。v0.7 拆分成了四个独立字段。
UserOperation.signature	—	账户自定义的签名数据，EntryPoint 不解析，直接透传给 validateUserOp。

代码模板

最小智能账户（validateUserOp + execute）

最小智能账户（validateUserOp + execute）Solidity

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

struct UserOperation {
    address sender;
    uint256 nonce;
    bytes initCode;              // v0.7 拆分为 factory + factoryData
    bytes callData;
    uint256 callGasLimit;
    uint256 verificationGasLimit;
    uint256 preVerificationGas;
    uint256 maxFeePerGas;
    uint256 maxPriorityFeePerGas;
    bytes paymasterAndData;      // v0.7 拆分为 paymaster + 两个 gasLimit + paymasterData
    bytes signature;
}

interface IEntryPoint {
    function getUserOpHash(UserOperation calldata userOp) external view returns (bytes32);
    function depositTo(address account) external payable;
}

/**
 * 最小可用的 ERC-4337 账户：
 * 私钥不再直接控制资产，而是控制「谁来签名 UserOperation」。
 */
contract MinimalAccount {
    IEntryPoint public immutable entryPoint;
    address public owner;

    error NotEntryPoint();
    error NotOwner();
    error CallFailed(bytes reason);

    event Executed(address indexed target, uint256 value, bytes data);

    constructor(IEntryPoint _entryPoint, address _owner) {
        entryPoint = _entryPoint;
        owner = _owner;
    }

    receive() external payable {}

    /// EntryPoint 在验证阶段调用：校验签名 + 预付 Gas
    function validateUserOp(
        UserOperation calldata userOp,
        bytes32 userOpHash,
        uint256 missingAccountFunds
    ) external returns (uint256 validationData) {
        if (msg.sender != address(entryPoint)) revert NotEntryPoint();

        // 用 userOpHash 验签，绝不能用 userOp 的编码结果
        if (_recover(userOpHash, userOp.signature) != owner) {
            return 1;   // SIG_VALIDATION_FAILED，EntryPoint 会拒绝这笔操作
        }

        // 账户余额不足时先补给 EntryPoint（实际项目通常由 Paymaster 承担）
        if (missingAccountFunds > 0) {
            (bool ok, ) = msg.sender.call{value: missingAccountFunds}("");
            ok;   // 补款失败不阻断验证，由 EntryPoint 统一判定
        }

        return 0;
    }

    /// 真正的业务入口：账户自己调用目标合约，msg.sender 是本账户
    function execute(address target, uint256 value, bytes calldata data) external {
        if (msg.sender != address(entryPoint) && msg.sender != address(this)) revert NotOwner();

        (bool ok, bytes memory ret) = target.call{value: value}(data);
        if (!ok) revert CallFailed(ret);

        emit Executed(target, value, data);
    }

    function addDeposit() external payable {
        entryPoint.depositTo{value: msg.value}(address(this));
    }

    function _recover(bytes32 hash, bytes memory signature) internal pure returns (address) {
        if (signature.length != 65) return address(0);

        bytes32 r;
        bytes32 s;
        uint8 v;
        assembly {
            r := mload(add(signature, 32))
            s := mload(add(signature, 64))
            v := byte(0, mload(add(signature, 96)))
        }

        // EIP-2：拒绝高位 s，防止签名可延展性攻击
        if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) {
            return address(0);
        }

        return ecrecover(hash, v, r, s);
    }
}

真实项目用 OpenZeppelin 的 Account + ECDSA 库（或 SimpleAccount 参考实现），它们处理了 EIP-191 前缀、可延展性与批量执行。

客户端：构造并发送 UserOperation

客户端：构造并发送 UserOperationTypeScript

import { createPublicClient, http, encodeFunctionData, parseAbi } from 'viem';
import { sepolia } from 'viem/chains';

// 任何兼容 ERC-4337 的 Bundler 都会暴露这一组 RPC 方法
const BUNDLER = 'https://public.stackup.sh/api/v1/node/ethereum-sepolia';

const account = '0xYourSmartAccount...';
const entryPoint = '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789';   // v0.6

const callData = encodeFunctionData({
  abi: parseAbi(['function execute(address target, uint256 value, bytes data)']),
  functionName: 'execute',
  args: [TARGET, 0n, innerCallData],
});

const userOp = {
  sender: account,
  nonce: await bundlerRequest('eth_getUserOperationCount', [account, entryPoint]),
  initCode: '0x',                                  // 账户已部署则留空
  callData,
  callGasLimit: '0x100000',
  verificationGasLimit: '0x100000',
  preVerificationGas: '0x10000',
  maxFeePerGas: '0x3b9aca00',
  maxPriorityFeePerGas: '0x3b9aca00',
  paymasterAndData: '0x',
  signature: '0x',                                 // 下面算出 userOpHash 后再填
};

// 签名对象是 userOpHash，不是 userOp 本身
const userOpHash: string = await bundlerRequest('eth_getUserOperationHashForUserOperation', [
  userOp,
  entryPoint,
  CHAIN_ID,
]);

const signature = await wallet.signMessage({ account, message: { raw: userOpHash as `0x${string}` } });
userOp.signature = signature;

const opHash: string = await bundlerRequest('eth_sendUserOperation', [userOp, entryPoint]);

// 轮询直到打包，receipt 里能找到这笔 userOp 落在哪个交易里
const receipt = await poll('eth_getUserOperationReceipt', [opHash]);
console.log('included in tx:', receipt.receipt.transactionHash);

async function bundlerRequest(method: string, params: unknown[]) {
  const res = await fetch(BUNDLER, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
  });
  const json = await res.json();
  if (json.error) throw new Error(json.error.message);
  return json.result;
}

常见 AA 错误码（都出现在 error.message 前缀里）：AA21 预付款不足、AA22 费率过低、AA23 验证超限、AA25 nonce 无效。

实现与使用时的常见陷阱

✕必须签 userOpHash，不能签 userOp 的编码结果——后者在不同链/不同 EntryPoint 上不可区分，会被重放。
✕v0.6 与 v0.7 的 UserOperation 结构不兼容（paymasterAndData 与 initCode 被拆成多个字段），接入前先确认 Bundler 与 EntryPoint 版本。
✕validateUserOp 里能调的存储范围受 ERC-7562 验证规则限制，不能读任意外部合约状态，否则 Bundler 会拒绝该操作。
✕Paymaster 有余额与抵押（stake）要求，欠费后所有依赖它的账户会集体无法发交易。
✕UserOp 的 nonce 是 256 位：高 192 位是 key，可以用不同 key 并行发多笔而不互相阻塞。

账户抽象（Account Abstraction）

函数签名与选择器

代码模板

实现与使用时的常见陷阱

相关标准