From 00efeba93c3eeb29c5980e70380b66e4d75f4048 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 18 Feb 2025 11:09:26 +0000 Subject: [PATCH 1/8] Initial ZIP draft for Account Metadata Keys --- zips/draft-str4d-account-metadata-keys.md | 198 ++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 zips/draft-str4d-account-metadata-keys.md diff --git a/zips/draft-str4d-account-metadata-keys.md b/zips/draft-str4d-account-metadata-keys.md new file mode 100644 index 000000000..069a412b5 --- /dev/null +++ b/zips/draft-str4d-account-metadata-keys.md @@ -0,0 +1,198 @@ + + ZIP: Unassigned + Title: Account Metadata Keys + Owners: Jack Grigg + Daira-Emma Hopwood + Kris Nuttycombe + Status: Draft + Category: Standards / Wallet + Created: 2025-02-18 + License: MIT + + +# Terminology + +The key words "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. + + +# Abstract + +This ZIP specifies the key tree for Account Metadata Keys. These are derived +from the same seed as a ZIP 32 [^zip-0032] account, and can be used by wallets +to derive encryption keys for local / off-chain metadata. + + +# Motivation + +A wallet's main data source is the Zcash chain: from this it can detect notes +received by an account, determine whether those notes are spent, build witnesses +for spending, recover on-chain memo data, and so on. However, wallets also +generate significant quantities of off-chain metadata as they are used, such as: + +- Local notes about transactions in the wallet. +- Mappings from Zcash addresses to user-meaningful recipient names. +- The exchange rate from ZEC to another currency that was used to determine how + much ZEC to send in a payment. + +This metadata is valuable to users, and highly desirable to ensure is backed up. +If the user's device is wiped or lost and the user recovers their wallet from a +backed-up mnemonic phrase, they will lose all of this metadata if it is not +stored somewhere. + +For other kinds of phone data, it is expected by users that their phone's normal +backup storage will have saved (most of) their data, such that access to e.g. +their Apple or Google account will be sufficient for data recovery. However, +metadata like mappings from Zcash addresses to recipient names can be +particularly sensitive, meaning that users may not want it to be backed up +unencrypted in their phone's normal backup storage. Similarly, the inability to +alter on-chain data means that permanently storing metadata in transaction memo +fields may also not be an option. + +Additionally, it is currently the case that users only need to back up a single +secret (a mnemonic seed phrase), once, in order to recover all information for +accounts derived from that secret. If metadata were encrypted using independent +key material, these keys would also need to be backed up, leading to fragility +of wallet restoration. + + +# Requirements + +- The user should not need to update their existing backups of secret material. +- It should be possible to store metadata about accounts for which we don't + control spend authority (i.e. imported UFVKs). +- The key tree must be future-extensible. + + +# Specification + +## Metadata key tree + +This ZIP registers the following ZIP 32 Registered Key Derivation [^zip-0032-rkd] +tree: + +- $\mathsf{ContextString} = \texttt{“MetadataKeys”}$ +- ZIP number: TBD + +The tree has the following general structure, specified in more detail below: + +- $m_{\mathsf{metadata}}$: Metadata Key tree + - $m_{\mathsf{metadata}} / TBD' / \mathsf{coinType}' / \mathsf{account}'$ - Account Metadata Key + - $\ldots / 0'$ - Account-level Inherent Metadata Key + - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) + - $\ldots / \texttt{0x7FFFFFFFF}' \# \texttt{PrivateSubject}$ - Private-use Inherent Metadata Key + - $\ldots / 1'$ - Account-level External Metadata Key + - $\ldots / 0' \# \langle FVKTypedItem \rangle$ - Imported UFVK Metadata Key + - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) + - $\ldots / \texttt{0x7FFFFFFFF}' \# \texttt{PrivateSubject}$ - Private-use External Metadata Key + - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) + - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) + +Non-leaf keys in the key tree MUST NOT be used directly to encrypt metadata. +Encryption keys are leaves in this key tree. The sole exception to this is +private-use keys (for which part of their key derivation is outside the scope of +this specification): encryption keys MAY be derived from the private-use key +leaves. + +### Account Metadata Key + +The Account Metadata Key is the root of a subtree that corresponds to a ZIP 32 +account represented elsewhere in the overall tree. It is derived from the seed +$\mathsf{S}$ as: + +$\mathsf{AccountMetadataKey} = \mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{RegKD}(\texttt{“MetadataKeys”}, \mathsf{S}, \mathsf{ZipNumber}), \mathsf{coinType}, [\,]), \mathsf{account}, [\,])$ + +or, in path notation: + +``` +m_metadata / TBD' / coin_type' / account' +``` + +### Inherent metadata keys + +The Account-level Inherent Metadata Key's subtree contains keys used for +metadata associated with the Account Metadata Key's corresponding account. The +key is derived as: + +$\mathsf{CKDreg}(\mathsf{AccountMetadataKey}, 0, [\,])$ + +### External metadata keys + +The Account-level External Metadata Key's subtree contains keys used for +metadata associated with imported UFVKs. Unlike the inherent metadata keys which +can leverage the inherent domain separation provided by the account index, here +domain separation between metadata keys is provided by the UFVKs themselves. + +As UFVKs may in general change over time (due to the inclusion of new +higher-preference FVK items, or removal of older deprecated FVK items), there is +no guarantee that the exact same set of FVK items will be present at both backup +creation time and recovery time. Instead, the most-preferred FVK item within a +UFVK is used as the domain separator, and the Imported UFVK Metadata Key is +derived as: + +$\mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{AccountMetadataKey}, 1, [\,]), 0, \langle FVKTypedItem \rangle)$ + +where $\langle FVKTypedItem \rangle$ is the encoding of the most preferred FVK +item within the ZIP 316 raw encoding of a UFVK. [^zip-0316] + +Usage of the Imported UFVK Metadata Key trees SHOULD follow ZIP 316 preference +order: [^zip-0316] + +- For encryption-like usage, the key tree corresponding to the most preferred + FVK item within a UFVK SHOULD be used. +- For decryption-like usage, each key tree SHOULD be tried in preference order + until metadata can be recovered. If metadata is recovered via an FVK item that + is not the most preferred, wallets SHOULD update their metadata backups by + re-encrypting the metadata using the key tree corresponding to most preferred + FVK item. + +## Standardised metadata protocols + +The following metadata protocols have been standardised: + +- None at time of writing. + +The remaining range of child indices from 0 to $\texttt{0x7FFFFFFFE}$ inclusive +are reserved for future updates to this ZIP. Wallet developers can propose new +standardised metadata protocols by writing a 2000-series ZIP that specifies the +protocol as an update to this ZIP. + +## Private use metadata keys + +In some contexts there is a need for deriving ad-hoc key trees for private use +by wallets, without ecosystem coordination and without any kind of compatibility +guarantees. This ZIP reserves child index $\texttt{0x7FFFFFFFF}$ (the maximum +valid hardened child index) within its key tree for this purpose. + +- Let $K$ be either the Account-level Inherent Metadata Key, or an Imported UFVK + Metadata Key. +- Let $\mathsf{PrivateSubject}$ be a globally-unique non-empty sequence of at + most 252 bytes that identifies the desired private use context. +- Return $\mathsf{CKDreg}(K, \texttt{0x7FFFFFFFF}, \mathsf{PrivateSubject})$ + +:::warning +It is the responsibility of wallet developers to ensure that they do not use +colliding $\mathsf{PrivateSubject}$ values, and to analyse their private use for +any security risks related to potential cross-protocol attacks (in the event that +two wallet developers happen to select a colliding $\mathsf{PrivateSubject}$). +Wallet developers that are unwilling to accept these risks SHOULD propose new +standardised metadata protocols instead, to benefit from ecosystem coordination +and review. +::: + + +# Reference implementation + +- https://github.com/Electric-Coin-Company/zcash-android-wallet-sdk/pull/1686 + + +# References + +[^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"](https://www.rfc-editor.org/info/bcp14) + +[^zip-0032]: [ZIP 32: Shielded Hierarchical Deterministic Wallets](zip-0032.rst) + +[^zip-0032-rkd]: [ZIP 32: Shielded Hierarchical Deterministic Wallets, Section: Registered key derivation](zip-0032.rst#specification-registered-key-derivation) + +[^zip-0316]: [ZIP 316: Unified Addresses and Unified Viewing Keys](zip-0316.rst) From deb8333827fe7c280446299c75d12d40072884f3 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Tue, 18 Feb 2025 21:43:33 +0000 Subject: [PATCH 2/8] Apply copy-editing suggestions from review --- zips/draft-str4d-account-metadata-keys.md | 38 +++++++++++------------ 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/zips/draft-str4d-account-metadata-keys.md b/zips/draft-str4d-account-metadata-keys.md index 069a412b5..0c23c191b 100644 --- a/zips/draft-str4d-account-metadata-keys.md +++ b/zips/draft-str4d-account-metadata-keys.md @@ -31,21 +31,21 @@ received by an account, determine whether those notes are spent, build witnesses for spending, recover on-chain memo data, and so on. However, wallets also generate significant quantities of off-chain metadata as they are used, such as: -- Local notes about transactions in the wallet. -- Mappings from Zcash addresses to user-meaningful recipient names. +- Local annotations about transactions in the wallet. +- Mappings between Zcash addresses and user-meaningful recipient names. - The exchange rate from ZEC to another currency that was used to determine how much ZEC to send in a payment. -This metadata is valuable to users, and highly desirable to ensure is backed up. +This metadata is valuable to users, and highly desirable to ensure to be backed up. If the user's device is wiped or lost and the user recovers their wallet from a backed-up mnemonic phrase, they will lose all of this metadata if it is not stored somewhere. For other kinds of phone data, it is expected by users that their phone's normal backup storage will have saved (most of) their data, such that access to e.g. -their Apple or Google account will be sufficient for data recovery. However, -metadata like mappings from Zcash addresses to recipient names can be -particularly sensitive, meaning that users may not want it to be backed up +the associated Apple or Google account will be sufficient for data recovery. +However, metadata such as mappings between Zcash addresses and recipient names can +be particularly sensitive, meaning that users may not want these to be backed up unencrypted in their phone's normal backup storage. Similarly, the inability to alter on-chain data means that permanently storing metadata in transaction memo fields may also not be an option. @@ -81,11 +81,11 @@ The tree has the following general structure, specified in more detail below: - $m_{\mathsf{metadata}} / TBD' / \mathsf{coinType}' / \mathsf{account}'$ - Account Metadata Key - $\ldots / 0'$ - Account-level Inherent Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - - $\ldots / \texttt{0x7FFFFFFFF}' \# \texttt{PrivateSubject}$ - Private-use Inherent Metadata Key + - $\ldots / \mathtt{0x7FFFFFFFF}' \# \mathsf{PrivateSubject}$ - Private-use Inherent Metadata Key - $\ldots / 1'$ - Account-level External Metadata Key - - $\ldots / 0' \# \langle FVKTypedItem \rangle$ - Imported UFVK Metadata Key + - $\ldots / 0' \# \mathsf{FVKTypedItem}$ - Imported UFVK Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - - $\ldots / \texttt{0x7FFFFFFFF}' \# \texttt{PrivateSubject}$ - Private-use External Metadata Key + - $\ldots / \mathtt{0x7FFFFFFFF}' \# \mathsf{PrivateSubject}$ - Private-use External Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) @@ -127,13 +127,13 @@ domain separation between metadata keys is provided by the UFVKs themselves. As UFVKs may in general change over time (due to the inclusion of new higher-preference FVK items, or removal of older deprecated FVK items), there is no guarantee that the exact same set of FVK items will be present at both backup -creation time and recovery time. Instead, the most-preferred FVK item within a +creation time and recovery time. Instead, the most preferred FVK item within a UFVK is used as the domain separator, and the Imported UFVK Metadata Key is derived as: -$\mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{AccountMetadataKey}, 1, [\,]), 0, \langle FVKTypedItem \rangle)$ +$\mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{AccountMetadataKey}, 1, [\,]), 0, \mathsf{FVKTypedItem})$ -where $\langle FVKTypedItem \rangle$ is the encoding of the most preferred FVK +where $\mathsf{FVKTypedItem}$ is the encoding of the most preferred FVK item within the ZIP 316 raw encoding of a UFVK. [^zip-0316] Usage of the Imported UFVK Metadata Key trees SHOULD follow ZIP 316 preference @@ -144,8 +144,8 @@ order: [^zip-0316] - For decryption-like usage, each key tree SHOULD be tried in preference order until metadata can be recovered. If metadata is recovered via an FVK item that is not the most preferred, wallets SHOULD update their metadata backups by - re-encrypting the metadata using the key tree corresponding to most preferred - FVK item. + re-encrypting the metadata using the key tree corresponding to the most + preferred FVK item. ## Standardised metadata protocols @@ -158,18 +158,18 @@ are reserved for future updates to this ZIP. Wallet developers can propose new standardised metadata protocols by writing a 2000-series ZIP that specifies the protocol as an update to this ZIP. -## Private use metadata keys +## Private-use metadata keys In some contexts there is a need for deriving ad-hoc key trees for private use by wallets, without ecosystem coordination and without any kind of compatibility -guarantees. This ZIP reserves child index $\texttt{0x7FFFFFFFF}$ (the maximum +guarantees. This ZIP reserves child index $\mathtt{0x7FFFFFFFF}$ (the maximum valid hardened child index) within its key tree for this purpose. - Let $K$ be either the Account-level Inherent Metadata Key, or an Imported UFVK Metadata Key. -- Let $\mathsf{PrivateSubject}$ be a globally-unique non-empty sequence of at - most 252 bytes that identifies the desired private use context. -- Return $\mathsf{CKDreg}(K, \texttt{0x7FFFFFFFF}, \mathsf{PrivateSubject})$ +- Let $\mathsf{PrivateSubject}$ be a globally unique non-empty sequence of at + most 252 bytes that identifies the desired private-use context. +- Return $\mathsf{CKDreg}(K, \mathtt{0x7FFFFFFFF}, \mathsf{PrivateSubject})$ :::warning It is the responsibility of wallet developers to ensure that they do not use From 0b665807e2ae733dd90f3cb505d397c807145bfa Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 20 Feb 2025 03:45:27 +0000 Subject: [PATCH 3/8] Formatting and variable name changes from review Co-authored-by: Daira-Emma Hopwood --- zips/draft-str4d-account-metadata-keys.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/zips/draft-str4d-account-metadata-keys.md b/zips/draft-str4d-account-metadata-keys.md index 0c23c191b..d6e674be7 100644 --- a/zips/draft-str4d-account-metadata-keys.md +++ b/zips/draft-str4d-account-metadata-keys.md @@ -81,11 +81,11 @@ The tree has the following general structure, specified in more detail below: - $m_{\mathsf{metadata}} / TBD' / \mathsf{coinType}' / \mathsf{account}'$ - Account Metadata Key - $\ldots / 0'$ - Account-level Inherent Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - - $\ldots / \mathtt{0x7FFFFFFFF}' \# \mathsf{PrivateSubject}$ - Private-use Inherent Metadata Key + - $\ldots / (\mathtt{0x7FFFFFFFF}', \mathsf{PrivateUseSubject})$ - Private-use Inherent Metadata Key - $\ldots / 1'$ - Account-level External Metadata Key - - $\ldots / 0' \# \mathsf{FVKTypedItem}$ - Imported UFVK Metadata Key + - $\ldots / (0', \mathsf{FVKTypedItem})$ - Imported UFVK Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - - $\ldots / \mathtt{0x7FFFFFFFF}' \# \mathsf{PrivateSubject}$ - Private-use External Metadata Key + - $\ldots / (\mathtt{0x7FFFFFFFF}', \mathsf{PrivateUseSubject})$ - Private-use External Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) @@ -167,15 +167,15 @@ valid hardened child index) within its key tree for this purpose. - Let $K$ be either the Account-level Inherent Metadata Key, or an Imported UFVK Metadata Key. -- Let $\mathsf{PrivateSubject}$ be a globally unique non-empty sequence of at +- Let $\mathsf{PrivateUseSubject}$ be a globally unique non-empty sequence of at most 252 bytes that identifies the desired private-use context. -- Return $\mathsf{CKDreg}(K, \mathtt{0x7FFFFFFFF}, \mathsf{PrivateSubject})$ +- Return $\mathsf{CKDreg}(K, \mathtt{0x7FFFFFFFF}, \mathsf{PrivateUseSubject})$ :::warning It is the responsibility of wallet developers to ensure that they do not use -colliding $\mathsf{PrivateSubject}$ values, and to analyse their private use for +colliding $\mathsf{PrivateUseSubject}$ values, and to analyse their private use for any security risks related to potential cross-protocol attacks (in the event that -two wallet developers happen to select a colliding $\mathsf{PrivateSubject}$). +two wallet developers happen to select a colliding $\mathsf{PrivateUseSubject}$). Wallet developers that are unwilling to accept these risks SHOULD propose new standardised metadata protocols instead, to benefit from ecosystem coordination and review. From ab459c754ba1be59c4d535518b3e8fb98bb83a41 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 20 Feb 2025 03:49:11 +0000 Subject: [PATCH 4/8] Assign ZIP 325 to draft-str4d-account-metadata-keys --- ...raft-str4d-account-metadata-keys.md => zip-0325.md} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename zips/{draft-str4d-account-metadata-keys.md => zip-0325.md} (96%) diff --git a/zips/draft-str4d-account-metadata-keys.md b/zips/zip-0325.md similarity index 96% rename from zips/draft-str4d-account-metadata-keys.md rename to zips/zip-0325.md index d6e674be7..82939d09e 100644 --- a/zips/draft-str4d-account-metadata-keys.md +++ b/zips/zip-0325.md @@ -1,5 +1,5 @@ - ZIP: Unassigned + ZIP: 325 Title: Account Metadata Keys Owners: Jack Grigg Daira-Emma Hopwood @@ -73,12 +73,12 @@ This ZIP registers the following ZIP 32 Registered Key Derivation [^zip-0032-rkd tree: - $\mathsf{ContextString} = \texttt{“MetadataKeys”}$ -- ZIP number: TBD +- $\mathsf{ZipNumber} = 325$ The tree has the following general structure, specified in more detail below: - $m_{\mathsf{metadata}}$: Metadata Key tree - - $m_{\mathsf{metadata}} / TBD' / \mathsf{coinType}' / \mathsf{account}'$ - Account Metadata Key + - $m_{\mathsf{metadata}} / 325' / \mathsf{coinType}' / \mathsf{account}'$ - Account Metadata Key - $\ldots / 0'$ - Account-level Inherent Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - $\ldots / (\mathtt{0x7FFFFFFFF}', \mathsf{PrivateUseSubject})$ - Private-use Inherent Metadata Key @@ -101,12 +101,12 @@ The Account Metadata Key is the root of a subtree that corresponds to a ZIP 32 account represented elsewhere in the overall tree. It is derived from the seed $\mathsf{S}$ as: -$\mathsf{AccountMetadataKey} = \mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{RegKD}(\texttt{“MetadataKeys”}, \mathsf{S}, \mathsf{ZipNumber}), \mathsf{coinType}, [\,]), \mathsf{account}, [\,])$ +$\mathsf{AccountMetadataKey} = \mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{RegKD}(\texttt{“MetadataKeys”}, \mathsf{S}, 325), \mathsf{coinType}, [\,]), \mathsf{account}, [\,])$ or, in path notation: ``` -m_metadata / TBD' / coin_type' / account' +m_metadata / 325' / coin_type' / account' ``` ### Inherent metadata keys From b9b736636fda933814211f1039be865cf9c043c6 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 27 Feb 2025 00:01:58 +0000 Subject: [PATCH 5/8] ZIP 325: Apply rewording to Motivation from review Co-authored-by: Daira-Emma Hopwood --- zips/zip-0325.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/zips/zip-0325.md b/zips/zip-0325.md index 82939d09e..abe509911 100644 --- a/zips/zip-0325.md +++ b/zips/zip-0325.md @@ -41,12 +41,12 @@ If the user's device is wiped or lost and the user recovers their wallet from a backed-up mnemonic phrase, they will lose all of this metadata if it is not stored somewhere. -For other kinds of phone data, it is expected by users that their phone's normal -backup storage will have saved (most of) their data, such that access to e.g. -the associated Apple or Google account will be sufficient for data recovery. +For other kinds of mobile device data, it is expected by users that their device's +normal backup storage will have saved (most of) their data, such that access to +e.g. the associated Apple or Google account will be sufficient for data recovery. However, metadata such as mappings between Zcash addresses and recipient names can be particularly sensitive, meaning that users may not want these to be backed up -unencrypted in their phone's normal backup storage. Similarly, the inability to +unencrypted in their device's normal backup storage. Similarly, the inability to alter on-chain data means that permanently storing metadata in transaction memo fields may also not be an option. From dc6fb14a8461e5b71894cd4bfa9000f5ae174e29 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 27 Feb 2025 00:03:02 +0000 Subject: [PATCH 6/8] ZIP 325: Fix typo in private use child index constant --- zips/zip-0325.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/zips/zip-0325.md b/zips/zip-0325.md index abe509911..29601e995 100644 --- a/zips/zip-0325.md +++ b/zips/zip-0325.md @@ -81,11 +81,11 @@ The tree has the following general structure, specified in more detail below: - $m_{\mathsf{metadata}} / 325' / \mathsf{coinType}' / \mathsf{account}'$ - Account Metadata Key - $\ldots / 0'$ - Account-level Inherent Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - - $\ldots / (\mathtt{0x7FFFFFFFF}', \mathsf{PrivateUseSubject})$ - Private-use Inherent Metadata Key + - $\ldots / (\mathtt{0x7FFFFFFF}', \mathsf{PrivateUseSubject})$ - Private-use Inherent Metadata Key - $\ldots / 1'$ - Account-level External Metadata Key - $\ldots / (0', \mathsf{FVKTypedItem})$ - Imported UFVK Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - - $\ldots / (\mathtt{0x7FFFFFFFF}', \mathsf{PrivateUseSubject})$ - Private-use External Metadata Key + - $\ldots / (\mathtt{0x7FFFFFFF}', \mathsf{PrivateUseSubject})$ - Private-use External Metadata Key - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) - $\ldots / \ldots$ - (Reserved for future updates to this ZIP) @@ -153,7 +153,7 @@ The following metadata protocols have been standardised: - None at time of writing. -The remaining range of child indices from 0 to $\texttt{0x7FFFFFFFE}$ inclusive +The remaining range of child indices from 0 to $\texttt{0x7FFFFFFE}$ inclusive are reserved for future updates to this ZIP. Wallet developers can propose new standardised metadata protocols by writing a 2000-series ZIP that specifies the protocol as an update to this ZIP. @@ -162,14 +162,14 @@ protocol as an update to this ZIP. In some contexts there is a need for deriving ad-hoc key trees for private use by wallets, without ecosystem coordination and without any kind of compatibility -guarantees. This ZIP reserves child index $\mathtt{0x7FFFFFFFF}$ (the maximum +guarantees. This ZIP reserves child index $\mathtt{0x7FFFFFFF}$ (the maximum valid hardened child index) within its key tree for this purpose. - Let $K$ be either the Account-level Inherent Metadata Key, or an Imported UFVK Metadata Key. - Let $\mathsf{PrivateUseSubject}$ be a globally unique non-empty sequence of at most 252 bytes that identifies the desired private-use context. -- Return $\mathsf{CKDreg}(K, \mathtt{0x7FFFFFFFF}, \mathsf{PrivateUseSubject})$ +- Return $\mathsf{CKDreg}(K, \mathtt{0x7FFFFFFF}, \mathsf{PrivateUseSubject})$ :::warning It is the responsibility of wallet developers to ensure that they do not use From b96218b1f2cf845d997c20e7ba68bc5a3f290f6e Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 27 Feb 2025 00:03:52 +0000 Subject: [PATCH 7/8] ZIP 325: Clarify wording around how UFVK is used Co-authored-by: Daira-Emma Hopwood --- zips/zip-0325.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zips/zip-0325.md b/zips/zip-0325.md index 29601e995..301b0539f 100644 --- a/zips/zip-0325.md +++ b/zips/zip-0325.md @@ -128,8 +128,8 @@ As UFVKs may in general change over time (due to the inclusion of new higher-preference FVK items, or removal of older deprecated FVK items), there is no guarantee that the exact same set of FVK items will be present at both backup creation time and recovery time. Instead, the most preferred FVK item within a -UFVK is used as the domain separator, and the Imported UFVK Metadata Key is -derived as: +UFVK is used as the domain in which keys can be generated, and the Imported +UFVK Metadata Key is derived as: $\mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{AccountMetadataKey}, 1, [\,]), 0, \mathsf{FVKTypedItem})$ From 070c185b6072523c3e2ddc85647786153d8d114d Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 27 Feb 2025 00:05:31 +0000 Subject: [PATCH 8/8] Render manually, while the CI-based rendering is broken --- README.rst | 2 + rendered/index.html | 2 + rendered/zip-0325.html | 241 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 245 insertions(+) create mode 100644 rendered/zip-0325.html diff --git a/README.rst b/README.rst index e9376841c..98293640c 100644 --- a/README.rst +++ b/README.rst @@ -178,6 +178,7 @@ written. 322 Generic Signed Message Format Reserved 323 Specification of getblocktemplate for Zcash Reserved 324 URI-Encapsulated Payments Draft + 325 Account Metadata Keys Draft 332 Wallet Recovery from zcashd HD Seeds Reserved 339 Wallet Recovery Words Reserved 400 Wallet.dat format Draft @@ -321,6 +322,7 @@ Index of ZIPs 322 Generic Signed Message Format Reserved 323 Specification of getblocktemplate for Zcash Reserved 324 URI-Encapsulated Payments Draft + 325 Account Metadata Keys Draft 332 Wallet Recovery from zcashd HD Seeds Reserved 339 Wallet Recovery Words Reserved 400 Wallet.dat format Draft diff --git a/rendered/index.html b/rendered/index.html index f06b03aa4..57551d152 100644 --- a/rendered/index.html +++ b/rendered/index.html @@ -133,6 +133,7 @@ 322 Generic Signed Message Format Reserved 323 Specification of getblocktemplate for Zcash Reserved 324 URI-Encapsulated Payments Draft + 325 Account Metadata Keys Draft 332 Wallet Recovery from zcashd HD Seeds Reserved 339 Wallet Recovery Words Reserved 400 Wallet.dat format Draft @@ -257,6 +258,7 @@ 322 Generic Signed Message Format Reserved 323 Specification of getblocktemplate for Zcash Reserved 324 URI-Encapsulated Payments Draft + 325 Account Metadata Keys Draft 332 Wallet Recovery from zcashd HD Seeds Reserved 339 Wallet Recovery Words Reserved 400 Wallet.dat format Draft diff --git a/rendered/zip-0325.html b/rendered/zip-0325.html new file mode 100644 index 000000000..10c4d87a7 --- /dev/null +++ b/rendered/zip-0325.html @@ -0,0 +1,241 @@ + + + + ZIP 325: Account Metadata Keys + + + + + + + +
ZIP: 325
+Title: Account Metadata Keys
+Owners: Jack Grigg <jack@electriccoin.co>
+        Daira-Emma Hopwood <daira@electriccoin.co>
+        Kris Nuttycombe <kris@electriccoin.co>
+Status: Draft
+Category: Standards / Wallet
+Created: 2025-02-18
+License: MIT
+
+ +

Terminology

+ +

The key words “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.

+ +

Abstract

+ +

This ZIP specifies the key tree for Account Metadata Keys. These are derived +from the same seed as a ZIP 32 2 account, and can be used by wallets +to derive encryption keys for local / off-chain metadata.

+ +

Motivation

+ +

A wallet’s main data source is the Zcash chain: from this it can detect notes +received by an account, determine whether those notes are spent, build witnesses +for spending, recover on-chain memo data, and so on. However, wallets also +generate significant quantities of off-chain metadata as they are used, such as:

+ +
    +
  • Local annotations about transactions in the wallet.
    • +
  • Mappings between Zcash addresses and user-meaningful recipient names.
    • +
  • The exchange rate from ZEC to another currency that was used to determine how +much ZEC to send in a payment.
    • +
+ +

This metadata is valuable to users, and highly desirable to ensure to be backed up. +If the user’s device is wiped or lost and the user recovers their wallet from a +backed-up mnemonic phrase, they will lose all of this metadata if it is not +stored somewhere.

+ +

For other kinds of mobile device data, it is expected by users that their device’s +normal backup storage will have saved (most of) their data, such that access to +e.g. the associated Apple or Google account will be sufficient for data recovery. +However, metadata such as mappings between Zcash addresses and recipient names can +be particularly sensitive, meaning that users may not want these to be backed up +unencrypted in their device’s normal backup storage. Similarly, the inability to +alter on-chain data means that permanently storing metadata in transaction memo +fields may also not be an option.

+ +

Additionally, it is currently the case that users only need to back up a single +secret (a mnemonic seed phrase), once, in order to recover all information for +accounts derived from that secret. If metadata were encrypted using independent +key material, these keys would also need to be backed up, leading to fragility +of wallet restoration.

+ +

Requirements

+ +
    +
  • The user should not need to update their existing backups of secret material.
    • +
  • It should be possible to store metadata about accounts for which we don’t +control spend authority (i.e. imported UFVKs).
    • +
  • The key tree must be future-extensible.
    • +
+ +

Specification

+ +

Metadata key tree

+ +

This ZIP registers the following ZIP 32 Registered Key Derivation 3 +tree:

+ +
    +
  • \(\mathsf{ContextString} = \texttt{“MetadataKeys”}\)
    • +
  • \(\mathsf{ZipNumber} = 325\)
    • +
+ +

The tree has the following general structure, specified in more detail below:

+ +
    +
  • \(m_{\mathsf{metadata}}\): Metadata Key tree
    • +
  • \(m_{\mathsf{metadata}} / 325' / \mathsf{coinType}' / \mathsf{account}'\) - Account Metadata Key + +
      +
    • \(\ldots / 0'\) - Account-level Inherent Metadata Key
      • +
    • \(\ldots / \ldots\) - (Reserved for future updates to this ZIP)
      • +
    • \(\ldots / (\mathtt{0x7FFFFFFF}', \mathsf{PrivateUseSubject})\) - Private-use Inherent Metadata Key
      • +
    • \(\ldots / 1'\) - Account-level External Metadata Key
      • +
    • \(\ldots / (0', \mathsf{FVKTypedItem})\) - Imported UFVK Metadata Key + +
        +
      • \(\ldots / \ldots\) - (Reserved for future updates to this ZIP)
        • +
      • \(\ldots / (\mathtt{0x7FFFFFFF}', \mathsf{PrivateUseSubject})\) - Private-use External Metadata Key
        • +
      • +
    • \(\ldots / \ldots\) - (Reserved for future updates to this ZIP)
      • +
    • \(\ldots / \ldots\) - (Reserved for future updates to this ZIP)
      • +
    • +
+ +

Non-leaf keys in the key tree MUST NOT be used directly to encrypt metadata. +Encryption keys are leaves in this key tree. The sole exception to this is +private-use keys (for which part of their key derivation is outside the scope of +this specification): encryption keys MAY be derived from the private-use key +leaves.

+ +

Account Metadata Key

+ +

The Account Metadata Key is the root of a subtree that corresponds to a ZIP 32 +account represented elsewhere in the overall tree. It is derived from the seed +\(\mathsf{S}\) as:

+ +

\(\mathsf{AccountMetadataKey} = \mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{RegKD}(\texttt{“MetadataKeys”}, \mathsf{S}, 325), \mathsf{coinType}, [\,]), \mathsf{account}, [\,])\)

+ +

or, in path notation:

+ +
m_metadata / 325' / coin_type' / account'
+
+ +

Inherent metadata keys

+ +

The Account-level Inherent Metadata Key’s subtree contains keys used for +metadata associated with the Account Metadata Key’s corresponding account. The +key is derived as:

+ +

\(\mathsf{CKDreg}(\mathsf{AccountMetadataKey}, 0, [\,])\)

+ +

External metadata keys

+ +

The Account-level External Metadata Key’s subtree contains keys used for +metadata associated with imported UFVKs. Unlike the inherent metadata keys which +can leverage the inherent domain separation provided by the account index, here +domain separation between metadata keys is provided by the UFVKs themselves.

+ +

As UFVKs may in general change over time (due to the inclusion of new +higher-preference FVK items, or removal of older deprecated FVK items), there is +no guarantee that the exact same set of FVK items will be present at both backup +creation time and recovery time. Instead, the most preferred FVK item within a +UFVK is used as the domain in which keys can be generated, and the Imported +UFVK Metadata Key is derived as:

+ +

\(\mathsf{CKDreg}(\mathsf{CKDreg}(\mathsf{AccountMetadataKey}, 1, [\,]), 0, \mathsf{FVKTypedItem})\)

+ +

where \(\mathsf{FVKTypedItem}\) is the encoding of the most preferred FVK +item within the ZIP 316 raw encoding of a UFVK. 4

+ +

Usage of the Imported UFVK Metadata Key trees SHOULD follow ZIP 316 preference +order: 4

+ +
    +
  • For encryption-like usage, the key tree corresponding to the most preferred +FVK item within a UFVK SHOULD be used.
    • +
  • For decryption-like usage, each key tree SHOULD be tried in preference order +until metadata can be recovered. If metadata is recovered via an FVK item that +is not the most preferred, wallets SHOULD update their metadata backups by +re-encrypting the metadata using the key tree corresponding to the most +preferred FVK item.
    • +
+ +

Standardised metadata protocols

+ +

The following metadata protocols have been standardised:

+ +
    +
  • None at time of writing.
    • +
+ +

The remaining range of child indices from 0 to \(\texttt{0x7FFFFFFE}\) inclusive +are reserved for future updates to this ZIP. Wallet developers can propose new +standardised metadata protocols by writing a 2000-series ZIP that specifies the +protocol as an update to this ZIP.

+ +

Private-use metadata keys

+ +

In some contexts there is a need for deriving ad-hoc key trees for private use +by wallets, without ecosystem coordination and without any kind of compatibility +guarantees. This ZIP reserves child index \(\mathtt{0x7FFFFFFF}\) (the maximum +valid hardened child index) within its key tree for this purpose.

+ +
    +
  • Let \(K\) be either the Account-level Inherent Metadata Key, or an Imported UFVK +Metadata Key.
    • +
  • Let \(\mathsf{PrivateUseSubject}\) be a globally unique non-empty sequence of at +most 252 bytes that identifies the desired private-use context.
    • +
  • Return \(\mathsf{CKDreg}(K, \mathtt{0x7FFFFFFF}, \mathsf{PrivateUseSubject})\)
    • +
+ +

:::warning +It is the responsibility of wallet developers to ensure that they do not use +colliding \(\mathsf{PrivateUseSubject}\) values, and to analyse their private use for +any security risks related to potential cross-protocol attacks (in the event that +two wallet developers happen to select a colliding \(\mathsf{PrivateUseSubject}\)). +Wallet developers that are unwilling to accept these risks SHOULD propose new +standardised metadata protocols instead, to benefit from ecosystem coordination +and review. +::: +

+ +

Reference implementation

+ +
    +
  • https://github.com/Electric-Coin-Company/zcash-android-wallet-sdk/pull/1686
    • +
+ +

References

+ +
+
+
    + +
  1. +

    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”  ↩︎

    +
    2. + +
  2. +

    ZIP 32: Shielded Hierarchical Deterministic Wallets  ↩︎

    +
    3. + +
  3. +

    ZIP 32: Shielded Hierarchical Deterministic Wallets, Section: Registered key derivation  ↩︎

    +
    4. + +
  4. +

    ZIP 316: Unified Addresses and Unified Viewing Keys  ↩︎

    +
    5. + +
+
+ +