change: Track the balance of the deferred chain value pool (#8729)

* Addresses clippy lints * checks network magic and returns early from `is_regtest()` * Moves `subsidy.rs` to `zebra-chain`, refactors funding streams into structs, splits them into pre/post NU6 funding streams, and adds them as a field on `testnet::Parameters` * Replaces Vec with HashMap, adds `ConfiguredFundingStreams` type and conversion logic with constraints. Minor refactors * Empties recipients list * Adds a comment on num_addresses calculation being invalid for configured Testnets, but that being okay since configured testnet parameters are checked when they're being built * Documentation fixes, minor cleanup, renames a test, adds TODOs, and fixes test logic * Removes unnecessary `ParameterSubsidy` impl for &Network, adds docs and TODOs * Adds a "deferred" FundingStreamReceiver, adds a post-NU6 funding streams, updates the `miner_fees_are_valid()` and `subsidy_is_valid()` functions to check that the deferred pool contribution is valid and that there are no unclaimed block subsidies after NU6 activation, and adds some TODOs * adds `lockbox_input_value()` fn * Adds TODOs for linking to relevant ZIPs and updating height ranges * Adds `nu6_lockbox_funding_stream` acceptance test * updates funding stream values test to check post-NU6 funding streams too, adds Mainnet/Testnet NU6 activation heights, fixes lints/compilation issue * Reverts Mainnet/Testnet NU6 activation height definitions, updates `test_funding_stream_values()` to use a configured testnet with the post-NU6 Mainnet funding streams height range * reverts unnecessary refactor * appease clippy * Adds a test for `lockbox_input_value()` * Applies suggestions from code review * Fixes potential panic * Fixes bad merge * Update zebra-chain/src/parameters/network_upgrade.rs * Updates acceptance test to check that invalid blocks are rejected * Checks that the original valid block template at height 2 is accepted as a block submission * Reverts changes for coinbase should balance exactly ZIP * Add `Deferred` to `ValueBalance` * Update snapshots * Unrelated: Revise docs * Add TODOs * Stop recalculating the block subsidy * Track deferred balances * Support heights below slow start shift in halvings * Fix `CheckpointVerifiedBlock` conversion in tests * Allow deserialization of legacy `ValueBalance`s * Simplify docs * Fix warnings raised by Clippy * Fix warnings raised by `cargo fmt` * Update zebra-chain/src/block.rs Co-authored-by: Arya <[email protected]> * Refactor docs around chain value pool changes * updates test name * Updates deferred pool funding stream name to "Lockbox", moves post-NU6 height ranges to constants, updates TODO * Updates `get_block_subsidy()` RPC method to exclude lockbox funding stream from `fundingstreams` field * Adds a TODO for updating `FundingStreamReceiver::name()` method docs * Updates `FundingStreamRecipient::new()` to accept an iterator of items instead of an option of an iterator, updates a comment quoting the coinbase transaction balance consensus rule to note that the current code is inconsistent with the protocol spec, adds a TODO for updating the quote there once the protocol spec has been updated. * Update zebra-consensus/src/checkpoint.rs Co-authored-by: Arya <[email protected]> * Update docs for value balances * Cleanup: Simplify getting info for FS receivers * Avoid a panic when deserializing value balances * Uses FPF Testnet address for post-NU6 testnet funding streams * Updates the NU6 consensus branch id * Update zebra-consensus/src/checkpoint.rs * Bump the major database format version * Add a database upgrade mark * Fix tests after merge * trigger GitHub actions --------- Co-authored-by: Arya <[email protected]> Co-authored-by: Pili Guerra <[email protected]>
ZcashFoundation · Aug 5, 2024 · 82ded59 · 82ded59
1 parent 16168d7
commit 82ded59
Show file tree

Hide file tree

Showing 31 changed files with 659 additions and 384 deletions.
diff --git a/zebra-chain/src/block.rs b/zebra-chain/src/block.rs
@@ -5,7 +5,7 @@ use std::{collections::HashMap, fmt, ops::Neg, sync::Arc};
 use halo2::pasta::pallas;
 
 use crate::{
-    amount::NegativeAllowed,
+    amount::{Amount, NegativeAllowed, NonNegative},
     block::merkle::AuthDataRoot,
     fmt::DisplayToDebug,
     orchard,
@@ -205,34 +205,39 @@ impl Block {
             .expect("number of transactions must fit u64")
     }
 
-    /// Get the overall chain value pool change in this block,
-    /// the negative sum of the transaction value balances in this block.
+    /// Returns the overall chain value pool change in this block---the negative sum of the
+    /// transaction value balances in this block.
     ///
-    /// These are the changes in the transparent, sprout, sapling, and orchard
-    /// chain value pools, as a result of this block.
+    /// These are the changes in the transparent, Sprout, Sapling, Orchard, and
+    /// Deferred chain value pools, as a result of this block.
     ///
-    /// Positive values are added to the corresponding chain value pool.
-    /// Negative values are removed from the corresponding pool.
+    /// Positive values are added to the corresponding chain value pool and negative values are
+    /// removed from the corresponding pool.
     ///
     /// <https://zebra.zfnd.org/dev/rfcs/0012-value-pools.html#definitions>
     ///
-    /// `utxos` must contain the [`transparent::Utxo`]s of every input in this block,
-    /// including UTXOs created by earlier transactions in this block.
-    /// (It can also contain unrelated UTXOs, which are ignored.)
+    /// The given `utxos` must contain the [`transparent::Utxo`]s of every input in this block,
+    /// including UTXOs created by earlier transactions in this block. It can also contain unrelated
+    /// UTXOs, which are ignored.
     ///
-    /// Note: the chain value pool has the opposite sign to the transaction
-    /// value pool.
+    /// Note that the chain value pool has the opposite sign to the transaction value pool.
     pub fn chain_value_pool_change(
         &self,
         utxos: &HashMap<transparent::OutPoint, transparent::Utxo>,
+        deferred_balance: Option<Amount<NonNegative>>,
     ) -> Result<ValueBalance<NegativeAllowed>, ValueBalanceError> {
-        let transaction_value_balance_total = self
+        Ok(*self
             .transactions
             .iter()
             .flat_map(|t| t.value_balance(utxos))
-            .sum::<Result<ValueBalance<NegativeAllowed>, _>>()?;
-
-        Ok(transaction_value_balance_total.neg())
+            .sum::<Result<ValueBalance<NegativeAllowed>, _>>()?
+            .neg()
+            .set_deferred_amount(
+                deferred_balance
+                    .unwrap_or(Amount::zero())
+                    .constrain::<NegativeAllowed>()
+                    .map_err(ValueBalanceError::Deferred)?,
+            ))
     }
 
     /// Compute the root of the authorizing data Merkle tree,

diff --git a/zebra-chain/src/parameters/network/subsidy.rs b/zebra-chain/src/parameters/network/subsidy.rs
@@ -68,20 +68,24 @@ pub enum FundingStreamReceiver {
 }
 
 impl FundingStreamReceiver {
-    /// The name for each funding stream receiver, as described in [ZIP-1014] and [`zcashd`].
+    /// Returns a human-readable name and a specification URL for the receiver, as described in
+    /// [ZIP-1014] and [`zcashd`].
     ///
     /// [ZIP-1014]: https://zips.z.cash/zip-1014#abstract
     /// [`zcashd`]: https://github.com/zcash/zcash/blob/3f09cfa00a3c90336580a127e0096d99e25a38d6/src/consensus/funding.cpp#L13-L32
     // TODO: Update method documentation with a reference to https://zips.z.cash/draft-nuttycom-funding-allocation once its
     //       status is updated to 'Proposed'.
-    pub fn name(self) -> &'static str {
-        match self {
-            FundingStreamReceiver::Ecc => "Electric Coin Company",
-            FundingStreamReceiver::ZcashFoundation => "Zcash Foundation",
-            FundingStreamReceiver::MajorGrants => "Major Grants",
-            // TODO: Find out what this should be called and update the funding stream name.
-            FundingStreamReceiver::Deferred => "Lockbox",
-        }
+    pub fn info(&self) -> (&'static str, &'static str) {
+        (
+            match self {
+                FundingStreamReceiver::Ecc => "Electric Coin Company",
+                FundingStreamReceiver::ZcashFoundation => "Zcash Foundation",
+                FundingStreamReceiver::MajorGrants => "Major Grants",
+                // TODO: Find out what this should be called and update the funding stream name
+                FundingStreamReceiver::Deferred => "Lockbox",
+            },
+            FUNDING_STREAM_SPECIFICATION,
+        )
     }
 }
 
@@ -90,6 +94,7 @@ impl FundingStreamReceiver {
 /// [7.10.1]: https://zips.z.cash/protocol/protocol.pdf#zip214fundingstreams
 pub const FUNDING_STREAM_RECEIVER_DENOMINATOR: u64 = 100;
 
+// TODO: Update the link for post-NU6 funding streams.
 /// The specification for all current funding stream receivers, a URL that links to [ZIP-214].
 ///
 /// [ZIP-214]: https://zips.z.cash/zip-0214

diff --git a/zebra-chain/src/transaction.rs b/zebra-chain/src/transaction.rs
@@ -1390,10 +1390,7 @@ impl Transaction {
             .map(|shielded_data| &mut shielded_data.value_balance)
     }
 
-    /// Get the value balances for this transaction,
-    /// using the transparent outputs spent in this transaction.
-    ///
-    /// See `value_balance` for details.
+    /// Returns the value balances for this transaction using the provided transparent outputs.
     pub(crate) fn value_balance_from_outputs(
         &self,
         outputs: &HashMap<transparent::OutPoint, transparent::Output>,
@@ -1404,25 +1401,26 @@ impl Transaction {
             + self.orchard_value_balance()
     }
 
-    /// Get the value balances for this transaction.
-    /// These are the changes in the transaction value pool,
-    /// split up into transparent, sprout, sapling, and orchard values.
+    /// Returns the value balances for this transaction.
     ///
-    /// Calculated as the sum of the inputs and outputs from each pool,
-    /// or the sum of the value balances from each pool.
+    /// These are the changes in the transaction value pool, split up into transparent, Sprout,
+    /// Sapling, and Orchard values.
     ///
-    /// Positive values are added to this transaction's value pool,
-    /// and removed from the corresponding chain value pool.
-    /// Negative values are removed from this transaction,
-    /// and added to the corresponding pool.
+    /// Calculated as the sum of the inputs and outputs from each pool, or the sum of the value
+    /// balances from each pool.
+    ///
+    /// Positive values are added to this transaction's value pool, and removed from the
+    /// corresponding chain value pool. Negative values are removed from this transaction, and added
+    /// to the corresponding pool.
     ///
     /// <https://zebra.zfnd.org/dev/rfcs/0012-value-pools.html#definitions>
     ///
-    /// `utxos` must contain the utxos of every input in the transaction,
-    /// including UTXOs created by earlier transactions in this block.
+    /// `utxos` must contain the utxos of every input in the transaction, including UTXOs created by
+    /// earlier transactions in this block.
+    ///
+    /// ## Note
     ///
-    /// Note: the chain value pool has the opposite sign to the transaction
-    /// value pool.
+    /// The chain value pool has the opposite sign to the transaction value pool.
     pub fn value_balance(
         &self,
         utxos: &HashMap<transparent::OutPoint, transparent::Utxo>,