Proposal for AddToken URI standard

[smilingkylan]

---

eip: 961
title: URL Format for Tokens
status: Active
type: Standards Track
author: Kylan Hurt <kylan@edgesecure.co>, Eliran Zach <eliran@edgesecure.co>
created: 2018-04-01
requires: 20, 137, 831

---

Simple Summary

A standard way of representing token information, facilitating the process of adding ERC #20 tokens as URLs on the application layer.

Abstract

URLs embedded in QR-codes, hyperlinks in web-pages, emails or chat messages provide for robust cross-application signaling between very loosely coupled applications. A standardized URL format for fundamental token information allows for instant invocation of the user's preferred wallet application (even if it is a webapp or a swarm đapp), with the correct parameterization of the token's information only to be confirmed by the user.

Motivation

The convenience of representing payment requests by standard URLs has been a significant factor in the cryptocurrency. Extending this convenient mechanism to support embedding of basic token information would help to facilitate the usage of Ethereum-based tokens. In particular, QR-code embedded URLs could be generated by token-generators to help users track the tokens via any wallet software that has the ability to scan QR codes (particularly mobile wallets). For example, rather than users needing to find the contract address and number of decimal places for a given token through an online directory, they could simply scan a QR-code provided by the token generator with this data embedded. The wallet software could then automatically add the tokens to the user's wallet. This would improve the user experience associated with purchasing and holding tokens as a digital asset.

Specification

Syntax

Token data URLs contain "ethereum" in their schema (protocol) part and are constructed as follows:

request                 = "ethereum" ":" "token_info-" target_address "@" chain_id [ "?" parameters ]
target_address          = ethereum_address
chain_id                = 1*DIGIT
ethereum_address        = ( "0x" 40*40HEXDIG ) / ENS_NAME
parameters              = parameter *( "&" parameter )
parameter               = key "=" value
key                     = "symbol" / "decimals" / "name" / "type"
value                   = STRING / number (0-18) / STRING / STRING

Where all of the key + value pairs are optional, allowing for maximum flexibility on the application layer.

Semantics

target_address is mandatory and denotes the contract address with which the user is asked to interact.

chain_id is mandatory and contains the decimal chain ID, such that transactions on various test- and private networks can be requested.

If using ENS names instead of hexadecimal addresses, the resolution is up to the payer, at any time between receiving the URL and sending the transaction. Hexadecimal addresses always take precedence over ENS names, i.e. even if there exists a matching ENS name consisting of 40 hexadecimal digits, it should never be resolved. Instead, the hexadecimal address should be used directly.

1. symbol (optional) is the token symbol (STRING) - Defaults to "SYM"
2. decimals (optional) is a whole number between 0 and 18 (inclusive) - Defaults to 18
3. name (optional) is a more user-friendly name (STRING) for the token, typically the name of the project that generated the tokens - Defaults to the value of symbol
4. type (optional) is the type of token (STRING), e.g. "ERC20". - Defaults to "ERC20"

Note: STRING is a URL-encoded unicode string of arbitrary length, where delimiters and the percentage symbol (%) are mandatorily hex-encoded with a % prefix.

Rationale

The proposed format is chosen to resemble ethereum:pay URLs as closely as possible, as both users and application programmers are already familiar with that format. Individuals generating these URLs are free to add and remove arbitrary parameters as they see fit.

Compatibility and Versioning

Future upgrades that are partially or fully incompatible with this proposal must use a prefix other than token_info- that is separated by a dash (-) character from whatever follows it, as specified by ERC #831.

Copyright

Copyright and related rights waived via CC0.

[MattLongCT]

I really like this idea! Definitely should be added to the main branch for more people to review!

[Arachnid]

Please rename this to eip-961.md and set the number as 961 here.

[smilingkylan]

Okay, will do as soon as I can get around to it.

[Arachnid]

Please update the formatting as per the new formatting standards in EIP-1 and EIP-X.

[Arachnid]

s/Standard/Standards/

[Arachnid]

This seems too generic, and may already be in use. Could you pick something more token-specific, or else make sure this is compatible with other uses of that URI?

[ligi]

token should not be optional here - for this ERC "token-" should be mandatory

[ligi]

eg should be e.g.
Also wondering if this should be a list - and perhaps in the form like defined in #881

[ligi]

token should not be optional here - for this ERC "token-" should be mandatory

[ligi]

Great initiative and use of #831 - just have some minor change requests.

[ligi]

what does "see below" refer to? As far as I see this should always be the "contract address" of the token

[smilingkylan]

Looks like it could be hold-over from the earlier EIP that we referenced. I will try to make the edit later today. Thank you for the heads up.

[ligi]

I think chain_id should not be optional. A token is always bound to a chain as far as I see - so in contrast to the payment URLs it is really important we always know the chainId

[smilingkylan]

Understood. I will make the adjustment.

[ligi]

One more thing that came up when reading over it again. You reference STRING, but removed the definition that was present in 681:

STRING is a URL-encoded unicode string of arbitrary length, where delimiters and the percentage symbol (%) are mandatorily hex-encoded with a % prefix.

I think STRING needs to be defined here when used or the definition needs to be imported somehow - but this way it does not compute ;-)

Also there should be the dependency to ERC #20 #137 #831 defined in the header like this:
requires: 20, 137, 831

[ligi]

Thanks for making the requested changes - LGTM from my side now

[freeatnet]

@kylanhurt How would the wallet discern the authenticity of the token information? In particular, what is to stop a malicious party from creating a URI containing an arbitrary token address combined with a name and symbol that would lead a user to believe they are looking at another, well-known, token?

[Arachnid]

This should be 'Draft'.

[Arachnid]

Please remove indentation here.

[Arachnid]

Standards track EIPs must also specify a category.

[ligi]

Added this EIP here: https://github.com/ethereum-magicians/scrolls/wiki/Wallet-Ring - also kindly invite you to join the ring

[smilingkylan]

@kylanhurt How would the wallet discern the authenticity of the token information? In particular, what is to stop a malicious party from creating a URI containing an arbitrary token address combined with a name and symbol that would lead a user to believe they are looking at another, well-known, token?

There is no way to trustlessly authenticate token information. Users will have to be suspicious about from whom or where they are getting the token information. Unfortunately there's no way around this unless someone wants to become a token list / directory curator (which is a lot of work).

[axic]

@kylanhurt are you still pursuing this ERC?

[github-actions]

There has been no activity on this pull request for two months. It will be closed in a week if no further activity occurs. If you would like to move this EIP forward, please respond to any outstanding feedback or add a comment indicating that you have addressed all required feedback and are ready for a review.

[github-actions]

This pull request was closed due to inactivity. If you are still pursuing it, feel free to reopen it and respond to any feedback or request a review in a comment.