|Author||Daniel A. Nagy|
|Requires||20, 137, 831|
A standard way of representing various transactions, especially payment requests in Ethers and ERC #20 tokens as URLs.
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.
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.
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 ]
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
UNIT is a URL-encoded unicode string. If
UNIT is ETH, it always means a multiplier of 1018. 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
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.
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.
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:
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:
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.
gasPrice are suggested user-editable values for gas limit and gas price, respectively, for the requested transaction. It is acceptable to abbreviate
gas, the two are treated synonymously.
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 and related rights waived via CC0.
Please cite this document as:
Daniel A. Nagy, "EIP-681: URL Format for Transaction Requests [DRAFT]," Ethereum Improvement Proposals, no. 681, August 2017. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-681.