This section states the encoding by which a payee states payments to a payer. It gives the URI grammar of ZIP 321, the grouping of parameters into payments and the conditions under which a parser accepts a URI; then the meaning of the address, amount, memo, label and message parameters, the capacity of one request, and the passage from an accepted request to a transaction plan.
A payment request precedes planning (§11.1): the payee states to the payer, in a form that a wallet reads mechanically, the recipient addresses, amounts and memos of the payments it asks for, and ZIP 321 fixes this encoding as a URI scheme. Its terms payment and payment request (ZIP 321, “Terminology”) are those of Definition 11.1. Everything that follows once the recipients are fixed is constructed in the earlier sections of this volume and in the Ironwood Guide, §“Note encryption”, §“Trial decryption and note acceptance”, §“Authentication paths”, §“Anchors” and §“Transaction digests and signatures”; this section re-derives none of it. The status of ZIP 321 is that of Table 1.
Let L be the set of strings derived from zcashurn in the following grammar in ABNF (RFC 5234), reproduced from ZIP 321, “URI Syntax”, with its longest rule continued on an indented line:
zcashurn = "zcash:" ( zcashaddress [ "?" zcashparams ]
/ "?" zcashparams )
zcashaddress = 1*( ALPHA / DIGIT )
zcashparams = zcashparam [ "&" zcashparams ]
zcashparam = [ addrparam / amountparam / assetparam / memoparam
/ messageparam / labelparam / otherreqparam / otherparam ]
NONZERO = %x31-39
DIGIT = %x30-39
paramindex = "." NONZERO 0*3DIGIT
addrparam = "address" [ paramindex ] "=" zcashaddress
amountparam = "amount" [ paramindex ] "=" 1*DIGIT [ "." 1*8DIGIT ]
assetparam = "req-asset" [ paramindex ] "=" *base64url
labelparam = "label" [ paramindex ] "=" *qchar
memoparam = "memo" [ paramindex ] "=" *base64url
messageparam = "message" [ paramindex ] "=" *qchar
paramname = ALPHA *( ALPHA / DIGIT / "+" / "-" )
otherreqparam = "req-" paramname [ paramindex ] [ "=" *qchar ]
otherparam = paramname [ paramindex ] [ "=" *qchar ]
qchar = unreserved / pct-encoded / allowed-delims / ":" / "@"
allowed-delims = "!" / "$" / "’" / "(" / ")" / "*" / "+" / "," / ";"
Here ALPHA, unreserved and pct-encoded are those of RFC 3986, Appendix A, and base64url is the alphabet of RFC 4648, Section 5, in which the values 62 and 63 are written - and _, with padding omitted. The grammar is read as follows: a parameter whose name is address, amount, label, memo, message or req-asset is derived only by its own production, and otherreqparam and otherparam derive only parameters with other names. A payment request URI is a string of L that meets the acceptance conditions (a) to (f) stated below in this subsection.
Without the reading, otherparam would derive amount=1%30, with name amount, no index and a qchar value; ZIP 321, “Invalid Examples”, rejects a URI with this parameter.
Surface forms. The grammar derives no // after the scheme, so a payment request URI has no authority component and is not hierarchical in the sense of RFC 3986, Section 1.2.3; ZIP 321, “Invalid Examples”, rejects zcash:// followed by an address. A URI zcash: A ? P , with A a zcashaddress, MUST be treated as zcash:?address= A & P (ZIP 321, “URI Semantics”). A request for a single payment SHOULD place its address in the hier-part; several payments are written with addrparam at distinct indices (same section). By this equivalence and condition (b) below, a URI zcash: A ?address= B & ... is not accepted: after the rewriting it carries address twice at the empty index.
Indices and grouping. Identify the empty index with 0 and let
Lexical rules. Percent encoding (RFC 3986, Section 2.1) occurs only inside qchar, that is, only in the values of label, message, otherreqparam and otherparam. Addresses, amounts, indices and parameter names are literal, so amount=1%30, %61mount=1 and an address beginning with %74 are not in L (ZIP 321, “URI Syntax” and “Invalid Examples”). The values of memo and req-asset are base64url without padding, and implementations MUST NOT accept the characters +, / and =, which occur only in the standard base64 alphabet (ZIP 321, “URI Syntax”; RFC 4648, Section 5).
Acceptance. A parser accepts a string u as a payment request URI only if all of the following hold (ZIP 321, “URI Syntax”, “URI Semantics” and “Forward compatibility”):
after the hier-part address is rewritten as address at the empty index, no pair of a parameter name and an index occurs twice (MUST NOT);
every index that carries a parameter other than address carries an address (MUST);
u names no parameter with prefix req- that the parser does not recognise, since such a parameter makes the entire URI invalid (MUST); other unrecognised parameters are ignored (SHOULD);
the address, amount and memo rules of §14.2 hold;
u decodes to at least one payment, a payment request containing one or more payments (ZIP 321, “Terminology”).
The prefix req- is part of the name of a parameter defined by a later revision of ZIP 321, not a modifier of an arbitrary parameter; the parameters address, amount, label, memo and message never carry it, since every conformant parser is required to understand them (ZIP 321, “Forward compatibility”). An accepted URI asks for one transaction: implementations SHOULD construct a single transaction that pays every address of the request (ZIP 321, “URI Semantics”).
Custom assets. The parameter req-asset is specified in ZIP 321, “Custom Assets”, with an encoding defined by ZIP 227, which the protocol described in this volume does not include. A parser of this protocol does not recognise req-asset, so by condition (d) a URI that carries it is invalid to that parser, and the further rule that amount and req-asset exclude each other at one index (ZIP 321, “URI Semantics”) never applies.
Quoted strings in ABNF are case-insensitive (RFC 5234, Section 2.3), so L contains strings beginning ZCASH: and strings with the parameters AMOUNT=1 and REQ-ASSET=; the value ranges NONZERO and DIGIT, given as %x ranges, and the base64url alphabet are case-sensitive. ZIP 321 does not address case: it states neither whether such URIs are to be accepted nor whether amount and AMOUNT at one index are the same parameter for condition (b). The volume states the grammar as written and resolves neither question; no parser’s behaviour is normative. Class: open problem (Definition 1.1).
Addresses. Implementations SHOULD check that each zcashaddress is a valid encoding of an address other than a Sprout address under protocol specification, §“Encodings of Addresses and Keys”: a transparent address (§“Transparent Addresses”, Base58Check), a Sapling payment address (§“Sapling Payment Addresses”, Bech32, ZIP 173) or a unified address (§“Unified Payment Addresses and Viewing Keys” and ZIP 316, Bech32m, BIP 350). Address formats later added to that section SHOULD be supported; where the network of the request is known, each address SHOULD be checked to belong to it; and every requirement of ZIP 316 applies to a unified address (ZIP 321, “URI Semantics”). Sprout addresses MUST NOT be supported (same section). ZIP 321 gives as its reason the restriction of ZIP 211 on adding value to the Sprout pool; in the protocol described, version- 4 transactions are invalid, and Sprout transfers exist only in transactions of versions 2 to 4 , so Sprout funds are unspendable (ZIP 2003, “Abstract”; ZIP 259, “Abstract”; Ironwood Guide, §“The transaction format”). A TEX address (ZIP 320) is in no section of the specification, and ZIP 321 names none; its reading as the recipient address of item 4 of Definition 3.20 is designed but unspecified (Definition 1.1). The addresses of an accepted request are thus recipient addresses in the sense of Definition 3.20.
Let
Parse. Let s match 1*DIGIT [ "." 1*8DIGIT ], and
write
| v := int (c) ⋅ COIN + z . |
Accept s if and only if
Render. For
Leading zeros of the whole part and trailing zeros of the fraction are ignored, the bound MAX _ MONEY is ZIP 321’s “MUST NOT be greater than 21000000 ZEC”, and a string with a comma or other grouping separator, with an empty whole part (.5), an empty fraction (50.) or more than 8 fraction digits matches no production (ZIP 321, “ZEC Transfer Amount”). ZIP 321 fixes only the value that an amount denotes; the rendering is canonical, not required.
For every integer v with
Write
Examples. On the examples of ZIP 321, “ZEC Transfer Amount” and
“Examples”, Construction 14.3 gives the following. The
parameter amount=1 denotes
Absent amount. ZIP 321 gives a payment a value only “if an amount parameter is provided” (ZIP 321, “ZEC Transfer Amount”). A payment without one has no value under ZIP 321, while Definition 11.1 requires a value, so the payer fixes the value before a plan is formed. Class: designed but unspecified (Definition 1.1).
A memo is a 512 -byte string M , the memo field of a note plaintext (Ironwood Guide, §“The note plaintext”; protocol specification, §“Encodings of Note Plaintexts and Memo Fields”). Let b64u be the encoding of RFC 4648, Section 5, with padding omitted, and let strip (M) be M with its trailing 0x00 bytes removed.
Encode.
Decode. Reject a value that contains a character outside the
base64url alphabet, in particular +, / or
=, or whose length is congruent to 1 modulo 4 , a length to
which no octet string encodes. Otherwise let b be its decoding under
RFC 4648, Section 5, and require
A payment without a memo parameter has no memo (Definition 11.1); its output, if shielded, carries the memo field that ZIP 302 designates as supplying no memo, 0xF6 ∥ 0 x00 511 , whose encoding is 9g (ZIP 302, “Specification”). A parameter memo= with the empty value differs from an absent parameter: it decodes to 0x00 512 , which a reader under ZIP 302 reads as the empty text. If the address at the index of a memo parameter does not permit memos, that is, is not memo-capable in the sense of predicate (i) of Definition 3.20, as for a transparent or TEX address, parsers MUST consider the entire URI invalid (ZIP 321, “Query Keys”), since a memo travels only in a note plaintext.
For every memo M ,
The string
Enc (M) uses only the base64url alphabet, and an
unpadded encoding of n octets has length ⌈ 8 n / 6 ⌉ , never
congruent to 1 modulo 4 , so decoding does not reject it. The encoding
b64u is injective with inverse the decoding of RFC 4648, so
ZIP 321 does not say whether a value whose final character carries non-zero unused bits (RFC 4648, Section 3.5) is accepted; the encoding Enc produces none. Stripping trailing zeros gives the shortest encoding and is not required: b64u (M) decodes to the same memo. As an instance, ZIP 321’s example value VGhpcyBpcyBhIHNpbXBsZSBtZW1vLg, of 30 characters, decodes to the 22 bytes of the text “This is a simple memo.”, padded with zeros to 512 bytes.
Labels and messages. The label at an index names its address, for example by the name of the recipient; a client that renders the payment for inspection SHOULD display the label together with the address, and a displayed label MUST be identifiable as distinct from the address. The message at an index is descriptive text that a client may display for that payment (ZIP 321, “Query Keys”). Both values are qchar strings, percent-decoded to octet strings; an octet outside qchar reaches them only by percent encoding. Neither enters the transaction (Definition 11.1).
Capacity. A request carries at most
Size. A block has at most
Shielded budget. ZIP 218, part of NU7, requires of every block, with S the number of Sapling spends plus outputs, A O and A I the numbers of Orchard-pool and Ironwood-pool Actions, and n JS the number of JoinSplit descriptions, each summed over the block’s transactions,
| S ≤ 300, A O ≤ 330, A I ≤ 330, n JS ≤ 0, | ||
| A O + A I + S + 2 n JS ≤ 330 |
(ZIP 218, “Shielded pool action limits”); versions 5 and 6 carry
no JoinSplit description in any case (Ironwood Guide,
§“The transaction format”). Each of these sums over a block is at
least the term of any one of its transactions. A transaction that pays
n payments by Sapling outputs has
| n ≤ o ≤ min (300, 330 − a) − s . |
The all-Sapling bound is therefore
Ironwood pool. An Action creates one note, so a transaction
that pays n payments by Ironwood-pool outputs has
| n ≤ a I ≤ 330 − a O − s − o . |
An Action contributes at least
Transparent outputs. ZIP 218 does not apply its limits to the transparent components of transactions (same section), so payments by transparent outputs are bounded by the size limit alone.
From request to plan. Each payment