CAIP-319: Wallet Notification JSON-RPC Method

Author Alex Donesky
Discussions-To https://github.com/ChainAgnostic/CAIPs/pull/X
Status Draft
Type Standard
Created 2024-08-01
Requires 2, 25, 171, 217

Table of Contents

Simple Summary

CAIP-319 defines a JSON-RPC method for a wallet to send notifications to a caller in a context authorized by or in a valid scopeObject and, optionally, tagged with a sessionId for maintaining session continuity if applicable.

Abstract

This proposal aims to define a standard method for wallets to send notifications to callers regarding events or state changes related to a specific, previously-authorized target network (such as nodes of a specific blockchain or consensus community within a protocol). It requires a valid scopeObject. It MAY be tagged with a sessionId if the CAIP-25 session in which it is authorized is keyed by a sessionId (see CAIP-316 for more details). 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 for this proposal comes from the need for standardized, chain-specific notifications from wallets to applications in a concurrent multi-chain connection where methods and notifications with the same namespace may exist across chains or namespaces.

Specification

Definition

The wallet is able to send a single JSON-RPC notification accompanied by a CAIP-2 compatible chainId, and optionally scoped by the sessionId of a pre-existing session if applicable.

Notification

The wallet or user agent would send a notification to the application as follows:

{
  "jsonrpc": "2.0",
  "method": "wallet_notify",
  "params": {
    "sessionId": "0xdeadbeef",
    "scope": "eip155:1",
    "notification": {
      "method": "eth_subscription",
      "params": {
        "subscription": "0x12345678",
        "result": {
          "blockNumber": "0x1234",
          "transactionHash": "0x5678",
          "logIndex": "0x9abc"
        }
      }
    }
  }
}

The JSON-RPC method is labeled as wallet_notify and expects two required parameters:

  • scope - a valid CAIP-2 chainId previously authorized to the caller within a CAIP-25 session
  • notification - an object containing the fields:
    • method - JSON-RPC notification method name previously authorized to the caller within a CAIP-25 session
    • params - JSON-RPC notification parameters

Additionally, it MAY include an optional parameter:

  • sessionId - CAIP-171 sessionId referencing a known, open session

Validation

  1. The application MUST check the scope against the identified session object before processing the notification.
  2. The application SHOULD verify that the notification.method is one it expects to receive for that specific scope.
  3. The application MAY apply other logic or validation to the notification data.
  4. The application MAY choose to ignore notifications it doesn’t recognize or considers invalid.

Response

As this syntax simply provides a wrapper to a standard JSON-RPC notification and functions as one itself, no response is expected from the application. The wallet or user agent SHOULD NOT wait for a response before continuing its operations.

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Alex Donesky, "CAIP-319: Wallet Notification JSON-RPC Method [DRAFT]," Chain Agnostic Improvement Proposals, no. 319, August 2024. [Online serial]. Available: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-319.md