ZIP: 321
Title: Payment Request URIs
Owners: Kris Nuttycombe (kris@electriccoin.co)
Daira Hopwood (daira@electriccoin.co)
Status: Proposed
Category: Standards / Wallet
Created: 2020-08-28
Discussions-To: <https://github.com/zcash/zips/issues/347>
Pull-Request: <https://github.com/zcash/zips/pull/395>
License: MIT
The key words "MUST", "MUST NOT", "SHOULD", "RECOMMENDED", and "MAY" in this document are to be interpreted as described in RFC 2119. [1]
The terms "Testnet" and "Mainnet" are to be interpreted as described in section 3.11 of the Zcash Protocol Specification [10].
The terms below are to be interpreted as follows:
- payment
- A transfer of funds implemented by a shielded or transparent output of a Zcash transaction.
- payment request
- A request for a wallet to construct a single Zcash transaction containing one or more payments.
This ZIP proposes a standard format for payment request URIs. Wallets that recognize this format enable users to construct transactions simply by clicking links on webpages or scanning QR codes.
In order for a robust transactional ecosystem to evolve for Zcash, it is necessary for vendors to be able to issue requests for payment. At present, the best option available is to manually specify a payment address, a payment amount, and potentially memo field content. Of these three components, existing wallets only provide functionality for reading payment addresses in a semi-automated fashion. It is then necessary for the user to manually enter payment amounts and any associated memo information, which is tedious and may be error-prone, particularly if a payment is intended for multiple recipients or the memo field information contains structured data that must be faithfully reproduced.
This ZIP seeks to eliminate these issues by proposing a standard format that wallet vendors may support so that human intervention is required only for approval, not creation, of such a transaction.
In Bitcoin, two different standards exist to permit vendors to issue payment requests that are understood by wallets: BIP-0021 [5] and BIP-0070 [6]. BIP-0021 provides a URI format that can be interpreted by a wallet to construct simple, single-recipient transactions; BIP-0070 uses a protobuf-based protocol that permits requests for transactions of arbitrary complexity.
The format proposed in this ZIP seeks a middle ground between these approaches: to provide a URI-based format which supports both the trivial use case and the slightly-more-complex situation where a transaction may include payments to multiple recipients.
The format must be a valid URI.
The format must permit the representation of one or more (payment address, amount, memo) tuples.
The following syntax specification uses ABNF [2].
zcashurn = "zcash:" ( zcashaddress [ "?" zcashparams ] / "?" zcashparams )
zcashaddress = 1*( ALPHA / DIGIT )
zcashparams = zcashparam [ "&" zcashparams ]
zcashparam = [ addrparam / amountparam / memoparam / messageparam / labelparam / reqparam / otherparam ]
NONZERO = %x31-39
DIGIT = %x30-39
paramindex = "." NONZERO 0*3DIGIT
addrparam = "address" [ paramindex ] "=" zcashaddress
amountparam = "amount" [ paramindex ] "=" 1*DIGIT [ "." 1*8DIGIT ]
labelparam = "label" [ paramindex ] "=" *qchar
memoparam = "memo" [ paramindex ] "=" *base64url
messageparam = "message" [ paramindex ] "=" *qchar
paramname = ALPHA *( ALPHA / DIGIT / "+" / "-" )
reqparam = "req-" paramname [ paramindex ] [ "=" *qchar ]
otherparam = paramname [ paramindex ] [ "=" *qchar ]
qchar = unreserved / pct-encoded / allowed-delims / ":" / "@"
allowed-delims = "!" / "$" / "'" / "(" / ")" / "*" / "+" / "," / ";"Here, ALPHA, unreserved and pct-encoded are as defined in
[3]. "base64url" is defined as in [4] with padding omitted.
(Note that this uses a different alphabet to the usual base64; the values 62 and
63 in the alphabet are encoded as - and _ respectively. Implementations
MUST NOT accept the characters +, /, and = that occur only in the
usual base64.)
Productions of the form 1*x indicate one or more successive instances of the
production x. Productions of the form <n>*<m>x indicate at least <n> and
at most <m> instances of production x.
Note that this grammar does not allow percent encoding outside the productions
that use qchar, i.e. the values of label, message, reqparam, and
otherparam parameters.
Purported ZIP 321 URIs that cannot be parsed according to the above grammar MUST NOT be accepted.
A ZIP-321 URI represents a request for the construction of a transaction having
one or more payments. In the case that only a single payment is being
requested, the recipient address SHOULD be included in the hier-part component
of the RFC 3986 URI; otherwise, multiple recipient addresses can be specified
using addrparam parameters with different indices.
Addresses, amounts, labels, and messages sharing the same paramindex
(including the empty paramindex) are interpreted to be associated with
the same payment for the purposes of payment construction. A paramindex
MUST NOT have leading zero(s). There is no significance to the ordering of
parameters, and paramindex values need not be sequential.
Due to restrictions on transaction construction described in [11], there may be no more than 2109 distinct payments requested by a single ZIP-321 URI.
A URI of the form zcash:<address>?... MUST be considered equivalent to a
URI of the form zcash:?address=<address>&... where <address> is an
instance of zcashaddress.
If there are any non-address parameters having a given paramindex, then
the URI MUST contain an address parameter having that paramindex. There
MUST NOT be more than one occurrence of a given parameter and paramindex.
Implementations SHOULD check that each instance of zcashaddress is a valid
string encoding of either:
- a Zcash transparent address, using Base58Check [7] as defined in [12]; or
- a Zcash Sapling address, using Bech32 [8] as defined in [13].
New address formats may be added in future. If the context of whether the payment URI is intended for Testnet or Mainnet is available, then each address SHOULD be checked to be for the correct network.
Sprout addresses MUST NOT be supported in payment requests. The rationale for this is that transfers to Sprout addresses will, at activation of the Canopy network upgrade, be restricted by ZIP 211 [9]; it cannot generally be expected that senders will have funds available in the Sprout pool with which to satisfy requests for payment to a Sprout address.
If an amount is provided, it MUST be specified in decimal ZEC. If a decimal fraction is present then a period (.) MUST be used as the separating character to separate the whole number from the decimal fraction, and both the whole number and the decimal fraction MUST be nonempty. No other separators (such as commas for grouping or thousands) are permitted. Leading zeros in the whole number or trailing zeros in the decimal fraction are ignored. There MUST NOT be more than 8 digits in the decimal fraction.
- For example,
amount=50.00oramount=50oramount=050is treated as 50 ZEC;amount=0.5oramount=00.500is treated as 0.5 ZEC; andamount=50,000.00oramount=50,00oramount=50.oramount=.5oramount=0.123456789are invalid.
The amount MUST NOT be greater than 21000000 ZEC (in general, monetary amounts in Zcash cannot be greater than this value).
- label
- Label for an address (e.g. name of receiver). If a label is present at
a
paramindex, a client rendering a payment for inspection by the user SHOULD display this label (if possible) as well as the associated address. If the label is displayed, it MUST be identifiable as distinct from the address. - address
- Zcash address string (shielded or transparent)
- memo
- Contents for the Zcash shielded memo field, encoded as base64url without
=padding. The decoded memo contents MUST NOT exceed 512 bytes, and if shorter, will be filled with trailing zeros to 512 bytes. Parsers MUST consider the entire URI invalid if the address associated with the sameparamindexis not a valid shielded address. - message
- Message that clients can display for the purpose of presenting descriptive
information about the payment at the associated
paramindexto the user.
zcash:ztestsapling10yy2ex5dcqkclhc7z7yrnjq2z6feyjad56ptwlfgmy77dmaqqrl9gyhprdx59qgmsnyfska2kez?amount=1&memo=VGhpcyBpcyBhIHNpbXBsZSBtZW1vLg&message=Thank%20you%20for%20your%20purchase
A valid payment request for a payment of 1 ZEC to a single shielded address, with a base64url-encoded memo and a message for display by the wallet.
zcash:?address=tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU&amount=123.456&address.1=ztestsapling10yy2ex5dcqkclhc7z7yrnjq2z6feyjad56ptwlfgmy77dmaqqrl9gyhprdx59qgmsnyfska2kez&amount.1=0.789&memo.1=VGhpcyBpcyBhIHVuaWNvZGUgbWVtbyDinKjwn6aE8J-PhvCfjok
A valid payment request with one transparent and one shielded recipient address, with an encoded Unicode memo for the shielded recipient.
zcash:?amount=3491405.05201255&address.1=ztestsapling10yy2ex5dcqkclhc7z7yrnjq2z6feyjad56ptwlfgmy77dmaqqrl9gyhprdx59qgmsnyfska2kez&amount.1=5740296.87793245
An invalid payment request; this is missing a payment address with empty paramindex.
zcash:?address=tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU&amount=1&amount.1=2&address.2=ztestsapling10yy2ex5dcqkclhc7z7yrnjq2z6feyjad56ptwlfgmy77dmaqqrl9gyhprdx59qgmsnyfska2kez
Also invalid; this request is missing address.1=.
zcash:?address.0=ztestsapling10yy2ex5dcqkclhc7z7yrnjq2z6feyjad56ptwlfgmy77dmaqqrl9gyhprdx59qgmsnyfska2kez&amount.0=2
Also invalid; address.0= and amount.0= are not permitted as leading 0s are
forbidden in paramindex.
zcash:?amount=1.234&amount=2.345&address=tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU zcash:?amount.1=1.234&amount.1=2.345&address.1=tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU"
Also invalid; duplicate amount= or amount.1= fields
zcash:tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?amount=1%30 zcash:tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?%61mount=1 zcash:%74mEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?amount=1
Invalid; percent encoding is only allowed in qchar productions, which do
not include addresses, amounts, or parameter names.
zcash://tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?amount=1
Invalid; the grammar does not allow //. ZIP 321 URIs are not
"hierarchical URIs" in the sense defined in [3] section 1.2.3,
and do not have an "authority component".
Variables which are prefixed with a req- are considered required. If a
parser does not recognize any variables which are prefixed with req-, it
MUST consider the entire URI invalid. Any other variables that are not
recognized, but that are not prefixed with a req-, SHOULD be ignored.
As this ZIP is written, several clients already implement a zcash: URI
scheme similar to this one, however usually without the additional req-
prefix requirement or the facility to specify multiple payments using
paramindex. These implementations also generally do not support URIs,
even with a single payment, where the address is specified as an address=
query parameter rather than in the hier-part of the URI. They may also
not support the memo parameter, or may not treat it as base64url-encoded.
Thus, it is RECOMMENDED that these features not be used in a mission-critical way until a grace period of 6 months from the finalization of this ZIP has passed, in order to allow client developers to release new versions, and users of old clients to upgrade.
| [1] | RFC 2119: Key words for use in RFCs to Indicate Requirement Levels |
| [2] | RFC 5234: Augmented BNF for Syntax Specifications: ABNF |
| [3] | (1, 2) RFC 3986: URI Generic Syntax, Appendix A. Collected ABNF for URI |
| [4] | RFC 4648 section 5: Base64 Encoding with URL and Filename Safe Alphabet |
| [5] | BIP 21: URI Scheme |
| [6] | BIP 70: Payment Protocol |
| [7] | Bitcoin Wiki: Base58Check encoding |
| [8] | ZIP 173: Bech32 Format |
| [9] | ZIP 211: Disabling Addition of New Value to the Sprout Value Pool |
| [10] | Zcash Protocol Specification, Version 2020.1.15. Section 3.11: Mainnet and Testnet |
| [11] | Zcash Protocol Specification, Version 2020.1.15. Section 4.12: Balance and Binding Signature (Sapling) |
| [12] | Zcash Protocol Specification, Version 2020.1.15. Section 5.6.1: Transparent Addresses |
| [13] | Zcash Protocol Specification, Version 2020.1.15. Section 5.6.4: Sapling Payment Addresses |