Skip to content

Commit 692847b

Browse files
bumblefudgebumblefudge
authored
Merge pull request #341 from ffmcgee725/feat/define-extension-id-as-a-valid-target-type
CAIP-341 - Extension ID Target Type Specification
2 parents 1c12742 + 0ea3f70 commit 692847b

File tree

1 file changed

+140
-0
lines changed

1 file changed

+140
-0
lines changed

‎CAIPs/caip-341.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
caip: 341
3+
title: Extension ID Target Type Specification
4+
author: Alex Donesky (@adonesky1), Jiexi Luan (@jiexi), Joao Tavares (@ffmcgee725)
5+
discussions-to: https://github.com/ChainAgnostic/CAIPs/issues/341
6+
status: Draft
7+
type: Standard
8+
created: 2024-12-12
9+
requires: 294
10+
---
11+
12+
## Simple Summary
13+
14+
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.
15+
16+
## Abstract
17+
18+
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.
19+
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.
20+
21+
## Motivation
22+
23+
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.
24+
25+
## Specification
26+
27+
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).
28+
29+
### Definitions
30+
31+
Wallet Provider: A user agent that manages accounts and facilitates transactions with a blockchain.
32+
33+
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.
34+
35+
Blockchain Library: A library or piece of software that assists a dapp to interact with a blockchain and interface with the Wallet.
36+
37+
### Target Type
38+
39+
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.
40+
41+
This field MAY be included in the `WalletData` object defined in [CAIP294].
42+
If included, the property `target` SHOULD be an array of objects, containing Extension ID type used to connect to wallets using `externally_connectable`.
43+
An array was chosen for easier interoperability and flexibility for multiple CAIP target definitions.
44+
This specification defines entries in that array typed as `caip341`.
45+
46+
```typescript
47+
interface WalletData {
48+
// Required properties
49+
uuid: string;
50+
name: string;
51+
icon: string;
52+
rdns: string;
53+
// Optional properties
54+
target?: { type: string, value: any }[],
55+
scopes?: Caip217AuthorizationScopes;
56+
}
57+
```
58+
59+
### Usage
60+
61+
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).
62+
63+
```ts
64+
const walletData = {
65+
uuid: "350670db-19fa-4704-a166-e52e178b59d2",
66+
name: "Example Wallet",
67+
icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
68+
rdns: "com.example.wallet",
69+
target: [
70+
{
71+
type: "caip341",
72+
value: "abcdefghijklmnopqrstuvwxyzabcdef"
73+
},
74+
{
75+
type: "caip315",
76+
value: true
77+
},
78+
{
79+
type: "caip316",
80+
value: {
81+
somethingElse: "hello"
82+
}
83+
}
84+
],
85+
scopes: {
86+
"eip155:1": {
87+
methods: ["eth_signTransaction", "eth_sendTransaction"],
88+
notifications: ["accountsChanged", "chainChanged"]
89+
}
90+
}
91+
}
92+
```
93+
94+
### Establishing Connection
95+
96+
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.
97+
All subsequent communication with the wallet SHOULD be conducted over the `externally_connectable` API using `runtime.connect()` and `runtime.sendMessage()`.
98+
99+
Example of establishing a connection and sending a message:
100+
101+
```ts
102+
const extensionId = walletData.target.find((entry) => entry.type === 'caip341').value;
103+
const port = chrome.runtime.connect(extensionId);
104+
105+
port.onMessage.addListener((message) => {
106+
// Handle incoming messages
107+
});
108+
109+
port.postMessage({
110+
id: 1,
111+
jsonrpc: "2.0",
112+
method: "wallet_createSession",
113+
params: {
114+
// ... session parameters ...
115+
}
116+
});
117+
```
118+
119+
## Rationale
120+
121+
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.
122+
123+
## Backwards Compatibility
124+
125+
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.
126+
127+
## Links
128+
129+
- [EIP-6963][eip-6963] - Ethereum's Multi Injected Provider Discovery
130+
- [CAIP-294][caip-294] - Browser Wallet Messaging for Extensions
131+
- [externally_connectable API documentation][externally_connectable API documentation] - Chrome's `externally_connectable` browser API documentation
132+
- [Wallet Standard][wallet standard] - Solana's Wallet Standard for discoverability
133+
134+
[eip-6963]: https://eips.ethereum.org/EIPS/eip-6963
135+
[caip-294]: https://chainagnostic.org/CAIPs/caip-294
136+
[externally_connectable API documentation]: https://developer.chrome.com/docs/extensions/reference/manifest/externally-connectable
137+
[wallet standard]: https://github.com/anza-xyz/wallet-standard
138+
139+
## Copyright
140+
Copyright and related rights waived via [CC0](../LICENSE).

0 commit comments

Comments
 (0)