Update eip-747 to watchAsset

EIPS/eip-747.md

@@ -1,33 +1,33 @@
 ---
 eip: <to be assigned>
-title: Add eth_watchToken to Provider
+title: Add wallet_watchAsset to Provider
 author: Dan Finlay (@danfinlay), Esteban Mino (@estebanmino)
 discussions-to: https://ethereum-magicians.org/t/eip-747-eth-watchtoken/1048
 status: WIP
 type: Interface
-category Interface
+category: Interface
 created: August 13, 2018
 ---
 
 <!--You can leave these HTML comments in your merged EIP and delete the visible duplicate text guides, they will not appear and may be helpful to refer to if you edit it again. This is the suggested template for new EIPs. Note that an EIP number will be assigned by an editor. When opening a pull request to submit your EIP, please use an abbreviated title in the filename, `eip-draft_title_abbrev.md`. The title should be 44 characters or less.-->
 
 ## Simple Summary
 <!--"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the EIP.-->
-A method for allowing users to easily track new tokens with a suggestion from sites they are visiting.
+A method for allowing users to easily track new assets with a suggestion from sites they are visiting.
 
 ## Abstract
 <!--A short (~200 word) description of the technical issue being addressed.-->
-Web3 JavaScript wallet browsers may implement `eth_watchToken()` to allow any website to suggest a token for the user's wallet to track.
+Web3 JavaScript wallet browsers may implement `wallet_watchAsset()` to allow any website to suggest a token for the user's wallet to track.
 
 ## Motivation
 <!--The motivation is critical for EIPs that want to change the Ethereum protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the EIP solves. EIP submissions without sufficient motivation may be rejected outright.-->
-Today, one of the major uses of ethereum wallets is to acquire and track tokens. Currently, each wallet either needs to pre-load a list of approved tokens, or users need to be stepped through a tedious process of adding a token for their given wallet.
+Today, one of the major uses of ethereum wallets is to acquire and track assets. Currently, each wallet either needs to pre-load a list of approved assets, or users need to be stepped through a tedious process of adding an asset for their given 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 tokens on 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.
 
-By leveraging a user's existing trust with websites they are learning about tokens on, we are able to decentralize the responsibility of managing a user's list of known tokens.
+By leveraging a user's existing trust with websites they are learning about assets on, we are able to decentralize the responsibility of managing a user's list of known assets.
 
 ## Specification
 <!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Ethereum platforms (go-ethereum, parity, cpp-ethereum, ethereumj, ethereumjs, and [others](https://github.com/ethereum/wiki/wiki/Clients)).-->
@@ -36,23 +36,27 @@ A new method is added to web3 browsers' ethereum providers:
 ```javascript
 
 /**
- * @param {String} tokenAddress - The address of the token to add
- * @param {String} tokenSymbol - The abbreviated name of the token to add.
- * @param {Number} tokenDecimals - The number of decimals to use when rendering the token count.
- * @param {String} tokenImage - Optional - The URL for the image to render for the token's icon. (TODO: Finalize type of this parameter.)
- * @returns {Promise} success - Whether the user added the token to their wallet.
- */
-async function eth_watchToken (
-  tokenAddress,
-  tokenSymbol,
-  tokenDecimals,
-  tokenImage
+* @param  {Object}  opts - The options specifing the asset `type` and `options` specific for each of asset.
+* @returns  {Promise} success - Whether the user added the asset to their wallet.
+*/
+async  function  wallet_watchAsset (
+  opts
 ) {
-  /* Implementation would go here */
+/* Implementation would go here */
 }
 
 // Sample usage:
-web3.eth.watchToken(tokenAddress, tokenSymbol, tokenDecimals [, tokenImage] )
+web3.wallet.watchAsset({ type, options })
+```
+As there are several types of different assets, this method has to provide support for each of them in a separate way. If it doesn't, it should give a response according to that.
+
+In the case of assets of type `ERC20`, this method works as follows.
+
+```javascript
+web3.wallet.watchAsset({ 
+	type: 'ERC20', 
+	options: { tokenAddress, tokenSymbol, tokenDecimals [, tokenImage] }
+})
 ```
 
 The `tokenImage` parameter should link to a web-standard image format (png, jpg, gif) of a reasonable size. To establish a baseline, let's say no greater than 512x512 pixels, and no greater than 256kb. However, this can be a client-defined setting.
@@ -65,19 +69,19 @@ If the user adds this token, it should appear somewhere in their wallet's UI, wi
 
 ## Rationale
 <!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.-->
-Displaying a user's tokens 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.
+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 token list, which they store client side, or they query a centralized API for token balances, which reduces decentralization, letting that API's owner easily correlate account holders with their IP addresses.
+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 token lists becomes a political act, and maintainers can be subject to regular harrassment and pressure to list otherwise unknown tokens.
+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 tokens makes tokens into a sort of spam mail: Users suddenly seeing new tokens that they don't care about in their wallet can be used to bombard them with information that they didn't opt into.
+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 token, 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 token, 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.
+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.
 
 ## Implementation
 <!--The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.-->