EIP-5792 Wallet Call API
Final · Account abstraction · EIP status Final · created 2022-10-17
Adds four JSON-RPC methods that let an app send several onchain calls to a wallet as one batch, check the processing status of that batch, and look up in advance the capabilities the wallet supports.
Why it is needed
Today, an app sends a transaction to a wallet with eth_sendTransaction and checks the result with eth_getTransactionReceipt. These names are themselves a legacy of the era when the node acted as the wallet, and they do not meet the needs of modern developers. Developers today want to bundle several calls and send them together. Many smart accounts can execute them atomically (all succeed or all are cancelled) within a single transaction. Developers also want to use features that new transaction formats provide, such as the paymaster (a fee-sponsoring service) in ERC-4337. However, eth_sendTransaction has no way to express any of this. This EIP defines new methods in the wallet_ namespace to cleanly separate the roles of wallet and app, enable features such as batched calls and paymasters, and create a path for safely adding new features in the future with minimal coordination.
What changes
Today
- Apps send calls one at a time with eth_sendTransaction and check the receipt separately with eth_getTransactionReceipt
- There is no standard way to send several calls as a batch or to request new features such as a paymaster
- An app has no way to know in advance which features a wallet supports
After EIP-5792
- Send several calls at once with wallet_sendCalls and check batch-level status with wallet_getCallsStatus
- Require atomic execution with the atomicRequired field, and request features such as a paymaster service together with the capabilities field
- Query per-chain supported features in advance with wallet_getCapabilities
- A fallback path to the existing eth_sendTransaction is defined for wallets that do not support the new methods
Who is affected
- App developers: You can send batched calls through the same interface whether the wallet is an EOA or a smart account. However, regardless of the atomic value, you must not assume that all calls go in a single transaction.
- Wallet developers: You must implement the four methods, the atomic capability reporting, and the defined error codes. Batch identifiers must be made unpredictable.
- Users: It becomes possible to handle multi-step operations (for example, approve and then execute) with a single confirmation.
- ERC-4337 ecosystem: Apps can use user-operation-based features in a standard way, for example by passing a paymaster service URL through capabilities.
In depth
wallet_sendCalls: request format and wallet obligations
A request consists of version, an optional id and from, a hexadecimal chainId (EIP-155, 0x prefix, no leading zeros), atomicRequired, and a calls array. Each call is a {to, data, value} tuple and can carry per-call capabilities. The wallet MUST send the calls in the requested order, on the same chain that the request's chainId points to, from the from address. If from is absent, the wallet SHOULD give the user a chance to see and choose the address on the confirmation screen. The wallet must not wait for finalization of the calls before completing the batch, and must not send any calls if the user rejects. The wallet MAY reject the request if from differs from the active account, or if sequential simulation predicts that some calls will fail.
atomicRequired and the atomic capability
The status of the atomic capability has three values: supported, ready, and unsupported. supported means the wallet executes the calls atomically and contiguously. ready means the wallet can upgrade to supported with user approval, and unsupported means there is no atomicity guarantee and no upgrade offer. This capability is expressed per chain, and if a chain has no atomic capability, it means batching is not supported on that chain. If atomicRequired is true, the wallet must execute all calls atomically (all succeed, or no material effect remains onchain) and contiguously, with no other transactions interleaved. A wallet in the ready state must upgrade before submitting. If it is false, sequential execution is also allowed, and the wallet may choose atomic execution when possible.
capabilities and the optional flag
The capabilities object is the channel through which an app requests wallet features. For example, an ERC-4337 wallet gets the paymaster service URL, from which it fetches the paymasterAndData input, placed here. Each capability can define global fields and per-call fields. A wallet MUST reject the request (error 5700) if it contains a capability the wallet does not support and that capability is not marked optional: true. For a capability marked optional, a wallet that does not support it processes the request as if the capability were not there. Definitions of specific capabilities are outside the scope of this EIP and are set in separate ERCs.
Batch identifier (id) rules
The id in the response is the key for tracking the batch. If the app provides an id, the wallet must honor it and return it unchanged in the response. An identifier must be a unique string of at most 4096 bytes (8194 characters including 0x), and an app-provided id must be unique per sending address and per app (identified by domain). A request with a duplicate id must be rejected (error 5720), and the wallet SHOULD return the status for 24 hours after wallet_sendCalls if wallet_getCallsStatus is called with the same id. For security, identifiers must be unpredictable so that a malicious app cannot infer another user's transaction information.
wallet_getCallsStatus: status codes and receipts
The response contains a status code, an atomic field, and a receipts array. Codes are divided into 1xx pending, 2xx confirmed, 4xx offchain failure, and 5xx chain rule failure. 100 means the batch was received but onchain execution is not complete, 200 means it was included without reverts, 400 means it was not included and will not be retried, 500 means a full revert (only gas-charging changes may remain), and 600 means a partial revert. If execution was atomic, atomic must be explicitly set to true, and receipts can be a single receipt or an array. For non-atomic execution, atomic is set to false and the wallet must return an array of receipts for all transactions included onchain, including reverted ones. The logs in a receipt must contain only those related to this batch, and must not include logs from other user operations in the same bundle or from the wallet upgrade process.
wallet_showCallsStatus and wallet_getCapabilities
wallet_showCallsStatus is a request to show the batch's information in the wallet UI. For a known id it returns no value, and for an unknown id or on failure it returns an RPC error. wallet_getCapabilities returns capabilities as an object keyed by chain id. A capability supported on all chains SHOULD be listed once under the special chainId value "0x0" and not repeated in the per-chain objects. For an unsupported chain, the wallet MUST omit the key from the response instead of returning an error. If the app and address have not yet been approved for connection, the wallet SHOULD return 4100 Unauthorized. The same capability information may also be exposed out of band, for example in CAIP-25 sessionProperties or in a location derived from the EIP-6963 rdns, but if it contradicts a live RPC response, the latter takes precedence.
Error codes and design background
The defined errors are -32602 (request cannot be parsed), 4001 (user rejected), 4100 (unconnected address), 5700 (non-optional capability not supported), 5710 (unsupported chain), 5720 (duplicate id), 5730 (unknown batch id), 5740 (batch too large), 5750 (atomicity possible through an upgrade but the user declined the upgrade), and 5760 (wallet does not support the requested atomic execution). For the name, the authors chose the wallet_ namespace instead of modifying eth_sendTransaction. An EOA wallet may turn one request into several transactions, and an ERC-4337 wallet may turn several calls into one transaction, so they settled on wallet_sendCalls. At first they planned to make atomic execution mandatory, but judged that too rigid and split it out into the atomic capability. A per-call gas field was also removed because it could not satisfy both ERC-4337 and EOA wallets.
Privacy considerations and current status
The capability query is designed so that it deliberately cannot distinguish between a feature being unsupported and permission being absent, which protects the progressive permission-granting pattern. If a wallet exposes capabilities to an untrusted caller, client fingerprinting could break user anonymity, so wallets are advised not to expose more than necessary. Apps querying capabilities excessively or inducing over-sharing are also anti-patterns to avoid. This EIP is an interface standard in Final status that wallets and apps adopt without a protocol fork, and it was discussed in 08.29 AMA #14, where no decision was made.