diff --git a/CAIPs/caip-341.md b/CAIPs/caip-341.md new file mode 100644 index 00000000..d6e75e92 --- /dev/null +++ b/CAIPs/caip-341.md @@ -0,0 +1,140 @@ +--- +caip: 341 +title: Extension ID Target Type Specification +author: Alex Donesky (@adonesky1), Jiexi Luan (@jiexi), Joao Tavares (@ffmcgee725) +discussions-to: https://github.com/ChainAgnostic/CAIPs/issues/341 +status: Draft +type: Standard +created: 2024-12-12 +requires: 294 +--- + +## 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`][externally_connectable API documentation] 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](https://www.rfc-editor.org/rfc/rfc2119). + +### 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`. + +```typescript +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](https://developer.chrome.com/docs/extensions/reference/manifest/externally-connectable). + +```ts +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: + +```ts +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. + +## Links + +- [EIP-6963][eip-6963] - Ethereum's Multi Injected Provider Discovery +- [CAIP-294][caip-294] - Browser Wallet Messaging for Extensions +- [externally_connectable API documentation][externally_connectable API documentation] - Chrome's `externally_connectable` browser API documentation +- [Wallet Standard][wallet standard] - Solana's Wallet Standard for discoverability + +[eip-6963]: https://eips.ethereum.org/EIPS/eip-6963 +[caip-294]: https://chainagnostic.org/CAIPs/caip-294 +[externally_connectable API documentation]: https://developer.chrome.com/docs/extensions/reference/manifest/externally-connectable +[wallet standard]: https://github.com/anza-xyz/wallet-standard + +## Copyright +Copyright and related rights waived via [CC0](../LICENSE).