From f3bbafb3deaae6538cc416206ca3e4dcdc991b5e Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Thu, 2 Feb 2023 08:39:57 +0100 Subject: [PATCH 01/13] define caip25 extensibility and caip207 core syntax --- CAIPs/caip-207.md | 236 ++++++++++++++++++++++++++++++++++++++++++++++ CAIPs/caip-25.md | 31 ++++-- 2 files changed, 260 insertions(+), 7 deletions(-) create mode 100644 CAIPs/caip-207.md diff --git a/CAIPs/caip-207.md b/CAIPs/caip-207.md new file mode 100644 index 00000000..fa9c2cf1 --- /dev/null +++ b/CAIPs/caip-207.md @@ -0,0 +1,236 @@ +--- +caip: 207 +title: JSON-RPC Authority Negotiation +author: Pedro Gomes (@pedrouid), Hassan Malik (@hmalik88) +discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/207 +status: Draft +type: Standard +created: 2023-02-02 +updated: 2023-02-02 +requires: [2, 10, 25, 171] +--- + +## Simple Summary + +CAIP-207 extends CAIP-25 to allow callers and respondents to negotiate RPC +authorities and RPC semantics before authorizing RPC terms. + +## Abstract + +CAIP-207 defines additional properties that CAIP-25 can be used +iteratively/progressively to layer custom or local RPC semantics and/or routing +onto a session. Since CAIP-25 respondents ignore unknown properties, respondents +that conform to CAIP-25 but not to CAIP-207 should be carefully considered and +accomodated by implementers. + +## Motivation + +While some core methods and notifications are foundational to a namespace and +universally defined out-of-band (meaning all callers and respondents agree to +them already), others are specific to chains or even to subsets of wallets and +dapps on a given chain, which requires semantic negotiation and/or network +routing negotiation before authorization can occur. + +## Specification + +Two properties are added to the scope objects requested in `optionalScopes` and +optionally returned in `sessionScopes`. These are both [ordered] strings of arrays: + +1. `rpcEndpoints` is an array of zero or more URLs of RPC endpoints that + the caller would prefer the respondent to use, ordered by preference. Each + must be a valid URL that addresses an RPC endpoint. The respondent may + return it empty, reordered, with less, the same, or even more conformant URLs + than received. +2. `rpcDocuments` is an array of zero or more URLs of machine-readable RPC + documents that the caller would prefer the respondent to use, ordered by + preference. This set of document collectively defines at least syntactically + if not also semantically any methods and/or notifications authorized by the + CAIP-25 authorization, in DESCENDING heirarchical authority. (For example, + any methods or notifications defined differently by multiple authorites will + be interpreted by whichever authority is closer to the 0-index of the array). + Each must be a valid URL that addresses a valid openRPC document. The + respondent may return it empty, reordered, with less, the same, or even more + conformant URLs than received. + +### Request + +A CAIP-207 request is a valid CAIP-25 except for the two additional properties. + +Example: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "method": "provider_authorization", + "params": { + "requiredScopes": { + "eip155": { + "chains": ["eip155:1", "eip155:137"], + "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"], + "notifications": ["accountsChanged", "chainChanged"] + }, + "eip155:42069": { + "methods": ["get_balance", "chainChanged", "42069_sEcReTbAlAnCe"], + "rpcDocuments": ["https://openrpc.42069-chain.org/"], + "rpcEndpoints": ["https://node1.42069-chain.org/"] + }, + "cosmos": { + ... + } + }, + "optionalScopes":{ + "eip155:42161": { + "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"], + "events": ["accountsChanged", "chainChanged"] + }, + "sessionProperties": { + "expiry": "2022-12-24T17:07:31+00:00", + "caip154-mandatory": "true" + } + } +} +``` + +### Response + +The wallet can respond to this method with either a success result or an error message. + +#### Success + +A succesful result will be a conformant successful result according to +[CAIP-25][], with the additional presence (if authorized) of the new properties +in one or more scope objects. + +An example of a successful response follows: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "sessionId": "0xdeadbeef", + "sessionScopes": { + "eip155": { + "chains": ["eip155:1", "eip155:137"], + "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "eth_sign", "personal_sign"] + "events": ["accountsChanged", "chainChanged"], + "accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb", "eip155:137:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"] + }, + "eip155:10": { + "methods": ["get_balance"], + "events": ["accountsChanged", "chainChanged"], + "accounts:" [] + }, + "eip155:42069": { + "methods": ["get_balance", "chainChanged", "42069_sEcReTbAlAnCe"], + "rpcDocuments": ["https://openrpc.42069-chain.org/"], + "rpcEndpoints": ["https://node1.42069-chain.org/"] + } + //... + }, + "sessionProperties": { + "expiry": "2022-11-31T17:07:31+00:00" + } + } +} +``` + +#### Failure States + +##### TODO: + +An example of an error response should match the following format: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "error": { + "code": 5000, + "message": "Unknown error" + } +} +``` + +The additional error messages codes to be supported in addition to CAIP-25s are the following: + +##### TODO: replace following with novel errors + +Possible error messages (to be discussed with WG): +- rpcDocuments not conformant syntactically (not openRPC, not served as mime type JSON, etc) + +Are these error messages required at protocol level or are they implementation-specific? +- rpcDocuments rejected by user input +- rpcDocuments rejected by policy/in principle +- rpcDocuments unreachable/404 +- rpcEndpoints rejected by user input +- rpcEndpoints rejected by policy/in principle +- rpcEndpoints unreachable/404 +- rpcEndpoints URL malformed + +* Unknown error OR no requested scopes were authorized + * code = 5000 + * message = "Unknown error" +* When user disapproves accepting calls with the request methods + * code = 5001 + * message = "User disapproved requested methods" +* When user disapproves accepting calls with the request events + * code = 5002 + * message = "User disapproved requested events" +* When wallet evaluates requested chains to not be supported + * code = 5100 + * message = "Requested chains are not supported" +* When wallet evaluates requested methods to not be supported + * code = 5101 + * message = "Requested methods are not supported" +* When wallet evaluates requested events to not be supported + * code = 5102 + * message = "Requested events are not supported" +* When a badly-formed request includes a `chainId` mismatched to scope + * code = 5103 + * message = "Scope/chain mismatch" +* When a badly-formed request defines one `chainId` two ways + * code = 5104 + * message = "ChainId defined in two different scopes" +* Invalid Session Properties Object + * code = 5200 + * message = "Invalid Session Properties requested" +* Session Properties requested outside of Session Properties Object + * code = 5201 + * message = "Session Properties can only be optional and global" + +## Security Considerations + +##### TODO +- what happens if wallet reorders Documents and dapp ignores that? should we + make more explicit how important the ordering of those arrays is, and that + neither party can guarantee how the other is ordering them? + +## Privacy Considerations + +##### TODO + +## Changelog + +## Links + +- [CAIP-2][] - Chain ID Specification +- [CAIP-10][] - Account ID Specification +- [CAIP-25][] - JSON-RPC Provider Request +- [CAIP-75][] - Blockchain Reference for the Hedera namespace +- [CAIP-171][] - Session Identifier Specification + +[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 +[CAIP-10]: https://chainagnostic.org/CAIPs/caip-10 +[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25 +[CAIP-75]: https://chainagnostic.org/CAIPs/caip-75 +[CAIP-104]: https://chainagnostic.org/CAIPs/caip-104 +[CAIP-171]: https://chainagnostic.org/CAIPs/caip-171 +[namespaces]: https://namespaces.chainagnostic.org +[RFC3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 +[CAIP-170]: https://chainagnostic.org/CAIPs/caip-170 + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE). \ No newline at end of file diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index 6f91afb1..4355ddd9 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -6,8 +6,8 @@ discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/25 status: Last Call type: Standard created: 2020-10-14 -updated: 2022-10-26 -requires: [2, 10, 171] +updated: 2023-02-02 +requires: [2, 10, 25, 171] --- ## Simple Summary @@ -157,7 +157,7 @@ The wallet can respond to this method with either a success result or an error m #### Success -The succesfull reslt contains one mandatory string (keyed as `sessionId` with a value +The succesfull result contains one mandatory string (keyed as `sessionId` with a value conformant to [CAIP-171][]) and two session objects, both mandatory and non-empty. The first is called `sessionScopes` and contains 1 or more scope objects. @@ -214,10 +214,12 @@ An example of a successful response follows: #### Failure States -The response MUST NOT be a success result when the user disapproves the accounts -matching the requested chains to be exposed or the requested methods are not -approved or the requested chains are not supported by the wallet or the -requested methods are not supported. +The response MUST NOT be a success result if any of the following conditions are met: +- the user disapproves the accounts matching the requested chains to be exposed +- requested methods are not approved +- the requested chains are not supported by the wallet +- the requested methods are not supported by the wallet +- there is anything malformed about the request An example of an error response should match the following format: @@ -264,6 +266,17 @@ The valid error messages codes are the following: * code = 5201 * message = "Session Properties can only be optional and global" +## Extensibility and Additional Properties + +Any other properties present in a request MUST be ignored by respondents, UNLESS +they are defined by an extension specification to CAIP-25 (such as, for example, +the methods defined in [CAIP-169][]). Since unsuccesful authorizations return +nothing, it is recommended that requests for potentially unstable or +authority-specific terms be handled progressively, i.e., requesting initial +authorization or feature discovery first, then negotiating authorities on any +local or versioned authorization terms (using, for example, [CAIP-207][]), and +only then requesting authorization of those terms. + ## Security Considerations The crucial security function of a shared session negotiated and maintained by a @@ -329,13 +342,17 @@ was in violation of policy). - [CAIP-25][] - JSON-RPC Provider Request - [CAIP-75][] - Blockchain Reference for the Hedera namespace - [CAIP-171][] - Session Identifier Specification +- [CAIP-207][] - Extension to CAIP-25 that enables explicit negotiation of RPC + authorities and semantics [CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 [CAIP-10]: https://chainagnostic.org/CAIPs/caip-10 [CAIP-25]: https://chainagnostic.org/CAIPs/caip-25 [CAIP-75]: https://chainagnostic.org/CAIPs/caip-75 [CAIP-104]: https://chainagnostic.org/CAIPs/caip-104 +[CAIP-169]: https://chainagnostic.org/CAIPs/caip-169 [CAIP-171]: https://chainagnostic.org/CAIPs/caip-171 +[CAIP-207]: https://chainagnostic.org/CAIPs/caip-207 [namespaces]: https://namespaces.chainagnostic.org [RFC3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 [CAIP-170]: https://chainagnostic.org/CAIPs/caip-170 From efb9ee7ba9958a93a85d94b410b2080fea1ce935 Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Thu, 2 Feb 2023 08:44:42 +0100 Subject: [PATCH 02/13] rollback Last Call status --- CAIPs/caip-25.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index 4355ddd9..54c76dc2 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -3,7 +3,7 @@ caip: 25 title: JSON-RPC Provider Authorization author: Pedro Gomes (@pedrouid), Hassan Malik (@hmalik88) discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/25 -status: Last Call +status: Review type: Standard created: 2020-10-14 updated: 2023-02-02 From 2016fa6cd01b1cd8c790407af7d9919d433fde33 Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Tue, 7 Feb 2023 12:03:29 +0100 Subject: [PATCH 03/13] General editorial cleanup thanks @kdenhartog --- CAIPs/{caip-207.md => caip-211.md} | 31 ++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) rename CAIPs/{caip-207.md => caip-211.md} (86%) diff --git a/CAIPs/caip-207.md b/CAIPs/caip-211.md similarity index 86% rename from CAIPs/caip-207.md rename to CAIPs/caip-211.md index fa9c2cf1..cd536c16 100644 --- a/CAIPs/caip-207.md +++ b/CAIPs/caip-211.md @@ -1,5 +1,5 @@ --- -caip: 207 +caip: 211 title: JSON-RPC Authority Negotiation author: Pedro Gomes (@pedrouid), Hassan Malik (@hmalik88) discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/207 @@ -12,24 +12,27 @@ requires: [2, 10, 25, 171] ## Simple Summary -CAIP-207 extends CAIP-25 to allow callers and respondents to negotiate RPC -authorities and RPC semantics before authorizing RPC terms. +CAIP-211 extends CAIP-25 to allow callers and respondents to anchor feature +discovery in specific RPC semantics and to request the respondent route requests +to specific RPC endpoints. ## Abstract -CAIP-207 defines additional properties that CAIP-25 can be used -iteratively/progressively to layer custom or local RPC semantics and/or routing -onto a session. Since CAIP-25 respondents ignore unknown properties, respondents -that conform to CAIP-25 but not to CAIP-207 should be carefully considered and -accomodated by implementers. +CAIP-211 defines additional properties that enable progressive usage of CAIP-25 +to layer custom or local RPC semantics and/or routing onto a session. Since +CAIP-25 respondents ignore unknown properties, respondents that conform to +CAIP-25 but not to CAIP-211 should be carefully considered and accomodated by +implementers. ## Motivation -While some core methods and notifications are foundational to a namespace and -universally defined out-of-band (meaning all callers and respondents agree to -them already), others are specific to chains or even to subsets of wallets and -dapps on a given chain, which requires semantic negotiation and/or network -routing negotiation before authorization can occur. +While some core methods and notifications are foundational to entire namespaces +and thus almost universally defined out-of-band (meaning all callers and +respondents agree to them already), others are specific to chains or even to +subsets of wallets and dapps on a given chain. This requires scope objects in +CAIP-25 requests to negotation semantic anchors and/or network routing +**before** authorization can occur in the confidence that both parties agree to +the syntax and semantics of a given chain or notification. ## Specification @@ -54,7 +57,7 @@ optionally returned in `sessionScopes`. These are both [ordered] strings of arr ### Request -A CAIP-207 request is a valid CAIP-25 except for the two additional properties. +A CAIP-211 request is a valid CAIP-25 except for the two additional properties. Example: From 8703b014734361eccf3bb41cfbd9283b641f6f3a Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Tue, 7 Feb 2023 12:22:57 +0100 Subject: [PATCH 04/13] More explicit semantics & pPrivacy consid cc @kdenhartog --- CAIPs/caip-211.md | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/CAIPs/caip-211.md b/CAIPs/caip-211.md index cd536c16..d166fe46 100644 --- a/CAIPs/caip-211.md +++ b/CAIPs/caip-211.md @@ -32,7 +32,22 @@ respondents agree to them already), others are specific to chains or even to subsets of wallets and dapps on a given chain. This requires scope objects in CAIP-25 requests to negotation semantic anchors and/or network routing **before** authorization can occur in the confidence that both parties agree to -the syntax and semantics of a given chain or notification. +the syntax and semantics of a given method or notification, which may only be +available on certain RPC endpoints. + +The concept of a custom RPC endpoint or definition presumes the existence of +"default" or universal endpoints and definitions, which can be hard to anchor in +explicit specifications unless a namespace profile of this CAIP has been +published. (This may be unnecessary in the case of younger namespaces without +customization built in at the per-chain or per-dapp layer). An empty array of +`rpcEndpoints` or `rpcDocuments` sent in either direction should be interpreted +differently than the absence of the array. Namely, either array being present +but empty in a request signals that a caller is requesting that custom endpoints +or definitions NOT be considered in CAIP-25 authorizations. Present but empty +arrays in a response confirms this behavior, while its absence can be taken to +mean the wallet either does not support custom endpoints/definitions or the user +has opted out of that degree of trust, which for privacy/fingerprinting reasons, +should not be handled by distinct codepaths (See Privacy Considerations). ## Specification @@ -164,10 +179,12 @@ Possible error messages (to be discussed with WG): - rpcDocuments not conformant syntactically (not openRPC, not served as mime type JSON, etc) Are these error messages required at protocol level or are they implementation-specific? -- rpcDocuments rejected by user input +- ~~rpcDocuments rejected by user input OR wallet does not support custom RPC documents~~ + - ^ no response in either case - rpcDocuments rejected by policy/in principle - rpcDocuments unreachable/404 -- rpcEndpoints rejected by user input +- ~~rpcEndpoints rejected by user input OR wallet does not support custom RPC documents~~ + - ^ no response in either case - rpcEndpoints rejected by policy/in principle - rpcEndpoints unreachable/404 - rpcEndpoints URL malformed @@ -212,6 +229,16 @@ Are these error messages required at protocol level or are they implementation-s ## Privacy Considerations +The trust model of custom RPC endpoints and/or definition documents is complex +and reputation/discovery systems are still emerging on a per-chain basis in many +ecosystems. For this reason, iterations of CAIP-25 should be considered a +delicate negotiation best done progressively to avoid malicious dapps partially +deanonymizing wallets by profiling their support for custom RPCs (i.e. +overasking). For this reason, as with the initial CAIP-25 exchange, discovery +requests rejected due to user input, due to security policy, and due to +non-support at the wallet software level should not be distinguished as the RPC +level. + ##### TODO ## Changelog From 1729b1bb164e630183acc9852bf3ba20eca517c5 Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Tue, 7 Feb 2023 16:47:57 +0100 Subject: [PATCH 05/13] More explicit example of rpcDocuments ordinality --- CAIPs/caip-211.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/CAIPs/caip-211.md b/CAIPs/caip-211.md index d166fe46..47cf711e 100644 --- a/CAIPs/caip-211.md +++ b/CAIPs/caip-211.md @@ -90,7 +90,7 @@ Example: }, "eip155:42069": { "methods": ["get_balance", "chainChanged", "42069_sEcReTbAlAnCe"], - "rpcDocuments": ["https://openrpc.42069-chain.org/"], + "rpcDocuments": ["https://openrpc.42069-chain.org/", "https://ethereum.github.io/execution-apis/api-documentation/"], "rpcEndpoints": ["https://node1.42069-chain.org/"] }, "cosmos": { @@ -142,7 +142,7 @@ An example of a successful response follows: }, "eip155:42069": { "methods": ["get_balance", "chainChanged", "42069_sEcReTbAlAnCe"], - "rpcDocuments": ["https://openrpc.42069-chain.org/"], + "rpcDocuments": ["https://ethereum.github.io/execution-apis/api-documentation/", "https://openrpc.42069-chain.org/"], "rpcEndpoints": ["https://node1.42069-chain.org/"] } //... @@ -154,6 +154,15 @@ An example of a successful response follows: } ``` +Note: +* The response re-ordered the RPC documents array, which still allows the + 42069-chain docs to define new methods such as the namespaced secret-balance + method example. However, since the ordinality of the array prioritizes earlier + authorities in any case where two define the same term, the chain-specific + authority is effectively prevented from redefining any methods defined in the + eip155-wide standard, even in the limited scope of the 42069 chain. This is + purely for illustrative purposes and not normative. + #### Failure States ##### TODO: From ff0e0f2b218ad4b9c9eace6c1cc2504d3ea33944 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Tue, 7 Feb 2023 17:57:07 +0100 Subject: [PATCH 06/13] Update CAIPs/caip-211.md --- CAIPs/caip-211.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CAIPs/caip-211.md b/CAIPs/caip-211.md index 47cf711e..4e6170d4 100644 --- a/CAIPs/caip-211.md +++ b/CAIPs/caip-211.md @@ -90,7 +90,7 @@ Example: }, "eip155:42069": { "methods": ["get_balance", "chainChanged", "42069_sEcReTbAlAnCe"], - "rpcDocuments": ["https://openrpc.42069-chain.org/", "https://ethereum.github.io/execution-apis/api-documentation/"], + "rpcDocuments": ["https://openrpc.42069-chain.org/", "https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json"], "rpcEndpoints": ["https://node1.42069-chain.org/"] }, "cosmos": { From ececfab6e957dd5102122adf1967d45874cf18ca Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Tue, 7 Feb 2023 17:58:06 +0100 Subject: [PATCH 07/13] Update CAIPs/caip-211.md --- CAIPs/caip-211.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CAIPs/caip-211.md b/CAIPs/caip-211.md index 4e6170d4..c2ec4616 100644 --- a/CAIPs/caip-211.md +++ b/CAIPs/caip-211.md @@ -142,7 +142,7 @@ An example of a successful response follows: }, "eip155:42069": { "methods": ["get_balance", "chainChanged", "42069_sEcReTbAlAnCe"], - "rpcDocuments": ["https://ethereum.github.io/execution-apis/api-documentation/", "https://openrpc.42069-chain.org/"], + "rpcDocuments": ["https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json", "https://openrpc.42069-chain.org/"], "rpcEndpoints": ["https://node1.42069-chain.org/"] } //... From 7d379d15e051842258984e6f97052b84b9bd7e00 Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Fri, 10 Feb 2023 15:14:01 +0100 Subject: [PATCH 08/13] to add duplicate-scope example and wallet scope --- CAIPs/caip-25.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index 54c76dc2..ed64436a 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -98,7 +98,7 @@ Example: "requiredScopes": { "eip155": { "chains": ["eip155:1", "eip155:137"], - "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"], + "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"], "events": ["accountsChanged", "chainChanged"] }, "eip155:10": { @@ -110,9 +110,16 @@ Example: } }, "optionalScopes":{ + "eip155": { + "methods": ["eth_sign","eth_signTypedData","eth_signTypedData_v3","eth_signTypedData_v4","wallet_switchEthereumChain","wallet_addEthereumChain"] + }, "eip155:42161": { "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"], "events": ["accountsChanged", "chainChanged"] + }, + "wallet" { + "method": ["creds_present", "creds_store"] + } }, "sessionProperties": { "expiry": "2022-12-24T17:07:31+00:00", @@ -138,6 +145,14 @@ Each scope object contains the following parameters: The `requiredScopes` array MUST contain 1 or more of these objects, if present; the `optionalScopes` array MUST contain 1 or more of them, if present. +There is one special-case scope object, named `wallet`, which refers to methods +and events independent of any namespace but, crucially, no chains or CASA +namespaces. This off-chain scope objects exists for callers and respondents to +negotiate support for chain-agnostic primitives like W3C decentralized +identifiers, W3C Verifiable Credentials, JWTs, IPFS, webCrypto, and other +cryptographic standards. At time or writing, the only CAIP that specifies +`wallet` methods so far is [CAIP-169][], although others may be in progress. + A third object is the `sessionProperties` object, all of whose properties MUST be in the interpreted as optional, since requesting applications cannot mandate session variables to providers. Because they are optional, providers MAY respond @@ -188,7 +203,7 @@ An example of a successful response follows: "sessionScopes": { "eip155": { "chains": ["eip155:1", "eip155:137"], - "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "eth_sign", "personal_sign"] + "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "eth_sign", "personal_sign", "eth_signTypedData_v4", "wallet_switchEthereumChain"] "events": ["accountsChanged", "chainChanged"], "accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb", "eip155:137:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"] }, @@ -201,6 +216,7 @@ An example of a successful response follows: "methods": ["personal_sign"], "events": ["accountsChanged", "chainChanged"], "accounts":["eip155:42161:0x0910e12C68d02B561a34569E1367c9AAb42bd810"] + }, "cosmos": { ... } From abf99617f27dc962154deb03c5e6603eadbc3a5e Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Fri, 17 Feb 2023 08:20:11 -0800 Subject: [PATCH 09/13] typo Co-authored-by: Hassan Malik <41640681+hmalik88@users.noreply.github.com> --- CAIPs/caip-211.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CAIPs/caip-211.md b/CAIPs/caip-211.md index c2ec4616..cc280965 100644 --- a/CAIPs/caip-211.md +++ b/CAIPs/caip-211.md @@ -30,7 +30,7 @@ While some core methods and notifications are foundational to entire namespaces and thus almost universally defined out-of-band (meaning all callers and respondents agree to them already), others are specific to chains or even to subsets of wallets and dapps on a given chain. This requires scope objects in -CAIP-25 requests to negotation semantic anchors and/or network routing +CAIP-25 requests to negotiate semantic anchors and/or network routing **before** authorization can occur in the confidence that both parties agree to the syntax and semantics of a given method or notification, which may only be available on certain RPC endpoints. From c78fb024ef840acc6b20fa33d0ec84c19e6972c2 Mon Sep 17 00:00:00 2001 From: By_caballero Date: Fri, 17 Feb 2023 18:16:46 +0100 Subject: [PATCH 10/13] nuance success response syntax for wallet obj --- CAIPs/caip-25.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index ed64436a..bf160a4f 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -146,12 +146,12 @@ The `requiredScopes` array MUST contain 1 or more of these objects, if present; the `optionalScopes` array MUST contain 1 or more of them, if present. There is one special-case scope object, named `wallet`, which refers to methods -and events independent of any namespace but, crucially, no chains or CASA -namespaces. This off-chain scope objects exists for callers and respondents to -negotiate support for chain-agnostic primitives like W3C decentralized -identifiers, W3C Verifiable Credentials, JWTs, IPFS, webCrypto, and other -cryptographic standards. At time or writing, the only CAIP that specifies -`wallet` methods so far is [CAIP-169][], although others may be in progress. +and events independent of CASA namespace. This off-chain scope objects exists +for callers and respondents to negotiate support for chain-agnostic primitives +like W3C decentralized identifiers, W3C Verifiable Credentials, JWTs, IPFS, +webCrypto, and other cryptographic standards. At time or writing, the only CAIP +that specifies `wallet` methods so far is [CAIP-169][], although others may be +in progress. A third object is the `sessionProperties` object, all of whose properties MUST be in the interpreted as optional, since requesting applications cannot mandate @@ -177,15 +177,16 @@ conformant to [CAIP-171][]) and two session objects, both mandatory and non-empt The first is called `sessionScopes` and contains 1 or more scope objects. * All required scope objects and all, none, or some of the optional scope object -(at the discretion of the provider) MUST be included if successful. -* As in the request, each scope object object MUST contain `methods` and -`events` objects, and a `chains` object if a specific chain is not specified in -the object's index. -* Unlike the request, each scope object MUST also contain an `accounts` array, -containing 0 or more [CAIP-10][] conformant accounts authorized for the session -and valid in the namespace and chain(s) authorized by the scope object they are -in. Additional constraints on the accounts authorized for a given session MAY be -specified in the corresponding [CAIP-104][] namespaces specification. + (at the discretion of the provider) MUST be included if successful. +* With the exception of the special `wallet` scope object, each scope object + MUST contain `methods` and `events` objects. If the object is not scoped to a + specific chain, it should also have a `chains` object. +* Even if unspecified in the request, each non-wallet scope object MUST also + contain an `accounts` array, containing 0 or more [CAIP-10][] conformant + accounts authorized for the session and valid in the namespace and chain(s) + authorized by the scope object they are in. Additional constraints on the + accounts authorized for a given session MAY be specified in the corresponding + [CAIP-104][] namespaces specification. A `sessionProperties` object MAY also be present, and its contents MAY correspond to the properties requested in the response or not (at the discretion From 32b38a71ecb1ed582b1a5425be601b49228aeb1e Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Sun, 19 Feb 2023 07:01:35 -0800 Subject: [PATCH 11/13] Update CAIPs/caip-211.md Co-authored-by: Hassan Malik <41640681+hmalik88@users.noreply.github.com> --- CAIPs/caip-211.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CAIPs/caip-211.md b/CAIPs/caip-211.md index cc280965..59f5f6ed 100644 --- a/CAIPs/caip-211.md +++ b/CAIPs/caip-211.md @@ -59,7 +59,7 @@ optionally returned in `sessionScopes`. These are both [ordered] strings of arr must be a valid URL that addresses an RPC endpoint. The respondent may return it empty, reordered, with less, the same, or even more conformant URLs than received. -2. `rpcDocuments` is an array of zero or more URLs of machine-readable RPC +2. `rpcDocuments` is an array of zero or more URLs of machine-readable OpenRPC documents that the caller would prefer the respondent to use, ordered by preference. This set of document collectively defines at least syntactically if not also semantically any methods and/or notifications authorized by the From f91abb189234dc4ae0733dfcfb266396ebbfc231 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Sun, 19 Feb 2023 07:04:25 -0800 Subject: [PATCH 12/13] Explicitly say can be in optional or requiredscope --- CAIPs/caip-211.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CAIPs/caip-211.md b/CAIPs/caip-211.md index 59f5f6ed..ce3b5076 100644 --- a/CAIPs/caip-211.md +++ b/CAIPs/caip-211.md @@ -51,8 +51,9 @@ should not be handled by distinct codepaths (See Privacy Considerations). ## Specification -Two properties are added to the scope objects requested in `optionalScopes` and -optionally returned in `sessionScopes`. These are both [ordered] strings of arrays: +CAIP-211 adds two properties, either of which can be set in `requiredScopes` or +in `optionalScopes` and, if authorized, optionally returned in `sessionScopes`. +These are both [ordered] strings of arrays: 1. `rpcEndpoints` is an array of zero or more URLs of RPC endpoints that the caller would prefer the respondent to use, ordered by preference. Each @@ -272,4 +273,4 @@ level. ## Copyright -Copyright and related rights waived via [CC0](../LICENSE). \ No newline at end of file +Copyright and related rights waived via [CC0](../LICENSE). From 2c1394e2257bc2d3df12947eacfc469a1e4a5e9b Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Wed, 15 Mar 2023 14:36:01 +0100 Subject: [PATCH 13/13] to clarify rpcDocuments def --- CAIPs/caip-211.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CAIPs/caip-211.md b/CAIPs/caip-211.md index ce3b5076..aaa6b4ad 100644 --- a/CAIPs/caip-211.md +++ b/CAIPs/caip-211.md @@ -62,14 +62,14 @@ These are both [ordered] strings of arrays: than received. 2. `rpcDocuments` is an array of zero or more URLs of machine-readable OpenRPC documents that the caller would prefer the respondent to use, ordered by - preference. This set of document collectively defines at least syntactically - if not also semantically any methods and/or notifications authorized by the - CAIP-25 authorization, in DESCENDING heirarchical authority. (For example, - any methods or notifications defined differently by multiple authorites will - be interpreted by whichever authority is closer to the 0-index of the array). - Each must be a valid URL that addresses a valid openRPC document. The - respondent may return it empty, reordered, with less, the same, or even more - conformant URLs than received. + preference. This set of documents defines the syntax (and optionally also the + semantics) of all the methods and/or notifications being requested and + authorized in a CAIP-25 authorization. The documents are listed in + descending heirarchical authority, i.e., documents later in the list extend + the first, but any terms already defined by a previous entry are dropped + rather than being redefined by the later documents. Each must be a valid URL + that addresses a valid openRPC document. The respondent may return it empty, + reordered, with less, the same, or even more conformant URLs than received. ### Request