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

ZIP 316: clarify requirements, especially for Unified Viewing Keys. 

This required introducing the Consumer definition, since a Consumer
of a UVK is not necessarily a Sender.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>
This commit is contained in:
Daira Hopwood 2021-07-12 13:18:31 +01:00
parent 9d6fa7d8ec
commit af1bee056f
2 changed files with 98 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
zip-0316.html
View File

@ -29,8 +29,10 @@ Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/482">https://g
<dd>A wallet or other software that can receive transfers of assets (such as ZEC) or in the future potentially other transaction-based state changes.</dd>
<dt>Producer</dt>
<dd>A wallet or other software that can create an Address (normally also a Recipient).</dd>
<dt>Consumer</dt>
<dd>A wallet or other software that can make use of an Address that it is given.</dd>
<dt>Sender</dt>
<dd>A wallet or other software that can send transfers of assets, or other consensus state side-effects defined in future.</dd>
<dd>A wallet or other software that can send transfers of assets, or other consensus state side-effects defined in future. Senders are a subset of Consumers.</dd>
<dt>Receiver</dt>
<dd>The necessary information to transfer an asset to a Recipient that generated that Receiver using a specific Transfer Protocol. Each Receiver is associated unambiguously with a specific Receiver Type, identified by an integer Typecode.</dd>
<dt>Receiver Encoding</dt>
@ -63,10 +65,10 @@ Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/482">https://g
</ul>
<p>Each of these has its own Address Encodings, as a string and as a QR code. (Since the QR code is derivable from the string encoding, for many purposes it suffices to consider the string encoding.)</p>
<p>The Orchard proposal <a id="id2" class="footnote_reference" href="#zip-0224">6</a> adds a new Address type, Orchard Addresses.</p>
<p>The difficulty with defining new Address Encodings for each Address type, is that end-users are forced to be aware of the various types, and in particular which types are supported by a given Sender or Recipient. In order to make sure that transfers are completed successfully, users may be forced to explicitly generate Addresses of different types and re-distribute encodings of them, which adds significant friction and cognitive overhead to understanding and using Zcash.</p>
<p>The difficulty with defining new Address Encodings for each Address type, is that end-users are forced to be aware of the various types, and in particular which types are supported by a given Consumer or Recipient. In order to make sure that transfers are completed successfully, users may be forced to explicitly generate Addresses of different types and re-distribute encodings of them, which adds significant friction and cognitive overhead to understanding and using Zcash.</p>
<p>The goals for a Unified Address standard are as follows:</p>
<ul>
<li>Simplify coordination between Recipients and Senders by removing complexity from negotiating Address types.</li>
<li>Simplify coordination between Recipients and Consumers by removing complexity from negotiating Address types.</li>
<li>Provide a “bridging mechanism” to allow shielded wallets to successfully interact with conformant Transparent-Only wallets.</li>
<li>Allow older conformant wallets to interact seamlessly with newer wallets.</li>
<li>Enable users of newer wallets to upgrade to newer transaction technologies and/or pools while maintaining seamless interactions with counterparties using older wallets.</li>
@ -89,11 +91,11 @@ Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/482">https://g
<li>A Producer <em>generates</em> an Address.</li>
<li>The Producer <em>encodes</em> the Address.</li>
<li>The Producer wallet or human user <em>distributes</em> this Address Encoding, This ZIP leaves distribution mechanisms out of scope.</li>
<li>A Sender wallet or user <em>imports</em> the Address Encoding through any of a variety of mechanisms (QR Code scanning, Payment URIs, cut-and-paste, or “in-band” protocols like <code>Reply-To</code> memos).</li>
<li>A Sender wallet <em>decodes</em> the Address Encoding and performs validity checks.</li>
<li>(Perhaps later in time) the Sender wallet executes a transfer of ZEC (or other assets or protocol state changes) to the Address.</li>
<li>A Consumer wallet or user <em>imports</em> the Address Encoding through any of a variety of mechanisms (QR Code scanning, Payment URIs, cut-and-paste, or “in-band” protocols like <code>Reply-To</code> memos).</li>
<li>A Consumer wallet <em>decodes</em> the Address Encoding and performs validity checks.</li>
<li>(Perhaps later in time) if the Consumer wallet is a Sender, it can execute a transfer of ZEC (or other assets or protocol state changes) to the Address.</li>
</ol>
<p>Encodings of the same Address may be distributed zero or more times through different means. Zero or more Senders may import Addresses. Zero or more of those may execute a Transfer. A single Sender may execute multiple Transfers over time from a single import.</p>
<p>Encodings of the same Address may be distributed zero or more times through different means. Zero or more Consumers may import Addresses. Zero or more of those (that are Senders) may execute a Transfer. A single Sender may execute multiple Transfers over time from a single import.</p>
<p>Steps 1 to 5 inclusive also apply to Interaction Flows for Unified Full Viewing Keys and Unified Incoming Viewing Keys.</p>
</section>
<section id="addresses"><h3><span class="section-heading">Addresses</span><span class="section-anchor"> <a rel="bookmark" href="#addresses"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
@ -134,7 +136,7 @@ Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/482">https://g
</section>
<section id="specification"><h2><span class="section-heading">Specification</span><span class="section-anchor"> <a rel="bookmark" href="#specification"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<section id="encoding-of-unified-addresses"><h3><span class="section-heading">Encoding of Unified Addresses</span><span class="section-anchor"> <a rel="bookmark" href="#encoding-of-unified-addresses"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Rather than defining a Bech32 string encoding of Orchard Shielded Payment Addresses, we instead define a Unified Address format that is able to encode a set of Receivers of different types. This enables the consumer of a Unified Address (i.e. the Sender) to choose the Receiver of the best type it supports, providing a better user experience as new Receiver Types are added in the future.</p>
<p>Rather than defining a Bech32 string encoding of Orchard Shielded Payment Addresses, we instead define a Unified Address format that is able to encode a set of Receivers of different types. This enables the Consumer of a Unified Address to choose the Receiver of the best type it supports, providing a better user experience as new Receiver Types are added in the future.</p>
<p>Assume that we are given a set of one or more Receiver Encodings for distinct types. That is, the set may optionally contain one Receiver of each of the Receiver Types in the following fixed Priority List:</p>
<ul>
<li>Typecode
@ -150,9 +152,6 @@ Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/482">https://g
— a Transparent P2PKH address.</li>
</ul>
<p>We say that a Receiver Type is “preferred” over another when it appears earlier in this Priority List.</p>
<p>A Unified Address MUST contain at least one shielded Receiver (Typecodes
<span class="math">\(\geq \mathtt{0x02}\)</span>
).</p>
<p>The Sender of a payment to a Unified Address MUST use the Receiver of the most preferred Receiver Type that it supports from the set.</p>
<p>For example, consider a wallet that supports sending funds to Orchard Receivers, and does not support sending to any Receiver Type that is preferred over Orchard. If that wallet is given a UA that includes an Orchard Receiver and possibly other Receivers, it MUST send to the Orchard Receiver.</p>
<p>The raw encoding of a Unified Address is a concatenation of
@ -179,7 +178,7 @@ Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/482">https://g
<p>We append 16 zero bytes to the concatenated encodings, and then apply the
<span class="math">\(\mathsf{F4Jumble}\)</span>
algorithm as described in <a href="#address-hardening">Address Hardening</a>. The output is then encoded with Bech32m <a id="id10" class="footnote_reference" href="#bip-0350">8</a>, ignoring any length restrictions. This is chosen over Bech32 in order to better handle variable-length inputs.</p>
<p>To decode a Unified Address Encoding, a Sender MUST use the following procedure:</p>
<p>To decode a Unified Address Encoding, a Consumer MUST use the following procedure:</p>
<ul>
<li>Decode using Bech32m, rejecting any address with an incorrect checksum.</li>
<li>Apply
@ -189,29 +188,36 @@ Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/482">https://g
<li>Parse the result as a raw encoding as described above, rejecting the entire Unified Address if it does not parse correctly.</li>
</ul>
<p>For Unified Addresses on Mainnet, the Human-Readable Part (as defined in <a id="id11" class="footnote_reference" href="#bip-0350">8</a>) is “<code>u</code>”. For Unified Addresses on Testnet, the Human-Readable Part is “<code>utest</code>”.</p>
<p>Notes:</p>
<p>A wallet MAY allow its user(s) to configure which Receiver Types it can send to. It MUST NOT allow the user(s) to change the order of the Priority List used to choose the Receiver Type.</p>
</section>
<section id="encoding-of-unified-full-incoming-viewing-keys"><h3><span class="section-heading">Encoding of Unified Full/Incoming Viewing Keys</span><span class="section-anchor"> <a rel="bookmark" href="#encoding-of-unified-full-incoming-viewing-keys"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Unified Full or Incoming Viewing Keys are encoded and decoded analogously to Unified Addresses. A Consumer MUST use the decoding procedure from the previous section. The same Priority List and the same Typecodes are used. The Priority List only applies to situations in which a Consumer needs to choose a particular Receiver.</p>
<p>For Shielded Addresses, the encoding used in place of the
<span class="math">\(\mathtt{addr}\)</span>
field is the raw encoding of the Full Viewing Key or Incoming Viewing Key.</p>
<p>Transparent Addresses do not have separate corresponding viewing keys, but the address itself can effectively be used as a viewing key. Therefore, a UFVK or UIVK MAY include a Transparent Address, which is encoded using the same Typecode and Receiver Encoding as in a Unified Address.</p>
</section>
<section id="requirements-for-both-unified-addresses-and-unified-viewing-keys"><h3><span class="section-heading">Requirements for both Unified Addresses and Unified Viewing Keys</span><span class="section-anchor"> <a rel="bookmark" href="#requirements-for-both-unified-addresses-and-unified-viewing-keys"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<ul>
<li>A Unified Address or Unified Viewing Key MUST NOT contain only transparent P2SH or P2PKH addresses (Typecodes
<span class="math">\(\mathtt{0x00}\)</span>
and
<span class="math">\(\mathtt{0x01}\)</span>
). The rationale is that the existing P2SH and P2PKH transparent-only address formats suffice for this purpose and are already supported by the existing ecosystem.</li>
<li>The
<span class="math">\(\mathtt{length}\)</span>
field is always encoded as a single byte, <em>not</em> as a
<span class="math">\(\mathtt{compactSize}\)</span>
.</li>
<li>For Transparent Addresses, the Receiver Encoding does not include the first two bytes of a raw encoding.</li>
<li>There is intentionally no Typecode defined for a Sprout Shielded Payment Address. Since it is no longer possible (since activation of ZIP 211 in the Canopy network upgrade <a id="id12" class="footnote_reference" href="#zip-0211">5</a>) to send funds into the Sprout chain value pool, this would not be generally useful.</li>
<li>Senders MUST ignore constituent Addresses with Typecodes they do not recognize.</li>
<li>Senders MUST reject Unified Addresses in which the same Typecode appears more than once, or that include both P2SH and P2PKH Transparent Addresses, or that contain only a Transparent Address.</li>
<li>Senders MUST reject Unified Addresses in which <em>any</em> constituent address does not meet the validation requirements of its Receiver Encoding, as specified in the Zcash Protocol Specification <a id="id13" class="footnote_reference" href="#protocol-nu5">2</a>.</li>
<li>Producers SHOULD order the constituent Addresses in the same order as in the Priority List above. However, Senders MUST NOT assume this ordering, and it does not affect which Address should be used by a Sender.</li>
<li>There is intentionally no Typecode defined for a Sprout Shielded Payment Address or Sprout Incoming Viewing Key. Since it is no longer possible (since activation of ZIP 211 in the Canopy network upgrade <a id="id12" class="footnote_reference" href="#zip-0211">5</a>) to send funds into the Sprout chain value pool, this would not be generally useful.</li>
<li>Senders MUST ignore constituent Addresses/Viewing Keys with Typecodes they do not recognize.</li>
<li>Senders MUST reject Unified Addresses/Viewing Keys in which the same Typecode appears more than once, or that include both P2SH and P2PKH Transparent Addresses, or that contain only a Transparent Address.</li>
<li>Senders MUST reject Unified Addresses/Viewing Keys in which <em>any</em> constituent address does not meet the validation requirements of its Receiver Encoding, as specified in the Zcash Protocol Specification <a id="id13" class="footnote_reference" href="#protocol-nu5">2</a>.</li>
<li>Producers SHOULD order the constituent Addresses/Viewing Keys in the same order as in the Priority List above. However, Consumers MUST NOT assume this ordering, and it does not affect which Address should be used by a Sender.</li>
<li>There MUST NOT be additional bytes at the end of the raw encoding that cannot be interpreted as specified above.</li>
<li>A wallet MAY allow its user(s) to configure which Receiver Types it can send to. It MUST NOT allow the user(s) to change the order of the Priority List used to choose the Receiver Type.</li>
</ul>
</section>
<section id="encoding-of-unified-full-incoming-viewing-keys"><h3><span class="section-heading">Encoding of Unified Full/Incoming Viewing Keys</span><span class="section-anchor"> <a rel="bookmark" href="#encoding-of-unified-full-incoming-viewing-keys"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Unified Full or Incoming Viewing Keys are encoded analogously to Unified Addresses. The same Priority List and the same Typecodes are used. For Shielded Addresses, the encoding used in place of the
<span class="math">\(\mathtt{addr}\)</span>
field is the raw encoding of the Full Viewing Key or Incoming Viewing Key.</p>
<p>Transparent Addresses do not have separate corresponding viewing keys, but the address itself can effectively be used as a viewing key. Therefore, a UFVK or UIVK MAY include a Transparent Address, which is encoded using the same Typecode and Receiver Encoding as in a Unified Address.</p>
</section>
<section id="address-hardening"><h3><span class="section-heading">Address hardening</span><span class="section-anchor"> <a rel="bookmark" href="#address-hardening"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Security goal (<strong>near second preimage resistance</strong>):</p>
<ul>

120
zip-0316.rst
View File

@ -30,9 +30,12 @@ Recipient
Producer
A wallet or other software that can create an Address (normally also a
Recipient).
Consumer
A wallet or other software that can make use of an Address that it is given.
Sender
A wallet or other software that can send transfers of assets, or other
consensus state side-effects defined in future.
consensus state side-effects defined in future. Senders are a subset of
Consumers.
Receiver
The necessary information to transfer an asset to a Recipient that generated
that Receiver using a specific Transfer Protocol. Each Receiver is associated
@ -89,7 +92,7 @@ The Orchard proposal [#zip-0224]_ adds a new Address type, Orchard Addresses.
The difficulty with defining new Address Encodings for each Address type, is
that end-users are forced to be aware of the various types, and in particular
which types are supported by a given Sender or Recipient. In order to make
which types are supported by a given Consumer or Recipient. In order to make
sure that transfers are completed successfully, users may be forced to
explicitly generate Addresses of different types and re-distribute encodings
of them, which adds significant friction and cognitive overhead to
@ -97,7 +100,7 @@ understanding and using Zcash.
The goals for a Unified Address standard are as follows:
- Simplify coordination between Recipients and Senders by removing complexity
- Simplify coordination between Recipients and Consumers by removing complexity
from negotiating Address types.
- Provide a “bridging mechanism” to allow shielded wallets to successfully
interact with conformant Transparent-Only wallets.
@ -146,18 +149,19 @@ Wallets follow a model *Interaction Flow* as follows:
2. The Producer *encodes* the Address.
3. The Producer wallet or human user *distributes* this Address Encoding,
This ZIP leaves distribution mechanisms out of scope.
4. A Sender wallet or user *imports* the Address Encoding through any of
4. A Consumer wallet or user *imports* the Address Encoding through any of
a variety of mechanisms (QR Code scanning, Payment URIs, cut-and-paste,
or “in-band” protocols like ``Reply-To`` memos).
5. A Sender wallet *decodes* the Address Encoding and performs validity
5. A Consumer wallet *decodes* the Address Encoding and performs validity
checks.
6. (Perhaps later in time) the Sender wallet executes a transfer of ZEC
(or other assets or protocol state changes) to the Address.
6. (Perhaps later in time) if the Consumer wallet is a Sender, it can execute
a transfer of ZEC (or other assets or protocol state changes) to the
Address.
Encodings of the same Address may be distributed zero or more times through
different means. Zero or more Senders may import Addresses. Zero or more of
those may execute a Transfer. A single Sender may execute multiple Transfers
over time from a single import.
different means. Zero or more Consumers may import Addresses. Zero or more of
those (that are Senders) may execute a Transfer. A single Sender may execute
multiple Transfers over time from a single import.
Steps 1 to 5 inclusive also apply to Interaction Flows for Unified Full Viewing
Keys and Unified Incoming Viewing Keys.
@ -267,9 +271,9 @@ Encoding of Unified Addresses
Rather than defining a Bech32 string encoding of Orchard Shielded
Payment Addresses, we instead define a Unified Address format that
is able to encode a set of Receivers of different types. This enables
the consumer of a Unified Address (i.e. the Sender) to choose the
Receiver of the best type it supports, providing a better user
experience as new Receiver Types are added in the future.
the Consumer of a Unified Address to choose the Receiver of the best
type it supports, providing a better user experience as new Receiver
Types are added in the future.
Assume that we are given a set of one or more Receiver Encodings
for distinct types. That is, the set may optionally contain one
@ -288,9 +292,6 @@ Priority List:
We say that a Receiver Type is “preferred” over another when it appears
earlier in this Priority List.
A Unified Address MUST contain at least one shielded Receiver
(Typecodes :math:`\geq \mathtt{0x02}`).
The Sender of a payment to a Unified Address MUST use the Receiver
of the most preferred Receiver Type that it supports from the set.
@ -322,7 +323,7 @@ The output is then encoded with Bech32m [#bip-0350]_, ignoring any
length restrictions. This is chosen over Bech32 in order to better
handle variable-length inputs.
To decode a Unified Address Encoding, a Sender MUST use the following
To decode a Unified Address Encoding, a Consumer MUST use the following
procedure:
* Decode using Bech32m, rejecting any address with an incorrect checksum.
@ -336,7 +337,39 @@ For Unified Addresses on Mainnet, the Human-Readable Part (as defined
in [#bip-0350]_) is “``u``”. For Unified Addresses on Testnet, the
Human-Readable Part is “``utest``”.
Notes:
A wallet MAY allow its user(s) to configure which Receiver Types it
can send to. It MUST NOT allow the user(s) to change the order of the
Priority List used to choose the Receiver Type.
Encoding of Unified Full/Incoming Viewing Keys
----------------------------------------------
Unified Full or Incoming Viewing Keys are encoded and decoded
analogously to Unified Addresses. A Consumer MUST use the decoding
procedure from the previous section. The same Priority List and the
same Typecodes are used. The Priority List only applies to situations
in which a Consumer needs to choose a particular Receiver.
For Shielded Addresses, the encoding used in place of the
:math:`\mathtt{addr}` field is the raw encoding of the Full Viewing Key
or Incoming Viewing Key.
Transparent Addresses do not have separate corresponding viewing keys,
but the address itself can effectively be used as a viewing key.
Therefore, a UFVK or UIVK MAY include a Transparent Address, which
is encoded using the same Typecode and Receiver Encoding as in a
Unified Address.
Requirements for both Unified Addresses and Unified Viewing Keys
----------------------------------------------------------------
* A Unified Address or Unified Viewing Key MUST NOT contain only
transparent P2SH or P2PKH addresses (Typecodes :math:`\mathtt{0x00}`
and :math:`\mathtt{0x01}`). The rationale is that the existing
P2SH and P2PKH transparent-only address formats suffice for this
purpose and are already supported by the existing ecosystem.
* The :math:`\mathtt{length}` field is always encoded as a single
byte, *not* as a :math:`\mathtt{compactSize}`.
@ -345,51 +378,32 @@ Notes:
the first two bytes of a raw encoding.
* There is intentionally no Typecode defined for a Sprout Shielded
Payment Address. Since it is no longer possible (since activation
of ZIP 211 in the Canopy network upgrade [#zip-0211]_) to send
funds into the Sprout chain value pool, this would not be generally
useful.
Payment Address or Sprout Incoming Viewing Key. Since it is no
longer possible (since activation of ZIP 211 in the Canopy network
upgrade [#zip-0211]_) to send funds into the Sprout chain value
pool, this would not be generally useful.
* Senders MUST ignore constituent Addresses with Typecodes they do
not recognize.
* Senders MUST ignore constituent Addresses/Viewing Keys with
Typecodes they do not recognize.
* Senders MUST reject Unified Addresses in which the same Typecode
appears more than once, or that include both P2SH and P2PKH
Transparent Addresses, or that contain only a Transparent Address.
* Senders MUST reject Unified Addresses/Viewing Keys in which the
same Typecode appears more than once, or that include both P2SH and
P2PKH Transparent Addresses, or that contain only a Transparent
Address.
* Senders MUST reject Unified Addresses in which *any* constituent
address does not meet the validation requirements of its
* Senders MUST reject Unified Addresses/Viewing Keys in which *any*
constituent address does not meet the validation requirements of its
Receiver Encoding, as specified in the Zcash Protocol Specification
[#protocol-nu5]_.
* Producers SHOULD order the constituent Addresses in the same order
as in the Priority List above. However, Senders MUST NOT assume
this ordering, and it does not affect which Address should be used
by a Sender.
* Producers SHOULD order the constituent Addresses/Viewing Keys in
the same order as in the Priority List above. However, Consumers
MUST NOT assume this ordering, and it does not affect which Address
should be used by a Sender.
* There MUST NOT be additional bytes at the end of the raw encoding
that cannot be interpreted as specified above.
* A wallet MAY allow its user(s) to configure which Receiver Types
it can send to. It MUST NOT allow the user(s) to change the order
of the Priority List used to choose the Receiver Type.
Encoding of Unified Full/Incoming Viewing Keys
----------------------------------------------
Unified Full or Incoming Viewing Keys are encoded analogously to
Unified Addresses. The same Priority List and the same Typecodes are
used. For Shielded Addresses, the encoding used in place of the
:math:`\mathtt{addr}` field is the raw encoding of the Full Viewing
Key or Incoming Viewing Key.
Transparent Addresses do not have separate corresponding viewing keys,
but the address itself can effectively be used as a viewing key.
Therefore, a UFVK or UIVK MAY include a Transparent Address, which
is encoded using the same Typecode and Receiver Encoding as in a
Unified Address.
Address hardening
-----------------