From 7b332787083c369f1859f8f62dd470de3c9225d0 Mon Sep 17 00:00:00 2001
From: teor <teor@riseup.net>
Date: Fri, 4 Jun 2021 22:57:41 +1000
Subject: [PATCH] Update docs for coinbase maturity for NU5 (#2248)

---
 zebra-state/src/constants.rs | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/zebra-state/src/constants.rs b/zebra-state/src/constants.rs
index 99126dcec..9b81eb2b6 100644
--- a/zebra-state/src/constants.rs
+++ b/zebra-state/src/constants.rs
@@ -2,15 +2,27 @@
 
 /// The maturity threshold for transparent coinbase outputs.
 ///
-/// A transaction MUST NOT spend a transparent output of a coinbase transaction
+/// This threshold uses the relevant chain for the block being verified by the
+/// non-finalized state.
+///
+/// For the best chain, coinbase spends are only allowed from blocks at or below
+/// the finalized tip. For other chains, coinbase spends can use outputs from
+/// early non-finalized blocks, or finalized blocks. But if that chain becomes
+/// the best chain, all non-finalized blocks past the [`MAX_BLOCK_REORG_HEIGHT`]
+/// will be finalized. This includes all mature coinbase outputs.
+///
+/// "A transaction MUST NOT spend a transparent output of a coinbase transaction
 /// from a block less than 100 blocks prior to the spend. Note that transparent
-/// outputs of coinbase transactions include Founders' Reward outputs.
+/// outputs of coinbase transactions include Founders' Reward outputs and
+/// transparent Funding Stream outputs."
+/// [7.1](https://zips.z.cash/protocol/nu5.pdf#txnencodingandconsensus)
 pub const MIN_TRANSPARENT_COINBASE_MATURITY: u32 = 100;
 
 /// The maximum chain reorganisation height.
 ///
-/// Allowing reorganisations past this height could allow double-spends of
-/// coinbase transactions.
+/// This threshold determines the maximum length of the best non-finalized chain.
+///
+/// Larger reorganisations would allow double-spends of coinbase transactions.
 pub const MAX_BLOCK_REORG_HEIGHT: u32 = MIN_TRANSPARENT_COINBASE_MATURITY - 1;
 
 /// The database format version, incremented each time the database format changes.