From e89b60e5a26ea58ebff72f20a5bbffbfbcbe382b Mon Sep 17 00:00:00 2001 From: Paul Dann Date: Wed, 15 Jan 2025 14:52:22 +0000 Subject: [PATCH 01/22] ZIP 233-235: Rephrase all references to "burning" --- zips/zip-0233.md | 90 ++++++++++++++++++++++++------------------------ zips/zip-0234.md | 67 +++++++++++++++++------------------ zips/zip-0235.md | 78 +++++++++++++++++++++-------------------- 3 files changed, 119 insertions(+), 116 deletions(-) diff --git a/zips/zip-0233.md b/zips/zip-0233.md index cb14919c2..63aea5c9f 100644 --- a/zips/zip-0233.md +++ b/zips/zip-0233.md @@ -1,6 +1,6 @@ ``` ZIP: 233 -Title: Network Sustainability Mechanism: Burning +Title: Network Sustainability Mechanism: Removing Funds From Circulation Owners: Jason McGee Zooko Wilcox Tomek Piotrowski @@ -40,9 +40,6 @@ defined by consensus. This is split between the miner and Funding Streams. on the network. [TODO: there is a potential terminology conflict between this and issuance as defined in ZIP 227.] -"Burning" - The method by which ZEC/TAZ becomes unavailable for circulation -on the network. - $\mathsf{MAX\_MONEY}$, as defined in § 5.3 ‘Constants’ [^protocol-constants], is the total ZEC/TAZ supply cap measured in zatoshi, corresponding to 21,000,000 ZEC. This is slightly larger than the supply cap for the current @@ -52,11 +49,11 @@ checks. # Abstract -This ZIP proposes the introduction of a mechanism to voluntarily burn funds, -removing those funds entirely from circulation on the network. This mechanism, -in combination with ZIP 234 [^zip-0234] and ZIP 235 [^zip-0235], comprises a -long-term strategy for the sustainability of the network. We will refer to the -combined effects of these three ZIPs as the “Network Sustainability Mechanism”. +This ZIP proposes the introduction of a mechanism to voluntarily remove funds +entirely from circulation on the network. This mechanism, in combination with +ZIP 234 [^zip-0234] and ZIP 235 [^zip-0235], comprises a long-term strategy for +the sustainability of the network. We will refer to the combined effects of +these three ZIPs as the “Network Sustainability Mechanism”. # Motivation @@ -64,71 +61,74 @@ combined effects of these three ZIPs as the “Network Sustainability Mechanism This mechanism seeks to address concerns about the sustainability of the network design shared by Bitcoin-like systems: -1. **Long Term Consensus Sustainability:** By enabling the burning of funds, the - network gains the ability to create "headroom" between the chain value and - $\mathsf{MAX\_MONEY}$. This lays necessary groundwork for extending the - block subsidy system, which currently has a clear final end date. -2. **Benefits to ZEC Holders:** Burning funds reduces the supply of ZEC, - benefiting network users in proportion to their holdings without requiring - them to opt into any scheme, introducing extra risk, active oversight, or - accounting complexity. +1. **Long Term Consensus Sustainability:** By enabling the removal of funds from + circulation, the network gains the ability to create "headroom" between the + chain value and $\mathsf{MAX\_MONEY}$. This lays necessary groundwork for + extending the block subsidy system, which currently has a clear final end + date. +2. **Benefits to ZEC Holders:** Removing funds from circulation reduces the + supply of ZEC, benefiting network users in proportion to their holdings + without requiring them to opt into any scheme, introducing extra risk, active + oversight, or accounting complexity. # Specification -## Burn amount +## Transaction Field -Each transaction gains a $\mathsf{burn\_amount}$ property, specifying the -value in zatoshis that is burned when the transaction is mined. The burned value -subtracts from the remaining value in the "transparent transaction value pool" -as described in § 3.4 ‘Transactions and Treestates’ [^protocol-transactions]. +Each transaction gains a $\mathsf{zip233\_amount}$ property, specifying the +value in zatoshis that is removed from circulation when the transaction is +mined. The value removed from circulation subtracts from the remaining value in +the "transparent transaction value pool" as described in § 3.4 ‘Transactions and +Treestates’ [^protocol-transactions]. -$\mathsf{burn\_amount}$ does not result in an output being produced in any +$\mathsf{zip233\_amount}$ does not result in an output being produced in any chain value pool, and therefore from the point at which the transaction is -applied to the global chain state, $\mathsf{burn\_amount}$ is subtracted from the -issued supply. It is unavailable for circulation on the network at least through -to the end of the block in which the transaction is mined. ZIP 234 [^zip-0234] -specifies a potential mechanism by which the burned funds would again become -available. +applied to the global chain state, $\mathsf{zip233\_amount}$ is subtracted from +the issued supply. It is unavailable for circulation on the network at least +through to the end of the block in which the transaction is mined. ZIP 234 +[^zip-0234] specifies a potential mechanism by which the funds removed from +circulation would again become available. ## Changes to ZIP 230 [^zip-0230] The following field is appended to the Common Transaction Fields of the v6 transaction format after `nExpiryHeight` [^zip-0230-transaction-format]: -| Bytes | Name | Data Type | Description | -|-------|--------------|-----------|----------------------------------------------------------| -| 8 | `burnAmount` | `uint64` | The value to be burned in this transaction, in zatoshis. | +| Bytes | Name | Data Type | Description | +|-------|----------------|-----------|----------------------------------------------------------------------------| +| 8 | `zip233Amount` | `uint64` | The value to be removed from circulation in this transaction, in zatoshis. | -The $\mathsf{burn\_amount}$ of a transaction is defined to be the value of the -`burnAmount` field if present, and otherwise 0. +The $\mathsf{zip233\_amount}$ of a transaction is defined to be the value of the +`zip233Amount` field if present, and otherwise 0. Notes: * If both this ZIP and ZIP 2002 are selected for inclusion in the same Network Upgrade, then the ambiguity in ordering of the fields added by these ZIPs would need to be resolved. -* Older transaction versions can continue to be supported after a network upgrade, - but burning is not possible for these transactions. For example, NU5 supports - both v4 and v5 transaction formats, for both coinbase and non-coinbase transactions. +* Older transaction versions can continue to be supported after a network + upgrade, but removing funds from circulation is not possible for these + transactions. For example, NU5 supports both v4 and v5 transaction formats, + for both coinbase and non-coinbase transactions. ## Changes to the Zcash Protocol Specification Make a change to § 3.4 ‘Transactions and Treestates’ [^protocol-transactions] -implementing the specification in [Burn amount]. +implementing the specification in [ZIP-233 Amount]. In § 7.1 ‘Transaction Encoding and Consensus’ [^protocol-txnconsensus], add: -> [NU7 onward] $\mathsf{burn\_amount}$ MUST be in the range $\{ 0 .. \mathsf{MAX\_MONEY} \}$. +> [NU7 onward] $\mathsf{zip233\_amount}$ MUST be in the range $\{ 0 .. \mathsf{MAX\_MONEY} \}$. ## Modifications relative to ZIP 244 [^zip-0244] Relative to the sighash algorithm defined in ZIP 244, the sighash algorithm that applies to v6 transactions differs by appending the encoding of -$\mathsf{burn\_amount}$ to the Common Transaction Fields that are the input +$\mathsf{zip233\_amount}$ to the Common Transaction Fields that are the input to the digest in T.1: `header_digest` [^zip-0244-t-1-header-digest]: -> T.1f: burn_amount (8-byte little-endian burn amount) +> T.1f: zip233_amount (8-byte little-endian amount to remove from circulation) Note: If both this ZIP and ZIP 2002 are selected for inclusion in the same Network Upgrade, then the ambiguity in ordering of the fields added by these @@ -144,11 +144,11 @@ All of these changes apply identically to Mainnet and Testnet. All technical decisions in this ZIP are balanced between the necessary robustness of the NSM mechanics, and simplicity of implementation. -## New transaction field for burn amount +## New transaction field for amount to remove from circulation -An explicit value distinguishes the burned ZEC from the transaction fee. -Explicitness also ensures any arithmetic flaws in any implementations are more -likely to be observed and caught immediately. +An explicit value distinguishes the funds to remove from circulation from +the transaction fee. Explicitness also ensures any arithmetic flaws in any +implementations are more likely to be observed and caught immediately. # Deployment @@ -178,7 +178,7 @@ This ZIP is proposed to activate with Network Upgrade 7. [^zip-0254] [^zip-0234]: [ZIP 234: Network Sustainability Mechanism: Issuance Smoothing](zip-0234.rst) -[^zip-0235]: [ZIP 235: Burn 60% of Transaction Fees](zip-0235.rst) +[^zip-0235]: [ZIP 235: Remove 60% of Transaction Fees From Circulation](zip-0235.rst) [^zip-0244]: [ZIP 244: Transaction Identifier Non-Malleability](zip-0244.rst) diff --git a/zips/zip-0234.md b/zips/zip-0234.md index bcc331b30..8a8be0abc 100644 --- a/zips/zip-0234.md +++ b/zips/zip-0234.md @@ -36,8 +36,8 @@ The symbol "$\,\cdot\,$" means multiplication, as described in § 2 ‘Notation "ZEC/TAZ" refers to the native currency of Zcash on a given network, i.e. ZEC on Mainnet and TAZ on Testnet. -The terms "Block Subsidy", "Issuance", and "Burning" are to be interpreted -as described in ZIP 233. [^zip-0233] +The terms "Block Subsidy" and "Issuance" are to be interpreted as described in +ZIP 233. [^zip-0233] Let $\mathsf{PostBlossomHalvingInterval}$ be as defined in [^protocol-diffadjustment]. @@ -66,8 +66,8 @@ inherited from Bitcoin, we propose a smooth logarithmic curve, defined as a fixed portion of the current value of the Money Reserve at a given block height. The new issuance scheme would approximate the current issuance over 4-year -intervals, assuming no ZEC/TAZ is burned during that time, and retains the -overall supply cap of `MAX_MONEY`. +intervals, assuming no ZEC/TAZ is removed from circulation during that time, and +retains the overall supply cap of `MAX_MONEY`. # Motivation @@ -76,8 +76,8 @@ Key Objectives: 1. We want to introduce an automated mechanism that allows users of the network to contribute to the long-term sustainability of the network. -2. We want to enable ZEC that has been burned to be recreated in the future to - benefit network sustainability. +2. We want to enable ZEC that has been removed from circulation to be recreated + in the future to benefit network sustainability. 3. We want to retain the existing ZEC supply cap of 21 million. 4. We want the issuance rate to remain similar to the historical rate for Zcash (and before that, Bitcoin). @@ -111,7 +111,7 @@ that satisfies the following requirements: non-zero, preventing any final "unmined" zatoshis. 4. For any 4-year period, all paid out block subsidies are approximately equal to half of the Money Reserve at the beginning of that 4-year period, if no - ZEC is burned during those 4 years. + ZEC is removed from circulation during those 4 years. 5. Decrease the short-term impact of the deployment of this ZIP on block subsidy recipients, and minimize the potential reputation risk to Zcash of changing the block subsidy amount. @@ -129,10 +129,10 @@ $\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT} = \mathsf{TBD}$ The block height will be chosen by the following criteria: - It is after NU7 activation height. -- It is calculated to be the lowest height after the second halving at - which the NSM issuance would be less than the current BTC-style issuance - _neglecting_ any burnt ZEC (i.e. assuming the amount of ZEC burnt is - exactly 0). +- It is calculated to be the lowest height after the second halving at which + the NSM issuance would be less than the current BTC-style issuance _neglecting_ + any ZEC removed from circulation (i.e. assuming the amount of ZEC removed from + circulation is exactly 0). This selection is intended to achieve Key Objective 6 while still being at a constant, predictable height. An alternative would be to have a dynamic @@ -141,21 +141,21 @@ testing the "less than" conditional with every block after the second halving. We prefer the pre-defined constant height parameter, to give everyone more _time_ certainty at the cost of _issuance level_ certainty. -The difference in up-front calculation versus dynamic calculation is in -whether or not burns are accounted for (since future burns cannot be -calculated up-front). This means with the pre-defined constant parameter -approach, issuance will jump _up_ some amount at activation. This amount -should be equivalent to all ZEC burnt prior to that height times -$\mathsf{BLOCK\_SUBSIDY\_FRACTION}$. For example, if a total of 100,000 ZEC -were burnt prior to the pre-defined constant activation height, then at -activation the issuance would be larger than BTC-style issuance by -$100\_000\textsf{ ZEC} \cdot \mathsf{BLOCK\_SUBSIDY\_FRACTION}$, -which we calculate equals $0.04126$ ZEC. This example is chosen to -demonstrate that a very large burn amount (much larger than expected) would -elevate issuance by a relatively small amount. For this reason, we believe -a pre-defined constant is a better approach to achieving Key Objective 6 -than a "dynamic latch" logic because it is so much simpler to implement -and reason about. +The difference in up-front calculation versus dynamic calculation is +in whether or not funds removed from circulation are accounted for +(since funds removed from circulation in the future cannot be calculated +up-front). This means with the pre-defined constant parameter approach, +issuance will jump _up_ some amount at activation. This amount should be +equivalent to all ZEC removed from circulation prior to that height times +$\mathsf{BLOCK\_SUBSIDY\_FRACTION}$. For example, if a total of 100,000 ZEC were +burnt prior to the pre-defined constant activation height, then at activation +the issuance would be larger than BTC-style issuance by $100\_000\textsf{ ZEC} +\cdot \mathsf{BLOCK\_SUBSIDY\_FRACTION}$, which we calculate equals $0.04126$ +ZEC. This example is chosen to demonstrate that a very large amount removed from +circulation (much larger than expected) would elevate issuance by a relatively +small amount. For this reason, we believe a pre-defined constant is a better +approach to achieving Key Objective 6 than a "dynamic latch" logic because it is +so much simpler to implement and reason about. $\mathsf{MoneyReserveAfter}(\mathsf{height}) =$ The value of the Money Reserve after the specified block height. @@ -189,9 +189,9 @@ This implies that after a period of 4 years around half of Money Reserve will have been issued as block subsidies, thus satisfying **Requirement 4**. The largest possible value in the Money Reserve is $\mathsf{MAX\_MONEY}$, in the -theoretically possible case that all issued funds are burned. If this happened, -the largest interim sum in the block subsidy calculation would be -$\mathsf{MAX\_MONEY} \cdot 4126 / 10\_000\_000\_000$. +theoretically possible case that all issued funds are removed from circulation. +If this happened, the largest interim sum in the block subsidy calculation would +be $\mathsf{MAX\_MONEY} \cdot 4126 / 10\_000\_000\_000$. This uses 62.91 bits, which is just under the 63-bit limit for signed two's complement 64-bit integer amount types. @@ -225,9 +225,9 @@ well as generate plots like the ones above. Its output: Last block is 47917869 in ~113.88 years ``` -indicates that, assuming that no ZEC is ever burned, the Money Reserve will be -depleted after 113.88 years, and the block subsidy will be 0 ZEC after that -point. +indicates that, assuming that no ZEC is ever removed from circulation, the Money +Reserve will be depleted after 113.88 years, and the block subsidy will be 0 ZEC +after that point. This fragment of the output: @@ -251,7 +251,8 @@ approximation beyond the four year half-life constraint. # Deployment This ZIP is proposed to activate with Network Upgrade 7. [^zip-0254] -It MUST be deployed at the same time or after ZIP 233 ("NSM: Burning" [^zip-0233]). +It MUST be deployed at the same time or after ZIP 233 ("NSM: Removing Funds From +Circulation" [^zip-0233]). # References diff --git a/zips/zip-0235.md b/zips/zip-0235.md index acfbdff73..7a43aea29 100644 --- a/zips/zip-0235.md +++ b/zips/zip-0235.md @@ -1,6 +1,6 @@ ``` ZIP: 235 -Title: Burn 60% of Transaction Fees +Title: Remove 60% of Transaction Fees From Circulation Owners: Jason McGee Zooko Wilcox Tomek Piotrowski @@ -36,58 +36,59 @@ The symbol "$\,\cdot\,$" means multiplication, as described in § 2 ‘Notation "ZEC/TAZ" refers to the native currency of Zcash on a given network, i.e. ZEC on Mainnet and TAZ on Testnet. -The terms "Block Subsidy", "Issuance", and "Burning" are to be interpreted -as described in ZIP 233. [^zip-0233] +The terms "Block Subsidy" and "Issuance" are to be interpreted as described in +ZIP 233. [^zip-0233] # Abstract -This ZIP proposes to burn 60% of transaction fees, while the remaining 40% is -directed as before, providing a deflationary effect, and building the groundwork -for long-term support of the Zcash network via the new block subsidy rules -proposed by ZIP 234 [^zip-0234]. +This ZIP proposes to remove 60% of transaction fees from circulation, while +the remaining 40% is directed as before, providing a deflationary effect, and +building the groundwork for long-term support of the Zcash network via the new +block subsidy rules proposed by ZIP 234 [^zip-0234]. # Motivation -ZIP 233 ("Network Sustainability Mechanism: Burning" [^zip-0233]) describes a -method by which ZEC can be burned to support network sustainability. +ZIP 233 ("Network Sustainability Mechanism: Removing Funds From Circulation" +[^zip-0233]) describes a method by which ZEC can be removed from circulation to +support network sustainability. By introducing a requirement that a certain proportion of transaction fees be -burned, we ensure that ZEC will be removed from circulating supply to contribute -to the long-term sustainability of the network as described below: +removed from circulation, we aim to contribute to the long-term sustainability +of the network as described below: ## Benefits to the Network 1. **Network Sustainability**: This mechanism involves temporarily reducing the supply of ZEC, similar to asset burning in Ethereum’s EIP-1559 [^eip-1559], - but with long-term sustainability benefits, as the burned funds effectively - boost future mining rewards, making it an attractive option for current and - future Zcash users. + but with long-term sustainability benefits, as the funds removed from + circulation effectively boost future mining rewards, making it an attractive + option for current and future Zcash users. 2. **Incentivizing Transaction Inclusion**: By maintaining a 40% share of transaction fees for miners, we continue incentivizing miners to prioritize including transactions in their blocks. This helps ensure the continued efficient processing of transactions and supports a robust and responsive network. -3. **Aligning Interests:** Burning transaction fees aligns the interests - of miners with the long-term health of the network, incentivizing them - to prioritize security and efficiency. As miners focus on maintaining a +3. **Aligning Interests:** Removing transaction fees from circulation aligns the + interests of miners with the long-term health of the network, incentivizing + them to prioritize security and efficiency. As miners focus on maintaining a robust network, overall adoption and usage can increase, leading to higher transaction volumes in the long run. This structure discourages short-term profit-seeking behaviors, as miners benefit more from a stable and thriving ecosystem than from engaging in malicious activities that could undermine the network's reputation and security. -4. **Future-Proofing the Network**: Burning a portion of transaction fees - is a forward-looking approach that prepares the Zcash network for future - challenges and opportunities. It establishes a financial buffer that can be - instrumental in addressing unforeseen issues and seizing strategic advantages - as the Zcash ecosystem evolves. +4. **Future-Proofing the Network**: Removing a portion of transaction fees from + circulation is a forward-looking approach that prepares the Zcash network for + future challenges and opportunities. It establishes a financial buffer that + can be instrumental in addressing unforeseen issues and seizing strategic + advantages as the Zcash ecosystem evolves. # Requirements * For each block, at least 60% (rounded down) of the total fees are to be - burned. + removed from circulation. * No restrictions are placed on the destination of the remaining proportion of fees. * Any fractions are rounded in favor of the miner. @@ -97,7 +98,7 @@ to the long-term sustainability of the network as described below: ## Consensus Rule Changes -For a given block, the coinbase transaction MUST have a $\mathsf{burn\_amount}$, +For a given block, the coinbase transaction MUST have a $\mathsf{zip233\_amount}$, as defined in [^zip-0233], that is greater than or equal to $\mathsf{floor}(\mathsf{transactionFees} \cdot 6 / 10)$. @@ -117,14 +118,14 @@ concern. ## Rationale for requiring the coinbase transaction to be v6 or later -There is no explicit mechanism in prior transaction versions to burn the -required funds. Since $\mathsf{burn\_amount} = 0$ for transaction versions -prior to v6, absent the rule about the coinbase transaction version it -would be technically possible to satisfy the constraint on $\mathsf{burn\_amount}$ -with earlier versions than v6, but only when $\mathsf{transactionFees} = 0$. -That would introduce a corner case in the transaction consensus rules that -is not useful, since it is expected that the $\mathsf{transactionFees}$ -will normally be non-zero. +There is no explicit mechanism in prior transaction versions to remove +the required funds from circulation. Since $\mathsf{zip233\_amount} = 0$ +for transaction versions prior to v6, absent the rule about the coinbase +transaction version it would be technically possible to satisfy the constraint +on $\mathsf{zip233\_amount}$ with earlier versions than v6, but only when +$\mathsf{transactionFees} = 0$. That would introduce a corner case in the +transaction consensus rules that is not useful, since it is expected that the +$\mathsf{transactionFees}$ will normally be non-zero. ## Estimated impact on miners @@ -137,7 +138,8 @@ regime, would be 87.86 ZEC. 100,000 blocks is approximately 3 months of blocks. Extrapolating to a year, we would expect 351.44 ZEC in fees paid to miners over a year. -If 60% of these fees burned, that would be 210.864 ZEC per year. [^zsf-fee-estimator] +If 60% of these fees are removed from circulation, that would be 210.864 ZEC per +year. [^zsf-fee-estimator] ## Considerations for the Future @@ -151,8 +153,8 @@ become greater than the block subsidy issuance. At that time we may need to reconsider the 60/40 split. However, this will likely not be the case for the next 8-10 years due to forecasts based on issuance models and network traffic. -Further ZIPs may be proposed to burn ZEC in various ways to support network -sustainability, including but not limited to: +Further ZIPs may be proposed to remove ZEC from circulation in various ways to +support network sustainability, including but not limited to: - ZSA fees - Fees and donations specific to decentralized applications @@ -164,8 +166,8 @@ sustainability, including but not limited to: # Deployment The implementation of this ZIP MUST be deployed at the same time or after -ZIP 233 ("NSM: Burning" [^zip-0233]), and ZIP 234 ("NSM: Issuance Smoothing" -[^zip-0234]). +ZIP 233 ("NSM: Removing Funds From Circulation" [^zip-0233]), and ZIP 234 ("NSM: +Issuance Smoothing" [^zip-0234]). # References @@ -182,7 +184,7 @@ ZIP 233 ("NSM: Burning" [^zip-0233]), and ZIP 234 ("NSM: Issuance Smoothing" [^zip-0230]: [ZIP 230: Version 6 Transaction Format](zip-0230.rst) -[^zip-0233]: [ZIP 233: Network Sustainability Mechanism: Burning](zip-0233.rst) +[^zip-0233]: [ZIP 233: Network Sustainability Mechanism: Removing Funds From Circulation](zip-0233.rst) [^zip-0234]: [ZIP 234: Network Sustainability Mechanism: Issuance Smoothing](zip-0234.rst) From 47177fe5bedabe13dbd50c19cca1a3bdb2beee9d Mon Sep 17 00:00:00 2001 From: Paul Dann Date: Wed, 29 Jan 2025 12:07:01 +0000 Subject: [PATCH 02/22] ZIP 233-235: Apply edits requested by str4d --- zips/zip-0233.md | 6 +++--- zips/zip-0234.md | 46 ++++++++++++++++++++++++---------------------- 2 files changed, 27 insertions(+), 25 deletions(-) diff --git a/zips/zip-0233.md b/zips/zip-0233.md index 63aea5c9f..c85156ab3 100644 --- a/zips/zip-0233.md +++ b/zips/zip-0233.md @@ -67,9 +67,9 @@ design shared by Bitcoin-like systems: extending the block subsidy system, which currently has a clear final end date. 2. **Benefits to ZEC Holders:** Removing funds from circulation reduces the - supply of ZEC, benefiting network users in proportion to their holdings - without requiring them to opt into any scheme, introducing extra risk, active - oversight, or accounting complexity. + circulating supply of ZEC, benefiting network users in proportion to their + holdings without requiring them to opt into any scheme, introducing extra + risk, active oversight, or accounting complexity. # Specification diff --git a/zips/zip-0234.md b/zips/zip-0234.md index 8a8be0abc..255414482 100644 --- a/zips/zip-0234.md +++ b/zips/zip-0234.md @@ -76,7 +76,7 @@ Key Objectives: 1. We want to introduce an automated mechanism that allows users of the network to contribute to the long-term sustainability of the network. -2. We want to enable ZEC that has been removed from circulation to be recreated +2. We want to enable ZEC that has been removed from circulation to be reissued in the future to benefit network sustainability. 3. We want to retain the existing ZEC supply cap of 21 million. 4. We want the issuance rate to remain similar to the historical rate for Zcash @@ -126,6 +126,9 @@ $\mathsf{BLOCK\_SUBSIDY\_FRACTION} = 4126 / 10\_000\_000\_000 = 0.0000004126$ $\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT} = \mathsf{TBD}$ +$\mathsf{MoneyReserveAfter}(\mathsf{height}) =$ The value of the Money Reserve +after the specified block height. + The block height will be chosen by the following criteria: - It is after NU7 activation height. @@ -134,7 +137,26 @@ The block height will be chosen by the following criteria: any ZEC removed from circulation (i.e. assuming the amount of ZEC removed from circulation is exactly 0). -This selection is intended to achieve Key Objective 6 while still being at +## Issuance Calculation + +At the $\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT}$, nodes should switch from the current issuance +calculation, to the following: + +$\mathsf{BlockSubsidy}(\mathsf{height}) = \mathsf{ceiling}(\mathsf{BLOCK\_SUBSIDY\_FRACTION} \cdot \mathsf{MoneyReserveAfter}(\mathsf{height} - 1))$ + +## Applicability + +All of these changes apply identically to Mainnet and Testnet. + + +# Rationale + +* Using an exponential decay function satisfies **Requirements 1** and **2** above. +* We round up to the next zatoshi to satisfy **Requirement 3** above. + +## Parameters + +The selection is intended to achieve Key Objective 6 while still being at a constant, predictable height. An alternative would be to have a dynamic "latch"-style activation, which would calculate the activation height by testing the "less than" conditional with every block after the second halving. @@ -157,26 +179,6 @@ small amount. For this reason, we believe a pre-defined constant is a better approach to achieving Key Objective 6 than a "dynamic latch" logic because it is so much simpler to implement and reason about. -$\mathsf{MoneyReserveAfter}(\mathsf{height}) =$ The value of the Money Reserve -after the specified block height. - -## Issuance Calculation - -At the $\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT}$, nodes should switch from the current issuance -calculation, to the following: - -$\mathsf{BlockSubsidy}(\mathsf{height}) = \mathsf{ceiling}(\mathsf{BLOCK\_SUBSIDY\_FRACTION} \cdot \mathsf{MoneyReserveAfter}(\mathsf{height} - 1))$ - -## Applicability - -All of these changes apply identically to Mainnet and Testnet. - - -# Rationale - -* Using an exponential decay function satisfies **Requirements 1** and **2** above. -* We round up to the next zatoshi to satisfy **Requirement 3** above. - ## BLOCK_SUBSIDY_FRACTION Let $\mathsf{IntendedMoneyReserveFractionRemainingAfterFourYears} = 0.5$. From 38fa8152255288624e67567be5106355185ec663 Mon Sep 17 00:00:00 2001 From: Paul Dann Date: Fri, 31 Jan 2025 12:50:03 +0000 Subject: [PATCH 03/22] Add Mark Herderson's name to ZIP authors --- zips/zip-0233.md | 1 + zips/zip-0234.md | 1 + zips/zip-0235.md | 1 + 3 files changed, 3 insertions(+) diff --git a/zips/zip-0233.md b/zips/zip-0233.md index c85156ab3..4a70c6a36 100644 --- a/zips/zip-0233.md +++ b/zips/zip-0233.md @@ -3,6 +3,7 @@ ZIP: 233 Title: Network Sustainability Mechanism: Removing Funds From Circulation Owners: Jason McGee Zooko Wilcox + Mark Henderson Tomek Piotrowski Mariusz Pilarek Paul Dann diff --git a/zips/zip-0234.md b/zips/zip-0234.md index 255414482..7d67f7dfd 100644 --- a/zips/zip-0234.md +++ b/zips/zip-0234.md @@ -3,6 +3,7 @@ ZIP: 234 Title: Network Sustainability Mechanism: Issuance Smoothing Owners: Jason McGee Zooko Wilcox + Mark Henderson Tomek Piotrowski Mariusz Pilarek Paul Dann diff --git a/zips/zip-0235.md b/zips/zip-0235.md index 7a43aea29..a5c92895f 100644 --- a/zips/zip-0235.md +++ b/zips/zip-0235.md @@ -3,6 +3,7 @@ ZIP: 235 Title: Remove 60% of Transaction Fees From Circulation Owners: Jason McGee Zooko Wilcox + Mark Henderson Tomek Piotrowski Mariusz Pilarek Paul Dann From a14bbf106e9d5a188118531be92d012a40f20ef6 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 6 Feb 2025 03:25:21 +0000 Subject: [PATCH 04/22] ZIP 227: Refactor the Asset Identifier section for clarity --- zips/zip-0227.rst | 58 +++++++++++++++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 20 deletions(-) diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst index 1234ef77c..e70bb433e 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -185,34 +185,23 @@ where the $\mathsf{Verify}$ algorithm is defined in BIP 340 [#bip-0340]_. Specification: Asset Identifier, Asset Digest, and Asset Base ============================================================= -For every new Asset, there MUST be a new and unique Asset Identifier, denoted $\mathsf{AssetId}$. We define this to be a globally unique pair $\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})$, where $\mathsf{ik}$ is the issuance key and $\mathsf{asset\_desc}$ is a byte string. +Every Asset has a globally-unique Asset Identifier, denoted $\mathsf{AssetId}$. A given +Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the +OrchardZSA protocol and potentially future Zcash shielded protocols. -A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the OrchardZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, $\mathsf{AssetDigest}$, which is simply is a $\textsf{BLAKE2b-512}$ hash of the Asset Identifier. -From the Asset Digest, we derive a specific Asset Base within each shielded protocol using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes. - -Let - -- $\mathsf{asset\_desc}$ be the asset description, which includes any information pertaining to the issuance, and is a non-empty byte sequence of at most 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. -- $\mathsf{ik}$ be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH. - -Define +From the Asset Identifier, we derive an Asset Digest .. math:: \mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId})), -where +where $\mathsf{EncodeAssetId}(\mathsf{AssetId})$ is a canonical encoding scheme for the +Asset Identifier. -- $\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{asset\_desc}\!$. -- Note that the initial $\mathtt{0x00}$ byte is a version byte. - -Define +From the Asset Digest, we derive a specific Asset Base that represents the Custom Asset +within each shielded protocol: .. math:: \mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) -In the case of the OrchardZSA protocol, we define - -.. math:: \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{AssetId}}) - -where $\mathsf{GroupHash}^\mathbb{P}$ is defined as in [#protocol-concretegrouphashpallasandvesta]_. +This Asset Base is included in shielded notes within the shielded protocol. The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram: @@ -226,11 +215,40 @@ The relations between the Asset Identifier, Asset Digest, and Asset Base are sho **Note:** To keep notations light and concise, we may omit $\mathsf{AssetId}$ (resp. $\mathsf{Protocol}$) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context. +ZIP 227 Asset Identifiers +------------------------- + +Assets issued using the protocol specified in this ZIP are scoped to the $\mathsf{ik}$ +that issued them. Within that scope, Asset Identifier uniqueness is obtained by way of an +asset description, $\mathsf{asset\_desc}$, which includes any information pertaining to +the issuance. $\mathsf{asset\_desc}$ is a non-empty byte sequence of at most 512 bytes +which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. + +We therefore define Asset Identifiers for assets issued under this ZIP as + +.. math:: \mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc}) + +and define their canonical encoding as + +.. math:: \mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{asset\_desc} + +Note that the initial $\mathtt{0x00}$ byte is a version byte, enabling future ZIPs to +specify alternative issuance protocols and Asset Identifiers. + Wallets MUST NOT display just the $\mathsf{asset\_desc}$ string to their users as the name of the Asset. Some possible alternatives include: - Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients. - The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets. +OrchardZSA Custom Assets +------------------------ + +In the case of the OrchardZSA protocol, we define + +.. math:: \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{AssetId}}) + +where $\mathsf{GroupHash}^\mathbb{P}$ is defined as in [#protocol-concretegrouphashpallasandvesta]_. + Specification: Issue Note, Issuance Action, Issuance Bundle and Issuance Protocol ================================================================================= From 47f402ceaad3afafe570614b6f562dfb19a597e4 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 6 Feb 2025 03:41:57 +0000 Subject: [PATCH 05/22] ZIP 227: Replace `asset_desc` with its hash in `AssetId` --- zips/zip-0227.rst | 58 +++++++++++++++++++++++++++++++++++------------ zips/zip-0230.rst | 6 +---- 2 files changed, 45 insertions(+), 19 deletions(-) diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst index e70bb433e..0947971ba 100644 --- a/zips/zip-0227.rst +++ b/zips/zip-0227.rst @@ -221,16 +221,20 @@ ZIP 227 Asset Identifiers Assets issued using the protocol specified in this ZIP are scoped to the $\mathsf{ik}$ that issued them. Within that scope, Asset Identifier uniqueness is obtained by way of an asset description, $\mathsf{asset\_desc}$, which includes any information pertaining to -the issuance. $\mathsf{asset\_desc}$ is a non-empty byte sequence of at most 512 bytes -which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. +the issuance. $\mathsf{asset\_desc}$ is a non-empty byte sequence which SHOULD be a +well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. -We therefore define Asset Identifiers for assets issued under this ZIP as +Define -.. math:: \mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc}) +.. math:: \mathsf{AssetDescHash} := \textsf{BLAKE2b-256}(\texttt{“ZSA-AssetDescCRH”},\; \mathsf{asset\_desc}), + +We define Asset Identifiers for assets issued under this ZIP as + +.. math:: \mathsf{AssetId} := (\mathsf{ik}, \mathsf{AssetDescHash}) and define their canonical encoding as -.. math:: \mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{asset\_desc} +.. math:: \mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{AssetDescHash})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{AssetDescHash} Note that the initial $\mathtt{0x00}$ byte is a version byte, enabling future ZIPs to specify alternative issuance protocols and Asset Identifiers. @@ -332,8 +336,9 @@ The issuer program performs the following operations: For all actions ``IssueAction``: -- encode $\mathsf{asset\_desc}$ as a UTF-8 byte string of size up to 512. -- compute $\mathsf{AssetDigest}$ from the issuance validating key $\mathsf{ik}$ and $\mathsf{asset\_desc}$ as decribed in the `Specification: Asset Identifier, Asset Digest, and Asset Base`_ section. +- encode $\mathsf{asset\_desc}$ as a UTF-8 byte string. +- compute $\mathsf{AssetDescHash}$ +- compute $\mathsf{AssetDigest}$ from the issuance validating key $\mathsf{ik}$ and $\mathsf{AssetDescHash}$ as decribed in the `Specification: Asset Identifier, Asset Digest, and Asset Base`_ section. - compute $\mathsf{AssetBase}$ from $\mathsf{AssetDigest}$ as decribed in the `Specification: Asset Identifier, Asset Digest, and Asset Base`_ section. - set the $\mathsf{finalize}$ boolean as desired (if more issuance actions are to be created for this $\mathsf{AssetBase}$, set $\mathsf{finalize} = 0$, otherwise set $\mathsf{finalize} = 1$). - for each recipient $i$: @@ -454,15 +459,40 @@ The following is a list of rationale for different decisions made in the proposa - The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This keeps the issuance details and the Asset Identifiers consistent across multiple shielded pools. It also separates the issuance authority from the spend authority, allowing for the potential transfer of issuance authority without compromising the spend authority. - The Custom Asset is described via a combination of the issuance validating key and an asset description string, to preclude the possibility of two different issuers creating colliding Custom Assets. -- The $\mathsf{asset\_desc}$ is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: +- We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack. - - links for storage such as for NFTs. - - metadata for Assets, encoded in any format. - - bridging information for Wrapped Assets (chain of origin, issuer name, etc) - - information to be committed by the issuer, though not enforceable by the protocol. +Hash of the asset description +----------------------------- -- We limit the size of the $\mathsf{asset\_desc}$ string to 512 bytes as it is a reasonable size to store metadata about the Asset, for example in JSON format. -- We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack. +In an earlier version of this ZIP, the asset description was a direct component of the +Asset Identifier, and was stored on-chain in each issuance transaction. The Asset +Identifier and issuance transactions now instead include a collision-resistant hash of the +asset description, for the following reasons: + +- A hash output (32 bytes per Issue Action) incurs lower average bandwidth costs in + issuance transactions than the asset description (previously up to 512 bytes). + +- The asset description can be longer than 512 bytes without incurring chain costs. + +- Including an asset description byte string directly in issuance transactions does not + ensure that the "user-visible" asset description is consensus-visible, because the byte + string could itself be a hash of another off-chain description (even if the consensus + rules had required it to be a Unicode string instead of only recommending it). + +- The lack of key rotation in this issuance protocol means that it is not sufficient to + mark an $\mathsf{ik}$ as trusted and then accept whatever asset descriptions are issued + by it. Each Asset Identifier needs to be independently verified, which requires some + out-of-band protocol that can also convey the corresponding asset description. + +- If issuance transactions include the asset descriptions directly, wallets will discover + them during scanning. This is an "attractive nuisance" because it would result in + wallets being more likely to expose the asset description directly to users without any + verification that the received asset has the value that a user might expect from that + description. By instead using a collision-resistant hash of an asset description, + wallets are forced to look up the corresponding asset description when a payment is + received in an unknown asset. That lookup can be mediated by a trusted party or common + trusted registry of known assets, or else will need to be approved directly by a user + who can personally assert their interest in that specific asset. Rationale for Global Issuance State ----------------------------------- diff --git a/zips/zip-0230.rst b/zips/zip-0230.rst index df7948497..21f03babe 100644 --- a/zips/zip-0230.rst +++ b/zips/zip-0230.rst @@ -367,11 +367,7 @@ An issuance action, ``IssueAction``, is the instance of issuing a specific Custo +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | +=============================+==========================+===========================================+=====================================================================+ -|``varies`` |``assetDescSize`` |``compactSize`` |The length of the asset description string in bytes. | -+-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ -|``assetDescSize`` |``asset_desc`` |``byte[assetDescSize]`` |A byte sequence of length ``assetDescSize`` bytes which SHOULD be a | -| | | |well-formed UTF-8 code unit sequence according to Unicode 15.0.0 | -| | | |or later. | +|``32`` |``assetDescHash`` |``byte[32]`` |A hash of the description of the Custom Asset. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ |``varies`` |``nNotes`` |``compactSize`` |The number of notes in the Issuance Action. | +-----------------------------+--------------------------+-------------------------------------------+---------------------------------------------------------------------+ From 9c32e1374ca1a1995ecd9985899502ef7123dbd1 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 6 Feb 2025 03:48:44 +0000 Subject: [PATCH 06/22] Render manually, while the CI-based rendering is broken --- rendered/zip-0227.html | 117 ++++++++++++++++++++--------------------- rendered/zip-0230.html | 14 ++--- 2 files changed, 61 insertions(+), 70 deletions(-) diff --git a/rendered/zip-0227.html b/rendered/zip-0227.html index d8171df05..d98cd8d05 100644 --- a/rendered/zip-0227.html +++ b/rendered/zip-0227.html @@ -268,47 +268,17 @@

Specification: Asset Identifier, Asset Digest, and Asset Base

-

For every new Asset, there MUST be a new and unique Asset Identifier, denoted +

Every Asset has a globally-unique Asset Identifier, denoted \(\mathsf{AssetId}\!\) - . We define this to be a globally unique pair - \(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{asset\_desc})\!\) - , where - \(\mathsf{ik}\) - is the issuance key and - \(\mathsf{asset\_desc}\) - is a byte string.

-

A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the OrchardZSA protocol and potentially future Zcash shielded protocols. For this Asset Identifier, we derive an Asset Digest, - \(\mathsf{AssetDigest}\!\) - , which is simply is a - \(\textsf{BLAKE2b-512}\) - hash of the Asset Identifier. From the Asset Digest, we derive a specific Asset Base within each shielded protocol using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

-

Let

-
    -
  • - \(\mathsf{asset\_desc}\) - be the asset description, which includes any information pertaining to the issuance, and is a non-empty byte sequence of at most 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
    • -
  • - \(\mathsf{ik}\) - be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.
    • -
-

Define

+ . A given Asset Identifier is used across all Zcash protocols that support ZSAs -- that is, the OrchardZSA protocol and potentially future Zcash shielded protocols.

+

From the Asset Identifier, we derive an Asset Digest

\(\mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId})),\)
-

where

-
    -
  • - \(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{asset\_desc})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{asset\_desc}\!\!\) - .
    • -
  • Note that the initial - \(\mathtt{0x00}\) - byte is a version byte.
    • -
-

Define

-
\(\mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}})\)
-

In the case of the OrchardZSA protocol, we define

-
\(\mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{AssetId}})\)

where - \(\mathsf{GroupHash}^\mathbb{P}\) - is defined as in 31.

+ \(\mathsf{EncodeAssetId}(\mathsf{AssetId})\) + is a canonical encoding scheme for the Asset Identifier.

+

From the Asset Digest, we derive a specific Asset Base that represents the Custom Asset within each shielded protocol:

+
\(\mathsf{AssetBase_{AssetId}} := \mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}})\)
+

This Asset Base is included in shielded notes within the shielded protocol.

The relations between the Asset Identifier, Asset Digest, and Asset Base are shown in the following diagram:

@@ -319,13 +289,38 @@ (resp. \(\mathsf{Protocol}\!\) ) in the subscript (resp. superscript) when the Asset Identifier (resp. Protocol) is clear from the context.

-

Wallets MUST NOT display just the - \(\mathsf{asset\_desc}\) - string to their users as the name of the Asset. Some possible alternatives include:

-
    -
  • Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
    • -
  • The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets.
    • -
+

ZIP 227 Asset Identifiers

+

Assets issued using the protocol specified in this ZIP are scoped to the + \(\mathsf{ik}\) + that issued them. Within that scope, Asset Identifier uniqueness is obtained by way of an asset description, + \(\mathsf{asset\_desc}\!\) + , which includes any information pertaining to the issuance. + \(\mathsf{asset\_desc}\) + is a non-empty byte sequence which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.

+

Define

+
\(\mathsf{AssetDescHash} := \textsf{BLAKE2b-256}(\texttt{“ZSA-AssetDescCRH”},\; \mathsf{asset\_desc}),\)
+

We define Asset Identifiers for assets issued under this ZIP as

+
\(\mathsf{AssetId} := (\mathsf{ik}, \mathsf{AssetDescHash})\)
+

and define their canonical encoding as

+
\(\mathsf{EncodeAssetId}(\mathsf{AssetId}) = \mathsf{EncodeAssetId}((\mathsf{ik}, \mathsf{AssetDescHash})) := \mathtt{0x00} || \mathsf{ik} || \mathsf{AssetDescHash}\)
+

Note that the initial + \(\mathtt{0x00}\) + byte is a version byte, enabling future ZIPs to specify alternative issuance protocols and Asset Identifiers.

+

Wallets MUST NOT display just the + \(\mathsf{asset\_desc}\) + string to their users as the name of the Asset. Some possible alternatives include:

+
    +
  • Wallets could allow clients to provide an additional configuration file that stores a one-to-one mapping of names to Asset Identifiers via a petname system. This allows clients to rename the Assets in a way they find useful. Default versions of this file with well-known Assets listed can be made available online as a starting point for clients.
    • +
  • The Asset Digest could be used as a more compact bytestring to uniquely determine an Asset, and wallets could support clients scanning QR codes to load Asset information into their wallets.
    • +
+
+

OrchardZSA Custom Assets

+

In the case of the OrchardZSA protocol, we define

+
\(\mathsf{ZSAValueBase}(\mathsf{AssetDigest_{AssetId}}) := \mathsf{GroupHash}^\mathbb{P}(\texttt{"z.cash:OrchardZSA"}, \mathsf{AssetDigest_{AssetId}})\)
+

where + \(\mathsf{GroupHash}^\mathbb{P}\) + is defined as in 31.

+

Specification: Issue Note, Issuance Action, Issuance Bundle and Issuance Protocol

Issue Note

@@ -426,13 +421,16 @@
  • encode \(\mathsf{asset\_desc}\) - as a UTF-8 byte string of size up to 512.
    • + as a UTF-8 byte string. +
  • compute + \(\mathsf{AssetDescHash}\) +
  • compute \(\mathsf{AssetDigest}\) from the issuance validating key \(\mathsf{ik}\) and - \(\mathsf{asset\_desc}\) + \(\mathsf{AssetDescHash}\) as decribed in the Specification: Asset Identifier, Asset Digest, and Asset Base section.
  • compute \(\mathsf{AssetBase}\) @@ -698,21 +696,20 @@
    • The issuance key structure is independent of the original key tree, but derived in an analogous manner (via ZIP 32). This keeps the issuance details and the Asset Identifiers consistent across multiple shielded pools. It also separates the issuance authority from the spend authority, allowing for the potential transfer of issuance authority without compromising the spend authority.
    • The Custom Asset is described via a combination of the issuance validating key and an asset description string, to preclude the possibility of two different issuers creating colliding Custom Assets.
      • -
    • The - \(\mathsf{asset\_desc}\) - is a general byte string in order to allow for a wide range of information type to be included that may be associated with the Assets. Some are: -
        -
      • links for storage such as for NFTs.
        • -
      • metadata for Assets, encoded in any format.
        • -
      • bridging information for Wrapped Assets (chain of origin, issuer name, etc)
        • -
      • information to be committed by the issuer, though not enforceable by the protocol.
        • -
      -
      • -
    • We limit the size of the - \(\mathsf{asset\_desc}\) - string to 512 bytes as it is a reasonable size to store metadata about the Asset, for example in JSON format.
    • We require non-zero fees in the presence of an issue bundle, in order to preclude the possibility of a transaction containing only an issue bundle. If a transaction includes only an issue bundle, the SIGHASH transaction hash would be computed solely based on the issue bundle. A duplicate bundle would have the same SIGHASH transaction hash, potentially allowing for a replay attack.
    +

    Hash of the asset description

    +

    In an earlier version of this ZIP, the asset description was a direct component of the Asset Identifier, and was stored on-chain in each issuance transaction. The Asset Identifier and issuance transactions now instead include a collision-resistant hash of the asset description, for the following reasons:

    +
      +
    • A hash output (32 bytes per Issue Action) incurs lower average bandwidth costs in issuance transactions than the asset description (previously up to 512 bytes).
      • +
    • The asset description can be longer than 512 bytes without incurring chain costs.
      • +
    • Including an asset description byte string directly in issuance transactions does not ensure that the "user-visible" asset description is consensus-visible, because the byte string could itself be a hash of another off-chain description (even if the consensus rules had required it to be a Unicode string instead of only recommending it).
      • +
    • The lack of key rotation in this issuance protocol means that it is not sufficient to mark an + \(\mathsf{ik}\) + as trusted and then accept whatever asset descriptions are issued by it. Each Asset Identifier needs to be independently verified, which requires some out-of-band protocol that can also convey the corresponding asset description.
      • +
    • If issuance transactions include the asset descriptions directly, wallets will discover them during scanning. This is an "attractive nuisance" because it would result in wallets being more likely to expose the asset description directly to users without any verification that the received asset has the value that a user might expect from that description. By instead using a collision-resistant hash of an asset description, wallets are forced to look up the corresponding asset description when a payment is received in an unknown asset. That lookup can be mediated by a trusted party or common trusted registry of known assets, or else will need to be approved directly by a user who can personally assert their interest in that specific asset.
      • +
    +

    Rationale for Global Issuance State

    It is necessary to ensure that the balance of any issued Custom Asset never becomes negative within a shielded pool, along the lines of ZIP 209 8. However, unlike for the shielded ZEC pools, there is no individual transaction field that directly corresponds to both the issued and burnt amounts for a given Asset. Therefore, we require that all nodes maintain a record of the current amount in circulation for every issued Custom Asset, and update this record based on the issuance and burn transactions processed. This allows for efficient detection of balance violations for any Asset, in which case we specify a consensus rule to reject the transaction or block.

    We limit the total issuance of any Asset to a maximum of diff --git a/rendered/zip-0230.html b/rendered/zip-0230.html index c10ed734c..f30ea2e7f 100644 --- a/rendered/zip-0230.html +++ b/rendered/zip-0230.html @@ -560,16 +560,10 @@ - varies - assetDescSize - compactSize - The length of the asset description string in bytes. - - - assetDescSize - asset_desc - byte[assetDescSize] - A byte sequence of length assetDescSize bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later. + 32 + assetDescHash + byte[32] + A hash of the description of the Custom Asset. varies From 8d224d10bef006a3cc8a0fc8c6c14cd53986c635 Mon Sep 17 00:00:00 2001 From: Kris Nuttycombe Date: Tue, 11 Feb 2025 16:49:46 -0700 Subject: [PATCH 07/22] Update zips/zip-0233.md motivation. This clarifies the "Benefits to ZEC Holders" section. Co-authored-by: Daira-Emma Hopwood --- zips/zip-0233.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/zips/zip-0233.md b/zips/zip-0233.md index 4a70c6a36..a508cf22a 100644 --- a/zips/zip-0233.md +++ b/zips/zip-0233.md @@ -68,9 +68,10 @@ design shared by Bitcoin-like systems: extending the block subsidy system, which currently has a clear final end date. 2. **Benefits to ZEC Holders:** Removing funds from circulation reduces the - circulating supply of ZEC, benefiting network users in proportion to their - holdings without requiring them to opt into any scheme, introducing extra - risk, active oversight, or accounting complexity. + circulating supply of ZEC. To the extent that this potentially contributes to + an increase in the value of remaining ZEC, it can be argued to benefit network + users in proportion to their holdings — without requiring them to opt into any + scheme, introducing extra risk, active oversight, or accounting complexity. # Specification From 00efeba93c3eeb29c5980e70380b66e4d75f4048 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 18 Feb 2025 11:09:26 +0000 Subject: [PATCH 08/22] 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 09/22] 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 a6d3eed30718ba07a525e94f8f98d783324af765 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Wed, 19 Feb 2025 23:52:01 +0000 Subject: [PATCH 10/22] Re-render HTML. Signed-off-by: Daira-Emma Hopwood --- README.rst | 8 ++-- rendered/index.html | 8 ++-- rendered/zip-0233.html | 94 +++++++++++++++++++++--------------------- rendered/zip-0234.html | 92 +++++++++++++++++++++-------------------- rendered/zip-0235.html | 81 ++++++++++++++++++------------------ 5 files changed, 146 insertions(+), 137 deletions(-) diff --git a/README.rst b/README.rst index e9376841c..5d68a1f79 100644 --- a/README.rst +++ b/README.rst @@ -156,9 +156,9 @@ written. 228 Asset Swaps for Zcash Shielded Assets Reserved 230 Version 6 Transaction Format Draft 231 Memo Bundles Draft - 233 Network Sustainability Mechanism: Burning Draft + 233 Network Sustainability Mechanism: Removing Funds From Circulation Draft 234 Network Sustainability Mechanism: Issuance Smoothing Draft - 235 Burn 60% of Transaction Fees Draft + 235 Remove 60% of Transaction Fees From Circulation Draft 245 Transaction Identifier Digests & Signature Validation for Transparent Zcash Extensions Draft 254 Deployment of the NU7 Network Upgrade Draft 302 Standardized Memo Field Format Draft @@ -283,9 +283,9 @@ Index of ZIPs 228 Asset Swaps for Zcash Shielded Assets Reserved 230 Version 6 Transaction Format Draft 231 Memo Bundles Draft - 233 Network Sustainability Mechanism: Burning Draft + 233 Network Sustainability Mechanism: Removing Funds From Circulation Draft 234 Network Sustainability Mechanism: Issuance Smoothing Draft - 235 Burn 60% of Transaction Fees Draft + 235 Remove 60% of Transaction Fees From Circulation Draft 236 Blocks should balance exactly Implemented (zcashd and zebrad) 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final diff --git a/rendered/index.html b/rendered/index.html index f06b03aa4..c0e79e8d1 100644 --- a/rendered/index.html +++ b/rendered/index.html @@ -111,9 +111,9 @@ 228 Asset Swaps for Zcash Shielded Assets Reserved 230 Version 6 Transaction Format Draft 231 Memo Bundles Draft - 233 Network Sustainability Mechanism: Burning Draft + 233 Network Sustainability Mechanism: Removing Funds From Circulation Draft 234 Network Sustainability Mechanism: Issuance Smoothing Draft - 235 Burn 60% of Transaction Fees Draft + 235 Remove 60% of Transaction Fees From Circulation Draft 245 Transaction Identifier Digests & Signature Validation for Transparent Zcash Extensions Draft 254 Deployment of the NU7 Network Upgrade Draft 302 Standardized Memo Field Format Draft @@ -219,9 +219,9 @@ 228 Asset Swaps for Zcash Shielded Assets Reserved 230 Version 6 Transaction Format Draft 231 Memo Bundles Draft - 233 Network Sustainability Mechanism: Burning Draft + 233 Network Sustainability Mechanism: Removing Funds From Circulation Draft 234 Network Sustainability Mechanism: Issuance Smoothing Draft - 235 Burn 60% of Transaction Fees Draft + 235 Remove 60% of Transaction Fees From Circulation Draft 236 Blocks should balance exactly Implemented (zcashd and zebrad) 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final diff --git a/rendered/zip-0233.html b/rendered/zip-0233.html index e486657c4..40a964bba 100644 --- a/rendered/zip-0233.html +++ b/rendered/zip-0233.html @@ -1,7 +1,7 @@ - ZIP 233: Network Sustainability Mechanism: Burning + ZIP 233: Network Sustainability Mechanism: Removing Funds From Circulation @@ -10,9 +10,10 @@ 

    ZIP: 233
-Title: Network Sustainability Mechanism: Burning
+Title: Network Sustainability Mechanism: Removing Funds From Circulation
 Owners: Jason McGee <jason@shieldedlabs.net>
         Zooko Wilcox <zooko@shieldedlabs.net>
+        Mark Henderson <mark@shieldedlabs.net>
         Tomek Piotrowski <tomek@eiger.co>
         Mariusz Pilarek <mariusz@eiger.co>
         Paul Dann <paul@eiger.co>
@@ -49,9 +50,6 @@ 
    Terminology
 
-
    “Burning” - The method by which ZEC/TAZ becomes unavailable for circulation
-on the network.
    
-
 
    \(\mathsf{MAX\_MONEY}\), as defined in § 5.3 ‘Constants’ 5,
 is the total ZEC/TAZ supply cap measured in zatoshi, corresponding to
 21,000,000 ZEC. This is slightly larger than the supply cap for the current
@@ -60,11 +58,11 @@ 
    TerminologyAbstract 
    
 
-
    This ZIP proposes the introduction of a mechanism to voluntarily burn funds,
-removing those funds entirely from circulation on the network. This mechanism,
-in combination with ZIP 234 6 and ZIP 235 7, comprises a
-long-term strategy for the sustainability of the network. We will refer to the
-combined effects of these three ZIPs as the “Network Sustainability Mechanism”.
    
+
    This ZIP proposes the introduction of a mechanism to voluntarily remove funds
+entirely from circulation on the network. This mechanism, in combination with
+ZIP 234 6 and ZIP 235 7, comprises a long-term strategy for
+the sustainability of the network. We will refer to the combined effects of
+these three ZIPs as the “Network Sustainability Mechanism”.
    
 
 
    Motivation 
    
 
@@ -72,32 +70,35 @@ 
    Motivation\(\mathsf{MAX\_MONEY}\). This lays necessary groundwork for extending the
-block subsidy system, which currently has a clear final end date.
    • -
  • Benefits to ZEC Holders: Burning funds reduces the supply of ZEC, -benefiting network users in proportion to their holdings without requiring -them to opt into any scheme, introducing extra risk, active oversight, or -accounting complexity.
    • +
  • Long Term Consensus Sustainability: By enabling the removal of funds from +circulation, the network gains the ability to create “headroom” between the +chain value and \(\mathsf{MAX\_MONEY}\). This lays necessary groundwork for +extending the block subsidy system, which currently has a clear final end +date.
    • +
  • Benefits to ZEC Holders: Removing funds from circulation reduces the +circulating supply of ZEC. To the extent that this potentially contributes to +an increase in the value of remaining ZEC, it can be argued to benefit network +users in proportion to their holdings — without requiring them to opt into any +scheme, introducing extra risk, active oversight, or accounting complexity.

    • Specification

    -

    Burn amount

    +

    Transaction Field

    -

    Each transaction gains a \(\mathsf{burn\_amount}\) property, specifying the -value in zatoshis that is burned when the transaction is mined. The burned value -subtracts from the remaining value in the “transparent transaction value pool” -as described in § 3.4 ‘Transactions and Treestates’ 8.

    +

    Each transaction gains a \(\mathsf{zip233\_amount}\) property, specifying the +value in zatoshis that is removed from circulation when the transaction is +mined. The value removed from circulation subtracts from the remaining value in +the “transparent transaction value pool” as described in § 3.4 ‘Transactions and +Treestates’ 8.

    -

    \(\mathsf{burn\_amount}\) does not result in an output being produced in any +

    \(\mathsf{zip233\_amount}\) does not result in an output being produced in any chain value pool, and therefore from the point at which the transaction is -applied to the global chain state, \(\mathsf{burn\_amount}\) is subtracted from the -issued supply. It is unavailable for circulation on the network at least through -to the end of the block in which the transaction is mined. ZIP 234 6 -specifies a potential mechanism by which the burned funds would again become -available.

    +applied to the global chain state, \(\mathsf{zip233\_amount}\) is subtracted from +the issued supply. It is unavailable for circulation on the network at least +through to the end of the block in which the transaction is mined. ZIP 234 +6 specifies a potential mechanism by which the funds removed from +circulation would again become available.

    Changes to ZIP 230 9

    @@ -117,22 +118,22 @@

    Changes to ZIP 230 Bytes Name Data Type - Description + Description 8 - burnAmount + zip233Amount uint64 - The value to be burned in this transaction, in zatoshis. + The value to be removed from circulation in this transaction, in zatoshis. -

    The \(\mathsf{burn\_amount}\) of a transaction is defined to be the value of the -burnAmount field if present, and otherwise 0.

    +

    The \(\mathsf{zip233\_amount}\) of a transaction is defined to be the value of the +zip233Amount field if present, and otherwise 0.

    Notes:

    @@ -140,31 +141,32 @@

    Changes to ZIP 230 If both this ZIP and ZIP 2002 are selected for inclusion in the same Network Upgrade, then the ambiguity in ordering of the fields added by these ZIPs would need to be resolved. -
  • Older transaction versions can continue to be supported after a network upgrade, -but burning is not possible for these transactions. For example, NU5 supports -both v4 and v5 transaction formats, for both coinbase and non-coinbase transactions.
    • +
  • Older transaction versions can continue to be supported after a network +upgrade, but removing funds from circulation is not possible for these +transactions. For example, NU5 supports both v4 and v5 transaction formats, +for both coinbase and non-coinbase transactions.

Changes to the Zcash Protocol Specification

Make a change to § 3.4 ‘Transactions and Treestates’ 8 -implementing the specification in Burn amount.

+implementing the specification in [ZIP-233 Amount].

In § 7.1 ‘Transaction Encoding and Consensus’ 11, add:

-

[NU7 onward] \(\mathsf{burn\_amount}\) MUST be in the range \(\{ 0 .. \mathsf{MAX\_MONEY} \}\).

+

[NU7 onward] \(\mathsf{zip233\_amount}\) MUST be in the range \(\{ 0 .. \mathsf{MAX\_MONEY} \}\).

Modifications relative to ZIP 244 12

Relative to the sighash algorithm defined in ZIP 244, the sighash algorithm that applies to v6 transactions differs by appending the encoding of -\(\mathsf{burn\_amount}\) to the Common Transaction Fields that are the input +\(\mathsf{zip233\_amount}\) to the Common Transaction Fields that are the input to the digest in T.1: header_digest 13:

-
 T.1f: burn_amount (8-byte little-endian burn amount)
+
 T.1f: zip233_amount (8-byte little-endian amount to remove from circulation)
@@ -181,11 +183,11 @@

RationaleNew transaction field for burn amount

+

New transaction field for amount to remove from circulation

-

An explicit value distinguishes the burned ZEC from the transaction fee. -Explicitness also ensures any arithmetic flaws in any implementations are more -likely to be observed and caught immediately.

+

An explicit value distinguishes the funds to remove from circulation from +the transaction fee. Explicitness also ensures any arithmetic flaws in any +implementations are more likely to be observed and caught immediately.

Deployment

@@ -222,7 +224,7 @@

References -

ZIP 235: Burn 60% of Transaction Fees  ↩︎

+

ZIP 235: Remove 60% of Transaction Fees From Circulation  ↩︎

  • diff --git a/rendered/zip-0234.html b/rendered/zip-0234.html index 7898fb543..fbdbb35f8 100644 --- a/rendered/zip-0234.html +++ b/rendered/zip-0234.html @@ -13,6 +13,7 @@ Title: Network Sustainability Mechanism: Issuance Smoothing Owners: Jason McGee <jason@shieldedlabs.net> Zooko Wilcox <zooko@shieldedlabs.net> + Mark Henderson <mark@shieldedlabs.net> Tomek Piotrowski <tomek@eiger.co> Mariusz Pilarek <mariusz@eiger.co> Paul Dann <paul@eiger.co> @@ -45,8 +46,8 @@

    Terminology“ZEC/TAZ” refers to the native currency of Zcash on a given network, i.e. ZEC on Mainnet and TAZ on Testnet.

    -

    The terms “Block Subsidy”, “Issuance”, and “Burning” are to be interpreted -as described in ZIP 233. 6

    +

    The terms “Block Subsidy” and “Issuance” are to be interpreted as described in +ZIP 233. 6

    Let \(\mathsf{PostBlossomHalvingInterval}\) be as defined in 7.

    @@ -74,8 +75,8 @@

    AbstractMotivation

    @@ -84,8 +85,8 @@

    MotivationRequirements
  • For any 4-year period, all paid out block subsidies are approximately equal to half of the Money Reserve at the beginning of that 4-year period, if no -ZEC is burned during those 4 years.
    • +ZEC is removed from circulation during those 4 years.

  • Decrease the short-term impact of the deployment of this ZIP on block subsidy recipients, and minimize the potential reputation risk to Zcash of changing the block subsidy amount.
    • @@ -137,42 +138,19 @@

    Parameters\(\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT} = \mathsf{TBD}\)

    +

    \(\mathsf{MoneyReserveAfter}(\mathsf{height}) =\) The value of the Money Reserve +after the specified block height.

    +

    The block height will be chosen by the following criteria:

    • It is after NU7 activation height.
      • -
    • It is calculated to be the lowest height after the second halving at -which the NSM issuance would be less than the current BTC-style issuance -neglecting any burnt ZEC (i.e. assuming the amount of ZEC burnt is -exactly 0).
      • +
    • It is calculated to be the lowest height after the second halving at which +the NSM issuance would be less than the current BTC-style issuance neglecting +any ZEC removed from circulation (i.e. assuming the amount of ZEC removed from +circulation is exactly 0).
    -

    This selection is intended to achieve Key Objective 6 while still being at -a constant, predictable height. An alternative would be to have a dynamic -“latch”-style activation, which would calculate the activation height by -testing the “less than” conditional with every block after the second halving. -We prefer the pre-defined constant height parameter, to give everyone more -time certainty at the cost of issuance level certainty.

    - -

    The difference in up-front calculation versus dynamic calculation is in -whether or not burns are accounted for (since future burns cannot be -calculated up-front). This means with the pre-defined constant parameter -approach, issuance will jump up some amount at activation. This amount -should be equivalent to all ZEC burnt prior to that height times -\(\mathsf{BLOCK\_SUBSIDY\_FRACTION}\). For example, if a total of 100,000 ZEC -were burnt prior to the pre-defined constant activation height, then at -activation the issuance would be larger than BTC-style issuance by -\(100\_000\textsf{ ZEC} \cdot \mathsf{BLOCK\_SUBSIDY\_FRACTION}\), -which we calculate equals \(0.04126\) ZEC. This example is chosen to -demonstrate that a very large burn amount (much larger than expected) would -elevate issuance by a relatively small amount. For this reason, we believe -a pre-defined constant is a better approach to achieving Key Objective 6 -than a “dynamic latch” logic because it is so much simpler to implement -and reason about.

    - -

    \(\mathsf{MoneyReserveAfter}(\mathsf{height}) =\) The value of the Money Reserve -after the specified block height.

    -

    Issuance Calculation

    At the \(\mathsf{DEPLOYMENT\_BLOCK\_HEIGHT}\), nodes should switch from the current issuance @@ -191,6 +169,31 @@

    RationaleParameters

    + +

    The selection is intended to achieve Key Objective 6 while still being at +a constant, predictable height. An alternative would be to have a dynamic +“latch”-style activation, which would calculate the activation height by +testing the “less than” conditional with every block after the second halving. +We prefer the pre-defined constant height parameter, to give everyone more +time certainty at the cost of issuance level certainty.

    + +

    The difference in up-front calculation versus dynamic calculation is +in whether or not funds removed from circulation are accounted for +(since funds removed from circulation in the future cannot be calculated +up-front). This means with the pre-defined constant parameter approach, +issuance will jump up some amount at activation. This amount should be +equivalent to all ZEC removed from circulation prior to that height times +\(\mathsf{BLOCK\_SUBSIDY\_FRACTION}\). For example, if a total of 100,000 ZEC were +burnt prior to the pre-defined constant activation height, then at activation +the issuance would be larger than BTC-style issuance by \(100\_000\textsf{ ZEC} +\cdot \mathsf{BLOCK\_SUBSIDY\_FRACTION}\), which we calculate equals \(0.04126\) +ZEC. This example is chosen to demonstrate that a very large amount removed from +circulation (much larger than expected) would elevate issuance by a relatively +small amount. For this reason, we believe a pre-defined constant is a better +approach to achieving Key Objective 6 than a “dynamic latch” logic because it is +so much simpler to implement and reason about.

    +

    BLOCK_SUBSIDY_FRACTION

    Let \(\mathsf{IntendedMoneyReserveFractionRemainingAfterFourYears} = 0.5\).

    @@ -203,9 +206,9 @@

    BLOCK_SUBSIDY_FRAC have been issued as block subsidies, thus satisfying Requirement 4.

    The largest possible value in the Money Reserve is \(\mathsf{MAX\_MONEY}\), in the -theoretically possible case that all issued funds are burned. If this happened, -the largest interim sum in the block subsidy calculation would be -\(\mathsf{MAX\_MONEY} \cdot 4126 / 10\_000\_000\_000\).

    +theoretically possible case that all issued funds are removed from circulation. +If this happened, the largest interim sum in the block subsidy calculation would +be \(\mathsf{MAX\_MONEY} \cdot 4126 / 10\_000\_000\_000\).

    This uses 62.91 bits, which is just under the 63-bit limit for signed two’s complement 64-bit integer amount types.

    @@ -243,9 +246,9 @@

    Appendix: Simulation< 
    Last block is 47917869 in ~113.88 years
    -

    indicates that, assuming that no ZEC is ever burned, the Money Reserve will be -depleted after 113.88 years, and the block subsidy will be 0 ZEC after that -point.

    +

    indicates that, assuming that no ZEC is ever removed from circulation, the Money +Reserve will be depleted after 113.88 years, and the block subsidy will be 0 ZEC +after that point.

    This fragment of the output:

    @@ -266,7 +269,8 @@

    Appen

    Deployment

    This ZIP is proposed to activate with Network Upgrade 7. 10 -It MUST be deployed at the same time or after ZIP 233 (“NSM: Burning” 6).

    +It MUST be deployed at the same time or after ZIP 233 (“NSM: Removing Funds From +Circulation” 6).

    References

    diff --git a/rendered/zip-0235.html b/rendered/zip-0235.html index c893b8541..4865735b5 100644 --- a/rendered/zip-0235.html +++ b/rendered/zip-0235.html @@ -1,7 +1,7 @@ - ZIP 235: Burn 60% of Transaction Fees + ZIP 235: Remove 60% of Transaction Fees From Circulation @@ -10,9 +10,10 @@ 
    ZIP: 235
-Title: Burn 60% of Transaction Fees
+Title: Remove 60% of Transaction Fees From Circulation
 Owners: Jason McGee <jason@shieldedlabs.net>
         Zooko Wilcox <zooko@shieldedlabs.net>
+        Mark Henderson <mark@shieldedlabs.net>
         Tomek Piotrowski <tomek@eiger.co>
         Mariusz Pilarek <mariusz@eiger.co>
         Paul Dann <paul@eiger.co>
@@ -45,58 +46,59 @@ 
    Terminology“ZEC/TAZ” refers to the native currency of Zcash on a given network, i.e.
 ZEC on Mainnet and TAZ on Testnet.
    
 
-
    The terms “Block Subsidy”, “Issuance”, and “Burning” are to be interpreted
-as described in ZIP 233. 6
    
+
    The terms “Block Subsidy” and “Issuance” are to be interpreted as described in
+ZIP 233. 6
    
 
 
    Abstract 
    
 
-
    This ZIP proposes to burn 60% of transaction fees, while the remaining 40% is
-directed as before, providing a deflationary effect, and building the groundwork
-for long-term support of the Zcash network via the new block subsidy rules
-proposed by ZIP 234 7.
    
+
    This ZIP proposes to remove 60% of transaction fees from circulation, while
+the remaining 40% is directed as before, providing a deflationary effect, and
+building the groundwork for long-term support of the Zcash network via the new
+block subsidy rules proposed by ZIP 234 7.
    
 
 
    Motivation 
    
 
-
    ZIP 233 (“Network Sustainability Mechanism: Burning” 6) describes a
-method by which ZEC can be burned to support network sustainability.
    
+
    ZIP 233 (“Network Sustainability Mechanism: Removing Funds From Circulation”
+6) describes a method by which ZEC can be removed from circulation to
+support network sustainability.
    
 
 
    By introducing a requirement that a certain proportion of transaction fees be
-burned, we ensure that ZEC will be removed from circulating supply to contribute
-to the long-term sustainability of the network as described below:
    
+removed from circulation, we aim to contribute to the long-term sustainability
+of the network as described below:
    
 
 
    Benefits to the Network 
    
 
 
      
 
    1. Network Sustainability: This mechanism involves temporarily reducing the
 supply of ZEC, similar to asset burning in Ethereum’s EIP-1559 8,
-but with long-term sustainability benefits, as the burned funds effectively
-boost future mining rewards, making it an attractive option for current and
-future Zcash users.
      2. 
+but with long-term sustainability benefits, as the funds removed from
+circulation effectively boost future mining rewards, making it an attractive
+option for current and future Zcash users.
 
    2. Incentivizing Transaction Inclusion: By maintaining a 40% share of
 transaction fees for miners, we continue incentivizing miners to prioritize
 including transactions in their blocks. This helps ensure the continued
 efficient processing of transactions and supports a robust and responsive
 network.
      3. 
-
    3. Aligning Interests: Burning transaction fees aligns the interests
-of miners with the long-term health of the network, incentivizing them
-to prioritize security and efficiency. As miners focus on maintaining a
+
    4. Aligning Interests: Removing transaction fees from circulation aligns the
+interests of miners with the long-term health of the network, incentivizing
+them to prioritize security and efficiency. As miners focus on maintaining a
 robust network, overall adoption and usage can increase, leading to higher
 transaction volumes in the long run. This structure discourages short-term
 profit-seeking behaviors, as miners benefit more from a stable and thriving
 ecosystem than from engaging in malicious activities that could undermine the
 network’s reputation and security.
      5. 
-
    5. Future-Proofing the Network: Burning a portion of transaction fees
-is a forward-looking approach that prepares the Zcash network for future
-challenges and opportunities. It establishes a financial buffer that can be
-instrumental in addressing unforeseen issues and seizing strategic advantages
-as the Zcash ecosystem evolves.
      6. 
+
    6. Future-Proofing the Network: Removing a portion of transaction fees from
+circulation is a forward-looking approach that prepares the Zcash network for
+future challenges and opportunities. It establishes a financial buffer that
+can be instrumental in addressing unforeseen issues and seizing strategic
+advantages as the Zcash ecosystem evolves.
      7. 
 
    
 
 
    Requirements 
    
 
 
      
 
    • For each block, at least 60% (rounded down) of the total fees are to be
-burned.
      • 
+removed from circulation.
 
    • No restrictions are placed on the destination of the remaining proportion of
 fees.
      • 
 
    • Any fractions are rounded in favor of the miner.
      • 
@@ -106,7 +108,7 @@ 
      SpecificationConsensus Rule Changes 
      
 
-
      For a given block, the coinbase transaction MUST have a \(\mathsf{burn\_amount}\),
+
      For a given block, the coinbase transaction MUST have a \(\mathsf{zip233\_amount}\),
 as defined in 6, that is greater than or equal to
 \(\mathsf{floor}(\mathsf{transactionFees} \cdot 6 / 10)\).
      
 
@@ -125,14 +127,14 @@ 
      RationaleRationale for requiring the coinbase transaction to be v6 or later 
      
 
-
      There is no explicit mechanism in prior transaction versions to burn the
-required funds. Since \(\mathsf{burn\_amount} = 0\) for transaction versions
-prior to v6, absent the rule about the coinbase transaction version it
-would be technically possible to satisfy the constraint on \(\mathsf{burn\_amount}\)
-with earlier versions than v6, but only when \(\mathsf{transactionFees} = 0\).
-That would introduce a corner case in the transaction consensus rules that
-is not useful, since it is expected that the \(\mathsf{transactionFees}\)
-will normally be non-zero.
      
+
      There is no explicit mechanism in prior transaction versions to remove
+the required funds from circulation. Since \(\mathsf{zip233\_amount} = 0\)
+for transaction versions prior to v6, absent the rule about the coinbase
+transaction version it would be technically possible to satisfy the constraint
+on \(\mathsf{zip233\_amount}\) with earlier versions than v6, but only when
+\(\mathsf{transactionFees} = 0\). That would introduce a corner case in the
+transaction consensus rules that is not useful, since it is expected that the
+\(\mathsf{transactionFees}\) will normally be non-zero.
      
 
 
      Estimated impact on miners 
      
 
@@ -145,7 +147,8 @@ 
      Estimated impact
 Extrapolating to a year, we would expect 351.44 ZEC in fees paid to miners over
 a year.
      
 
-
      If 60% of these fees burned, that would be 210.864 ZEC per year. 11
      
+
      If 60% of these fees are removed from circulation, that would be 210.864 ZEC per
+year. 11
      
 
 
      Considerations for the Future 
      
 
@@ -159,8 +162,8 @@ 
      Considerations
 reconsider the 60/40 split. However, this will likely not be the case for the
 next 8–10 years due to forecasts based on issuance models and network traffic.
      
 
-
      Further ZIPs may be proposed to burn ZEC in various ways to support network
-sustainability, including but not limited to:
      
+
      Further ZIPs may be proposed to remove ZEC from circulation in various ways to
+support network sustainability, including but not limited to:
      
 
 
        
 
      • ZSA fees
        • 
@@ -173,8 +176,8 @@ 
        Considerations
 
        Deployment 
        
 
 
        The implementation of this ZIP MUST be deployed at the same time or after
-ZIP 233 (“NSM: Burning” 6), and ZIP 234 (“NSM: Issuance Smoothing”
-7).
        
+ZIP 233 (“NSM: Removing Funds From Circulation” 6), and ZIP 234 (“NSM:
+Issuance Smoothing” 7).
        
 
 
        References 
        
 
@@ -203,7 +206,7 @@ 
        References
-
        ZIP 233: Network Sustainability Mechanism: Burning  ↩︎
        
+
        ZIP 233: Network Sustainability Mechanism: Removing Funds From Circulation  ↩︎
        
 
 
 
      • 

From 7277edd2a84a660bc2465e84cc4a4a40cab02d40 Mon Sep 17 00:00:00 2001
From: Daira-Emma Hopwood 
Date: Wed, 12 Feb 2025 17:59:44 +0000
Subject: [PATCH 11/22] Add registered child key derivation with support for
 tags, and a requirement to document the usage in a ZIP.

Signed-off-by: Daira-Emma Hopwood 
---
 rendered/zip-0032.html | 306 ++++++++++++++++++++++++++++-------------
 zips/zip-0032.rst      | 150 +++++++++++++++-----
 2 files changed, 328 insertions(+), 128 deletions(-)

diff --git a/rendered/zip-0032.html b/rendered/zip-0032.html
index d4dd53635..5bdee9043 100644
--- a/rendered/zip-0032.html
+++ b/rendered/zip-0032.html
@@ -28,9 +28,10 @@
         
        
         
        Terminology 
        
             
        The key words "MUST", "MUST NOT", "SHOULD", "RECOMMENDED", and "MAY" in this document are to be interpreted as described in BCP 14 1 when, and only when, they appear in all capitals.
        
-            
        "Jubjub" refers to the elliptic curve defined in 15.
        
+            
        "Jubjub" refers to the elliptic curve defined in 14.
        
+            
        A "cryptovalue" is a high-entropy value used in a cryptographic protocol that is not necessarily a key.
        
             
        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 10.
        
+            
        The terms "Testnet" and "Mainnet" are to be interpreted as described in section 3.12 of the Zcash Protocol Specification 9.
        
         
        
         
        Abstract 
        
             
        This proposal defines a mechanism for extending hierarchical deterministic wallets, as described in BIP 32 2, to support Zcash's shielded addresses.
        
@@ -54,7 +55,7 @@
             
        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 9. They are reproduced here for convenience:
        
+            
        Most of the notation and functions used in this ZIP are defined in the Zcash protocol specification 8. They are reproduced here for convenience:
        
             
          
                 
        • 
                     \(\mathsf{truncate}_k(S)\)
@@ -106,7 +107,7 @@
                     \(\mathsf{repr}_\mathbb{J}(P)\)
                  is the representation of the Jubjub elliptic curve point
                     \(P\)
-                 as a bit sequence, defined in 15.
          • 
+                 as a bit sequence, defined in 14.
                 
        • 
                     \(\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
@@ -146,9 +147,9 @@
                     \(d\)
                  to a base point on the Jubjub elliptic curve, or to
                     \(\bot\)
-                 if the diversifier is invalid. It is instantiated in 13.
          • 
+                 if the diversifier is invalid. It is instantiated in 12.
             
        
-            
        The following algorithm standardized in 22 is used:
        
+            
        The following algorithm standardized in 21 is used:
        
             
          
                 
        • 
                     \(\mathsf{FF1}\text{-}\mathsf{AES256.Encrypt}(key, tweak, x)\)
@@ -271,7 +272,7 @@
                         \(\mathsf{nsk}_m\!\)
                     , and
                         \(\mathsf{ovk}_m\)
-                     via the standard Sapling derivation 11:
+                     via the standard Sapling derivation 10:
                         
            
                             
          • 
                                 \(\mathsf{ask}_m = \mathsf{ToScalar^{Sapling}}(\mathsf{PRF^{expand}}(\mathsf{sk}_m, [\mathtt{0x00}]))\)
@@ -305,7 +306,7 @@
                     \(0\!\)
                 , or if the corresponding
                     \(\mathsf{ivk}\)
-                 derived as specified in 11 is
+                 derived as specified in 10 is
                     \(0\!\)
                 .
            
             
        
@@ -336,7 +337,7 @@
                                     \((\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 11.
        • 
+                                 as described in 10.
                             
      
                         
                         
    • Split
@@ -380,16 +381,16 @@
                         \(0\!\)
                     , or if the corresponding
                         \(\mathsf{ivk}\)
-                     derived as specified in 11 is
+                     derived as specified in 10 is
                         \(0\!\)
                     .

    Deriving a child extended full viewing key

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

    + be as defined in 10.

    \(\mathsf{CKDfvk}((\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})\) @@ -446,7 +447,7 @@ \(\mathsf{ak}_i\) is the zero point of Jubjub, or if the corresponding \(\mathsf{ivk}\) - derived as specified in 11 is + derived as specified in 10 is \(0\!\) .

    @@ -462,7 +463,7 @@ \(\mathsf{ak}\) and \(\mathsf{nk}\) - as specified in 11. + as specified in 10.
  • Let \(I = \textsf{BLAKE2b-256}(\texttt{“Zcash\_SaplingInt”}, \mathsf{EncodeExtFVKParts}(\mathsf{ak}, \mathsf{nk}, \mathsf{ovk}, \mathsf{dk}))\!\) .
    • @@ -490,14 +491,14 @@ \(\mathsf{ak}\) is the zero point of Jubjub, or if the corresponding \(\mathsf{ivk}\) - derived as specified in 11 is + derived as specified in 10 is \(0\!\) .

    Deriving a Sapling internal full viewing key

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

    + be as defined in 10.

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

    @@ -540,12 +541,12 @@
    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.

    +

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

    Note that the internal extended key is invalid if \(\mathsf{ak}\) is the zero point of Jubjub, or if the corresponding \(\mathsf{ivk_{internal}}\) - derived from the internal full viewing key as specified in 11 is + derived from the internal full viewing key as specified in 10 is \(0\!\) .

    @@ -582,6 +583,7 @@

    Specification: Hardened-only key derivation

    The derivation mechanism for Sapling addresses specified above incurs significant complexity to support non-hardened derivation. In the several years since Sapling was deployed, we have seen no use cases for non-hardened derivation appear. With that in mind, we now have a general hardened-only derivation process that retains compatibility with existing derivation path semantics (to enable deriving the same path across multiple contexts).

    +

    The functions defined in this section are intended for internal use by context-specific mechanisms in subsequent sections, rather than for direct use.

    Instantiation

    Let \(\mathsf{Context}\) @@ -631,21 +633,58 @@

    Hardened-only child key derivation

    +

    As well as the integer child index + \(i\!\) + , the child key derivation function defined here supports a byte sequence + \(\mathsf{tag}\) + and a + \(\mathsf{full\_width\_leaf}\) + flag ( + \(\!0\) + representing + \(\mathsf{false}\!\) + , + \(1\) + representing + \(\mathsf{true}\!\) + ). Each triple + \((i, \mathsf{tag}, \mathsf{full\_width\_leaf})\) + produces an independent output.

    +

    The + \(\mathsf{tag}\) + and + \(\mathsf{full\_width\_leaf}\) + inputs are reserved for use by Registered child key derivation; for other uses + \(\mathsf{tag}\) + MUST be + \([\,]\) + and + \(\mathsf{full\_width\_leaf}\) + MUST be + \(\mathsf{false}\) + ( + \(\!0\!\) + ).

    - \(\mathsf{CKDh}^\mathsf{Context}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)\) - \(\rightarrow (\mathsf{sk}_i, \mathsf{c}_i)\) + \(\mathsf{CKDh}^\mathsf{Context}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{full\_width\_leaf})\) + \(\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})\) :

      -
    • Check whether - \(i \geq 2^{31}\) - (whether the child is a hardened key). -
        -
      • If so (hardened child): let - \(I = \mathsf{PRF^{expand}}(\mathsf{c}_{par}, [\mathsf{Context.CKDDomain}]\,||\,\mathsf{sk}_{par}\,||\,\mathsf{I2LEOSP}_{32}(i))\!\) - .
        • -
      • If not (normal child): return failure.
        • -
      -
      • +
    • If + \(i < 2^{31}\) + (non-hardened child index): return failure.
      • +
    • If + \(tag = [\,]\) + and + \(\mathsf{full\_width\_leaf} = \mathsf{false}\!\) + , then let + \(\mathsf{leaf} = [\,]\!\) + , otherwise let + \(\mathsf{leaf} = [\mathsf{full\_width\_leaf}]\!\) + .
      • +
    • Let + \(I = \mathsf{PRF^{expand}}(\mathsf{c}_{par}, [\mathsf{Context.CKDDomain}]\,||\,\mathsf{sk}_{par}\,||\,\mathsf{I2LEOSP}_{32}(i)\,||\,\mathsf{leaf}\,||\,\mathsf{tag})\!\) + .
    • Split \(I\) into two 32-byte sequences, @@ -653,18 +692,8 @@ and \(I_R\!\) .
      • -
    • Use - \(I_L\) - as the child secret key - \(\mathsf{sk}_i\!\) - .
      • -
    • Use - \(I_R\) - as the child chain code - \(\mathsf{c}_i\!\) - .
    • Return - \((\mathsf{sk}_i, \mathsf{c}_i)\!\) + \((I_L, I_R)\!\) .
    @@ -707,10 +736,10 @@ :

    • Return - \(\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)\) + \(\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], \mathsf{false})\)
    -

    Note that the resulting child spending key may produce an invalid external FVK, as specified in 12, with small probability. The corresponding internal FVK derived as specified in the next section may also be invalid with small probability.

    +

    Note that the resulting child spending key may produce an invalid external FVK, as specified in 11, with small probability. The corresponding internal FVK derived as specified in the next section may also be invalid with small probability.

    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.

    @@ -718,7 +747,7 @@ \(\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.

    + be the corresponding external full viewing key, obtained as specified in 11.

    Define \(\mathsf{DeriveInternalFVK^{Orchard}}(\mathsf{ak}, \mathsf{nk}, \mathsf{rivk})\) as follows:

    @@ -727,7 +756,7 @@ \(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}))\!\) + \(\mathsf{rivk_{internal}} = \mathsf{ToScalar^{Orchard}}(\mathsf{PRF^{expand}}(K, [\mathtt{0x83}] \,||\, \mathsf{I2LEOSP_{256}}(\mathsf{ak}) \,||\, \mathsf{I2LEOSP_{256}}(\mathsf{nk})))\!\) .
  • Return \((\mathsf{ak}, \mathsf{nk}, \mathsf{rivk_{internal}})\!\) @@ -746,13 +775,13 @@ \(\mathsf{ivk_{internal}}\) and \(\mathsf{ovk_{internal}}\) - fields being derived, as specified in 12 and shown in the following diagram:

    + fields being derived, as specified in 11 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.

    -

    Note that the resulting FVK may be invalid, as specified in 12.

    +

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

    +

    Note that the resulting FVK may be invalid, as specified in 11.

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

    @@ -790,54 +819,129 @@

    -

    Specification: Arbitrary key derivation

    -

    In some contexts there is a need for deriving arbitrary keys with the same derivation path as existing key material (for example, deriving an arbitrary account-level key), without the need for ecosystem-wide coordination. The following instantiation of the hardened key generation process may be used for this purpose.

    +

    Specification: Registered key derivation

    +

    In the context of a particular application protocol defined by a ZIP, there is sometimes a need to define an HD subtree that will not collide with keys derived for other protocols, as far as that is possible to assure by following the ZIP process 22.

    +

    Within this subtree, the application protocol may use derivation paths related to those used for existing key material — for example, to derive an account-level key. The following instantiation of the hardened key generation process may be used for this purpose.

    +

    It is strongly RECOMMENDED that implementors ensure that documentation of the usage and derivation paths of the application protocol's key tree in the corresponding ZIP is substantially complete, before public deployment of software or hardware using this mechanism. The ZIP process allows for subsequent updates and corrections.

    Let \(\mathsf{ContextString}\) be a globally-unique non-empty sequence of at most 252 bytes that identifies the desired context.

    We instantiate the hardened key generation process with the following constants:

    • - \(\mathsf{Arbitrary.MKGDomain} = \texttt{“ZcashArbitraryKD”}\) + \(\mathsf{Registered.MKGDomain} = \texttt{“ZIPRegistered\_KD”}\) +
      • +
    • + \(\mathsf{Registered.CKDDomain} = \mathtt{0xAC}\) +
      • +
    +

    Registered subtree root key generation

    +

    Let + \(S\) + be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes.

    +

    The registered subtree root is obtained as:

    +

    + \(\mathsf{RegKD}(\mathsf{ContextString}, \mathsf{S}, \mathsf{ZipNumber})\) + \(\rightarrow (\mathsf{sk}_{subtree}, \mathsf{c}_{subtree})\) + :

    +
      +
    • Let + \((\mathsf{sk}_{m}, \mathsf{c}_{m}) = \mathsf{MKGh}^\mathsf{Registered}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)\!\) + .
      • +
    • Return + \(\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{m}, \mathsf{c}_{m}), \mathsf{ZipNumber} + 2^{31}, [\,], \mathsf{false})\!\) + .
      • +
    +

    Note: The intermediate key + \((\mathsf{sk}_{m}, \mathsf{c}_{m})\) + would grant the ability to derive the subtree root for application protocols defined in any ZIP using the same + \(\mathsf{ContextString}\) + and seed. This is a potentially dangerous scope of grant since it cannot be known what future protocols will use this mechanism; therefore, + \((\mathsf{sk}_{m}, \mathsf{c}_{m})\) + SHOULD NOT be used or stored directly without careful consideration of security consequences.

    +
    +

    Registered child key derivation

    +

    As well as the integer child index + \(i\!\) + , the child key derivation function defined here supports a byte sequence + \(\mathsf{tag}\!\) + ; each pair + \((i, \mathsf{tag})\) + produces a different child key. If an explicit tag is not required, + \(\mathsf{tag}\) + is set to the empty byte sequence.

    +

    Note: The tag MUST use an unambiguous encoding within the given context. It is RECOMMENDED to use a prefix-free encoding, which may require the use of length fields if multiple fields need to be encoded.

    +

    + \(\mathsf{CKDreg}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})\) + \(\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})\) + :

    +
      +
    • Return + \(\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{false})\!\) + .
      • +
    +
    +

    Full-width child cryptovalue derivation

    +

    If the application protocol requires a 64-byte cryptovalue (for example, to avoid an entropy bottleneck in its subsequent operations), then a similar process to Registered child key derivation above can be used to obtain such a cryptovalue at a given child index; again with optional tag. The same considerations about encoding of the + \(\mathsf{tag}\) + apply as above.

    +

    + \(\mathsf{CKDfw}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})\) + \(\rightarrow \mathsf{K}_{child}\) + :

    +
      +
    • Let + \((I_L, I_R) = \mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{true})\!\) + .
      • +
    • Return + \(I_L\,||\,I_R\!\) + .
      • +
    +
    +
    +

    Specification: Ad-hoc key derivation (deprecated)

    +

    For compatibility with existing deployments, we also define a mechanism to derive ad-hoc key trees for private use by applications, without ecosystem coordination. This was called "arbitrary key derivation" in previous iterations of this ZIP, but that term caused confusion as to the applicability of the mechanism.

    +

    Since there is no guarantee of non-collision between different application protocols, and no way to tie these key trees to well-defined specification or documentation processes, use of this mechanism is NOT RECOMMENDED for new protocols.

    +

    Let + \(\mathsf{ContextString}\) + be a globally-unique non-empty sequence of at most 252 bytes that identifies the desired context.

    +

    We instantiate the hardened key derivation process with the following constants:

    +
      +
    • + \(\mathsf{Adhoc.MKGDomain} = \texttt{“ZcashArbitraryKD”}\)
    • - \(\mathsf{Arbitrary.CKDDomain} = \mathtt{0xAB}\) + \(\mathsf{Adhoc.CKDDomain} = \mathtt{0xAB}\)
    -

    Arbitrary master key generation

    +

    Ad-hoc master key generation (deprecated)

    Let \(S\) be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes.

    -

    The master extended arbitrary key is:

    +

    The master extended ad-hoc key is:

    - \(m_\mathsf{Arbitrary} = \mathsf{MKGh}^\mathsf{Arbitrary}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)\!\) + \(m_\mathsf{Adhoc} = \mathsf{MKGh}^\mathsf{Adhoc}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)\!\) .

    -

    Arbitrary child key derivation

    +

    Ad-hoc child key derivation (deprecated)

    \(\mathsf{CKDarb}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)\) \(\rightarrow (\mathsf{sk}_i, \mathsf{c}_i)\) :

    • Return - \(\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)\!\) + \(\mathsf{CKDh}^\mathsf{Adhoc}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], \mathsf{false})\!\) .
    -

    If the context requires a 64-byte key (for example, to avoid an entropy bottleneck in its particular subsequent operations), and +

    Note: a previous iteration of this ZIP suggested that, if \(i\) - is the last element of an HD path, the concatenation + is the last element of an HD path (i.e. no extension of this path is used), then the concatenation \(\mathsf{sk}_i\,||\,\mathsf{c}_i\) - MAY be used as a key. In this case, - \((\mathsf{sk}_i, \mathsf{c}_i)\) - MUST NOT be given as input to - \(\mathsf{CKDarb}\) - (this is a restatement of the requirement that - \(i\) - is the last element of an HD path).

    + could be used as a 64-bit key. This is NOT RECOMMENDED, because it is difficult to define safe APIs that enforce the restriction that a given node in the key tree must not be used both in this way and to derive further child keys. Full-width child cryptovalue derivation provides a safe way to obtain the same functionality for new application protocols.

    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

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

      @@ -850,7 +954,7 @@ ) 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\!\) @@ -859,7 +963,7 @@ \(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\) @@ -881,7 +985,7 @@ 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:

    • \(m_\mathsf{Sapling} / purpose' / coin\_type' / account' / address\_index\!\) @@ -913,7 +1017,7 @@

      Sapling Full Viewing Key Fingerprints and Tags

      A "Sapling full viewing key fingerprint" of a full viewing key with raw encoding \(\mathit{FVK}\) - (as specified in 18) is given by:

      + (as specified in 17) is given by:

      • \(\mathsf{BLAKE2b}\text{-}\mathsf{256}(\texttt{“ZcashSaplingFVFP”}, \mathit{FVK})\!\) @@ -925,7 +1029,7 @@

        Orchard Full Viewing Key Fingerprints and Tags

        An "Orchard full viewing key fingerprint" of a full viewing key with raw encoding \(\mathit{FVK}\) - (as specified in 20) is given by:

        + (as specified in 19) is given by:

        • \(\mathsf{BLAKE2b}\text{-}\mathsf{256}(\texttt{“ZcashOrchardFVFP”}, \mathit{FVK})\!\) @@ -950,7 +1054,7 @@

      Specification: Key Encodings

      -

      The following encodings are analogous to the xprv and xpub encodings defined in BIP 32 for transparent keys and addresses. Each key type has a raw representation and a Bech32 7 encoding.

      +

      The following encodings are analogous to the xprv and xpub encodings defined in BIP 32 for transparent keys and addresses. Each key type has a raw representation and a Bech32 7 encoding.

      Sapling extended spending keys

      A Sapling extended spending key \((\mathsf{ask, nsk, ovk, dk, c})\!\) @@ -1042,7 +1146,7 @@ \(0\!\) .

      When encoded as Bech32, the Human-Readable Part is secret-orchard-extsk-main for Mainnet, or secret-orchard-extsk-test for Testnet.

      -

      We define this encoding for completeness, however given that it includes the capability to derive child spending keys, we expect that most wallets will only expose the regular Orchard spending key encoding to users 21.

      +

      We define this encoding for completeness, however given that it includes the capability to derive child spending keys, we expect that most wallets will only expose the regular Orchard spending key encoding to users 20.

      Values reserved due to previous specification for Sprout

      @@ -1067,7 +1171,7 @@

    Test Vectors

    -

    TBC

    +

    Test vectors are available at <https://github.com/zcash/zcash-test-vectors> in the sapling_zip32, sapling_zip32_hard, orchard_zip32, zip_0032_registered, and zip_0032_arbitrary files for each format.

    Reference Implementation

    diff --git a/zips/zip-0032.rst b/zips/zip-0032.rst index ebf2b6f0c..4beb20ff1 100644 --- a/zips/zip-0032.rst +++ b/zips/zip-0032.rst @@ -25,6 +25,8 @@ interpreted as described in BCP 14 [#BCP14]_ when, and only when, they appear in "Jubjub" refers to the elliptic curve defined in [#protocol-jubjub]_. +A "cryptovalue" is a high-entropy value used in a cryptographic protocol that is not necessarily a key. + 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. @@ -365,6 +367,9 @@ non-hardened derivation appear. With that in mind, we now have a general hardene process that retains compatibility with existing derivation path semantics (to enable deriving the same path across multiple contexts). +The functions defined in this section are intended for internal use by context-specific mechanisms in +subsequent sections, rather than for direct use. + Instantiation ------------- @@ -397,18 +402,22 @@ $\mathsf{MKGh}^\mathsf{Context}(\mathsf{IKM}) \rightarrow (\mathsf{sk}_m, \maths Hardened-only child key derivation ---------------------------------- -$\mathsf{CKDh}^\mathsf{Context}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)$ $\rightarrow (\mathsf{sk}_i, \mathsf{c}_i)$ : +As well as the integer child index $i$, the child key derivation function defined here supports a +byte sequence $\mathsf{tag}$ and a $\mathsf{full\_width\_leaf}$ flag ($\!0$ representing $\mathsf{false}$, +$1$ representing $\mathsf{true}$). Each triple $(i, \mathsf{tag}, \mathsf{full\_width\_leaf})$ produces +an independent output. -- Check whether $i \geq 2^{31}$ (whether the child is a hardened key). +The $\mathsf{tag}$ and $\mathsf{full\_width\_leaf}$ inputs are reserved for use by `Registered child key derivation`_; +for other uses $\mathsf{tag}$ MUST be $[\,]$ and $\mathsf{full\_width\_leaf}$ MUST be $\mathsf{false}$ ($\!0$). - - If so (hardened child): let - $I = \mathsf{PRF^{expand}}(\mathsf{c}_{par}, [\mathsf{Context.CKDDomain}]\,||\,\mathsf{sk}_{par}\,||\,\mathsf{I2LEOSP}_{32}(i))$. - - If not (normal child): return failure. +$\mathsf{CKDh}^\mathsf{Context}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{full\_width\_leaf})$ $\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})$ : +- If $i < 2^{31}$ (non-hardened child index): return failure. +- If $tag = [\,]$ and $\mathsf{full\_width\_leaf} = \mathsf{false}$, then let $\mathsf{leaf} = [\,]$, + otherwise let $\mathsf{leaf} = [\mathsf{full\_width\_leaf}]$. +- Let $I = \mathsf{PRF^{expand}}(\mathsf{c}_{par}, [\mathsf{Context.CKDDomain}]\,||\,\mathsf{sk}_{par}\,||\,\mathsf{I2LEOSP}_{32}(i)\,||\,\mathsf{leaf}\,||\,\mathsf{tag})$. - Split $I$ into two 32-byte sequences, $I_L$ and $I_R$. -- Use $I_L$ as the child secret key $\mathsf{sk}_i$. -- Use $I_R$ as the child chain code $\mathsf{c}_i$. -- Return $(\mathsf{sk}_i, \mathsf{c}_i)$. +- Return $(I_L, I_R)$. Specification: Orchard key derivation @@ -439,7 +448,7 @@ Orchard child key derivation $\mathsf{CKDsk}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)$ $\rightarrow (\mathsf{sk}_{i}, \mathsf{c}_i)$ : -- Return $\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)$ +- Return $\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], \mathsf{false})$ Note that the resulting child spending key may produce an invalid external FVK, as specified in [#protocol-orchardkeycomponents]_, with small probability. The corresponding internal FVK @@ -462,7 +471,7 @@ Define $\mathsf{DeriveInternalFVK^{Orchard}}(\mathsf{ak}, \mathsf{nk}, \mathsf{r as follows: - 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}))$. +- Let $\mathsf{rivk_{internal}} = \mathsf{ToScalar^{Orchard}}(\mathsf{PRF^{expand}}(K, [\mathtt{0x83}] \,||\, \mathsf{I2LEOSP_{256}}(\mathsf{ak}) \,||\, \mathsf{I2LEOSP_{256}}(\mathsf{nk})))$. - Return $(\mathsf{ak}, \mathsf{nk}, \mathsf{rivk_{internal}})$. The result of applying $\mathsf{DeriveInternalFVK^{Orchard}}$ to the external full viewing @@ -513,43 +522,119 @@ valid diversifiers. The default diversifier for $(\mathsf{sk}_i, \mathsf{c}_i)$ is defined to be $d_{i,0}.$ -Specification: Arbitrary key derivation -======================================= +Specification: Registered key derivation +======================================== + +In the context of a particular application protocol defined by a ZIP, there is sometimes +a need to define an HD subtree that will not collide with keys derived for other protocols, +as far as that is possible to assure by following the ZIP process [#zip-0000]_. + +Within this subtree, the application protocol may use derivation paths related to those +used for existing key material — for example, to derive an account-level key. The following +instantiation of the hardened key generation process may be used for this purpose. -In some contexts there is a need for deriving arbitrary keys with the same derivation path as -existing key material (for example, deriving an arbitrary account-level key), without the need for -ecosystem-wide coordination. The following instantiation of the hardened key generation process may -be used for this purpose. +It is strongly RECOMMENDED that implementors ensure that documentation of the usage and +derivation paths of the application protocol's key tree in the corresponding ZIP is +substantially complete, before public deployment of software or hardware using this +mechanism. The ZIP process allows for subsequent updates and corrections. Let $\mathsf{ContextString}$ be a globally-unique non-empty sequence of at most 252 bytes that identifies the desired context. We instantiate the hardened key generation process with the following constants: -- $\mathsf{Arbitrary.MKGDomain} = \texttt{“ZcashArbitraryKD”}$ -- $\mathsf{Arbitrary.CKDDomain} = \mathtt{0xAB}$ +- $\mathsf{Registered.MKGDomain} = \texttt{“ZIPRegistered\_KD”}$ +- $\mathsf{Registered.CKDDomain} = \mathtt{0xAC}$ + +Registered subtree root key generation +-------------------------------------- + +Let $S$ be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. + +The registered subtree root is obtained as: -Arbitrary master key generation +$\mathsf{RegKD}(\mathsf{ContextString}, \mathsf{S}, \mathsf{ZipNumber})$ $\rightarrow (\mathsf{sk}_{subtree}, \mathsf{c}_{subtree})$ : + +- Let $(\mathsf{sk}_{m}, \mathsf{c}_{m}) = \mathsf{MKGh}^\mathsf{Registered}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)$. +- Return $\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{m}, \mathsf{c}_{m}), \mathsf{ZipNumber} + 2^{31}, [\,], \mathsf{false})$. + +Note: The intermediate key $(\mathsf{sk}_{m}, \mathsf{c}_{m})$ would grant the ability to derive the +subtree root for application protocols defined in *any* ZIP using the same $\mathsf{ContextString}$ +and seed. This is a potentially dangerous scope of grant since it cannot be known what future +protocols will use this mechanism; therefore, $(\mathsf{sk}_{m}, \mathsf{c}_{m})$ SHOULD NOT be +used or stored directly without careful consideration of security consequences. + +Registered child key derivation ------------------------------- +As well as the integer child index $i$, the child key derivation function defined here supports a +byte sequence $\mathsf{tag}$; each pair $(i, \mathsf{tag})$ produces a different child key. If an +explicit tag is not required, $\mathsf{tag}$ is set to the empty byte sequence. + +Note: The tag MUST use an unambiguous encoding within the given context. It is RECOMMENDED to use +a prefix-free encoding, which may require the use of length fields if multiple fields need to be +encoded. + +$\mathsf{CKDreg}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})$ $\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})$ : + +- Return $\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{false})$. + +Full-width child cryptovalue derivation +--------------------------------------- + +If the application protocol requires a 64-byte cryptovalue (for example, to avoid an entropy +bottleneck in its subsequent operations), then a similar process to `Registered child key derivation`_ +above can be used to obtain such a cryptovalue at a given child index; again with optional tag. +The same considerations about encoding of the $\mathsf{tag}$ apply as above. + +$\mathsf{CKDfw}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})$ $\rightarrow \mathsf{K}_{child}$ : + +- Let $(I_L, I_R) = \mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{true})$. +- Return $I_L\,||\,I_R$. + + +Specification: Ad-hoc key derivation (deprecated) +================================================= + +For compatibility with existing deployments, we also define a mechanism to derive ad-hoc +key trees for private use by applications, without ecosystem coordination. This was called +"arbitrary key derivation" in previous iterations of this ZIP, but that term caused confusion +as to the applicability of the mechanism. + +Since there is no guarantee of non-collision between different application protocols, and no +way to tie these key trees to well-defined specification or documentation processes, use of +this mechanism is NOT RECOMMENDED for new protocols. + +Let $\mathsf{ContextString}$ be a globally-unique non-empty sequence of at most 252 bytes +that identifies the desired context. + +We instantiate the hardened key derivation process with the following constants: + +- $\mathsf{Adhoc.MKGDomain} = \texttt{“ZcashArbitraryKD”}$ +- $\mathsf{Adhoc.CKDDomain} = \mathtt{0xAB}$ + +Ad-hoc master key generation (deprecated) +----------------------------------------- + Let $S$ be a seed byte sequence of a chosen length, which MUST be at least 32 and at most 252 bytes. -The master extended arbitrary key is: +The master extended ad-hoc key is: -$m_\mathsf{Arbitrary} = \mathsf{MKGh}^\mathsf{Arbitrary}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)$. +$m_\mathsf{Adhoc} = \mathsf{MKGh}^\mathsf{Adhoc}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)$. -Arbitrary child key derivation ------------------------------- +Ad-hoc child key derivation (deprecated) +---------------------------------------- $\mathsf{CKDarb}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)$ $\rightarrow (\mathsf{sk}_i, \mathsf{c}_i)$ : -- Return $\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)$. +- Return $\mathsf{CKDh}^\mathsf{Adhoc}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], \mathsf{false})$. -If the context requires a 64-byte key (for example, to avoid an entropy bottleneck in its particular -subsequent operations), and $i$ is the last element of an HD path, the concatenation -$\mathsf{sk}_i\,||\,\mathsf{c}_i$ MAY be used as a key. In this case, -$(\mathsf{sk}_i, \mathsf{c}_i)$ MUST NOT be given as input to $\mathsf{CKDarb}$ (this -is a restatement of the requirement that $i$ is the last element of an HD path). +Note: a previous iteration of this ZIP suggested that, if $i$ is the last element of an HD path +(i.e. no extension of this path is used), then the concatenation $\mathsf{sk}_i\,||\,\mathsf{c}_i$ +could be used as a 64-bit key. This is NOT RECOMMENDED, because it is difficult to define safe APIs +that enforce the restriction that a given node in the key tree must not be used both in this way +and to derive further child keys. `Full-width child cryptovalue derivation`_ provides a safe way to +obtain the same functionality for new application protocols. Specification: Wallet usage @@ -756,7 +841,9 @@ for Sprout, and therefore SHOULD NOT be used in future Zcash-related specificati Test Vectors ============ -TBC +Test vectors are available at in the +`sapling_zip32`, `sapling_zip32_hard`, `orchard_zip32`, `zip_0032_registered`, and +`zip_0032_arbitrary` files for each format. Reference Implementation @@ -778,7 +865,6 @@ References .. [#bip-0044] `BIP 44: Multi-Account Hierarchy for Deterministic Wallets `_ .. [#slip-0044] `SLIP 44: Registered coin types for BIP-0044 `_ .. [#bip-0173] `BIP 173: Base32 address format for native v0-16 witness outputs `_ -.. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys `_ .. [#protocol] `Zcash Protocol Specification, Version 2022.2.19 or later [NU5 proposal] `_ .. [#protocol-networks] `Zcash Protocol Specification, Version 2022.2.19. Section 3.12: Mainnet and Testnet `_ .. [#protocol-saplingkeycomponents] `Zcash Protocol Specification, Version 2022.2.19. Section 4.2.2: Sapling Key Components `_ @@ -793,3 +879,5 @@ References .. [#protocol-orchardfullviewingkeyencoding] `Zcash Protocol Specification, Version 2022.2.19. Section 5.6.4.4: Orchard Raw Full Viewing Keys `_ .. [#protocol-orchardspendingkeyencoding] `Zcash Protocol Specification, Version 2022.2.19. Section 5.6.4.5: Orchard Spending Keys `_ .. [#NIST-SP-800-38G] `NIST Special Publication 800-38G — Recommendation for Block Cipher Modes of Operation: Methods for Format-Preserving Encryption `_ +.. [#zip-0000] `ZIP 0: ZIP Process `_ +.. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys `_ From 25f79a3a3fe2cf989d9d2e0a7771182b61ce26c1 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Sat, 15 Feb 2025 13:06:47 +0000 Subject: [PATCH 12/22] Address review comments: clarify the use of `full_width_leaf` and use the LaTeX cases environment. Signed-off-by: Daira-Emma Hopwood --- rendered/zip-0032.html | 53 +++++++++++++++++------------------------- zips/zip-0032.rst | 27 +++++++++++---------- 2 files changed, 36 insertions(+), 44 deletions(-) diff --git a/rendered/zip-0032.html b/rendered/zip-0032.html index 5bdee9043..159aceb63 100644 --- a/rendered/zip-0032.html +++ b/rendered/zip-0032.html @@ -639,32 +639,27 @@ \(\mathsf{tag}\) and a \(\mathsf{full\_width\_leaf}\) - flag ( - \(\!0\) - representing - \(\mathsf{false}\!\) - , + flag (representing a boolean value where + \(0\) + means false and \(1\) - representing - \(\mathsf{true}\!\) - ). Each triple + means true). Each triple \((i, \mathsf{tag}, \mathsf{full\_width\_leaf})\) produces an independent output.

    -

    The +

    Non-empty \(\mathsf{tag}\) - and - \(\mathsf{full\_width\_leaf}\) - inputs are reserved for use by Registered child key derivation; for other uses + inputs are reserved for use in Registered key derivation. For all other uses currently defined, \(\mathsf{tag}\) MUST be - \([\,]\) - and + \([\,]\!\) + .

    +

    The case + \(\mathsf{full\_width\_leaf} = 1\) + is reserved for use in Full-width child cryptovalue derivation (to ensure domain separation of the full-width derivation from other cases). For all other uses currently defined, \(\mathsf{full\_width\_leaf}\) MUST be - \(\mathsf{false}\) - ( - \(\!0\!\) - ).

    + \(0\!\) + .

    \(\mathsf{CKDh}^\mathsf{Context}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{full\_width\_leaf})\) \(\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})\) @@ -673,15 +668,9 @@

  • If \(i < 2^{31}\) (non-hardened child index): return failure.
    • -
  • If - \(tag = [\,]\) - and - \(\mathsf{full\_width\_leaf} = \mathsf{false}\!\) - , then let - \(\mathsf{leaf} = [\,]\!\) - , otherwise let - \(\mathsf{leaf} = [\mathsf{full\_width\_leaf}]\!\) - .
    • +
  • Let + \(\mathsf{leaf} = \begin{cases} \,[\,],&\!\!\textsf{if } \mathsf{tag} = [\,] \textsf{ and } \mathsf{full\_width\_leaf} = 0 \\ \,[\mathsf{full\_width\_leaf}],&\!\!\textsf{otherwise.}\end{cases}\) +
  • Let \(I = \mathsf{PRF^{expand}}(\mathsf{c}_{par}, [\mathsf{Context.CKDDomain}]\,||\,\mathsf{sk}_{par}\,||\,\mathsf{I2LEOSP}_{32}(i)\,||\,\mathsf{leaf}\,||\,\mathsf{tag})\!\) .
    • @@ -736,7 +725,7 @@ :

    • Return - \(\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], \mathsf{false})\) + \(\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], 0)\)

    Note that the resulting child spending key may produce an invalid external FVK, as specified in 11, with small probability. The corresponding internal FVK derived as specified in the next section may also be invalid with small probability.

    @@ -849,7 +838,7 @@ \((\mathsf{sk}_{m}, \mathsf{c}_{m}) = \mathsf{MKGh}^\mathsf{Registered}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)\!\) .
  • Return - \(\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{m}, \mathsf{c}_{m}), \mathsf{ZipNumber} + 2^{31}, [\,], \mathsf{false})\!\) + \(\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{m}, \mathsf{c}_{m}), \mathsf{ZipNumber} + 2^{31}, [\,], 0)\!\) .

    • Note: The intermediate key @@ -877,7 +866,7 @@ :

    • Return - \(\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{false})\!\) + \(\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 0)\!\) .
    @@ -891,7 +880,7 @@ :

    • Let - \((I_L, I_R) = \mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{true})\!\) + \((I_L, I_R) = \mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 1)\!\) .
    • Return \(I_L\,||\,I_R\!\) @@ -930,7 +919,7 @@ :

      • Return - \(\mathsf{CKDh}^\mathsf{Adhoc}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], \mathsf{false})\!\) + \(\mathsf{CKDh}^\mathsf{Adhoc}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], 0)\!\) .

      Note: a previous iteration of this ZIP suggested that, if diff --git a/zips/zip-0032.rst b/zips/zip-0032.rst index 4beb20ff1..11058904a 100644 --- a/zips/zip-0032.rst +++ b/zips/zip-0032.rst @@ -403,18 +403,21 @@ Hardened-only child key derivation ---------------------------------- As well as the integer child index $i$, the child key derivation function defined here supports a -byte sequence $\mathsf{tag}$ and a $\mathsf{full\_width\_leaf}$ flag ($\!0$ representing $\mathsf{false}$, -$1$ representing $\mathsf{true}$). Each triple $(i, \mathsf{tag}, \mathsf{full\_width\_leaf})$ produces -an independent output. +byte sequence $\mathsf{tag}$ and a $\mathsf{full\_width\_leaf}$ flag (representing a boolean value +where $0$ means false and $1$ means true). Each triple $(i, \mathsf{tag}, \mathsf{full\_width\_leaf})$ +produces an independent output. -The $\mathsf{tag}$ and $\mathsf{full\_width\_leaf}$ inputs are reserved for use by `Registered child key derivation`_; -for other uses $\mathsf{tag}$ MUST be $[\,]$ and $\mathsf{full\_width\_leaf}$ MUST be $\mathsf{false}$ ($\!0$). +Non-empty $\mathsf{tag}$ inputs are reserved for use in `Registered key derivation <#specification-registered-key-derivation>`_. +For all other uses currently defined, $\mathsf{tag}$ MUST be $[\,]$. + +The case $\mathsf{full\_width\_leaf} = 1$ is reserved for use in +`Full-width child cryptovalue derivation`_ (to ensure domain separation of the full-width derivation +from other cases). For all other uses currently defined, $\mathsf{full\_width\_leaf}$ MUST be $0$. $\mathsf{CKDh}^\mathsf{Context}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{full\_width\_leaf})$ $\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})$ : - If $i < 2^{31}$ (non-hardened child index): return failure. -- If $tag = [\,]$ and $\mathsf{full\_width\_leaf} = \mathsf{false}$, then let $\mathsf{leaf} = [\,]$, - otherwise let $\mathsf{leaf} = [\mathsf{full\_width\_leaf}]$. +- Let $\mathsf{leaf} = \begin{cases} \,[\,],&\!\!\textsf{if } \mathsf{tag} = [\,] \textsf{ and } \mathsf{full\_width\_leaf} = 0 \\ \,[\mathsf{full\_width\_leaf}],&\!\!\textsf{otherwise.}\end{cases}$ - Let $I = \mathsf{PRF^{expand}}(\mathsf{c}_{par}, [\mathsf{Context.CKDDomain}]\,||\,\mathsf{sk}_{par}\,||\,\mathsf{I2LEOSP}_{32}(i)\,||\,\mathsf{leaf}\,||\,\mathsf{tag})$. - Split $I$ into two 32-byte sequences, $I_L$ and $I_R$. - Return $(I_L, I_R)$. @@ -448,7 +451,7 @@ Orchard child key derivation $\mathsf{CKDsk}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)$ $\rightarrow (\mathsf{sk}_{i}, \mathsf{c}_i)$ : -- Return $\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], \mathsf{false})$ +- Return $\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], 0)$ Note that the resulting child spending key may produce an invalid external FVK, as specified in [#protocol-orchardkeycomponents]_, with small probability. The corresponding internal FVK @@ -556,7 +559,7 @@ The registered subtree root is obtained as: $\mathsf{RegKD}(\mathsf{ContextString}, \mathsf{S}, \mathsf{ZipNumber})$ $\rightarrow (\mathsf{sk}_{subtree}, \mathsf{c}_{subtree})$ : - Let $(\mathsf{sk}_{m}, \mathsf{c}_{m}) = \mathsf{MKGh}^\mathsf{Registered}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)$. -- Return $\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{m}, \mathsf{c}_{m}), \mathsf{ZipNumber} + 2^{31}, [\,], \mathsf{false})$. +- Return $\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{m}, \mathsf{c}_{m}), \mathsf{ZipNumber} + 2^{31}, [\,], 0)$. Note: The intermediate key $(\mathsf{sk}_{m}, \mathsf{c}_{m})$ would grant the ability to derive the subtree root for application protocols defined in *any* ZIP using the same $\mathsf{ContextString}$ @@ -577,7 +580,7 @@ encoded. $\mathsf{CKDreg}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})$ $\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})$ : -- Return $\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{false})$. +- Return $\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 0)$. Full-width child cryptovalue derivation --------------------------------------- @@ -589,7 +592,7 @@ The same considerations about encoding of the $\mathsf{tag}$ apply as above. $\mathsf{CKDfw}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})$ $\rightarrow \mathsf{K}_{child}$ : -- Let $(I_L, I_R) = \mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{true})$. +- Let $(I_L, I_R) = \mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 1)$. - Return $I_L\,||\,I_R$. @@ -627,7 +630,7 @@ Ad-hoc child key derivation (deprecated) $\mathsf{CKDarb}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i)$ $\rightarrow (\mathsf{sk}_i, \mathsf{c}_i)$ : -- Return $\mathsf{CKDh}^\mathsf{Adhoc}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], \mathsf{false})$. +- Return $\mathsf{CKDh}^\mathsf{Adhoc}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], 0)$. Note: a previous iteration of this ZIP suggested that, if $i$ is the last element of an HD path (i.e. no extension of this path is used), then the concatenation $\mathsf{sk}_i\,||\,\mathsf{c}_i$ From 41be02e2c971f1c0870faeea3a8ec2b081ca3e14 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Mon, 17 Feb 2025 22:42:49 +0000 Subject: [PATCH 13/22] Apply suggestions from str4d's review. Co-authored-by: Jack Grigg --- rendered/zip-0032.html | 14 +++++++++++--- zips/zip-0032.rst | 21 +++++++++++++++------ 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/rendered/zip-0032.html b/rendered/zip-0032.html index 159aceb63..a992de523 100644 --- a/rendered/zip-0032.html +++ b/rendered/zip-0032.html @@ -196,6 +196,9 @@ \(m_\mathsf{Sapling} / a / b / c\!\) .

    +

    Note: no corresponding notation is currently defined for the result of Hardened-only child key derivation with a non-empty tag and/or + \(\mathsf{full\_width\_flag}\) + set to true.

    Specification: Sapling key derivation

    Sapling extended keys

    @@ -811,7 +814,7 @@

    Specification: Registered key derivation

    In the context of a particular application protocol defined by a ZIP, there is sometimes a need to define an HD subtree that will not collide with keys derived for other protocols, as far as that is possible to assure by following the ZIP process 22.

    Within this subtree, the application protocol may use derivation paths related to those used for existing key material — for example, to derive an account-level key. The following instantiation of the hardened key generation process may be used for this purpose.

    -

    It is strongly RECOMMENDED that implementors ensure that documentation of the usage and derivation paths of the application protocol's key tree in the corresponding ZIP is substantially complete, before public deployment of software or hardware using this mechanism. The ZIP process allows for subsequent updates and corrections.

    +

    It is strongly RECOMMENDED that implementors ensure that documentation of the context string(s), and the usage and derivation paths of the application protocol's key tree in the corresponding ZIP are substantially complete, before public deployment of software or hardware using this mechanism. The ZIP process allows for subsequent updates and corrections.

    Let \(\mathsf{ContextString}\) be a globally-unique non-empty sequence of at most 252 bytes that identifies the desired context.

    @@ -866,7 +869,7 @@ :

    • Return - \(\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 0)\!\) + \(\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 0)\!\) .
    @@ -875,7 +878,7 @@ \(\mathsf{tag}\) apply as above.

    - \(\mathsf{CKDfw}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})\) + \(\mathsf{derive\_child\_cryptovalue}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})\) \(\rightarrow \mathsf{K}_{child}\) :

      @@ -886,6 +889,11 @@ \(I_L\,||\,I_R\!\) .
    +

    For the avoidance of doubt, the output of + \(\mathsf{derive\_child\_cryptovalue}\) + MUST NOT be provided as input to any key derivation function defined in ZIP 32. In particular, it MUST NOT be reinterpreted directly or indirectly as an input to + \(\mathsf{CKDh}\!\) + .

    Specification: Ad-hoc key derivation (deprecated)

    diff --git a/zips/zip-0032.rst b/zips/zip-0032.rst index 11058904a..beb401b7e 100644 --- a/zips/zip-0032.rst +++ b/zips/zip-0032.rst @@ -144,6 +144,9 @@ indicate hardened derivation ($\!i' = i + 2^{31}$) as in BIP 44 [#bip-0044]_: - $\mathsf{CKDfvk}(\mathsf{CKDfvk}(\mathsf{CKDfvk}(m_\mathsf{Sapling}, a), b), c)$ is written as $m_\mathsf{Sapling} / a / b / c$. +Note: no corresponding notation is currently defined for the result of +`Hardened-only child key derivation`_ with a non-empty tag and/or $\mathsf{full\_width\_flag}$ set to true. + Specification: Sapling key derivation ===================================== @@ -536,10 +539,11 @@ Within this subtree, the application protocol may use derivation paths related t used for existing key material — for example, to derive an account-level key. The following instantiation of the hardened key generation process may be used for this purpose. -It is strongly RECOMMENDED that implementors ensure that documentation of the usage and -derivation paths of the application protocol's key tree in the corresponding ZIP is -substantially complete, before public deployment of software or hardware using this -mechanism. The ZIP process allows for subsequent updates and corrections. +It is strongly RECOMMENDED that implementors ensure that documentation of the context +string(s), and the usage and derivation paths of the application protocol's key tree in +the corresponding ZIP are substantially complete, before public deployment of software +or hardware using this mechanism. The ZIP process allows for subsequent updates and +corrections. Let $\mathsf{ContextString}$ be a globally-unique non-empty sequence of at most 252 bytes that identifies the desired context. @@ -580,7 +584,7 @@ encoded. $\mathsf{CKDreg}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})$ $\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})$ : -- Return $\mathsf{CKDh}^\mathsf{Arbitrary}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 0)$. +- Return $\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 0)$. Full-width child cryptovalue derivation --------------------------------------- @@ -590,11 +594,16 @@ bottleneck in its subsequent operations), then a similar process to `Registered above can be used to obtain such a cryptovalue at a given child index; again with optional tag. The same considerations about encoding of the $\mathsf{tag}$ apply as above. -$\mathsf{CKDfw}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})$ $\rightarrow \mathsf{K}_{child}$ : +$\mathsf{derive\_child\_cryptovalue}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag})$ $\rightarrow \mathsf{K}_{child}$ : - Let $(I_L, I_R) = \mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 1)$. - Return $I_L\,||\,I_R$. +For the avoidance of doubt, the output of $\mathsf{derive\_child\_cryptovalue}$ +MUST NOT be provided as input to any key derivation function defined in ZIP 32. +In particular, it MUST NOT be reinterpreted directly or indirectly as an input to +$\mathsf{CKDh}$. + Specification: Ad-hoc key derivation (deprecated) ================================================= From e601318ef98e7a86a47c443ec00d543552746be7 Mon Sep 17 00:00:00 2001 From: Daira-Emma Hopwood Date: Wed, 19 Feb 2025 22:33:41 +0000 Subject: [PATCH 14/22] Change to definition of `CKDh` inspired by a change in the implementation. Co-authored-by: Jack Grigg Co-authored-by: Kris Nuttycombe Signed-off-by: Daira-Emma Hopwood --- rendered/zip-0032.html | 67 ++++++++++++++++++++---------------------- zips/zip-0032.rst | 34 ++++++++++----------- 2 files changed, 47 insertions(+), 54 deletions(-) diff --git a/rendered/zip-0032.html b/rendered/zip-0032.html index a992de523..aa84fe5f1 100644 --- a/rendered/zip-0032.html +++ b/rendered/zip-0032.html @@ -196,9 +196,11 @@ \(m_\mathsf{Sapling} / a / b / c\!\) . -

    Note: no corresponding notation is currently defined for the result of Hardened-only child key derivation with a non-empty tag and/or - \(\mathsf{full\_width\_flag}\) - set to true.

    +

    Note: no corresponding notation is currently defined for the result of Hardened-only child key derivation with non-zero + \(\mathsf{lead}\) + and/or non-empty + \(\mathsf{tag}\!\) + .

    Specification: Sapling key derivation

    Sapling extended keys

    @@ -638,33 +640,15 @@

    Hardened-only child key derivation

    As well as the integer child index \(i\!\) - , the child key derivation function defined here supports a byte sequence - \(\mathsf{tag}\) - and a - \(\mathsf{full\_width\_leaf}\) - flag (representing a boolean value where - \(0\) - means false and - \(1\) - means true). Each triple - \((i, \mathsf{tag}, \mathsf{full\_width\_leaf})\) + , the child key derivation function defined here supports a lead byte + \(\mathsf{lead}\) + (used for domain separation) and byte sequence + \(\mathsf{tag}\!\) + . Each triple + \((i, \mathsf{lead}, \mathsf{tag})\) produces an independent output.

    -

    Non-empty - \(\mathsf{tag}\) - inputs are reserved for use in Registered key derivation. For all other uses currently defined, - \(\mathsf{tag}\) - MUST be - \([\,]\!\) - .

    -

    The case - \(\mathsf{full\_width\_leaf} = 1\) - is reserved for use in Full-width child cryptovalue derivation (to ensure domain separation of the full-width derivation from other cases). For all other uses currently defined, - \(\mathsf{full\_width\_leaf}\) - MUST be - \(0\!\) - .

    - \(\mathsf{CKDh}^\mathsf{Context}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, \mathsf{full\_width\_leaf})\) + \(\mathsf{CKDh}^\mathsf{Context}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{lead}, \mathsf{tag})\) \(\rightarrow (\mathsf{sk}_{child}, \mathsf{c}_{child})\) :

      @@ -672,10 +656,10 @@ \(i < 2^{31}\) (non-hardened child index): return failure.
    • Let - \(\mathsf{leaf} = \begin{cases} \,[\,],&\!\!\textsf{if } \mathsf{tag} = [\,] \textsf{ and } \mathsf{full\_width\_leaf} = 0 \\ \,[\mathsf{full\_width\_leaf}],&\!\!\textsf{otherwise.}\end{cases}\) + \(\mathsf{lead\_enc} = \begin{cases} \,[\,],&\!\!\textsf{if } \mathsf{lead} = 0 \textsf{ and } \mathsf{tag} = [\,] \\ \,[\mathsf{lead}],&\!\!\textsf{otherwise.}\end{cases}\)
    • Let - \(I = \mathsf{PRF^{expand}}(\mathsf{c}_{par}, [\mathsf{Context.CKDDomain}]\,||\,\mathsf{sk}_{par}\,||\,\mathsf{I2LEOSP}_{32}(i)\,||\,\mathsf{leaf}\,||\,\mathsf{tag})\!\) + \(I = \mathsf{PRF^{expand}}(\mathsf{c}_{par}, [\mathsf{Context.CKDDomain}]\,||\,\mathsf{sk}_{par}\,||\,\mathsf{I2LEOSP}_{32}(i)\,||\,\mathsf{lead\_enc}\,||\,\mathsf{tag})\!\) .
    • Split \(I\) @@ -688,6 +672,19 @@ \((I_L, I_R)\!\) .
    +

    Note that in the input to + \(\mathsf{PRF^{expand}}\!\) + , the case + \(\mathsf{lead} = 0\) + and + \(\mathsf{tag} = [\,]\) + is encoded in a way compatible with the definition of + \(\mathsf{CKDh}\) + in previous versions of this specification (before + \(\mathsf{lead}\) + and + \(\mathsf{tag}\) + were added).

    Specification: Orchard key derivation

    @@ -728,7 +725,7 @@ :

    • Return - \(\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, [\,], 0)\) + \(\mathsf{CKDh}^\mathsf{Orchard}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, 0, [\,])\)

    Note that the resulting child spending key may produce an invalid external FVK, as specified in 11, with small probability. The corresponding internal FVK derived as specified in the next section may also be invalid with small probability.

    @@ -841,7 +838,7 @@ \((\mathsf{sk}_{m}, \mathsf{c}_{m}) = \mathsf{MKGh}^\mathsf{Registered}([\mathsf{length}(\mathsf{ContextString})]\,||\,\mathsf{ContextString}\,||\,[\mathsf{length}(S)]\,||\,S)\!\) .
  • Return - \(\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{m}, \mathsf{c}_{m}), \mathsf{ZipNumber} + 2^{31}, [\,], 0)\!\) + \(\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{m}, \mathsf{c}_{m}), \mathsf{ZipNumber} + 2^{31}, 0, [\,])\!\) .

    • Note: The intermediate key @@ -869,7 +866,7 @@ :

    • Return - \(\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, \mathsf{tag}, 0)\!\) + \(\mathsf{CKDh}^\mathsf{Registered}((\mathsf{sk}_{par}, \mathsf{c}_{par}), i, 0, \mathsf{tag})\!\) .
    @@ -883,7 +880,7 @@ :

    Draft ZIPs

    @@ -197,14 +197,14 @@ 204 Zcash P2P Network Protocol Reserved 205 Deployment of the Sapling Network Upgrade Final 206 Deployment of the Blossom Network Upgrade Final - 207 Funding Streams [Pre-NU6] Final, [NU6] Implemented (zcashd and zebrad) + 207 Funding Streams [Canopy, NU6] Final 208 Shorter Block Target Spacing Final 209 Prohibit Negative Shielded Chain Value Pool Balances Final 210 Sapling Anchor Deduplication within Transactions Withdrawn 211 Disabling Addition of New Value to the Sprout Chain Value Pool Final 212 Allow Recipient to Derive Ephemeral Secret from Note Plaintext Final 213 Shielded Coinbase Final - 214 Consensus rules for a Zcash Development Fund [Revision 0] Final, [Revision 1] Implemented (zcashd and zebrad) + 214 Consensus rules for a Zcash Development Fund [Revision 0: Canopy, Revision 1: NU6] Final 215 Explicitly Defining and Modifying Ed25519 Validation Rules Final 216 Require Canonical Jubjub Point Encodings Final 217 Aggregate Signatures Reserved @@ -222,7 +222,7 @@ 233 Network Sustainability Mechanism: Removing Funds From Circulation Draft 234 Network Sustainability Mechanism: Issuance Smoothing Draft 235 Remove 60% of Transaction Fees From Circulation Draft - 236 Blocks should balance exactly Implemented (zcashd and zebrad) + 236 Blocks should balance exactly Final 239 Relay of Version 5 Transactions Final 243 Transaction Signature Validation for Sapling Final 244 Transaction Identifier Non-Malleability Final @@ -230,7 +230,7 @@ 250 Deployment of the Heartwood Network Upgrade Final 251 Deployment of the Canopy Network Upgrade Final 252 Deployment of the NU5 Network Upgrade Final - 253 Deployment of the NU6 Network Upgrade Implemented (zcashd and zebrad) + 253 Deployment of the NU6 Network Upgrade Final 254 Deployment of the NU7 Network Upgrade Draft 300 Cross-chain Atomic Transactions Proposed 301 Zcash Stratum Protocol Final @@ -278,7 +278,7 @@ 1012 Dev Fund to ECC + ZF + Major Grants Obsolete 1013 Keep It Simple, Zcashers: 10% to ECC, 10% to ZF Obsolete 1014 Establishing a Dev Fund for ECC, ZF, and Major Grants Active - 1015 Block Subsidy Allocation for Non-Direct Development Funding Proposed + 1015 Block Subsidy Allocation for Non-Direct Development Funding Final 2001 Lockbox Funding Streams Implemented (zcashd and zebrad) 2002 Explicit Fees Draft 2003 Disallow version 4 transactions Draft diff --git a/rendered/zip-0207.html b/rendered/zip-0207.html index 88ced65b0..2f3e8b707 100644 --- a/rendered/zip-0207.html +++ b/rendered/zip-0207.html @@ -13,7 +13,7 @@ Title: Funding Streams Owners: Jack Grigg <str4d@electriccoin.co> Daira-Emma Hopwood <daira-emma@electriccoin.co> -Status: [Pre-NU6] Final, [NU6] Implemented (zcashd and zebrad) +Status: [Canopy, NU6] Final Category: Consensus Created: 2019-01-04 License: MIT @@ -276,7 +276,7 @@

    Deployment

    This proposal was initially deployed with Canopy. 18

    -

    Changes to support deferred funding streams are to be deployed with NU6. 19

    +

    Changes to support deferred funding streams were deployed with NU6. 19

    Backward compatibility

    This proposal intentionally creates what is known as a "bilateral consensus rule change". Use of this mechanism requires that all network participants upgrade their software to a compatible version within the upgrade window. Older software will treat post-upgrade blocks as invalid, and will follow any pre-upgrade consensus branch that persists.

    diff --git a/rendered/zip-0214.html b/rendered/zip-0214.html index 75a60ab89..267c34704 100644 --- a/rendered/zip-0214.html +++ b/rendered/zip-0214.html @@ -10,7 +10,7 @@ Title: Consensus rules for a Zcash Development Fund Owners: Daira-Emma Hopwood <daira-emma@electriccoin.co> Kris Nuttycombe <kris@nutty.land> -Status: [Revision 0] Final, [Revision 1] Implemented (zcashd and zebrad) +Status: [Revision 0: Canopy, Revision 1: NU6] Final Category: Consensus Created: 2020-02-28 License: MIT @@ -356,7 +356,8 @@

    Rationale for Revision 0

    It was judged to be unnecessary to have a mechanism to update funding stream definitions (in case of security breach or changes to direct grant recipients) other than at network upgrades.

    Deployment

    -

    Revision 0 of this proposal was deployed with Canopy. 11 Revision 1 of this proposal is intended to be deployed with NU6. 12

    +

    Revision 0 of this proposal was deployed with Canopy. 11

    +

    Revision 1 of this proposal was deployed with NU6. 12

    References

    diff --git a/rendered/zip-0236.html b/rendered/zip-0236.html index b7e13f610..e7ebdba0d 100644 --- a/rendered/zip-0236.html +++ b/rendered/zip-0236.html @@ -11,7 +11,7 @@ Owners: Daira-Emma Hopwood <daira-emma@electriccoin.co> Credits: Jack Grigg Kris Nuttycombe -Status: Implemented (zcashd and zebrad) +Status: Final Category: Consensus Created: 2024-07-02 License: MIT @@ -67,8 +67,8 @@

    Deployment

    -

    This ZIP is to be deployed with NU6. 7

    -

    The wording change to § 7.1.2 depends on 8 which is also to be deployed with NU6. 7

    +

    This ZIP was deployed with NU6. 7

    +

    The wording change to § 7.1.2 depends on 8 which was also deployed with NU6. 7

    Reference implementation

      diff --git a/rendered/zip-0253.html b/rendered/zip-0253.html index 1c4dadbae..d7f7f75a5 100644 --- a/rendered/zip-0253.html +++ b/rendered/zip-0253.html @@ -9,7 +9,7 @@ 
      ZIP: 253
 Title: Deployment of the NU6 Network Upgrade
 Owners: Arya <arya@zfnd.org>
-Status: Implemented (zcashd and zebrad)
+Status: Final
 Category: Consensus / Network
 Created: 2024-07-17
 License: MIT
diff --git a/rendered/zip-1015.html b/rendered/zip-1015.html
index 0b5c52872..f7a5a3525 100644
--- a/rendered/zip-1015.html
+++ b/rendered/zip-1015.html
@@ -15,7 +15,7 @@
          Daira-Emma Hopwood
          Jack Grigg
          Skylar Saveland
-Status: Proposed
+Status: Final
 Category: Consensus
 Created: 2024-08-26
 License: MIT
diff --git a/zips/zip-0207.rst b/zips/zip-0207.rst
index 291da0a09..4091249ec 100644
--- a/zips/zip-0207.rst
+++ b/zips/zip-0207.rst
@@ -4,7 +4,7 @@
   Title: Funding Streams
   Owners: Jack Grigg 
           Daira-Emma Hopwood 
-  Status: [Pre-NU6] Final, [NU6] Implemented (zcashd and zebrad)
+  Status: [Canopy, NU6] Final
   Category: Consensus
   Created: 2019-01-04
   License: MIT
@@ -265,7 +265,7 @@ Deployment
 
 This proposal was initially deployed with Canopy. [#zip-0251]_
 
-Changes to support deferred funding streams are to be deployed with NU6. [#zip-0253]_
+Changes to support deferred funding streams were deployed with NU6. [#zip-0253]_
 
 
 Backward compatibility
diff --git a/zips/zip-0214.rst b/zips/zip-0214.rst
index 974bdd7d9..9b4ec1b3e 100644
--- a/zips/zip-0214.rst
+++ b/zips/zip-0214.rst
@@ -4,7 +4,7 @@
   Title: Consensus rules for a Zcash Development Fund
   Owners: Daira-Emma Hopwood 
           Kris Nuttycombe 
-  Status: [Revision 0] Final, [Revision 1] Implemented (zcashd and zebrad)
+  Status: [Revision 0: Canopy, Revision 1: NU6] Final
   Category: Consensus
   Created: 2020-02-28
   License: MIT
@@ -394,7 +394,8 @@ Deployment
 ==========
 
 `Revision 0`_ of this proposal was deployed with Canopy. [#zip-0251]_
-`Revision 1`_ of this proposal is intended to be deployed with NU6. [#zip-0253]_
+
+`Revision 1`_ of this proposal was deployed with NU6. [#zip-0253]_
 
 
 References
diff --git a/zips/zip-0236.rst b/zips/zip-0236.rst
index ed8d59a0b..c872c457d 100644
--- a/zips/zip-0236.rst
+++ b/zips/zip-0236.rst
@@ -5,7 +5,7 @@
   Owners: Daira-Emma Hopwood 
   Credits: Jack Grigg
            Kris Nuttycombe
-  Status: Implemented (zcashd and zebrad)
+  Status: Final
   Category: Consensus
   Created: 2024-07-02
   License: MIT
@@ -130,9 +130,9 @@ These changes apply identically to Mainnet and Testnet.
 Deployment
 ==========
 
-This ZIP is to be deployed with NU6. [#zip-0253]_
+This ZIP was deployed with NU6. [#zip-0253]_
 
-The wording change to § 7.1.2 depends on [#zip-2001]_ which is also to be deployed
+The wording change to § 7.1.2 depends on [#zip-2001]_ which was also deployed
 with NU6. [#zip-0253]_
 
 
diff --git a/zips/zip-0253.md b/zips/zip-0253.md
index 6f9a1492d..aac49a5b1 100644
--- a/zips/zip-0253.md
+++ b/zips/zip-0253.md
@@ -2,7 +2,7 @@
     ZIP: 253
     Title: Deployment of the NU6 Network Upgrade
     Owners: Arya 
-    Status: Implemented (zcashd and zebrad)
+    Status: Final
     Category: Consensus / Network
     Created: 2024-07-17
     License: MIT
diff --git a/zips/zip-1015.rst b/zips/zip-1015.rst
index b94dc5830..e6ca4e41b 100644
--- a/zips/zip-1015.rst
+++ b/zips/zip-1015.rst
@@ -9,7 +9,7 @@
            Daira-Emma Hopwood
            Jack Grigg
            Skylar Saveland
-  Status: Proposed
+  Status: Final
   Category: Consensus
   Created: 2024-08-26
   License: MIT

From 519658baa2aa47d0b961251a7634f0fbd822d320 Mon Sep 17 00:00:00 2001
From: Daira-Emma Hopwood 
Date: Thu, 20 Feb 2025 14:11:42 +0000
Subject: [PATCH 18/22] Describe the status of deployed non-consensus ZIPs as
 Active.

Signed-off-by: Daira-Emma Hopwood 
---
 README.rst             | 24 ++++++++++++------------
 rendered/index.html    | 24 ++++++++++++------------
 rendered/zip-0301.html |  2 +-
 rendered/zip-0308.html |  2 +-
 rendered/zip-0316.html |  2 +-
 rendered/zip-0320.html |  2 +-
 rendered/zip-0321.html |  2 +-
 rendered/zip-2001.html |  2 +-
 zips/zip-0301.rst      |  2 +-
 zips/zip-0308.rst      |  2 +-
 zips/zip-0316.rst      |  2 +-
 zips/zip-0320.rst      |  2 +-
 zips/zip-0321.rst      |  2 +-
 zips/zip-2001.rst      |  2 +-
 14 files changed, 36 insertions(+), 36 deletions(-)

diff --git a/README.rst b/README.rst
index 07de8d177..75d619e78 100644
--- a/README.rst
+++ b/README.rst
@@ -115,16 +115,16 @@ Released ZIPs
    - - - + + + - - + + - +
    252 Deployment of the NU5 Network Upgrade Final
    253 Deployment of the NU6 Network Upgrade Final
    300 Cross-chain Atomic Transactions Proposed
    301 Zcash Stratum Protocol Final
    308 Sprout to Sapling Migration Final
    316 Unified Addresses and Unified Viewing Keys [Revision 0] Final, [Revision 1] Proposed
    301 Zcash Stratum Protocol Active
    308 Sprout to Sapling Migration Active
    316 Unified Addresses and Unified Viewing Keys [Revision 0] Active, [Revision 1] Proposed
    317 Proportional Transfer Fee Mechanism Active
    320 Defining an Address Type to which funds can only be sent from Transparent Addresses Proposed
    321 Payment Request URIs Proposed
    320 Defining an Address Type to which funds can only be sent from Transparent Addresses Active
    321 Payment Request URIs Active
    401 Addressing Mempool Denial-of-Service Active
    1014 Establishing a Dev Fund for ECC, ZF, and Major Grants Active
    1015 Block Subsidy Allocation for Non-Direct Development Funding Final
    2001 Lockbox Funding Streams Implemented (zcashd and zebrad)
    2001 Lockbox Funding Streams Final
    Draft ZIPs @@ -297,14 +297,14 @@ Index of ZIPs 253 Deployment of the NU6 Network Upgrade Final 254 Deployment of the NU7 Network Upgrade Draft 300 Cross-chain Atomic Transactions Proposed - 301 Zcash Stratum Protocol Final + 301 Zcash Stratum Protocol Active 302 Standardized Memo Field Format Draft 303 Sprout Payment Disclosure Reserved 304 Sapling Address Signatures Draft 305 Best Practices for Hardware Wallets supporting Sapling Reserved 306 Security Considerations for Anchor Selection Reserved 307 Light Client Protocol for Payment Detection Draft - 308 Sprout to Sapling Migration Final + 308 Sprout to Sapling Migration Active 309 Blind Off-chain Lightweight Transactions (BOLT) Reserved 310 Security Properties of Sapling Viewing Keys Draft 311 Zcash Payment Disclosures Draft @@ -312,12 +312,12 @@ Index of ZIPs 313 Reduce Conventional Transaction Fee to 1000 zatoshis Obsolete 314 Privacy upgrades to the Zcash light client protocol Reserved 315 Best Practices for Wallet Implementations Draft - 316 Unified Addresses and Unified Viewing Keys [Revision 0] Final, [Revision 1] Proposed + 316 Unified Addresses and Unified Viewing Keys [Revision 0] Active, [Revision 1] Proposed 317 Proportional Transfer Fee Mechanism Active 318 Associated Payload Encryption Reserved 319 Options for Shielded Pool Retirement Reserved - 320 Defining an Address Type to which funds can only be sent from Transparent Addresses Proposed - 321 Payment Request URIs Proposed + 320 Defining an Address Type to which funds can only be sent from Transparent Addresses Active + 321 Payment Request URIs Active 322 Generic Signed Message Format Reserved 323 Specification of getblocktemplate for Zcash Reserved 324 URI-Encapsulated Payments Draft @@ -343,7 +343,7 @@ Index of ZIPs 1013 Keep It Simple, Zcashers: 10% to ECC, 10% to ZF Obsolete 1014 Establishing a Dev Fund for ECC, ZF, and Major Grants Active 1015 Block Subsidy Allocation for Non-Direct Development Funding Final - 2001 Lockbox Funding Streams Implemented (zcashd and zebrad) + 2001 Lockbox Funding Streams Final 2002 Explicit Fees Draft 2003 Disallow version 4 transactions Draft 2004 Remove the dependency of consensus on note encryption Draft diff --git a/rendered/index.html b/rendered/index.html index ca38ac47c..07934be04 100644 --- a/rendered/index.html +++ b/rendered/index.html @@ -80,16 +80,16 @@ 252 Deployment of the NU5 Network Upgrade Final 253 Deployment of the NU6 Network Upgrade Final 300 Cross-chain Atomic Transactions Proposed - 301 Zcash Stratum Protocol Final - 308 Sprout to Sapling Migration Final - 316 Unified Addresses and Unified Viewing Keys [Revision 0] Final, [Revision 1] Proposed + 301 Zcash Stratum Protocol Active + 308 Sprout to Sapling Migration Active + 316 Unified Addresses and Unified Viewing Keys [Revision 0] Active, [Revision 1] Proposed 317 Proportional Transfer Fee Mechanism Active - 320 Defining an Address Type to which funds can only be sent from Transparent Addresses Proposed - 321 Payment Request URIs Proposed + 320 Defining an Address Type to which funds can only be sent from Transparent Addresses Active + 321 Payment Request URIs Active 401 Addressing Mempool Denial-of-Service Active 1014 Establishing a Dev Fund for ECC, ZF, and Major Grants Active 1015 Block Subsidy Allocation for Non-Direct Development Funding Final - 2001 Lockbox Funding Streams Implemented (zcashd and zebrad) + 2001 Lockbox Funding Streams Final

    Draft ZIPs

    These are works-in-progress that have been assigned ZIP numbers. These will eventually become either Proposed (and thus Released), or one of Withdrawn, Rejected, or Obsolete.

    @@ -233,14 +233,14 @@ 253 Deployment of the NU6 Network Upgrade Final 254 Deployment of the NU7 Network Upgrade Draft 300 Cross-chain Atomic Transactions Proposed - 301 Zcash Stratum Protocol Final + 301 Zcash Stratum Protocol Active 302 Standardized Memo Field Format Draft 303 Sprout Payment Disclosure Reserved 304 Sapling Address Signatures Draft 305 Best Practices for Hardware Wallets supporting Sapling Reserved 306 Security Considerations for Anchor Selection Reserved 307 Light Client Protocol for Payment Detection Draft - 308 Sprout to Sapling Migration Final + 308 Sprout to Sapling Migration Active 309 Blind Off-chain Lightweight Transactions (BOLT) Reserved 310 Security Properties of Sapling Viewing Keys Draft 311 Zcash Payment Disclosures Draft @@ -248,12 +248,12 @@ 313 Reduce Conventional Transaction Fee to 1000 zatoshis Obsolete 314 Privacy upgrades to the Zcash light client protocol Reserved 315 Best Practices for Wallet Implementations Draft - 316 Unified Addresses and Unified Viewing Keys [Revision 0] Final, [Revision 1] Proposed + 316 Unified Addresses and Unified Viewing Keys [Revision 0] Active, [Revision 1] Proposed 317 Proportional Transfer Fee Mechanism Active 318 Associated Payload Encryption Reserved 319 Options for Shielded Pool Retirement Reserved - 320 Defining an Address Type to which funds can only be sent from Transparent Addresses Proposed - 321 Payment Request URIs Proposed + 320 Defining an Address Type to which funds can only be sent from Transparent Addresses Active + 321 Payment Request URIs Active 322 Generic Signed Message Format Reserved 323 Specification of getblocktemplate for Zcash Reserved 324 URI-Encapsulated Payments Draft @@ -279,7 +279,7 @@ 1013 Keep It Simple, Zcashers: 10% to ECC, 10% to ZF Obsolete 1014 Establishing a Dev Fund for ECC, ZF, and Major Grants Active 1015 Block Subsidy Allocation for Non-Direct Development Funding Final - 2001 Lockbox Funding Streams Implemented (zcashd and zebrad) + 2001 Lockbox Funding Streams Final 2002 Explicit Fees Draft 2003 Disallow version 4 transactions Draft 2004 Remove the dependency of consensus on note encryption Draft diff --git a/rendered/zip-0301.html b/rendered/zip-0301.html index e84119136..5b5fe98c3 100644 --- a/rendered/zip-0301.html +++ b/rendered/zip-0301.html @@ -14,7 +14,7 @@ Marek Palatinus (slush) and colleagues Jelle Bourdeaud'hui (razakal) ocminer -Status: Final +Status: Active Category: Standards / Ecosystem Created: 2016-09-23 License: MIT diff --git a/rendered/zip-0308.html b/rendered/zip-0308.html index 6afcc473a..8c0c43732 100644 --- a/rendered/zip-0308.html +++ b/rendered/zip-0308.html @@ -11,7 +11,7 @@ Owners: Daira-Emma Hopwood <daira-emma@electriccoin.co> Original-Authors: Daira-Emma Hopwood Eirik Ogilvie-Wigley -Status: Final +Status: Active Category: Standards / RPC / Wallet Created: 2018-11-27 License: MIT diff --git a/rendered/zip-0316.html b/rendered/zip-0316.html index 594829c81..9ca5cc111 100644 --- a/rendered/zip-0316.html +++ b/rendered/zip-0316.html @@ -20,7 +20,7 @@ Ying Tong Lai Credits: Taylor Hornby Stephen Smith -Status: [Revision 0] Final, [Revision 1] Proposed +Status: [Revision 0] Active, [Revision 1] Proposed Category: Standards / RPC / Wallet Created: 2021-04-07 License: MIT diff --git a/rendered/zip-0320.html b/rendered/zip-0320.html index 1932b0d0a..f2b0182e5 100644 --- a/rendered/zip-0320.html +++ b/rendered/zip-0320.html @@ -14,7 +14,7 @@ Owners: Daira-Emma Hopwood <daira-emma@electriccoin.co> Kris Nuttycombe <kris@nutty.land> Credits: Hanh -Status: Proposed +Status: Active Category: Standards / Wallet Created: 2024-01-12 License: MIT diff --git a/rendered/zip-0321.html b/rendered/zip-0321.html index 447bcf50e..e9a5669a4 100644 --- a/rendered/zip-0321.html +++ b/rendered/zip-0321.html @@ -11,7 +11,7 @@ Owners: Kris Nuttycombe <kris@electriccoin.co> Daira-Emma Hopwood <daira-emma@electriccoin.co> Credits: Francisco Gindre -Status: Proposed +Status: Active Category: Standards / Wallet Created: 2020-08-28 Discussions-To: <https://github.com/zcash/zips/issues/347> diff --git a/rendered/zip-2001.html b/rendered/zip-2001.html index 48717be1c..e1ba9922a 100644 --- a/rendered/zip-2001.html +++ b/rendered/zip-2001.html @@ -14,7 +14,7 @@ Owners: Kris Nuttycombe <kris@nutty.land> Credits: Daira-Emma Hopwood <daira-emma@electriccoin.co> Jack Grigg <jack@electriccoin.co> -Status: Implemented (zcashd and zebrad) +Status: Final Category: Consensus Created: 2024-07-02 License: MIT diff --git a/zips/zip-0301.rst b/zips/zip-0301.rst index c76161db3..6224149b3 100644 --- a/zips/zip-0301.rst +++ b/zips/zip-0301.rst @@ -8,7 +8,7 @@ Marek Palatinus (slush) and colleagues Jelle Bourdeaud'hui (razakal) ocminer - Status: Final + Status: Active Category: Standards / Ecosystem Created: 2016-09-23 License: MIT diff --git a/zips/zip-0308.rst b/zips/zip-0308.rst index ed039af23..95ee1351c 100644 --- a/zips/zip-0308.rst +++ b/zips/zip-0308.rst @@ -5,7 +5,7 @@ Owners: Daira-Emma Hopwood Original-Authors: Daira-Emma Hopwood Eirik Ogilvie-Wigley - Status: Final + Status: Active Category: Standards / RPC / Wallet Created: 2018-11-27 License: MIT diff --git a/zips/zip-0316.rst b/zips/zip-0316.rst index 973735b2c..8154bceb9 100644 --- a/zips/zip-0316.rst +++ b/zips/zip-0316.rst @@ -11,7 +11,7 @@ Ying Tong Lai Credits: Taylor Hornby Stephen Smith - Status: [Revision 0] Final, [Revision 1] Proposed + Status: [Revision 0] Active, [Revision 1] Proposed Category: Standards / RPC / Wallet Created: 2021-04-07 License: MIT diff --git a/zips/zip-0320.rst b/zips/zip-0320.rst index 141f24cbf..3630aba57 100644 --- a/zips/zip-0320.rst +++ b/zips/zip-0320.rst @@ -5,7 +5,7 @@ Owners: Daira-Emma Hopwood Kris Nuttycombe Credits: Hanh - Status: Proposed + Status: Active Category: Standards / Wallet Created: 2024-01-12 License: MIT diff --git a/zips/zip-0321.rst b/zips/zip-0321.rst index 42f0be20a..da840d642 100644 --- a/zips/zip-0321.rst +++ b/zips/zip-0321.rst @@ -5,7 +5,7 @@ Owners: Kris Nuttycombe Daira-Emma Hopwood Credits: Francisco Gindre - Status: Proposed + Status: Active Category: Standards / Wallet Created: 2020-08-28 Discussions-To: diff --git a/zips/zip-2001.rst b/zips/zip-2001.rst index 487eac25c..8931bb0b7 100644 --- a/zips/zip-2001.rst +++ b/zips/zip-2001.rst @@ -5,7 +5,7 @@ Owners: Kris Nuttycombe Credits: Daira-Emma Hopwood Jack Grigg - Status: Implemented (zcashd and zebrad) + Status: Final Category: Consensus Created: 2024-07-02 License: MIT From b9b736636fda933814211f1039be865cf9c043c6 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 27 Feb 2025 00:01:58 +0000 Subject: [PATCH 19/22] 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 20/22] 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 21/22] 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 22/22] 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. + +
    +
    + +