EIP-747 The wallet_watchAsset RPC method (wallet_watchAsset RPC Method)
Final · Other · EIP status Final · created 2018-08-13
Standardizes the wallet_watchAsset RPC method, which lets a website ask a wallet to add a specific token to its tracked asset list.
Why it is needed
One of a wallet's key functions is showing the user's assets. Without this standard, a wallet has to choose one of two approaches. First, the wallet can maintain a pre-approved asset list, in which case the wallet team is responsible for the list's security and bears the communication overhead of querying a large number of known assets. The original text notes that maintaining such an asset list itself becomes a political act, inviting harassment and listing pressure. Second, users can manually add tokens by entering the contract address themselves, which makes for a very poor user experience. Meanwhile, automatically displaying all assets causes tokens of no interest to pile up like spam and can be abused for phishing. Users typically learn about a token on a website, and at that moment both the site and the user want to track that token. The purpose of this proposal is to provide an API that lets both sides cooperate at this natural point of contact.
What changes
Today
- Wallets have to maintain their own asset list or query a centralized API for balances
- To see a token, users have to manually add it by entering the contract address themselves
- Querying a centralized API can link an account to an IP address
After EIP-747
- A website can call wallet_watchAsset to suggest adding a token to a wallet
- After validating the request, the wallet shows a prompt asking the user whether to add it
- If the name or symbol resembles a well known token, the wallet shows a warning to prevent phishing
Who is affected
- Users: Instead of manually adding a token by copying and pasting its address, a user can track it simply by approving a confirmation prompt raised by the website.
- Dapp developers: They can request, in a standardized way, that their service's token be displayed in a user's wallet.
- Wallet developers: The burden of maintaining a pre-approved asset list in advance is reduced, but they take on verification responsibilities such as checksum validation, similar-token warnings, and SSRF defenses.
In depth
Method definition and the immediate return rule
wallet_watchAsset is a new wallet-scoped RPC method that requests that a specified asset be added to the user's wallet list. If the request is valid, it MUST return true immediately, before prompting the user, and if invalid, it MUST return an error. A successful response only means the wallet recognized the request and found no problems; it does not guarantee that the user was prompted or that the asset was actually added. The specific meaning of "adding to the wallet" is left to the wallet implementation.
Parameter structure
The method takes a single WatchAssetParameters object as its parameter. Its structure is type: string (the asset's interface, e.g. 'ERC1046') and options: any. The type string SHOULD be the commonly used name of the interface implemented by the asset contract; defining global identifiers per asset type is out of scope for this EIP. The structure of options SHOULD be extended or modified depending on the asset type, and such changes MUST be specified in a separate EIP.
Return value and error conditions
The return happens immediately without waiting for user interaction. It returns boolean true if the request is valid, or an error if it is not. The error conditions the original text gives as examples (not exhaustive) are: the asset type is not recognized or not supported, the asset is on an allowlist or denylist (treated as an 'invalid' request since resolving the root cause requires developer action), image download failed, and the wallet did not fetch some of the metadata needed for display in order to prevent SSRF attacks.
ERC1046 type
options consists of address: string (required) and chainId?: number (optional). address MUST be a 0x-prefixed checksummed hexadecimal contract address, and the request MUST be treated as invalid if checksum validation fails. If chainId is omitted, the current chain ID is used as the default; the call MUST fail if the wallet does not recognize chainId or has no concept of an "active chain" and chainId is omitted. The wallet MUST fetch the ERC-1046 tokenURI and check the token type via the interop field, and MUST return an error if parsing fails or the type is unknown. It SHOULD compare name, symbol, address, and chainId against well known token lists and display a warning if the name or symbol is similar but the address differs, and SHOULD whitelist or blacklist specific ports and schemes to avoid SSRF attacks.
Legacy ERC20 type
The options structure and validation rules are the same as the ERC1046 type. address is required and the request is invalid if checksum validation fails, and the chainId handling rules are also the same. The rule for displaying a similar-token warning by comparing against well known token lists (SHOULD) is also the same. However, the original text RECOMMENDs using the ERC1046 type instead where possible, since it supports images and custom metadata.
Security considerations
Covers three issues. First, server side request forgery (SSRF). If the wallet sends a request to an arbitrary URL, it could be tricked into, for example, modifying data on a locally hosted redis database, so it is recommended to sanitize URIs by allowing only specific schemes and ports. Second, verification. If a symbol or name is identical or similar to another token, the user must be warned to prevent phishing scams. Third, fingerprinting. To prevent identifying users based on wallet behavior or registered assets, RPC calls must return immediately when a prompt appears or an error occurs, without waiting for the user to approve or reject.
Status and background
This EIP is a Final Standards Track (Interface) standard, created on August 13, 2018, and requires EIP-20, EIP-1046, and EIP-1193. The Rationale explains that asset display is a basic feature all dapp users expect, but relying on centralized API lookups harms decentralization and links accounts to IP addresses, and that updating asset lists over the network is especially costly on bandwidth constrained devices. It also notes that automatically registering assets turns tokens into something like spam mail, pointing out that airdropped tokens already exemplify this and are a major cause of network congestion.