--- eip: 7811 title: Wallet Asset Discovery 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), Derek Rein (@arein), Chris Smith (@chris13524) discussions-to: https://ethereum-magicians.org/t/erc-7811-wallet-asset-discovery/21639 status: Draft type: Standards Track category: ERC created: 2024-11-07 requires: 20, 155, 721, 5792 --- ## 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 Hex = `0x${string}`; type Address = Hex; type AssetType = "native" | "erc20" | "erc721" | string; type Address = Hex; type AddressOrNative = Address | "native"; type Eip155ChainId = Hex; type WalletGetAssetsRequest = { account: Address; assetFilter?: Record< Eip155ChainId, { address: AddressOrNative; type: AssetType; }[] >; assetTypeFilter?: AssetType[]; chainFilter?: Hex[]; }; ``` `account` is a **REQUIRED** field that indicates for which account assets are requested. `assetFilter` is **OPTIONAL** field that accepts a list of assets identifiers. Each asset identifier is an object that contains `address` and `type` fields and is scoped by `chainId`, where ChainId **MUST** be a valid [EIP-155](./eip-155.md) chainId. If the `assetFilter` field is provided, the wallet **MUST** only return the assets specified within it, even if `assetTypeFilter` or `chainFilter` could have further filtered the result. This effectively disregards the `assetTypeFilter` and `chainFilter` fields entirely. The reason for this is that they are already implicitly defined within the `assetFilter`. If the `assetFilter` field is omitted, the wallet **SHOULD** return all available assets for the requested account. It is **RECOMMENDED** that the returned assets be ordered by estimated value in descending order, as determined by the wallet. `assetTypeFilter` is an **OPTIONAL** field that specifies an array of asset types, as defined in this ERC. If `assetTypeFilter` field is provided, wallet **MUST** include only assets with those types in the response. `chainFilter` is an **OPTIONAL** field that specifies an array of chain ids, where each value in the array **MUST** be a valid [EIP-155](./eip-155.md) chainId Consumers of `wallet_getAssets` SHOULD set `assetFilter`, `assetTypeFilter` and `chainFilter` with as granular as reasonably possible values. For example, if an app is only interested in interacting with a single token on a single chain, it should provide filters for this. Doing this both ensures that wallets and the underlying infrastructure do not incur excessive cost, as well as significantly increased performance to client applications. #### Example request ```json { "account": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "assetFilter": { "0x1": [ { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "type": "erc20" }, { "address": "native", "type": "native" } ], "0xa": [ { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "type": "erc20" } ] }, "assetTypeFilter": ["ERC20", "native"], "chainFilter": ["0x1"] } ``` #### Response schema ```ts type Asset = { address: AddressOrNative; balance: Hex; type: string; metadata: any; }; type WalletGetAssetsResponse = Record; ``` The key **MUST** be [EIP-155](./eip-155.md) chainId Asset fields: `address` is the address of the asset as `Hex` or `native` string for native assets. `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 [ERC-20](./eip-20.md) tokens - **`erc721`:** For [ERC-721](./eip-721.md) tokens (NFTs) - **`native`:** For the chain's native asset **`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": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "balance": "0xcaaea35047fe5702", "type": "ERC20", "metadata": { "name": "Token", "symbol": "TOK", "decimals": 18 } }, { "address": "native", "balance": "0xcaaea35047fe5702", "type": "native" } ], "0xa": [ { "address": "0x456", "balance": "0xcd5595", "type": "ERC721", "metadata": { //... } } ] } ``` ### Well-known asset types Below are expansions of `metadata` for well-known asset types. Implementations that are compliant with this ERC and return these well-known asset types **MUST** return at least these fields in `metadata`. Implementations **MAY** return more fields than specified here. 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 future ERCs. **Native** ```ts type NativeAsset = { address: "native"; balance: Hex; type: "native"; }; ``` Example: ```json { "address": "native", "balance": "0xcaaea35047fe5702", "type": "native" } ``` **ERC-20 Token** ```ts type Erc20Asset = { address: Hex; balance: Hex; type: "erc20"; metadata: { name: string; symbol: string; decimals: number; }; }; ``` Example: ```json { "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "balance": "0xcaaea35047fe5702", "type": "erc20", "metadata": { "name": "Token", "symbol": "TOK", "decimals": 18 } } ``` **ERC-721 Token** ```ts type Erc721Asset = { address: Hex; balance: Hex; type: "erc721"; metadata: { name: string; symbol: string; tokenId: Hex; tokenURI?: string; }; }; ``` Example: ```json { "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "balance": "0x01", "type": "erc721", "metadata": { "name": "Thor's hammer", "symbol": "THOR", "tokenId": "0x1", "tokenURI": "ipfs://hash" } } ``` ### Capabilities If the wallet is using [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/0848f06f6cfc29ce619bccdd5035c1d500033b21/CAIPs/caip-25.md) authorization, wallet **SHOULD** include `wallet_getAssets` in the `methods` array in `sessionScopes` of `eip155` namespace. 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 { "0xa": { "assetDiscovery": { "supported": true } } } ``` ## Rationale ## Security Considerations ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).