Unified Addresses and Unified Viewing Keys

Preamble

ZIP

316

Title

Unified Addresses and Unified Viewing Keys

Owners

• Daira-Emma Hopwood
• Nathan Wilcox
• Jack Grigg
• Sean Bowe
• Kris Nuttycombe

Original-Authors

• Greg Pfeil
• Ying Tong Lai

Credits

• Taylor Hornby
• Stephen Smith

Status

[Revision 0] Active, [Revision 1] Withdrawn, [Revision 2] Draft

Category

Standards / RPC / Wallet

Created

2021-04-07

License

MIT

Discussions-To

https://github.com/zcash/zips/issues/482

Terminology

The key words "MUST", "MUST NOT", "SHOULD", "RECOMMENDED", and "MAY" in this document are to be interpreted as described in BCP 14¹ when, and only when, they 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 side effects to consensus state that may be defined in future. Senders are a subset of Consumers.

Receiver

The necessary information to transfer an asset to a Recipient that generated that Receiver using a specific Transfer Protocol. Each Receiver is associated unambiguously with a specific Receiver Type, identified by an integer Typecode.

Receiver Encoding

An encoding of a Receiver as a byte sequence.

Viewing Key

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.

Viewing Key Encoding

An encoding of a Viewing Key as a byte sequence.

Metadata Encoding

An encoding of metadata that is not a Receiver or Viewing Key, but may affect the interpretation of the overall Unified Address/Viewing Key.

Item

An Receiver Encoding, Viewing Key Encoding, or Metadata Encoding.

Legacy Address

A Transparent, Sprout, or Sapling Address.

Unified Address (or UA)

A Unified Address combines multiple Receiver (and optionally Metadata) Items.

Unified Full Viewing Key (or UFVK)

A Unified Full Viewing Key combines multiple Full Viewing Key (and optionally Metadata) Items.

Unified Incoming Viewing Key (or UIVK)

A Unified Incoming Viewing Key combines multiple Incoming Viewing Key (and optionally Metadata) Items.

Unified Viewing Key (or UVK)

Either a Unified Full Viewing Key or a Unified Incoming Viewing Key.

Address

Either a Legacy Address or a Unified Address.

Transfer Protocol

A specification of how a Sender can transfer assets to a Recipient. For example, the Transfer Protocol for a Sapling Receiver is the subset of the Zcash protocol required to successfully transfer ZEC using Sapling Spend/Output Transfers as specified in the Zcash Protocol Specification. (A single Zcash transaction can contain transfers of multiple Transfer Protocols. For example a t→z transaction that shields to the Sapling pool requires both Transparent and Sapling Transfer Protocols.)

Unified String Encoding

An encoding of a UA/UVK as a US-ASCII string, intended either for display and transfer by Zcash end-users, or internal use by Zcash-related software.

Unified QR Encoding

An encoding of a UA/UVK as a QR code, intended for display and transfer by Zcash end-users in situations where usability advantages of a 2D bar code may be relevant.

Address Encoding

The externally visible encoding of an Address (e.g. as a string of characters or a QR code).

Unix Epoch Time

An integer representing a UTC time in seconds relative to the Unix Epoch of 1970-01-01T00:00:00Z.

Notation for sequences, conversions, and arithmetic operations follows the Zcash protocol specification².

Abstract

This proposal defines Unified Addresses, which bundle together Zcash Addresses of different types in a way that can be presented as a single Address Encoding. It also defines Unified Viewing Keys, which perform a similar function for Zcash viewing keys.

Motivation

Up to and including the Canopy network upgrade, Zcash supported the following Payment Address types:

• Transparent Addresses (P2PKH and P2SH)
• Sprout Addresses
• Sapling Addresses

Each of these has its own Address Encodings, as a string and as a QR code. (Since the QR code is derivable from the string encoding as described in ³, for many purposes it suffices to consider the string encoding.)

The Orchard proposal⁴ adds a new Address type, Orchard Addresses.

The difficulty with defining new Address Encodings for each Address type, is that end-users are forced to be aware of the various types, and in particular which types are supported by a given Consumer or Recipient. In order to make sure that transfers are completed successfully, users may be forced to explicitly generate Addresses of different types and re-distribute encodings of them, which adds significant friction and cognitive overhead to understanding and using Zcash.

The goals for a Unified Address standard are as follows:

• Simplify coordination between Recipients and Consumers by removing complexity from negotiating Address types.
• Provide a “bridging mechanism” to allow shielded wallets to successfully interact with conformant Transparent-Only wallets.
• Allow older conformant wallets to interact seamlessly with newer wallets.
• Enable users of newer wallets to upgrade to newer transaction technologies and/or pools while maintaining seamless interactions with counterparties using older wallets.
• Facilitate wallets to assume more sophisticated responsibilities for shielding and/or migrating user funds.
• Allow wallets to potentially develop new transfer mechanisms without underlying protocol changes.
• Support abstractions corresponding to a Unified Address that provide the functionality of Full Viewing Keys and Incoming Viewing Keys.
• 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.
• Allow for Metadata Items to be included in Unified Addresses/Viewing Keys in order to provide future extensibility.
• 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.

Requirements

Overview

Unified Addresses specify multiple methods for payment to a Recipient's wallet. The Sender's wallet can then non-interactively select the method of payment.

Importantly, any wallet can support Unified Addresses, even when that wallet only supports a subset of payment methods for receiving and/or sending.

Despite having some similar characteristics, the Unified Address standard is orthogonal to Payment Request URIs⁵ and similar schemes. Since Payment Requests encode addresses as alphanumeric strings, no change to ZIP 321 is required in order to use Unified Addresses in Payment Requests.

Concepts

Wallets follow a model Interaction Flow as follows:

1. A Producer generates an Address.
2. The Producer encodes the Address.
3. The Producer wallet or human user distributes this Address Encoding. This ZIP leaves distribution mechanisms out of scope.
4. A Consumer wallet or user imports the Address Encoding through any of a variety of mechanisms (QR code scanning, Payment URIs, cut-and-paste, or “in-band” protocols like Reply-To memos).
5. A Consumer wallet decodes the Address Encoding and performs validity checks.
6. (Perhaps later in time) if the Consumer wallet is a Sender, it can execute a transfer of ZEC (or other assets or protocol state changes) to the Address.

Encodings of the same Address may be distributed zero or more times through different means. Zero or more Consumers may import Addresses. Zero or more of those (that are Senders) may execute a Transfer. A single Sender may execute multiple Transfers over time from a single import.

Steps 1 to 5 inclusive also apply to Interaction Flows for Unified Full Viewing Keys and Unified Incoming Viewing Keys.

Addresses

A Unified Address (or UA for short) combines one or more Receivers.

When new Transport Protocols are introduced to the Zcash protocol after Unified Addresses are standardized, those should introduce new Receiver Types but not 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.

For Revision 2, users must be able to visually distinguish addresses that risk information being leaked on-chain as a result of a transfer, from addresses that present no such risks, with the exception of pool-crossing amounts. The latter are accepted leage in the UA design, in order to achieve the desired wallet compatibility properties.

Receivers

Every wallet must properly parse encodings of a Unified Address or Unified Viewing Key containing unrecognised Items.

A wallet may process unrecognised Items by indicating to the user their presence or similar information for usability or diagnostic purposes.

Transport Encoding

The Unified String Encoding is “opaque” to human readers: it does not allow visual identification of which Receivers or Receiver Types are present.

The Unified String Encoding is resilient against typos, transcription errors, cut-and-paste errors, truncation, or other likely UX hazards.

There is a well-defined Unified QR Encoding of a Unified Address (or UFVK or UIVK) as a QR code, which produces QR codes that are reasonably compact and robust.

There is a well-defined transformation between the Unified QR Encoding and Unified String Encoding of a given UA/UVK in either direction.

The Unified String Encoding fits into ZIP-321 Payment URIs⁶ and general URIs without introducing parse ambiguities.

The encoding must support sufficiently many Recipient Types to allow for reasonable future expansion.

The encoding must allow all wallets to safely and correctly parse out unrecognised Receiver Types well enough to ignore them.

Transfers

When executing a Transfer the Sender selects a Receiver via a Selection process.

Given a valid UA, Selection must treat any unrecognised Item as though it were absent (with the exception that Items with typecodes in the MUST-understand range may not be ignored; the Sender must reject addresses containing MUST-understand Items that they do not recognise).

• 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.
• This property is crucial for allowing wallets that support only older shielded protocols to interact with newer shielded wallets, removing a disincentive for adopting newer shielded wallets.
• This property also allows wallets to upgrade to newer shielded protocol support without re-acquiring counterparty UAs. If they are re-acquired, the user flow and usability will be minimally disrupted.

Experimental Usage

Unified Addresses and Unified Viewing Keys must be able to include Receivers and Viewing Keys of experimental types, possibly alongside non-experimental ones. These experimental Receivers or Viewing Keys must be used only by wallets whose users have explicitly opted into the corresponding experiment.

Viewing Keys

A Unified Full Viewing Key (resp. Unified Incoming Viewing Key) can be used in a similar way to a Full Viewing Key (resp. Incoming Viewing Key) as described in the Zcash Protocol Specification⁷.

For a Transparent P2PKH Address that is derived according to BIP 32 ⁸ and BIP 44⁹, the nearest equivalent to a Full Viewing Key or Incoming Viewing Key for a given BIP 44 account is an extended public key, as defined in the section “Extended keys” of BIP 32. Therefore, UFVKs and UIVKs should be able to include such extended public keys.

A wallet should support deriving a UIVK from a UFVK, and a Unified Address from a UIVK.

Open Issues and Known Concerns

Privacy impacts of transparent or cross-pool transactions, and the associated UX issues, will be addressed in ZIP 315 (in preparation).

Specification

Revisions

A Revision 0 UA/UVK is distinguished from a Revision 2 UA/UVK by its Human-Readable Part, as follows.

Let addr_prefix be:

• “u”, if this is a UA or UVK prior to Revision 2;
• “zu”, if this is a shielded-only UA from Revision 2 onward.
• “tu”, if this is a transparent-enabled UA from Revision 2 onward.

The Human-Readable Parts (as defined in¹¹) of Unified Addresses are defined as:

• addr_prefix, for Unified Addresses on Mainnet;
• addr_prefix || “test”, for Unified Addresses on Testnet.

Let ivk_prefix be:

• “uivk” prior to Revision 2;
• “uvi” from Revision 2 onward.

Let fvk_prefix be:

• “uview” prior to Revision 2;
• “uvf” from Revision 2 onward.

The Human-Readable Parts of Unified Viewing Keys are defined as:

• ivk_prefix for Unified Incoming Viewing Keys on Mainnet;
• ivk_prefix || “test” for Unified Incoming Viewing Keys on Testnet;
• fvk_prefix for Unified Full Viewing Keys on Mainnet;
• fvk_prefix || “test” for Unified Full Viewing Keys on Testnet.

Encoding of Unified Addresses

Rather than defining a Bech32 string encoding of Orchard Shielded Payment Addresses, we instead define a Unified Address format that is able to encode a set of Receivers of different types. This enables the Consumer of a Unified Address to choose the Receiver of the best type it supports, providing a better user experience as new Receiver Types are added in the future.

Assume that we are given a set of one or more Receiver Encodings for distinct types. That is, the set may optionally contain one Receiver of each of the Receiver Types in the following fixed Priority List:

• Typecode $\mathtt{0x03}$ — an Orchard raw address as defined in¹²;
• Typecode $\mathtt{0x02}$ — a Sapling raw address as defined in¹³;
• Typecode $\mathtt{0x01}$ — a Transparent P2SH address, or Typecode $\mathtt{0x00}$ — a Transparent P2PKH address.

If, and only if, the user of a Producer or Consumer wallet explicitly opts into an experiment as described in Experimental Usage, 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).

We say that a Receiver Type is “preferred” over another when it appears earlier in this Priority List (as potentially modified by experiments).

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.

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.

The raw encoding of a Unified Address is a concatenation of $(\mathtt{typecode}, \mathtt{length}, \mathtt{addr})$ encodings of the constituent Receivers, in ascending order of Typecode:

• $\mathtt{typecode} : \mathtt{compactSize}$ — the Typecode from the above Priority List;
• $\mathtt{length} : \mathtt{compactSize}$ — the length in bytes of $\mathtt{addr}$;
• $\mathtt{addr} : \mathtt{byte[length]}$ — the Receiver Encoding.

The values of the $\mathtt{typecode}$ and $\mathtt{length}$ fields MUST be less than or equal to $\mathtt{0x2000000}$. (The limitation on the total length of encodings described below imposes a smaller limit for $\mathtt{length}$ in practice.)

A Receiver Encoding is the raw encoding of a Shielded Payment Address, or the $160$-bit script hash of a P2SH address¹⁴, or the $160$-bit validating key hash of a P2PKH address¹⁵.

Let padding be the Human-Readable Part of the Unified Address in US-ASCII, padded to 16 bytes with zero bytes. We append padding to the concatenated encodings, and then apply the $\mathsf{F4Jumble}$ algorithm as described in Jumbling. (In order for the limitation on the $\mathsf{F4Jumble}$ input size to be met, the total length of encodings MUST be at most $\ell^\mathsf{MAX}_M - 16$ bytes, where $\ell^\mathsf{MAX}_M$ is defined in Jumbling.) The output is then encoded with Bech32m¹⁶, ignoring any length restrictions. This is chosen over Bech32 in order to better handle variable-length inputs.

To decode a Unified Address Encoding, a Consumer MUST use the following procedure:

• Decode using Bech32m, rejecting any address with an incorrect checksum.
• Apply $\mathsf{F4Jumble}^{-1}$ (this can also reject if the input is not in the correct range of lengths).
• Let padding be the Human-Readable Part, padded to 16 bytes as for encoding. If the result ends in padding, remove these 16 bytes; otherwise reject.
• Parse the result as a raw encoding as described above, rejecting the entire Unified Address if it does not parse correctly.

The Human-Readable Part is as specified for a Unified Address in Revisions.

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.

Encoding of Unified Full/Incoming Viewing Keys

Unified Full or Incoming Viewing Keys are encoded and decoded analogously to Unified Addresses. A Consumer MUST use the decoding procedure from the previous section. 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.

For each FVK Type or IVK Type currently defined in this specification, the same Typecode is used as for the corresponding Receiver Type in a Unified Address. Additional FVK Types and IVK Types MAY be defined in future, and these will not necessarily use the same Typecode as the corresponding Unified Address.

The following FVK or IVK Encodings are used in place of the $\mathtt{addr}$ field:

• An Orchard FVK or IVK Encoding, with Typecode $\mathtt{0x03}$, is the raw encoding of the Orchard Full Viewing Key or Orchard Incoming Viewing Key respectively.
• A Sapling FVK Encoding, with Typecode $\mathtt{0x02}$, is the encoding of $(\mathsf{ak}, \mathsf{nk}, \mathsf{ovk}, \mathsf{dk})$ given by $\mathsf{EncodeExtFVKParts}(\mathsf{ak}, \mathsf{nk}, \mathsf{ovk}, \mathsf{dk})$, where $\mathsf{EncodeExtFVKParts}$ is defined in¹⁷. This SHOULD be derived from the Extended Full Viewing Key at the Account level of the ZIP 32 hierarchy.
• A Sapling IVK Encoding, also with Typecode $\mathtt{0x02}$, is an encoding of $(\mathsf{dk}, \mathsf{ivk})$ given by $\mathsf{dk}\,||\,\mathsf{I2LEOSP}_{256}(\mathsf{ivk})$. Note that a zero $\mathsf{ivk}$ is not valid¹⁸.

The Human-Readable Part is as specified for a Unified Viewing Key in Revisions.

Rationale for address derivation

Click to show/hide

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

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.

Requirements for both Unified Addresses and Unified Viewing Keys

• A Unified Address or Unified Viewing Key MUST contain at least one non-metadata Item.
• A Revision 0 Unified Address MUST contain at least one shielded Item (currently Typecodes $\mathtt{0x02}$ and $\mathtt{0x03}$). Consumers MUST reject addresses that violate this restriction.
• A Revision 2 Unified Address encoded with the zu prefix MUST NOT contain any transparent Items (currently Typecodes $\mathtt{0x00}$ and $\mathtt{0x01}$). Consumers MUST reject addresses that violate this restriction.
• A Revision 0 Unified Viewing Key MUST contain at least one shielded Item (currently Typecodes $\mathtt{0x02}$ and $\mathtt{0x03}$). This requirement is dropped for Revision 2 UVKs. Consumers MUST reject any UVK that violates the restriction applying to its Revision.
• The $\mathtt{typecode}$ and $\mathtt{length}$ fields are encoded as $\mathtt{compactSize}$.²⁴ (Although existing Receiver Encodings and Viewing Key Encodings are all less than 256 bytes and so could use a one-byte length field, encodings for experimental types may be longer.)
• Within a single UA or UVK, all HD-derived Receivers, FVKs, and IVKs SHOULD represent an Address or Viewing Key for the same account (as used in derivation at the ZIP 32 or BIP 44 Account level, or, for ZIP 48²⁵ and/or FROST²⁶ UVKs, a single set of signers with the ability to generate independent addresses corresponding to that spending authority). In the case of FROST, key material MUST be derived according to the requirements of ZIPs 312 and 2005, in particular the "Usage with FROST" section of the latter²⁷.
• For Transparent Addresses, the Receiver Encoding does not include the first two bytes of a raw encoding.
• There is intentionally no Typecode defined for a Sprout Shielded Payment Address or Sprout Incoming Viewing Key. Since it is no longer possible (since activation of ZIP 211 in the Canopy network upgrade²⁸) to send funds into the Sprout chain value pool, this would not be generally useful.
• It is RECOMMENDED that Producers upgrade to understand and generate Revision 2 addresses as soon as possible.
• With the exception of MUST-understand Metadata Items, Consumers MUST ignore constituent Items with Typecodes they do not recognise.
• 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 Metadata Items.
• Consumers MUST reject Unified Addresses/Viewing Keys in which any constituent Item does not meet the validation requirements of its encoding, as specified in this ZIP and the Zcash Protocol Specification ²⁹.
• 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.
• There MUST NOT be additional bytes at the end of the raw encoding that cannot be interpreted as specified above.
• If the encoding of a Unified Address/Viewing Key is shown to a user in an abridged form due to lack of space, at least the first 20 characters MUST be included. This helps the user to see enough of the UA/UVK to defend against partial matching attacks; see Rationale for showing at least the first 20 characters for additional commentary on how the cost of such attacks depends on the number of characters the user is able to check.

Rationale for dropping the "at least one shielded Item" restriction for UVKs

Click to show/hide

The original rationale for this restriction was that the existing P2SH and P2PKH transparent-only address formats, and the existing P2PKH extended public key format, sufficed for representing viewing keys with transparent Items, and were already supported by the existing ecosystem.

However, as of Revision 2 there are uses for transparent-only UVKs that are not covered by the existing formats. In particular, they allow the representation of viewing keys for P2SH addresses, which is an important use case with the advent of ZIP 48³⁰. In addition, transparent-only viewing keys can use Metadata Items to represent expiration heights/dates as described in Address Expiration Metadata that is useful in the generation of tu-prefixed addresses.

Rationale for removing Transparent Receivers from zu Unified Addresses

Click to show/hide

A common complaint about Revision 0 Unified Addresses was that there was no way for a user to visually distinguish a Unified Address that allowed the receipt of transparent funds from one that did not; Transparent addresses do not provide any privacy protection, and including them in UAs created a risk that Senders would fall back to transparent transfers even when the Recipient supports shielded protocols. Historically, the z address prefix indicated to the user that no element of the recipient address would cause information about the recipient to be leaked on-chain by transfers to that address. Revision 2 restores this property.

Transparent Items are still permitted in Unified Viewing Keys because viewing keys serve a different purpose: they allow observation of transaction activity across all pools, including transparent. A UFVK or UIVK that includes a transparent component allows the holder to derive transparent addresses for scanning purposes and to track transparent funds associated with the same account.

Rationale for Item ordering

Click to show/hide

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/UVK (provided that unrecognised Items are retained).

Rationale for showing at least the first 20 characters

Click to show/hide

Showing fewer than 20 characters of the String Encoding of a UA/UVK would potentially allow practical attacks in which the adversary constructs another UA/UVK that matches in the characters shown. When a UA/UVK is abridged it is preferable to show a prefix rather than some other part, both for a more consistent user experience across wallets, and because security analysis of the cost of partial UA/UVK string matching attacks is more complicated if checksum characters are included in the characters that are compared.

To analyze the difficulty of partial matching attacks, we must subtract the length of the HRP and the "1" separator from the 20 characters. The longest HRP defined for a Mainnet UA/UVK in this specification for is "uview" for Revision 0 UFVKs — and so in the worst case only 14 characters, corresponding to 70 bits, of the jumbled Mainnet UA/UVK data will be present. (We are not particularly concerned about attacks on Testnet UA/UVKs.) This implies an easier partial matching attack than Zcash's usual target security level against classical attacks of $2^{125}$. Note also that multi-target attacks are possible. 20 characters should therefore be considered an absolute minimum, and wallet implementors may wish to show a larger number of initial characters for abridged UA/UVKs to enable users to defend against partial matching attacks up to a higher difficulty for the adversary.

Note that if different sources show different substrings of a UA/UVK then users are only able to compare the characters that are common to all of these substrings, and so it is only initial characters that contribute to satisfying this requirement.

Adding new types

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³¹.

For experimentation prior to proposing a ZIP, experimental types MAY be added using the reserved Typecodes $\mathtt{0xFFFA}$ to $\mathtt{0xFFFF}$ 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.

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

Metadata Items

Typecodes $\mathtt{0xC0}$ to $\mathtt{0xFC}$ 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).

A Revision 0 UA/UVK (determined by its HRP as specified in Revisions) MUST NOT include any Metadata Items with a MUST-understand Typecode; a Consumer MUST reject as invalid any UA/UVK that violates this requirement.

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.

New Metadata Types SHOULD be introduced either by a modification to this ZIP or by a new ZIP, in accordance with the ZIP Process³².

Rationale for making Revision 0 UA/UVKs with MUST-understand Typecodes invalid

Click to show/hide

A Consumer implementing this ZIP prior to Revision 2 will not recognise the Human-Readable Parts beginning with “zu” that mark a Revision 2 UA/UVK. So if a UA/UVK that includes MUST-understand Typecodes is required to use these Revision 2 HRPs, this will ensure that the MUST-understand specification is correctly enforced even for such implementations.

Address Expiration Metadata

As of Revision 2, Typecodes $\mathtt{0xE0}$ and $\mathtt{0xE1}$ are reserved for optional address expiry metadata. A producer MAY choose to generate Unified Addresses containing either or both of the following Metadata Item Types, or none.

The value of a $\mathtt{0xE0}$ item MUST be an unsigned 32-bit integer in little-endian order specifying the Address Expiry Height, a block height of the Zcash chain associated with the UA/UVK. A Unified Address containing metadata Typecode $\mathtt{0xE0}$ MUST be considered expired when the height of the Zcash chain is greater than this value.

The value of a $\mathtt{0xE1}$ item MUST be an unsigned 64-bit integer in little-endian order specifying a Unix Epoch Time, hereafter referred to as the Address Expiry Time. A Unified Address containing Metadata Typecode $\mathtt{0xE1}$ MUST be considered expired when the current time is after the Address Expiry Time.

A Sender that supports Revision 2 of this specification MUST set a non-zero nExpiryHeight field in transactions it creates that are sent to a Unified Address that defines an Address Expiry Height. If the nExpiryHeight normally constructed by the Sender would be greater than the Address Expiry Height, then the transaction MUST NOT be sent. If only an Address Expiry Time is specified, then the Sender SHOULD choose a value for nExpiryHeight such that the transaction will expire no more than 24 hours after the current time. If both $\mathtt{0xE0}$ and $\mathtt{0xE1}$ Metadata Items are present, then both restrictions apply.

If a Sender sends to multiple Unified Addresses in the same transaction, then all of the Address Expiry constraints imposed by the individual addresses apply.

If a wallet user attempts to send to an expired address, the error presented to the user by the wallet SHOULD include a suggestion that the user should attempt to obtain a currently-valid address for the intended recipient. A wallet MUST NOT send to an address that it knows to have expired.

Address expiration imposes no constraints on the Producer of an address. A Producer MAY generate multiple Unified Addresses with the same Receivers but different expiration metadata and/or any number of distinct Diversified Unified Addresses with the same or different expiry metadata, in any combination. Note that although changes to metadata will result in a visually distinct address, such updated addresses will be directly linkable to the original addresses because they share the same Receivers.

When deriving a UIVK from a UFVK containing Typecodes $\mathtt{0xE0}$ and/or $\mathtt{0xE1}$, these Metadata Items MUST be retained unmodified in the derived UIVK.

When deriving a Unified Address from a UFVK or UIVK containing a Metadata Item having Typecode $\mathtt{0xE0}$, the derived Unified Address MUST contain a Metadata Item having Typecode $\mathtt{0xE0}$ such that the Address Expiry Height of the resulting address is less than or equal to the Expiry Height of the viewing key.

When deriving a Unified Address from a UFVK or UIVK containing a Metadata Item having Typecode $\mathtt{0xE1}$, the derived Unified Address MUST contain a Metadata Item having Typecode $\mathtt{0xE1}$ such that the Address Expiry Time of the resulting address is less than or equal to the Expiry Time of the viewing key.

Producers of Diversified Unified Addresses should be aware that the expiration metadata could potentially be used to link addresses from the same source. Normally, if Diversified Unified Addresses derived from the same UIVK contain only Sapling and/or Orchard Receivers and no Metadata Items, they will be unlinkable as described in³³; this property does not hold when Metadata Items are present. It is RECOMMENDED that when deriving Unified Addresses from a UFVK or UIVK containing expiry metadata that the Expiry Height and Expiry Time of each distinct address vary from one another, so as to reduce the likelihood that addresses may be linked via their expiry metadata.

Rationale

The intent of this specification is that Consumers of Unified Addresses must not send to expired addresses. If only an Address Expiry Time is specified, a transaction to the associated address could be mined after the Address Expiry Time within a 24-hour window.

The reason that the transaction MUST NOT be sent when its nExpiryHeight as normally constructed is greater than the Address Expiry Height is to avoid unnecessary information leakage in that field about which address was used as the destination. If a sender were to instead use the expiry height to directly set the nExpiryHeight field, this would leak the expiry information of the destination address, which may then be identifiable.

When honoring an Address Expiry Time, the reason that a sender SHOULD choose a nExpiryHeight that is expected to occur within 24 hours of the time of transaction construction is to, when possible, ensure that the expiry time is respected to within a day. Address Expiry Times are advisory and do not represent hard bounds because computer clocks often disagree, but every effort should be made to ensure that transactions expire instead of being mined more than 24 hours after a recipient address's expiry time. When chain height information is available to the Sender, it is both permissible and advisable to set this bound more tightly; a common expiry delta used by many wallets is 40 blocks from the current chain tip, as suggested in ZIP 203 ³⁴.

Typecode Registry

The following table specifies the full range of Typecodes and indicates which address types permit each Typecode. Typecode range entries in the table below are to be interpreted as end-inclusive.