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, `wallet_connect`. It leverages the modular capabilities approach defined in [ERC-5792](./eip-5792.md#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
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
+
+### 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 access to the user account(s) information, as well as to any capabilities associated with them 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](./eip-4361.md).
+
+##### 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 Sign-In with Ethereum (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](./eip-191.md) `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)](./eip-4361.md) 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](./eip-4361.md#security-considerations). As more capabilities are added, care must be taken to avoid unpredictable interactions.
+
+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](../LICENSE.md).