From 68f0f270dcc034cbf5f818e9357684fa2843aa20 Mon Sep 17 00:00:00 2001 From: Jason Dreyzehner Date: Fri, 16 Jun 2023 13:10:18 -0400 Subject: [PATCH] Restrict use of 't' parameter to reasonable cases --- readme.md | 54 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/readme.md b/readme.md index 2b8499c..b7677a8 100644 --- a/readme.md +++ b/readme.md @@ -82,20 +82,20 @@ In further detail: #### Payment URI Parameters -| Parameter | Description | Additional Validation When Present | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `c` | The category identifier of the requested token(s), hex-encoded in user interface order1. | Error if `f` and/or `n` are not set. Error if address is not CashToken-supporting (e.g. [version `2` and `3` CashAddresses](https://cashtokens.org/docs/spec/chip#cashaddress-token-support)). Error if `amount` is set (`s` may be used). | -| `e` | The Unix timestamp at which this URI expires. For the purpose of expiration, payments are considered to have occurred at the moment they are heard over the public network (rather than the time at which they are confirmed in a block). | Error if the indicated expiration time has passed. Error if `amount` is set (`s` may be used). | -| `f` | The fungible token amount requested in category `c` tokens. The amount is in terms of on-chain fungible token units, without respect for display standards. E.g. for a category in which `100` fungible tokens are considered to be `1.00 XAMPL`, `f=100` would be a request for `1.00 XAMPL`. | Error if `c` is not set. | -| `m` | A message that describes the transaction to the user. The message must be [utf8-based, percent encoded](https://en.wikipedia.org/wiki/URL_encoding); uppercase letters should also be percent encoded for reliable transmission2. | Error if `message` is also set. | -| `n` | The requested non-fungible token commitment of category `c`. The commitment must be hex-encoded, e.g. `n=01` requests an NFT with commitment `0x01`; `n` or `n=` requests an NFT with an empty commitment. | Error if `c` is not set. | -| `r` | An `HTTPS` request URL, similar to [BIP72](https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki), but used by the [below described Payment Protocol](#payment-protocol). The `https://` is implied and must be omitted (see [Behavior of `r` parameter](#behavior-of-r-parameter)). If provided, all other parameters are ignored (other parameters may be used as a fallback for implementations without full payment protocol support). | | -| `s` | The requested number of satoshis, e.g. `s=123456` is a request for `0.00123456 BCH`. If `s` is not set, the minimum value for the requested output (dust limit) is implied. | Error if `amount` is also set. | -| `t` | The receiver can safely receive CashTokens. Implied by CashToken-supporting [v2 and v3 CashAddresses](https://cashtokens.org/docs/spec/chip#cashaddress-token-support); the `t` parameter has no additional impact on URIs with CashToken-supporting addresses. | | -| **BIP21 Parameters** | -| `` | An unknown, custom parameter that implementations can safely ignore. | | -| `amount` | The requested amount in whole BCH, e.g. `amount=.00123456` is a request for `0.00123456 BCH`. Included for backwards-compatibility with BIP21, but the `s` parameter is recommended for applications not requiring BIP21 compatibility. (See [Inclusion of `s` parameter](#inclusion-of-s-parameter).) | Error if `s` is also set. | -| `message` | Identical to `m`, included for backwards-compatibility with BIP21. Note that the [BIP21 `label` parameter is not supported](#exclusion-of-label-parameter). | Error if `m` is also set. | +| Parameter | Description | Additional Validation When Present | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `c` | The category identifier of the requested token(s), hex-encoded in user interface order1. | Error if `f` and/or `n` are not set. Error if address is not CashToken-supporting (e.g. [version `2` and `3` CashAddresses](https://cashtokens.org/docs/spec/chip#cashaddress-token-support)). Error if `amount` is set (`s` may be used). | +| `e` | The Unix timestamp at which this URI expires. For the purpose of expiration, payments are considered to have occurred at the moment they are heard over the public network (rather than the time at which they are confirmed in a block). | Error if the indicated expiration time has passed. Error if `amount` is set (`s` may be used). | +| `f` | The fungible token amount requested in category `c` tokens. The amount is in terms of on-chain fungible token units, without respect for display standards. E.g. for a category in which `100` fungible tokens are considered to be `1.00 XAMPL`, `f=100` would be a request for `1.00 XAMPL`. | Error if `c` is not set. | +| `m` | A message that describes the transaction to the user. The message must be [utf8-based, percent encoded](https://en.wikipedia.org/wiki/URL_encoding); uppercase letters should also be percent encoded for reliable transmission2. | Error if `message` is also set. | +| `n` | The requested non-fungible token commitment of category `c`. The commitment must be hex-encoded, e.g. `n=01` requests an NFT with commitment `0x01`; `n` or `n=` requests an NFT with an empty commitment. | Error if `c` is not set. | +| `r` | An `HTTPS` request URL, similar to [BIP72](https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki), but used by the [below described Payment Protocol](#payment-protocol). The `https://` is implied and must be omitted (see [Behavior of `r` parameter](#behavior-of-r-parameter)). If provided, all other parameters are ignored (other parameters may be used as a fallback for implementations without full payment protocol support). | | +| `s` | The requested number of satoshis, e.g. `s=123456` is a request for `0.00123456 BCH`. If `s` is not set, the minimum value for the requested output (dust limit) is implied. | Error if `amount` is also set. | +| **Compatibility** | +| `t` | The receiver can safely receive CashTokens. Implied by CashToken-supporting [v2 and v3 CashAddresses](https://cashtokens.org/docs/spec/chip#cashaddress-token-support). The `t` parameter should only be used for backwards-compatibility; specific token requests must use a token-aware address (see the `c` parameter). | Error if `amount`, `c`, or `s` is also set. | +| `amount` | The requested amount in whole BCH, e.g. `amount=.00123456` is a request for `0.00123456 BCH`. Included for backwards-compatibility with BIP21, but the `s` parameter is recommended for applications not requiring BIP21 compatibility. (See [Inclusion of `s` parameter](#inclusion-of-s-parameter).) | Error if `s` is also set. | +| `message` | Identical to `m`, included for backwards-compatibility with BIP21. Note that the [BIP21 `label` parameter is not supported](#exclusion-of-label-parameter). | Error if `m` is also set. | +| `` | An unknown, custom parameter that implementations can safely ignore. | |
@@ -136,15 +136,19 @@ The following examples demonstrate well-formed payment URIs. | Description | Parameters | URI | | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | v0 address | | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl` | -| v0 address, CashTokens support | `t` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t` | -| v0 address, CashTokens support, web-safe URI | `t` | `bitcoin:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t` | -| v2 address (implicit CashTokens support) | | `bitcoincash:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v` | -| v2 address (implicit CashTokens support), web-safe URI | | `bitcoin:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v` | +| v0 address, token support | `t` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t` | +| v0 address, token support, web-safe URI | `t` | `bitcoin:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t` | +| v0 address, token support, backwards-compatible message | `t`, `message` of `test` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t&message=test` | +| v0 address, token support, message | `t`, `m` of `Tip for Alice at Venue` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t&m=%54ip%20for%20%41lice%20at%20%56enue` | +| v0 address, token support, message, expiration | `t`, `m` of `Tip for Bob at Venue`, expiration of `2022-11-15T12:00:00.000Z` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t&e=1668513600&m=%54ip%20for%20%42ob%20at%20%56enue` | +| v2 address (implicit token support) | | `bitcoincash:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v` | +| v2 address (implicit token support), web-safe URI | | `bitcoin:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v` | | v0 address, satoshis, expiration | `s=123400`, expiration of `2023-05-15T12:00:00.000Z` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?s=123400&e=1684152000` | | Payment Protocol-Only | `r=example.com/pay/1234` | `bitcoincash:?r=example.com/pay/1234` | | Payment Protocol-Only, web-safe URI | `r=example.com/pay/1234` | `bitcoin:?r=example.com/pay/1234` | | Payment Protocol; falls back to v0 address, BIP21 amount | `r=example.com/pay/1234`, `amount=.001234` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?amount=.001234&r=example.com/pay/1234` | | Payment Protocol; falls back to v0 address, satoshis, and expiration | `r=example.com/pay/1234`, `s=123400`, expiration of `2023-05-15T12:00:00.000Z` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?s=123400&e=1684152000&r=example.com/pay/1234` | +| Payment Protocol; falls back to v0 address, token support, message | `r=example.com/tip/1234`, `t`, `m` of `Tip for Bob at Venue` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?r=example.com/tip/1234&t&m=%54ip%20for%20%42ob%20at%20%56enue` | | v0 address, BIP21-compatible amount and message | `amount=1` (`1.00000000 BCH`), `message` of `Test at ACME (10% Friends & Family Discount)` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?amount=1&message=%54est%20at%20%41%43%4D%45%20%2810%25%20%46riends%20%26%20%46amily%20%44iscount%29` | | v0 address, satoshi amount and message | `s=12345` (`0.00012345 BCH`), `m` of `Multi\nLine\nMessage: T̶̀est` | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?s=12345&m=%4Dulti%0A%4Cine%0A%4Dessage%3A%20%54%CD%80%CC%B6est` | | v2 address, 10,000 FT request, minimum satoshis | `c=0afd5f9ad130d043f627fad3b422ab17cfb5ff0fc69e4782eea7bd0853948428`,`f=10000` | `bitcoincash:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v?c=0afd5f9ad130d043f627fad3b422ab17cfb5ff0fc69e4782eea7bd0853948428&f=10000` | @@ -160,6 +164,9 @@ The following examples demonstrate malformed payment URIs. For each, implementat | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | No address or request URL is provided. | `bitcoincash:?amount=1` | | No address or request URL is provided. | `bitcoincash:?s=1000` | +| Token-accepting request requires a token-aware address. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t&amount=1` | +| Token-accepting request requires a token-aware address. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t&s=1000` | +| Token-accepting request requires a token-aware address. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t&c=0afd5f9ad130d043f627fad3b422ab17cfb5ff0fc69e4782eea7bd0853948428&f=10000` | | Expiring request uses the deprecated `amount` parameter. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?amount=1&e=1684152000` | | Both `s` and `amount` are set. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?s=123456&amount=.00123456` | | Both `m` and `message` are set. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?m=abc&message=abc` | @@ -167,9 +174,9 @@ The following examples demonstrate malformed payment URIs. For each, implementat | Token request pays to an address without token support. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?c=0afd5f9ad130d043f627fad3b422ab17cfb5ff0fc69e4782eea7bd0853948428&f=10` | | Token request pays to an address without token support. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?t&c=0afd5f9ad130d043f627fad3b422ab17cfb5ff0fc69e4782eea7bd0853948428&f=10` | | Token request uses the ambiguous `amount` parameter. | `bitcoincash:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v?c=0afd5f9ad130d043f627fad3b422ab17cfb5ff0fc69e4782eea7bd0853948428&f=10&amount=.0001` | -| Token request is missing a token category. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?f=10` | -| Token request is missing a token category. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?n=00` | -| Token request is missing a token category. | `bitcoincash:qr7fzmep8g7h7ymfxy74lgc0v950j3r2959lhtxxsl?n=00` | +| Token request is missing a token category. | `bitcoincash:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v?f=10` | +| Token request is missing a token category. | `bitcoincash:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v?n` | +| Token request is missing a token category. | `bitcoincash:zr7fzmep8g7h7ymfxy74lgc0v950j3r295z4y4gq0v?n=00` |
@@ -323,9 +330,10 @@ Thank you to [Jonas Lundqvist](https://github.com/jonas-lundqvist), [Tom Zander] This section summarizes the evolution of this document. - **Draft v1.0.0** - - Defined `e` (expiration) parameter ([#6](https://github.com/bitjson/chip-paypro/issues/6)) - - Drop support for `req-` parameter prefix ([#1](https://github.com/bitjson/chip-paypro/issues/1)) - Initial publication + - Dropped support for `req-` parameter prefix ([#1](https://github.com/bitjson/chip-paypro/issues/1)) + - Restricted use of `t` to reasonable cases ([#2](https://github.com/bitjson/chip-paypro/issues/2)) + - Defined `e` (expiration) parameter ([#6](https://github.com/bitjson/chip-paypro/issues/6)) ## Copyright