fix(chain)!: validate the total amount when updating a value balance (#10817)

Author: mergify[bot]

CHANGELOG.md

@@ -19,6 +19,12 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 - Peer-set, crawler-handshake, and address-book gauges now include a `network` label, so Mainnet
   and Testnet values no longer overwrite each other in processes that run both networks.
 
+### Fixed
+
+- Reject blocks whose total chain value pool balance would exceed `MAX_MONEY`,
+  enforcing the cap on the total monetary base
+  ([#10817](https://github.com/ZcashFoundation/zebra/pull/10817))
+
 ## [Zebra 6.2.3](https://github.com/ZcashFoundation/zebra/releases/tag/v6.2.3) - 2026-07-27
 
 This is an optional release with network hardenings for operators that experience issues with their nodes peer set connectivity or otherwise want to be proactive about avoiding such issues.

zebra-chain/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Breaking Changes
+
+- Added the `ValueBalanceError::Total` variant returned when the sum of value
+  pools is out of range
+  ([#10817](https://github.com/ZcashFoundation/zebra/pull/10817))
+
+### Added
+
+- `ValueBalance::total`, which returns the sum of all value pool balances
+
 ## [11.3.0] - 2026-07-27
 
 ### Added

zebra-chain/src/value_balance.rs

@@ -160,6 +160,23 @@ where
         }
     }
 
+    /// Returns the sum of all value pool balances.
+    pub fn total(self) -> Result<Amount<C>, amount::Error> {
+        let total: i128 = [
+            self.transparent,
+            self.sprout,
+            self.sapling,
+            self.orchard,
+            self.deferred,
+            self.ironwood,
+        ]
+        .into_iter()
+        .map(|amount| i128::from(amount.zatoshis()))
+        .sum();
+
+        Amount::try_from(total)
+    }
+
     /// Convert this value balance to a different ValueBalance type,
     /// if it satisfies the new constraint
     pub fn constrain<C2>(self) -> Result<ValueBalance<C2>, ValueBalanceError>
@@ -318,26 +335,35 @@ impl ValueBalance<NonNegative> {
             .expect("conversion from NonNegative to NegativeAllowed is always valid");
         chain_value_pool = (chain_value_pool + chain_value_pool_change)?;
 
-        chain_value_pool.constrain()
+        let chain_value_pool = chain_value_pool.constrain::<NonNegative>()?;
+
+        // The sum of all chain value pools is the total monetary base, which consensus caps at
+        // `MAX_MONEY`. Reject any change that would push the chain value pool total over that cap.
+        chain_value_pool.total().map_err(ValueBalanceError::Total)?;
+
+        Ok(chain_value_pool)
     }
 
     /// Create a fake value pool for testing purposes.
     ///
-    /// The resulting [`ValueBalance`] will have half of the MAX_MONEY amount on each pool.
+    /// The resulting [`ValueBalance`] has `MAX_MONEY / 8` on the transparent, Sprout, Sapling,
+    /// Orchard, and Ironwood pools; the deferred pool is zero. This keeps the total within the
+    /// valid `Amount` range (see [`ValueBalance::total`]), while leaving headroom for value pool
+    /// changes that tests commit on top of it.
     #[cfg(any(test, feature = "proptest-impl"))]
     pub fn fake_populated_pool() -> ValueBalance<NonNegative> {
         let mut fake_value_pool = ValueBalance::zero();
 
         let fake_transparent_value_balance =
-            ValueBalance::from_transparent_amount(Amount::try_from(MAX_MONEY / 2).unwrap());
+            ValueBalance::from_transparent_amount(Amount::try_from(MAX_MONEY / 8).unwrap());
         let fake_sprout_value_balance =
-            ValueBalance::from_sprout_amount(Amount::try_from(MAX_MONEY / 2).unwrap());
+            ValueBalance::from_sprout_amount(Amount::try_from(MAX_MONEY / 8).unwrap());
         let fake_sapling_value_balance =
-            ValueBalance::from_sapling_amount(Amount::try_from(MAX_MONEY / 2).unwrap());
+            ValueBalance::from_sapling_amount(Amount::try_from(MAX_MONEY / 8).unwrap());
         let fake_orchard_value_balance =
-            ValueBalance::from_orchard_amount(Amount::try_from(MAX_MONEY / 2).unwrap());
+            ValueBalance::from_orchard_amount(Amount::try_from(MAX_MONEY / 8).unwrap());
         let fake_ironwood_value_balance =
-            ValueBalance::from_ironwood_amount(Amount::try_from(MAX_MONEY / 2).unwrap());
+            ValueBalance::from_ironwood_amount(Amount::try_from(MAX_MONEY / 8).unwrap());
 
         fake_value_pool.set_transparent_value_balance(fake_transparent_value_balance);
         fake_value_pool.set_sprout_value_balance(fake_sprout_value_balance);
@@ -468,6 +494,9 @@ pub enum ValueBalanceError {
     /// ironwood amount error {0}
     Ironwood(amount::Error),
 
+    /// total amount error {0}
+    Total(amount::Error),
+
     /// ValueBalance is unparsable
     Unparsable,
 }
@@ -481,6 +510,7 @@ impl fmt::Display for ValueBalanceError {
             Orchard(e) => format!("orchard amount err: {e}"),
             Deferred(e) => format!("deferred amount err: {e}"),
             Ironwood(e) => format!("ironwood amount err: {e}"),
+            Total(e) => format!("total amount err: {e}"),
             Unparsable => "value balance is unparsable".to_string(),
         })
     }

zebra-chain/src/value_balance/tests/vectors.rs

@@ -1,7 +1,7 @@
 //! Fixed test vectors for value balances.
 
 use crate::{
-    amount::{Amount, NegativeAllowed, NonNegative},
+    amount::{Amount, NegativeAllowed, NonNegative, MAX_MONEY},
     value_balance::{ValueBalance, ValueBalanceError},
 };
 
@@ -35,6 +35,32 @@ fn ironwood_pool_enforces_non_negative_balance() {
     assert!(matches!(error, ValueBalanceError::Ironwood(_)));
 }
 
+/// Check that `add_chain_value_pool_change` rejects a chain value pool whose
+/// individual pools are each within the valid `Amount` range, but whose total
+/// exceeds `MAX_MONEY` (the total monetary base cap).
+#[test]
+fn total_over_max_money_is_rejected() {
+    let _init_guard = zebra_test::init();
+
+    // Start from a pool that already holds the maximum value in the transparent
+    // pool. This is individually valid (`transparent` is within `0..=MAX_MONEY`).
+    let mut chain = ValueBalance::<NonNegative>::zero();
+    chain.set_transparent_value_balance(ValueBalance::from_transparent_amount(
+        Amount::try_from(MAX_MONEY).expect("MAX_MONEY is a valid amount"),
+    ));
+
+    // Add the maximum value to the sprout pool. Each pool remains individually
+    // valid (`sprout` is within `0..=MAX_MONEY`), but the total becomes
+    // `2 * MAX_MONEY`, which exceeds the `MAX_MONEY` cap on the monetary base.
+    let error = chain
+        .add_chain_value_pool_change(ValueBalance::from_sprout_amount(
+            Amount::<NegativeAllowed>::try_from(MAX_MONEY).expect("MAX_MONEY is a valid amount"),
+        ))
+        .expect_err("a total exceeding MAX_MONEY must be rejected");
+
+    assert!(matches!(error, ValueBalanceError::Total(_)));
+}
+
 /// Check that the ironwood value balance is included in a transaction's
 /// remaining value.
 #[test]