ERC-7811 Wallet asset list lookup (Wallet Asset Discovery)
Draft · Accounts & wallets · created 2024-11-07
Defines the JSON-RPC method wallet_getAssets, through which a wallet tells an app the user's full list of assets. Even assets that are hard to discover from on-chain data alone can be provided directly by the wallet.
Why it is needed
Decentralized apps (dapps) today mainly read on-chain data recorded on the blockchain to determine a user's balance. This approach has limits. An app cannot see at once the assets a user holds split across multiple accounts and multiple chains, and it also misses assets that don't surface through on-chain lookups alone. As a result, an app may judge that the balance is insufficient and block the user's action even though the wallet could actually handle it. The wallet already knows the user's asset information, including assets not visible on-chain, but there is no standard channel to pass that information to the app. This proposal closes that gap by creating a common way for a wallet to hand over its known asset list to an app.
In depth
Request structure and required fields
The request consists of four fields: account, assetFilter, assetTypeFilter, and chainFilter. account is the only REQUIRED field, indicating which account's assets are being requested. assetFilter is an optional field that takes, per chain ID, a list of asset identifiers with address and type; assetTypeFilter is an optional field taking an array of asset types; and chainFilter is an optional field taking an array of chain IDs. All chain IDs must be valid EIP-155 chainIds.
assetFilter takes priority over the other filters
If assetFilter is given, the wallet MUST return only the assets specified within it, and assetTypeFilter and chainFilter are completely ignored in that case, because what those two filters would restrict is already implicitly defined within assetFilter. If assetFilter is omitted, the wallet SHOULD return all available assets for that account, and it is RECOMMENDED to sort them in descending order of the wallet's estimated value.
Set filters as narrowly as possible
Callers of this method SHOULD set assetFilter, assetTypeFilter, and chainFilter as finely as is reasonably possible. For example, an app interested in only a single token on one chain should supply a filter matching that. This avoids imposing excessive cost on the wallet and its underlying infrastructure, and also significantly improves the client app's performance.
Response structure
The response MUST be an object keyed by EIP-155 chainId, with each value an array of assets. Each asset has address, balance, type, and metadata fields. address is the asset's address, using the string native for the native asset. balance is a hex balance. type is a string indicating the asset kind, such as erc20, erc721, or native, among others not limited to these. metadata is an optional object holding additional information about the asset, whose fields can vary by asset type and wallet implementation.
Minimum metadata for well-known asset types
When an implementation of this ERC returns a well-known type, it MUST include at least the defined metadata fields, and MAY include more. erc20 carries name, symbol, and decimals; erc721 carries name, symbol, tokenId, and an optional tokenURI. native has address set to native and no metadata. Since type is a plain string, the type an app expects and the type a wallet returns can diverge, so two different assets must not share the same type, and new asset types should be defined by a later ERC.
How support is announced
A wallet using the CAIP-25 permissions approach SHOULD include wallet_getAssets in the methods array within sessionScopes under the eip155 namespace. A wallet supporting ERC-5792 SHOULD respond to a wallet_getCapabilities request with the assetDiscovery key, whose value is an object with a supported key set to true. It is advisable for a wallet to include this for every chainId.
This proposal is still in Draft stage
This proposal is in Draft status and its content may change. The Rationale and Security Considerations sections of the original have not been written yet. It is advisable to check the latest original text before implementing.