status-im
/
EIPs
mirror of https://github.com/status-im/EIPs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

EIP: Explicit reference to ERC #67 added. Protocol part changed to "ethpay" for distinction and compatibility.

This commit is contained in:
Daniel A. Nagy 2017-08-03 16:30:32 +02:00
parent 56a2454b07
commit 1546a4804b
1 changed files with 13 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
EIPS/pay_req_url_fmt.md
View File

@ -7,31 +7,25 @@
Category: ERC
Status: Draft
Created: 2017-08-01
Requires: #20, #137
Requires: #20, #67, #137
## Simple Summary
A standard way of representing 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.
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.
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.
Note that this is different from ERC #67, which is a URL format for representing arbitrary transactions and as such is more general and low-level. This ERC deals specifically with the important special case of payment requests.
## Specification
### Syntax
Payment request URLs contain "ethereum" in their schema (protocol) part and are constructed as follows:
Payment request URLs contain "ethpay" in their schema (protocol) part and are constructed as follows:
request = "ethereum" ":" beneficiary_address [ "/" token_contract_address ] [ "?" parameters ]
request = "ethpay" ":" beneficiary_address [ "/" token_contract_address ] [ "?" parameters ]
beneficiary_address = ethereum_address
token_contract_address = ethereum_address
ethereum_address = 40*40HEXDIG / ENS_NAME
@ -46,26 +40,15 @@ At present, the only `key` defined is `amount` and the corresponding `value` is
For the syntax of ENS_NAME, please consult ERC #137 defining Ethereum Name Service.
### Semantics
If `token_contract_address` is missing, then the payment is requested in the native token of the blockchain, which is Ether in our case.
The only mandatory field `beneficiary_address` denotes the address of the account to be credited with the requested token.
If `token_contract_address` is missing, then the payment is requested in the native token of the blockchain, which is Ether in our case. The only mandatory field `beneficiary_address` denotes the address of the account to be credited with the requested token.
Thus, if `token_contract_address` is missing, the target address of the transaction is `beneficiary_address`, otherwise it is
`token_contract_address`, with the appropriate transaction data, as defined in ERC #20 indicating the transfer of the given amount of tokens.
Thus, if `token_contract_address` is missing, the target address of the transaction is `beneficiary_address`, otherwise it is `token_contract_address`, with the appropriate transaction data, as defined in ERC #20 indicating the transfer of the given amount of tokens.
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 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.
The amount is to be interpreted in the decimal definition of the token, NOT the atomic unit. In case of Ether, it needs to
be multiplied by 10^18 to get the integer amount in Wei. For other tokens, the decimal value should be read from the
token contract before conversion.
The amount is to be interpreted in the decimal definition of the token, NOT the atomic unit. In case of Ether, it needs to be multiplied by 10^18 to get the integer amount in Wei. For other tokens, the decimal value should be read from the token contract before conversion.
Note that the indicated amount is only a suggestion and the user is free to change it. With no indicated amount, the user should be
prompted to enter the amount to be paid. In case of multiple suggestions, the user should have the option of choosing one or
enter their own.
Note that the indicated amount is only a suggestion and the user is free to change it. With no indicated amount, the user should be prompted to enter the amount to be paid. In case of multiple suggestions, the user should have the option of choosing one or enter their own.
## 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:`.
Additional parameters may be added, if popular use cases requiring them emerge in practice.
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:`. Additional parameters may be added, if popular use cases requiring them emerge in practice.