mirror of https://github.com/status-im/EIPs.git
85 lines
7.3 KiB
Markdown
85 lines
7.3 KiB
Markdown
---
|
|
eip: 681
|
|
title: URL Format for Transaction Requests
|
|
author: Daniel A. Nagy <daniel@ethereum.org>
|
|
type: Standards Track
|
|
category: ERC
|
|
status: Draft
|
|
created: 2017-08-01
|
|
requires: 20, 137, 831
|
|
---
|
|
|
|
## 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](https://solidity.readthedocs.io/en/develop/abi-spec.html). `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<sup>18</sup>. 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](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](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](https://creativecommons.org/publicdomain/zero/1.0/).
|