From 8734965d0ccb28bf8468c82358f3fd34f0c734d3 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 19 Jan 2022 19:11:28 +0000 Subject: [PATCH] ZIPs 32 and 316: Regenerate HTML. Signed-off-by: Daira Hopwood --- zip-0032.html | 271 ++++++++++++++++++++++++++++++++++++++------------ zip-0316.html | 247 ++++++++++++++++++++++++++++++++++----------- 2 files changed, 397 insertions(+), 121 deletions(-) diff --git a/zip-0032.html b/zip-0032.html index e8ff090b..d02a8a27 100644 --- a/zip-0032.html +++ b/zip-0032.html @@ -11,7 +11,10 @@ Title: Shielded Hierarchical Deterministic Wallets Owners: Jack Grigg <str4d@electriccoin.co> Daira Hopwood <daira@electriccoin.co> -Credits: Pieter Wuille +Credits: Sean Bowe + Kris Nuttycombe + Ying Tong Lai + Pieter Wuille Marek Palatinus Pavol Rusnak Status: Final @@ -23,9 +26,9 @@ License: MIT

Terminology

The key words "MUST", "MUST NOT", and "MAY" in this document are to be interpreted as described in RFC 2119. 1

-

"Jubjub" refers to the elliptic curve defined in 13.

+

"Jubjub" refers to the elliptic curve defined in 15.

A "chain code" is a cryptovalue that is needed, in addition to a spending key, in order to derive descendant keys and addresses of that key.

-

The terms "Testnet" and "Mainnet" are to be interpreted as described in section 3.12 of the Zcash Protocol Specification 9.

+

The terms "Testnet" and "Mainnet" are to be interpreted as described in section 3.12 of the Zcash Protocol Specification 10.

Abstract

This proposal defines a mechanism for extending hierarchical deterministic wallets, as decribed in BIP 32 2, to support Zcash's shielded addresses.

@@ -49,7 +52,7 @@ License: MIT

At present, no such equivalent exists for Zcash's shielded addresses. This is of particular concern for hardware wallets; all currently-marketed devices only store a seed internally, and have trained their users to only backup that seed. Given that the Sapling upgrade will make it feasible to use hardware wallets with shielded addresses, it is desirable to have a standard mechanism for deriving them.

Conventions

-

Most of the notation and functions used in this ZIP are defined in the Zcash protocol specification 8. They are reproduced here for convenience:

+

Most of the notation and functions used in this ZIP are defined in the Zcash protocol specification 9. They are reproduced here for convenience:

  • \(\mathsf{truncate}_k(S)\) @@ -101,7 +104,7 @@ License: MIT \(\mathsf{repr}_\mathbb{J}(P)\) is the representation of the Jubjub elliptic curve point \(P\) - as a bit sequence, defined in 13.
    • + as a bit sequence, defined in 15.
  • \(\mathsf{BLAKE2b}\text{-}\mathsf{256}(p, x)\) refers to unkeyed BLAKE2b-256 in sequential mode, with an output digest length of 32 bytes, 16-byte personalization string @@ -125,18 +128,25 @@ License: MIT \(r_\mathbb{J}\) is the order of the Jubjub large prime subgroup.
  • - \(\mathsf{ToScalar}(x) :=\) + \(r_\mathbb{P}\) + is the order of the Pallas curve.
    • +
  • + \(\mathsf{ToScalar^{Sapling}}(x) :=\) \(\mathsf{LEOS2IP}_{512}(x) \pmod{r_\mathbb{J}}\) .
  • - \(\mathsf{DiversifyHash}(d)\) + \(\mathsf{ToScalar^{Orchard}}(x) :=\) + \(\mathsf{LEOS2IP}_{512}(x) \pmod{r_\mathbb{P}}\) + .
    • +
  • + \(\mathsf{DiversifyHash^{Sapling}}(d)\) maps a diversifier \(d\) to a base point on the Jubjub elliptic curve, or to \(\bot\) - if the diversifier is invalid. It is instantiated in 11.
    • + if the diversifier is invalid. It is instantiated in 13.
-

The following algorithm standardized in 20 is used:

+

The following algorithm standardized in 22 is used:

  • \(\mathsf{FF1}\text{-}\mathsf{AES256.Encrypt}(key, tweak, x)\) @@ -264,13 +274,13 @@ License: MIT \(\mathsf{nsk}_m\) , and \(\mathsf{ovk}_m\) - via the standard Sapling derivation 10: + via the standard Sapling derivation 11:
    • - \(\mathsf{ask}_m = \mathsf{ToScalar}(\mathsf{PRF^{expand}}(\mathsf{sk}_m, [\texttt{0x00}]))\) + \(\mathsf{ask}_m = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(\mathsf{sk}_m, [\texttt{0x00}]))\)
    • - \(\mathsf{nsk}_m = \mathsf{ToScalar}(\mathsf{PRF^{expand}}(\mathsf{sk}_m, [\texttt{0x01}]))\) + \(\mathsf{nsk}_m = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(\mathsf{sk}_m, [\texttt{0x01}]))\)
    • \(\mathsf{ovk}_m = \mathsf{truncate}_{32}(\mathsf{PRF^{expand}}(\mathsf{sk}_m, [\texttt{0x02}]))\) @@ -320,7 +330,7 @@ License: MIT \((\mathsf{nk}_{par}, \mathsf{ak}_{par}, \mathsf{ovk}_{par})\) is the full viewing key derived from \((\mathsf{ask}_{par}, \mathsf{nsk}_{par}, \mathsf{ovk}_{par})\) - as described in 10.
      • + as described in 11.
  • Split @@ -331,10 +341,10 @@ License: MIT \(I_R\) .
  • Let - \(I_\mathsf{ask} = \mathsf{ToScalar}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x13}]))\) + \(I_\mathsf{ask} = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x13}]))\) .
  • Let - \(I_\mathsf{nsk} = \mathsf{ToScalar}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x14}]))\) + \(I_\mathsf{nsk} = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x14}]))\) .
  • Return:
      @@ -361,10 +371,10 @@ License: MIT

Deriving a child extended full viewing key

Let - \(\mathcal{G}\) - be as defined in 12 and let - \(\mathcal{H}\) - be as defined in 10.

+ \(\mathcal{G}^\mathsf{Sapling}\) + be as defined in 14 and let + \(\mathcal{H}^\mathsf{Sapling}\) + be as defined in 11.

\(\mathsf{CDKfvk}((\mathsf{ak}_{par}, \mathsf{nk}_{par}, \mathsf{ovk}_{par}, \mathsf{dk}_{par}, \mathsf{c}_{par}), i)\) \(\rightarrow (\mathsf{ak}_{i}, \mathsf{nk}_{i}, \mathsf{ovk}_{i}, \mathsf{dk}_{i}, \mathsf{c}_{i})\) @@ -390,18 +400,18 @@ License: MIT \(I_R\) .

  • Let - \(I_\mathsf{ask} = \mathsf{ToScalar}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x13}]))\) + \(I_\mathsf{ask} = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x13}]))\) .
  • Let - \(I_\mathsf{nsk} = \mathsf{ToScalar}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x14}]))\) + \(I_\mathsf{nsk} = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x14}]))\) .
  • Return:
    • - \(\mathsf{ak}_i = [I_\mathsf{ask}]\,\mathcal{G} + \mathsf{ak}_{par}\) + \(\mathsf{ak}_i = [I_\mathsf{ask}]\,\mathcal{G}^\mathsf{Sapling} + \mathsf{ak}_{par}\)
    • - \(\mathsf{nk}_i = [I_\mathsf{nsk}]\,\mathcal{H} + \mathsf{nk}_{par}\) + \(\mathsf{nk}_i = [I_\mathsf{nsk}]\,\mathcal{H}^\mathsf{Sapling} + \mathsf{nk}_{par}\)
    • \(\mathsf{ovk}_i = \mathsf{truncate}_{32}(\mathsf{PRF^{expand}}(I_L, [\texttt{0x15}]\) @@ -419,6 +429,91 @@ License: MIT
    • +

    Sapling internal key derivation

    +

    The above derivation mechanisms produce external addresses suitable for giving out to senders. We also want to be able to produce another address derived from a given external address, for use by wallets for internal operations such as change and auto-shielding. Unlike BIP 44 that allows deriving a stream of external and internal addresses in the same hierarchical derivation tree 5, for any external full viewing key we only need to be able to derive a single internal full viewing key that has viewing authority for just internal transfers. We also need to be able to derive the corresponding internal spending key if we have the external spending key.

    +

    Deriving a Sapling internal spending key

    +

    Let + \((\mathsf{ask}, \mathsf{nsk}, \mathsf{ovk}, \mathsf{dk})\) + be the external spending key.

    +
      +
    • Derive the corresponding + \(\mathsf{ak}\) + and + \(\mathsf{nk}\) + as specified in 11.
      • +
    • Let + \(I = \textsf{BLAKE2b-256}(\texttt{"Zcash_SaplingInt"}, \mathsf{EncodeExtFVKParts}(\mathsf{ak}, \mathsf{nk}, \mathsf{ovk}, \mathsf{dk}))\) + .
      • +
    • Let + \(I_\mathsf{nsk} = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(I, [\mathtt{0x17}]))\) + .
      • +
    • Let + \(R = \mathsf{PRF^{expand}}(I, [\mathtt{0x18}])\) + .
      • +
    • Let + \(\mathsf{nsk_{internal}} = (I_\mathsf{nsk} + \mathsf{nsk}) \pmod{r_\mathbb{J}}\) + .
      • +
    • Split + \(R\) + into two 32-byte sequences, + \(\mathsf{dk_{internal}}\) + and + \(\mathsf{ovk_{internal}}\) + .
      • +
    • Return the internal spending key as + \((\mathsf{ask}, \mathsf{nsk_{internal}}, \mathsf{ovk_{internal}}, \mathsf{dk_{internal}})\) + .
      • +
    +
    +

    Deriving a Sapling internal full viewing key

    +

    Let + \(\mathcal{H}^\mathsf{Sapling}\) + be as defined in 11.

    +

    Let + \((\mathsf{ak}, \mathsf{nk}, \mathsf{ovk}, \mathsf{dk})\) + be the external full viewing key.

    +
      +
    • Let + \(I = \textsf{BLAKE2b-256}(\texttt{"Zcash_SaplingInt"}, \mathsf{EncodeExtFVKParts}(\mathsf{ak}, \mathsf{nk}, \mathsf{ovk}, \mathsf{dk}))\) + .
      • +
    • Let + \(I_\mathsf{nsk} = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(I, [\mathtt{0x17}]))\) + .
      • +
    • Let + \(R = \mathsf{PRF^{expand}}(I, [\mathtt{0x18}])\) + .
      • +
    • Let + \(\mathsf{nk_{internal}} = [I_\mathsf{nsk}] \mathcal{H}^\mathsf{Sapling} + \mathsf{nk}\) + .
      • +
    • Split + \(R\) + into two 32-byte sequences, + \(\mathsf{dk_{internal}}\) + and + \(\mathsf{ovk_{internal}}\) + .
      • +
    • Return the internal full viewing key as + \((\mathsf{ak}, \mathsf{nk_{internal}}, \mathsf{ovk_{internal}}, \mathsf{dk_{internal}})\) + .
      • +
    +

    This design uses the same technique as non-hardened derivation to obtain a full viewing key with the same spend authority (the private key corresponding to + \(\mathsf{ak}\) + ) as the original, but viewing authority only for internal transfers.

    +

    The values of + \(I\) + , + \(I_\mathsf{nsk}\) + , and + \(R\) + are the same between deriving a full viewing key, and deriving the corresponding spending key. Both of these derivations are shown in the following diagram:

    +
    + +
    Diagram of Sapling internal key derivation
    +
    +

    (For simplicity, the proof authorizing key is not shown.)

    +

    This method of deriving internal keys is applied to external keys that are children of the Account level. It was implemented in zcashd as part of support for ZIP 316 8.

    +
    +

    Sapling diversifier derivation

    The 88-bit diversifiers for a Sapling extended key are derived from its diversifier key \(\mathsf{dk}\) @@ -436,7 +531,7 @@ License: MIT

    A valid diversifier \(d_j\) is one for which - \(\mathsf{DiversifyHash}(d_j) \neq \bot\) + \(\mathsf{DiversifyHash^{Sapling}}(d_j) \neq \bot\) . For a given \(\mathsf{dk}\) , approximately half of the possible values of @@ -466,7 +561,7 @@ License: MIT \(\mathsf{EncodeASK}(\mathsf{a_{sk}})\) be the 32-byte encoding of \(\mathsf{a_{sk}}\) - in the raw encoding of a Sprout spending key (excluding lead bytes) as specified in 15.

    + in the raw encoding of a Sprout spending key (excluding lead bytes) as specified in 17.

    Let \(\mathsf{DecodeASK}(ASK)\) be the result of clearing the 4 most significant bits of the first byte of @@ -538,6 +633,7 @@ License: MIT \(\mathsf{c}_i\) . +

    There is no support for internal key derivation for Sprout.

    Specification: Orchard key derivation

    @@ -618,6 +714,41 @@ License: MIT .
    +

    Orchard internal key derivation

    +

    As in the case of Sapling, for a given external address, we want to produce another address for use by wallets for internal operations such as change and auto-shielding. That is, for any external full viewing key we need to be able to derive a single internal full viewing key that has viewing authority for just internal transfers. We also need to be able to derive the corresponding internal spending key if we have the external spending key.

    +

    Let + \(\mathsf{ask}\) + be the spend authorizing key if available, and let + \((\mathsf{ak}, \mathsf{nk}, \mathsf{rivk})\) + be the corresponding external full viewing key, obtained as specified in 12.

    +
      +
    • Let + \(K = \mathsf{I2LEBSP}_{256}(\mathsf{rivk})\) + .
      • +
    • Let + \(\mathsf{rivk_{internal}} = \mathsf{ToScalar^{Orchard}}(\mathsf{PRF^{expand}}(K, [\mathtt{0x83}] \,||\, \mathsf{I2LEOSP_{256}}(\mathsf{ak}) \,||\, \mathsf{I2LEOSP_{256}}(\mathsf{nk}))\) + .
      • +
    +

    Then the expanded internal spending key is + \((\mathsf{ask}, \mathsf{nk}, \mathsf{rivk_{internal}})\) + , and the internal full viewing key is + \((\mathsf{ak}, \mathsf{nk}, \mathsf{rivk_{internal}})\) + .

    +

    Unlike Sapling internal key derivation, we do not base this internal key derivation procedure on non-hardened derivation, which is not defined for Orchard. We can obtain the desired separation of viewing authority by modifying only the + \(\mathsf{rivk_{internal}}\) + field relative to the external full viewing key, which results in different + \(\mathsf{dk_{internal}}\) + , + \(\mathsf{ivk_{internal}}\) + and + \(\mathsf{ovk_{internal}}\) + fields being derived, as specified in 12 and shown in the following diagram:

    +
    + +
    Diagram of Orchard internal key derivation, also showing derivation from the parent extended spending key
    +
    +

    This method of deriving internal keys is applied to external keys that are children of the Account level. It was implemented in zcashd as part of support for ZIP 316 8.

    +

    Orchard diversifier derivation

    As with Sapling, we define a mechanism for deterministically deriving a sequence of diversifiers, without leaking how many diversified addresses have already been generated for an account. Unlike Sapling, we do so by deriving a diversifier key directly from the full viewing key, instead of as part of the extended spending key. This means that the full viewing key provides the capability to determine the position of a diversifier within the sequence, which matches the capabilities of a Sapling extended full viewing key but simplifies the key structure.

    Given an Orchard extended spending key @@ -630,12 +761,12 @@ License: MIT \(\mathsf{sk}_i\) .

  • Let - \(\mathsf{K} = \mathsf{I2LEBSP}_{256}(\mathsf{rivk})\) + \(K = \mathsf{I2LEBSP}_{256}(\mathsf{rivk})\) and let - \(\mathsf{B} = \mathsf{repr}_{\mathbb{P}}(\mathsf{ak})\,||\,\mathsf{I2LEBSP}_{256}(\mathsf{nk})\) + \(B = \mathsf{repr}_{\mathbb{P}}(\mathsf{ak})\,||\,\mathsf{I2LEBSP}_{256}(\mathsf{nk})\) .
  • - \(\mathsf{dk}_i = \mathsf{truncate}_{32}(\mathsf{PRF^{expand}}(\mathsf{K}, [\texttt{0x82}]\,||\,\mathsf{LEBS2OSP}_{512}(\mathsf{B})))\) + \(\mathsf{dk}_i = \mathsf{truncate}_{32}(\mathsf{PRF^{expand}}(K, [\texttt{0x82}]\,||\,\mathsf{LEBS2OSP}_{512}(B)))\) .
  • Let \(j\) @@ -657,7 +788,7 @@ License: MIT

    • Specification: Wallet usage

    -

    Existing Zcash-supporting HD wallets all use BIP 44 5 to organize their derived keys. In order to more easily mesh with existing user experiences, we broadly follow BIP 44's design here. However, we have altered the design where it makes sense to leverage features of shielded addresses.

    +

    Existing Zcash-supporting HD wallets all use BIP 44 5 to organize their derived keys. In order to more easily mesh with existing user experiences, we broadly follow BIP 44's design here. However, we have altered the design where it makes sense to leverage features of shielded addresses.

    Key path levels

    Sprout, Sapling, and Orchard key paths have the following three path levels at the top, all of which use hardened derivation:

      @@ -670,7 +801,7 @@ License: MIT ) following the BIP 43 recommendation. It indicates that the subtree of this node is used according to this specification.
    • \(coin\_type\) - : a constant identifying the cryptocurrency that this subtree's keys are used with. For compatibility with existing BIP 44 implementations, we use the same constants as defined in SLIP 44 6. Note that in keeping with that document, all cryptocurrency testnets share + : a constant identifying the cryptocurrency that this subtree's keys are used with. For compatibility with existing BIP 44 implementations, we use the same constants as defined in SLIP 44 6. Note that in keeping with that document, all cryptocurrency testnets share \(coin\_type\) index \(1\) @@ -679,7 +810,7 @@ License: MIT \(account\) : numbered from index \(0\) - in sequentially increasing manner. Defined as in BIP 44 5.
      • + in sequentially increasing manner. Defined as in BIP 44 5.

    Unlike BIP 44, none of the shielded key paths have a \(change\) @@ -701,7 +832,7 @@ License: MIT payment addresses, because each diversifier has around a 50% chance of being invalid.

    If in certain circumstances a wallet needs to derive independent spend authorities within a single account, they MAY additionally support a non-hardened \(address\_index\) - path level as in 5:

    + path level as in 5: