From 0e9722abf4214c15c470c1bfdf9b50273050e805 Mon Sep 17 00:00:00 2001 From: Nguyen Anh Tu Date: Tue, 7 Jan 2025 11:27:55 +0700 Subject: [PATCH 1/2] feat(doc): caip - add caip-320 --- CAIPs/caip-320.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 CAIPs/caip-320.md diff --git a/CAIPs/caip-320.md b/CAIPs/caip-320.md new file mode 100644 index 00000000..18f732ef --- /dev/null +++ b/CAIPs/caip-320.md @@ -0,0 +1,149 @@ +--- +# Every document starts with a front matter in YAML enclosed by triple dashes. +# See https://jekyllrb.com/docs/front-matter/ to learn more about this concept. +caip: 320 +title: Wallet Switch Chain JSON-RPC Method +author: Anh Tu Nguyen (@tuna1207), Chaitanya Potti (@chaitanyapotti), Tai Nguyen (@tanguyenvn) +discussions-to: +status: Draft +type: Standard +created: 2025-01-06 +updated: 2025-01-06 +requires: 2, 25, 171, 316 +--- + + + +## Simple Summary + + + +CAIP-320 introduces the wallet_switchChain method for a chain agnostic wallet to switch the current active chain of the wallet using the id specified in CAIP-2. + +## Abstract + + + +This proposal aims to define a standard method for decentralized applications to invoke a chain agnostic wallet to switch the current active chain of the wallet using the blockchain id specified in CAIP-2. + +## Motivation + + + +The motivation comes from the lack of standardization for multichain wallet to switch current active chain between multiple blockchain and define the expected JSON-RPC methods to be used by an application through a provider connecting to a signer or other user agent. + +## Specification + + + +### 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][] + +### Definition + +The JSON-RPC provider is able to invoke a single JSON-RPC request accompanied by a [CAIP-2][] compatible `chainId` authorized by a pre-existing session. +If that pre-existing session was initiated by a [CAIP-25] response containing a [sessionId][CAIP-171], this `sessionId` value should also be returned at the top level of the `wallet_switchChain` envelope (see [CAIP-316] for more context on managing sessions with and without `sessionId` keys). + +### Request + +The application would interface with an JSON-RPC provider to make request as follows: + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "method": "wallet_switchChain", + "params": { + "sessionId": "0xdeadbeef", + "chainId": "eip155:1" + } +} +``` + +The JSON-RPC method is labeled as `wallet_switchChain` and expects two parameters, **two of them required**: + +- **sessionId** (conditional) - [CAIP-171][] `SessionId` disambiguates an open session in a multi-session actor; it is required in some sessions, such as [CAIP-25][] sessions created by a response containing one, and SHOULD be omitted in other sessions, such as [CAIP-25] sessions created by a response not containing one (see [CAIP-316]). +- **chainId** (required) - a valid [CAIP-2][] network identifier, previously authorized by or within a `scopeObject` in the active session + +### Validation + +1. A respondent SHOULD check the `scope` against active session's `scopeObject`s before executing or responding to such a request, and SHOULD invalidate a request for a scope not previously authorized. +2. The respondent SHOULD check that `request.method` is authorized for the specified scope, and SHOULD invalidate a request for a scope not previously authorized. +3. The respondent MAY check that the `request.params` are valid for `request.method`, if its syntax is known to it. +4. The respondent MAY apply other logic or validation. +5. The respondent MAY chose to drop invalid requests or return an error message. + +### Response + +Upon successful validation, the respondent will switch the current active chain to the targeted network. + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "result": { + "sessionId": "0xdeadbeef", + "chainId": "eip155:1" + } +} +``` + +#### Error Handling + +##### Generic Failure Code + +Unless the dapp is known to the wallet and trusted, the generic/undefined error response, + +```jsonc +{ + "id": 1, + "jsonrpc": "2.0", + "error": { + "code": 0, + "message": "Unknown error" + } +} +``` + +##### Trusted Failure Codes + +More informative error messages MAY be sent in trusted-counterparty circumstances. +The core error messages over trusted connections are as follows: + +The valid error messages codes are the following: + +- User rejected request + - code = 4001 + - message = "User disapproved request" +- Unrecognized chain + - code = 4902 + - message = "Unrecognized chain" +- Chain not supported + - code = 4903 + - message = "Chain not supported" + +## References + + + +- [CAIP-2]: Network identifiers +- [CAIP-25]: Authorized session definition +- [CAIP-171]: Session identifiers for Authorized Sessions +- [CAIP-217]: Scope Definitions for Authorized Sessions +- [CAIP-316]: Managing Authorized Sessions With and Without Identifiers +- [wallet_switchEthereumChain]: Metamask switch chain ethereum JSON-RPC method + +[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 +[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25 +[CAIP-171]: https://chainagnostic.org/CAIPs/caip-171 +[CAIP-217]: https://chainagnostic.org/CAIPs/caip-217 +[CAIP-316]: https://chainagnostic.org/CAIPs/caip-316 +[wallet_switchEthereumChain]: https://docs.metamask.io/wallet/reference/json-rpc-methods/wallet_switchethereumchain/ + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE). From 6c5a4109a3f4af0c68d68a87e26cd09c7991e0fc Mon Sep 17 00:00:00 2001 From: Nguyen Anh Tu Date: Tue, 7 Jan 2025 11:32:13 +0700 Subject: [PATCH 2/2] feat(doc): caip - update caip 320 discussions to --- CAIPs/caip-320.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CAIPs/caip-320.md b/CAIPs/caip-320.md index 18f732ef..7813a016 100644 --- a/CAIPs/caip-320.md +++ b/CAIPs/caip-320.md @@ -4,7 +4,7 @@ caip: 320 title: Wallet Switch Chain JSON-RPC Method author: Anh Tu Nguyen (@tuna1207), Chaitanya Potti (@chaitanyapotti), Tai Nguyen (@tanguyenvn) -discussions-to: +discussions-to: https://github.com/ChainAgnostic/CAIPs/discussions/343 status: Draft type: Standard created: 2025-01-06