智能合约钱包：架构、UserOperation 与可复现的测试工作流

智能合约钱包究竟是什么

智能合约钱包，通常称为智能账户，是一种链上账户，其控制逻辑以已部署的字节码实现。资金存放在合约地址，合约决定给定操作是否被授权：它可以检查一个签名、多个签名、一个通行密钥、一个带过期时间的会话密钥，或开发者编码的任意策略。这与外部拥有账户的核心区别在于，后者中私钥的持有是协议理解的唯一授权原语。

实际后果是钱包行为在账户层面变得可升级和可编程。多签批准阈值、社交恢复守护者、支出限额和批量调用都是合约逻辑而非协议特性。代价是这些特性中的每一个现在都成为攻击面：账户实现中的漏洞、配置错误的模块或不安全的升级路径，即使用户密钥从未暴露，也可能危及资金。

本文聚焦于使用 ERC-4337 的 EVM 智能账户，因为这是大多数工具和基础设施提供商所针对的模型。其他运行时上的账户抽象，例如 Starknet 上的原生账户合约，遵循相同的心智模型，但用运行时级别的账户语义取代了 bundler 和 EntryPoint 机制。

• 资金由合约代码持有，而非由密钥控制的地址持有。
• 授权是合约决策，因此可以是多方、有时限或策略驱动的。
• 可升级性和模块系统同时增加了能力和风险。

工作流的假设与前提条件

以下流程假设您拥有目标网络的 EVM 兼容 RPC 端点、想要检查的账户实现地址，以及对 JSON-RPC 的基本熟悉。运行只读验证步骤不需要有资金的密钥；只有在打算提交真实 UserOperation 时才需要。

全程使用 RPC_URL 等占位符端点，并替换为您自己的提供商 URL。如果您仍在选择基础设施，多链 RPC 端点指南涵盖了端点行为在不同网络间的差异，OnFinality 的 API 服务描述了托管访问。对于 bundler 和节点延迟至关重要的生产工作负载，在承诺使用共享端点之前，请查看专用节点选项。

ERC-4337 心智模型：UserOperation 与 EntryPoint

ERC-4337 通过引入一种称为 UserOperation 的高级交易对象，避免更改基础协议。用户或应用程序签署描述预期调用的 UserOperation，bundler 将一个或多个打包成发送到单例 EntryPoint 合约的普通交易。然后 EntryPoint 调用智能账户的验证函数，可选地调用 paymaster 支付 gas，最后执行请求的调用。

这种分层使得无需协议更改即可实现 gas 赞助和批量处理。这也意味着有三个不同的参与方，您必须推理其行为：验证的账户合约、同意支付的 paymaster，以及决定是否包含操作的 bundler。任何一层的失败都会表现为被拒绝或丢弃的 UserOperation，错误文本通常会告诉您哪一层拒绝了。

账户的 nonce 由 EntryPoint 而非网络管理，这是常见的混淆来源。来自同一账户的两个 UserOperation 可以因 EntryPoint nonce 不同而都有效，即使底层 EOA nonce 未变，且卡住的操作可能阻塞后续操作，直到被替换或失效。

• 账户合约：验证签名并执行调用。
• Paymaster：可选地赞助 gas，受其自身策略检查约束。
• Bundler：模拟、批量处理并提交到 EntryPoint。
• EntryPoint：协调验证和执行的单例。

使用 curl 检查智能账户

在信任任何钱包集成之前，确认您视为智能账户的地址确实有代码并暴露预期接口。以下只读调用适用于任何标准 EVM JSON-RPC 端点。将 RPC_URL 和 ACCOUNT_ADDRESS 替换为您自己的值。

第一个调用如果地址是合约则返回字节码，如果是 EOA 则返回 0x。第二个调用读取账户的 EntryPoint 引用，如果实现暴露了公共 getter；并非每个实现都如此，因此将空结果视为不确定，而非配置错误的证据。

curl -s RPC_URL \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getCode","params":["ACCOUNT_ADDRESS","latest"]}'

curl -s RPC_URL \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_call","params":[{"to":"ACCOUNT_ADDRESS","data":"0xENTRYPOINT_GETTER_SELECTOR"},"latest"]}'

使用脚本化检查验证部署

单次 curl 调用适用于抽查，但可重复的验证脚本更适合 CI 和跨端点比较行为。下面的 Python 示例检查地址是否有代码、读取其余额并确认链 ID，以便您知道实际在与哪个网络通信。它仅使用标准库和占位符端点。

针对您计划在生产中使用的每个端点运行此脚本。如果两个端点在链 ID 上不一致，或在同一区块对同一地址返回不同的字节码，请停止并调查，然后再部署任何依赖它们的东西。

import json, urllib.request

RPC_URL = "RPC_URL"
ACCOUNT = "ACCOUNT_ADDRESS"

def rpc(method, params):
    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode()
    req = urllib.request.Request(RPC_URL, data=body, headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=10) as resp:
        payload = json.loads(resp.read())
    if "error" in payload:
        raise RuntimeError(payload["error"])
    return payload["result"]

chain_id = int(rpc("eth_chainId", []), 16)
code = rpc("eth_getCode", [ACCOUNT, "latest"])
balance = int(rpc("eth_getBalance", [ACCOUNT, "latest"]), 16)

print("chain_id:", chain_id)
print("is_contract:", code not in ("0x", "0x0"))
print("code_bytes:", (len(code) - 2) // 2)
print("balance_wei:", balance)

预期验证结果及其解读

正确配置的智能账户应返回与您预期网络匹配的链 ID、非空字节码字符串以及与您记录一致的余额。记录代码字节长度和读取时的区块号，因为代理实现可能在升级后更改字节码，后续不匹配通常是账户被意外升级的第一个迹象。

当您在多个端点上运行相同检查时，将结果捕获到表格中，以便差异可见而非凭记忆。如下模板就足够了；填入您自己测量的值，而非依赖任何已发布的数字。

该表中的延迟应由您自己的客户端在多次请求中测量，而非从提供商的营销页面复制。表格的意义在于一致性：如果一个端点落后其他端点许多区块，UserOperation 模拟结果将因 bundler 使用的端点不同而不同。

在提交前模拟 UserOperation

大多数 bundler 暴露一个 RPC 方法来模拟 UserOperation，通常是 eth_estimateUserOperationGas 或供应商特定的等效方法。模拟在您花费任何费用之前捕获签名失败、paymaster 拒绝和 gas 不足情况。确切的请求形状取决于您的 bundler，因此查阅其文档以获取字段名称；下面的结构用占位符说明了模式。

将模拟视为部署管道中的必需关卡。模拟失败的 UserOperation 几乎肯定会在链上失败，且模拟的错误消息通常比链上回滚原因更具体。

curl -s BUNDLER_URL \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_estimateUserOperationGas",
    "params": [
      {
        "sender": "ACCOUNT_ADDRESS",
        "nonce": "0x0",
        "callData": "0xCALLDATA",
        "callGasLimit": "0x0",
        "verificationGasLimit": "0x0",
        "preVerificationGas": "0x0",
        "maxFeePerGas": "0x0",
        "maxPriorityFeePerGas": "0x0",
        "signature": "0xSIGNATURE"
      },
      "ENTRYPOINT_ADDRESS"
    ]
  }'

排查常见的智能账户故障

故障集中在少数原因上。签名验证错误通常意味着账户期望的签名方案与您的客户端使用的不同，或者 UserOperation 哈希是在与账户重建不同的字段上计算的。Paymaster 拒绝意味着赞助策略拒绝了操作，通常因为目标合约或选择器不在允许列表中，或者账户已超过速率限制。

当先前的 UserOperation 仍在 bundler 的内存池中待处理时，会出现 nonce 冲突。由于 EntryPoint 独立于网络跟踪 nonce，您必须向 EntryPoint 查询账户的当前 nonce，而不是读取 EOA 上的 eth_getTransactionCount。如果操作卡住，用使用相同 nonce 和更高费用的操作替换它，或等待其被丢弃。

Gas 估算失败通常由模拟和执行之间状态变化引起。模拟期间充足的 paymaster 余额可能在 bundle 落地时耗尽，模拟时存在的代币批准可能在包含前被撤销。构建重新模拟的重试，而非盲目重新提交。

• 签名错误：确认签名方案和确切的 UserOperation 哈希字段。
• Paymaster 错误：检查赞助策略、允许列表和 paymaster 存款。
• Nonce 错误：向 EntryPoint 而非 EOA 查询当前 nonce。
• Gas 错误：在提交前立即重新模拟并处理状态漂移。

智能合约钱包的局限性与权衡

智能账户增加了 EOA 没有的依赖层。您的用户依赖账户实现的正确性、EntryPoint 的持续可用性，以及 bundler 继续包含他们的操作。可升级账户引入了一个管理员密钥或治理流程，可以在资金存入后更改规则，这是一个有意义的信任假设，即使升级路径有时间锁。

Gas 成本也不同。验证比普通签名检查更昂贵，paymaster 赞助将成本转移给资助 paymaster 的人，而非消除成本。批量处理可以减少每次调用的开销，但节省取决于您实际批量处理多少调用以及每个调用的 calldata 大小。

最后，可移植性不是自动的。为一个链签名的 UserOperation 在另一个链上无效，除非账户和 EntryPoint 部署在那里且签名方案考虑了链 ID。跨链重放保护是账户实现的属性，而非 ERC-4337 本身的属性。

构建和运营智能账户的后续步骤

首先固定您打算支持的账户实现和 EntryPoint 地址，然后针对堆栈中的每个端点运行验证脚本并记录结果。从那里开始，将模拟添加到提交路径，对 bundler 响应进行插桩，以便故障可归因于特定层，并将 paymaster 余额和存款水平作为一等运营指标进行监控。

如果您正在为 bundler 和节点层选择基础设施，RPC 端点指南解释了应评估什么，RPC 定价帮助您根据预期 UserOperation 量建模成本。对于网络特定的部署细节，在假设给定链支持您选择的账户实现之前，浏览支持的网络列表。具体的端点和提供商建议由 RPC Assistant 单独处理，因此本文用于方法论，该资源用于具体选择。