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

After EIP-747

Who is affected

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.

Original EIP · ← EIPs