ERC-7871 Unified Wallet Signature Request API (Wallet Signing API)
Draft · Signatures & auth · created 2024-01-29
Consolidates the multiple methods apps used to call when requesting signatures from wallets into a single wallet_sign method, so new signing schemes can be supported without adding new methods.
Why it is needed
Today, wallets and apps each call different JSON-RPC methods depending on the situation when requesting a signature, such as personal_sign or eth_signTypedData_v4. Wallets and developer tools must implement and maintain all of these methods, and whenever a new signed_data version is added to EIP-191, a corresponding new method has to be created separately. There is also no standard way for a wallet to tell an app which additional features it supports for signing. This duplication and fragmentation makes wallet implementations more complex, and app developers also have to account for different methods across different wallets.
What to implement
type Capability = { [key: string]: unknown; optional?: boolean; }: A type representing a single additional feature an app passes to a wallet; if optional is true, the wallet is not required to support that feature.type SignParams = { version: string; address?: `0x${string}`; request: { type: `0x${string}`; // 1-byte EIP-191 version data: any; // data corresponding to the above version }; capabilities?: Record<string, Capability>; };: The set of parameters passed to a wallet_sign call, containing the type of data to sign (request), the signing party (address), and additional features (capabilities).type SignResult = { signature: `0x${string}`; capabilities?: Record<string, any>; };: The result a wallet returns for a wallet_sign request, containing the actual signature value (signature) and a response for capabilities.type ValidatorRequest = { type: '0x00'; data: { validator: `0x${string}`; // Intended validator address data: `0x${string}`; // Data to sign }; }: The signing request format for EIP-191 version 0x00, used for data intended for a specified validator.type TypedDataRequest = { type: '0x01'; data: { ...TypedData // TypedData as defined by EIP-712 } }: The signing request format for EIP-191 version 0x01, used for EIP-712 structured data.type PersonalSignRequest = { type: '0x45'; data: { message: string; // UTF-8 message string } }: The signing request format for EIP-191 version 0x45, used for personal_sign-style messages.
In depth
The Role of the wallet_sign Method
wallet_sign is a new JSON-RPC method by which an app requests a signature from a wallet for EIP-191 signed_data. It merges the previously scattered signature request methods into this single one, allowing a signature for any EIP-191 signed_data version to be requested through the same interface.
SignParams Structure
version is a top-level parameter indicating the version of the wallet_sign interface itself. address is optional; if included, the wallet MUST return a signature only from that address. request consists of type and data, where type is the 1-byte version of EIP-191 signed_data (e.g. 0x01, 0x45) and data holds the data matching that version. capabilities is an optional field through which an app passes additional features to the wallet, following the EIP-5792 approach.
SignResult Structure
For a signature request, the wallet returns the signature value in the signature field. The capabilities field is optional and may contain the wallet's response to the capabilities included in the request.
The Three Request Interfaces
This ERC defines request schemas for the three signed_data versions currently defined in EIP-191. ValidatorRequest, with type 0x00, holds a validator address and the data to be signed. TypedDataRequest, with type 0x01, holds the EIP-712 TypedData as-is in data. PersonalSignRequest, with type 0x45, holds a UTF-8 string message in data. It is recommended (SHOULD) that request interfaces for any future signed_data versions be defined in a separate ERC.
Capabilities and Feature Discovery
wallet_sign supports capabilities in the EIP-5792 style. Through the capabilities field, an app can request that a wallet use an additional feature, and which signing-related capabilities a wallet supports can be checked in advance via the wallet_getCapabilities method defined by EIP-5792.
Specifying the Signing Party via the address Parameter
address in SignParams is an optional parameter, but if included, the wallet MUST honor it and return a signature only from the specified address.
Rationale Sections Still Empty
This proposal is currently in Draft status, and the Rationale, Backwards Compatibility, and Security Considerations sections are all still marked TODO, with no concrete content filled in yet. The specification may change as detailed design and security analysis are added.