Abstract
This document describes an URI scheme for making EToken payments. It's heavily based on Bitcoin BIP-0021.
Motivation
The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.
Specification
General rules for handling (important!)
Clients MUST NOT act on URIs without getting the user's authorization. They SHOULD require the user to manually approve each payment individually, though in some cases they MAY allow the user to automatically make this decision.
Operating system integration
Graphical clients SHOULD register themselves as the handler for the "etoken:" URI scheme by default, if no other handler is already registered. If there is already a registered handler, they MAY prompt the user to change it once when they first run the client.
The scheme component ("etoken:") could be changed to other string if the client only supports one of EToken currencies. For example for OpenTugrik currency it could be “opentugrik:”. In this case it wouldn't cause conflicts with other clients that could be installed on user's device.
General Format
URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of an Ethereum account address, and the query component provides additional payment options.
Elements of the query component may contain characters outside the valid range. These must first be encoded according to UTF-8, and then each octet of the corresponding UTF-8 sequence must be percent-encoded as described in RFC 3986.
ABNF grammar
(See also a simpler representation of syntax below)
urn = "etoken:" address [ "?" params ]
address = *hexchar
params = param [ "&" params ]
param = [ amountparam / currencyparam / labelparam / messageparam / otherparam / reqparam ]
amountparam = "amount=" *digit [ "." *digit ]
currencyparam = "currency=" *qchar
labelparam = "label=" *qchar
messageparam = "message=" *qchar
otherparam = qchar *qchar [ "=" *qchar ]
reqparam = "req-" qchar *qchar [ "=" *qchar ]
Here, "qchar" corresponds to valid characters of an RFC 3986 URI query component, excluding the "=" and "&" characters, which this specification takes as separators.
The scheme component ("etoken:" in this specification) is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys.
Query Keys
All parameters except of address are optional:
- address: Ethereum address or ICAP (required)
- amount: amount of EToken currency
- message: comment, description, reference number or order ID
- label: label for the address (e.g. name of receiver)
- currency: EToken currency name (for clients that support multiple currencies)
- (others): optional, for future extensions
Transfer amount/size
If an amount is provided, it MUST be specified in decimal units. All amounts MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions. I.e. amount=50.00 or amount=50 is treated as 50 EToken coins, and amount=50,000.00 is invalid.
Clients MAY display the amount in any format that is not intended to deceive the user. They SHOULD choose a format that is foremost least confusing, and only after that most reasonable given the amount requested. For example, region specific formatting or additional coloring could be applied to make amounts easily readable and improve UX.
Accessibility (URI scheme name)
Should someone from the outside happen to see such a URI, the URI scheme name already gives a description. A quick search should then do the rest to help them find the resources needed to make their payment.
Compatibility
Variables which are prefixed with a req- are considered required. If a client does not implement any variables which are prefixed with req-, it MUST consider the entire URI invalid. Any other variables which are not implemented, but which are not prefixed with a req-, can be safely ignored.
If currency is specified in URI but is not supported, the client MUST consider the entire URI invalid. Currency could be contained in parameter or in ICAP if it's used instead of Ethereum address. For example:
- XE50TSTPOOLABC123456 – TST currency
- XE04TGRSHOPI12345678 – TGR currency
Appendix
Simpler syntax
This section is non-normative and does not cover all possible syntax. Please see the BNF grammar above for the normative syntax.
[foo] means optional, <bar> are placeholders
etoken:<address>[?amount=<amount>][?currency=<currency>][?label=<label>][?message=<message>]
Examples
Just the address:
etoken:490c0dd13bfea5865ca985297cf2bed3f77beb5d
Just ICAP address:
etoken:XE04TGRSHOPI12345678
Address with name:
etoken:490c0dd13bfea5865ca985297cf2bed3f77beb5d?label=Big-Boss
Request 20.30 TST to "Big-Boss":
etoken:490c0dd13bfea5865ca985297cf2bed3f77beb5d?label=Big-Boss&amount=20.30¤cy=TST
Request 42 TST with message (the most used case!):
etoken:490c0dd13bfea5865ca985297cf2bed3f77beb5d?amount=42¤cy=TST&message=Donation%20for%20education
Request 42 OpenTugriks with custom client:
opentugrik:490c0dd13bfea5865ca985297cf2bed3f77beb5d?amount=42
Request 100.0016 TST to ICAP address (notice that currency is specified inside ICAP):
etoken:XE50TSTPOOLABC123456?label=Store%2042&amount=100.0016&message=Invoice%20payment
Additional notes
- Characters must be URI encoded properly.
- Note that using double slash (etoken://) is incorrect - see RFC3986 for details.