[Feature] Introduce constructor, Operand::Checksum and Operand::Edition

ledger/block/src/transaction/merkle.rs

@@ -216,7 +216,7 @@ impl<N: Network> Transaction<N> {
         // Ensure the number of functions is within the allowed range.
         ensure!(
             num_transitions < Self::MAX_TRANSITIONS, // Note: Observe we hold back 1 for the fee.
-            "Execution must contain less than {num_transitions} transitions, found {}",
+            "Execution must contain less than {} transitions, found {num_transitions}",
             Self::MAX_TRANSITIONS,
         );
         Ok(())

ledger/block/src/transactions/confirmed/mod.rs

@@ -51,20 +51,22 @@ impl<N: Network> ConfirmedTransaction<N> {
             }
         };
 
-        // Count the number of `InitializeMapping` and `UpdateKeyValue` finalize operations.
-        let (num_initialize_mappings, num_update_key_values) =
-            finalize_operations.iter().try_fold((0, 0), |(init, update), operation| match operation {
-                FinalizeOperation::InitializeMapping(..) => Ok((init + 1, update)),
-                FinalizeOperation::UpdateKeyValue(..) => Ok((init, update + 1)),
+        // Count the number of `InitializeMapping` and `*KeyValue` finalize operations.
+        let (num_initialize_mappings, num_key_values) =
+            finalize_operations.iter().try_fold((0, 0), |(init, key_value), operation| match operation {
+                FinalizeOperation::InitializeMapping(..) => Ok((init + 1, key_value)),
+                FinalizeOperation::InsertKeyValue(..) // At the time of writing, `InsertKeyValue` is only used in tests. However, it is added for completeness, as it is a valid operation.
+                | FinalizeOperation::RemoveKeyValue(..)
+                | FinalizeOperation::UpdateKeyValue(..) => Ok((init, key_value + 1)),
                 op => {
                     bail!("Transaction '{}' (deploy) contains an invalid finalize operation ({op})", transaction.id())
                 }
             })?;
 
         // Perform safety checks on the finalize operations.
         {
-            // Ensure the number of finalize operations matches the number of 'InitializeMapping' and 'UpdateKeyValue' finalize operations.
-            if num_initialize_mappings + num_update_key_values != finalize_operations.len() {
+            // Ensure the number of finalize operations matches the number of 'InitializeMapping' and '*KeyValue' finalize operations.
+            if num_initialize_mappings + num_key_values != finalize_operations.len() {
                 bail!(
                     "Transaction '{}' (deploy) must contain '{}' operations",
                     transaction.id(),
@@ -79,14 +81,14 @@ impl<N: Network> ConfirmedTransaction<N> {
                     program.mappings().len(),
                 )
             }
-            // Ensure the number of finalize operations matches the number of 'UpdateKeyValue' finalize operations.
-            if num_update_key_values != fee.num_finalize_operations() {
-                bail!(
-                    "Transaction '{}' (deploy) must contain {} 'UpdateKeyValue' operations (found '{num_update_key_values}')",
-                    transaction.id(),
-                    fee.num_finalize_operations()
-                );
-            }
+            // Ensure the number of fee finalize operations lower bounds the number of '*KeyValue' finalize operations.
+            // The lower bound is due to the fact that constructors can issue '*KeyValue' operations as part of the deployment.
+            ensure!(
+                fee.num_finalize_operations() <= num_key_values,
+                "Transaction '{}' (deploy) must contain at least {} 'UpdateKeyValue' operations (found '{num_key_values}')",
+                transaction.id(),
+                fee.num_finalize_operations()
+            );
         }
 
         // Return the accepted deploy transaction.

ledger/store/src/program/finalize.rs

@@ -600,11 +600,16 @@ impl<N: Network, P: FinalizeStorage<N>> FinalizeStore<N, P> {
 }
 
 impl<N: Network, P: FinalizeStorage<N>> FinalizeStoreTrait<N> for FinalizeStore<N, P> {
-    /// Returns `true` if the given `program ID` and `mapping name` exist.
+    /// Returns `true` if the given `program ID` and `mapping name` is confirmed to exist.
     fn contains_mapping_confirmed(&self, program_id: &ProgramID<N>, mapping_name: &Identifier<N>) -> Result<bool> {
         self.storage.contains_mapping_confirmed(program_id, mapping_name)
     }
 
+    /// Returns `true` if the given `program ID` and `mapping name` exist.
+    fn contains_mapping_speculative(&self, program_id: &ProgramID<N>, mapping_name: &Identifier<N>) -> Result<bool> {
+        self.storage.contains_mapping_speculative(program_id, mapping_name)
+    }
+
     /// Returns `true` if the given `program ID`, `mapping name`, and `key` exist.
     fn contains_key_speculative(
         &self,

synthesizer/process/src/cost.rs

@@ -21,10 +21,10 @@ use console::{
     program::{FinalizeType, Identifier, LiteralType, PlaintextType},
 };
 use ledger_block::{Deployment, Execution, Transaction};
-use synthesizer_program::{CastType, Command, Finalize, Instruction, Operand, StackProgram};
+use synthesizer_program::{CastType, Command, Finalize, Instruction, Operand, Program, StackProgram};
 
-/// Returns the *minimum* cost in microcredits to publish the given deployment (total cost, (storage cost, synthesis cost, namespace cost)).
-pub fn deployment_cost<N: Network>(deployment: &Deployment<N>) -> Result<(u64, (u64, u64, u64))> {
+/// Returns the *minimum* cost in microcredits to publish the given deployment (total cost, (storage cost, synthesis cost, constructor cost, namespace cost)).
+pub fn deployment_cost<N: Network>(deployment: &Deployment<N>) -> Result<(u64, (u64, u64, u64, u64))> {
     // Determine the number of bytes in the deployment.
     let size_in_bytes = deployment.size_in_bytes()?;
     // Retrieve the program ID.
@@ -44,7 +44,10 @@ pub fn deployment_cost<N: Network>(deployment: &Deployment<N>) -> Result<(u64, (
     // Compute the synthesis cost in microcredits.
     let synthesis_cost = num_combined_variables.saturating_add(num_combined_constraints) * N::SYNTHESIS_FEE_MULTIPLIER;
 
-    // Compute the namespace cost in credits: 10^(10 - num_characters).
+    // Compute the constructor cost in microcredits.
+    let constructor_cost = constructor_cost_in_microcredits(deployment.program())?;
+
+    // Compute the namespace cost in microcredits: 10^(10 - num_characters) * 1e6
     let namespace_cost = 10u64
         .checked_pow(10u32.saturating_sub(num_characters))
         .ok_or(anyhow!("The namespace cost computation overflowed for a deployment"))?
@@ -53,10 +56,11 @@ pub fn deployment_cost<N: Network>(deployment: &Deployment<N>) -> Result<(u64, (
     // Compute the total cost in microcredits.
     let total_cost = storage_cost
         .checked_add(synthesis_cost)
+        .and_then(|x| x.checked_add(constructor_cost))
         .and_then(|x| x.checked_add(namespace_cost))
         .ok_or(anyhow!("The total cost computation overflowed for a deployment"))?;
 
-    Ok((total_cost, (storage_cost, synthesis_cost, namespace_cost)))
+    Ok((total_cost, (storage_cost, synthesis_cost, constructor_cost, namespace_cost)))
 }
 
 /// Returns the *minimum* cost in microcredits to publish the given execution (total cost, (storage cost, finalize cost)).
@@ -405,6 +409,20 @@ pub fn cost_per_command<N: Network>(
     }
 }
 
+/// Returns the minimum number of microcredits required to run the constructor in the given program.
+/// Each command in a constructor costs 100_000 microcredits.
+/// If a constructor does not exist, no cost is incurred.
+pub fn constructor_cost_in_microcredits<N: Network>(program: &Program<N>) -> Result<u64> {
+    match program.constructor() {
+        Some(constructor) => {
+            let num_commands = constructor.commands().len() as u64;
+            let cost = num_commands.checked_mul(100_000).ok_or(anyhow!("Constructor cost overflowed"))?;
+            Ok(cost)
+        }
+        None => Ok(0),
+    }
+}
+
 /// Returns the minimum number of microcredits required to run the finalize.
 pub fn cost_in_microcredits_v2<N: Network>(stack: &Stack<N>, function_name: &Identifier<N>) -> Result<u64> {
     cost_in_microcredits(stack, function_name, ConsensusFeeVersion::V2)

synthesizer/process/src/finalize.rs

@@ -66,8 +66,17 @@ impl<N: Network> Process<N> {
                 // Initialize the mapping.
                 finalize_operations.push(store.initialize_mapping(*program_id, *mapping.name())?);
             }
-            finish!(timer, "Initialize the program mappings");
+            lap!(timer, "Initialize the program mappings");
+
+            // If the program has a constructor, execute it and extend the finalize operations.
+            // This must happen after the mappings are initialized as the constructor may depend on them.
+            if deployment.program().contains_constructor() {
+                let operations = finalize_constructor(state, store, &stack, *fee.transition_id())?;
+                finalize_operations.extend(operations);
+                lap!(timer, "Execute the constructor");
+            }
 
+            finish!(timer, "Finished finalizing the deployment");
             // Return the stack and finalize operations.
             Ok((stack, finalize_operations))
         })
@@ -183,6 +192,101 @@ fn finalize_fee_transition<N: Network, P: FinalizeStorage<N>>(
     }
 }
 
+/// Finalizes the constructor.
+fn finalize_constructor<N: Network, P: FinalizeStorage<N>>(
+    state: FinalizeGlobalState,
+    store: &FinalizeStore<N, P>,
+    stack: &Stack<N>,
+    transition_id: N::TransitionID,
+) -> Result<Vec<FinalizeOperation<N>>> {
+    // Retrieve the program ID.
+    let program_id = stack.program_id();
+    #[cfg(debug_assertions)]
+    println!("Finalizing constructor for {}...", stack.program_id());
+
+    // Initialize a list for finalize operations.
+    let mut finalize_operations = Vec::new();
+
+    // Initialize a nonce for the constructor registers.
+    // Currently, this nonce is set to zero for every constructor.
+    let nonce = 0;
+
+    // Get the constructor logic. If the program does not have a constructor, return early.
+    let Some(constructor) = stack.program().constructor() else {
+        return Ok(finalize_operations);
+    };
+
+    // Get the constructor types.
+    let constructor_types = stack.get_constructor_types()?.clone();
+
+    // Initialize the finalize registers.
+    let mut registers = FinalizeRegisters::new(state, transition_id, *program_id.name(), constructor_types, nonce);
+
+    // Initialize a counter for the commands.
+    let mut counter = 0;
+
+    // Evaluate the commands.
+    while counter < constructor.commands().len() {
+        // Retrieve the command.
+        let command = &constructor.commands()[counter];
+        // Finalize the command.
+        match &command {
+            Command::BranchEq(branch_eq) => {
+                let result =
+                    try_vm_runtime!(|| branch_to(counter, branch_eq, constructor.positions(), stack, &registers));
+                match result {
+                    Ok(Ok(new_counter)) => {
+                        counter = new_counter;
+                    }
+                    // If the evaluation fails, bail and return the error.
+                    Ok(Err(error)) => bail!("'constructor' failed to evaluate command ({command}): {error}"),
+                    // If the evaluation fails, bail and return the error.
+                    Err(_) => bail!("'constructor' failed to evaluate command ({command})"),
+                }
+            }
+            Command::BranchNeq(branch_neq) => {
+                let result =
+                    try_vm_runtime!(|| branch_to(counter, branch_neq, constructor.positions(), stack, &registers));
+                match result {
+                    Ok(Ok(new_counter)) => {
+                        counter = new_counter;
+                    }
+                    // If the evaluation fails, bail and return the error.
+                    Ok(Err(error)) => bail!("'constructor' failed to evaluate command ({command}): {error}"),
+                    // If the evaluation fails, bail and return the error.
+                    Err(_) => bail!("'constructor' failed to evaluate command ({command})"),
+                }
+            }
+            Command::Await(_) => {
+                bail!("Cannot `await` a Future in a constructor")
+            }
+            _ => {
+                let result = try_vm_runtime!(|| command.finalize(stack, store, &mut registers));
+                match result {
+                    // If the evaluation succeeds with an operation, add it to the list.
+                    Ok(Ok(Some(finalize_operation))) => finalize_operations.push(finalize_operation),
+                    // If the evaluation succeeds with no operation, continue.
+                    Ok(Ok(None)) => {}
+                    // If the evaluation fails, bail and return the error.
+                    Ok(Err(error)) => {
+                        println!("'constructor' failed to evaluate command ({command}): {error}");
+                        bail!("'constructor' failed to evaluate command ({command}): {error}")
+                    }
+                    // If the evaluation fails, bail and return the error.
+                    Err(_) => {
+                        println!("'constructor' failed to evaluate command ({command})");
+                        bail!("'constructor' failed to evaluate command ({command})")
+                    }
+                }
+                counter += 1;
+            }
+        };
+    }
+
+    // Return the finalize operations.
+    Ok(finalize_operations)
+}
+
 /// Finalizes the given transition.
 fn finalize_transition<N: Network, P: FinalizeStorage<N>>(
     state: FinalizeGlobalState,

synthesizer/process/src/stack/evaluate.rs

@@ -85,6 +85,22 @@ impl<N: Network> StackEvaluate<N> for Stack<N> {
                     Operand::BlockHeight => bail!("Cannot retrieve the block height 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, retrieve the checksum from the stack.
+                    Operand::Checksum(program_id) => {
+                        let checksum = match program_id {
+                            Some(program_id) => *self.get_external_stack(program_id)?.program_checksum(),
+                            None => *self.program_checksum(),
+                        };
+                        Ok(Value::Plaintext(Plaintext::from(Literal::Field(checksum))))
+                    }
+                    // If the operand is the program edition, retrieve the edition from the stack.
+                    Operand::Edition(program_id) => {
+                        let edition = match program_id {
+                            Some(program_id) => *self.get_external_stack(program_id)?.program_edition(),
+                            None => *self.program_edition(),
+                        };
+                        Ok(Value::Plaintext(Plaintext::from(Literal::U16(edition))))
+                    }
                 }
             })
             .collect();
@@ -218,6 +234,22 @@ impl<N: Network> StackEvaluate<N> for Stack<N> {
                     Operand::BlockHeight => bail!("Cannot retrieve the block height 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, retrieve the checksum from the stack.
+                    Operand::Checksum(program_id) => {
+                        let checksum = match program_id {
+                            Some(program_id) => *self.get_external_stack(program_id)?.program_checksum(),
+                            None => *self.program_checksum(),
+                        };
+                        Ok(Value::Plaintext(Plaintext::from(Literal::Field(checksum))))
+                    }
+                    // If the operand is the program edition, retrieve the edition from the stack.
+                    Operand::Edition(program_id) => {
+                        let edition = match program_id {
+                            Some(program_id) => *self.get_external_stack(program_id)?.program_edition(),
+                            None => *self.program_edition(),
+                        };
+                        Ok(Value::Plaintext(Plaintext::from(Literal::U16(edition))))
+                    }
                 }
             })
             .collect::<Result<Vec<_>>>()?;

synthesizer/process/src/stack/execute.rs

@@ -120,6 +120,26 @@ impl<N: Network> StackExecute<N> for Stack<N> {
                     Operand::NetworkID => {
                         bail!("Illegal operation: cannot retrieve the network id in a closure scope")
                     }
+                    // If the operand is the checksum, retrieve the checksum from the stack.
+                    Operand::Checksum(program_id) => {
+                        let checksum = match program_id {
+                            Some(program_id) => *self.get_external_stack(program_id)?.program_checksum(),
+                            None => *self.program_checksum(),
+                        };
+                        Ok(circuit::Value::Plaintext(circuit::Plaintext::from(circuit::Literal::Field(
+                            circuit::Field::new(circuit::Mode::Constant, checksum),
+                        ))))
+                    }
+                    // If the operand is the edition, retrieve the edition from the stack.
+                    Operand::Edition(program_id) => {
+                        let edition = match program_id {
+                            Some(program_id) => *self.get_external_stack(program_id)?.program_edition(),
+                            None => *self.program_edition(),
+                        };
+                        Ok(circuit::Value::Plaintext(circuit::Plaintext::from(circuit::Literal::U16(
+                            circuit::U16::new(circuit::Mode::Constant, edition),
+                        ))))
+                    }
                 }
             })
             .collect();
@@ -355,6 +375,26 @@ impl<N: Network> StackExecute<N> for Stack<N> {
                     Operand::NetworkID => {
                         bail!("Illegal operation: cannot retrieve the network id in a function scope")
                     }
+                    // If the operand is the checksum, retrieve the checksum from the stack.
+                    Operand::Checksum(program_id) => {
+                        let checksum = match program_id {
+                            Some(program_id) => *self.get_external_stack(program_id)?.program_checksum(),
+                            None => *self.program_checksum(),
+                        };
+                        Ok(circuit::Value::Plaintext(circuit::Plaintext::from(circuit::Literal::Field(
+                            circuit::Field::new(circuit::Mode::Constant, checksum),
+                        ))))
+                    }
+                    // If the operand is the edition, retrieve the edition from the stack.
+                    Operand::Edition(program_id) => {
+                        let edition = match program_id {
+                            Some(program_id) => *self.get_external_stack(program_id)?.program_edition(),
+                            None => *self.program_edition(),
+                        };
+                        Ok(circuit::Value::Plaintext(circuit::Plaintext::from(circuit::Literal::U16(
+                            circuit::U16::new(circuit::Mode::Constant, edition),
+                        ))))
+                    }
                 }
             })
             .collect::<Result<Vec<_>>>()?;