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 11 and similar schemes, and the Unified Address format is likely to be incorporated into such schemes as a new Address type.

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.

Receivers

Every Wallet must properly parse a Unified Address containing unrecognized Receiver Types; and similarly for Unified Viewing Keys containing unrecognized Viewing Key Types.

A Wallet may process unrecognized Receiver Types or Viewing Key Types by indicating to the user their presence or similar information for usability or diagnostic purposes.

Transport Encoding

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

The string encoding is resilient against typos, transcription errors, cut-and-paste errors, unanticipated truncation, or other anticipated UX hazards.

There is a well-defined 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 QR Code and string encodings in either direction.

The string encoding fits into ZIP-321 Payment URIs 11 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 unrecognized 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 unrecognized Receiver as though it were absent.

• 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 Transparent-Only UA-Conformant wallets to interact with newer shielded wallets, removing a disincentive for adopting newer shielded wallets.
• This property also allows Transparent-Only wallets to upgrade to shielded 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 2.

For a Transparent P2PKH Address that is derived according to BIP 32 12 and BIP 44 15, 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).

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 5;
• Typecode \(\mathtt{0x02}\) — a Sapling raw address as defined in 4;
• Typecode \(\mathtt{0x01}\) — a Transparent P2SH address, or Typecode \(\mathtt{0x00}\) — a Transparent P2PKH address.

We say that a Receiver Type is “preferred” over another when it appears earlier in this Priority List.

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 consituent Receivers:

• \(\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}.\)

A Receiver Encoding is the raw encoding of a Shielded Payment Address, or the \(160\!\) -bit script hash of a P2SH address 19, or the \(160\!\) -bit validating key hash of a P2PKH address 18.

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. The output is then encoded with Bech32m 17, 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.

For Unified Addresses on Mainnet, the Human-Readable Part (as defined in 17) is “u”. For Unified Addresses on Testnet, the Human-Readable Part is “utest”.

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.

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 UFVK Type or UIVK Type currently defined in this specification, the same Typecode is used as for the corresponding Receiver Type in a Unified Address. Additional UFVK Types and UIVK Types MAY be defined in future, and these will not necessarily use the same Typecode as the corresponding Unified Address.

The following UFVK or UIVK Encodings are used in place of the \(\mathtt{addr}\) field:

• An Orchard UFVK or UIVK Encoding, with Typecode \(\mathtt{0x03},\) is the raw encoding of the Orchard Full Viewing Key or Orchard Incoming Viewing Key respectively.
• A Sapling UFVK Encoding, with Typecode \(\mathtt{0x02},\) is the encoding of a Sapling Extended Full Viewing Key defined in 7.
• A Sapling UIVK Encoding, also with Typecode \(\mathtt{0x02},\) is an encoding of \((\mathsf{dk}, \mathsf{ivk})\) given by \(\mathsf{I2LEOSP}_{88}(\mathsf{dk})\,||\,\mathsf{I2LEOSP}_{256}(\mathsf{ivk}).\)
• There is no defined way to represent a Viewing Key for a Transparent P2SH Address in a UFVK or UIVK (because P2SH Addresses cannot be diversified in an unlinkable way). The Typecode \(\mathtt{0x01}\) MUST NOT be included in a UFVK or UIVK by Producers, and MUST be treated as unrecognized by Consumers.
• For Transparent P2PKH Addresses that are derived according to BIP 32 12 and BIP 44 15, the UFVK and UIVK Encodings have Typecode \(\mathtt{0x00}.\) These encodings are identical and are the serialization of an extended public key, defined in the section “Serialization format” of BIP 32 13.

The Human-Readable Parts (as defined in 17) of Unified Viewing Keys are defined as follows:

• “uivk” for Unified Incoming Viewing Keys on Mainnet;
• “uivktest” for Unified Incoming Viewing Keys on Testnet;
• “uview” for Unified Full Viewing Keys on Mainnet;
• “uviewtest” for Unified Full Viewing Keys on Testnet.

Requirements for both Unified Addresses and Unified Viewing Keys

• A Unified Address or Unified Viewing Key MUST NOT contain only transparent P2SH or P2PKH addresses (Typecodes \(\mathtt{0x00}\) and \(\mathtt{0x01}\) ). The rationale is that the existing P2SH and P2PKH transparent-only address formats, and the existing P2PKH extended public key format, suffice for this purpose and are already supported by the existing ecosystem.
• The \(\mathtt{typecode}\) and \(\mathtt{length}\) fields are encoded as \(\mathtt{compactSize}.\) 20 (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.)
• Each Receiver, UFVK, or UIVK SHOULD represent an Address or Viewing Key at the ZIP 32 or BIP 44 Account level.
• 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 9) to send funds into the Sprout chain value pool, this would not be generally useful.
• Consumers MUST ignore constituent Addresses/Viewing Keys with Typecodes they do not recognize.
• Consumers MUST reject Unified Addresses/Viewing Keys in which the same Typecode appears more than once, or that include both P2SH and P2PKH Transparent Addresses, or that contain only a Transparent Address.
• Consumers MUST reject Unified Addresses/Viewing Keys in which any constituent address does not meet the validation requirements of its Receiver Encoding, as specified in the Zcash Protocol Specification 2.
• Producers SHOULD order the constituent Addresses/Viewing Keys in the same order as in the Priority List above. However, Consumers MUST NOT assume this ordering, and it does not affect which Address should be used by a Sender.
• There MUST NOT be additional bytes at the end of the raw encoding that cannot be interpreted as specified above.

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

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.

Deriving a UIVK from a UFVK

Each UIVK Encoding can straightforwardly be derived from the corresponding UFVK Encoding, without changing the Typecode. In the case of a Transparent P2PKH UFVK Encoding, the UIVK Encoding is the same.

Deriving a Unified Address from a UIVK

To derive a Unified Address from a UIVK we need to choose a diversifier index, which MUST be valid for all of the Viewing Key Types in the UIVK. That is,

• A Sapling diversifier index MUST generate a valid diversifier as defined in ZIP 32 section “Sapling diversifier derivation” 8.
• A Transparent diversifier index MUST be in the range \(0\) to \(2^{31}\) inclusive.

There are no additional constraints on an Orchard diversifier index.

In the case of deriving a Transparent P2PKH Receiver from a Transparent P2PKH UIVK, the diversifier index is used as a BIP 44 child key index at the Index level to derive the address. As is usual for derivations below the BIP 44 Account level, non-hardened (public) derivation 14 MUST be used, with the Change element of the path being 0, and the Index element of the path being the diversifier index 16. That is, the BIP 44 path of the Transparent P2PKH Receiver MUST be:

• \(m / 44' / \mathit{coin\_type\kern0.05em'} / \mathit{account\kern0.1em'} / 0 / \mathit{diversifier\_index}.\)

Jumbling

Security goal (near second preimage resistance):

• An adversary is given \(q\) Unified Addresses, generated honestly.
• The attack goal is to produce a “partially colliding” valid Unified Address that:
  1. has a string encoding matching that of one of the input Addresses on some subset of characters (for concreteness, consider the first \(n\) and last \(m\) characters, up to some bound on \(n+m\) );
  2. is controlled by the adversary (for concreteness, the adversary knows at least one of the private keys of the constituent Addresses).

Security goal (nonmalleability):

• In this variant, part b) above is replaced by the meaning of the new Address being “usefully” different than the Address it is based on, even though the adversary does not know any of the private keys. For example, if it were possible to delete a shielded constituent Address from a UA leaving only a Transparent Address, that would be a significant malleability attack.

Solution

We use an unkeyed 4-round Feistel construction to approximate a random permutation. (As explained below, 3 rounds would not be sufficient.)

Let \(H_i\) be a hash personalized by \(i,\) with maximum output length \(\ell_H\) bytes. Let \(G_i\) be a XOF (a hash function with extendable output length) based on \(H,\) personalized by \(i.\)

Define \(\ell^\mathsf{MAX}_M = (2^{16} + 1) \cdot \ell_H.\) For the instantiation using BLAKE2b defined below, \(\ell^\mathsf{MAX}_M = 4194368.\)

Given input \(M\) of length \(\ell_M\) bytes such that \(48 \leq \ell_M \leq \ell^\mathsf{MAX}_M,\) define \(\mathsf{F4Jumble}(M)\) by:

• let \(\ell_L = \mathsf{min}(\ell_H, \mathsf{floor}(\ell_M/2))\)
• let \(\ell_R = \ell_M - \ell_L\)
• split \(M\) into \(a\) of length \(\ell_L\) bytes and \(b\) of length \(\ell_R\) bytes
• let \(x = b \oplus G_0(a)\)
• let \(y = a \oplus H_0(x)\)
• let \(d = x \oplus G_1(y)\)
• let \(c = y \oplus H_1(d)\)
• return \(c \,||\, d.\)

The inverse function \(\mathsf{F4Jumble}^{-1}\) is obtained in the usual way for a Feistel construction, by observing that \(r = p \oplus q\) implies \(p = r \oplus q.\)

The first argument to BLAKE2b below is the personalization.

We instantiate \(H_i(u)\) by \(\mathsf{BLAKE2b‐}(8\ell_L)(\texttt{“UA_F4Jumble_H”} \,||\,\) \([i, 0, 0], u),\) with \(\ell_H = 64.\)

We instantiate \(G_i(u)\) as the first \(\ell_R\) bytes of the concatenation of \([\mathsf{BLAKE2b‐}512(\texttt{“UA_F4Jumble_G”} \,||\, [i] \,||\,\) \(\mathsf{I2LEOSP}_{16}(j), u) \text{ for } j \text{ from}\) \(0 \text{ up to } \mathsf{ceiling}(\ell_R/\ell_H)-1].\)

(In practice the lengths \(\ell_L\) and \(\ell_R\) will be roughly the same until \(\ell_M\) is larger than \(128\) bytes.)

Heuristic analysis

A 3-round unkeyed Feistel, as shown, is not sufficient:

Suppose that an adversary has a target input/output pair \((a \,||\, b, c \,||\, d),\) and that the input to \(H_0\) is \(x.\) By fixing \(x,\) we can obtain another pair \(((a \oplus t) \,||\, b', (c \oplus t) \,||\, d')\) such that \(a \oplus t\) is close to \(a\) and \(c \oplus t\) is close to \(c.\) ( \(b'\) and \(d'\) will not be close to \(b\) and \(d,\) but that isn't necessarily required for a valid attack.)

A 4-round Feistel thwarts this and similar attacks. Defining \(x\) and \(y\) as the intermediate values in the first diagram above:

• if \((x', y')\) are fixed to the same values as \((x, y),\) then \((a', b', c', d') = (a, b, c, d);\)
• if \(x' = x\) but \(y' \neq y,\) then the adversary is able to introduce a controlled \(\oplus\!\) -difference \(a \oplus a' = y \oplus y',\) but the other three pieces \((b, c, d)\) are all randomized, which is sufficient;
• if \(y' = y\) but \(x' \neq x,\) then the adversary is able to introduce a controlled \(\oplus\!\) -difference \(d \oplus d' = x \oplus x',\) but the other three pieces \((a, b, c)\) are all randomized, which is sufficient;
• if \(x' \neq x\) and \(y' \neq y,\) all four pieces are randomized.

Note that the size of each piece is at least 24 bytes.

It would be possible to make an attack more expensive by making the work done by a Producer more expensive. (This wouldn't necessarily have to increase the work done by the Consumer.) However, given that Unified Addresses may need to be produced on constrained computing platforms, this was not considered to be beneficial overall.

The padding contains the HRP so that the HRP has the same protection against malleation as the rest of the address. This may help against cross-network attacks, or attacks that confuse addresses with viewing keys.