Skip to content

Commit cbc2c10

Browse files
pedrouidpedrouid
authored
Merge pull request #16 from pedrouid/caip25-refresh-alt
CAIP-25: New Schema (with two examples)
2 parents bb001e8 + 07b6ea8 commit cbc2c10

File tree

1 file changed

+194
-96
lines changed

1 file changed

+194
-96
lines changed

‎CAIPs/caip-25.md‎

Lines changed: 194 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ Callers may revoke sessions using `wallet_revokeSession`, passing the `sessionId
4949

5050
Authorization requests are expressed as a top-level object `scopes` containing keyed [scopeObjects][CAIP-217].
5151

52-
Each `scopeObject` is keyed by a [CAIP-2][] chain ID. A null reference can be used to refer to a scope that applies to ANY chain within that namespace (eg. `eip155:0`)
52+
Each `scopeObject` is keyed by a [CAIP-2][] or [CAIP-104][] identifiers. A null reference can be used to refer to a scope that applies to ANY chain within that namespace (eg. `eip155:0`)
5353

5454
Wallets MAY authorize a subset of scopes or scope properties as requested, and MAY also authorize additional scopes or scope properties. This enables granular control and flexibility on the part of the respondent.
5555

@@ -61,61 +61,176 @@ If a connection is rejected, the wallet MAY respond with a generic error or sile
6161

6262
#### Request
6363

64+
```typescript
65+
interface CAIP25JsonRpcRequest {
66+
id: number;
67+
jsonrpc: "2.0";
68+
method: "wallet_createSession";
69+
params: {
70+
scopes: {
71+
[scopeKey: string]: {
72+
chains?: string[];
73+
accounts?: string[];
74+
methods: string[];
75+
notifications: string[];
76+
};
77+
};
78+
properties?: {
79+
[propertyKey: string]: any;
80+
};
81+
};
82+
}
83+
```
84+
85+
The `scopes` object MUST contain one or more scopeObjects.
86+
87+
The `properties` object MAY be included for global session metadata.
88+
89+
### Response
90+
91+
#### Success
92+
93+
```typescript
94+
interface CAIP25JsonRpcResponse {
95+
id: number;
96+
jsonrpc: "2.0";
97+
result: {
98+
scopes: {
99+
[scopeKey: string]: {
100+
chains?: string[];
101+
accounts: string[];
102+
methods: string[];
103+
notifications: string[];
104+
capabilities?: {
105+
[capabilityKey: string]: any;
106+
};
107+
};
108+
};
109+
properties?: {
110+
[propertyKey: string]: any;
111+
};
112+
};
113+
}
114+
```
115+
116+
Each entry within `scopes` object MAY contain `accounts` and `capabilities` as part of its object for success response.
117+
118+
#### Error Codes
119+
120+
The wallet MAY return generic or specific error messages depending on trust. Trusted responses may include codes like:
121+
122+
- `5000`: Unknown error
123+
- `5001`: User disapproved requested methods
124+
- `5002`: User disapproved requested notifications
125+
- `5100-5102`: Unsupported chains, methods, or notifications
126+
- `5201-5302`: Malformed requests
127+
128+
## Examples
129+
130+
**Example 1**
131+
132+
For request, we define a very simple scope for 10 EVM chains with the exact same scope.
133+
64134
```jsonc
135+
// JSON-RPC REQUEST
65136
{
66137
"id": 1,
67138
"jsonrpc": "2.0",
68139
"method": "wallet_createSession",
69140
"params": {
70141
"scopes": {
71-
"wallet": {
72-
"methods": [
73-
"wallet_revokeSession",
74-
"wallet_getSession",
75-
"wallet_authenticate",
76-
"wallet_pay"
142+
"eip155": {
143+
"chains": [
144+
"1",
145+
"10",
146+
"130",
147+
"324",
148+
"2741",
149+
"8453",
150+
"42161",
151+
"59144",
152+
"534352",
153+
"747474"
77154
],
78-
"notifications": ["wallet_sessionChanged"]
79-
},
80-
"wallet:eip155": {
155+
"methods": ["eth_sendTransaction", "personal_sign"],
156+
"notifications": ["accountsChanged", "chainChanged"]
157+
}
158+
},
159+
"properties": {
160+
"expiry": "2022-12-24T17:07:31+00:00"
161+
}
162+
}
163+
}
164+
```
165+
166+
For response, we also keep it quite simple with no wallet capabilities or special scopes.
167+
168+
```jsonc
169+
// JSON-RPC RESPONSE
170+
{
171+
"id": 1,
172+
"jsonrpc": "2.0",
173+
"result": {
174+
"scopes": {
175+
"eip155": {
176+
"chains": [
177+
"1",
178+
"10",
179+
"130",
180+
"324",
181+
"2741",
182+
"8453",
183+
"42161",
184+
"59144",
185+
"534352",
186+
"747474"
187+
],
188+
"accounts": ["0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"],
189+
"methods": ["eth_sendTransaction", "personal_sign"],
190+
"notifications": ["accountsChanged", "chainChanged"]
191+
}
192+
},
193+
"properties": {
194+
"expiry": "2022-12-24T17:07:31+00:00"
195+
}
196+
}
197+
}
198+
```
199+
200+
**Example 2**
201+
202+
For the request, we define the expectation of 5 EVM chains with similar scope and additonally we have 2 Solana chains with similar scope
203+
204+
```jsonc
205+
// JSON-RPC REQUEST
206+
{
207+
"id": 1,
208+
"jsonrpc": "2.0",
209+
"method": "wallet_createSession",
210+
"params": {
211+
"scopes": {
212+
"eip155": {
213+
"chains": ["1", "10", "324", "8453", "42161"],
81214
"methods": [
215+
"eth_sendTransaction",
82216
"personal_sign",
83217
"wallet_grantPermissions",
84-
"wallet_getAssets"
218+
"wallet_getAssets",
219+
"wallet_sendCalls"
85220
],
86-
"notifications": []
87-
},
88-
"eip155": {
89-
"methods": ["eth_sendTransaction"],
90221
"notifications": ["accountsChanged", "chainChanged"]
91222
},
92-
"eip155:1": {
93-
"methods": [],
94-
"notifications": []
95-
},
96-
"eip155:8453": {
97-
"methods": ["wallet_sendCalls"],
98-
"notifications": []
99-
},
100-
"eip155:42161": {
101-
"methods": ["wallet_sendCalls"],
102-
"notifications": []
103-
},
104223
"solana": {
224+
"chains": [
225+
"5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
226+
"4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z"
227+
],
105228
"methods": [
106229
"solana_signMessage",
107230
"solana_signTransaction",
108231
"solana_signAndSendTransaction"
109232
],
110233
"notifications": []
111-
},
112-
"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": {
113-
"methods": [],
114-
"notifications": []
115-
},
116-
"solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z": {
117-
"methods": [],
118-
"notifications": []
119234
}
120235
},
121236
"properties": {
@@ -125,70 +240,65 @@ If a connection is rejected, the wallet MAY respond with a generic error or sile
125240
}
126241
```
127242

128-
The `scopes` object MUST contain one or more scopeObjects.
243+
For the response, we match the same scopes as the request but separate 2 out of 5 EVM chains into individual scopes because of non-overlapping accounts, capabilities or methods.
129244

130-
The `properties` object MAY be included for global session metadata.
131-
132-
### Response
245+
Additionaly we have the two Solana chains returning the same scopes but returning two different account addresses for each chain including a unique capability for one of the chains
133246

134-
#### Success
247+
Finally the wallet has provided within properties with its walletInfo per [CAIP-372][].
135248

136249
```jsonc
250+
// JSON-RPC RESPONSE
137251
{
138252
"id": 1,
139253
"jsonrpc": "2.0",
140254
"result": {
141255
"sessionId": "0xdeadbeef",
142256
"scopes": {
143-
"wallet": {
144-
"accounts": [],
145-
"methods": [
146-
"wallet_revokeSession",
147-
"wallet_getSession",
148-
"wallet_authenticate",
149-
"wallet_pay"
150-
],
151-
"notifications": ["wallet_sessionChanged"],
152-
"capabilities": {}
153-
},
154-
"wallet:eip155": {
155-
"accounts": [],
257+
"eip155": {
258+
"chains": ["1", "10", "324"],
259+
"accounts": ["0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"],
156260
"methods": [
261+
"eth_sendTransaction",
157262
"personal_sign",
263+
"wallet_addEthereumChain",
158264
"wallet_grantPermissions",
159-
"wallet_getAssets"
265+
"wallet_getAssets",
266+
"wallet_sendCalls"
160267
],
161-
"notifications": [],
268+
"notifications": ["accountsChanged", "chainChanged"],
162269
"capabilities": {
163270
"walletService": "https://wallet-service.example.com/rpc"
164271
}
165272
},
166-
"eip155": {
273+
"eip155:8453": {
167274
"accounts": ["0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"],
168-
"methods": ["eth_sendTransaction"],
275+
"methods": [
276+
"eth_sendTransaction",
277+
"personal_sign",
278+
"wallet_grantPermissions",
279+
"wallet_getAssets",
280+
"wallet_sendCalls"
281+
],
169282
"notifications": ["accountsChanged", "chainChanged"],
170-
"capabilities": {}
171-
},
172-
"eip155:1": {
173-
"accounts": [],
174-
"methods": [],
175-
"notifications": [],
176-
"capabilities": {}
177-
},
178-
"eip155:8453": {
179-
"accounts": [],
180-
"methods": ["wallet_sendCalls"],
181-
"notifications": [],
182283
"capabilities": {
183284
"atomic": {
184285
"status": "supported"
185286
}
186287
}
187288
},
188289
"eip155:42161": {
189-
"accounts": ["0x0495766cD136138Fc492Dd499B8DC87A92D6685b"],
190-
"methods": ["wallet_sendCalls"],
191-
"notifications": [],
290+
"accounts": [
291+
"0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb",
292+
"0x0495766cD136138Fc492Dd499B8DC87A92D6685b"
293+
],
294+
"methods": [
295+
"eth_sendTransaction",
296+
"personal_sign",
297+
"wallet_grantPermissions",
298+
"wallet_getAssets",
299+
"wallet_sendCalls"
300+
],
301+
"notifications": ["accountsChanged", "chainChanged"],
192302
"capabilities": {
193303
"atomic": {
194304
"status": "supported"
@@ -199,7 +309,7 @@ The `properties` object MAY be included for global session metadata.
199309
}
200310
}
201311
},
202-
"solana": {
312+
"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": {
203313
"accounts": [],
204314
"methods": [
205315
"solana_signMessage",
@@ -208,22 +318,20 @@ The `properties` object MAY be included for global session metadata.
208318
],
209319
"notifications": [],
210320
"capabilities": {
211-
"supportedTransactionVersions": ["legacy"]
212-
}
213-
},
214-
"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": {
215-
"accounts": ["7S3P4HxJpyyigGzodYwHtCxZyUQe9JiBMHyRWXArAaKv"],
216-
"methods": [],
217-
"notifications": [],
218-
"capabilities": {
219-
"supportedTransactionVersions": ["0"]
321+
"supportedTransactionVersions": ["legacy", "0"]
220322
}
221323
},
222324
"solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z": {
223325
"accounts": ["6LmSRCiu3z6NCSpF19oz1pHXkYkN4jWbj9K1nVELpDkT"],
224-
"methods": [],
326+
"methods": [
327+
"solana_signMessage",
328+
"solana_signTransaction",
329+
"solana_signAndSendTransaction"
330+
],
225331
"notifications": [],
226-
"capabilities": {}
332+
"capabilities": {
333+
"supportedTransactionVersions": ["legacy"]
334+
}
227335
}
228336
},
229337
"properties": {
@@ -239,18 +347,6 @@ The `properties` object MAY be included for global session metadata.
239347
}
240348
```
241349

242-
Each entry within `scopes` object MAY contain `accounts` and `capabilities` as part of its object for success response.
243-
244-
#### Error Codes
245-
246-
The wallet MAY return generic or specific error messages depending on trust. Trusted responses may include codes like:
247-
248-
- `5000`: Unknown error
249-
- `5001`: User disapproved requested methods
250-
- `5002`: User disapproved requested notifications
251-
- `5100-5102`: Unsupported chains, methods, or notifications
252-
- `5201-5302`: Malformed requests
253-
254350
## Security Considerations
255351

256352
To avoid ambiguity in authorizations, `scopes` MUST retain their original keyed structure using [CAIP-2][] or [CAIP-104][] identifiers. This ensures clarity in what is authorized and prevents accidental scope merging or misinterpretation.
@@ -283,6 +379,7 @@ To mitigate fingerprinting risks, wallets should prefer uniform or silent failur
283379
- [CAIP-312][] - `wallet_getSession` Specification
284380
- [CAIP-311][] - `wallet_sessionChanged` Specification
285381
- [CAIP-316][] - Session Lifecycle Management equivalence chart and diagrams
382+
- [CAIP-372][] - Wallet Information Metadata Standard
286383
- [RFC-2119][] - Key words for use in RFCs to Indicate Requirement Levels
287384

288385
[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2
@@ -294,6 +391,7 @@ To mitigate fingerprinting risks, wallets should prefer uniform or silent failur
294391
[CAIP-312]: https://chainagnostic.org/CAIPs/CAIP-312
295392
[CAIP-311]: https://chainagnostic.org/CAIPs/CAIP-311
296393
[CAIP-316]: https://chainagnostic.org/CAIPs/caip-316
394+
[CAIP-372]: https://chainagnostic.org/CAIPs/caip-372
297395
[RFC-2119]: https://datatracker.ietf.org/doc/html/rfc2119
298396

299397
## Copyright

0 commit comments

Comments
 (0)