Use NetworkUpgrade for TZE epoch determination.

This adds a `Future` variant for both BranchId and NetworkUpgrade.

Cargo.toml

@@ -13,7 +13,3 @@ members = [
 lto = true
 panic = 'abort'
 codegen-units = 1
-
-[profile.dev]
-debug = true
-opt-level = 0

zcash_extensions/Cargo.toml

@@ -16,4 +16,4 @@ zcash_primitives = { version = "0.4.0", path = "../zcash_primitives" }
 ff = "0.8"
 jubjub = "0.5.1"
 rand_core = "0.5.1"
-zcash_proofs = { path = "../zcash_proofs" }
+zcash_proofs = { version = "0.3.0", path = "../zcash_proofs" }

zcash_extensions/src/consensus/transparent.rs

@@ -1,12 +1,15 @@
 //! Consensus logic for Transparent Zcash Extensions.
 
 use std::convert::TryFrom;
+use zcash_primitives::consensus::NetworkUpgrade;
 use zcash_primitives::extensions::transparent::{Error, Extension, Precondition, Witness};
-use zcash_primitives::transaction::components::TzeOut;
-use zcash_primitives::transaction::Transaction;
+use zcash_primitives::transaction::{components::TzeOut, Transaction};
 
 use crate::transparent::demo;
 
+/// Wire value for the demo extension identifier.
+pub const EXTENSION_DEMO: u32 = 0;
+
 /// The set of programs that have assigned type IDs within the Zcash consensus rules.
 #[derive(Debug, Clone, Copy)]
 pub enum ExtensionId {
@@ -20,7 +23,7 @@ impl TryFrom<u32> for ExtensionId {
 
     fn try_from(t: u32) -> Result<Self, Self::Error> {
         match t {
-            0 => Ok(ExtensionId::Demo),
+            EXTENSION_DEMO => Ok(ExtensionId::Demo),
             n => Err(InvalidExtId(n)),
         }
     }
@@ -29,13 +32,14 @@ impl TryFrom<u32> for ExtensionId {
 impl From<ExtensionId> for u32 {
     fn from(type_id: ExtensionId) -> u32 {
         match type_id {
-            ExtensionId::Demo => 0,
+            ExtensionId::Demo => EXTENSION_DEMO,
         }
     }
 }
 
 /// The complete set of context data that is available to any extension having
-/// an assigned extension type ID.
+/// an assigned extension type ID. This type may be modified in the future if
+/// additional context information is required by newly integrated TZEs.
 pub struct Context<'a> {
     pub height: i32,
     pub tx: &'a Transaction,
@@ -47,9 +51,19 @@ impl<'a> Context<'a> {
     }
 }
 
+/// Implementations of this trait provide complete extension validation rules
+/// for a specific epoch, and handle dispatch of verification to individual
+/// TZEs based upon extension ID and mode.
 pub trait Epoch {
     type Error;
 
+    /// For a specific epoch, if the extension ID and mode of the supplied
+    /// witness matches that of the supplied precondition, these values will
+    /// be passed to the associated extension for verification, along with
+    /// whatever that extension requires of the provided `Context`.
+    ///
+    /// Successful validation is indicated by the returned Result containing
+    /// no errors.
     fn verify<'a>(
         &self,
         precondition: &Precondition,
@@ -74,13 +88,11 @@ impl<'a> demo::Context for Context<'a> {
     }
 }
 
-/// Wire identifier for the dummy network upgrade epoch.
-pub const NEXT_BRANCH_ID: u32 = 0x7374f403;
+/// Identifier for the set of TZEs associated with the FUTURE network upgrade.
+/// This epoch is intended only for use on test networks.
+struct EpochVTest;
 
-/// A set of demo TZEs associated with the dummy network upgrade.
-struct EpochV1;
-
-impl Epoch for EpochV1 {
+impl Epoch for EpochVTest {
     type Error = String;
 
     fn verify<'a>(
@@ -89,9 +101,10 @@ impl Epoch for EpochV1 {
         witness: &Witness,
         ctx: &Context<'a>,
     ) -> Result<(), Error<Self::Error>> {
-        // This epoch contains the following set of programs:
         let ext_id = ExtensionId::try_from(precondition.extension_id)
             .map_err(|InvalidExtId(id)| Error::InvalidExtensionId(id))?;
+
+        // This epoch recognizes the following set of extensions:
         match ext_id {
             ExtensionId::Demo => demo::Program
                 .verify(precondition, witness, ctx)
@@ -100,11 +113,10 @@ impl Epoch for EpochV1 {
     }
 }
 
-pub fn epoch_for_branch(consensus_branch_id: u32) -> Option<Box<dyn Epoch<Error = String>>> {
+pub fn epoch_for_branch(network_upgrade: NetworkUpgrade) -> Option<Box<dyn Epoch<Error = String>>> {
     // Map from consensus branch IDs to epochs.
-    let _tmp_branch_id = NEXT_BRANCH_ID;
-    match consensus_branch_id {
-        NEXT_BRANCH_ID => Some(Box::new(EpochV1)),
+    match network_upgrade {
+        NetworkUpgrade::Future => Some(Box::new(EpochVTest)),
         _ => None,
     }
 }

zcash_primitives/src/consensus.rs

@@ -27,6 +27,7 @@ impl Parameters for MainNetwork {
             NetworkUpgrade::Blossom => Some(653_600),
             NetworkUpgrade::Heartwood => Some(903_000),
             NetworkUpgrade::Canopy => Some(1_046_400),
+            NetworkUpgrade::Future => None,
         }
     }
 }
@@ -43,6 +44,7 @@ impl Parameters for TestNetwork {
             NetworkUpgrade::Blossom => Some(584_000),
             NetworkUpgrade::Heartwood => Some(903_800),
             NetworkUpgrade::Canopy => Some(1_028_500),
+            NetworkUpgrade::Future => None,
         }
     }
 }
@@ -73,6 +75,12 @@ pub enum NetworkUpgrade {
     ///
     /// [Canopy]: https://z.cash/upgrade/canopy/
     Canopy,
+    /// The [FUTURE] network upgrade.
+    ///
+    /// This upgrade is expected never to activate on mainnet;
+    /// it is intended for use in integration testing of functionality
+    /// that is a candidate for integration in a future network upgrade.
+    Future,
 }
 
 impl fmt::Display for NetworkUpgrade {
@@ -83,6 +91,7 @@ impl fmt::Display for NetworkUpgrade {
             NetworkUpgrade::Blossom => write!(f, "Blossom"),
             NetworkUpgrade::Heartwood => write!(f, "Heartwood"),
             NetworkUpgrade::Canopy => write!(f, "Canopy"),
+            NetworkUpgrade::Future => write!(f, "FUTURE"),
         }
     }
 }
@@ -95,6 +104,7 @@ impl NetworkUpgrade {
             NetworkUpgrade::Blossom => BranchId::Blossom,
             NetworkUpgrade::Heartwood => BranchId::Heartwood,
             NetworkUpgrade::Canopy => BranchId::Canopy,
+            NetworkUpgrade::Future => BranchId::Future,
         }
     }
 }
@@ -140,6 +150,9 @@ pub enum BranchId {
     Heartwood,
     /// The consensus rules deployed by [`NetworkUpgrade::Canopy`].
     Canopy,
+    /// Candidates for future consensus rules; this branch will never
+    /// activate on mainnet.
+    Future,
 }
 
 impl TryFrom<u32> for BranchId {
@@ -153,6 +166,7 @@ impl TryFrom<u32> for BranchId {
             0x2bb4_0e60 => Ok(BranchId::Blossom),
             0xf5b9_230b => Ok(BranchId::Heartwood),
             0xe9ff_75a6 => Ok(BranchId::Canopy),
+            0xffff_ffff => Ok(BranchId::Future),
             _ => Err("Unknown consensus branch ID"),
         }
     }
@@ -167,6 +181,7 @@ impl From<BranchId> for u32 {
             BranchId::Blossom => 0x2bb4_0e60,
             BranchId::Heartwood => 0xf5b9_230b,
             BranchId::Canopy => 0xe9ff_75a6,
+            BranchId::Future => 0xffff_ffff,
         }
     }
 }