From b99b95f863530cf7d1e4e32a52c0a7fca3e89228 Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Tue, 22 Nov 2022 22:48:55 +0100 Subject: [PATCH 1/8] alternate extensions model Signed-off-by: bumblefudge --- CAIPs/caip-25.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index eb84255d..46fce5ee 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -51,10 +51,14 @@ given set of parameters by calling the following JSON-RPC request "method": "provider_authorization", "params": { "eip155": { - "chains": ["eip155:1"], + "chains": ["eip155:1", "eip155:137"], "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "personal_sign"] "events": ["accountsChanged", "chainChanged"] }, + "eip155:10": { + "methods": ["personal_sign"] + "events": ["accountsChanged", "chainChanged"] + }, "cosmos": { ... } @@ -64,9 +68,13 @@ given set of parameters by calling the following JSON-RPC request ``` The JSON-RPC method is labelled as `provider_authorization` and expects one or -more objects each named after the pertinent ChainAgnostic namespace and each -containing with three parameters: -- chains - array of CAIP-2 compliant chainId's +more objects each named after the scope of authorization: +1. EITHER an entire ChainAgnostic [namespace][] +2. OR a specific [CAIP-2][] in that namespace. + +Each object contains the following parameters: +- chains - array of [CAIP-2][]-compliant `chainId`'s. This parameter MAY be + omitted if the chain scope is already given by the name of the object. - methods - array of JSON-RPC methods expected to be used during the session - events - array of JSON-RPC message/events expected to be emitted during the session @@ -96,7 +104,8 @@ An example of a successful response should match the following format: ``` The accounts returned as a result should match the requested `chainId`s and -should be an array of CAIP-10 compliant `accountId`s. +should be an array of [CAIP-10][] compliant `accountId`s. + #### Failure States The response MUST NOT be a success result when the user disapproves the accounts @@ -136,6 +145,12 @@ The valid error messages codes are the following: * 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" ## Changelog From c5224d496207a329eb80827e8cd67da417874401 Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Thu, 24 Nov 2022 15:39:21 +0100 Subject: [PATCH 2/8] to rename sessionIdentifer in res Signed-off-by: bumblefudge --- 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 46fce5ee..5f663073 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -97,7 +97,7 @@ An example of a successful response should match the following format: "id": 1, "jsonrpc": "2.0", "result": { - "session": "0xdeadbeef", + "sessionIdentifier": "0xdeadbeef", "accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"] } } From c0c676968d8632061363271ab19d845eb9d632cd Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Thu, 24 Nov 2022 18:45:48 +0100 Subject: [PATCH 3/8] option/req extended Signed-off-by: bumblefudge --- CAIPs/caip-25.md | 116 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 94 insertions(+), 22 deletions(-) diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index 5f663073..3a1a5b8f 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -39,36 +39,57 @@ forthcoming one. Within that session model, this interface outlines the authorization of an injected provider per namespace. +The application interfaces with a provider to populate a session with a base +state describing authorized chains, methods, event, and accounts. This +negotation takes place by sending the application's REQUIRED and REQUESTED +properties of the session. If any requirements are not met, a failure response +expressive of one or more specific failure states will be sent (see below). +Conversely, a succesful response will contain all the required properties *and +the provider's choice of the optional properties* expressed as a unified set of +parameters. + ### Request -The application would interface with a provider to authorize a provider with a -given set of parameters by calling the following JSON-RPC request +Example: -``` +```jsonc { - "id": 1, - "jsonrpc": "2.0", - "method": "provider_authorization", - "params": { - "eip155": { - "chains": ["eip155:1", "eip155:137"], - "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "personal_sign"] - "events": ["accountsChanged", "chainChanged"] + "id": 1, + "jsonrpc": "2.0", + "method": "provider_authorization", + "params": { + "required": { + "eip155": { + "chains": ["eip155:1", "eip155:137"], + "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"] + "events": ["accountsChanged", "chainChanged"] }, "eip155:10": { - "methods": ["personal_sign"] - "events": ["accountsChanged", "chainChanged"] + "methods": ["get_balance"], + "events": ["accountsChanged", "chainChanged"] }, "cosmos": { - ... + ... } - }, + }, + "optional":{ + "eip155:42161": { + "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"], + "events": ["accountsChanged", "chainChanged"] + }, + "sessionProperties": { + "expiry": "2022-12-24T17:07:31+00:00", + "auto-refresh": "true" + } + } + }, } ``` -The JSON-RPC method is labelled as `provider_authorization` and expects one or -more objects each named after the scope of authorization: +The JSON-RPC method is labelled as `provider_authorization` and both the +"required" and "optional" arrays are populated with objects each +named after the scope of authorization: 1. EITHER an entire ChainAgnostic [namespace][] 2. OR a specific [CAIP-2][] in that namespace. @@ -79,18 +100,39 @@ Each object contains the following parameters: - events - array of JSON-RPC message/events expected to be emitted during the session +The `required` array MUST contain 1 or more of these objects; the `optional` +array MAY contain 0 or more of them, but MUST NOT be present if empty of any +objects. + +A special case is the `sessionProperties` object, which MUST be in the +`optional` array if present, as applications cannot mandate session variables to +providers. Because they are optional, providers MAY respond with all of the +requested properties, or a subset of the session properties, or no +`sessionProperties` object at all; they MAY even replace the values of the +optional session properties with their own values. Applications are expected to +track all of these returned properties in the session object identified by the +`sessionIdentifier`. All properties and their values MUST conform to definitions +in [CAIP-170][]. + ### Response The wallet can respond to this method with either a success result or an error message. #### Success -The response MUST be a success result when the user approved accounts matching -the requested chains to be exposed and the requested methods to be used. +The response MUST be structured as a session object containing all required +parameters and all, none, or some of the optional objections. Optionally, a +`sessionProperties` object may also be present, but its contents MUST conform to +[CAIP-170][] and MAY share all, none, or some of the recommended properties, in +addition to those provided by the provider. -The response MUST include `session` which is a `SessionIdentifier` as defined in [caip-171](./caip-171). +All namespace objects MUST contain an `accounts` array, and at least one of them +must contain an account authorized for use in the constructed session. -An example of a successful response should match the following format: +The response MUST also include `sessionIdentifier` which is a `sessionIdentifier` as +defined in [caip-171](./caip-171) before the `session` object it identifies. + +An example of a successful response follows: ```jsonc { @@ -98,7 +140,29 @@ An example of a successful response should match the following format: "jsonrpc": "2.0", "result": { "sessionIdentifier": "0xdeadbeef", - "accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"] + "session": { + "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:42161": { + "methods": ["personal_sign"], + "events": ["accountsChanged", "chainChanged"], + "accounts":["eip155:42161:0x0910e12C68d02B561a34569E1367c9AAb42bd810"] + "cosmos": { + ... + }, + "sessionProperties": { + "expiry": "2022-11-31T17:07:31+00:00" + } + } } } ``` @@ -151,6 +215,12 @@ The valid error messages codes are the following: * 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" +* Required Session Properties + * code = 5201 + * message = "Session Properties can only be optional" ## Changelog @@ -158,6 +228,8 @@ The valid error messages codes are the following: - 2022-10-26: Addressed Berlin Gathering semantics issues and params syntax; consolidated variants across issues and forks post-Amsterdam Gathering +[RFC3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 + ## Copyright Copyright and related rights waived via [CC0](../LICENSE). From 625c6b1d4f2acddd152a6cec300e8e2857fbd90d Mon Sep 17 00:00:00 2001 From: bumblefudge Date: Thu, 24 Nov 2022 18:57:03 +0100 Subject: [PATCH 4/8] typo - caip-170 link Signed-off-by: bumblefudge --- CAIPs/caip-25.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index 3a1a5b8f..701af643 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -229,6 +229,7 @@ The valid error messages codes are the following: consolidated variants across issues and forks post-Amsterdam Gathering [RFC3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 +[CAIP-170]: https://chainagnostic.org/CAIPs/caip-170 ## Copyright From 6ddf56a6463cbcf4cc12801736a21294b303a674 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Tue, 29 Nov 2022 15:15:50 +0100 Subject: [PATCH 5/8] to fix indentation --- CAIPs/caip-25.md | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index 701af643..eecf498d 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -61,29 +61,28 @@ Example: "required": { "eip155": { "chains": ["eip155:1", "eip155:137"], - "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"] + "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"], "events": ["accountsChanged", "chainChanged"] - }, - "eip155:10": { - "methods": ["get_balance"], - "events": ["accountsChanged", "chainChanged"] - }, - "cosmos": { - ... - } }, - "optional":{ - "eip155:42161": { - "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"], - "events": ["accountsChanged", "chainChanged"] - }, - "sessionProperties": { - "expiry": "2022-12-24T17:07:31+00:00", - "auto-refresh": "true" - } + "eip155:10": { + "methods": ["get_balance"], + "events": ["accountsChanged", "chainChanged"] + }, + "cosmos": { + ... } - }, - + }, + "optional":{ + "eip155:42161": { + "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"], + "events": ["accountsChanged", "chainChanged"] + }, + "sessionProperties": { + "expiry": "2022-12-24T17:07:31+00:00", + "auto-refresh": "true" + } + } + } } ``` From b93bc01376dc4ec9b4d024f29923e22a799898f8 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Mon, 5 Dec 2022 22:53:17 +0100 Subject: [PATCH 6/8] change requested session param in example --- 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 eecf498d..7d63d012 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -79,7 +79,7 @@ Example: }, "sessionProperties": { "expiry": "2022-12-24T17:07:31+00:00", - "auto-refresh": "true" + "caip154-mandatory": "true" } } } From 1771c97bd9b45f7448f7621f4ae2589e835b941b Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Wed, 7 Dec 2022 16:43:42 +0100 Subject: [PATCH 7/8] Update CAIPs/caip-25.md --- 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 7d63d012..c0e5b179 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -217,7 +217,7 @@ The valid error messages codes are the following: * Invalid Session Properties Object * code = 5200 * message = "Invalid Session Properties requested" -* Required Session Properties + * Required Session Properties * code = 5201 * message = "Session Properties can only be optional" From a3e3df90489a73af9ceb41b0c33224aa87c7a0e3 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Wed, 7 Dec 2022 23:15:36 +0100 Subject: [PATCH 8/8] editorial changes discussed on today's call --- CAIPs/caip-25.md | 78 +++++++++++++++++++++++++----------------------- 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index c0e5b179..1e5661f5 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -58,7 +58,7 @@ Example: "jsonrpc": "2.0", "method": "provider_authorization", "params": { - "required": { + "requiredNamespaces": { "eip155": { "chains": ["eip155:1", "eip155:137"], "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"], @@ -72,46 +72,48 @@ Example: ... } }, - "optional":{ + "optionalNamespaces":{ "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" - } - } + }, + "sessionProperties": { + "expiry": "2022-12-24T17:07:31+00:00", + "caip154-mandatory": "true" + } } } ``` The JSON-RPC method is labelled as `provider_authorization` and both the -"required" and "optional" arrays are populated with objects each -named after the scope of authorization: +"requiredNamespaces" and "optionalNamespaces" arrays are populated with +`namespace` objects each named after the scope of authorization: 1. EITHER an entire ChainAgnostic [namespace][] 2. OR a specific [CAIP-2][] in that namespace. -Each object contains the following parameters: +Each `namespace` object contains the following parameters: - chains - array of [CAIP-2][]-compliant `chainId`'s. This parameter MAY be omitted if the chain scope is already given by the name of the object. - methods - array of JSON-RPC methods expected to be used during the session - events - array of JSON-RPC message/events expected to be emitted during the session -The `required` array MUST contain 1 or more of these objects; the `optional` -array MAY contain 0 or more of them, but MUST NOT be present if empty of any -objects. +The `requiredNamespaces` array MUST contain 1 or more of these objects, and MUST +be present; the `optionalNamespaces` array MUST contain 1 or more of them, if +present. -A special case is the `sessionProperties` object, which MUST be in the -`optional` array if present, as applications cannot mandate session variables to -providers. Because they are optional, providers MAY respond with all of the -requested properties, or a subset of the session properties, or no +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 +with all of the requested properties, or a subset of the session properties, or no `sessionProperties` object at all; they MAY even replace the values of the -optional session properties with their own values. Applications are expected to -track all of these returned properties in the session object identified by the -`sessionIdentifier`. All properties and their values MUST conform to definitions -in [CAIP-170][]. +optional session properties with their own values. The `sessionProperties` +object MUST contain 1 or more properties if present. + +Requesting applications are expected to track all of these returned properties in +the session object identified by the `sessionId`. All properties and their values +MUST conform to definitions in [CAIP-170][], and MUST be ignored (rather than +tracked) if they do not. ### Response @@ -119,17 +121,22 @@ The wallet can respond to this method with either a success result or an error m #### Success -The response MUST be structured as a session object containing all required -parameters and all, none, or some of the optional objections. Optionally, a -`sessionProperties` object may also be present, but its contents MUST conform to -[CAIP-170][] and MAY share all, none, or some of the recommended properties, in -addition to those provided by the provider. +The succesfull reslt contains one mandatory string (keyed as `sessionId` with a value +conformant to [CAIP-171][]) and two session objects, both mandatory and non-empty. -All namespace objects MUST contain an `accounts` array, and at least one of them -must contain an account authorized for use in the constructed session. +The first is called `sessionNamespaces` and contains 1 or more namespace objects. +* All required namespaces and all, none, or some of the optional namespaces (at the +discretion of the provider) MUST be included if successful. +* As in the request, each namespace 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 namespace 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 chains authorized. -The response MUST also include `sessionIdentifier` which is a `sessionIdentifier` as -defined in [caip-171](./caip-171) before the `session` object it identifies. +A `sessionProperties` object MAY also be present, and its contents MAY correspond to the +properties requested in the response or not (at the discretion of the provider) but MUST +conform to the properties names and value constraints described in [CAIP-170][]; any other +MUST be dropped by the requester. An example of a successful response follows: @@ -138,8 +145,8 @@ An example of a successful response follows: "id": 1, "jsonrpc": "2.0", "result": { - "sessionIdentifier": "0xdeadbeef", - "session": { + "sessionId": "0xdeadbeef", + "sessionNamespaces": { "eip155": { "chains": ["eip155:1", "eip155:137"], "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "eth_sign", "personal_sign"] @@ -166,9 +173,6 @@ An example of a successful response follows: } ``` -The accounts returned as a result should match the requested `chainId`s and -should be an array of [CAIP-10][] compliant `accountId`s. - #### Failure States The response MUST NOT be a success result when the user disapproves the accounts @@ -213,7 +217,7 @@ The valid error messages codes are the following: * message = "Scope/chain mismatch" * When a badly-formed request defines one `chainId` two ways * code = 5104 - * message = "ChainId defined in two different scopes" + * message = "ChainId defined in two different scopes" * Invalid Session Properties Object * code = 5200 * message = "Invalid Session Properties requested"