14 Payment requests (ZIP 321)

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.

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 $\text{zcash:}A\text{?}P$, with $A$ a zcashaddress, MUST be treated as (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 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 $J:=\{0,1,\mathrm{\dots },9999\}$. The rendering $\iota$ maps $0$ to the empty string and $i\ge 1$ to $\text{.}\parallel \mathrm{dec}(i)$, where $\mathrm{dec}(i)$ is the decimal representation of $i$ without leading zeros. The strings that match [ paramindex ] are the empty string and the strings $\text{.}{d}_1\mathrm{\cdots }{d}_k$ with $1\le k\le 4$, $d_1\in \{\text{1},\mathrm{\dots },\text{9}\}$ and $d_2,\mathrm{\dots },d_k$ decimal digits; these are exactly the decimal representations without leading zeros of the integers $1$ to $9999$. Hence $\iota$ is a bijection from $J$ onto the index suffixes, and its inverse is parsing. The strings .0, .01 and .10000 match no production, and ZIP 321, “Invalid Examples”, rejects address.0= and amount.0=. Parameters whose suffixes denote the same index $i\in J$, the empty index included, belong to one payment $P_i$; the order of the parameters is insignificant, and indices need not be consecutive (ZIP 321, “URI Semantics”). A URI therefore decodes to a finite map $i\mapsto P_i$ on a subset of $J$, and carries at most $|J|=10,000$ payments: $9999$ at indices $1$ to $9999$ and one at the empty index.

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”):

1. (a)

   $u\in L$ under the reading of Definition 14.1; a purported ZIP 321 URI that cannot be so parsed MUST NOT be accepted;

2. (b)

   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);

3. (c)

   every index that carries a parameter other than address carries an address (MUST);

4. (d)

   $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);

5. (e)

   the address, amount and memo rules of §14.2 hold;

6. (f)

   $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.

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.

Examples. On the examples of ZIP 321, “ZEC Transfer Amount” and “Examples”, Construction 14.3 gives the following. The parameter amount=1 denotes $100,000,000$ zatoshi, amount=123.456 denotes $12,345,600,000$ zatoshi, and amount.1=0.789 denotes $78,900,000$ zatoshi for the payment at index $1$. The values 50, 050 and 50.00 denote $5,000,000,000$ zatoshi, and 0.5 and 00.500 denote $50,000,000$ zatoshi. The value 21000000 denotes $\mathrm{𝖬𝖠𝖷}\mathrm{\_}\mathrm{𝖬𝖮𝖭𝖤𝖸}=2,100,000,000,000,000$ zatoshi and is accepted, while 21000000.00000001 exceeds $\mathrm{𝖬𝖠𝖷}\mathrm{\_}\mathrm{𝖬𝖮𝖭𝖤𝖸}$ and is rejected. The values 50,000.00, 50,00, 50., .5 and 0.123456789 are invalid. The parameters address.0= and amount.0= are invalid, their index having a leading zero, and so is any parameter with the five-digit suffix .10000.

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).

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 $\mathrm{Enc}$ produces none. Stripping trailing zeros gives the shortest encoding and is not required: $\mathrm{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 $10,000$ payments (§14.1), and the one transaction it asks for is bounded further by consensus; the bound that binds is the least of the following.

1. (i)

   Size. A block has at most $2,000,000$ bytes (protocol specification, §“Block Header Encoding and Consensus”), and a Sapling output contributes at least $948$ bytes to a transaction, so a transaction has at most $\lfloor 2,000,000/948\rfloor =2109$ Sapling outputs (protocol specification, §“Balance and Binding Signature (Sapling)”). This is the bound that ZIP 321, “URI Semantics”, states.

2. (ii)

   Shielded budget. ZIP 218, part of NU7, requires of every block, with $S$ the number of Sapling spends plus outputs, $A$ the number of Orchard-pool Actions and $n_{\mathrm{𝖩𝖲}}$ the number of JoinSplit descriptions, each summed over the block’s transactions,

   $$S\le 300,A\le 330,A+S+2n_{\mathrm{𝖩𝖲}}\le 330$$

   (ZIP 218, “Shielded pool action limits”). Versions $5$ and $6$ carry no JoinSplit description (Ironwood Guide, §“The transaction format”), so $n_{\mathrm{𝖩𝖲}}=0$. 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 $o\ge n$ Sapling outputs; with $s$ Sapling spends and $a$ Orchard-pool Actions it is mined only if $s+o\le 300$ and $a+s+o\le 330$, hence only if

   $$n\le o\le \min (300,\mathrm{\hspace{0.17em}330}-a)-s.$$

   The all-Sapling bound is therefore $\min (2109,300)=300$ outputs, fewer with spends or Orchard-pool Actions, and the bound of (i) never binds; one transaction carries at most $330$ units of the shared budget.

3. (iii)

   Orchard pool. No payment output lies in the Orchard pool (Construction 11.5, Proposition 11.6), so the Orchard-pool Actions of the transaction only consume the shared budget of (ii).

4. (iv)

   Ironwood pool and transparent outputs. ZIP 218 as written counts neither Ironwood-pool Actions nor transparent components, so payments by Ironwood-pool or transparent outputs are bounded by the size limit alone. Whether Ironwood-pool Actions enter the shared budget is an open proposal (Consensus Guide, §“A block budget for shielded work”). Class of (iv): open problem (Definition 1.1).

From request to plan. Each payment $P_i=(a,v,m)$ of an accepted request, its value fixed by the payer if absent, is a payment in the sense of Definition 11.1 and becomes one output of the plan: its pool is that of Construction 11.5, a TEX address is paid by Construction 11.7, and its memo, if any, is the memo field of that output’s note plaintext (Construction 14.5). A TEX payment funded from shielded notes needs the two transactions of Construction 11.7, so the MUST of ZIP 320, “Design considerations for Senders”, and not the SHOULD of ZIP 321 that asks for a single transaction, fixes the shape of such a plan. From there construction is that of §11.1 and Constructions 11.18 and 11.20: an Orchard-protocol output is sealed as in the Ironwood Guide, §“Encryption to the recipient”, a Sapling output as in the protocol specification, §“Sending Notes (Sapling)”, and the Ironwood Guide, §“Transaction digests and signatures”, gives the digest that every signature signs.