Merge pull request #2993 from ProvableHQ/feat/finalize-timestamp

vicsn · web-flow · commit f9adcf4244a7 · 2025-11-05T09:22:45.000+01:00
[Feature] Add `block.timestamp` operand to finalize
diff --git a/ledger/src/advance.rs b/ledger/src/advance.rs
@@ -345,10 +345,14 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
             latest_coinbase_target,
         )?;
 
+        // Determine if the block timestamp should be included.
+        let next_block_timestamp =
+            (next_height >= N::CONSENSUS_HEIGHT(ConsensusVersion::V12).unwrap_or_default()).then_some(next_timestamp);
         // Construct the finalize state.
         let state = FinalizeGlobalState::new::<N>(
             next_round,
             next_height,
+            next_block_timestamp,
             next_cumulative_weight,
             next_cumulative_proof_target,
             previous_block.hash(),
diff --git a/ledger/src/check_next_block.rs b/ledger/src/check_next_block.rs
@@ -42,10 +42,14 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
             }
         }
 
+        // Determine if the block timestamp should be included.
+        let block_timestamp = (block.height() >= N::CONSENSUS_HEIGHT(ConsensusVersion::V12).unwrap_or_default())
+            .then_some(block.timestamp());
         // Construct the finalize state.
         let state = FinalizeGlobalState::new::<N>(
             block.round(),
             block.height(),
+            block_timestamp,
             block.cumulative_weight(),
             block.cumulative_proof_target(),
             block.previous_hash(),
diff --git a/synthesizer/process/src/stack/evaluate.rs b/synthesizer/process/src/stack/evaluate.rs
@@ -83,6 +83,8 @@ impl<N: Network> Stack<N> {
                     Operand::Caller => Ok(Value::Plaintext(Plaintext::from(Literal::Address(registers.caller()?)))),
                     // If the operand is the block height, throw an error.
                     Operand::BlockHeight => bail!("Cannot retrieve the block height from a closure scope."),
+                    // If the operand is the block timestamp, throw an error.
+                    Operand::BlockTimestamp => bail!("Cannot retrieve the block timestamp from a closure scope."),
                     // If the operand is the network id, throw an error.
                     Operand::NetworkID => bail!("Cannot retrieve the network ID from a closure scope."),
                     // If the operand is the program checksum, throw an error.
@@ -237,6 +239,8 @@ impl<N: Network> Stack<N> {
                     Operand::Caller => Ok(Value::Plaintext(Plaintext::from(Literal::Address(registers.caller()?)))),
                     // If the operand is the block height, throw an error.
                     Operand::BlockHeight => bail!("Cannot retrieve the block height from a function scope."),
+                    // If the operand is the block timestamp, throw an error.
+                    Operand::BlockTimestamp => bail!("Cannot retrieve the block timestamp from a function scope."),
                     // If the operand is the network id, throw an error.
                     Operand::NetworkID => bail!("Cannot retrieve the network ID from a function scope."),
                     // If the operand is the program checksum, throw an error.
diff --git a/synthesizer/process/src/stack/execute.rs b/synthesizer/process/src/stack/execute.rs
@@ -115,6 +115,10 @@ impl<N: Network> Stack<N> {
                     Operand::BlockHeight => {
                         bail!("Illegal operation: cannot retrieve the block height in a closure scope")
                     }
+                    // If the operand is the block timestamp, throw an error.
+                    Operand::BlockTimestamp => {
+                        bail!("Illegal operation: cannot retrieve the block timestamp in a closure scope")
+                    }
                     // If the operand is the network id, throw an error.
                     Operand::NetworkID => {
                         bail!("Illegal operation: cannot retrieve the network id in a closure scope")
@@ -365,6 +369,10 @@ impl<N: Network> Stack<N> {
                     Operand::BlockHeight => {
                         bail!("Illegal operation: cannot retrieve the block height in a function scope")
                     }
+                    // If the operand is the block timestamp, throw an error.
+                    Operand::BlockTimestamp => {
+                        bail!("Illegal operation: cannot retrieve the block timestamp in a function scope")
+                    }
                     // If the operand is the network id, throw an error.
                     Operand::NetworkID => {
                         bail!("Illegal operation: cannot retrieve the network id in a function scope")
diff --git a/synthesizer/process/src/stack/finalize_registers/mod.rs b/synthesizer/process/src/stack/finalize_registers/mod.rs
@@ -19,7 +19,7 @@ use crate::FinalizeTypes;
 use console::{
     network::prelude::*,
     program::{Identifier, Literal, Plaintext, Register, Value},
-    types::{U16, U32},
+    types::{I64, U16, U32},
 };
 use snarkvm_synthesizer_program::{FinalizeGlobalState, FinalizeRegistersState, Operand, RegistersTrait, StackTrait};
 
diff --git a/synthesizer/process/src/stack/finalize_registers/registers_trait.rs b/synthesizer/process/src/stack/finalize_registers/registers_trait.rs
@@ -41,6 +41,13 @@ impl<N: Network> RegistersTrait<N> for FinalizeRegisters<N> {
             Operand::BlockHeight => {
                 return Ok(Value::Plaintext(Plaintext::from(Literal::U32(U32::new(self.state.block_height())))));
             }
+            // If the operand is the block timestamp, load the block timestamp.
+            Operand::BlockTimestamp => match self.state.block_timestamp() {
+                Some(timestamp) => {
+                    return Ok(Value::Plaintext(Plaintext::from(Literal::I64(I64::new(timestamp)))));
+                }
+                None => bail!("The block timestamp is not available until ConsensusVersion::V12"),
+            },
             // If the operand is the network ID, load the network ID.
             Operand::NetworkID => {
                 return Ok(Value::Plaintext(Plaintext::from(Literal::U16(U16::new(N::ID)))));
diff --git a/synthesizer/process/src/stack/finalize_types/matches.rs b/synthesizer/process/src/stack/finalize_types/matches.rs
@@ -64,9 +64,10 @@ impl<N: Network> FinalizeTypes<N> {
                         "Struct member '{struct_name}.{member_name}' expects {member_type}, but found '{plaintext_type}' in the operand '{operand}'.",
                     )
                 }
-                // Ensure the program ID, block height, network ID, checksum, edition, and program owner types matches the member type.
+                // Ensure the program ID, block height, block timestamp, network ID, checksum, edition, and program owner types matches the member type.
                 Operand::ProgramID(..)
                 | Operand::BlockHeight
+                | Operand::BlockTimestamp
                 | Operand::NetworkID
                 | Operand::Checksum(_)
                 | Operand::Edition(_)
@@ -144,6 +145,7 @@ impl<N: Network> FinalizeTypes<N> {
                 // Ensure the program ID, block height, network ID, checksum, edition, and program owner types matches the element type.
                 Operand::ProgramID(..)
                 | Operand::BlockHeight
+                | Operand::BlockTimestamp
                 | Operand::NetworkID
                 | Operand::Checksum(_)
                 | Operand::Edition(_)
diff --git a/synthesizer/process/src/stack/finalize_types/mod.rs b/synthesizer/process/src/stack/finalize_types/mod.rs
@@ -106,6 +106,7 @@ impl<N: Network> FinalizeTypes<N> {
             Operand::Signer => bail!("'self.signer' is not a valid operand in a finalize context."),
             Operand::Caller => bail!("'self.caller' is not a valid operand in a finalize context."),
             Operand::BlockHeight => FinalizeType::Plaintext(PlaintextType::Literal(LiteralType::U32)),
+            Operand::BlockTimestamp => FinalizeType::Plaintext(PlaintextType::Literal(LiteralType::I64)),
             Operand::NetworkID => FinalizeType::Plaintext(PlaintextType::Literal(LiteralType::U16)),
             Operand::Checksum(_) => FinalizeType::Plaintext(PlaintextType::Array(ArrayType::new(
                 PlaintextType::Literal(LiteralType::U8),
diff --git a/synthesizer/process/src/stack/register_types/matches.rs b/synthesizer/process/src/stack/register_types/matches.rs
@@ -88,6 +88,10 @@ impl<N: Network> RegisterTypes<N> {
                 Operand::BlockHeight => bail!(
                     "Struct member '{struct_name}.{member_name}' cannot be from a block height in a non-finalize scope"
                 ),
+                // If the operand is a block timestamp type, throw an error.
+                Operand::BlockTimestamp => bail!(
+                    "Struct member '{struct_name}.{member_name}' cannot be from a block timestamp in a non-finalize scope"
+                ),
                 // If the operand is a network ID type, throw an error.
                 Operand::NetworkID => bail!(
                     "Struct member '{struct_name}.{member_name}' cannot be from a network ID in a non-finalize scope"
@@ -181,6 +185,10 @@ impl<N: Network> RegisterTypes<N> {
                 }
                 // If the operand is a block height type, throw an error.
                 Operand::BlockHeight => bail!("Array element cannot be from a block height in a non-finalize scope"),
+                // If the operand is a block timestamp type, throw an error.
+                Operand::BlockTimestamp => {
+                    bail!("Array element cannot be from a block timestamp in a non-finalize scope")
+                }
                 // If the operand is a network ID type, throw an error.
                 Operand::NetworkID => bail!("Array element cannot be from a network ID in a non-finalize scope"),
                 // If the operand is a checksum type, throw an error.
@@ -252,6 +260,9 @@ impl<N: Network> RegisterTypes<N> {
             Operand::BlockHeight => {
                 bail!("Forbidden operation: Cannot cast a block height as a record owner")
             }
+            Operand::BlockTimestamp => {
+                bail!("Forbidden operation: Cannot cast a block timestamp as a record owner")
+            }
             Operand::NetworkID => {
                 bail!("Forbidden operation: Cannot cast a network ID as a record owner")
             }
@@ -324,6 +335,12 @@ impl<N: Network> RegisterTypes<N> {
                                 "Record entry '{record_name}.{entry_name}' expects a '{plaintext_type}', but found a block height in the operand '{operand}'."
                             )
                         }
+                        // Fail if the operand is a block timestamp.
+                        Operand::BlockTimestamp => {
+                            bail!(
+                                "Record entry '{record_name}.{entry_name}' expects a '{plaintext_type}', but found a block timestamp in the operand '{operand}'."
+                            )
+                        }
                         // Fail if the operand is a network ID.
                         Operand::NetworkID => {
                             bail!(
diff --git a/synthesizer/process/src/stack/register_types/mod.rs b/synthesizer/process/src/stack/register_types/mod.rs
@@ -97,6 +97,9 @@ impl<N: Network> RegisterTypes<N> {
                 RegisterType::Plaintext(PlaintextType::Literal(LiteralType::Address))
             }
             Operand::BlockHeight => bail!("'block.height' is not a valid operand in a non-finalize context."),
+            Operand::BlockTimestamp => {
+                bail!("'block.timestamp' is not a valid operand in a non-finalize context.")
+            }
             Operand::NetworkID => bail!("'network.id' is not a valid operand in a non-finalize context."),
             Operand::Checksum(_) => bail!("'checksum' is not a valid operand in a non-finalize context."),
             Operand::Edition(_) => bail!("'edition' is not a valid operand in a non-finalize context."),
diff --git a/synthesizer/process/src/stack/registers/registers_circuit.rs b/synthesizer/process/src/stack/registers/registers_circuit.rs
@@ -102,6 +102,8 @@ impl<N: Network, A: circuit::Aleo<Network = N>> RegistersCircuit<N, A> for Regis
             }
             // If the operand is the block height, throw an error.
             Operand::BlockHeight => bail!("Cannot load the block height in a non-finalize context"),
+            // If the operand is the block timestamp, throw an error.
+            Operand::BlockTimestamp => bail!("Cannot load the block timestamp in a non-finalize context"),
             // If the operand is the network ID, throw an error.
             Operand::NetworkID => bail!("Cannot load the network ID in a non-finalize context"),
             // If the operand is the checksum, throw an error.
diff --git a/synthesizer/process/src/stack/registers/registers_trait.rs b/synthesizer/process/src/stack/registers/registers_trait.rs
@@ -88,6 +88,8 @@ impl<N: Network, A: circuit::Aleo<Network = N>> RegistersTrait<N> for Registers<
             Operand::Caller => return Ok(Value::Plaintext(Plaintext::from(Literal::Address(self.caller()?)))),
             // If the operand is the block height, throw an error.
             Operand::BlockHeight => bail!("Cannot load the block height in a non-finalize context"),
+            // If the operand is the block timestamp, throw an error.
+            Operand::BlockTimestamp => bail!("Cannot load the block timestamp in a non-finalize context"),
             // If the operand is the network ID, throw an error.
             Operand::NetworkID => bail!("Cannot load the network ID in a non-finalize context"),
             // If the operand is the checksum, throw an error.
diff --git a/synthesizer/process/src/tests/test_credits.rs b/synthesizer/process/src/tests/test_credits.rs
@@ -70,7 +70,7 @@ macro_rules! test_atomic_finalize {
 
 /// Samples a new finalize state.
 fn sample_finalize_state(block_height: u32) -> FinalizeGlobalState {
-    FinalizeGlobalState::from(block_height as u64, block_height, [0u8; 32])
+    FinalizeGlobalState::from(block_height as u64, block_height, None, [0u8; 32])
 }
 
 /// Returns the `value` for the given `key` in the `mapping` for the given `program_id`.
diff --git a/synthesizer/process/src/tests/test_execute.rs b/synthesizer/process/src/tests/test_execute.rs
@@ -46,7 +46,7 @@ type CurrentAleo = AleoV0;
 
 /// Samples a new finalize state.
 pub fn sample_finalize_state(block_height: u32) -> FinalizeGlobalState {
-    FinalizeGlobalState::from(block_height as u64, block_height, [0u8; 32])
+    FinalizeGlobalState::from(block_height as u64, block_height, None, [0u8; 32])
 }
 
 /// Samples a valid fee for the given process, block store, and finalize store.
diff --git a/synthesizer/process/src/tests/test_utils.rs b/synthesizer/process/src/tests/test_utils.rs
@@ -64,7 +64,7 @@ pub(super) use test_atomic_finalize;
 
 /// Samples a new finalize state.
 fn sample_finalize_state(block_height: u32) -> FinalizeGlobalState {
-    FinalizeGlobalState::from(block_height as u64, block_height, [0u8; 32])
+    FinalizeGlobalState::from(block_height as u64, block_height, None, [0u8; 32])
 }
 
 /// Returns the `value` for the given `key` in the `mapping` for the given `program_id`.
diff --git a/synthesizer/program/src/lib.rs b/synthesizer/program/src/lib.rs
@@ -967,6 +967,22 @@ impl<N: Network> ProgramCore<N> {
         function_contains || closure_contains || command_contains || array_size_exceeds
     }
 
+    /// Returns `true` if a program contains any V12 syntax.
+    /// This includes `Operand::BlockTimestamp`.
+    /// This is enforced to be `false` for programs before `ConsensusVersion::V12`.
+    #[inline]
+    pub fn contains_v12_syntax(&self) -> bool {
+        // Check each instruction and output in each function's finalize scope for the use of
+        // `Operand::BlockTimestamp`.
+        cfg_iter!(self.functions()).any(|(_, function)| {
+            function.finalize_logic().is_some_and(|finalize_logic| {
+                cfg_iter!(finalize_logic.commands()).any(|command| {
+                    cfg_iter!(command.operands()).any(|operand| matches!(operand, Operand::BlockTimestamp))
+                })
+            })
+        })
+    }
+
     /// Returns `true` if a program contains any string type.
     /// Before ConsensusVersion::V12, variable-length string sampling when using them as inputs caused deployment synthesis to be inconsistent and abort with probability 63/64.
     /// After ConsensusVersion::V12, string types are disallowed.
diff --git a/synthesizer/program/src/logic/finalize_global_state/mod.rs b/synthesizer/program/src/logic/finalize_global_state/mod.rs
@@ -21,6 +21,8 @@ pub struct FinalizeGlobalState {
     block_round: u64,
     /// The block height.
     block_height: u32,
+    /// The block timestamp.
+    block_timestamp: Option<i64>, // TODO (raychu86): Consider adding the entire Metadata here instead.
     /// The block-specific random seed.
     random_seed: [u8; 32],
 }
@@ -39,6 +41,7 @@ impl FinalizeGlobalState {
         Self::new::<N>(
             block_round,
             block_height,
+            None,
             block_cumulative_weight,
             block_cumulative_proof_target,
             previous_block_hash,
@@ -50,18 +53,22 @@ impl FinalizeGlobalState {
     pub fn new<N: Network>(
         block_round: u64,
         block_height: u32,
+        block_timestamp: Option<i64>,
         block_cumulative_weight: u128,
         block_cumulative_proof_target: u128,
         previous_block_hash: N::BlockHash,
     ) -> Result<Self> {
-        // Initialize the preimage.
+        // Initialize the preimage, optionally including the block timestamp.
         let preimage = to_bits_le![
             block_round,
             block_height,
             block_cumulative_weight,
             block_cumulative_proof_target,
             (*previous_block_hash); 605
-        ];
+        ]
+        .into_iter()
+        .chain(block_timestamp.into_iter().flat_map(|ts| to_bits_le![ts]))
+        .collect::<Vec<_>>();
 
         // Hash the preimage to get the random seed.
         let seed = N::hash_bhp768(&preimage)?.to_bytes_le()?;
@@ -72,13 +79,18 @@ impl FinalizeGlobalState {
         let mut random_seed = [0u8; 32];
         random_seed.copy_from_slice(&seed[..32]);
 
-        Ok(Self { block_round, block_height, random_seed })
+        Ok(Self { block_round, block_height, block_timestamp, random_seed })
     }
 
     /// Initializes a new global state.
     #[inline]
-    pub const fn from(block_round: u64, block_height: u32, random_seed: [u8; 32]) -> Self {
-        Self { block_round, block_height, random_seed }
+    pub const fn from(
+        block_round: u64,
+        block_height: u32,
+        block_timestamp: Option<i64>,
+        random_seed: [u8; 32],
+    ) -> Self {
+        Self { block_round, block_height, block_timestamp, random_seed }
     }
 
     /// Returns the block round.
@@ -98,4 +110,10 @@ impl FinalizeGlobalState {
     pub const fn random_seed(&self) -> &[u8; 32] {
         &self.random_seed
     }
+
+    /// Returns the block timestamp.
+    #[inline]
+    pub const fn block_timestamp(&self) -> Option<i64> {
+        self.block_timestamp
+    }
 }
diff --git a/synthesizer/program/src/logic/instruction/operand/bytes.rs b/synthesizer/program/src/logic/instruction/operand/bytes.rs
@@ -52,6 +52,7 @@ impl<N: Network> FromBytes for Operand<N> {
                 };
                 Ok(Self::ProgramOwner(program_id))
             }
+            10 => Ok(Self::BlockTimestamp),
             variant => Err(error(format!("Failed to deserialize operand variant {variant}"))),
         }
     }
@@ -109,6 +110,7 @@ impl<N: Network> ToBytes for Operand<N> {
                     }
                 }
             }
+            Self::BlockTimestamp => 10u8.write_le(&mut writer),
         }
     }
 }
diff --git a/synthesizer/program/src/logic/instruction/operand/mod.rs b/synthesizer/program/src/logic/instruction/operand/mod.rs
@@ -41,6 +41,9 @@ pub enum Operand<N: Network> {
     /// The operand is the block height.
     /// Note: This variant is only accessible in the `finalize` scope.
     BlockHeight,
+    /// The operand is the block timestamp.
+    /// Note: This variant is only accessible in the `finalize` scope.
+    BlockTimestamp,
     /// The operand is the network ID.
     /// Note: This variant is only accessible in the `finalize` scope.
     NetworkID,
diff --git a/synthesizer/program/src/logic/instruction/operand/parse.rs b/synthesizer/program/src/logic/instruction/operand/parse.rs
@@ -27,6 +27,7 @@ impl<N: Network> Parser for Operand<N> {
             map(tag("self.signer"), |_| Self::Signer),
             map(tag("self.caller"), |_| Self::Caller),
             map(tag("block.height"), |_| Self::BlockHeight),
+            map(tag("block.timestamp"), |_| Self::BlockTimestamp),
             map(tag("network.id"), |_| Self::NetworkID),
             // Note that `Operand::Checksum` and `Operand::Edition` must be parsed before `Operand::ProgramID`s, since an edition or checksum may be prefixed with a program ID.
             map(pair(opt(terminated(ProgramID::parse, tag("/"))), tag("checksum")), |(program_id, _)| {
@@ -89,6 +90,8 @@ impl<N: Network> Display for Operand<N> {
             Self::Caller => write!(f, "self.caller"),
             // Prints the identifier for the block height, i.e. block.height
             Self::BlockHeight => write!(f, "block.height"),
+            // Prints the identifier for the block timestamp, i.e. block.timestamp
+            Self::BlockTimestamp => write!(f, "block.timestamp"),
             // Prints the identifier for the network ID, i.e. network.id
             Self::NetworkID => write!(f, "network.id"),
             // Prints the optional program ID with the checksum keyword, i.e. `checksum` or `token.aleo/checksum`
@@ -140,6 +143,9 @@ mod tests {
         let operand = Operand::<CurrentNetwork>::parse("block.height").unwrap().1;
         assert_eq!(Operand::BlockHeight, operand);
 
+        let operand = Operand::<CurrentNetwork>::parse("block.timestamp").unwrap().1;
+        assert_eq!(Operand::BlockTimestamp, operand);
+
         let operand = Operand::<CurrentNetwork>::parse("network.id").unwrap().1;
         assert_eq!(Operand::NetworkID, operand);
 
diff --git a/synthesizer/program/tests/helpers/sample.rs b/synthesizer/program/tests/helpers/sample.rs
diff --git a/synthesizer/program/tests/instruction/ecdsa.rs b/synthesizer/program/tests/instruction/ecdsa.rs
diff --git a/synthesizer/src/vm/finalize.rs b/synthesizer/src/vm/finalize.rs
diff --git a/synthesizer/src/vm/mod.rs b/synthesizer/src/vm/mod.rs
diff --git a/synthesizer/src/vm/verify.rs b/synthesizer/src/vm/verify.rs
diff --git a/synthesizer/tests/expectations/vm/execute_and_finalize/test_rand.out b/synthesizer/tests/expectations/vm/execute_and_finalize/test_rand.out
diff --git a/synthesizer/tests/test_vm_execute_and_finalize.rs b/synthesizer/tests/test_vm_execute_and_finalize.rs
diff --git a/synthesizer/tests/tests/vm/execute_and_finalize/test_rand.aleo b/synthesizer/tests/tests/vm/execute_and_finalize/test_rand.aleo

Original file line number	Diff line number	Diff line change
`@@ -42,10 +42,14 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {`
`42`	`42`	`}`
`43`	`43`	`}`
`44`	`44`
	`45`	`+ // Determine if the block timestamp should be included.`
	`46`	`+ let block_timestamp = (block.height() >= N::CONSENSUS_HEIGHT(ConsensusVersion::V12).unwrap_or_default())`
	`47`	`+ .then_some(block.timestamp());`
`45`	`48`	`// Construct the finalize state.`
`46`	`49`	`let state = FinalizeGlobalState::new::<N>(`
`47`	`50`	`block.round(),`
`48`	`51`	`block.height(),`
	`52`	`+ block_timestamp,`
`49`	`53`	`block.cumulative_weight(),`
`50`	`54`	`block.cumulative_proof_target(),`
`51`	`55`	`block.previous_hash(),`