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:
+ 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.
+ Similarly, a Unified Full Viewing Key or Unified Incoming Viewing Key provides the corresponding visibility into transactions that may use addresses of different types. Typically these will be the addresses for each pool derived from an Account as defined in . (It is not possible for a UVK to include viewing keys for multiple addresses of the same type.)
+ When a string encoding of a Unified Address or Unified Viewing Key is shown to a user, it MUST be encoded using the Unified String Encoding defined in String Encodings of Unified Addresses and Unified Viewing Keys. The main reason for this is to satisfy the requirements concerning resilience to user error and resistance to malleability attacks, as described in Transport Encodings.
+ In cases where Unified Addresses or Unified Viewing Keys are not shown directly to users but need to be encoded as machine-readable data, the Unified Raw Encoding MAY be used instead of the Unified String Encoding. This has the advantage of reducing the space requirement, and may also reduce computational costs and implementation complexity.
+ A Unified Raw Encoding has no resilience to data corruption and transcription errors, or resistance to malleability attacks, and therefore MUST NOT be used in situations where these properties are required. For clarity, this includes all situations where Address Encodings are exposed directly to end-users.
+ Encoding Prefixes
+ The following HRPs (Human-Readable Parts as defined in ) and Lead Bytes are defined to tag particular Unified Address or Viewing Key types on a specific network.
+
+
+
+ | Meaning |
+ HRP |
+ Lead Byte |
+
+
+
+
+ | Unified Addresses on Mainnet |
+ u |
+ 0 |
+
+
+ | Unified Addresses on Testnet |
+ utest |
+ 1 |
+
+
+ | Unified Incoming Viewing Keys on Mainnet |
+ uivk |
+ 2 |
+
+
+ | Unified Incoming Viewing Keys on Testnet |
+ uivktest |
+ 3 |
+
+
+ | Unified Full Viewing Keys on Mainnet |
+ uview |
+ 4 |
+
+
+ | Unified Full Viewing Keys on Testnet |
+ uviewtest |
+ 5 |
+
+
+
+ Their usage is defined in the following sections.
+
+ Raw Encoding of Unified Addresses
+ Assume that we are given a set of one or more Receiver Items 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 ;
+ — an Orchard raw address as defined in ;
- Typecode
\(\mathtt{0x02}\)
- — a Sapling raw address as defined in ;
+ — a Sapling raw address as defined in ;
- Typecode
\(\mathtt{0x01}\)
— a Transparent P2SH address, or Typecode
@@ -175,9 +238,14 @@
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
+
A Binary HRP is a single length byte
+ \(\mathtt{hrp\_len}\)
+ from 0 to 16 inclusive, followed by
+ \(\mathtt{hrp\_len}\)
+ bytes of a US-ASCII-encoded HRP.
+ The Unified Raw Encoding of a Unified Address is a Binary HRP followed by a concatenation of
\((\mathtt{typecode}, \mathtt{length}, \mathtt{addr})\)
- encodings of the consituent Receivers, in ascending order of Typecode:
+ encodings of the constituent Receivers, in ascending order of Typecode:
-
\(\mathtt{typecode} : \mathtt{compactSize}\)
@@ -189,7 +257,7 @@
-
\(\mathtt{addr} : \mathtt{byte[length]}\)
- — the Receiver Encoding.
+ — the Receiver Item.
The values of the
\(\mathtt{typecode}\)
@@ -200,43 +268,24 @@
(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
+
A Receiver Item is the raw encoding of a Shielded Payment Address, or the
\(160\!\)
- -bit script hash of a P2SH address , or the
+ -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.
-
- For Unified Addresses on Mainnet, the Human-Readable Part (as defined in ) is “u”. For Unified Addresses on Testnet, the Human-Readable Part is “utest”.
+ -bit validating key hash of a P2PKH address .
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.
+ Raw Encoding of Unified Full/Incoming Viewing Keys
+ Unified Full or Incoming Viewing Keys are encoded and decoded analogously to Unified Addresses. 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
+
The following FVK or IVK Items are used in place of the
\(\mathtt{addr}\)
field:
- - An Orchard FVK or IVK Encoding, with Typecode
+
- An Orchard FVK or IVK Item, with Typecode
\(\mathtt{0x03},\)
is is the raw encoding of the Orchard Full Viewing Key or Orchard Incoming Viewing Key respectively.
- - A Sapling FVK Encoding, with Typecode
+
- A Sapling FVK Item, with Typecode
\(\mathtt{0x02},\)
is the encoding of
\((\mathsf{ak}, \mathsf{nk}, \mathsf{ovk}, \mathsf{dk})\)
@@ -245,7 +294,7 @@
, 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
+
- A Sapling IVK Item, also with Typecode
\(\mathtt{0x02},\)
is an encoding of
\((\mathsf{dk}, \mathsf{ivk})\)
@@ -255,7 +304,7 @@
- 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 and BIP 44 , the FVK and IVK Encodings have Typecode
+
- For Transparent P2PKH Addresses that are derived according to BIP 32 and BIP 44 , the FVK and IVK Items have Typecode
\(\mathtt{0x00}.\)
Both of these are encodings of the chain code and public key
\((\mathsf{c}, \mathsf{pk})\)
@@ -267,18 +316,84 @@
\(m / 44' / coin\_type' / account' / 0\)
.
- The Human-Readable Parts (as defined in ) 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.
-
Rationale for address derivation
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.
+ String Encodings of Unified Addresses and Unified Viewing Keys
+ A Unified String Encoding for a UA/UIVK is obtained by constructing the corresponding Unified Raw Encoding as defined in previous sections, and then converting it to a Unified String Encoding as follows.
+ Let
+ \(\ell^\mathsf{MAX}_M\)
+ be as defined in Jumbling.
+
+ - Parse and strip the Binary HRP from the start of the Unified Raw Encoding
+ \(\mathtt{R}\)
+ , as follows:
+
+ - If
+ \(\mathsf{length}(\mathtt{R}) = 0\!\)
+ , reject.
+ - Let
+ \(\mathtt{hrp\_len} = \mathtt{R}[0]\!\)
+ . If
+ \(\mathtt{hrp\_len} > 16\)
+ or
+ \(\mathtt{hrp\_len} > \mathsf{length}(\mathtt{R}) - 1\)
+ or
+ \(\mathsf{length}(\mathtt{R}) - 1 - \mathtt{hrp\_len} > \ell^\mathsf{MAX}_M - 16\!\)
+ , reject.
+ - Let
+ \(\mathtt{hrp} = \mathtt{R}[1\;..\!=\mathtt{hrp\_len}]\!\)
+ .
+ - Let
+ \(\mathtt{raw\_items} = \mathtt{R}[1 + \mathtt{hrp\_len}\;..\!=\mathsf{length}(\mathtt{R}) - 1]\)
+ (i.e. the remainder of the Unified Raw Encoding after the Binary HRP).
+
+
+ - Let
+ \(\mathtt{padded\_hrp}\)
+ be
+ \(\mathtt{hrp}\)
+ padded to 16 bytes with zero bytes.
+ - Apply the
+ \(\mathsf{F4Jumble}\)
+ algorithm described in Jumbling to
+ \(\mathtt{raw\_items} \,||\, \mathtt{padded\_hrp}\!\)
+ .
+ - Encode the output with Bech32m , ignoring any length restrictions.
+
+ Any equivalent procedure MAY be used, for example, a Producer MAY construct
+ \(\mathtt{padded\_hrp}\)
+ and
+ \(\mathtt{raw\_items}\)
+ directly rather than explicitly obtaining them from a Unified Raw Encoding.
+ The check that
+ \(\mathsf{length}(\mathtt{R}) - 1 - \mathtt{hrp\_len} > \ell^\mathsf{MAX}_M - 16\)
+ in step 1 ensures that
+ \(\mathtt{raw\_items} \,||\, \mathtt{padded\_hrp}\)
+ never exceeds the
+ \(\mathsf{F4Jumble}\)
+ input size limitation in step 3.
+ Bech32m is chosen over Bech32 in order to better handle variable-length inputs.
+ To decode a Unified String Encoding, a Consumer MUST use the following procedure:
+
+ - Decode using Bech32m, rejecting any address with an incorrect checksum. This yields HRP and data fields. If the HRP is not recognised or not supported (for example, a Testnet HRP for a Consumer that only supports Mainnet), reject.
+ - Let
+ \(\mathtt{expected\_padded\_hrp}\)
+ be the US-ASCII-encoded HRP, padded to 16 bytes with zero bytes.
+ - Apply
+ \(\mathsf{F4Jumble}^{-1}\)
+ to the payload (this can also reject if the input is not in the correct range of lengths).
+ - If the output ends in
+ \(\mathtt{expected\_padded\_hrp}\)
+ , remove these 16 bytes; otherwise reject.
+ - Parse the result as
+ \(\mathtt{raw\_items}\)
+ described above, rejecting the entire Unified Address if it does not parse correctly.
+
+ The Human-Readable Parts of Unified Addresses and Unified Viewing Keys are defined as given in Encoding Prefixes.
+
Requirements for both Unified Addresses and Unified Viewing Keys
- A Unified Address or Unified Viewing Key MUST contain at least one shielded Item (Typecodes
@@ -292,13 +407,13 @@
\(\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.)
+ (Although existing Receiver Items and Viewing Key Items 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 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.
+ - For Transparent Addresses, the Receiver Item 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.
- Consumers MUST ignore constituent Items 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 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 any constituent Item that the Consumer recognizes 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.
@@ -355,7 +470,7 @@
\(\mathsf{ovk}\)
components from the transparent FVK
\((\mathsf{c}, \mathsf{pk})\)
- (described in Encoding of Unified Full/Incoming Viewing Keys) as follows:
+ (described in Raw Encoding of Unified Full/Incoming Viewing Keys) as follows:
- Let
\(I_\mathsf{ovk} = \mathsf{PRF^{expand}}_{\mathsf{LEOS2BSP}_{256}(\mathsf{c})}\big([\mathtt{0xd0}] \,||\, \mathsf{ser_P}(\mathsf{pk})\big)\)
@@ -419,7 +534,7 @@
However, the specification of which outgoing viewing key should be used is left somewhat open in and ; in particular, it was unclear whether transfers should be considered as being sent from an address, or from a ZIP 32 account . The adoption of multiple shielded protocols that support outgoing viewing keys (i.e. Sapling and Orchard) further complicates this question, since from NU5 activation, nothing at the consensus level prevents a wallet from spending both Sapling and Orchard notes in the same transaction. (Recommendations about wallet usage of multiple pools will be given in ZIP 315 .)
Here we refine the protocol specification in order to allow more precise determination of viewing authority for UFVKs.
A Sender will attempt to determine a "sending Account" for each transfer. The preferred approach is for the API used to perform a transfer to directly specify a sending Account. Otherwise, if the Sender can ascertain that all funds used in the transfer are from addresses associated with some Account, then it SHOULD treat that as the sending Account. If not, then the sending Account is undetermined.
- The Sender also determines a "preferred sending protocol" —one of "transparent", "Sapling", or "Orchard"— corresponding to the most preferred Receiver Type (as given in Encoding of Unified Addresses) of any funds sent in the transaction.
+ The Sender also determines a "preferred sending protocol" —one of "transparent", "Sapling", or "Orchard"— corresponding to the most preferred Receiver Type (as given in Raw Encoding of Unified Addresses) of any funds sent in the transaction.
If the sending Account has been determined, then the Sender SHOULD use the external or internal
\(\mathsf{ovk}\)
(according to the type of transfer), as specified by the preferred sending protocol, of the full viewing key for that Account (i.e. at the ZIP 32 Account level).
@@ -715,6 +830,15 @@
LIONESS is a similarly structured 4-round unbalanced Feistel cipher.
+ QR Encodings of Unified Addresses and Unified Viewing Keys
+ The Unified QR Encoding of a UA or UVK is as specified in ; that is, the QR code representation of its Unified String Encoding converted to uppercase, using the Alphanumeric mode specified in sections 7.3.4 and 7.4.4 of .
+ A Consumer MAY support parsing multiple kinds of address and/or viewing key from a QR code, in which case it SHOULD use the HRP to provisionally recognize (subject to further validation) potential address or viewing key types.
+ When a Consumer recognizes the content of a QR code as a potential Unified String Encoding, it SHOULD NOT present the resulting content to the user as representing an address, without first checking that it is a valid Unified String Encoding by attempting to decode it.
+ A Producer MUST NOT generate a QR Encoding directly from a Unified Raw Encoding (using the QR "Byte mode" defined in section 7.3.5, or otherwise).
+ Rationale for not using Byte mode
+ A QR code using the Unified Raw Encoding in Byte mode could be slightly smaller, however we believe this choice would be likely to cause interoperability problems. It also would not satisfy the requirement that the Unified Raw Encoding not be shown to users, since it is common for software that supports QR codes to try to decode the content and present it as a string. (Clause 6.1 b) 3) of specifies that the default interpretation of byte data is as an ISO-8859-1 text string.)
+
+