diff --git a/CAIPs/caip-345.md b/CAIPs/caip-345.md new file mode 100644 index 00000000..8bda9e0d --- /dev/null +++ b/CAIPs/caip-345.md @@ -0,0 +1,104 @@ +--- +caip: CAIP-345 +title: Wallet Service URL property +author: Chris Smith (@chris13524) +discussions-to: https://github.com/ChainAgnostic/CAIPs/discussions/345 +status: Draft +type: Standard +created: 2025-02-17 +updated: 2025-02-17 +requires: 25 +--- + +## Simple Summary + +This CAIP defines a mechanism for CAIP-25 wallets to advertize support for a "wallet service" which can handle requests for specific wallet RPC methods instead of apps sending these requests directly to the wallet app. + +## Abstract + +A short (~200 word) description of the technical issue being addressed. + +## Motivation + +In protocols such as WalletConnect it is bad UX to redirect the user to a wallet to handle requests that are non-actionable to them. Examples of this include: +- `wallet_getCapabilities` - Defined in [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792#wallet_getcapabilities) +- `wallet_getCallsStatus` - Defined in [EIP-5792](https://eips.ethereum.org/EIPS/eip-5792#wallet_getcallsstatus-rpc-specification) +- `wallet_getAssets` - Defined in [EIP-7811](https://eip.tools/eip/7811) + +By defining a way for wallets to send requests to an external URL, the requests can be satisfied without needing the wallet app to be open. + +## Specification + + +Apps SHOULD use the wallet service when available for a method, instead of calling the wallet directly. + +Wallets SHOULD implement fallback handling for all wallet service methods. + +Wallets MUST NOT include the same method multiple times or with different (conflicting) wallet service URLs. Apps SHOULD NOT attempt to recover from multiple or conflicting wallet service URLs, but MAY use the first URL available for the method as a convenience for implementation. + +```ts +type WalletService = { + url: string, + methods: string[], +}[]; + +type Properties = { + walletService: WalletService, + [key: string]: any, // other properties +}; +``` + +An easy way for apps to find the wallet service URL for a given method would be: + +```javascript +walletService.find(s => s.methods.includes(method)).url +``` + +The `walletService` key can be used in both `sessionProperties` and `scopedProperties`, depending on what namespaces the method(s) in question are supported on. + +Below is an example support for `wallet_getAssets` which is only supported on `eip155` namespaces: + +```json +"scopedProperties": { + "eip155": { + "walletService": [{ + "url": "", + "methods": ["wallet_getAssets"] + }], + } +} +``` + +## Rationale + + +Allowing multiple URLs to be provided for different methods (useful for different endpoints, params or auth tokens). While at the same time, not duplicating the Wallet Service URL. + +There was consideration for being able to specify different wallet service URLs for different accounts. However this would not make sense in the context of CAIP-25 because there is no mechanism to scope the methods themselves to particular accounts. If we provided a mechanism to scope the methods to accounts in this CAIP, the app may still try to send the method requests for non-listed accounts directly to the wallet. + +There was consideraiton for defining the standard to have a unique wallet service URL for every single method. However this would cause excessive bandwidth consumption if the same URL were to be used for multiple methods. + +## Test Cases + + +## Security Considerations + +The wallet service would bear the security resonsibility of responding to these wallet RPC requests. Wallets should make informed decisions about which providers they use for this. + +## Privacy Considerations + +Similarly, the wallet service would have visibility into the wallet RPC requests being sent to it. + +## Backwards Compatibility + +This new property is fully backwards-compatible with CAIP-25. + +## References + + +- [CAIP-25][CAIP-25] is where this property is used + +[CAIP-25]: https://ChainAgnostic.org/CAIPs/caip-25 + +## Copyright +Copyright and related rights waived via [CC0](../LICENSE).