mirror of https://github.com/zcash/zips.git
ZIP 316: regenerate HTML.
Signed-off-by: Daira Hopwood <daira@jacaranda.org>
This commit is contained in:
Daira Hopwood
parent
2d5159361e
commit
fbad8acac0
|
|
@ -41,14 +41,18 @@ Discussions-To: <<a href="https://github.com/zcash/zips/issues/482">https://g
|
|||
<dd>The necessary information to view information about payments to an Address, or (in the case of a Full Viewing Key) from an Address. An Incoming Viewing Key can be derived from a Full Viewing Key, and an Address can be derived from an Incoming Viewing Key.</dd>
|
||||
<dt>Viewing Key Encoding</dt>
|
||||
<dd>An encoding of a Viewing Key as a byte sequence.</dd>
|
||||
<dt>Metadata Encoding</dt>
|
||||
<dd>An encoding of metadata that is not a Receiver or Viewing Key, but may affect the interpretation of the overall Unified Address/Viewing Key.</dd>
|
||||
<dt>Item</dt>
|
||||
<dd>An Receiver Encoding, Viewing Key Encoding, or Metadata Encoding.</dd>
|
||||
<dt>Legacy Address</dt>
|
||||
<dd>A Transparent, Sprout, or Sapling Address.</dd>
|
||||
<dt>Unified Address (or UA)</dt>
|
||||
<dd>A Unified Address combines multiple Receivers.</dd>
|
||||
<dd>A Unified Address combines multiple Receiver (and optionally Metadata) items.</dd>
|
||||
<dt>Unified Full Viewing Key (or UFVK)</dt>
|
||||
<dd>A Unified Full Viewing Key combines multiple Full Viewing Keys.</dd>
|
||||
<dd>A Unified Full Viewing Key combines multiple Full Viewing Key (and optionally Metadata) items.</dd>
|
||||
<dt>Unified Incoming Viewing Key (or UIVK)</dt>
|
||||
<dd>A Unified Incoming Viewing Key combines multiple Incoming Viewing Keys.</dd>
|
||||
<dd>A Unified Incoming Viewing Key combines multiple Incoming Viewing Key (and optionally Metadata) items.</dd>
|
||||
<dt>Unified Viewing Key</dt>
|
||||
<dd>Either a Unified Full Viewing Key or a Unified Incoming Viewing Key.</dd>
|
||||
<dt>Address</dt>
|
||||
|
|
@ -83,6 +87,7 @@ Discussions-To: <<a href="https://github.com/zcash/zips/issues/482">https://g
|
|||
<li>Allow wallets to potentially develop new transfer mechanisms without underlying protocol changes.</li>
|
||||
<li>Support abstractions corresponding to a Unified Address that provide the functionality of Full Viewing Keys and Incoming Viewing Keys.</li>
|
||||
<li>Provide forward compatibility that is standard for all wallets across a range of potential future features. Some examples might include Layer 2 features, cross-chain interoperability and bridging, and decentralized exchange.</li>
|
||||
<li>Allow for Metadata items to be included in Unified Addresses/Viewing Keys in order to provide future extensibility.</li>
|
||||
<li>The standard should work well for Zcash today and upcoming potential upgrades, and also anticipate even broader use cases down the road such as cross-chain functionality.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
|
@ -110,8 +115,8 @@ Discussions-To: <<a href="https://github.com/zcash/zips/issues/482">https://g
|
|||
<p>When new Transport Protocols are introduced to the Zcash protocol after Unified Addresses are standardized, those should introduce new Receiver Types but <em>not</em> different Address types outside of the UA standard. There needs to be a compelling reason to deviate from the standard, since the benefits of UA come precisely from their applicability across all new protocol upgrades.</p>
|
||||
</section>
|
||||
<section id="receivers"><h3><span class="section-heading">Receivers</span><span class="section-anchor"> <a rel="bookmark" href="#receivers"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>Every Wallet must properly <em>parse</em> a Unified Address containing unrecognized Receiver Types; and similarly for Unified Viewing Keys containing unrecognized Viewing Key Types.</p>
|
||||
<p>A Wallet may process unrecognized Receiver Types or Viewing Key Types by indicating to the user their presence or similar information for usability or diagnostic purposes.</p>
|
||||
<p>Every Wallet must properly <em>parse</em> a Unified Address or Unified Viewing Key containing unrecognized Items.</p>
|
||||
<p>A Wallet may process unrecognized Items by indicating to the user their presence or similar information for usability or diagnostic purposes.</p>
|
||||
</section>
|
||||
<section id="transport-encoding"><h3><span class="section-heading">Transport Encoding</span><span class="section-anchor"> <a rel="bookmark" href="#transport-encoding"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>The string encoding is “opaque” to human readers: it does <em>not</em> allow visual identification of which Receivers or Receiver Types are present.</p>
|
||||
|
|
@ -124,7 +129,7 @@ Discussions-To: <<a href="https://github.com/zcash/zips/issues/482">https://g
|
|||
</section>
|
||||
<section id="transfers"><h3><span class="section-heading">Transfers</span><span class="section-anchor"> <a rel="bookmark" href="#transfers"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>When executing a Transfer the Sender selects a Receiver via a Selection process.</p>
|
||||
<p>Given a valid UA, Selection must treat any unrecognized Receiver as though it were absent.</p>
|
||||
<p>Given a valid UA, Selection must treat any unrecognized Item as though it were absent.</p>
|
||||
<ul>
|
||||
<li>This property is crucial for forward compatibility to ensure users who upgrade to newer protocols / UAs don't lose the ability to smoothly interact with older wallets.</li>
|
||||
<li>This property is crucial for allowing Transparent-Only UA-Conformant wallets to interact with newer shielded wallets, removing a disincentive for adopting newer shielded wallets.</li>
|
||||
|
|
@ -160,12 +165,13 @@ Discussions-To: <<a href="https://github.com/zcash/zips/issues/482">https://g
|
|||
<span class="math">\(\mathtt{0x00}\)</span>
|
||||
— 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>If, and only if, the user of a Producer or Consumer wallet explicitly opts into an experiment as described in <a href="#experimental-usage">Experimental Usage</a>, the specification of the experiment MAY include additions to the above Priority List (such additions SHOULD maintain the intent of preferring more recent shielded protocols).</p>
|
||||
<p>We say that a Receiver Type is “preferred” over another when it appears earlier in this Priority List (as potentially modified by experiments).</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
|
||||
<span class="math">\((\mathtt{typecode}, \mathtt{length}, \mathtt{addr})\)</span>
|
||||
encodings of the consituent Receivers:</p>
|
||||
encodings of the consituent Receivers, in ascending order of Typecode:</p>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="math">\(\mathtt{typecode} : \mathtt{compactSize}\)</span>
|
||||
|
|
@ -204,7 +210,7 @@ Discussions-To: <<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="id14" class="footnote_reference" href="#bip-0350">25</a>) is “<code>u</code>”. For Unified Addresses on Testnet, the Human-Readable Part is “<code>utest</code>”.</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>
|
||||
<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, except by opting into experiments.</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. For Viewing Keys, a Consumer will normally take the union of information provided by all contained Receivers, and therefore the Priority List defined in the previous section is not used.</p>
|
||||
|
|
@ -254,6 +260,10 @@ Discussions-To: <<a href="https://github.com/zcash/zips/issues/482">https://g
|
|||
<li>“<code>uview</code>” for Unified Full Viewing Keys on Mainnet;</li>
|
||||
<li>“<code>uviewtest</code>” for Unified Full Viewing Keys on Testnet.</li>
|
||||
</ul>
|
||||
<section id="rationale-for-address-derivation"><h4><span class="section-heading">Rationale for address derivation</span><span class="section-anchor"> <a rel="bookmark" href="#rationale-for-address-derivation"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h4>
|
||||
<p>The design of address derivation is designed to maintain unlinkability between addresses derived from the same UIVK, to the extent possible. (This is only partially achieved if the UA contains a Transparent P2PKH Address, since the on-chain transaction graph can potentially be used to link transparent addresses.)</p>
|
||||
<p>Note that it may be difficult to retain this property for Metadata Items, and this should be taken into account in the design of such Items.</p>
|
||||
</section>
|
||||
</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>
|
||||
|
|
@ -275,9 +285,12 @@ Discussions-To: <<a href="https://github.com/zcash/zips/issues/482">https://g
|
|||
<li>Consumers MUST ignore constituent Addresses/Viewing Keys with Typecodes they do not recognize.</li>
|
||||
<li>Consumers 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>Consumers 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="id22" 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>Consumers MUST reject Unified Addresses/Viewing Keys in which the constituent Items are not ordered in ascending Typecode order. Note that this is different to priority order, and does not affect which Receiver in a Unified 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>
|
||||
</ul>
|
||||
<section id="rationale-for-item-ordering"><h4><span class="section-heading">Rationale for item ordering</span><span class="section-anchor"> <a rel="bookmark" href="#rationale-for-item-ordering"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h4>
|
||||
<p>The rationale for requiring Items to be canonically ordered by Typecode is that it enables implementations to use an in-memory representation that discards ordering, while retaining the same round-trip serialization of a UA/UIVK (provided that unrecognized items are retained).</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="adding-new-types"><h3><span class="section-heading">Adding new types</span><span class="section-anchor"> <a rel="bookmark" href="#adding-new-types"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>It is intended that new Receiver Types and Viewing Key Types SHOULD be introduced either by a modification to this ZIP or by a new ZIP, in accordance with the ZIP Process <a id="id23" class="footnote_reference" href="#zip-0000">10</a>.</p>
|
||||
|
|
@ -288,31 +301,48 @@ Discussions-To: <<a href="https://github.com/zcash/zips/issues/482">https://g
|
|||
inclusive. This provides for six simultaneous experiments, which can be referred to as experiments A to F. This should be sufficient because experiments are expected to be reasonably short-term, and should otherwise be either standardized in a ZIP (and allocated a Typecode outside this reserved range) or discontinued.</p>
|
||||
<p>New types SHOULD maintain the same distinction between FVK and IVK authority as existing types, i.e. an FVK is intended to give access to view all transactions to and from the address, while an IVK is intended to give access only to view incoming payments (as opposed to change).</p>
|
||||
</section>
|
||||
<section id="metadata-items"><h3><span class="section-heading">Metadata Items</span><span class="section-anchor"> <a rel="bookmark" href="#metadata-items"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>Typecodes
|
||||
<span class="math">\(\mathtt{0xE0}\)</span>
|
||||
to
|
||||
<span class="math">\(\mathtt{0xFC}\)</span>
|
||||
inclusive are reserved to indicate Metadata Items other than Receivers or Viewing Keys. These items MAY affect the overall interpretation of the UA / UVK (for example, by specifying an expiration date).</p>
|
||||
<p>Since Metadata Items are not Receivers, they MUST NOT be selected by a Sender when choosing a Receiver to send to, and since they are not Viewing Keys, they MUST NOT provide additional authority to view information about transactions.</p>
|
||||
<p>Currently no Metadata Types are defined. New Metadata Types SHOULD be introduced either by a modification to this ZIP or by a new ZIP, in accordance with the ZIP Process <a id="id24" class="footnote_reference" href="#zip-0000">10</a>.</p>
|
||||
</section>
|
||||
<section id="deriving-a-uivk-from-a-ufvk"><h3><span class="section-heading">Deriving a UIVK from a UFVK</span><span class="section-anchor"> <a rel="bookmark" href="#deriving-a-uivk-from-a-ufvk"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>The following derivations are applied to each component FVK:</p>
|
||||
<ul>
|
||||
<li>For a Sapling FVK, the corresponding Sapling IVK is obtained as specified in <a id="id24" class="footnote_reference" href="#protocol-saplingkeycomponents">4</a>.</li>
|
||||
<li>For an Orchard FVK, the corresponding Orchard IVK is obtained as specified in <a id="id25" class="footnote_reference" href="#protocol-orchardkeycomponents">5</a>.</li>
|
||||
<li>For a Sapling FVK, the corresponding Sapling IVK is obtained as specified in <a id="id25" class="footnote_reference" href="#protocol-saplingkeycomponents">4</a>.</li>
|
||||
<li>For an Orchard FVK, the corresponding Orchard IVK is obtained as specified in <a id="id26" class="footnote_reference" href="#protocol-orchardkeycomponents">5</a>.</li>
|
||||
<li>For a Transparent P2PKH FVK, the corresponding Transparent P2PKH IVK is obtained by deriving the child key with non-hardened index
|
||||
<span class="math">\(0\)</span>
|
||||
as described in <a id="id26" class="footnote_reference" href="#bip-0032-public-to-public">22</a>.</li>
|
||||
as described in <a id="id27" class="footnote_reference" href="#bip-0032-public-to-public">22</a>.</li>
|
||||
</ul>
|
||||
<p>In each case, the Typecode remains the same as in the FVK.</p>
|
||||
<p>Items (including Metadata Items) that are unrecognized by a given Consumer, or that are specified in experiments that the user has not opted into (see <a href="#experimental-usage">Experimental Usage</a>), MUST be dropped when deriving a UIVK from a UFVK.</p>
|
||||
</section>
|
||||
<section id="deriving-a-unified-address-from-a-uivk"><h3><span class="section-heading">Deriving a Unified Address from a UIVK</span><span class="section-anchor"> <a rel="bookmark" href="#deriving-a-unified-address-from-a-uivk"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>To derive a Unified Address from a UIVK we need to choose a diversifier index, which MUST be valid for all of the Viewing Key Types in the UIVK. That is,</p>
|
||||
<ul>
|
||||
<li>A Sapling diversifier index MUST generate a valid diversifier as defined in ZIP 32 section “Sapling diversifier derivation” <a id="id27" class="footnote_reference" href="#zip-0032-sapling-diversifier-derivation">13</a>.</li>
|
||||
<li>A Sapling diversifier index MUST generate a valid diversifier as defined in ZIP 32 section “Sapling diversifier derivation” <a id="id28" class="footnote_reference" href="#zip-0032-sapling-diversifier-derivation">13</a>.</li>
|
||||
<li>A Transparent diversifier index MUST be in the range
|
||||
<span class="math">\(0\)</span>
|
||||
to
|
||||
<span class="math">\(2^{31} - 1\)</span>
|
||||
inclusive.</li>
|
||||
<li>There are no additional constraints on an Orchard diversifier index.</li>
|
||||
</ul>
|
||||
<p>There are no additional constraints on an Orchard diversifier index.</p>
|
||||
<p>In the case of deriving a Transparent P2PKH Receiver from a Transparent P2PKH IVK, the diversifier index is used as a BIP 44 child key index at the Index level <a id="id28" class="footnote_reference" href="#bip-0044-path-index">24</a> to derive the address. As is usual for derivations below the BIP 44 Account level, non-hardened (public) derivation <a id="id29" class="footnote_reference" href="#bip-0032-public-to-public">22</a> MUST be used. The IVK is assumed to correspond to the extended public key for the non-change element of the path. That is, if the UIVK was constructed correctly then the BIP 44 path of the Transparent P2PKH Receiver will be
|
||||
<span class="math">\(m / 44' / \mathit{coin\_type\kern0.05em'} / \mathit{account\kern0.1em'} / 0 / \mathit{diversifier\_index}.\)</span>
|
||||
</p>
|
||||
<p>The following derivations are applied to each component IVK using the diversifier index:</p>
|
||||
<ul>
|
||||
<li>For a Sapling IVK, the corresponding Sapling Receiver is obtained as specified in <a id="id29" class="footnote_reference" href="#protocol-saplingkeycomponents">4</a>.</li>
|
||||
<li>For an Orchard IVK, the corresponding Orchard Receiver is obtained as specified in <a id="id30" class="footnote_reference" href="#protocol-orchardkeycomponents">5</a>.</li>
|
||||
<li>For a Transparent P2PKH IVK, the diversifier index is used as a BIP 44 child key index at the Index level <a id="id31" class="footnote_reference" href="#bip-0044-path-index">24</a> to derive the corresponding Transparant P2PKH Receiver. As is usual for derivations below the BIP 44 Account level, non-hardened (public) derivation <a id="id32" class="footnote_reference" href="#bip-0032-public-to-public">22</a> MUST be used. The IVK is assumed to correspond to the extended public key for the non-change element of the path. That is, if the UIVK was constructed correctly then the BIP 44 path of the Transparent P2PKH Receiver will be
|
||||
<span class="math">\(m / 44' / \mathit{coin\_type\kern0.05em'} / \mathit{account\kern0.1em'} / 0 / \mathit{diversifier\_index}.\)</span>
|
||||
</li>
|
||||
</ul>
|
||||
<p>In each case, the Typecode remains the same as in the IVK.</p>
|
||||
<p>Items (including Metadata Items) that are unrecognized by a given Consumer, or that are specified in experiments that the user has not opted into (see <a href="#experimental-usage">Experimental Usage</a>), MUST be dropped when deriving a Receiver from a UIVK.</p>
|
||||
</section>
|
||||
<section id="jumbling"><h3><span class="section-heading">Jumbling</span><span class="section-anchor"> <a rel="bookmark" href="#jumbling"><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>
|
||||
|
|
@ -468,7 +498,7 @@ c^{n+m}}{q}.\)</span>
|
|||
bytes; otherwise it applies
|
||||
<span class="math">\(\mathsf{F4Jumble}^{-1}.\)</span>
|
||||
It rejects any result that does not end in the expected 16-byte padding, before stripping these 16 bytes and parsing the result.</p>
|
||||
<p>(48 bytes is the minimum size of a valid UA, UFVK, or UIVK raw encoding plus 16 bytes of padding, corresponding to a single Sapling Incoming Viewing Key.
|
||||
<p>(48 bytes allows for the minimum size of a shielded UA, UFVK, or UIVK item encoding to be 32 bytes, taking into account 16 bytes of padding. Although there is currently no shielded item encoding that short, it is plausible that one might be added in future.
|
||||
<span class="math">\(\ell^\mathsf{MAX}_M\)</span>
|
||||
bytes is the largest input/output size supported by
|
||||
<span class="math">\(\mathsf{F4Jumble}.\)</span>
|
||||
|
|
|
|||
Loading…
Reference in New Issue