initial structure for eip155/caip25 and /caip211 profiles (#101)

ChainAgnostic · May 23, 2024 · ea6a807 · ea6a807
2 parents 002194a + e5871c7
commit ea6a807
Show file tree

Hide file tree

Showing 2 changed files with 204 additions and 0 deletions.
diff --git a/eip155/caip211.md b/eip155/caip211.md
@@ -0,0 +1,51 @@
+---
+namespace-identifier: eip155-caip25
+title: EIP155 Namespace, aka EVM Chains - JSON-RPC Provider Authorization
+author: Pedro Gomes (@pedrouid), Hassan Malik (@hmalik88), bumblefudge (@bumblefudge)
+discussions-to: 
+status: Draft
+type: Standard
+created: 2024-02-05
+updated: 2024-02-05
+requires: ["CAIP-25", "CAIP-211", "CAIP-217"]
+---
+
+# CAIP-25
+
+_For context, see the [CAIP-211] and [CAIP-25] specifications._
+
+## Rationale
+
+In the Ethereum space, JSON-RPC connections are not constrained by a single interface definition; numerous overlapping implicit and explicit authorities define the valid interactions between a user agent like a wallet and a decentralization application (whether web-based or otherwise).
+The core RPC capabilities (concretely, the syntax and semantics of RPC methods and notifications) of any Ethereum or EVM-compatible network are assumed to be defined by the consensus of the Ethereum Improvement Proposal process.
+In practice, this consensus is captured almost exhaustively by the [common API documentation][execution API] published by the execution-client community;
+this documentation should be considered the implicit authority when no overriding authority has been declared for RPC capabilities.
+
+## Capability Expression
+
+In the context of [CAIP-25][] or other negotiations between decentralized applications and user agents, decentralization applications SHOULD ONLY request, and wallets SHOULD ONLY express support for, RPC methods and notifications specified in the [execution API] documentation.
+The [execution API] capabilities are considered the implicit default authority in any `eip155` authorization scope where no authorities have been explicitly declared.
+
+When requesting or expressing support for any other RPC methods and/or notifications, additional authorities SHOULD be requested in a separate [CAIP-217] `authorizationScope` object, with authorities and endpoints explicitly declared as specified in [CAIP-211].
+
+In any scope object with additional authorities declared, methods or notifications specified by multiple authorities should be defined and understood according to the greatest authority in the list as per the [CAIP-211] specification.
+
+## Examples
+
+## References
+
+- [EIP155][]: Ethereum Improvement Proposal specifying generation and validation of ChainIDs
+
+[execution API]: https://github.com/ethereum/execution-apis?tab=readme-ov-file#execution-api-specification
+[CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
+[CAIP-10]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md
+[CAIP-19]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md
+[CAIP-25]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-25.md
+[CAIP-211]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-211.md
+[CAIP-217]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-217.md
+[EIP]: https://eips.ethereum.org/EIPS/eip-1
+[EIP155]: https://eips.ethereum.org/EIPS/eip-155
+
+## Rights
+
+Copyright and related rights waived via CC0.
diff --git a/eip155/caip25.md b/eip155/caip25.md
@@ -0,0 +1,153 @@
+---
+namespace-identifier: eip155-caip25
+title: EIP155 Namespace, aka EVM Chains - JSON-RPC Provider Authorization
+author: Pedro Gomes (@pedrouid), Hassan Malik (@hmalik88), bumblefudge (@bumblefudge)
+discussions-to: 
+status: Draft
+type: Standard
+created: 2024-02-05
+updated: 2024-02-05
+requires: ["CAIP-25", "CAIP-211", "CAIP-217"]
+---
+
+# CAIP-25
+
+_For context, see the [CAIP-25][] specification._
+
+## Rationale
+
+In the Ethereum space, many networks interact in a given application or session, and as such it is necessary for applications and user-agents like wallets to negotiation and authorize interfaces dynamically and mutually.
+The [CAIP-25] negotiation allows for multiple [CAIP-217] authorization scopes to be negotiated together. 
+
+## Network-specific versus Namespace-wide Scopes
+
+Authorizing permissions and capabilities to each network separately (i.e., in its own [CAIP-217] authorization object) is recommended in most use-cases, so that over the session and across sessions, each network can granularly gain or attenuate permissions and capabilities separately. 
+Conversely, an authorization object scoped to all of `eip155` can only add or substract individual networks from the `chains` array, or add and substract capabilities to all enumerated networks in that array.
+
+It is also worth mentioning that if a network supports any capabilities NOT supported by other networks, they should never share an authorization object, as the semantics of [CAIP-217] interpret this as supporting EVERY capability listed on EVERY network listed.
+
+In such cases, not only is a separate authorization object recommended, but an explicit [CAIP-211] declaration of the RPC authority where these network-specific capabilities are specified is also recommended;
+see the [eip155/caip211.md](./caip211.md) profile for further guidance on using `method` and `notification` definitions which are not universal to the eip155 namespace.
+
+## Session Properties
+
+No namespace-wide or network-specific session properties have yet been proposed for standardization.
+When crafting such properties for contextual/in-network usage, it is recommended to align one's semantics and syntax (including case-sensitive style guides for property names!) with the [EIP-6963] wallet provider interface (which extends the [EIP-1193] interface) for common properties across architectures, making sure to avoid any collisions.
+
+Similarly, wherever possible, session properties should align closely with information passed as JSON objects by `wallet_` RPC methods, like capabilities or permissions. For example, the capability objects keyed to hexidecimal [EIP-155] `chainId`s defined as the expected return content of the `wallet_getCapabilities` method in [EIP-5792] should also be valid keyed the same way in `sessionProperties.capabilities`.
+
+## Examples
+
+### Example Request
+
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "provider_authorize",
+  "params": {
+    "requiredScopes": {
+      "eip155": {
+        "scopes": ["eip155:1", "eip155:137"],
+        "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"],
+        "notifications": ["accountsChanged", "chainChanged"]
+      },
+      "eip155:10": {
+        "methods": ["get_balance"],
+        "notifications": ["accountsChanged", "chainChanged"]
+      },
+      "wallet": {
+        "methods": ["wallet_getPermissions", "wallet_switchEthereumChain", "wallet_creds_store", "wallet_creds_verify", "wallet_creds_issue", "wallet_creds_present", "wallet_getCapabilities"],
+        "notifications": []
+      },
+      "cosmos": {
+        ...
+      }
+    },
+    "optionalScopes":{
+      "eip155:42161": {
+        "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"],
+        "notifications": ["accountsChanged", "chainChanged"]
+    },
+    "sessionProperties": {
+      "expiry": "2022-12-24T17:07:31+00:00",
+      "caip154": {
+          "supported":"true"
+      }
+    }         
+  }
+}
+
+### Example Response
+
+```json
+{
+  "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"]
+        "notifications": ["accountsChanged", "chainChanged"],
+        "accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb", "eip155:137:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"]
+      },
+      "eip155:10": {
+        "methods": ["get_balance"],
+        "notifications": ["accountsChanged", "chainChanged"],
+        "accounts:" []
+      },
+      "eip155:42161": {
+        "methods": ["personal_sign"],
+        "notifications": ["accountsChanged", "chainChanged"],
+        "accounts":["eip155:42161:0x0910e12C68d02B561a34569E1367c9AAb42bd810"]
+      },
+      "wallet": {
+        "methods": ["wallet_getPermissions", "wallet_switchEthereumChain", "wallet_getCapabilities"],
+        "notifications": []
+      },
+      "cosmos": {
+        ...
+      }
+    },      
+    "sessionProperties": {
+      "capabilities": {
+          "0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb": {
+            "0x31": {
+              "paymasterService": {
+                 "supported": true
+               },
+               "sessionKeys": {
+                  "supported": true
+               }
+            },
+            "0x3432313631": {
+              "sessionKeys": {
+                "supported": false
+              }              
+            }
+          }
+       }   
+    }
+  }
+}
+## References
+
+- [EIP155][]: Ethereum Improvement Proposal specifying generation and validation of ChainIDs
+
+[execution API]: https://github.com/ethereum/execution-apis?tab=readme-ov-file#execution-api-specification
+[CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
+[CAIP-10]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md
+[CAIP-19]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md
+[CAIP-25]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-25.md
+[CAIP-211]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-211.md
+[CAIP-217]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-217.md
+[EIP]: https://eips.ethereum.org/EIPS/eip-1
+[EIP-155]: https://eips.ethereum.org/EIPS/eip-155
+[EIP-1193]: https://eips.ethereum.org/EIPS/eip-1193
+[EIP-5792]: https://eips.ethereum.org/EIPS/eip-5792
+[EIP-6963]: https://eips.ethereum.org/EIPS/eip-6963
+
+## Rights
+
+Copyright and related rights waived via CC0.