EIP 681: URL Format for Transaction Requests

Simple Summary

A standard way of representing various transactions, especially payment requests in Ethers and ERC #20 tokens as URLs.

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 payment requests 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 payment transaction only to be confirmed by the (authenticated) user.

Motivation

The convenience of representing payment requests by standard URLs has been a major factor in the wide adoption of Bitcoin. Bringing a similarly convenient mechanism to Ethereum would speed up its acceptance as a payment platform among end-users. In particular, URLs embedded in broadcast Intents are the preferred way of launching applications on the Android operating system and work across practically all applications. Desktop web browsers have a standardized way of defining protocol handlers for URLs with specific protocol specifications. Other desktop applications typically launch the web browser upon encountering a URL. Thus, payment request URLs could be delivered through a very broad, ever growing selection of channels.

This specification supersedes ERC #67, which is a URL format for representing arbitrary transactions in a low-level fashion. This ERC focuses specifically on the important special case of payment requests, while allowing for other, ABI-specified transactions.

Specification

Syntax

Payment request URLs contain “ethereum” in their schema (protocol) part and are constructed as follows:

request                 = erc831_part target_address [ "@" chain_id ] [ "/" function_name ] [ "?" parameters ]
erc831_part             = schema and optional prefix as defined in #831 - typically "ethereum" ":" [ "pay-" ] in this case
target_address          = ethereum_address
chain_id                = 1*DIGIT
function_name           = STRING
ethereum_address        = ( "0x" 40*40HEXDIG ) / ENS_NAME
parameters              = parameter *( "&" parameter )
parameter               = key "=" value
key                     = "value" / "gas" / "gasLimit" / "gasPrice" / TYPE
value                   = number / ethereum_address / STRING
number                  = [ "-" / "+" ] *DIGIT [ "." 1*DIGIT ] [ ( "e" / "E" ) [ 1*DIGIT ] [ "+" UNIT ]

Where TYPE is a standard ABI type name, as defined in Ethereum Contract ABI specification. STRING is a URL-encoded unicode string of arbitrary length, where delimiters and the percentage symbol (%) are mandatorily hex-encoded with a % prefix.

UNIT is a URL-encoded unicode string. If UNIT is ETH, it always means a multiplier of 10¹⁸. If it is something else AND the addressed contract has a symbol field exactly matching this string AND the contract has a decimals field, then 10 to that power is used as a multiplier. Otherwise, the payment request is deemed invalid. Applications that have no access to the blockchain should refuse accepting requests with a non-empty UNIT, if it is not ETH.

Note that a number can be expressed in scientific notation, with a multiplier of a power of 10. The use of this notation is strongly encouraged when expressing monetary value in Ethers or ERC #20 tokens in atomic units (e. g. Wei, in case of Ether).

If key in the parameter list is value, gasLimit, gasPrice or gas then value MUST be a number. Otherwise, it must correspond to the TYPE string used as key.

For the syntax of ENS_NAME, please consult ERC #137 defining Ethereum Name Service.

Semantics

target_address is mandatory and denotes either the beneficiary of native token payment (see below) or the contract address with which the user is asked to interact.

chain_id is optional and contains the decimal chain ID, such that transactions on various test- and private networks can be requested. If no chain_id is present, the client’s current network setting remains effective.

If function_name is missing, then the URL is requesting payment in the native token of the blockchain, which is Ether in our case. The amount is specified in value parameter, in the atomic unit (i.e. Wei). The use of scientific notation is strongly encouraged. For example, requesting 2.014 ETH to address 0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359 would look as follows: ethereum:0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359?value=2.014e18

Requesting payments in ERC #20 tokens involves a request to call the transfer function of the token contract with an address and a uint256 typed parameter, containing the beneficiary address and the amount in atomic units, respectively. For example, requesting a Unicorn to address 0x8e23ee67d1332ad560396262c48ffbb01f93d052 looks as follows: ethereum:0x89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7/transfer?address=0x8e23ee67d1332ad560396262c48ffbb01f93d052&uint256=1

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.

If the payer client has access to the blockchain, the interface should display the amount in the units as specified in the token contract. Otherwise, it should be displayed as expressed in the URL.

Note that the indicated amount is only a suggestion (as are all the supplied arguments) which the user is free to change. With no indicated amount, the user should be prompted to enter the amount to be paid.

Similarly gasLimit and gasPrice are suggested user-editable values for gas limit and gas price, respectively, for the requested transaction. It is acceptable to abbreviate gasLimit as gas, the two are treated synonymously.

Rationale

The proposed format is chosen to resemble bitcoin: URLs as closely as possible, as both users and application programmers are already familiar with that format. In particular, this motivated the omission of the unit, which is often used in Ethereum ecosystem. Handling different orders of magnitude is delegated to the application, just like in the case of bitcoin:, but lacking access to the block chain, the application can take a hint from the exponent in the URL. Additional parameters may be added, if popular use cases requiring them emerge in practice.

Compatibility and Versioning

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

Copyright

Copyright and related rights waived via CC0.