EIP-5792 Wallet Call API 实战指南：EIPs 仓库中的钱包批处理调用与能力协商标准

EIP-5792 Wallet Call API 实战指南EIPs 仓库中的钱包批处理调用与能力协商标准【免费下载链接】EIPsThe Ethereum Improvement Proposal repository项目地址: https://gitcode.com/GitHub_Trending/ei/EIPs本文以 Ethereum Improvement Proposal 仓库中的 eip-5792.md 为骨架系统讲解wallet_命名空间的四个 JSON-RPC 方法wallet_sendCalls、wallet_getCallsStatus、wallet_showCallsStatus、wallet_getCapabilities覆盖批量 onchain 调用提交、状态查询、原子性保证协商与钱包能力发现。读完本文你将掌握 EIP-5792 的完整参数语义、TypeScript 类型契约、状态码/错误码体系并了解它在智能账户如 ERC-4337与 EOA 钱包两种实现下的行为差异可直接据此实现或对接兼容的钱包与 DApp。一、为什么需要一套新的wallet_RPC在 EIP-5792 之前应用向用户钱包发送交易并查询状态的方式只有eth_sendTransaction与eth_getTransactionReceipt。这套旧方法存在两个根本性缺陷无法批量开发者希望把多个调用合并到一次 RPC 请求中提交由智能账户Smart Account在同一笔交易内原子执行而eth_sendTransaction一次只能发送一笔交易。无法表达新交易格式诸如 ERC-4337 交易中的 paymaster 等能力无从表达eth_sendTransaction的名称本身也是节点充当钱包时代的产物。EIP-5792Status: FinalStandards Track / Interfacerequires: EIP-1193因此新增四个wallet_命名空间的 JSON-RPC 方法三个用于处理链上调用批次一个用于查询钱包能力。设计目标是强制分离钱包与应用职责、让开发者能使用 paymaster 与批量交易、为后续可安全发现的新特性预留清晰的扩展通道。应用可以立即使用这三个批处理方法并在钱包不支持时回退到eth_sendTransaction/eth_getTransactionReceipt。二、wallet_sendCalls提交一批链上调用wallet_sendCalls请求钱包提交一批调用。from与chainId使用 EIP-155 整数并以十六进制表示带0x前缀chainId不允许前导零。calls数组中的元素是简单的{to, data, value}三元组。2.1 能力capabilities与atomicRequiredcapabilities字段是应用与钱包就钱包已支持能力进行通信的通道。例如应用可以在此指定 paymaster 服务 URL供 ERC-4337 钱包向该服务请求 User Operation 所需的paymasterAndData输入。每个在capabilities成员中定义的能力可定义全局字段或调用级字段全局字段设置在该能力于capabilities对象中的条目内calls数组中的每个实体还可携带可选的capabilities对象把能力专属的元数据附加到单个调用上。atomicRequired字段指定钱包是否必须以原子方式处理整批调用。钱包原子执行批量调用的能力通过内建的atomic能力暴露并可通过wallet_getCapabilities查询。应用可将某个能力标记为可选设置optional: true。若能力不可选而钱包不支持钱包必须拒绝请求错误码5700。2.2 钱包必须遵循的规则除非被某能力显式覆盖能力本身不在本 EIP 范围内应由独立 ERC 定义必须按请求中的顺序发送调用必须在请求chainId标识的同一链上发送调用必须在请求from指定的地址上发送调用若未提供from钱包应在确认时给用户查看和选择from地址的机会不得等待任何调用最终确认后才完成批次若用户拒绝请求不得发送该请求中的任何调用当atomicRequired为true时必须原子执行所有调用——要么全部成功要么链上无任何实质影响必须连续执行所有调用——批次内的调用之间不得插入其他交易/调用若钱包能够把原子性保证从ready升级到supported但尚未升级则必须在提交调用前完成升级再按上述保证提交。当atomicRequired为false时可以顺序执行全部调用不提供原子性/连续性保证若钱包能提供原子性保证也可以原子方式执行批次若钱包能升级原子性保证到supported也可以升级后再原子执行。若from地址与当前启用账户不匹配可以拒绝请求若按顺序模拟时批次中有一个或多个调用预期失败可以拒绝请求若请求包含钱包不支持的capability顶层或调用级且该能力未被显式标记为可选必须拒绝请求。2.3id标识符规则若提供了id字段钱包必须尊重它并在响应中原样返回标识符无论由应用提供还是钱包生成必须是唯一字符串最长 4096 字节含前导0x时为 8194 字符应用提供的id在同一应用应以域名标识内、对同一发送方必须唯一钱包必须拒绝重复id的请求错误码5720在对应的wallet_sendCalls之后 24 小时内当以相同id调用wallet_getCallsStatus时钱包应能返回批次状态。2.4 RPC 规范TypeScripttype Capability { [key: string]: unknown; optional?: boolean; } type SendCallsParams { version: string; id?: string; from?: 0x${string}; chainId: 0x${string}; // Hex chain id atomicRequired: boolean; calls: { to?: 0x${string}; data?: 0x${string}; value?: 0x${string}; // Hex value capabilities?: Recordstring, Capability; }[]; capabilities?: Recordstring, Capability; }; type SendCallsResult { id: string; capabilities?: Recordstring, any; };2.5 请求示例[ { version: 2.0.0, from: 0xd46e8dd67c5d32be8058bb8eb970870f07244567, chainId: 0x01, atomicRequired: true, calls: [ { to: 0xd46e8dd67c5d32be8058bb8eb970870f07244567, value: 0x9184e72a, data: 0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675 }, { to: 0xd46e8dd67c5d32be8058bb8eb970870f07244567, value: 0x182183, data: 0xfbadbaf01 } ], capabilities: { paymasterService: { url: https://..., optional: true } } } ]注意由于paymasterService能力被标记为optional: true不支持它的钱包仍会照常处理请求如同该能力不存在若该optional字段为false或缺失不支持该能力的钱包必须拒绝请求。2.6 返回值示例{ id: 0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331, }capabilities响应对象允许钱包在响应中附带能力专属的元数据。三、wallet_getCallsStatus查询批次状态wallet_getCallsStatus返回通过wallet_sendCalls提交的调用批次的状态批次标识符即wallet_sendCalls返回的id值。响应中receipts对象的元素是eth_getTransactionReceipt返回对象的严格子集。capabilities对象允许钱包在响应中附带能力专属元数据。3.1atomic字段与receipts结构约束atomic字段说明钱包如何处理该批次调用直接影响receipts字段的结构receipts中的收据必须按链上打包顺序排列若钱包原子执行多个调用wallet_getCallsStatus可以返回包含单个交易收据或收据数组的receipts字段取决于批次在链上如何被打包且必须显式返回atomic: true若钱包非原子执行多个调用则必须返回包含收据数组的receipts字段涵盖链上已包含该批次调用的所有交易包括最终 revert 的批次调用且必须显式返回atomic: false收据对象中的logs必须只包含与wallet_sendCalls提交的调用相关的日志。例如当交易由 ERC-4337 bundler 提交时日志只能包含由wallet_sendCalls提交的调用所构造的 User Operation 相关的日志不应包含同一 bundle 中其他无关 User Operation 的日志同理如果用户在提交批次前升级钱包以支持原子性日志不得包含升级过程中产生的日志。3.2 RPC 规范TypeScripttype GetCallsParams [string]; type GetCallsResult { version: string; id: 0x${string}; chainId: 0x${string}; status: number; // See Status Codes atomic: boolean; receipts?: { logs: { address: 0x${string}; data: 0x${string}; topics: 0x${string}[]; }[]; status: 0x${string}; // Hex 1 or 0 for success or failure, respectively blockHash: 0x${string}; blockNumber: 0x${string}; gasUsed: 0x${string}; transactionHash: 0x${string}; }[]; capabilities?: Recordstring, any; };3.3status状态码status字段为批次当前状态提供简短摘要为内部交易收据数组补充链下上下文。状态码分类如下1xx待处理Pending、2xx已确认Confirmed、4xx链下失败Offchain failures、5xx链规则失败Chain rules failures。CodeDescription100批次已被钱包接收但尚未在链上完成执行待处理200批次已无回滚地包含在链上receipts 数组包含所有调用的信息已确认400批次未包含在链上且钱包不再重试链下失败500批次完全回滚链上可能只包含与 gas 费用相关的变更链规则失败600批次部分回滚链上可能包含部分与批次调用相关的变更部分链规则失败这些类别内更具体的状态码应由独立 ERC 提出并达成共识。id批次标识符是wallet_sendCalls返回的、以十六进制字符串表示的 64 字节唯一值。3.4 请求与返回示例[ 0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331 ]{ version: 2.0.0, chainId: 0x01, id: 0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331, status: 200, atomic: true, receipts: [ { logs: [ { address: 0xa922b54716264130634d6ff183747a8ead91a40b, topics: [ 0x5a2a90727cc9d000dd060b1132a5c977c9702bb3a52afe360c9c22f0e9451a68 ], data: 0xabcd } ], status: 0x1, blockHash: 0xf19bbafd9fd0124ec110b848e8de4ab4f62bf60c189524e54213285e7f540d4a, blockNumber: 0xabcd, gasUsed: 0xdef, transactionHash: 0x9b7bb827c2e5e3c1a0a44dc53e573aa0b3af3bd1f9f5ed03071b100bb039eaff } ] }四、wallet_showCallsStatus让钱包展示批次信息wallet_showCallsStatus请求钱包展示某个已通过wallet_sendCalls发送的调用 bundle 的相关信息。注意对于已知的id批次标识符该方法不返回任何内容若标识符未知或出现任何其他执行失败则返回 RPC 调用错误。type ShowCallsParams string; // Call bundle identifier returned by wallet_sendCalls请求参数即wallet_sendCalls返回的调用 bundle 标识符[0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331]五、wallet_getCapabilities能力发现该 RPC 允许应用向钱包请求能力如批量交易、paymaster 通信而无需单独的发现与授权请求两者的区别见下文隐私考虑。若用户尚未授权应用与所请求地址之间的连接该方法应返回4100 Unauthorized错误。社区预期将在后续独立 ERC 中对更多能力的定义达成共识。5.1 链级per-chain能力组织能力以键值对返回键为能力名称值为该名称定义的结构外层对象按相关 EIP-155chainId十六进制分组。之所以按链嵌套是因为钱包在会话中授权的多个链上可能支持不同的能力。钱包在所有链上都支持的能力应只出现一次使用特殊链 ID0x0且不应在嵌套的逐链对象中重复。若钱包不支持wallet_getCapabilities请求中查询的某个链钱包不得返回错误而应在响应中不包含该不支持链的键。type GetCapabilitiesParams [0x${string}, [0x${string}]]; // Wallet address, array of queried chain ids (optional) type GetCapabilitiesResult Record0x${string}, Recordstring, any; // Hex chain id请求示例钱包地址 可选查询链 ID 数组[0xd46e8dd67c5d32be8058bb8eb970870f07244567, [0x2105, 0x14A34]]返回值示例以下能力仅为示意{ 0x0: { flow-control: { supported: true } }, 0x2105: { paymasterService: { supported: true }, sessionKeys: { supported: true } }, 0x14A34: { auxiliaryFunds: { supported: true } } }5.2 带外的能力表达除了直接查询钱包相同的能力对象也可以带外out-of-band暴露例如存放在 CAIP-25 兼容钱包 Provider 接口的sessionProperties和/或scopedProperties集合中见其以太坊使用 Profile 的请求/响应示例或存放在由 EIP-6963rdns标识符派生的 URL 等已知位置。Provider 抽象层也可以缓存之前的请求结果或从带外注入能力以改善用户体验。若这些补充的能力表达与钱包实时 RPC 响应中的能力相互矛盾应以实时 RPC 响应为准作为能力当前且权威的表达。六、atomic能力原子性协商与上文示例中的其他能力及未来 EIP 将定义的能力一样atomic能力说明钱包将如何执行通过wallet_sendCalls请求的交易批次。其唯一属性status的合法 JSON-RPC 值为supported钱包将原子且连续地执行这些调用ready钱包能够在用户批准后升级到supportedunsupported钱包不提供任何原子性或连续性保证也不会向用户建议升级。该能力在每条链上分别表达应理解为仅对该链上的交易批次的保证。若某链上不存在atomic能力且未被另一能力不在本 EIP 范围内显式覆盖则表示钱包不支持在该链上批量执行。type AtomicCapability { status: supported | ready | unsupported; };包含atomic的wallet_getCapabilities返回示例{ 0x2105: { atomic: { status: supported } }, 0x14A34: { atomic: { status: unsupported } } }七、错误码总览以下错误码适用于本 EIP 规定的方法遵循 JSON-RPC 2.0 错误对象规范必须包含code与message字段。其中4001与4100沿袭自 EIP-1193对应 User Rejected Request 与 Unauthorized。CodeMessageDescriptionRelated RPCs-32602Invalid params钱包无法解析该请求如缺少 0x 前缀、chain id 前导零、请求未通过 schema 校验wallet_sendCalls,wallet_getCallsStatus,wallet_showCallsStatus,wallet_getCapabilities4001User Rejected Request用户拒绝提交调用批次来自 EIP-1193wallet_sendCalls4100Unauthorized指定地址未连接或不在钱包中来自 EIP-1193wallet_sendCalls,wallet_getCapabilities5700Unsupported non-optional capability该钱包不支持未标记为可选的某个能力wallet_sendCalls5710Unsupported chain id该钱包不支持指定的 chain idwallet_sendCalls5720Duplicate ID已存在以该 id 提交的 bundlewallet_sendCalls5730Unknown bundle id该 bundle id 未知 / 尚未提交wallet_getCallsStatus,wallet_showCallsStatus5740Bundle too large调用 bundle 过大钱包无法处理wallet_sendCalls5750Atomic-ready wallet rejected upgrade钱包可通过升级支持原子性但用户拒绝了升级wallet_sendCalls5760Atomicity not supported钱包不支持原子执行但请求要求原子执行wallet_sendCalls八、设计取舍Rationale8.1 关于命名作者曾考虑直接修改eth_sendTransaction以支持这些新能力但该方法终究是节点签名交易时代的产物因此决定改用更能描述其用途的wallet_命名空间。命名也曾候选wallet_sendTransaction与wallet_sendCalls最终选择wallet_sendCalls是因为在 EOA 钱包场景下wallet_send*方法可能发送多笔交易而之所以不用wallet_sendTransactions是因为在其他钱包实现如 ERC-4337中多个调用可能合并进一笔交易。8.2 调用执行的原子性wallet_sendCalls接受calls数组但本提案不要求这些调用必须作为单笔交易执行。它允许 EOA 钱包表达单笔交易或多笔交易执行调用的能力也允许应用表达对调用执行方式的最低原子性要求。atomic特殊能力被纳入规范核心以提升表达力并促进钱包与应用双方的采纳因其对消除应用与钱包间歧义至关重要该能力同时以wallet_sendCalls请求中的顶层字段atomicRequired与wallet_getCallsStatus响应中的atomic字段显式表达。最初提案要求多调用必须原子执行经讨论后认为过于主观最终改为包含atomic能力规范——这样 EOA 钱包也能接受多调用同时仍给开发者仅在原子执行时提交批次的选择。8.3 调用 gas limit最初提案为calls字段中的每个调用包含可选gas字段但这在 ERC-4337 钱包下会产生误导——User Operation 只能为所有调用指定单一gas limit无法逐调用指定。随后提案改为适用于所有调用的单一gas值这对 ERC-4337 钱包可行但对 EOA 钱包不可行。当决定让 EOA 钱包也能处理多调用后跨用例统一的gas字段无法成立最终将其整体移除。九、向后兼容不支持本 EIP 所定义方法的钱包在收到这些新 JSON-RPC 方法调用时应返回错误响应。应用在因钱包不支持而调用失败时可以尝试通过eth_sendTransaction串行发送同一批调用也可以向用户提示其钱包不受支持、请求未被处理。十、安全与隐私考虑不得假设单笔交易无论atomic值如何应用开发者都不得假设所有调用会在单笔交易中发送例如抗重组且实现 sendBundle 的 L2 就可能不这样做。批次 ID 不可预测钱包必须确保wallet_sendCalls返回的批次标识符不可预测防止恶意应用推断其他用户交易的信息。不得泄露敏感信息钱包不得在wallet_getCallsStatus的capabilities响应中泄露敏感信息。隐私设计渐进式授权与渐进式同意范式对现代用户体验和用户代理匿名性至关重要。为保护这些模式免受功能发现改善体验带来的交叉激励能力语义被特意设计为**混淆缺乏功能支持与缺乏功能权限**之间的区别。钱包应避免向不可信调用方或超出必要范围的调用方暴露能力否则其用户代理客户端软件可能被指纹识别或概率性辨识叠加 Web 平台固有的去匿名化向量可能促成个体用户或某客户端全体用户的去匿名化。同理应用过度查询能力或激励能力过度共享含第三方共享属于应避免的反模式。十一、生态延伸仓库中基于 EIP-5792 的能力扩展本 EIP 明确将能力定义交由独立 ERC 扩展。当前仓库中已有两份以它为基础requires: 5792的后续提案可作为理解能力扩展机制的第一手素材eip-7867.mdFlow Control Wallet Call Capability为 EIP-5792 增加flowControl能力允许 DApp 下调原子性要求并控制调用失败/回滚后的行为——引入批次范围的strict与loose原子性概念strict批次在链重组面前仍保持原子loose则否以及逐调用的失败后继续continue或停止halt选项。其 JSON Schema 直接插入wallet_sendCalls请求的批次级或调用级capabilities对象中键名为flowControlatomicity取值枚举为[strict, loose, none]。eip-7896.mdABI attachment inwallet_sendCalls针对盲签问题增加interfaces能力允许应用把合约接口规范ABI附加到请求中使钱包能可靠解码 calldata 并展示给用户。其类型定义为capabilities?: { interfaces?: InterfacesCapability } Recordstring, CapabilityInterfacesCapability以合约地址为键映射到{ version, spec }初始定义abi-v1与abi-v2两个版本对应 Solidity 的pragma abicoder v1/pragma abicoder v2Vyper 实现abi-v2并建议应用将其标记为optional。这两个例子展示了 EIP-5792 的能力插槽如何被后续标准安全地填充——钱包只需在wallet_getCapabilities响应中声明、在wallet_sendCalls请求中消费即可无协调地扩展功能。十二、相关标准引用eip-1193.mdEthereum Provider JavaScript API4001/4100错误码来源EIP-5792 的requires依赖eip-155.md简单重放攻击防护chainId的编码基础eip-4337.md账户抽象Account Abstractionpaymaster 与 User Operation 场景的参考实现该文件在仓库中已标记为 Moved指向 ERC 仓库eip-6963.mdMulti Injected Provider Discovery其rdns反向域名标识符可作为能力带外发布的寻址基础版权说明本 EIP 全文版权已通过 LICENSE.md 的 CC0 协议放弃。【免费下载链接】EIPsThe Ethereum Improvement Proposal repository项目地址: https://gitcode.com/GitHub_Trending/ei/EIPs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考