feat: implement CAIP25 MultiChain API and NextJS playground integration

docs/CAIPS/caip-27_wallet_invokeMethod.md

@@ -0,0 +1,164 @@
+---
+caip: 27
+title: Wallet Invoke Method JSON-RPC Method
+author: Pedro Gomes (@pedrouid), Hassan Malik (@hmalik88)
+discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/27
+status: Draft
+type: Standard
+created: 2020-12-12
+updated: 2024-08-12
+requires: 2, 25, 171, 217, 316
+---
+
+## Simple Summary
+
+CAIP-27 defines a JSON-RPC method for a decentralized application to invoke a targeted JSON-RPC method, marked for a specified target previously authorized by a valid [scopeObject][CAIP-217], and tagged with a [sessionId][CAIP-171] for maintaining session continuity if applicable.
+
+## Abstract
+
+This proposal has the goal of defining a standard method for decentralized applications to invoke JSON-RPC methods from decentralized applications directed to a given, previously-authorized target network.
+These "target networks" can include nodes of a specific blockchain (accessed via the user agent), the consensus community within a cryptographic protocol, or a user agent's network-specific state.
+The JSON-RPC method is nested inside a JSON-RPC "envelope", which takes as required argument a [CAIP-2] identifier designating the target network, with an optional second argument for the [sessionId][CAIP-171] of that session if applicable (see [CAIP-316]).
+These two properties MAY be inherited from a persistent session created by [CAIP-25][], but could also be used as part of other session management mechanisms.
+
+## Motivation
+
+This routing envelope avoids ambiguity when applications interface with a multi-chain agent (e.g. a cryptocurrency wallets which supports the same method on multiple chains in a given RPC namespace, or supports methods with the same name on multiple [namespaces]).
+
+## 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_invokeMethod` 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_invokeMethod",
+  "params": {
+    "sessionId": "0xdeadbeef",
+    "scope": "eip155:1",
+    "request": {
+      "method": "eth_sendTransaction",
+      "params": [
+        {
+          "to": "0x4B0897b0513FdBeEc7C469D9aF4fA6C0752aBea7",
+          "from": "0xDeaDbeefdEAdbeefdEadbEEFdeadbeefDEADbEEF",
+          "gas": "0x76c0",
+          "value": "0x8ac7230489e80000",
+          "data": "0x",
+          "gasPrice": "0x4a817c800"
+        }
+      ]
+    }
+  }
+}
+```
+
+The JSON-RPC method is labeled as `wallet_invokeMethod` and expects three 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]).
+- **scope** (required) - a valid [CAIP-2][] network identifier, previously authorized by or within a `scopeObject` in the active session
+- **request** (required) - an object containing the fields:
+  - **method** (required) - the JSON-RPC method to invoke (previously authorized for the targeted network)
+  - **params** (required) - JSON-RPC parameters to invoke (may be empty but must be set)
+
+### 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, but it MUST NOT route or submit them.
+
+### Response
+
+Upon successful validation, the respondent will submit or route the request to the targeted network.
+If the targeted network returns a response to the respondent, the respondent MAY forward this response to the caller.
+
+```jsonc
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": {
+    "sessionId": "0xdeadbeef",
+    "scope": "eip155:1",
+    "result": {
+      "method": "eth_sendTransaction",
+      "result": "0x4e306b5a5a37532e1734503f7d2427a86f2c992fbe471f5be403b9f734e667c8"
+    }
+  }
+}
+```
+
+Constraints on, metadata about, or envelopes for response-forwarding MAY be set by [namespace][namespaces] profiles of this CAIP.
+
+#### Error Handling
+
+Note that errors pertaining to the connection or session should replace the top-level `"result"` object, but cannot be matched to requests sent without a unique `id`:
+
+```jsonc
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32700,
+    "message": "Parse Error"
+  }
+}
+```
+
+Conversely, errors specific to the method passed or its RPC namespace should be expressed INSIDE the result of a response envelope, with targeting information preserved:
+
+```jsonc
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": {
+    "sessionId": "0xdeadbeef",
+    "scope": "eip155:1",
+    "error": {
+      "code": 4100,
+      "message": "The requested account and/or method has not been authorized by the user."
+    }
+  }
+}
+```
+
+The latter category of error depend on the design of the passed method defined within the given RPC namespace, and MAY be defined by a [namespace][namespaces] profile of this CAIP if not in the underlying documentation for that RPC community.
+
+## Backwards Compatibility
+
+Early drafts of this specification did not constrain `scope` to [CAIP-2] identifiers, but rather to any [valid scopeStrings][CAIP-217] previously-authorized, including namespace-wide ones.
+No known implementations in production took advantage of this affordance, as to date no RPC [namespaces] have been defined that could receive such requests regardless of [CAIP-2] network identifiers.
+
+## Links
+
+- [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
+- [Namespaces]: CASA RPC Namespaces
+
+[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
+[namespaces]: https://namespaces.chainagnostic.org/
+[RFC 2119]: https://www.ietf.org/rfc/rfc2119.txt
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE).

docs/CAIPS/caip-311_sessionChanged.md

@@ -0,0 +1,78 @@
+---
+caip: 311
+title: JSON-RPC Event for Session Authorization Updates
+author: Alex Donesky (@adonesky1)
+discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/285/files
+status: Draft
+type: Standard
+created: 2024-07-12
+requires: 25, 217
+---
+
+## Simple Summary
+
+CAIP-311 introduces the `wallet_sessionChanged` event for notifying callers party to an active [CAIP-25][] session of updates to session authorizations made by users directly in the wallet.
+
+## Abstract
+
+This proposal aims to extend the [CAIP-25][] standard by defining a new JSON-RPC event for notifying the caller of updates to session authorizations. This event allows wallets to dynamically inform callers of changes to authorizations made by users on the wallet side, without having to initiate a new session each time.
+
+## Motivation
+
+The motivation behind this proposal is to provide bidirectional management of [CAIP-25][] session authorizations. The proposed event provides an intuitive way to notify dapps of changes to authorizations within an active session, simplifying the management of session lifecycles.
+
+## Definition
+
+## Specification
+
+This event is published by the wallet to notify the callers of updates to a shared session's authorization scopes. The event payload contains the new `sessionScopes`. If a connection between the wallet and the caller is severed and the possibility of missed events arises, the caller should immediately call `wallet_getSession` to retrieve the current session scopes.
+
+**Notification Parameters:**
+
+- `sessionId` (string, optional): The session identifier.
+- `sessionScopes` (object of `scopeObject` objects, required): An object containing the full updated session scopes, each formatted according to [CAIP-217][].
+
+**Notification:**
+
+```jsonc
+{
+  "method": "wallet_sessionChanged",
+  "params": {
+    "sessionScopes": {
+      "eip155:1": {
+        "methods": ["eth_signTransaction", "eth_sendTransaction"],
+        "notifications": ["accountsChanged"],
+        "accounts": ["eip155:1:0xabc123"]
+      },
+      "eip155:137": {
+        "methods": ["eth_sendTransaction"],
+        "notifications": [],
+        "accounts": ["eip155:137:0xdef456"]
+      }
+    }
+  }
+}
+```
+
+## Security Considerations
+
+The introduction of this lifecycle method must ensure that only authorized parties can retrieve the authorizations of a session. Proper authentication and authorization mechanisms must be in place to prevent unauthorized access or modifications.
+
+To achieve this, it is recommended to establish a connection over domain-bound or other 1:1 transports. Where applicable, additional binding to a `sessionId` is recommended to ensure secure session management. This approach helps to create a secure communication channel that can effectively authenticate and authorize session-related requests, minimizing the risk of unauthorized access or session hijacking.
+
+## Links
+
+- [CAIP-25] - JSON-RPC Handshake Protocol Specification. i.e `wallet_createSession`
+- [CAIP-217]- Authorization Scopes, i.e. syntax for `scopeObject`s
+
+[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25
+[CAIP-217]: https://chainagnostic.org/CAIPs/caip-217
+[CAIP-311]: https://chainagnostic.org/CAIPs/caip-311
+[CAIP-312]: https://chainagnostic.org/CAIPs/caip-312
+[CAIP-316]: https://chainagnostic.org/CAIPs/caip-316
+
+
+## Copyright
+
+Copyright and related rights waived via
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/).

docs/CAIPS/caip-312_wallet_getSession.md

@@ -0,0 +1,121 @@
+---
+caip: 312
+title: JSON-RPC Method for Retrieving Session Authorizations
+author: Alex Donesky (@adonesky1)
+discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/285/files
+status: Draft
+type: Standard
+created: 2024-07-13
+requires: 25, 217
+---
+
+## Simple Summary
+
+CAIP-312 introduces the `wallet_getSession` method for retrieving authorizations from an active [CAIP-25][] initiated session.
+
+## Abstract
+
+This proposal aims to extend the [CAIP-25][] standard by defining a new JSON-RPC method for retrieving authorizations within a session. This method allows callers to dynamically retrieve authorizations and properties.
+
+## Motivation
+
+The motivation behind this proposal is to enhance the flexibility of [CAIP-25][] by enabling the retrieval of session authorizations at any time. The proposed method provides an intuitive way to retrieve authorizations for an active session, allowing callers to access session data without having to persist and track it over the full life of the method.
+
+## Specification
+
+### Definition
+
+The `wallet_getSession` method returns an active session.
+If a `sessionId` is provided, it returns the authorizations for that specific session;
+If no `sessionId` parameter is provided - and there is a single active session with no `sessionId` assigned - it returns the session authorizations and properties for that session;
+otherwise, an appropriate error message;
+
+**Parameters:**
+
+- `sessionId` (string, optional): The session identifier.
+
+### Request
+
+The caller would interface with a wallet via the same provider by which it called `wallet_createSession` to retrieve a session by calling the following JSON-RPC request:
+
+```jsonc
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "wallet_getSession",
+  "params": {}
+}
+```
+
+### Response
+
+An example of a successful response follows:
+
+```jsonc
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": {
+    "sessionScopes": {
+      "eip155:1": {
+        "methods": ["eth_signTransaction"],
+        "notifications": ["accountsChanged"],
+        "accounts": ["eip155:1:0xabc123"]
+      },
+      "eip155:137": {
+        "methods": ["eth_sendTransaction"],
+        "notifications": ["chainChanged"],
+        "accounts": ["eip155:137:0xdef456"]
+      },
+      "solana:4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ": {
+        "methods": ["getBalance", "getAccountInfo", "sendTransaction", "getBlock"],
+        "notifications": [],
+        "accounts": ["solana:4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ:4Nd1mS8AUwK3kU3gdiAM6QCvqhA7Do8rKtMXsGyqrJxy"]
+      }
+  }
+}
+```
+
+### Failure States
+
+The response MUST NOT be a JSON-RPC success result in any of the following failure states.
+
+#### 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"
+  }
+}
+```
+
+is RECOMMENDED for any of the following cases:
+
+- a `sessionId` is passed but not recognized,
+- no `sessionId` is passed and only active session(s) have `sessionId`s, or
+- there are no active sessions
+
+## Security Considerations
+
+The introduction of this lifecycle method must ensure that only authorized parties can retrieve the authorizations of a session. Proper authentication and authorization mechanisms must be in place to prevent unauthorized access or modifications.
+
+To achieve this, it is recommended to establish a connection over domain-bound or other 1:1 transports. Where applicable, additional binding to a `sessionId` is recommended to ensure secure session management. This approach helps to create a secure communication channel that can effectively authenticate and authorize session-related requests, minimizing the risk of unauthorized access or session hijacking.
+
+## Links
+
+- [CAIP-25] - JSON-RPC Handshake Protocol Specification. i.e `wallet_createSession`
+- [CAIP-217]- Authorization Scopes, i.e. syntax for `scopeObject`s
+
+[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25
+[CAIP-217]: https://chainagnostic.org/CAIPs/caip-217
+
+## Copyright
+
+Copyright and related rights waived via
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/).