EIP-747: wallet_watchAsset RPC Method

Abstract #

This EIP standardizes a new wallet-scoped RPC method, wallet_watchAsset, to allow a client to suggest a token for the user's wallet to track.

Motivation #

Today, one of the major uses of Ethereum wallets is to track users' assets. Without this EIP, each wallet either needs to pre-load a list of approved assets, or users must manually add assets to their wallet. In the first case, wallets are burdened with both the security of managing this list, as well as the bandwidth of mass polling for known assets on their wallet. In the second case, the user experience is terrible.

Specification #

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

A new RPC method, wallet_watchAsset is added. wallet_watchAsset requests that a specified asset be added to the user's wallet. It MUST return true if the asset was successfully added, or error if it was not. The meaning of "added to the user's wallet" is dependent on the wallet implementation. A successful call to wallet_watchAsset SHOULD indicate that the specified asset is listed in the user's wallet (regardless of whether it already was listed).

wallet_watchAsset Parameters #

The wallet_watchAsset method takes a single parameter, a WatchAssetParameters object, which is defined as follows:

interface WatchAssetParameters {
  type: string; // The asset's interface, e.g. 'ERC20'
  options: {
    address: string; // The hexadecimal Ethereum address of the token contract
    chainId?: number; // The chain ID of the asset. If empty, defaults to the current chain ID.
    name?: sring; // A human-readable name. If the contract has a `name()` method, it MUST override this parameter.
    symbol?: string; // A ticker symbol or shorthand, up to 5 alphanumerical characters. If the contract has a `symbol()` method, it MUST override this parameter.
    decimals?: number; // The number of asset decimals. If the contract has a `decimals()` method, it MUST override this parameter.
    image?: string; // A string url of the token logo
  };
}

The type string SHOULD be the commonly accepted name of the interface implemented by the asset's contract, e.g. ERC20. Defining the global identifiers for different asset types is beyond the scope of this EIP. address is required, and the other fields are optional. address should be the hexadecimal Ethereum address of the token contract. symbol is a ticker symbol or shorthand, up to 5 alphanumerical characters. decimals is the number of asset decimals. image is a string url of the token logo. The following image formats must be supported:

• GIF
• PNG
• JPG/JPEG
• SVG

If the resolved image is a bitmap, its dimensions SHOULD not exceed 512x512 pixels. Neither the URI nor the image it resolves to SHOULD have a size larger than 256kb.

This interface SHOULD be extended or modified depending on the asset type. These changes MUST be specified in a separate EIP.

If the wallet does not recognize the chainId, or the chainId is blank and the wallet does not have a concept of "active" chain, the call MUST fail.

If the both the ERC-20 name() function and the name field are provided, the name() function takes precedence. If the two fields don't match, a warning MUST be displayed to the user. o avoid fingerprinting, this warning MUST be displayed regardless of whether the wallet decides to force the call to fail.

wallet_watchAsset SHOULD check the ERC-20 name() and/or symbol() (if applicable) and the provided name and/or symbol fields against a list of well-known tokens. If the address and/or chainId don't match any known addresses for those tokens, a warning MUST be displayed to the user. To avoid fingerprinting, this warning MUST be displayed regardless of whether the wallet decides to force the call to fail.

If the asset is already listed in the user's wallet, a prompt to "update" the token information MUST be displayed to the user, even if no information is changed (this is to avoid fingerprinting). Regardless of whether the user chooses to update the token information, the call SHOULD succeed.

wallet_watchAsset Returns #

wallet_watchAsset returns the boolean value true if the the asset is listed in the user's wallet (regardless of whether the asset was already listed), and an error otherwise. An error might occur in the following cases (but is not limited to these cases):

• The user declines a request to add a formerly unknown token
• The asset type is unrecognized/unsupported
• Downloading the image failed to load
• The wallet blocked the asset, either due to an allowlist or denylist

Rationale #

Displaying a user's assets is a basic feature that every modern dapp user expects. However, keeping this list, and polling for it from the network can be costly, especially on bandwidth constrained devices.

Most wallets today either manage their own assets list, which they store client side, or they query a centralized API for balances, which reduces decentralization, letting that API's owner easily correlate account holders with their IP addresses.

Maintaining one of these assets lists becomes a political act, and maintainers can be subject to regular harassment and pressure to list otherwise unknown assets.

Furthermore, automatically listing assets makes assets into a sort of spam mail: Users suddenly seeing new assets that they don't care about in their wallet can be used to bombard them with information that they didn't opt into.

This phenomenon is exacerbated by the trend towards airdropped tokens, which has been a cause of network congestion, because spamming people with new tokens has so far been rewarded with user attention.

While some people might suggest we begin a TCR of trusted tokens to watch, this would not solve the client-side bandwidth issues, nor the airdropped token spam issues. What we really want is a small list of tokens the user cares about.

Most of the time a user is adding a asset, they learned about it on a website. At that moment, there is a natural alignment of interests, where the website wants the user to track their asset, and the user wants to track it. This is a natural point to introduce an API to easily allow these parties to collaborate, without involving the politics of the wallet's developers.

Test Cases #

In the case of assets of type ERC20, this method works as follows.

ethereum.request({
  method: 'wallet_watchAsset',
  params: {
    type: 'ERC20',
    options: {
      address: '0xb60e8dd61c5d32be8058bb8eb970870f07233155',
      chainId: 1,
      image: 'https://foo.io/token-image.svg',
    },
  },
});
  .then((success) => {
    if (success) {
      console.log('FOO successfully added to wallet!')
    } else {
      throw new Error('Something went wrong.')
    }
  })
  .catch(console.error)

Upon calling this request, the user must be prompted with the opportunity to add this token to their wallet:

Security Considerations #

SSRF #

Wallets should be careful about making arbitrary requests to URLs. As such, it is recommended for wallets to sanitize the URI by whitelisting specific schemes and ports. A vulnerable wallet could be tricked into, for example, modifying data on a locally-hosted redis database.

Validation #

Wallets should warn users if the symbol or name matches or is similar to another token, or if the name or symbol doesn't match the ERC-20 ones.

Fingerprinting #

To avoid fingerprinting based on wallet behavior, the warning discussed in the Validation subsection above has to be displayed even if the user has no option to add the token in the event of a failed validation check. Additionally, the user must be prompted to "update" the asset, even if no changes are made.

Copyright #

Copyright and related rights waived via CC0.