ZIP 320: Define the semantics of Source Restriction Metadata Items in UVKs.

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

zip-0320.html

@@ -9,7 +9,7 @@
     <section>
         <pre>ZIP: 320
 Title: Defining an Address Type to which funds can only be sent from Transparent Addresses
-Owners: Daira Emma Hopwood &lt;daira@electriccoin.co&gt;
+Owners: Daira-Emma Hopwood &lt;daira@electriccoin.co&gt;
         Kris Nuttycombe &lt;kris@nutty.land&gt;
 Credits: Hanh
 Status: Draft
@@ -17,7 +17,8 @@ Category: Standards / Wallet
 Created: 2024-01-12
 License: MIT
 Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/757">https://github.com/zcash/zips/issues/757</a>&gt;
-Pull-Request: &lt;<a href="https://github.com/zcash/zips/pull/760">https://github.com/zcash/zips/pull/760</a>&gt;</pre>
+Pull-Request: &lt;<a href="https://github.com/zcash/zips/pull/760">https://github.com/zcash/zips/pull/760</a>&gt;
+              &lt;<a href="https://github.com/zcash/zips/pull/766">https://github.com/zcash/zips/pull/766</a>&gt;</pre>
         <section id="terminology"><h2><span class="section-heading">Terminology</span><span class="section-anchor"> <a rel="bookmark" href="#terminology"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
             <p>The key words "MUST", "SHOULD", and "MAY" in this document are to be interpreted as described in BCP 14 <a id="footnote-reference-1" class="footnote_reference" href="#bcp14">1</a> when, and only when, they appear in all capitals.</p>
             <p>The terms "Recipient", "Producer", "Consumer", "Sender", "Receiver", "Item", "Metadata Item", "Typecode", "Address", "Unified Address" (UA), "Unified Viewing Key" (UVK), "Unified Full Viewing Key" (UFVK), and "Unified Incoming Viewing Key" (UIVK) are to be interpreted as described in ZIP 316 <a id="footnote-reference-2" class="footnote_reference" href="#zip-0316-terminology">5</a>.</p>
@@ -96,13 +97,13 @@ console.log(t1)</pre>
             <section id="specification-alternative-2"><h3><span class="section-heading">Specification (Alternative 2)</span><span class="section-anchor"> <a rel="bookmark" href="#specification-alternative-2"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
                 <p>Upon activation of this ZIP, the section <cite>Metadata Items</cite> of ZIP 316 <a id="footnote-reference-16" class="footnote_reference" href="#zip-0316-metadata-items">10</a> will be modified to define a new MUST-understand Metadata Item type: Source Restriction Metadata, having Typecode
                     <span class="math">\(\mathtt{0xE2}\)</span>
-                , the value of which must be a single byte:</p>
+                , the value of which MUST be a single byte:</p>
                 <ul>
                     <li>
                         <span class="math">\(\mathtt{0x00}\)</span>
                      - Transparent Source Only</li>
                 </ul>
-                <p>Additional Source Restriction Metadata values may be defined in the future.</p>
+                <p>Additional Source Restriction Metadata values can be defined in the future, but a Consumer that does not recognise the value MUST reject the entire UA/UVK as invalid.</p>
                 <p>The "Requirements for both Unified Addresses and Unified Viewing Keys" section of ZIP 316 <a id="footnote-reference-17" class="footnote_reference" href="#zip-0316-unified-requirements">8</a> will be modified as follows — the text:</p>
                 <blockquote>
                     <p>A Unified Address or Unified Viewing Key MUST contain at least one shielded Item (Typecodes
@@ -113,16 +114,16 @@ console.log(t1)</pre>
                 </blockquote>
                 <p>will be replaced by:</p>
                 <blockquote>
-                    <p>A Unified Address MUST contain at least one Receiver and any number of Metadata Items. The selection of Receivers is further restricted such that a Unified Address MUST <strong>either</strong>:</p>
+                    <p>A Unified Address or Unified Viewing Key MUST <strong>either</strong>:</p>
                     <ul>
-                        <li>contain at least one shielded Receiver (Typecodes
+                        <li>contain at least one shielded Item (Typecodes
                             <span class="math">\(\mathtt{0x02}\)</span>
                          and
                             <span class="math">\(\mathtt{0x03}\)</span>
                         ), and <strong>no</strong> Source Restriction Metadata Item having value
                             <span class="math">\(\mathtt{0x00}\)</span>
                         ; <strong>or</strong></li>
-                        <li>contain <strong>both</strong> a Transparent Receiver (Typecode
+                        <li>contain <strong>both</strong> a Transparent Item (Typecode
                             <span class="math">\(\mathtt{0x00}\)</span>
                          or Typecode
                             <span class="math">\(\mathtt{0x01}\)</span>
@@ -130,13 +131,8 @@ console.log(t1)</pre>
                             <span class="math">\(\mathtt{0xE2}\)</span>
                         ) having value
                             <span class="math">\(\mathtt{0x00}\)</span>
-                        , and <strong>no other</strong> Receivers.</li>
+                        , and <strong>no other</strong> non-Metadata Items.</li>
                     </ul>
-                    <p>A Unified Viewing Key MUST contain at least one shielded Item (Typecodes
-                        <span class="math">\(\mathtt{0x02}\)</span>
-                     and
-                        <span class="math">\(\mathtt{0x03}\)</span>
-                    ).</p>
                 </blockquote>
                 <p>In the following, the “<code>u+</code>” Human Readable Part of Revision 1 Unified Addresses is a placeholder value, pending the finalization of Revision 1 <a id="footnote-reference-18" class="footnote_reference" href="#zip-0316-revision-1">7</a>.</p>
                 <p>A Traceable Unified Address is produced from a Mainnet Zcash P2PKH address by executing the following steps:</p>
@@ -161,6 +157,7 @@ console.log(t1)</pre>
                 <p>Wallets and other Senders MUST ensure that only transparent UTXOs are spent in the creation of a transaction to any Unified Address containing a Source Restriction Metadata Item having value
                     <span class="math">\(\mathtt{0x00}\)</span>
                 .</p>
+                <p>Any Source Restriction Metadata Item MUST be preserved with the same value when deriving a UIVK from a UFVK, or a UA from a UIVK. It has no other effect on the meaning of the UFVK or UIVK.</p>
             </section>
             <section id="reference-implementation-alternative-2"><h3><span class="section-heading">Reference Implementation (Alternative 2)</span><span class="section-anchor"> <a rel="bookmark" href="#reference-implementation-alternative-2"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
                 <p>Javascript using <cite>zcash_address_wasm</cite> <a id="footnote-reference-23" class="footnote_reference" href="#zcash-address-wasm">17</a>:</p>
@@ -213,6 +210,7 @@ expiry time: Mon Feb 13 2024 01:14:18 GMT</pre>
                 <ul>
                     <li>By integrating with the Unified Address framework, Consumers of Revision 1 Unified Addresses that have not yet been upgraded to recognize these addresses can automatically be prompted to upgrade their wallets or services to understand the unrecognized MUST-understand Metadata Typecode.</li>
                     <li>It is possible to include address expiration metadata in a Traceable Unified Address, which can help to mitigate problems related to stored addresses in the future.</li>
+                    <li>The Source Restriction Metadata feature can easily be extended to express other kinds of source restriction, such as "Shielded Source Only" or "Fully Shielded with No Pool Crossing".</li>
                     <li>Traceable Unified Addresses benefit from the robustness to errors and protection against malleation of Unified Addresses <a id="footnote-reference-25" class="footnote_reference" href="#f4jumble">15</a>.</li>
                     <li>Regardless of which proposal is adopted, the Zcash Community will need to work with exchanges other than Binance to update their address parsing logic to understand the new address format. By encouraging Consumers such as exchanges to adopt parsing for Unified Addresses, this proposal furthers the original goal of Unified Addresses to reduce fragmentation in the address ecosystem.
                         <p>Whenever any new feature is added, wallets have a choice whether or not to support that new feature. The point of Unified Address parsing is that wallets don’t have to upgrade to recognize a different address format as a valid Zcash address. Instead of returning a “Not a valid Zcash address” error, which could be confusing for users, they can return an error more like “This is a valid Zcash address, but this wallet does not support sending to it.” This can be used as a prompt to upgrade the wallet to a version (or alternative) that does support that feature.</p>

zip-0320.rst

@@ -2,7 +2,7 @@
 
   ZIP: 320
   Title: Defining an Address Type to which funds can only be sent from Transparent Addresses
-  Owners: Daira Emma Hopwood <daira@electriccoin.co>
+  Owners: Daira-Emma Hopwood <daira@electriccoin.co>
           Kris Nuttycombe <kris@nutty.land>
   Credits: Hanh
   Status: Draft
@@ -11,6 +11,7 @@
   License: MIT
   Discussions-To: <https://github.com/zcash/zips/issues/757>
   Pull-Request: <https://github.com/zcash/zips/pull/760>
+                <https://github.com/zcash/zips/pull/766>
 
 Terminology
 ===========
@@ -178,11 +179,13 @@ Specification (Alternative 2)
 Upon activation of this ZIP, the section `Metadata Items` of ZIP 316
 [#zip-0316-metadata-items]_ will be modified to define a new MUST-understand
 Metadata Item type: Source Restriction Metadata, having Typecode
-:math:`\mathtt{0xE2}`, the value of which must be a single byte:
+:math:`\mathtt{0xE2}`, the value of which MUST be a single byte:
 
 * :math:`\mathtt{0x00}` - Transparent Source Only
 
-Additional Source Restriction Metadata values may be defined in the future.
+Additional Source Restriction Metadata values can be defined in the future,
+but a Consumer that does not recognise the value MUST reject the entire
+UA/UVK as invalid.
 
 The "Requirements for both Unified Addresses and Unified Viewing Keys" section
 of ZIP 316 [#zip-0316-unified-requirements]_ will be modified as follows — the
@@ -197,20 +200,15 @@ text:
 
 will be replaced by:
 
-  A Unified Address MUST contain at least one Receiver and any number
+  A Unified Address or Unified Viewing Key MUST **either**:
-  of Metadata Items. The selection of Receivers is further restricted 
-  such that a Unified Address MUST **either**:
 
-  * contain at least one shielded Receiver (Typecodes :math:`\mathtt{0x02}`
+  * contain at least one shielded Item (Typecodes :math:`\mathtt{0x02}`
     and :math:`\mathtt{0x03}`), and **no** Source Restriction Metadata Item
     having value :math:`\mathtt{0x00}`; **or**
-  * contain **both** a Transparent Receiver (Typecode :math:`\mathtt{0x00}` or
+  * contain **both** a Transparent Item (Typecode :math:`\mathtt{0x00}` or
     Typecode :math:`\mathtt{0x01}`) **and** a Source Restriction Metadata Item
     (Typecode :math:`\mathtt{0xE2}`) having value :math:`\mathtt{0x00}`, and
-    **no other** Receivers.
+    **no other** non-Metadata Items.
-
-  A Unified Viewing Key MUST contain at least one shielded Item (Typecodes
-  :math:`\mathtt{0x02}` and :math:`\mathtt{0x03}`). 
 
 In the following, the “``u+``” Human Readable Part of Revision 1 Unified
 Addresses is a placeholder value, pending the finalization of Revision 1 
@@ -245,6 +243,10 @@ Wallets and other Senders MUST ensure that only transparent UTXOs are spent in
 the creation of a transaction to any Unified Address containing a Source
 Restriction Metadata Item having value :math:`\mathtt{0x00}`.
 
+Any Source Restriction Metadata Item MUST be preserved with the same value
+when deriving a UIVK from a UFVK, or a UA from a UIVK. It has no other effect
+on the meaning of the UFVK or UIVK.
+
 Reference Implementation (Alternative 2)
 ----------------------------------------
 
@@ -322,6 +324,9 @@ Pros To Alternative 2
 - It is possible to include address expiration metadata in a Traceable Unified
   Address, which can help to mitigate problems related to stored addresses in
   the future.
+- The Source Restriction Metadata feature can easily be extended to express
+  other kinds of source restriction, such as "Shielded Source Only" or
+  "Fully Shielded with No Pool Crossing".
 - Traceable Unified Addresses benefit from the robustness to errors and
   protection against malleation of Unified Addresses [#F4Jumble]_.
 - Regardless of which proposal is adopted, the Zcash Community will need to