CAIP-27: Wallet Invoke Method JSON-RPC Method

Author Pedro Gomes, Hassan Malik
Discussions-To https://github.com/ChainAgnostic/CAIPs/pull/27
Status Draft
Type Standard
Created 2020-12-12
Updated 2024-07-02
Requires 2, 25, 171, 217

Simple Summary

CAIP-27 defines a JSON-RPC method for a wallet-connected application to invoke a wallet invoke an JSON-RPC method in a specified context defined by a valid scopeObject and tagged with a sessionId for maintaining session continuity.

Abstract

This proposal has the goal of defining a standard method for decentralized applications to invoke JSON-RPC methods from user agents (such as cryptocurrency wallets) directed to a given, previously-authorized target chain (such as nodes of a specific blockchain or consensus community within a protocol). It requires a valid scopeObject and a valid sessionId for interoperability and composability. These two properties MAY be inherited from a persistent session created by CAIP-25, but could also be used as part of other session management mechanisms.

Motivation

The motivation comes from the ambiguity that comes from interfacing with a multi-chain agent (e.g. a cryptocurrency wallets which supports the same method on multiple chains in a namespace, or supports methods with the same name on multiple namespaces).

Specification

Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” written in uppercase in this document are to be interpreted as described in RFC 2119

Definition

The JSON-RPC provider is able to invoke a single JSON-RPC request accompanied by a CAIP-2 compatible chainId scoped by the sessionId of a pre-existing session.

Request

The application would interface with an JSON-RPC provider to make request as follows:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "wallet_invokeMethod",
  "params": {
    "sessionId": "0xdeadbeef",
    "scope": "eip155:1",
    "request": {
      "method": "personal_sign",
      "params": [
        "0x68656c6c6f20776f726c642c207369676e2074657374206d65737361676521",
        "0xa89Df33a6f26c29ea23A9Ff582E865C03132b140"
      ]
    }
  }
}

The JSON-RPC method is labeled as wallet_invokeMethod and expects three required parameters:

  • sessionId - CAIP-171 SessionId referencing a known, open session
  • scope - a valid scopeObject previously authorized to the caller and persisted in the session identified by sessionId
  • request - an object containing the fields:
    • method - JSON-RPC method to invoke
    • params - JSON-RPC parameters to invoke (may be empty but must be set)

Validation

  1. A respondent MUST check the scope against the identified session object before executing or responding to such a request, and invalidate a request for a scope not already authorized and persisted.
  2. The respondent SHOULD check that request.method is authorized in the session object for that specific scope.
  3. The respondent MAY check that the params are valid for that method, if its syntax is known to it.
  4. The respondent MAY apply other logic or validation.
  5. The respondent MAY chose to drop invalid requests or return an error message, but it MUST NOT route or submit them.

Response

Upon succesful validation, the respondent will submit or route the request to the targeted chain. If the targeted chain returns a response to the respondent, the respondent MAY forward this response to the caller. Constraints on, metadata about, or envelopes for response-forwarding MAY be set by namespace profiles of this CAIP.

Similarly, error messages depend on the design of a given namespace, and MAY be defined by a namespace profile of this CAIP.

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Pedro Gomes, Hassan Malik, "CAIP-27: Wallet Invoke Method JSON-RPC Method [DRAFT]," Chain Agnostic Improvement Proposals, no. 27, December 2020. [Online serial]. Available: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-27.md