Add ERC: Wallet Connection API

ERCS/erc-7846.md

@@ -0,0 +1,233 @@
+--- 
+eip: 7846
+title: Wallet Connection API  
+description: Adds JSON-RPC method for requesting wallet connection with modular capabilities.  
+author: Conner Swenberg (@ilikesymmetry), Jake Moxey (@jxom), Lukas Rosario (@lukasrosario).
+discussions-to: https://ethereum-magicians.org/t/erc-7846-wallet-connection-api/22245
+status: Draft
+type: Standards Track
+category: ERC
+created: 2024-12-15
+---
+
+## Abstract
+
+This ERC introduces a new wallet connection JSON-RPC method focused on extensibility. It leverages the modular capabilities approach defined in [ERC-5792](https://eips.ethereum.org/EIPS/eip-5792#wallet_getcapabilities) to streamline connections and authentication into a single interaction.
+
+## Motivation
+
+With applications beginning to require support for more sophisticated functionality in wallet connection flows, the need for a unified and extensible wallet connection JSON-RPC method has become more apparent.
+
+This is especially evident in the case of attempting to batch connection with authentication, where existing methods like `eth_requestAccounts` and `personal_sign` lack extensibility and require at least two separate user interactions (ie. connect and then sign).
+
+## Specification
+
+### JSON-RPC Methods
+
+#### `wallet_connect`
+
+Requests to connect account(s) with optional capabilities.
+
+##### Request
+
+```ts
+type Request = {
+  method: 'wallet_connect',
+  params: [{
+    // JSON-RPC method version.
+    version: string;
+    // Optional capabilities to request (e.g. Sign In With Ethereum).
+    capabilities?: Record<string, unknown>;
+  }]
+}
+```
+
+##### Response
+
+List of connected accounts with their associated capabilities.
+
+```ts
+type Response = {
+  accounts: {
+    // Address of the connected account.
+    address: `0x${string}`;
+    // Capabilities granted that is associated with this account.
+    capabilities: Record<string, unknown>;
+  }[]
+}
+```
+
+##### Example
+
+```ts
+const response = await provider.request({
+  method: 'wallet_connect',
+  params: [{
+    version: '1',
+    capabilities: {
+      signInWithEthereum: {
+        nonce: '12345678',
+        chainId: '0x1'
+      }
+    }
+  }]
+})
+/**
+ * {
+ *   accounts: [
+ *     {
+ *       address: '0x...',
+ *       capabilities: {
+ *         signInWithEthereum: {
+ *           message: 'app.com wants you to sign in with your Ethereum account:\n0x...',
+ *           signature: '0x...'
+ *         }
+ *       }
+ *     }
+ *   ]
+ * }
+ */
+```
+
+#### `wallet_disconnect`
+
+Disconnects connected account(s).
+
+- The wallet SHOULD revoke any capabilities associated with the account(s) that were granted upon connection via `wallet_connect`.
+
+##### Request
+
+```ts
+type Request = {
+  method: 'wallet_disconnect'
+}
+```
+
+##### Example
+
+```ts
+await provider.request({
+  method: 'wallet_disconnect',
+})
+```
+
+### Capabilities
+
+#### `signInWithEthereum`
+
+Adds support for offchain authentication using [ERC-4361: Sign-In with Ethereum](https://eips.ethereum.org/EIPS/eip-4361).
+
+##### Parameters
+
+Same as ERC-4361 specification with minor modifications: 
+* The casing of multi-word fields has been adjusted to camelCase instead of kebab-case. Resources are an array field. 
+* The account address returned by `wallet_connect` MUST match the address inferred in the SIWE message.
+* `version` is optional and defaults to an accepted version defined in ERC-4361 if not provided.
+* `domain` is optional and defaults to the domain of the requesting app if not provided.
+* `uri` is optional and defaults to the uri of the requesting app if not provided.
+* `issuedAt` is optional and defaults to the current time if not provided.
+
+The wallet MUST return a ERC-4361-formatted message that exactly matches the requested parameters and a signature over the EIP-191 `personal_sign` hash of the message. The app SHOULD also verify that the two match for security.
+
+```ts
+type Parameters = {
+  signInWithEthereum: {
+    nonce: string;
+    chainId: string; // EIP-155 hex-encoded
+    version?: string;
+    scheme?: string;
+    domain?: string;
+    uri?: string;
+    statement?: string;
+    issuedAt?: string;
+    expirationTime?: string;
+    notBefore?: string;
+    requestId?: string;
+    resources?: string[];
+  }
+}
+```
+
+##### Response
+
+Formatted SIWE message and signature.
+
+```ts
+type Response = {
+  signInWithEthereum: {
+    // Formatted SIWE message.
+    message: string;
+    // Signature over the EIP-191 personal_sign hash of the message.
+    signature: `0x${string}`;
+  }
+}
+```
+
+#### Example
+
+```ts
+const result = await provider.request({
+  method: 'wallet_connect',
+  params: [{
+    version: '1',
+    capabilities: {
+      signInWithEthereum: {
+        nonce: '12345678',
+        chainId: '0x1',
+        version: '1',
+        domain: 'app.com',
+        uri: 'https://app.com/connect',
+        issuedAt: '2024-12-35T04:20:00Z',
+        expirationTime: '2024-12-35T06:09:00Z'
+      }
+    }
+  }]
+})
+/**
+ * {
+ *   accounts: [
+ *     {
+ *       address: '0x...',
+ *       capabilities: {
+ *         signInWithEthereum: {
+ *           message: 'app.com wants you to sign in with your Ethereum account:\n0x...',
+ *           signature: '0x...'
+ *         }
+ *       }
+ *     }
+ *   ]
+ * }
+ */
+```
+
+## Rationale
+
+### Multiple Accounts
+
+Returning multiple accounts allows greater generality for apps that wish to interact in more complex ways with users. This also improves our backwards compatibility with `eth_requestAccounts`. In practice, we expect most apps only interact with the first account in the array.
+
+### Capability Results
+
+Returning capability results alongside the connection unlocks many valuable use cases such as authentication, user metadata sharing, and permissions granted to the app.
+
+### Initial Authentication Capability
+
+To ensure immediate value, this proposal includes a capability that combines wallet connection with authentication using the widely adopted [Sign In With Ethereum (ERC-4361)](https://eips.ethereum.org/EIPS/eip-4361) standard. This optional capability simplifies the onboarding process for apps and users by combining two steps — connection and authentication — into a single interaction. Apps that prefer alternative authentication flows can implement their own capabilities without being constrained by this design.
+
+By unifying connection and authentication into one step, apps can reduce friction, improve the user experience, and minimize redundant interactions.
+
+## Backwards Compatibility
+
+This standard builds on existing JSON-RPC methods and complements ERC-5792 for future extensibility. Wallets can continue supporting legacy methods.
+
+## Security Considerations
+
+Applies [ERC-4361 security principles](https://eips.ethereum.org/EIPS/eip-4361#security-considerations). As more capabilities are added, care must be taken to avoid unpredictable interactions.
+
+## Privacy Considerations
+
+Wallet addresses and any shared capabilities must be handled securely to avoid data leaks or man-in-the-middle attacks.
+
+## Copyright
+
+Copyright and related rights waived via CC0.