zec
/
zips
mirror of https://github.com/zcash/zips.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

ZIP 321: updates for Unified Addresses. 

Signed-off-by: Daira Emma Hopwood <daira@jacaranda.org>
This commit is contained in:
Daira Emma Hopwood 2023-12-25 22:14:50 +00:00
parent a08c861dd9
commit e6dc1ab660
1 changed files with 46 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
zip-0321.rst
View File

@ -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
[#protocol-saplingbalance]_, there may be no more than 2109 distinct payments
requested by a single ZIP-321 URI.
Implementations SHOULD construct a single transaction that pays all of the
specified instances of ``zcashaddress``. The number of such addresses is
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
in [#protocol-transparentaddrencoding]_; or
* a Zcash Sapling address, using Bech32 [#zip-0173]_ as defined in
[#protocol-saplingpaymentaddrencoding]_.
* a Zcash transparent address, as defined in [#protocol-transparentaddrencoding]_,
using Base58Check [#base58check]_;
* a Zcash Sapling payment address as defined in [#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
payment URI is intended for Testnet or Mainnet is available, then each address
SHOULD be checked to be for the correct network.
New address formats may be added to [#protocol-addressandkeyencoding]_ in future,
and these SHOULD be supported whether or not this ZIP is updated to explicitly
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
network upgrade, be restricted by ZIP 211 [#zip-0211]_; 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.
this is that transfers to Sprout addresses are, since activation of the Canopy
network upgrade, restricted by ZIP 211 [#zip-0211]_. 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 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,
with a base64url-encoded memo and a message for display by the wallet.
A valid payment request for a payment of 1 ZEC to a single shielded Sapling
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.
A valid payment request with one transparent and one shielded Sapling 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>`_