ZIP 321: updates for Unified Addresses.

Signed-off-by: Daira Emma Hopwood <daira@jacaranda.org>

zip-0321.rst

@@ -4,6 +4,7 @@
   Title: Payment Request URIs
   Owners: Kris Nuttycombe (kris@electriccoin.co)
           Daira Emma Hopwood (daira@electriccoin.co)
+  Credits: Francisco Gindre
   Status: Proposed
   Category: Standards / Wallet
   Created: 2020-08-28
@@ -141,9 +142,16 @@ 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
+Implementations SHOULD construct a single transaction that pays all of the
-[#protocol-saplingbalance]_, there may be no more than 2109 distinct payments
+specified instances of ``zcashaddress``. The number of such addresses is
-requested by a single ZIP-321 URI.
+therefore limited by restrictions on transaction construction. In general this
+limit depends, at least, on the mix of destination address types. For example,
+if all payments were to Sapling payment addresses (each specified either
+directly or as a Receiver of a Unified Address), the limit described in
+[#protocol-saplingbalance]_ implies that constructing a transaction for a
+ZIP-321 URI might fail if it requests more than 2109 distinct payments. The
+effective limit might be lower if payments to Orchard addresses or other future
+types of address are included.
 
 A URI of the form ``zcash:<address>?...`` MUST be considered equivalent to a
 URI of the form ``zcash:?address=<address>&...`` where ``<address>`` is an
@@ -154,22 +162,35 @@ 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:
+string encoding of an address, other than a Sprout address, as specified in the
+subsections of section 5.6 (Encoding of Addresses and Keys) of the Zcash protocol
+specification [#protocol-addressandkeyencoding]_. At the time of writing this
+includes the following address formats:
 
-* a Zcash transparent address, using Base58Check [#base58check]_ as defined
+* a Zcash transparent address, as defined in [#protocol-transparentaddrencoding]_,
-  in [#protocol-transparentaddrencoding]_; or
+  using Base58Check [#base58check]_;
-* a Zcash Sapling address, using Bech32 [#zip-0173]_ as defined in
+* a Zcash Sapling payment address as defined in [#protocol-saplingpaymentaddrencoding]_,
-  [#protocol-saplingpaymentaddrencoding]_.
+  using Bech32 [#zip-0173]_;
+* a Zcash Unified Address as defined in [#protocol-unifiedencodings]_ and [#zip-0316]_,
+  using Bech32m [#bip-0350]_.
 
-New address formats may be added in future. If the context of whether the
+New address formats may be added to [#protocol-addressandkeyencoding]_ in future,
-payment URI is intended for Testnet or Mainnet is available, then each address
+and these SHOULD be supported whether or not this ZIP is updated to explicitly
-SHOULD be checked to be for the correct network.
+include them.
+
+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.
+
+All of the requirements of ZIP 316 [#zip-0316]_ apply in the case of payments
+to Unified Addresses.
 
 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
+this is that transfers to Sprout addresses are, since activation of the Canopy
-network upgrade, be restricted by ZIP 211 [#zip-0211]_; it cannot generally
+network upgrade, restricted by ZIP 211 [#zip-0211]_. It cannot generally be
-be expected that senders will have funds available in the Sprout pool with which
+expected that senders will have funds available in the Sprout pool with which
-to satisfy requests for payment to a Sprout address.
+to satisfy requests for payment to a Sprout address. If the same rationale
+applies to other address types in future, consideration should be given to
+updating this ZIP to exclude these types, as part of their deprecation.
 
 Transfer amount
 ---------------
@@ -208,7 +229,8 @@ memo
    ``=`` 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 same ``paramindex`` is not a valid shielded address. 
+   the same ``paramindex`` does not permit the use of memos (i.e. it is a
+   transparent address).
 
 message
    Message that clients can display for the purpose of presenting descriptive
@@ -224,15 +246,15 @@ Valid examples
 
   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,
+A valid payment request for a payment of 1 ZEC to a single shielded Sapling
-with a base64url-encoded memo and a message for display by the wallet.
+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,
+A valid payment request with one transparent and one shielded Sapling recipient
-with an encoded Unicode memo for the shielded recipient.
+address, with a base64url-encoded Unicode memo for the shielded recipient.
 
 Invalid Examples
 ~~~~~~~~~~~~~~~~
@@ -323,10 +345,14 @@ References
 .. [#base64url] `RFC 4648 section 5: Base64 Encoding with URL and Filename Safe Alphabet <https://www.rfc-editor.org/rfc/rfc4648.html#section-5>`_
 .. [#bip-0021] `BIP 21: URI Scheme <https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki>`_
 .. [#bip-0070] `BIP 70: Payment Protocol <https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki>`_
+.. [#bip-0350] `BIP 350: Bech32m format for v1+ witness addresses <https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki>`_
 .. [#base58check] `Bitcoin Wiki: Base58Check encoding <https://en.bitcoin.it/wiki/Base58Check_encoding>`_
 .. [#zip-0173] `ZIP 173: Bech32 Format <zip-0173.rst>`_
 .. [#zip-0211] `ZIP 211: Disabling Addition of New Value to the Sprout Value Pool <zip-0211.rst>`_
+.. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys <zip-0316.rst>`_
 .. [#protocol-networks] `Zcash Protocol Specification, Version 2023.4.0. Section 3.11: Mainnet and Testnet <protocol/protocol.pdf#networks>`_
 .. [#protocol-saplingbalance] `Zcash Protocol Specification, Version 2023.4.0. Section 4.12: Balance and Binding Signature (Sapling) <protocol/protocol.pdf#saplingbalance>`_
+.. [#protocol-addressandkeyencoding] `Zcash Protocol Specification, Version 2023.4.0. Section 5.6: Encodings of Addresses and Keys <protocol/protocol.pdf#addressandkeyencoding>`_
 .. [#protocol-transparentaddrencoding] `Zcash Protocol Specification, Version 2023.4.0. Section 5.6.1.1: Transparent Addresses <protocol/protocol.pdf#transparentaddrencoding>`_
 .. [#protocol-saplingpaymentaddrencoding] `Zcash Protocol Specification, Version 2023.4.0. Section 5.6.3.1: Sapling Payment Addresses <protocol/protocol.pdf#saplingpaymentaddrencoding>`_
+.. [#protocol-unifiedencodings] `Zcash Protocol Specification, Version 2023.4.0. Section 5.6.4.1: Unified Payment Addresses and Viewing Keys <protocol/protocol.pdf#unifiedencodings>`_