diff --git a/CAIPs/caip-171.md b/CAIPs/caip-171.md new file mode 100644 index 00000000..2604b3a4 --- /dev/null +++ b/CAIPs/caip-171.md @@ -0,0 +1,62 @@ +--- +caip: 171 +title: Session Identifiers +author: Olaf Tomalka (@ritave) +discussions-to: +status: Draft +type: Standard +created: 2022-11-09 +--- + +## Simple Summary + +This CAIP defines an common identifier for representing an open session with a +wallet, including both in-browser session tokens and API-based connection IDs. + +## Motivation + +Currently, sessions with wallet clients are tracked differently across different +architectures: in-browser MetaMask sandboxes instance-specific connections based +on origin which are referred to by tokens in the browser, while WalletConnect +uses a topic-based pub/sub protocol keyed to a unique topic string, etc. +Aligning specific aspects of session state can be hard without shared +assumptions about session boundaries and tracking. A minimal assumption is that +sessions are tracked by identifiers, and that different actors can update the +session accordingly. + +## Specification + +> Such sections are considered non-normative. + +### Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" written in +uppercase in this document are to be interpreted as described in [RFC +2119](https://www.ietf.org/rfc/rfc2119.txt) + +### Definition + +Whenever a CAIP uses the name `SessionIdentifier` and has this CAIP in the +`required` front-matter property, it SHALL be interpreted as reference to this +specification. + +> Notice that there are no code constraints on the token value. This is by +> design and the value is implementation-dependent. + +```typescript +type SessionIdentifier = string; +``` + +Properties of the `SessionIdentifier` are as follows: +1. It MUST uniquely identify an open and stateful session. +2. It MUST identify a closeable session, and it MUST become invalid + after a session is closed. +3. It MUST remain the same as the identified session's state changes. +4. It MUST be serializable into JSON. Serialization and later deserialization using +JSON MUST result in the same value. + +## Copyright + +Copyright and related rights waived via +[CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/CAIPs/caip-25.md b/CAIPs/caip-25.md index a217f26f..eb84255d 100644 --- a/CAIPs/caip-25.md +++ b/CAIPs/caip-25.md @@ -7,7 +7,7 @@ status: Draft type: Standard created: 2020-10-14 updated: 2022-10-26 -requires: [2, 10] +requires: [2, 10, 171] --- ## Simple Summary @@ -66,7 +66,6 @@ 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 - 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 @@ -81,6 +80,8 @@ The wallet can respond to this method with either a success result or an error m 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 include `session` which is a `SessionIdentifier` as defined in [caip-171](./caip-171). + An example of a successful response should match the following format: ```jsonc @@ -88,6 +89,7 @@ An example of a successful response should match the following format: "id": 1, "jsonrpc": "2.0", "result": { + "session": "0xdeadbeef", "accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"] } } @@ -95,7 +97,6 @@ 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. - #### Failure States The response MUST NOT be a success result when the user disapproves the accounts @@ -117,29 +118,30 @@ An example of an error response should match the following format: ``` The valid error messages codes are the following: - -- When user disapproves exposing accounts to requested chains - - code = 5000 - - message = "User disapproved requested chains" -- 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" - -## Links - -n/a +* When user disapproves exposing accounts to requested chains + * code = 5000 + * message = "User disapproved requested chains" +* 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" + +## Changelog + +- 2022-11-26: add mandatory indexing by session identifier (i.e. CAIP-171 requirement) +- 2022-10-26: Addressed Berlin Gathering semantics issues and params syntax; + consolidated variants across issues and forks post-Amsterdam Gathering ## Copyright diff --git a/CAIPs/caip-27.md b/CAIPs/caip-27.md index 1f09d1ad..76a5db12 100644 --- a/CAIPs/caip-27.md +++ b/CAIPs/caip-27.md @@ -6,24 +6,33 @@ discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/27 status: Draft type: Standard created: 2020-12-12 -requires: 2 +updated: 2022-11-16 +requires: ["2", "25", "171"] --- ## Simple Summary -CAIP-27 defines a standard JSON-RPC method for requesting to a target chain +CAIP-27 defines a standard JSON-RPC method for requesting methods mapped to a +target chain. ## Abstract -This proposal has the goal to define a standard method for decentralization applications to request JSON-RPC requests from cryptocurrency wallets directly to a target chain. +This proposal has the goal to define a standard method for decentralization +applications to request JSON-RPC methods from cryptocurrency wallets directed to +a given target chain. ## Motivation -The motivation comes from the ambiguity that comes from interfacing with multi-chain cryptocurrency wallets which may support the same methods for different chains and there is no indication of the chain that is being targeted by the decentralized application. +The motivation comes from the ambiguity that comes from interfacing with +multi-chain cryptocurrency wallets which may support the same methods for +different chains and there is no indication of the chain that is being targeted +by the decentralized application. ## Specification -The JSON-RPC provider is able to make any JSON-RPC requests accompanied by a [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md) compatible chainId's +The JSON-RPC provider is able to make one or more JSON-RPC requests accompanied +by a [CAIP-2][] compatible `chainId` and a keyed to a specific [CAIP-171][] +session. ### Request @@ -36,6 +45,7 @@ The application would interface with a provider to make request as follows: "method": "caip_request", "params": { "chainId": "eip155:1", + "session": "0xdeadbeef", "request": { "method": "personal_sign", "params": [ @@ -47,20 +57,26 @@ The application would interface with a provider to make request as follows: } ``` -The JSON-RPC method is labelled as `caip_request` and expects two parameters: +The JSON-RPC method is labelled as `caip_request` and expects three parameters: -- chainId - CAIP-2 compatible chainId +- chainId - [CAIP-2][]-defined `chainId` to identify both a namespace and a + specific chain or network within it +- session - [CAIP-171][] `SessionToken` to identify the session opened or + updated by a [CAIP-25][] interaction. - request - an object containing the fields: - method - JSON-RPC method to request - params - JSON-RPC parameters to request ### Response -The wallet will respond to the requested with the targeted chain connection and it will return a response with a success result or error message. +The wallet will respond to the requested with the targeted chain connection and +it will return a response with a success result or error message. ## Links -n/a +[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 +[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25 +[CAIP-171]: https://chainagnostic.org/CAIPs/caip-171 ## Copyright