diff --git a/zip-0320.html b/zip-0320.html index 6087999b..ac846081 100644 --- a/zip-0320.html +++ b/zip-0320.html @@ -3,6 +3,7 @@ ZIP 320: Defining an Address Type to which funds can only be sent from Transparent Addresses +
@@ -11,9 +12,195 @@ Title: Defining an Address Type to which funds can only be sent from Transparent Owners: Daira Emma Hopwood <daira@electriccoin.co> Kris Nuttycombe <kris@nutty.land> Credits: Hanh -Status: Reserved +Status: Draft Category: Standards / Wallet Discussions-To: <https://github.com/zcash/zips/issues/757> +

Terminology

+

The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be interpreted as described in BCP 14 1 when, and only when, they appear in all capitals.

+

The terms below are to be interpreted as follows:

+
+

Abstract

+

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

+
+

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.

+
+

Requirements

+
    +
  1. 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.
    2. +
  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 the address.
    3. +
  3. No changes to recipient infrastructure beyond changes to address encoding and decoding should be required as a consequence of this ZIP.
    4. +
+
+

Specification (Alternative 1)

+

TEX Addresses

+

A TEX Address is a bech32m reencoding of a transparent Zcash P2PKH address 5

+
+

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)

+

A TEX address may be 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.
    2. +
  2. Remove the two-byte address prefix from the resulting byte array. These bytes should be equal to + \(\mathtt{[0x1C, 0xB8]}\) + . The remainder of the byte array (the validating key hash) should have a length of 20 bytes.
    3. +
  3. Reencode the 20-byte validating key hash using the bech32m encoding as defined in 6 with the human-readable prefix (HRP) 'tex'.
    4. +
+

For testnet addresses, the lead bytes of a P2PKH address are + \(\mathtt{[0x1C, 0xB8]}\) + and the 'textest' HRP should be used when reencoding.

+
+

Reference Implementation (Alternative 1)

+ +
+
+

Specification (Alternative 2)

+

Traceable Unified Addresses

+

A Traceable Unified Address is a reencoding of a transparent Zcash address into a Unified Address 2.

+
+

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.

+

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 4 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.

+
+

Detailed Specification (Alternative 2)

+

Upon activation of this ZIP, the section Encoding of Unified Addresses of ZIP 316 2 will be modified to define a new Traceable Receiver Type having typecode + \(\mathtt{0x04}\) + , the value of which must be the 20-byte validating key hash of a Zcash P2PKH Address as defined in 5.

+

The "Requirements for both Unified Addresses and Unified Viewing Keys" section of ZIP 316 3 will be modified as follows:

+ 
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
+address formats, and the existing P2PKH extended public key format,
+suffice for representing transparent Items and are already supported
+by the existing ecosystem.
+

will be replaced by:

+ 
A Unified Address MUST contain at least one Receiver, plus 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
+MUST contain **only** a Traceable Address Receiver (Typecode
+:math:`\mathtt{0x04}`).
+
+A Unified Viewing Key MUST contain at least one shielded Item (Typecodes
+:math:`\mathtt{0x02}` and :math:`\mathtt{0x03}`).
+

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.
    2. +
  2. Remove the two-byte address prefix from the resulting byte array. These bytes should be equal to + \(\mathtt{[0x1C, 0xB8]}\) + . The remainder of the byte array (the validating key hash) should have a length of 20 bytes.
    3. +
  3. Construct a new Unified Address using a single Traceable Receiver + \(\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 4 may be included.
    4. +
+
+

Reference Implementation (Alternative 2)

+

Javascript library zcash_address_wasm:

+ +

Rust:

+ + + + + + + + +
1Information 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"
+ + + + + + + +
2ZIP 316: Unified Addresses
+ + + + + + + +
3ZIP 316: Requirements for both Unified Addresses and Unified Viewing Keys
+ + + + + + + +
4ZIP 316:
+ + + + + + + +
5Zcash Protocol Specification, Version 2023.4.0. Section 5.6.1.1 Transparent Addresses
+ + + + + + + +
6BIP 350: Bech32m format for v1+ witness addresses
+
+
\ No newline at end of file diff --git a/zip-0320.rst b/zip-0320.rst index 7d8df012..6d5a8121 100644 --- a/zip-0320.rst +++ b/zip-0320.rst @@ -5,7 +5,242 @@ Owners: Daira Emma Hopwood Kris Nuttycombe Credits: Hanh - Status: Reserved + Status: Draft Category: Standards / Wallet Discussions-To: +Terminology +=========== + +The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are +to be interpreted as described in BCP 14 [#BCP14]_ when, and only when, they +appear in all capitals. + +The terms below are to be interpreted as follows: + +Abstract +======== + +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 + +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. + +Requirements +============ + +1. 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. +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 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) +============================= + +TEX Addresses +------------- + +A TEX Address is a ``bech32m`` reencoding of a transparent Zcash P2PKH address +[#protocol-taddr]_ + +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) +-------------------------------------- + +A TEX address may be 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. +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. +3. Reencode the 20-byte **validating key hash** using the ``bech32m`` encoding + as defined in [#bip-0350]_ with the human-readable prefix (HRP) ``'tex'``. + +For testnet addresses, the lead bytes of a P2PKH address are +:math:`\mathtt{[0x1C, 0xB8]}` and the ``'textest'`` HRP should be used when +reencoding. + +Wallets sending to a TEX address MUST ensure that only transparent UTXOs are +spent in the creation of a transaction. + +Reference Implementation (Alternative 1) +---------------------------------------- + +.. code-block: javascript + + import bs58check from 'bs58check' + import {bech32m} from 'bech32' + + // From t1 to tex + var b58decoded = bs58check.decode('t1VmmGiyjVNeCjxDZzg7vZmd99WyzVby9yC') + console.assert(b58decoded[0] == 28 && b58decoded[1] == 184, 'Invalid address prefix'); + var pkh = b58decoded.slice(2) + var tex = bech32m.encode('tex', bech32m.toWords(pkh)) + console.log(tex) + + // From tex to t1 + 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.log(t1) + +Specification (Alternative 2) +============================= + +Traceable Unified Addresses +--------------------------- + +A Traceable Unified Address is a reencoding of a transparent Zcash address into +a Unified Address [#zip-0316-unified-addresses]_. + +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. + +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 [#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. + +Detailed 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 +Traceable Receiver Type having typecode :math:`\mathtt{0x04}`, the value of +which MUST be the 20-byte **validating key hash** of a Zcash P2PKH Address as +defined in [#protocol-taddr]_. + +The "Requirements for both Unified Addresses and Unified Viewing Keys" section +of ZIP 316 [#zip-0316-unified-requirements]_ will be modified as follows:: + + 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 + address formats, and the existing P2PKH extended public key format, + suffice for representing transparent Items and are already supported + by the existing ecosystem. + +will be replaced by:: + + A Unified Address MUST contain at least one Receiver, plus 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 + MUST contain **only** a Traceable Address Receiver (Typecode + :math:`\mathtt{0x04}`). + + A Unified Viewing Key MUST contain at least one shielded Item (Typecodes + :math:`\mathtt{0x02}` and :math:`\mathtt{0x03}`). + +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. +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. +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. + +Wallets sending to a Traceable Unified Address MUST ensure that only +transparent UTXOs are spent in the creation of a transaction. + +Reference Implementation (Alternative 2) +---------------------------------------- + +Javascript library `zcash_address_wasm`: + +.. code-block: javascript + import { to_traceable_address } from 'zcash_address_wasm' + + // 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) + +Rust: + +.. code-block: rust + use zcash_address::{ + unified::{self, Encoding}, + Network, ToAddress, TryFromAddress, ZcashAddress, + }; + + struct TraceableReceiver { + net: Network, + data: [u8; 20], + } + + impl TraceableReceiver { + fn to_address(&self, expiry_time: u64) -> ZcashAddress { + let traceable_addr = unified::Address::try_from_items(vec![ + unified::Receiver::Unknown { + typecode: 0x04, + data: self.data.to_vec(), + }, + unified::Receiver::Unknown { + typecode: 0xE0, + data: expiry_time.to_le_bytes().to_vec(), + }, + ]) + .expect("We know that this produces a valid address."); + + ZcashAddress::from_unified(self.net, traceable_addr) + } + } + + impl TryFromAddress for TraceableReceiver { + type Error = unified::ParseError; + + fn try_from_transparent_p2pkh( + net: Network, + data: [u8; 20], + ) -> Result> { + Ok(TraceableReceiver { net, data }) + } + } + +.. [#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" `_ +.. [#zip-0316-unified-addresses] `ZIP 316: Unified Addresses `_ +.. [#zip-0316-unified-requirements] `ZIP 316: Requirements for both Unified Addresses and Unified Viewing Keys `_ +.. [#zip-0316-address-expiry] `ZIP 316: `_ +.. [#protocol-taddr] `Zcash Protocol Specification, Version 2023.4.0. Section 5.6.1.1 Transparent Addresses `_ +.. [#bip-0350] `BIP 350: Bech32m format for v1+ witness addresses `_