Network Sustainability Mechanism - ZIP 233 implementation (ZcashFoundation#8930)

Author: mariopil

zebra-chain/src/parameters/network_upgrade.rs

@@ -236,8 +236,9 @@ pub(crate) const CONSENSUS_BRANCH_IDS: &[(NetworkUpgrade, ConsensusBranchId)] =
     (Nu5, ConsensusBranchId(0xc2d6d0b4)),
     (Nu6, ConsensusBranchId(0xc8e71055)),
     (Nu6_1, ConsensusBranchId(0x4dec4df0)),
+    // TODO: set below to (Nu7, ConsensusBranchId(0x77190ad8)), once the same value is set in librustzcash
     #[cfg(any(test, feature = "zebra-test"))]
-    (Nu7, ConsensusBranchId(0x77190ad8)),
+    (Nu7, ConsensusBranchId(0xffffffff)),
     #[cfg(zcash_unstable = "zfuture")]
     (ZFuture, ConsensusBranchId(0xffffffff)),
 ];

zebra-chain/src/transaction.rs

@@ -161,6 +161,8 @@ pub enum Transaction {
         lock_time: LockTime,
         /// The latest block height that this transaction can be added to the chain.
         expiry_height: block::Height,
+        /// The burn amount for this transaction, if any.
+        zip233_amount: Amount<NonNegative>,
         /// The transparent inputs to the transaction.
         inputs: Vec<transparent::Input>,
         /// The transparent outputs from the transaction.
@@ -169,7 +171,6 @@ pub enum Transaction {
         sapling_shielded_data: Option<sapling::ShieldedData<sapling::SharedAnchor>>,
         /// The orchard data for this transaction, if any.
         orchard_shielded_data: Option<orchard::ShieldedData>,
-        // TODO: Add the rest of the v6 fields.
     },
 }
 
@@ -190,6 +191,8 @@ impl fmt::Display for Transaction {
         if let Some(expiry_height) = self.expiry_height() {
             fmter.field("expiry_height", &expiry_height);
         }
+        #[cfg(feature = "tx_v6")]
+        fmter.field("zip233_amount", &self.zip233_amount());
 
         fmter.field("transparent_inputs", &self.inputs().len());
         fmter.field("transparent_outputs", &self.outputs().len());
@@ -321,6 +324,11 @@ impl Transaction {
                     .contains(orchard::Flags::ENABLE_SPENDS))
     }
 
+    /// Does this transaction have zip233_amount output?
+    #[cfg(feature = "tx_v6")]
+    pub fn has_zip233_amount(&self) -> bool {
+        self.zip233_amount() > Amount::<NonNegative>::zero()
+    }
     /// Does this transaction have shielded outputs?
     ///
     /// See [`Self::has_transparent_or_shielded_outputs`] for details.
@@ -1537,6 +1545,19 @@ impl Transaction {
             Transaction::V6 { .. } => Some(TX_V6_VERSION_GROUP_ID),
         }
     }
+
+    /// Access the zip233 amount field of this transaction, regardless of version.
+    pub fn zip233_amount(&self) -> Amount<NonNegative> {
+        match self {
+            Transaction::V1 { .. }
+            | Transaction::V2 { .. }
+            | Transaction::V3 { .. }
+            | Transaction::V4 { .. }
+            | Transaction::V5 { .. } => Amount::zero(),
+            #[cfg(feature = "tx_v6")]
+            Transaction::V6 { zip233_amount, .. } => *zip233_amount,
+        }
+    }
 }
 
 #[cfg(any(test, feature = "proptest-impl"))]

zebra-chain/src/transaction/builder.rs

@@ -9,6 +9,101 @@ use crate::{
 };
 
 impl Transaction {
+    /// Returns a new version 6 coinbase transaction for `network` and `height`,
+    /// which contains the specified `outputs`.
+    #[cfg(feature = "tx_v6")]
+    pub fn new_v6_coinbase(
+        network: &Network,
+        height: Height,
+        outputs: impl IntoIterator<Item = (Amount<NonNegative>, transparent::Script)>,
+        miner_data: Vec<u8>,
+        zip233_amount: Option<Amount<NonNegative>>,
+    ) -> Transaction {
+        // # Consensus
+        //
+        // These consensus rules apply to v5 coinbase transactions after NU5 activation:
+        //
+        // > If effectiveVersion ≥ 5 then this condition MUST hold:
+        // > tx_in_count > 0 or nSpendsSapling > 0 or
+        // > (nActionsOrchard > 0 and enableSpendsOrchard = 1).
+        //
+        // > A coinbase transaction for a block at block height greater than 0 MUST have
+        // > a script that, as its first item, encodes the block height as follows. ...
+        // > let heightBytes be the signed little-endian representation of height,
+        // > using the minimum nonzero number of bytes such that the most significant byte
+        // > is < 0x80. The length of heightBytes MUST be in the range {1 .. 5}.
+        // > Then the encoding is the length of heightBytes encoded as one byte,
+        // > followed by heightBytes itself. This matches the encoding used by Bitcoin
+        // > in the implementation of [BIP-34]
+        // > (but the description here is to be considered normative).
+        //
+        // > A coinbase transaction script MUST have length in {2 .. 100} bytes.
+        //
+        // Zebra adds extra coinbase data if configured to do so.
+        //
+        // Since we're not using a lock time, any sequence number is valid here.
+        // See `Transaction::lock_time()` for the relevant consensus rules.
+        //
+        // <https://zips.z.cash/protocol/protocol.pdf#txnconsensus>
+        let inputs = vec![transparent::Input::new_coinbase(height, miner_data, None)];
+
+        // > The block subsidy is composed of a miner subsidy and a series of funding streams.
+        //
+        // <https://zips.z.cash/protocol/protocol.pdf#subsidyconcepts>
+        //
+        // > The total value in zatoshi of transparent outputs from a coinbase transaction,
+        // > minus vbalanceSapling, minus vbalanceOrchard, MUST NOT be greater than
+        // > the value in zatoshi of block subsidy plus the transaction fees
+        // > paid by transactions in this block.
+        //
+        // > If effectiveVersion ≥ 5 then this condition MUST hold:
+        // > tx_out_count > 0 or nOutputsSapling > 0 or
+        // > (nActionsOrchard > 0 and enableOutputsOrchard = 1).
+        //
+        // <https://zips.z.cash/protocol/protocol.pdf#txnconsensus>
+        let outputs: Vec<_> = outputs
+            .into_iter()
+            .map(|(amount, lock_script)| transparent::Output::new_coinbase(amount, lock_script))
+            .collect();
+        assert!(
+            !outputs.is_empty(),
+            "invalid coinbase transaction: must have at least one output"
+        );
+
+        Transaction::V6 {
+            // > The transaction version number MUST be 4 or 5. ...
+            // > If the transaction version number is 5 then the version group ID
+            // > MUST be 0x26A7270A.
+            // > If effectiveVersion ≥ 5, the nConsensusBranchId field MUST match the consensus
+            // > branch ID used for SIGHASH transaction hashes, as specified in [ZIP-244].
+            network_upgrade: NetworkUpgrade::current(network, height),
+
+            // There is no documented consensus rule for the lock time field in coinbase
+            // transactions, so we just leave it unlocked. (We could also set it to `height`.)
+            lock_time: LockTime::unlocked(),
+
+            // > The nExpiryHeight field of a coinbase transaction MUST be equal to its
+            // > block height.
+            expiry_height: height,
+
+            // > The NSM zip233_amount field [ZIP-233] must be set. It must be >= 0.
+            zip233_amount: zip233_amount.unwrap_or(Amount::zero()),
+
+            inputs,
+            outputs,
+
+            // Zebra does not support shielded coinbase yet.
+            //
+            // > In a version 5 coinbase transaction, the enableSpendsOrchard flag MUST be 0.
+            // > In a version 5 transaction, the reserved bits 2 .. 7 of the flagsOrchard field
+            // > MUST be zero.
+            //
+            // See the Zcash spec for additional shielded coinbase consensus rules.
+            sapling_shielded_data: None,
+            orchard_shielded_data: None,
+        }
+    }
+
     /// Returns a new version 5 coinbase transaction for `network` and `height`,
     /// which contains the specified `outputs`.
     pub fn new_v5_coinbase(

zebra-chain/src/transaction/serialize.rs

@@ -20,6 +20,9 @@ use crate::{
     },
 };
 
+#[cfg(feature = "tx_v6")]
+use crate::parameters::TX_V6_VERSION_GROUP_ID;
+
 use super::*;
 use crate::sapling;
 
@@ -678,6 +681,7 @@ impl ZcashSerialize for Transaction {
                 network_upgrade,
                 lock_time,
                 expiry_height,
+                zip233_amount,
                 inputs,
                 outputs,
                 sapling_shielded_data,
@@ -687,7 +691,7 @@ impl ZcashSerialize for Transaction {
                 // https://zips.z.cash/zip-0230#specification
 
                 // Denoted as `nVersionGroupId` in the spec.
-                writer.write_u32::<LittleEndian>(TX_V5_VERSION_GROUP_ID)?;
+                writer.write_u32::<LittleEndian>(TX_V6_VERSION_GROUP_ID)?;
 
                 // Denoted as `nConsensusBranchId` in the spec.
                 writer.write_u32::<LittleEndian>(u32::from(
@@ -702,6 +706,9 @@ impl ZcashSerialize for Transaction {
                 // Denoted as `nExpiryHeight` in the spec.
                 writer.write_u32::<LittleEndian>(expiry_height.0)?;
 
+                // Denoted as `zip233_amount` in the spec.
+                zip233_amount.zcash_serialize(&mut writer)?;
+
                 // Denoted as `tx_in_count` and `tx_in` in the spec.
                 inputs.zcash_serialize(&mut writer)?;
 
@@ -718,8 +725,6 @@ impl ZcashSerialize for Transaction {
                 // `flagsOrchard`,`valueBalanceOrchard`, `anchorOrchard`, `sizeProofsOrchard`,
                 // `proofsOrchard`, `vSpendAuthSigsOrchard`, and `bindingSigOrchard`.
                 orchard_shielded_data.zcash_serialize(&mut writer)?;
-
-                // TODO: Add the rest of v6 transaction fields.
             }
         }
         Ok(())
@@ -972,6 +977,55 @@ impl ZcashDeserialize for Transaction {
                     orchard_shielded_data,
                 })
             }
+            #[cfg(feature = "tx_v6")]
+            (6, true) => {
+                // Denoted as `nVersionGroupId` in the spec.
+                let id = limited_reader.read_u32::<LittleEndian>()?;
+                if id != TX_V6_VERSION_GROUP_ID {
+                    return Err(SerializationError::Parse("expected TX_V6_VERSION_GROUP_ID"));
+                }
+                // Denoted as `nConsensusBranchId` in the spec.
+                // Convert it to a NetworkUpgrade
+                let network_upgrade =
+                    NetworkUpgrade::try_from(limited_reader.read_u32::<LittleEndian>()?)?;
+
+                // Denoted as `lock_time` in the spec.
+                let lock_time = LockTime::zcash_deserialize(&mut limited_reader)?;
+
+                // Denoted as `nExpiryHeight` in the spec.
+                let expiry_height = block::Height(limited_reader.read_u32::<LittleEndian>()?);
+
+                // Denoted as `zip233_amount` in the spec.
+                let zip233_amount = (&mut limited_reader).zcash_deserialize_into()?;
+
+                // Denoted as `tx_in_count` and `tx_in` in the spec.
+                let inputs = Vec::zcash_deserialize(&mut limited_reader)?;
+
+                // Denoted as `tx_out_count` and `tx_out` in the spec.
+                let outputs = Vec::zcash_deserialize(&mut limited_reader)?;
+
+                // A bundle of fields denoted in the spec as `nSpendsSapling`, `vSpendsSapling`,
+                // `nOutputsSapling`,`vOutputsSapling`, `valueBalanceSapling`, `anchorSapling`,
+                // `vSpendProofsSapling`, `vSpendAuthSigsSapling`, `vOutputProofsSapling` and
+                // `bindingSigSapling`.
+                let sapling_shielded_data = (&mut limited_reader).zcash_deserialize_into()?;
+
+                // A bundle of fields denoted in the spec as `nActionsOrchard`, `vActionsOrchard`,
+                // `flagsOrchard`,`valueBalanceOrchard`, `anchorOrchard`, `sizeProofsOrchard`,
+                // `proofsOrchard`, `vSpendAuthSigsOrchard`, and `bindingSigOrchard`.
+                let orchard_shielded_data = (&mut limited_reader).zcash_deserialize_into()?;
+
+                Ok(Transaction::V6 {
+                    network_upgrade,
+                    lock_time,
+                    expiry_height,
+                    zip233_amount,
+                    inputs,
+                    outputs,
+                    sapling_shielded_data,
+                    orchard_shielded_data,
+                })
+            }
             (_, _) => Err(SerializationError::Parse("bad tx header")),
         }
     }

zebra-consensus/src/transaction.rs

@@ -555,13 +555,22 @@ where
             // Get the `value_balance` to calculate the transaction fee.
             let value_balance = tx.value_balance(&spent_utxos);
 
+            let zip233_amount = match *tx {
+            	#[cfg(feature="tx_v6")]
+                Transaction::V6{ .. } => tx.zip233_amount(),
+                _ => Amount::zero()
+            };
+
             // Calculate the fee only for non-coinbase transactions.
             let mut miner_fee = None;
             if !tx.is_coinbase() {
                 // TODO: deduplicate this code with remaining_transaction_value()?
                 miner_fee = match value_balance {
                     Ok(vb) => match vb.remaining_transaction_value() {
-                        Ok(tx_rtv) => Some(tx_rtv),
+                        Ok(tx_rtv) => match tx_rtv - zip233_amount {
+                            Ok(fee) => Some(fee),
+                            Err(_) => return Err(TransactionError::IncorrectFee),
+                        }
                         Err(_) => return Err(TransactionError::IncorrectFee),
                     },
                     Err(_) => return Err(TransactionError::IncorrectFee),

zebra-consensus/src/transaction/check.rs

@@ -122,9 +122,15 @@ pub fn lock_time_has_passed(
 ///
 /// This check counts both `Coinbase` and `PrevOut` transparent inputs.
 pub fn has_inputs_and_outputs(tx: &Transaction) -> Result<(), TransactionError> {
+    #[cfg(feature = "tx_v6")]
+    let has_other_circulation_effects = tx.has_zip233_amount();
+
+    #[cfg(not(feature = "tx_v6"))]
+    let has_other_circulation_effects = false;
+
     if !tx.has_transparent_or_shielded_inputs() {
         Err(TransactionError::NoInputs)
-    } else if !tx.has_transparent_or_shielded_outputs() {
+    } else if !tx.has_transparent_or_shielded_outputs() && !has_other_circulation_effects {
         Err(TransactionError::NoOutputs)
     } else {
         Ok(())

zebra-consensus/src/transaction/tests/prop.rs

@@ -303,6 +303,9 @@ fn mock_transparent_transaction(
     // Create the mock transaction
     let expiry_height = block_height;
 
+    #[cfg(feature = "tx_v6")]
+    let zip233_amount = Amount::zero();
+
     let transaction = match transaction_version {
         4 => Transaction::V4 {
             inputs,
@@ -321,6 +324,17 @@ fn mock_transparent_transaction(
             orchard_shielded_data: None,
             network_upgrade,
         },
+        #[cfg(feature = "tx_v6")]
+        6 => Transaction::V6 {
+            inputs,
+            outputs,
+            lock_time,
+            expiry_height,
+            zip233_amount,
+            sapling_shielded_data: None,
+            orchard_shielded_data: None,
+            network_upgrade,
+        },
         invalid_version => unreachable!("invalid transaction version: {}", invalid_version),
     };
 

zebra-rpc/Cargo.toml

@@ -23,6 +23,7 @@ categories = [
 exclude = ["*.proto"]
 
 [features]
+tx_v6 = ["zebra-chain/tx_v6", "zebra-state/tx_v6", "zebra-consensus/tx_v6"]
 
 # Production features that activate extra dependencies, or extra features in
 # dependencies
@@ -39,6 +40,7 @@ proptest-impl = [
     "zebra-chain/proptest-impl",
 ]
 
+
 [dependencies]
 chrono = { workspace = true, features = ["clock", "std"] }
 futures = { workspace = true }

zebra-rpc/src/methods.rs

@@ -2413,6 +2413,8 @@ where
             mempool_txs,
             mempool_tx_deps,
             extra_coinbase_data.clone(),
+            #[cfg(feature = "tx_v6")]
+            None,
         );
 
         tracing::debug!(
@@ -2433,6 +2435,8 @@ where
             mempool_txs,
             submit_old,
             extra_coinbase_data,
+            #[cfg(feature = "tx_v6")]
+            None,
         );
 
         Ok(response.into())