From 7fa98ee45d59e33a9a07ca8353021b616e13c0f9 Mon Sep 17 00:00:00 2001 From: Luka Isailovic Date: Thu, 7 Nov 2024 17:42:08 +0100 Subject: [PATCH 1/4] add wallet asset discovery ERC --- ERCS/erc-wallet-asset-discovery.md | 218 +++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 ERCS/erc-wallet-asset-discovery.md diff --git a/ERCS/erc-wallet-asset-discovery.md b/ERCS/erc-wallet-asset-discovery.md new file mode 100644 index 0000000000..d36ed48f50 --- /dev/null +++ b/ERCS/erc-wallet-asset-discovery.md @@ -0,0 +1,218 @@ +--- +eip: xxxx +title: Wallet Asset Discovery ERC +description: JSON-RPC method for wallets to share a user’s complete asset list with Dapps, including assets not easily discoverable through on-chain information alone. +author: Luka Isailovic (@lukaisailovic), Konrad Kopp (@kopy-kat) +discussions-to: TBD +status: Draft +type: Standards Track +category: ERC +created: 2024-11-07 +--- + +## Abstract + +This ERC introduces a new RPC call, wallet_getAssets, for wallets to declare to the Dapp what assets are owned by the user. This allows for more accurate asset discovery and the use of assets that aren’t available on-chain but can be provided by the wallet + +## Motivation + +Currently, Dapps primarily rely on on-chain data to determine a user's balance, which can be limiting. Furthermore, a Dapp might restrict the user from initiating actions that the wallet could otherwise resolve, as it cannot account for the total assets a user has across different accounts or chains. + +Wallets already have information about a user's assets, including those not visible on-chain, and need a way to communicate that information to Dapps. + +## Specification + +The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. + +### Method: `wallet_getAssets` + +#### Request schema + +```ts +type WalletGetAssetsRequest = { + account: Hex; + requiredAssets?: Record; +}; +``` + +`account` is a required field that indicates for which account assets are requested. + +`requiredAssets` is an optional field that specifies only the assets Dapp cares about on the specific chains. If it is provided, the response from the wallet SHOULD include those assets. + +#### Example request + +```json +{ + "account": "0x123", + "requiredAssets": { + "0x1": ["0x456", "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"], + "0xa": ["0x789", "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"] + } +} +``` + +#### Response schema + +```ts +type Asset = { + address: Hex; + balance: Hex; + type: string; + metadata: any; +}; +type WalletGetAssetsResponse = Record; +``` + +The key **SHOULD** be EIP-155 chainId + +Asset fields: + +`address` is the address of the asset as Hex. Native assets **MUST** use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` address specified by ERC-7528 + +`balance` is the balance of the asset as Hex + +**`type`:** A string indicating the type of the asset. Common asset types include but **aren’t limited to**: + +- **`ERC20`:** For ERC20 tokens +- **`ERC721`:** For ERC721 tokens (NFTs) +- **`native`:** For the chain's native currency + +**`metadata`:** An optional object containing additional information about the asset. The specific fields within the metadata object may vary depending on the asset type and the wallet's implementation." + +#### Example response + +```json +{ + "0x1": [ + { + address: "0x123", + balance: "0xcaaea35047fe5702", + type: "ERC20", + metadata: { + name: "Token", + symbol: "TOK", + decimals: 18, + } + }, + { + address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", + balance: "0xcaaea35047fe5702", + type: "native" + } + ], + "0xa": [ + { + address: "0x456", + balance: "0xcd5595", + type: "ERC721", + metadata: { + //... + } + } + ], +}; +``` + +### Asset definitions + +This section specifies a structure for the most commonly used asset types. +This ERC does not specify an exhaustive list of asset types. Since the type is a generic string, there could be a mismatch between the type Dapp expects and the one returned by the wallet. It’s important that no two assets share the same type. Therefore, new asset types should be specified in ERCs, either in this ERC as an amendment or in another ERC. + +**Native** + +```ts +type NativeAsset = { + address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"; + balance: Hex; + type: "native"; + metadata: any; +}; +``` + +Example: + +```json +{ + "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", + "balance": "0xcaaea35047fe5702", + "type": "native" +} +``` + +**ERC-20 Token** + +```ts +type Erc20Asset = { + address: Hex; + balance: Hex; + type: "ERC20"; + metadata: { + name: string; + symbol: string; + decimals: number; + [key: string]: any; + }; +}; +``` + +Example: + +```json +{ + address: "0x123", + balance: "0xcaaea35047fe5702", + type: "ERC20", + metadata: { + name: "Token", + symbol: "TOK", + decimals: 18 + } +}, +``` + +**ERC-721 Token** + +```ts +type Erc721Asset = { + address: Hex; + balance: Hex; + type: "ERC20"; + metadata: { + name: string; + symbol: string; + [key: string]: any; + }; +}; +``` + +## Capabilities + +If the wallet is using CAIP-25 authorization, wallet **SHOULD** include `assetDiscovery` key in the CAIP-25 `sessionsProperties` object. Value should be an object with `supported` key and value `true` + +```json +{ + //... + "sessionProperties": { + "assetDiscovery": { + "supported": true + } + } +} +``` + +If the wallet supports ERC-5792 wallet **SHOULD** respond on `wallet_getCapabilities` request using the `assetDiscovery` key. Value should be an object with `supported` key and value `true` +Wallet **SHOULD** include this for every chainId. + +```json +{ + "0xa": { + "assetDiscovery": { + "supported": true + } + } +} +``` + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE.md). From 06feb1904fd1db3628f29f289d8805533114d2fb Mon Sep 17 00:00:00 2001 From: Luka Isailovic Date: Sat, 9 Nov 2024 21:57:19 +0100 Subject: [PATCH 2/4] update with erc number and discussion topic --- ERCS/{erc-wallet-asset-discovery.md => erc-7811.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename ERCS/{erc-wallet-asset-discovery.md => erc-7811.md} (97%) diff --git a/ERCS/erc-wallet-asset-discovery.md b/ERCS/erc-7811.md similarity index 97% rename from ERCS/erc-wallet-asset-discovery.md rename to ERCS/erc-7811.md index d36ed48f50..12336963b7 100644 --- a/ERCS/erc-wallet-asset-discovery.md +++ b/ERCS/erc-7811.md @@ -1,9 +1,9 @@ --- -eip: xxxx -title: Wallet Asset Discovery ERC +eip: 7811 +title: Wallet Asset Discovery description: JSON-RPC method for wallets to share a user’s complete asset list with Dapps, including assets not easily discoverable through on-chain information alone. author: Luka Isailovic (@lukaisailovic), Konrad Kopp (@kopy-kat) -discussions-to: TBD +discussions-to: https://ethereum-magicians.org/t/erc-7811-wallet-asset-discovery/21639 status: Draft type: Standards Track category: ERC From aefaed669901acb1ad365d2e1e803b38f747c9fe Mon Sep 17 00:00:00 2001 From: Luka Isailovic Date: Sat, 9 Nov 2024 22:09:02 +0100 Subject: [PATCH 3/4] update links and description --- ERCS/erc-7811.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/ERCS/erc-7811.md b/ERCS/erc-7811.md index 12336963b7..dae6be5117 100644 --- a/ERCS/erc-7811.md +++ b/ERCS/erc-7811.md @@ -1,7 +1,7 @@ --- eip: 7811 title: Wallet Asset Discovery -description: JSON-RPC method for wallets to share a user’s complete asset list with Dapps, including assets not easily discoverable through on-chain information alone. +description: JSON-RPC method for wallets to share a user’s full asset list with Dapps, including assets not easily found through on-chain data alone author: Luka Isailovic (@lukaisailovic), Konrad Kopp (@kopy-kat) discussions-to: https://ethereum-magicians.org/t/erc-7811-wallet-asset-discovery/21639 status: Draft @@ -63,18 +63,18 @@ type Asset = { type WalletGetAssetsResponse = Record; ``` -The key **SHOULD** be EIP-155 chainId +The key **SHOULD** be [EIP-155](./eip-155.md) chainId Asset fields: -`address` is the address of the asset as Hex. Native assets **MUST** use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` address specified by ERC-7528 +`address` is the address of the asset as Hex. Native assets **MUST** use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` address specified by [ERC-7528](./eip-7528.md) `balance` is the balance of the asset as Hex **`type`:** A string indicating the type of the asset. Common asset types include but **aren’t limited to**: -- **`ERC20`:** For ERC20 tokens -- **`ERC721`:** For ERC721 tokens (NFTs) +- **`ERC20`:** For [ERC-20](./eip-20.md) tokens +- **`ERC721`:** For [ERC-721](./eip-721.md) tokens (NFTs) - **`native`:** For the chain's native currency **`metadata`:** An optional object containing additional information about the asset. The specific fields within the metadata object may vary depending on the asset type and the wallet's implementation." @@ -200,7 +200,7 @@ If the wallet is using CAIP-25 authorization, wallet **SHOULD** include `assetDi } ``` -If the wallet supports ERC-5792 wallet **SHOULD** respond on `wallet_getCapabilities` request using the `assetDiscovery` key. Value should be an object with `supported` key and value `true` +If the wallet supports [ERC-5792](./eip-5792.md) wallet **SHOULD** respond on `wallet_getCapabilities` request using the `assetDiscovery` key. Value should be an object with `supported` key and value `true` Wallet **SHOULD** include this for every chainId. ```json @@ -213,6 +213,10 @@ Wallet **SHOULD** include this for every chainId. } ``` +## Rationale + +## Security Considerations + ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md). From ff4b3eb3ac8e275d5f055546caed66919ab0d3d0 Mon Sep 17 00:00:00 2001 From: Luka Isailovic Date: Sat, 9 Nov 2024 22:12:58 +0100 Subject: [PATCH 4/4] ident capabilities section --- ERCS/erc-7811.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7811.md b/ERCS/erc-7811.md index dae6be5117..c2a1895ff7 100644 --- a/ERCS/erc-7811.md +++ b/ERCS/erc-7811.md @@ -185,7 +185,7 @@ type Erc721Asset = { }; ``` -## Capabilities +### Capabilities If the wallet is using CAIP-25 authorization, wallet **SHOULD** include `assetDiscovery` key in the CAIP-25 `sessionsProperties` object. Value should be an object with `supported` key and value `true`