CAIP-372 - Wallet Information Metadata Standard

CAIPs/caip-372.md

@@ -0,0 +1,130 @@
+---
+caip: 372
+title: Wallet Information Metadata Standard
+author: Pedro Gomes (@pedrouid)
+discussions-to: https://github.com/ChainAgnostic/CAIPs/pull/372
+status: Draft
+type: Standard
+created: 2025-08-11
+---
+
+## Simple Summary
+
+This CAIP defines a standard `WalletInfo` metadata object to identify and validate the wallet provider that a client application is interacting with.
+It can be used across RPC methods, APIs, and protocols to provide consistent, cross-chain wallet identification.
+
+## Abstract
+
+The `WalletInfo` object provides a minimal, standardized set of fields that uniquely identify a wallet provider and allow dApps to confirm they are connected to the intended wallet.
+The object is designed for use in [CAIP-25] session properties, [CAIP-282] messages, and other API contexts.
+The definition includes a UUIDv4 identifier, human-readable name, icon URI, and reverse-DNS string to support clear and reliable wallet identification.
+
+## Motivation
+
+Wallet providers often expose their brand, capabilities, or identity inconsistently across blockchains and APIs.
+This creates friction for dApps attempting to present clear wallet branding or confirm that the connection is genuine.
+
+By standardizing `WalletInfo`, wallet providers can:
+
+- Ensure a consistent presentation across dApps and chains.
+- Reduce risk of misidentification or spoofing by unverified wallets.
+- Facilitate richer integrations in protocols like CAIP-25 and CAIP-282.
+
+For dApps, this enables:
+
+- Trust signals to the user (correct wallet branding and identity).
+- Improved debugging and support workflows.
+- Safer handling of wallet interactions across chains.
+
+## Specification
+
+A `WalletInfo` object MUST contain the following fields:
+
+- **uuid**: A globally unique identifier (UUIDv4) generated by the wallet provider to uniquely distinguish different wallet provider sessions that have otherwise matching properties.The cryptographic uniqueness of UUIDv4 ensures separate identification of independent sessions.
+- **name**: A human-readable name or alias of the wallet provider, suitable for display to the user (e.g., "Example Wallet Extension" or "Awesome Example Wallet").
+- **icon**: A URI pointing to an image asset representing the wallet. The image SHOULD be square, with a minimum resolution of 96×96px. SVG or PNG formats are recommended. The asset SHOULD be optimized for display on both light and dark backgrounds.
+- **rdns**: The reverse domain name string identifying the wallet provider (e.g., `com.example.wallet`). This is expected to remain stable throughout the lifetime of the wallet product. dApps MUST be prepared to handle values that are unknown, invalid, or potentially misleading, similar to handling user agent strings in web browsers.
+
+Wallet providers SHOULD generate and maintain the same `uuid` only for the lifetime of a given page/session context, not permanently across user devices, to avoid unnecessary tracking while preserving identification during the session.
+
+## Examples
+
+### Example in CAIP-25 RPC Response
+
+```jsonc
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": {
+    "sessionId": "0xdeadbeef",
+    "wallet": {
+      "methods": ["wallet_pay"],
+      "notifications": [],
+      "info": {
+        "uuid": "350670db-19fa-4704-a166-e52e178b59d2",
+        "name": "Example Wallet",
+        "icon": "data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'/>",
+        "rdns": "com.example.wallet"
+      },
+      "capabilities": {
+        "walletService": "https://wallet-service.example.com/rpc"
+      }
+    }
+  }
+}
+```
+
+### Example in CAIP-282 `wallet_announce` Message
+
+```typescript
+// for "wallet_announce" method
+interface WalletAnnounceParams {
+  info: WalletInfo;
+  scopes?: AuthorizationScopes;
+}
+```
+
+Example payload:
+
+```json
+{
+  "method": "wallet_announce",
+  "params": {
+    "info": {
+      "uuid": "350670db-19fa-4704-a166-e52e178b59d2",
+      "name": "Example Wallet",
+      "icon": "https://example.com/icon.png",
+      "rdns": "com.example.wallet"
+    },
+    "scopes": {
+      "eip155:1": ["eth_sendTransaction"]
+    }
+  }
+}
+```
+
+## Rationale
+
+Standardizing wallet identification metadata:
+
+- Reduces dApp logic required for wallet detection.
+- Creates a consistent user experience for wallet branding.
+- Minimizes risk of spoofing by enforcing a predictable set of fields.
+- Works across chains and protocols (CAIP-25, CAIP-282, and beyond).
+
+The `uuid` field is ephemeral enough to avoid unnecessary tracking while still providing strong uniqueness during the session lifecycle.
+
+## Backwards Compatibility
+
+This CAIP is additive and backward compatible.
+dApps and wallets that do not recognize or provide `WalletInfo` can continue to function without changes.
+Implementations MAY omit or ignore unknown fields without causing errors.
+
+## References
+
+- [CAIP-25: Create Session](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md)
+- [CAIP-282: Wallet Communication](https://github.com/ChainAgnostic/CAIPs/pull/282)
+
+## Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).