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

ZIP 320: Add Background and Analysis sections.

This commit is contained in:
Kris Nuttycombe 2024-01-13 09:16:14 -07:00
parent 9b97740f14
commit 2e103629a6
2 changed files with 275 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
zip-0320.html
View File

@ -14,44 +14,63 @@ Owners: Daira Emma Hopwood <daira@electriccoin.co>
Credits: Hanh
Status: Draft
Category: Standards / Wallet
Discussions-To: &lt;<a href="https://github.com/zcash/zips/issues/757">https://github.com/zcash/zips/issues/757</a>&gt;</pre>
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>
<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", "MUST NOT", "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 below are to be interpreted as follows:</p>
<dl>
<dt>Recipient</dt>
<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 (in which case it is normally also a Recipient) or a Viewing Key.</dd>
<dt>Consumer</dt>
<dd>A wallet or other software that can make use of an Address or Viewing Key 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. Senders are a subset of Consumers.</dd>
</dl>
</section>
<section id="abstract"><h2><span class="section-heading">Abstract</span><span class="section-anchor"> <a rel="bookmark" href="#abstract"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>This ZIP defines a new encoding for transparent Zcash addresses. Wallets must ensure that no shielded notes are spent in transactions that send to a transparent address encoded in the specified fashion.</p>
<p>This ZIP is presently in Draft status, and defines two alternate encodings</p>
<p>This ZIP is presently in Draft status, and defines two alternate encodings for consideration. Analysis of the benefits and drawbacks of each of the proposed alternatives is presented at the end of this document.</p>
</section>
<section id="background"><h2><span class="section-heading">Background</span><span class="section-anchor"> <a rel="bookmark" href="#background"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>In November of 2023, the Zcash community received notice from the Binance cryptocurrency exchange that Zcash was at risk of being delisted from the exchange unless the community could provide a mechanism by which Binance could refuse deposits from shielded addresses and return them to the depositor. This issue was raised and discussed at length in the Zcash Community forum <a id="footnote-reference-2" class="footnote_reference" href="#binance-delisting">2</a>.</p>
<p>In the course of that discussion thread, wallet developer and community member @hanh <a id="footnote-reference-3" class="footnote_reference" href="#hanh-profile">3</a> suggested a wallet-oriented approach <a id="footnote-reference-4" class="footnote_reference" href="#hanh-suggestion">4</a> that involved defining a new encoding for Zcash transparent P2PKH addresses. A Consumer of such an address, whether it be a wallet or an exchange, could recognize this encoding as a directive that the wallet should only spend transparent funds when creating an output to that address.</p>
</section>
<section id="motivation"><h2><span class="section-heading">Motivation</span><span class="section-anchor"> <a rel="bookmark" href="#motivation"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>The Binance cryptocurrency exchange requires that funds sent to their deposit addresses come from source addresses that are readily identifiable using on-chain information, such that if necessary funds may be rejected by sending them back to the source address(es). This ZIP is intended to standardize a transparent address encoding that is only usable by wallets that understand and will respect this constraint.</p>
<p>The Binance cryptocurrency exchange requires that funds sent to their deposit addresses come from source addresses that are readily identifiable using on-chain information, such that if necessary funds may be rejected by sending them back to the source address(es). This ZIP is intended to standardize a transparent address encoding that is not yet understood by preexisting Consumers, in order to prevent inadvertent shielded spends when sending to such addresses. Then, Consumers that upgrade to support the new encoding will do so with the understanding that they must respect the restrictions on sources of funds described in this ZIP.</p>
</section>
<section id="requirements"><h2><span class="section-heading">Requirements</span><span class="section-anchor"> <a rel="bookmark" href="#requirements"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<ol type="1">
<li>An entity wishing to receive funds from exclusively transparent sources must be able to generate a receiving address such that only transparent funds will be spent in transactions sent to this address.</li>
<li>Wallets that have not been upgraded to recognize the new address format cannot mistake the address for another address type or inadvertently send shielded funds the address.</li>
<li>No changes to recipient infrastructure beyond changes to address encoding and decoding should be required as a consequence of this ZIP.</li>
<li>A Recipient wishing to receive funds from exclusively transparent sources must be able to generate a receiving address such that only transparent funds will be spent in transactions with an output to this address.</li>
<li>Wallets and other Consumers that have not been upgraded to recognize the new address format cannot mistake the address for another address type or inadvertently send shielded funds to the address.</li>
<li>No changes to Recipient infrastructure beyond changes to address encoding and decoding should be required as a consequence of this ZIP.</li>
</ol>
</section>
<section id="specification-alternative-1"><h2><span class="section-heading">Specification (Alternative 1)</span><span class="section-anchor"> <a rel="bookmark" href="#specification-alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<section id="alternative-1"><h2><span class="section-heading">Alternative 1</span><span class="section-anchor"> <a rel="bookmark" href="#alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<p>This alternative was suggested by @hanh in <a id="footnote-reference-5" class="footnote_reference" href="#hanh-suggestion">4</a>.</p>
<section id="tex-addresses"><h3><span class="section-heading">TEX Addresses</span><span class="section-anchor"> <a rel="bookmark" href="#tex-addresses"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>A TEX Address is a <code>bech32m</code> reencoding of a transparent Zcash P2PKH address <a id="footnote-reference-2" class="footnote_reference" href="#protocol-taddr">5</a></p>
<p>A TEX Address is a <code>bech32m</code> reencoding of a transparent Zcash P2PKH address <a id="footnote-reference-6" class="footnote_reference" href="#protocol-transparentaddrencoding">8</a>.</p>
</section>
<section id="motivations-for-alternative-1"><h3><span class="section-heading">Motivations for Alternative 1</span><span class="section-anchor"> <a rel="bookmark" href="#motivations-for-alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>The TEX Address is the simplest-possible approach to creating a new address type that indicates that only transparent sources of funds should be used.</p>
<p>The TEX Address is the simplest possible approach to creating a new address type that indicates that only transparent sources of funds should be used.</p>
</section>
<section id="detailed-specification-alternative-1"><h3><span class="section-heading">Detailed Specification (Alternative 1)</span><span class="section-anchor"> <a rel="bookmark" href="#detailed-specification-alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>A TEX address may be produced from a mainnet Zcash P2PKH Address by executing the following steps:</p>
<section id="specification-alternative-1"><h3><span class="section-heading">Specification (Alternative 1)</span><span class="section-anchor"> <a rel="bookmark" href="#specification-alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>A TEX address is produced from a mainnet Zcash P2PKH Address by executing the following steps:</p>
<ol type="1">
<li>Decode the address to a byte array using the <code>base58check</code> decoding algorithm.</li>
<li>Remove the two-byte address prefix from the resulting byte array. These bytes should be equal to
<li>Decode the address to a byte array using the Base58Check decoding algorithm <a id="footnote-reference-7" class="footnote_reference" href="#base58check">10</a>.</li>
<li>If the length of the resulting byte sequence is not 22 bytes or if its two-byte address prefix is not
<span class="math">\(\mathtt{[0x1C, 0xB8]}\)</span>
. The remainder of the byte array (the <strong>validating key hash</strong>) should have a length of 20 bytes.</li>
<li>Reencode the 20-byte <strong>validating key hash</strong> using the <code>bech32m</code> encoding as defined in <a id="footnote-reference-3" class="footnote_reference" href="#bip-0350">6</a> with the human-readable prefix (HRP) <code>'tex'</code>.</li>
, return an error. Otherwise, let the <strong>validating key hash</strong> be the remaining 20 bytes of the array after removing the two-byte address prefix.</li>
<li>Reencode the 20-byte <strong>validating key hash</strong> using the Bech32m encoding defined in <a id="footnote-reference-8" class="footnote_reference" href="#bip-0350">12</a> with the human-readable prefix (HRP) <code>"tex"</code>.</li>
</ol>
<p>For testnet addresses, the lead bytes of a P2PKH address are
<p>For testnet addresses, the required lead bytes of a P2PKH address in step 2 are
<span class="math">\(\mathtt{[0x1C, 0xB8]}\)</span>
and the <code>'textest'</code> HRP should be used when reencoding.</p>
, and the <code>"textest"</code> HRP is used when reencoding in step 3.</p>
<p>Wallets and other Senders sending to a TEX address MUST ensure that only transparent UTXOs are spent in the creation of a transaction.</p>
</section>
<section id="reference-implementation-alternative-1"><h3><span class="section-heading">Reference Implementation (Alternative 1)</span><span class="section-anchor"> <a rel="bookmark" href="#reference-implementation-alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<!-- code-block: javascript
@ -59,7 +78,8 @@ import bs58check from 'bs58check'
import {bech32m} from 'bech32'
// From t1 to tex
var b58decoded = bs58check.decode('t1VmmGiyjVNeCjxDZzg7vZmd99WyzVby9yC')
console.assert(b58decoded[0] == 28 &amp;&amp; b58decoded[1] == 184, 'Invalid address prefix');
console.assert(len(b58decoded) == 22, 'Invalid length');
console.assert(b58decoded[0] == 0x1C &amp;&amp; b58decoded[1] == 0xB8, 'Invalid address prefix');
var pkh = b58decoded.slice(2)
var tex = bech32m.encode('tex', bech32m.toWords(pkh))
console.log(tex)
@ -67,23 +87,24 @@ console.log(tex)
var bech32decoded = bech32m.decode('tex1s2rt77ggv6q989lr49rkgzmh5slsksa9khdgte')
console.assert(bech32decoded.prefix == 'tex', 'Invalid address prefix')
var pkh2 = Uint8Array.from(bech32m.fromWords(bech32decoded.words))
var t1 = bs58check.encode(Buffer.concat([Uint8Array.from([28, 184]), pkh2]))
console.assert(len(pkh2) == 20, 'Invalid length');
var t1 = bs58check.encode(Buffer.concat([Uint8Array.from([0x1C, 0xB8]), pkh2]))
console.log(t1) -->
</section>
</section>
<section id="specification-alternative-2"><h2><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></h2>
<section id="alternative-2"><h2><span class="section-heading">Alternative 2</span><span class="section-anchor"> <a rel="bookmark" href="#alternative-2"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<section id="traceable-unified-addresses"><h3><span class="section-heading">Traceable Unified Addresses</span><span class="section-anchor"> <a rel="bookmark" href="#traceable-unified-addresses"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>A Traceable Unified Address is a reencoding of a transparent Zcash address into a Unified Address <a id="footnote-reference-4" class="footnote_reference" href="#zip-0316-unified-addresses">2</a>.</p>
<p>A Traceable Unified Address is a reencoding of a transparent Zcash address into a Unified Address <a id="footnote-reference-9" class="footnote_reference" href="#zip-0316-unified-addresses">5</a>.</p>
</section>
<section id="motivations-for-alternative-2"><h3><span class="section-heading">Motivations for Alternative 2</span><span class="section-anchor"> <a rel="bookmark" href="#motivations-for-alternative-2"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>Traceable Unified Addresses fit into the existing Zcash Unified Address ecosystem. As such, wallets that support Unified Addresses will be able to parse (but not necessarily send to) a Traceable Unified Address. Even in the case that Traceable Receivers are not understood by the sending wallet, a Unified Address-supporting wallet will be able to automatically provide good error messages for their users to indicate that the wallet needs to be updated to understand these addresses.</p>
<p>In addition, by integrating with the Unified Address framework, it becomes possible for the addresses being generated to include extra metadata, in particular, metadata items such as an Address Expiry Height or Address Expiry Date <a id="footnote-reference-5" class="footnote_reference" href="#zip-0316-address-expiry">4</a> may be included. For exchange use cases such as Binance's, it is useful to ensure that an address provided to a user has a limited utility life, such that after expiration the user must obtain a new address in order to be able to continue to send funds.</p>
<p>Traceable Unified Addresses fit into the existing Zcash Unified Address ecosystem. Existing Consumers that support Unified Addresses will automatically be able to recognize a Traceable Unified Address as a valid Zcash address, but will not be able to send to that address unless they update their code to understand the new Receiver Typecode defined in this ZIP. Even in the case that Traceable Receivers are not understood by the sending wallet, a Unified Address-supporting wallet will be able to automatically provide good error messages for their users to indicate that the wallet needs to be updated to understand and send to these addresses.</p>
<p>In addition, by integrating with the Unified Address framework, it becomes possible for the addresses being generated to include extra metadata, in particular, metadata items such as an Address Expiry Height or Address Expiry Date <a id="footnote-reference-10" class="footnote_reference" href="#zip-0316-address-expiry">7</a> may be included. For exchange use cases such as Binance's, it is useful to ensure that an address provided to a user has a limited utility life, such that after expiration the user must obtain a new address in order to be able to continue to send funds <a id="footnote-reference-11" class="footnote_reference" href="#binance-address-expiry">9</a>.</p>
</section>
<section id="detailed-specification-alternative-2"><h3><span class="section-heading">Detailed Specification (Alternative 2)</span><span class="section-anchor"> <a rel="bookmark" href="#detailed-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>Encoding of Unified Addresses</cite> of ZIP 316 <a id="footnote-reference-6" class="footnote_reference" href="#zip-0316-unified-addresses">2</a> will be modified to define a new Traceable Receiver Type having typecode
<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>Encoding of Unified Addresses</cite> of ZIP 316 <a id="footnote-reference-12" class="footnote_reference" href="#zip-0316-unified-addresses">5</a> will be modified to define a new Traceable Receiver Type having typecode
<span class="math">\(\mathtt{0x04}\)</span>
, the value of which must be the 20-byte <strong>validating key hash</strong> of a Zcash P2PKH Address as defined in <a id="footnote-reference-7" class="footnote_reference" href="#protocol-taddr">5</a>.</p>
<p>The "Requirements for both Unified Addresses and Unified Viewing Keys" section of ZIP 316 <a id="footnote-reference-8" class="footnote_reference" href="#zip-0316-unified-requirements">3</a> will be modified as follows:</p>
, the value of which MUST be the 20-byte <strong>validating key hash</strong> of a Zcash P2PKH Address as defined in <a id="footnote-reference-13" class="footnote_reference" href="#protocol-transparentaddrencoding">8</a>.</p>
<p>The "Requirements for both Unified Addresses and Unified Viewing Keys" section of ZIP 316 <a id="footnote-reference-14" class="footnote_reference" href="#zip-0316-unified-requirements">6</a> will be modified as follows — the text:</p>
<pre>A Unified Address or Unified Viewing Key MUST contain at least one
shielded Item (Typecodes :math:`\mathtt{0x02}` and :math:`\mathtt{0x03}`).
The rationale is that the existing P2SH and P2PKH transparent-only
@ -91,7 +112,7 @@ address formats, and the existing P2PKH extended public key format,
suffice for representing transparent Items and are already supported
by the existing ecosystem.</pre>
<p>will be replaced by:</p>
<pre>A Unified Address MUST contain at least one Receiver, plus any number
<pre>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 **either** contain at least one shielded
Receiver (Typecodes :math:`\mathtt{0x02}` and :math:`\mathtt{0x03}`), OR
@ -102,20 +123,24 @@ A Unified Viewing Key MUST contain at least one shielded Item (Typecodes
:math:`\mathtt{0x02}` and :math:`\mathtt{0x03}`).</pre>
<p>A Traceable Unified Address is produced from a mainnet Zcash P2PKH address by executing the following steps:</p>
<ol type="1">
<li>Decode the address to a byte array using the <code>base58check</code> decoding algorithm.</li>
<li>Remove the two-byte address prefix from the resulting byte array. These bytes should be equal to
<li>Decode the address to a byte array using the Base58Check decoding algorithm <a id="footnote-reference-15" class="footnote_reference" href="#base58check">10</a>.</li>
<li>If the length of the resulting byte sequence is not 22 bytes or if its two-byte address prefix is not
<span class="math">\(\mathtt{[0x1C, 0xB8]}\)</span>
. The remainder of the byte array (the <strong>validating key hash</strong>) should have a length of 20 bytes.</li>
, return an error. Otherwise, let the <strong>validating key hash</strong> be the remaining 20 bytes of the array after removing the two-byte address prefix.</li>
<li>Construct a new Unified Address using a single Traceable Receiver
<span class="math">\(\mathtt{0x04}\)</span>
with the 20-byte <strong>validating_key_hash</strong> as its value. In addition, metadata items such as an Address Expiry Height or Address Expiry Date <a id="footnote-reference-9" class="footnote_reference" href="#zip-0316-address-expiry">4</a> may be included.</li>
with the 20-byte <strong>validating_key_hash</strong> as its value. In addition, metadata items such as an Address Expiry Height or Address Expiry Date <a id="footnote-reference-16" class="footnote_reference" href="#zip-0316-address-expiry">7</a> MAY be included.</li>
</ol>
<p>Wallets and other Senders sending to a Traceable Unified Address MUST ensure that only transparent UTXOs are spent in the creation of a transaction.</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 library <cite>zcash_address_wasm</cite>:</p>
<!-- code-block: javascript
import { to_traceable_address } from 'zcash_address_wasm'
var traceable_addr = to_traceable_address('t1VmmGiyjVNeCjxDZzg7vZmd99WyzVby9yC', Date.now()) -->
// Create a deposit address that is valid for 30 days
var expiry_time = new Date();
expiry_time.setDate(expiry_time.getDate() + 30);
var traceable_addr = to_traceable_address('t1VmmGiyjVNeCjxDZzg7vZmd99WyzVby9yC', expiry_time.getTime() / 1000) -->
<p>Rust:</p>
<!-- code-block: rust
use zcash_address::{
@ -151,6 +176,33 @@ impl TryFromAddress for TraceableReceiver {
Ok(TraceableReceiver { net, data })
}
} -->
</section>
</section>
<section id="analysis-of-alternative-1"><h2><span class="section-heading">Analysis of Alternative 1</span><span class="section-anchor"> <a rel="bookmark" href="#analysis-of-alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<section id="pros-to-alternative-1"><h3><span class="section-heading">Pros to Alternative 1</span><span class="section-anchor"> <a rel="bookmark" href="#pros-to-alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<ul>
<li>The reencoding from Zcash P2PKH addresses is extremely straightforward and relies only upon widely available encoding libraries.</li>
</ul>
</section>
<section id="cons-to-alternative-1"><h3><span class="section-heading">Cons to Alternative 1</span><span class="section-anchor"> <a rel="bookmark" href="#cons-to-alternative-1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<ul>
<li>Creation of a new fully-distinct address type further fragments the Zcash address ecosystem. Avoiding such fragmentation and providing smooth upgrade paths and good error messages to users is exactly the problem that Unifed Addresses <a id="footnote-reference-17" class="footnote_reference" href="#zip-0316-unified-addresses">5</a> were intended to avoid.</li>
<li>The TEX address type does not provide any mechanism for address expiration. One of the questions Binance has asked has been what to do about users who have stored their existing transparent deposit address in their wallets, or as a withdrawal address for other exchanges or services. This is a challenging problem to mitigate now because address expiration was not previously implemented. We should not further compound this problem by defining a new distinct address type that does not provide a mechanism for address expiry.</li>
</ul>
</section>
</section>
<section id="analysis-of-alternative-2"><h2><span class="section-heading">Analysis of Alternative 2</span><span class="section-anchor"> <a rel="bookmark" href="#analysis-of-alternative-2"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>
<section id="pros-to-alternative-2"><h3><span class="section-heading">Pros To Alternative 2</span><span class="section-anchor"> <a rel="bookmark" href="#pros-to-alternative-2"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<ul>
<li>By integrating with the Unified Address framework, Consumers of Traceable 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 receiver typecode.</li>
<li>It is possible to include address expiration metadata in a Traceable Address, which can help to mitigate problems related to stored addresses in the future.</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.</li>
</ul>
</section>
<section id="cons-to-alternative-2"><h3><span class="section-heading">Cons to Alternative 2</span><span class="section-anchor"> <a rel="bookmark" href="#cons-to-alternative-2"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<ul>
<li>Unified Address encoding is slightly more complex than the proposed TEX address encoding, and requires use of the F4Jumble encoding algorithm <a id="footnote-reference-18" class="footnote_reference" href="#f4jumble">11</a>. However, this can be readily mitigated by providing a purpose-built library for Traceable Address encoding to Producers.</li>
</ul>
<table id="bcp14" class="footnote">
<tbody>
<tr>
@ -159,10 +211,34 @@ impl TryFromAddress for TraceableReceiver {
</tr>
</tbody>
</table>
<table id="zip-0316-unified-addresses" class="footnote">
<table id="binance-delisting" class="footnote">
<tbody>
<tr>
<th>2</th>
<td><a href="https://forum.zcashcommunity.com/t/important-potential-binance-delisting/45954">Zcash Community Forum thread "Important: Potential Binance Delisting"</a></td>
</tr>
</tbody>
</table>
<table id="hanh-profile" class="footnote">
<tbody>
<tr>
<th>3</th>
<td>'Zcash Community Forum user @hanh &lt;<a href="https://forum.zcashcommunity.com/u/hanh/summary">https://forum.zcashcommunity.com/u/hanh/summary</a>&gt;'_</td>
</tr>
</tbody>
</table>
<table id="hanh-suggestion" class="footnote">
<tbody>
<tr>
<th>4</th>
<td>'Ywallet developer @hanh's proposal &lt;<a href="https://forum.zcashcommunity.com/t/important-potential-binance-delisting/45954/112">https://forum.zcashcommunity.com/t/important-potential-binance-delisting/45954/112</a>&gt;'_</td>
</tr>
</tbody>
</table>
<table id="zip-0316-unified-addresses" class="footnote">
<tbody>
<tr>
<th>5</th>
<td><a href="zip-0316#encoding-of-unified-addresses">ZIP 316: Unified Addresses</a></td>
</tr>
</tbody>
@ -170,7 +246,7 @@ impl TryFromAddress for TraceableReceiver {
<table id="zip-0316-unified-requirements" class="footnote">
<tbody>
<tr>
<th>3</th>
<th>6</th>
<td><a href="zip-0316#requirements-for-both-unified-addresses-and-unified-viewing-keys">ZIP 316: Requirements for both Unified Addresses and Unified Viewing Keys</a></td>
</tr>
</tbody>
@ -178,23 +254,47 @@ impl TryFromAddress for TraceableReceiver {
<table id="zip-0316-address-expiry" class="footnote">
<tbody>
<tr>
<th>4</th>
<th>7</th>
<td><a href="zip-0316#address-expiration-metadata">ZIP 316:</a></td>
</tr>
</tbody>
</table>
<table id="protocol-taddr" class="footnote">
<table id="protocol-transparentaddrencoding" class="footnote">
<tbody>
<tr>
<th>5</th>
<th>8</th>
<td><a href="protocol/protocol.pdf#transparentaddrencoding">Zcash Protocol Specification, Version 2023.4.0. Section 5.6.1.1 Transparent Addresses</a></td>
</tr>
</tbody>
</table>
<table id="binance-address-expiry" class="footnote">
<tbody>
<tr>
<th>9</th>
<td><a href="https://forum.zcashcommunity.com/t/unified-address-expiration/46564/6">Zcash Community Forum post describing motivations for address expiry</a></td>
</tr>
</tbody>
</table>
<table id="base58check" class="footnote">
<tbody>
<tr>
<th>10</th>
<td><a href="https://en.bitcoin.it/wiki/Base58Check_encoding">Base58Check encoding — Bitcoin Wiki</a></td>
</tr>
</tbody>
</table>
<table id="f4jumble" class="footnote">
<tbody>
<tr>
<th>11</th>
<td><a href="zip-0316#jumbling">ZIP 316: F4Jumble encoding</a></td>
</tr>
</tbody>
</table>
<table id="bip-0350" class="footnote">
<tbody>
<tr>
<th>6</th>
<th>12</th>
<td><a href="https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki">BIP 350: Bech32m format for v1+ witness addresses</a></td>
</tr>
</tbody>

173
zip-0320.rst
View File

@ -21,6 +21,20 @@ appear in all capitals.
The terms below are to be interpreted as follows:
Recipient
A wallet or other software that can receive transfers of assets (such
as ZEC) or in the future potentially other transaction-based state changes.
Producer
A wallet or other software that can create an Address (in which case it is
normally also a Recipient) or a Viewing Key.
Consumer
A wallet or other software that can make use of an Address or Viewing Key
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. Senders are a subset of
Consumers.
Abstract
========
@ -28,8 +42,26 @@ This ZIP defines a new encoding for transparent Zcash addresses. Wallets must
ensure that no shielded notes are spent in transactions that send to a
transparent address encoded in the specified fashion.
This ZIP is presently in Draft status, and defines two alternate encodings
for consideration.
This ZIP is presently in Draft status, and defines two alternate encodings for
consideration. Analysis of the benefits and drawbacks of each of the proposed
alternatives is presented at the end of this document.
Background
==========
In November of 2023, the Zcash community received notice from the Binance
cryptocurrency exchange that Zcash was at risk of being delisted from the
exchange unless the community could provide a mechanism by which Binance could
refuse deposits from shielded addresses and return them to the depositor. This
issue was raised and discussed at length in the Zcash Community forum
[#binance-delisting]_.
In the course of that discussion thread, wallet developer and community member
@hanh [#hanh-profile]_ suggested a wallet-oriented approach [#hanh-suggestion]_
that involved defining a new encoding for Zcash transparent P2PKH addresses. A
Consumer of such an address, whether it be a wallet or an exchange, could
recognize this encoding as a directive that the wallet should only spend
transparent funds when creating an output to that address.
Motivation
==========
@ -37,24 +69,29 @@ Motivation
The Binance cryptocurrency exchange requires that funds sent to their deposit
addresses come from source addresses that are readily identifiable using
on-chain information, such that if necessary funds may be rejected by sending
them back to the source address(es). This ZIP is intended to standardize
a transparent address encoding that is only usable by wallets that understand
and will respect this constraint.
them back to the source address(es). This ZIP is intended to standardize a
transparent address encoding that is not yet understood by preexisting
Consumers, in order to prevent inadvertent shielded spends when sending to such
addresses. Then, Consumers that upgrade to support the new encoding will do so
with the understanding that they must respect the restrictions on sources of
funds described in this ZIP.
Requirements
============
1. An entity wishing to receive funds from exclusively transparent sources
1. A Recipient wishing to receive funds from exclusively transparent sources
must be able to generate a receiving address such that only transparent
funds will be spent in transactions with an output to this address.
2. Wallets that have not been upgraded to recognize the new address format
cannot mistake the address for another address type or inadvertently
send shielded funds to the address.
3. No changes to recipient infrastructure beyond changes to address encoding
2. Wallets and other Consumers that have not been upgraded to recognize the new
address format cannot mistake the address for another address type or
inadvertently send shielded funds to the address.
3. No changes to Recipient infrastructure beyond changes to address encoding
and decoding should be required as a consequence of this ZIP.
Specification (Alternative 1)
=============================
Alternative 1
=============
This alternative was suggested by @hanh in [#hanh-suggestion]_.
TEX Addresses
-------------
@ -68,8 +105,8 @@ Motivations for Alternative 1
The TEX Address is the simplest possible approach to creating a new address
type that indicates that only transparent sources of funds should be used.
Detailed Specification (Alternative 1)
--------------------------------------
Specification (Alternative 1)
-----------------------------
A TEX address is produced from a mainnet Zcash P2PKH Address by executing the
following steps:
@ -87,8 +124,8 @@ For testnet addresses, the required lead bytes of a P2PKH address in step 2
are :math:`\mathtt{[0x1C, 0xB8]}`, and the ``"textest"`` HRP is used when
reencoding in step 3.
Wallets sending to a TEX address MUST ensure that only transparent UTXOs are
spent in the creation of a transaction.
Wallets and other Senders sending to a TEX address MUST ensure that only
transparent UTXOs are spent in the creation of a transaction.
Reference Implementation (Alternative 1)
----------------------------------------
@ -114,8 +151,8 @@ Reference Implementation (Alternative 1)
var t1 = bs58check.encode(Buffer.concat([Uint8Array.from([0x1C, 0xB8]), pkh2]))
console.log(t1)
Specification (Alternative 2)
=============================
Alternative 2
=============
Traceable Unified Addresses
---------------------------
@ -127,12 +164,14 @@ Motivations for Alternative 2
-----------------------------
Traceable Unified Addresses fit into the existing Zcash Unified Address
ecosystem. As such, wallets that support Unified Addresses will be able to
parse (but not necessarily send to) a Traceable Unified Address. Even in the
case that Traceable Receivers are not understood by the sending wallet, a
Unified Address-supporting wallet will be able to automatically provide good
error messages for their users to indicate that the wallet needs to be updated
to understand these addresses.
ecosystem. Existing Consumers that support Unified Addresses will automatically
be able to recognize a Traceable Unified Address as a valid Zcash address, but
will not be able to send to that address unless they update their code to
understand the new Receiver Typecode defined in this ZIP. Even in the case that
Traceable Receivers are not understood by the sending wallet, a Unified
Address-supporting wallet will be able to automatically provide good error
messages for their users to indicate that the wallet needs to be updated to
understand and send to these addresses.
In addition, by integrating with the Unified Address framework, it becomes
possible for the addresses being generated to include extra metadata, in
@ -140,10 +179,11 @@ particular, metadata items such as an Address Expiry Height or Address Expiry
Date [#zip-0316-address-expiry]_ may be included. For exchange use cases such
as Binance's, it is useful to ensure that an address provided to a user has a
limited utility life, such that after expiration the user must obtain a new
address in order to be able to continue to send funds.
address in order to be able to continue to send funds
[#binance-address-expiry]_.
Detailed Specification (Alternative 2)
--------------------------------------
Specification (Alternative 2)
-----------------------------
Upon activation of this ZIP, the section `Encoding of Unified Addresses` of ZIP
316 [#zip-0316-unified-addresses]_ will be modified to define a new
@ -177,18 +217,19 @@ will be replaced by::
A Traceable Unified Address is produced from a mainnet Zcash P2PKH address by
executing the following steps:
1. Decode the address to a byte array using the Base58Check decoding
algorithm [#Base58Check]_.
2. Remove the two-byte address prefix from the resulting byte array. These
bytes should be equal to :math:`\mathtt{[0x1C, 0xB8]}`. The remainder of the
byte array (the **validating key hash**) should have a length of 20 bytes.
1. Decode the address to a byte array using the Base58Check decoding algorithm
[#Base58Check]_.
2. If the length of the resulting byte sequence is not 22 bytes or if its
two-byte address prefix is not :math:`\mathtt{[0x1C, 0xB8]}`, return an
error. Otherwise, let the **validating key hash** be the remaining 20 bytes
of the array after removing the two-byte address prefix.
3. Construct a new Unified Address using a single Traceable Receiver
:math:`\mathtt{0x04}` with the 20-byte **validating_key_hash** as
its value. In addition, metadata items such as an Address Expiry Height
or Address Expiry Date [#zip-0316-address-expiry]_ MAY be included.
:math:`\mathtt{0x04}` with the 20-byte **validating_key_hash** as its value.
In addition, metadata items such as an Address Expiry Height or Address
Expiry Date [#zip-0316-address-expiry]_ MAY be included.
Wallets sending to a Traceable Unified Address MUST ensure that only
transparent UTXOs are spent in the creation of a transaction.
Wallets and other Senders sending to a Traceable Unified Address MUST ensure
that only transparent UTXOs are spent in the creation of a transaction.
Reference Implementation (Alternative 2)
----------------------------------------
@ -246,10 +287,68 @@ Rust:
}
}
Analysis of Alternative 1
=========================
Pros to Alternative 1
---------------------
- The reencoding from Zcash P2PKH addresses is extremely straightforward and
relies only upon widely available encoding libraries.
Cons to Alternative 1
---------------------
- Creation of a new fully-distinct address type further fragments the Zcash
address ecosystem. Avoiding such fragmentation and providing smooth upgrade
paths and good error messages to users is exactly the problem that Unifed
Addresses [#zip-0316-unified-addresses]_ were intended to avoid.
- The TEX address type does not provide any mechanism for address expiration.
One of the questions Binance has asked has been what to do about users who
have stored their existing transparent deposit address in their wallets, or
as a withdrawal address for other exchanges or services. This is a
challenging problem to mitigate now because address expiration was not
previously implemented. We should not further compound this problem by
defining a new distinct address type that does not provide a mechanism for
address expiry.
Analysis of Alternative 2
=========================
Pros To Alternative 2
---------------------
- By integrating with the Unified Address framework, Consumers of Traceable
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 receiver typecode.
- It is possible to include address expiration metadata in a Traceable Address,
which can help to mitigate problems related to stored addresses in the
future.
- 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.
Cons to Alternative 2
---------------------
- Unified Address encoding is slightly more complex than the proposed TEX address
encoding, and requires use of the F4Jumble encoding algorithm [#F4Jumble]_.
However, this can be readily mitigated by providing a purpose-built library for
Traceable Address encoding to Producers.
.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" <https://www.rfc-editor.org/info/bcp14>`_
.. [#binance-delisting] `Zcash Community Forum thread "Important: Potential Binance Delisting" <https://forum.zcashcommunity.com/t/important-potential-binance-delisting/45954>`_
.. [#hanh-profile] 'Zcash Community Forum user @hanh <https://forum.zcashcommunity.com/u/hanh/summary>'_
.. [#hanh-suggestion] 'Ywallet developer @hanh's proposal <https://forum.zcashcommunity.com/t/important-potential-binance-delisting/45954/112>'_
.. [#zip-0316-unified-addresses] `ZIP 316: Unified Addresses <zip-0316#encoding-of-unified-addresses>`_
.. [#zip-0316-unified-requirements] `ZIP 316: Requirements for both Unified Addresses and Unified Viewing Keys <zip-0316#requirements-for-both-unified-addresses-and-unified-viewing-keys>`_
.. [#zip-0316-address-expiry] `ZIP 316: <zip-0316#address-expiration-metadata>`_
.. [#protocol-transparentaddrencoding] `Zcash Protocol Specification, Version 2023.4.0. Section 5.6.1.1 Transparent Addresses <protocol/protocol.pdf#transparentaddrencoding>`_
.. [#binance-address-expiry] `Zcash Community Forum post describing motivations for address expiry <https://forum.zcashcommunity.com/t/unified-address-expiration/46564/6>`_
.. [#Base58Check] `Base58Check encoding — Bitcoin Wiki <https://en.bitcoin.it/wiki/Base58Check_encoding>`_
.. [#F4Jumble] `ZIP 316: F4Jumble encoding <zip-0316#jumbling>`_
.. [#bip-0350] `BIP 350: Bech32m format for v1+ witness addresses <https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki>`_