CAIP-341: Extension ID Target Type Specification

Author Alex Donesky, Jiexi Luan, Joao Tavares
Discussions-To https://github.com/ChainAgnostic/CAIPs/issues/341
Status Draft
Type Standard
Created 2024-12-12
Requires 294

Table of Contents

Simple Summary

CAIP-341 defines the Extension ID type as a valid target type for establishing connections with browser extension wallets via the CAIP-294 wallet_announce wallet discovery event.

Abstract

This proposal introduces a new target type, Extension ID, for the target field of the WalletData interface dispatched in CAIP-294’s wallet_announce event. This target type is used to specify the extension ID of a browser extension wallet, allowing callers to establish connections with the wallet using the externally_connectable API.

Motivation

CAIP-294 proposes a solution to fragmentation across blockchain ecosystems wallet discovery mechanisms (e.g Ethereum’s EIP-6963, Solana’s Wallet Standard). By defining a standardized target type for browser extension wallets that use the externally_connectable browser API, we aim to extend CAIP-294’s unified solution to cross ecosystem wallet discoverability, enhancing interoperability across these different blockchain ecosystems.

Specification

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

Definitions

Wallet Provider: A user agent that manages accounts and facilitates transactions with a blockchain.

Decentralized Application (dapp): A web page that relies upon one or many Web3 platform APIs which are exposed to the web page via the Wallet.

Blockchain Library: A library or piece of software that assists a dapp to interact with a blockchain and interface with the Wallet.

Target Type

The target field in the WalletData interface is used to specify the connection method for the wallet. This CAIP introduces the Extension ID type as a valid target type.

This field MAY be included in the WalletData object defined in [CAIP294]. If included, the property target SHOULD be an array of objects, containing Extension ID type used to connect to wallets using externally_connectable. An array was chosen for easier interoperability and flexibility for multiple CAIP target definitions. This specification defines entries in that array typed as caip341.

interface WalletData {
  // Required properties
  uuid: string;
  name: string;
  icon: string;
  rdns: string;
  // Optional properties
  target?: { type: string, value: any }[],
  scopes?: Caip217AuthorizationScopes;
}

Usage

The Extension ID target type is used to specify the extension ID of a browser extension wallet. This allows the dapp to establish a connection with the wallet using the externally_connectable API. The externally_connectable API documentation can be found here.

const walletData = {
  uuid: "350670db-19fa-4704-a166-e52e178b59d2",
  name: "Example Wallet",
  icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  rdns: "com.example.wallet",
  target: [
    {
      type: "caip341",
      value: "abcdefghijklmnopqrstuvwxyzabcdef"
    },
    {
      type: "caip315",
      value: true
    },
    {
      type: "caip316",
      value: {
        somethingElse: "hello"
      }
    }
  ],
  scopes: {
    "eip155:1": {
      methods: ["eth_signTransaction", "eth_sendTransaction"],
      notifications: ["accountsChanged", "chainChanged"]
    }
  }
}

Establishing Connection

When the target type is caip341 (i.e., Extension ID), the dapp MUST use the Extension ID to establish a connection with the wallet using the externally_connectable browser API, using the passed value to uniquely identify the extension. All subsequent communication with the wallet SHOULD be conducted over the externally_connectable API using runtime.connect() and runtime.sendMessage().

Example of establishing a connection and sending a message:

const extensionId = walletData.target.find((entry) => entry.type === 'caip341').value;
const port = chrome.runtime.connect(extensionId);

port.onMessage.addListener((message) => {
  // Handle incoming messages
});

port.postMessage({
  id: 1,
  jsonrpc: "2.0",
  method: "wallet_createSession",
  params: {
    // ... session parameters ...
  }
});

Rationale

By defining the Extension ID target type, we provide a standardized way for dapps to connect with browser extension wallets. This reduces complexity and enhances interoperability across different blockchain ecosystems. The use of the externally_connectable API ensures secure and efficient communication between the dapp and the wallet.

Backwards Compatibility

This CAIP is fully compatible with existing standards and does not introduce any breaking changes. It extends the WalletData interface to include the target field, which is optional and does not affect existing implementations.

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Alex Donesky, Jiexi Luan, Joao Tavares, "CAIP-341: Extension ID Target Type Specification [DRAFT]," Chain Agnostic Improvement Proposals, no. 341, December 2024. [Online serial]. Available: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-341.md