CAIP-311: JSON-RPC Event for Session Authorization Updates

Author Alex Donesky
Discussions-To https://github.com/ChainAgnostic/CAIPs/pull/285/files
Status Draft
Type Standard
Created 2024-07-12
Requires 25, 217

Table of Contents

Simple Summary

CAIP-311 introduces the wallet_sessionChanged event for notifying callers party to an active CAIP-25 session of updates to session authorizations made by users directly in the wallet.

Abstract

This proposal aims to extend the CAIP-25 standard by defining a new JSON-RPC event for notifying the caller of updates to session authorizations. This event allows wallets to dynamically inform callers of changes to authorizations made by users on the wallet side, without having to initiate a new session each time.

Motivation

The motivation behind this proposal is to provide bidirectional management of CAIP-25 session authorizations. The proposed event provides an intuitive way to notify dapps of changes to authorizations within an active session, simplifying the management of session lifecycles.

Definition

Specification

This event is published by the wallet to notify the callers of updates to a shared session’s authorization scopes. The event payload contains the new sessionScopes. If a connection between the wallet and the caller is severed and the possibility of missed events arises, the caller should immediately call wallet_getSession to retrieve the current session scopes.

Notification Parameters:

  • sessionId (string, optional): The session identifier.
  • sessionScopes (object of scopeObject objects, required): An object containing the full updated session scopes, each formatted according to CAIP-217.

Notification:

{
  "method": "wallet_sessionChanged",
  "params": {
    "sessionScopes": {
      "eip155:1": {
        "methods": ["eth_signTransaction", "eth_sendTransaction"],
        "notifications": ["accountsChanged"],
        "accounts": ["eip155:1:0xabc123"]
      },
      "eip155:137": {
        "methods": ["eth_sendTransaction"],
        "notifications": [],
        "accounts": ["eip155:137:0xdef456"]
      }
    }
  }
}

Security Considerations

The introduction of this lifecycle method must ensure that only authorized parties can retrieve the authorizations of a session. Proper authentication and authorization mechanisms must be in place to prevent unauthorized access or modifications.

To achieve this, it is recommended to establish a connection over domain-bound or other 1:1 transports. Where applicable, additional binding to a sessionId is recommended to ensure secure session management. This approach helps to create a secure communication channel that can effectively authenticate and authorize session-related requests, minimizing the risk of unauthorized access or session hijacking.

  • CAIP-25 - JSON-RPC Handshake Protocol Specification. i.e wallet_createSession
  • CAIP-217- Authorization Scopes, i.e. syntax for scopeObjects

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Alex Donesky, "CAIP-311: JSON-RPC Event for Session Authorization Updates [DRAFT]," Chain Agnostic Improvement Proposals, no. 311, July 2024. [Online serial]. Available: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-311.md