ERC-7836 Wallet call preparation API
Draft · Accounts & wallets · created 2024-12-06
Defines two JSON-RPC methods that let an app receive a digest to be signed from a wallet, sign it directly with a session key, and then hand off execution. This standardizes a flow in which the app, not the wallet, signs the call bundle.
Why it is needed
Demand is growing for apps to send transactions on a user's behalf. For example, an app that automates trading on a decentralized exchange wants to use a session key with limited, scoped permissions to skip the approval and signing step on the wallet screen every time the user trades. However, each Smart Contract Account has a different execution interface, so the format of the call data to be signed also differs by account implementation. For an app to sign for an arbitrary account implementation, it would have to build and maintain a mapping of signing logic for each account implementation, which is effectively impossible. So there needs to be a simple way for an app to tell the wallet which call it wants to execute, receive back the payload to sign with a session key, and then hand off execution together with the signature once signing is complete.
What to implement
wallet_prepareCalls: Takes a list of calls to execute, prepares a call bundle matching the account implementation, and returns the digest to be signed along with the values needed for the execution request (capabilities, chainId, context, version).wallet_sendPreparedCalls: Takes the prepared call bundle and signature, executes it, and returns a bundle id in the same format as wallet_sendCalls.
In depth
wallet_prepareCalls request format
The request is identical to EIP-5792's wallet_sendCalls. params contains the array of calls to execute (calls, each entry with to and the optional fields data, value, capabilities), bundle-level capabilities, the chainId of the target chain for submission, the sending address from (optional), a key hint for signing key (optional), and the method version. key contains the public key publicKey, the key type type (one of secp256k1, p256, webauthn-p256), and prehash, which indicates whether the key pre-hashes the digest (the default behavior of the WebCrypto API).
wallet_prepareCalls response and digest
The wallet returns the signing-target digest together with the values needed to fill out the wallet_sendPreparedCalls request: capabilities, chainId, context, version, and key. context is wallet-specific internal data; the original cites an ERC-4337 UserOperation or an alternative as an example. The response's key.type may additionally include webcrypto-p256, which was not in the request. After signing the digest, the caller passes the rest of the response, excluding the digest, as-is to wallet_sendPreparedCalls.
wallet_sendPreparedCalls
The request is identical to the wallet_prepareCalls response but with a signature field added. That is, it contains capabilities, chainId, context, the key actually used for signing, the signature over the call bundle, and version. The response contains the bundle identifier id and capabilities, the same as wallet_sendCalls. The example code shows a flow where the digest is destructured out of the prepareCalls response, signed with a p256 key, and then sent with only the signature added to the rest of the request.
Design rationale
These two methods extend the interface established by EIP-5792 to meet app developers' new needs. For this purpose, adding a separate endpoint is simpler than adding options to wallet_sendCalls. Since a wallet already prepares calls internally and submits signed calls to the chain to support wallet_sendCalls, exposing the prepared calls externally is relatively straightforward for the wallet.
Backward compatibility
This does not break the existing EIP-5792 flow. It does not modify or deprecate wallet_sendCalls, so wallets that follow EIP-5792 continue to work as is. wallet_prepareCalls follows the same request shape as wallet_sendCalls and keeps the field formats for capabilities, chainId, context, and version, while returning the values needed to pass to wallet_sendPreparedCalls. wallet_sendPreparedCalls takes the data the wallet was already building internally, with only an externally generated signature added. The additional key types from the WebCrypto or WebAuthn family are optional and do not affect EIP-5792 behavior.
Still in draft stage
This proposal's status is Draft. Since it is still a draft under discussion, the method names, field composition, and list of key types may change going forward. It is safe to check the latest original text when implementing.
Things to watch out for
- Checking key permissions and scope: The wallet must verify that the key.publicKey in the request is a key approved for that account, and that the requested capabilities fall within that key's permission scope (scope, limits, validity period).
- Consistency in prehash handling: If the signer and verifier handle key.prehash differently (such as a mismatch between double-hashing and an already pre-hashed input), verification can fail. Wallets should fix the hash function per key type.
- Linking preparation and execution: Wallets should ideally verify that wallet_sendPreparedCalls corresponds to a digest they could have produced themselves (e.g. by recomputing it), and may use a preparation identifier or expiry period to prevent replay of long-lived requests.
- WebAuthn and origin binding: webauthn-p256 keys should use credentials bound to user verification and origin. Apps should keep session keys non-extractable, protect them with hardware where possible, and avoid showing an unintelligible digest as-is on the end-user approval screen.
- Guarding against resource exhaustion and denial of service: Wallets can rate-limit wallet_prepareCalls, cap bundle size, and validate input early, so that malformed or malicious requests do not repeatedly trigger costly context generation.