SRC-7871: Wallet Signing API

Adds a JSON-RPC method for requesting a signature from a wallet

Abstract

Defines a new JSON-RPC method wallet_sign which enables apps to ask a wallet to sign SIP-191 messages.

Applications can use this JSON-RPC method to request a signature over any version of signed_data as defined by SIP-191. The new JSON-RPC method allows for support of future SIP-191 signed_data versions.

The new JSON-RPC method also supports SIP-5792-style capabilities, and support for signing capabilities can be discovered using wallet_getCapabilities as defined in SIP-5792.

Motivation

Wallets and developer tools currently support multiple JSON-RPC methods for handling offchain signature requests. This proposal simplifies wallet & tooling implementations by consolidating these requests under a single wallet_sign JSON-RPC method. This also leaves room for new SIP-191 signed_data versions without needing to introduce a new corresponding JSON-RPC method.

Furthermore, this new wallet_sign method introduces new functionalities via SIP-5792-style capabilities.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174. One new JSON-RPC method is introduced.

wallet_sign

Requests a signature over SIP-191 signed_data from a wallet.

The top-level version parameter is for specifying the version of wallet_sign should the top-level interface change.

The request.type parameter is for specifying the SIP-191 signed_data version (e.g. 0x01 for structured data, 0x45 for personal_sign messaged). The request.data parameter is the corresponding data according to the signed_data version.

The optional address parameter is for requesting a signature from a specified address. If included, the wallet MUST respect it and only respond with a signature from that address.

The capabilities field is how an app can communicate with a wallet about capabilities that a wallet supports.

This proposal defines request schemas for the three signed_data versions currently in SIP-191 (0x00, 0x01, 0x45). Any future signed_data versions can be supported by wallet_sign, and their request interfaces are left to future SRCs.

wallet_sign RPC Specification

type Capability = {
  [key: string]: unknown;
  optional?: boolean;
}

type SignParams = {
  version: string;
  address?: `0x${string}`;
  request: {
    type: `0x${string}`; // 1-byte SIP-191 version
    data: any; // data corresponding to the above version
  };
  capabilities?: Record<string, Capability>;
};

type SignResult = {
  signature: `0x${string}`;
  capabilities?: Record<string, any>;
};

Request Interfaces

Below are request interfaces for the signed_data versions specified in SIP-191 at time of writing. These include:

• 0x00 - Data with intended validator
• 0x01 - SIP-712 Typed Data
• 0x45 - Personal Sign

Any new request interfaces corresponding to new signed_data versions SHOULD be defined in their own SRCs.

type ValidatorRequest = {
  type: '0x00';
  data: {
    validator: `0x${string}`; // Intended validator address
    data: `0x${string}`; // Data to sign
  };
}

type TypedDataRequest = {
  type: '0x01';
  data: {
    ...TypedData // TypedData as defined by SIP-712
  }
}

type PersonalSignRequest = {
  type: '0x45';
  data: {
    message: string; // UTF-8 message string
  }
}

wallet_sign Example Parameters

{
  "version": "1.0",
  "request": {
    "type": "0x45",
    "data": {
      "message": "Hello world"
    }
  }
}

wallet_sign Example Return Value

{
  "signature": "0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
}

Rationale

Backwards Compatibility

Security Considerations

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Lukas Rosario (@lukasrosario), Jake Moxey (@jxom), Cody Crozier (@wcrozier12), Conner Swenberg (@ilikesymmetry), "SRC-7871: Wallet Signing API [DRAFT]," Sila Improvement Proposals, no. 7871, January 2024. Available: https://sips.sila.org/SIPS/sip-7871.