change: Track the balance of the deferred chain value pool

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,

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

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>,