From 640a8a7616222f7667341abbe483724d4123aa41 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Tue, 1 Aug 2017 11:53:19 +0200 Subject: [PATCH 01/17] EIP: Payment request URL specification for QR codes, hyperlinks and Android Intents. --- EIPS/pay_req_url_fmt.md | 65 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 EIPS/pay_req_url_fmt.md diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md new file mode 100644 index 00000000..804baafe --- /dev/null +++ b/EIPS/pay_req_url_fmt.md @@ -0,0 +1,65 @@ +## Preamble + + EIP: + Title: URL Format for Payment Requests + Author: Daniel A. Nagy + Type: Standard Track + Category: ERC + Status: Draft + Created: 2017-08-01 + Requires: #20 + +## 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 webpages, 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 parametrization 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 +practiaclly 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. + +## Specification + +### Syntax +Payment request URLs contain "ethereum" in their schema (protocol) part and are constructed as follows: + + request = "ethereum" ":" beneficiary_address [ "/" token_contract_address ] [ "?" parameters ] + beneficiary_address = ethereum_address + token_contract_address = ethereum_address + ethereum_address = 40*40HEXDIG + parameters = parameter *( "&" parameter ) + parameter = key "=" value + +At present, the only `key` defined is `amount` and the corresponding `value` is a decimal number. Thus: + + key = "amount" + value = *DIGIT [ "." 1*DIGIT ] + +### 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. + +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. + +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. + +## 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. From b7f8744d9d8026dec909b2baf2e58a0ffc5f5c99 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Tue, 1 Aug 2017 13:40:10 +0200 Subject: [PATCH 02/17] EIP: Add ENS support to payment requests --- EIPS/pay_req_url_fmt.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index 804baafe..719d3986 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -7,22 +7,22 @@ Category: ERC Status: Draft Created: 2017-08-01 - Requires: #20 + Requires: #20, #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 webpages, emails or chat messages provide for robust cross-application signaling between very +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 parametrization of the payment transaction only to be +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 -practiaclly all applications. Desktop web browsers have a standardized way of defining protocol handlers for URLs with specific protocol +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. @@ -34,7 +34,7 @@ Payment request URLs contain "ethereum" in their schema (protocol) part and are request = "ethereum" ":" beneficiary_address [ "/" token_contract_address ] [ "?" parameters ] beneficiary_address = ethereum_address token_contract_address = ethereum_address - ethereum_address = 40*40HEXDIG + ethereum_address = 40*40HEXDIG / ENS_NAME parameters = parameter *( "&" parameter ) parameter = key "=" value @@ -43,6 +43,8 @@ At present, the only `key` defined is `amount` and the corresponding `value` is key = "amount" value = *DIGIT [ "." 1*DIGIT ] +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. @@ -50,6 +52,9 @@ The only mandatory field `beneficiary_address` denotes the address of the accoun 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. + 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. From 56a2454b07e02428bee7165345710edf2e5e4a1f Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Tue, 1 Aug 2017 14:17:23 +0200 Subject: [PATCH 03/17] EIP: Explicit disclaimer for hexadecimal addresses taking priority over ENS names. --- EIPS/pay_req_url_fmt.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index 719d3986..3988c6a9 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -52,8 +52,9 @@ The only mandatory field `beneficiary_address` denotes the address of the accoun 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. +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 From 1546a4804b45c29d78a18a8281ce03066467b6db Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Thu, 3 Aug 2017 16:30:32 +0200 Subject: [PATCH 04/17] EIP: Explicit reference to ERC #67 added. Protocol part changed to "ethpay" for distinction and compatibility. --- EIPS/pay_req_url_fmt.md | 43 +++++++++++++---------------------------- 1 file changed, 13 insertions(+), 30 deletions(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index 3988c6a9..c6c45fce 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -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. From 2b8a1608999c931f4d92afdea60eb1d76dea5804 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Thu, 3 Aug 2017 16:47:06 +0200 Subject: [PATCH 05/17] EIP: Removed #67 from requirements. It is not required, merely referenced. --- EIPS/pay_req_url_fmt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index c6c45fce..293ca132 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -7,7 +7,7 @@ Category: ERC Status: Draft Created: 2017-08-01 - Requires: #20, #67, #137 + Requires: #20, #137 ## Simple Summary A standard way of representing payment requests in Ethers and ERC #20 tokens as URLs. From 6845cebac04fcce4c5cd2d61561a383f5f461da7 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Thu, 7 Sep 2017 20:41:21 +0200 Subject: [PATCH 06/17] EIP: Major overhaul, taking into account the feedback received. In particular, generalized to supersede ERC 67. --- EIPS/pay_req_url_fmt.md | 43 ++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index 293ca132..5573cc3d 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -1,16 +1,17 @@ ## Preamble EIP: - Title: URL Format for Payment Requests + Title: URL Format for Transaction Requests Author: Daniel A. Nagy Type: Standard Track Category: ERC Status: Draft + Replaces: 67 Created: 2017-08-01 - Requires: #20, #137 + Requires: 20 ## Simple Summary -A standard way of representing payment requests in Ethers and ERC #20 tokens as URLs. +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. @@ -18,37 +19,47 @@ URLs embedded in QR-codes, hyperlinks in web-pages, emails or chat messages prov ## 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. -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. +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 "ethpay" in their schema (protocol) part and are constructed as follows: - request = "ethpay" ":" beneficiary_address [ "/" token_contract_address ] [ "?" parameters ] - beneficiary_address = ethereum_address - token_contract_address = ethereum_address - ethereum_address = 40*40HEXDIG / ENS_NAME + request = "ethereum" ":" target_address [ "/" function_name ] [ "?" parameters ] + target_address = ethereum_address + function_name = STRING + ethereum_address = ( "0x" 40*40HEXDIG ) / ENS_NAME parameters = parameter *( "&" parameter ) parameter = key "=" value + key = "value" / "gas" / TYPE + value = number / ethereum_address / STRING + number = [ "-" / "+" ] *DIGIT [ "." 1*DIGIT ] [ ( "e" / "E" ) [ 1*DIGIT ] -At present, the only `key` defined is `amount` and the corresponding `value` is a decimal number. Thus: +Where `TYPE` is a standard ABI type name, as defined in [Ethereum Contract ABI specification](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). `STRING` is a URL-encoded unicode string of arbitrary length, where delimiters and the percentage symbol (`%`) are mandatorily hex-encoded with a `%` prefix. - key = "amount" - value = *DIGIT [ "." 1*DIGIT ] +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` 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 -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. +`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. + +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. -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. +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 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 (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. ## 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:`, 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. From fcc7b9ee4df74b2fab1745a1151d279d2d896c7a Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Thu, 7 Sep 2017 21:38:47 +0200 Subject: [PATCH 07/17] EIP: fixes missing s/ethpay/ethereum --- EIPS/pay_req_url_fmt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index 5573cc3d..6f7f1095 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -24,7 +24,7 @@ This specification supersedes ERC #67, which is a URL format for representing ar ## Specification ### Syntax -Payment request URLs contain "ethpay" in their schema (protocol) part and are constructed as follows: +Payment request URLs contain "ethereum" in their schema (protocol) part and are constructed as follows: request = "ethereum" ":" target_address [ "/" function_name ] [ "?" parameters ] target_address = ethereum_address From ab76063e6593605488eff1806dd479067a92dee3 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Sat, 16 Sep 2017 19:58:25 +0200 Subject: [PATCH 08/17] EIP: Added the possibility of using a unit. Making the standard sufficiently flexible for use with both online and offline clients, enhancing human readability, if desired. --- EIPS/pay_req_url_fmt.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index 6f7f1095..51fb5a84 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -34,9 +34,16 @@ Payment request URLs contain "ethereum" in their schema (protocol) part and are parameter = key "=" value key = "value" / "gas" / TYPE value = number / ethereum_address / STRING - number = [ "-" / "+" ] *DIGIT [ "." 1*DIGIT ] [ ( "e" / "E" ) [ 1*DIGIT ] + 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://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). `STRING` is a URL-encoded unicode string of arbitrary length, where delimiters and the percentage symbol (`%`) are mandatorily hex-encoded with a `%` prefix. + +Where `TYPE` is a standard ABI type name, as defined in [Ethereum Contract ABI specification](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). `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 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). From afe03e700e381b7197d791f773b0220e94312dc1 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Wed, 1 Nov 2017 23:54:51 +0100 Subject: [PATCH 09/17] ERC: Added chain_id Support for testnets and private chains added. --- EIPS/pay_req_url_fmt.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index 51fb5a84..dcaf7f95 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -8,7 +8,7 @@ Status: Draft Replaces: 67 Created: 2017-08-01 - Requires: 20 + Requires: 20, 137 ## Simple Summary A standard way of representing various transactions, especially payment requests in Ethers and ERC #20 tokens as URLs. @@ -26,8 +26,9 @@ This specification supersedes ERC #67, which is a URL format for representing ar ### Syntax Payment request URLs contain "ethereum" in their schema (protocol) part and are constructed as follows: - request = "ethereum" ":" target_address [ "/" function_name ] [ "?" parameters ] + request = "ethereum" ":" target_address [ "@" chain_id ] [ "/" function_name ] [ "?" parameters ] target_address = ethereum_address + chain_id = 1*DIGIT function_name = STRING ethereum_address = ( "0x" 40*40HEXDIG ) / ENS_NAME parameters = parameter *( "&" parameter ) @@ -55,6 +56,8 @@ For the syntax of ENS_NAME, please consult ERC #137 defining Ethereum Name Servi `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 main network (1) is assumed. + 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) From 7eff5575dc47b7289540ff54f33b1f39c35daac6 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Thu, 2 Nov 2017 16:15:16 +0100 Subject: [PATCH 10/17] ERC: versioning --- EIPS/pay_req_url_fmt.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index dcaf7f95..d930cb5a 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -73,3 +73,6 @@ Note that the indicated amount is only a suggestion (as are all the supplied arg ## 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 should introduce a version prefix to `target_address` that is separated by a dash (`-`) character from whatever follows it. Exact specifications lie outside the scope of this document. From e03547104e806aba4aa512fe5ade2febfde77856 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Fri, 3 Nov 2017 21:22:24 +0100 Subject: [PATCH 11/17] ERC: We are 681 --- EIPS/pay_req_url_fmt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/pay_req_url_fmt.md index d930cb5a..05dd7ed3 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/pay_req_url_fmt.md @@ -1,6 +1,6 @@ ## Preamble - EIP: + EIP: 861 Title: URL Format for Transaction Requests Author: Daniel A. Nagy Type: Standard Track From 4eca54f2899e78ea7a91981aa42f0c4c34526946 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Tue, 7 Nov 2017 12:53:27 +0100 Subject: [PATCH 12/17] ERC: Corrected numbering typo and renamed file --- EIPS/{pay_req_url_fmt.md => eip-681.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename EIPS/{pay_req_url_fmt.md => eip-681.md} (99%) diff --git a/EIPS/pay_req_url_fmt.md b/EIPS/eip-681.md similarity index 99% rename from EIPS/pay_req_url_fmt.md rename to EIPS/eip-681.md index 05dd7ed3..26b17bb3 100644 --- a/EIPS/pay_req_url_fmt.md +++ b/EIPS/eip-681.md @@ -1,6 +1,6 @@ ## Preamble - EIP: 861 + EIP: 681 Title: URL Format for Transaction Requests Author: Daniel A. Nagy Type: Standard Track From b5444e4c94d0d402ae6b4d1de42652a861e36f39 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Mon, 15 Jan 2018 15:05:27 +0100 Subject: [PATCH 13/17] Update eip-681.md [ERC] default chain_id behavior changed for backwards compatibility. --- EIPS/eip-681.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-681.md b/EIPS/eip-681.md index 26b17bb3..6ba40af1 100644 --- a/EIPS/eip-681.md +++ b/EIPS/eip-681.md @@ -56,7 +56,7 @@ For the syntax of ENS_NAME, please consult ERC #137 defining Ethereum Name Servi `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 main network (1) is assumed. +`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) From f4ba09d033f7ea3f08b96922be0f8e1ae90971f9 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Mon, 15 Jan 2018 15:14:16 +0100 Subject: [PATCH 14/17] [EIP] Optional pay- prefix. If no prefix exists, pay- is assumed. --- EIPS/eip-681.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-681.md b/EIPS/eip-681.md index 6ba40af1..1b1f27c3 100644 --- a/EIPS/eip-681.md +++ b/EIPS/eip-681.md @@ -26,7 +26,7 @@ This specification supersedes ERC #67, which is a URL format for representing ar ### Syntax Payment request URLs contain "ethereum" in their schema (protocol) part and are constructed as follows: - request = "ethereum" ":" target_address [ "@" chain_id ] [ "/" function_name ] [ "?" parameters ] + request = "ethereum" ":" [ "pay-" ]target_address [ "@" chain_id ] [ "/" function_name ] [ "?" parameters ] target_address = ethereum_address chain_id = 1*DIGIT function_name = STRING From 1bc54d967ac1b615b4a08973128a05a035fd8f2e Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Fri, 16 Feb 2018 16:16:55 +0100 Subject: [PATCH 15/17] Added copyright notice, removed ERC 76 dependency --- EIPS/eip-681.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/EIPS/eip-681.md b/EIPS/eip-681.md index 1b1f27c3..1174c3c5 100644 --- a/EIPS/eip-681.md +++ b/EIPS/eip-681.md @@ -6,7 +6,6 @@ Type: Standard Track Category: ERC Status: Draft - Replaces: 67 Created: 2017-08-01 Requires: 20, 137 @@ -76,3 +75,7 @@ The proposed format is chosen to resemble `bitcoin:` URLs as closely as possible ## Compatibility and Versioning Future upgrades that are partially or fully incompatible with this proposal should introduce a version prefix to `target_address` that is separated by a dash (`-`) character from whatever follows it. Exact specifications lie outside the scope of this document. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 7e33495cce02fe5bd68a29bd75be4e42724a8d4a Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Mon, 19 Feb 2018 11:42:42 +0100 Subject: [PATCH 16/17] [ERC] Clarified gas and added 831 as a dependency. --- EIPS/eip-681.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-681.md b/EIPS/eip-681.md index 1174c3c5..522b0a2c 100644 --- a/EIPS/eip-681.md +++ b/EIPS/eip-681.md @@ -7,7 +7,7 @@ Category: ERC Status: Draft Created: 2017-08-01 - Requires: 20, 137 + Requires: 20, 137, 831 ## Simple Summary A standard way of representing various transactions, especially payment requests in Ethers and ERC #20 tokens as URLs. @@ -32,7 +32,7 @@ Payment request URLs contain "ethereum" in their schema (protocol) part and are ethereum_address = ( "0x" 40*40HEXDIG ) / ENS_NAME parameters = parameter *( "&" parameter ) parameter = key "=" value - key = "value" / "gas" / TYPE + key = "value" / "gas" / "gasLimit" / "gasPrice" / TYPE value = number / ethereum_address / STRING number = [ "-" / "+" ] *DIGIT [ "." 1*DIGIT ] [ ( "e" / "E" ) [ 1*DIGIT ] [ "+" UNIT ] @@ -47,7 +47,7 @@ the blockchain should refuse accepting requests with a non-empty `UNIT`, if it i 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` or `gas` then *value* MUST be a `number`. Otherwise, it must correspond to the `TYPE` string used as *key*. +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. @@ -70,6 +70,8 @@ If the payer client has access to the blockchain, the interface should display t 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. From 991d4f7bbf315a7425be33db90a0d5002de81857 Mon Sep 17 00:00:00 2001 From: "Daniel A. Nagy" Date: Mon, 19 Feb 2018 12:07:02 +0100 Subject: [PATCH 17/17] [ERC] Fixes Compatibility and Versioning Added explicit reference to #831 --- EIPS/eip-681.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-681.md b/EIPS/eip-681.md index 522b0a2c..ab4b1cff 100644 --- a/EIPS/eip-681.md +++ b/EIPS/eip-681.md @@ -76,7 +76,7 @@ Similarly `gasLimit` and `gasPrice` are suggested user-editable values for *gas 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 should introduce a version prefix to `target_address` that is separated by a dash (`-`) character from whatever follows it. Exact specifications lie outside the scope of this document. +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