ECIP 1037: Simple Interactive URI Scheme Source

AuthorCody Burns
StatusDraft
TypeStandards Track
CategoryInterface
Created2017-09-09

This ECIP is based off BIP 0021 can be referenced at https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki

==Abstract== This ECIP proposes a URI scheme for interacting with ethereum contract and accounts in a uniform standard format.

==Motivation== The purpose of this URI scheme is to enable users to easily make payments and interact with smart contracts by simply clicking links on webpages or scanning QR Codes. This allows for nfc, qr codes, or other similar non-interactive devices to store and transmit a standard message to a user, as well as interactive applications such as websites and dApps to present simple data to a user for action

==Specification==

=== General rules for handling (important!) ===

ETC 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. ETC clients SHOULD include the message field describing the actions of the code.

=== Operating system integration === Graphical ethereum clients SHOULD register themselves as the handler for the “ethereum:” 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.

=== General Format ===

Ethereum URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of an Ethereum 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 ===

ethereumurn = “ethereum:” ethereumaddress & ethereumchainid [ “?” ethereumparams ] ethereumaddress = *hexdig ethereumchainid = “id=” *digit ethereumparams = ethereumparam [ “&” ethereumparams ] ethereumparam = [ amountparam / gasparam / gaslimitparm / nonceparam / codeparam / labelparam / messageparam / otherparam / reqparam] amountparam = “amount=” *digit [ “.” *digit ] gasparam = “gas=” *digit gaslimitparm = “glmt=” *digit nonceparam = “n=” *digit codeparam = “code=” *hexdig 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 ECIP takes as separators.

The scheme component (“ethereum:”) 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 ===

*address: ethereum account or contract address in hexidecimal *id: eip 155 compliant chainid, used for sanity check *amount = amount of ether to transfer, denominated in ETC *gas = gas price *gaslmt = amount of gas transaction is not to exceed *nonce = account nonce *code = byte code data for transaction *label: Label for that address (e.g. name of receiver) *message: message that describes the transaction to the user ([[#Examples|see examples below]]) *(others): optional, for future extensions

=== EIP 155 Transaction ===

The intent of the uri is to pass all information nessecarry for forming a raw transaction to another device or service for signing.

A raw transaction should map the uri functions as follows for RLP encoding:

var rawTX = { nonce = nonceparam, gasprice = gasparam, gaslimit = gaslimitparam, to = ethereumaddress, value = amountparam * 10**18, data = codeparam, v = ethereumchainid, r = ‘’, s = ‘’ }

The parameters labelparam, messageparam, otherparam, and reqparam are not used in transaction signing and can be optionally displayed to the user to pass additional information about the transaction.

==== Transfer amount/size ====

If an amount is provided, it MUST be specified in decimal ETC. 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 ETC, and amount=50,000.00 is invalid.

ETC 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, so long as the majority of users work in ETC units, values should always be displayed in ETC by default, even if wei would otherwise be a more logical interpretation of the amount.

=== ENS addresses ===

The Ethereum Name Service is a protocol and ABI definition that provides flexible resolution of short, human-readable names to service and resource identifiers. This permits users and developers to refer to human-readable and easy to remember names, and permits those names to be updated as necessary when the underlying resource (contract, content-addressed data, etc) changes.

ENS names must conform to the following syntax:

::=