feat: batch kernel skeleton

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## v0.16.0 (TBD)
 
 ### Changes
+- Added a skeleton batch kernel ([#1122](https://github.com/0xMiden/protocol/issues/1122)) wired through `LocalBatchProver::prove` and attached to `ProvenBatch` as an `ExecutionProof`. It does not yet perform any verification.
 
 - [BREAKING] Renamed `AccountStorageDelta` to `AccountStoragePatch` ([#3002](https://github.com/0xMiden/protocol/pull/3002)).
 - [BREAKING] Extracted `NullifierTreeBackendReader` and `AccountTreeBackendReader` traits from existing `NullifierTreeBackend` and `AccountTreeBackend` traits ([#2755](https://github.com/0xMiden/protocol/pull/2755)).

crates/miden-protocol/asm/kernels/batch/main.masm

@@ -0,0 +1,41 @@
+# MAIN
+# =================================================================================================
+
+#! Batch kernel program (skeleton).
+#!
+#! A transaction batch groups a set of independently-proven transactions so they can later be
+#! aggregated into a block by the block kernel. This program defines the public input/output
+#! contract that the batch kernel will eventually verify, but currently does not yet perform
+#! any verification: it drops its inputs and exits, leaving the all-zero word output region as the
+#! stack's initial padding zeros.
+#!
+#! Inputs: [
+#!   BATCH_ID,
+#!   BLOCK_COMMITMENT,
+#!   pad(8),
+#! ]
+#!
+#! Outputs: [
+#!   INPUT_NOTES_COMMITMENT,
+#!   OUTPUT_NOTES_COMMITMENT,
+#!   batch_expiration_block_num,
+#!   pad(7),
+#! ]
+#!
+#! Where:
+#! - BATCH_ID is the batch's `BatchId`, the commitment to its transactions.
+#! - BLOCK_COMMITMENT is the commitment of the batch's reference block.
+#! - INPUT_NOTES_COMMITMENT will be the sequential hash over every transaction's input note
+#!   commitments. In this skeleton it is the empty word.
+#! - OUTPUT_NOTES_COMMITMENT will be the sequential hash over every transaction's output note
+#!   commitments. In this skeleton it is the empty word.
+#! - batch_expiration_block_num will be the minimum of every transaction's
+#!   `expiration_block_num`. In this skeleton it is zero.
+#!
+proc main
+    dropw dropw
+end
+
+begin
+    exec.main
+end

crates/miden-protocol/build.rs

@@ -20,6 +20,7 @@ const ASM_PROTOCOL_DIR: &str = "protocol";
 const SHARED_UTILS_DIR: &str = "shared_utils";
 const SHARED_MODULES_DIR: &str = "shared_modules";
 const ASM_TX_KERNEL_DIR: &str = "kernels/transaction";
+const ASM_BATCH_KERNEL_DIR: &str = "kernels/batch";
 
 const PROTOCOL_LIB_NAMESPACE: &str = "miden::protocol";
 
@@ -85,13 +86,32 @@ fn main() -> Result<()> {
     let protocol_lib = compile_protocol_lib(&source_dir, &target_dir, assembler.clone())?;
     assembler.link_dynamic_library(protocol_lib)?;
 
+    // compile batch kernel
+    compile_batch_kernel(&source_dir, &target_dir.join("kernels"))?;
+
     generate_error_constants(&source_dir, &build_dir)?;
 
     generate_event_constants(&source_dir, &target_dir)?;
 
     Ok(())
 }
 
+// COMPILE BATCH KERNEL
+// ================================================================================================
+
+/// Reads the batch kernel MASM source from the `source_dir`, compiles it, and saves the result
+/// to the `target_dir` as a `batch_kernel.masb` binary file.
+fn compile_batch_kernel(source_dir: &Path, target_dir: &Path) -> Result<()> {
+    let batch_kernel_dir = source_dir.join(ASM_BATCH_KERNEL_DIR);
+    let main_file_path = batch_kernel_dir.join("main.masm");
+
+    let assembler = build_assembler(None)?;
+    let batch_main = assembler.assemble_program(main_file_path)?;
+
+    let masb_file_path = target_dir.join("batch_kernel.masb");
+    batch_main.write_to_file(masb_file_path).into_diagnostic()
+}
+
 // COMPILE TRANSACTION KERNEL
 // ================================================================================================
 

crates/miden-protocol/src/batch/kernel.rs

@@ -0,0 +1,150 @@
+use alloc::vec::Vec;
+
+use miden_core::program::Kernel;
+
+use crate::batch::{BatchOutput, ProposedBatch};
+use crate::block::BlockNumber;
+use crate::errors::BatchOutputError;
+use crate::utils::serde::Deserializable;
+use crate::utils::sync::LazyLock;
+use crate::vm::{AdviceInputs, Program, ProgramInfo, StackInputs, StackOutputs};
+use crate::{Felt, Word};
+
+// CONSTANTS
+// ================================================================================================
+
+static KERNEL_MAIN: LazyLock<Program> = LazyLock::new(|| {
+    let bytes = include_bytes!(concat!(env!("OUT_DIR"), "/assets/kernels/batch_kernel.masb"));
+    Program::read_from_bytes(bytes).expect("failed to deserialize batch kernel runtime")
+});
+
+// BATCH KERNEL
+// ================================================================================================
+
+/// The batch kernel program: an executable Miden program that proves a batch of transactions.
+///
+/// The kernel takes `[BATCH_ID, BLOCK_COMMITMENT]` as public inputs and emits
+/// `[INPUT_NOTES_COMMITMENT, OUTPUT_NOTES_COMMITMENT, batch_expiration_block_num]`. See
+/// `asm/kernels/batch/main.masm` for the input/output contract.
+pub struct BatchKernel;
+
+impl BatchKernel {
+    // KERNEL SOURCE CODE
+    // --------------------------------------------------------------------------------------------
+
+    /// Returns the executable batch kernel program loaded from the build's `OUT_DIR`.
+    pub fn main() -> Program {
+        KERNEL_MAIN.clone()
+    }
+
+    /// Returns [`ProgramInfo`] for the batch kernel program.
+    ///
+    /// The batch kernel does not expose syscalls, so the associated [`Kernel`] is empty.
+    pub fn program_info() -> ProgramInfo {
+        ProgramInfo::new(Self::main().hash(), Kernel::default())
+    }
+
+    // INPUT BUILDERS
+    // --------------------------------------------------------------------------------------------
+
+    /// Transforms the provided [`ProposedBatch`] into the stack and advice inputs needed to
+    /// execute the batch kernel.
+    pub fn prepare_inputs(proposed_batch: &ProposedBatch) -> (StackInputs, AdviceInputs) {
+        let block_commitment = proposed_batch.reference_block_header().commitment();
+        let batch_id = proposed_batch.id().as_word();
+
+        let stack_inputs = Self::build_input_stack(batch_id, block_commitment);
+        let advice_inputs = Self::build_advice_inputs(proposed_batch);
+
+        (stack_inputs, advice_inputs)
+    }
+
+    /// Returns the stack with the public inputs required by the batch kernel.
+    ///
+    /// The initial stack is:
+    ///
+    /// ```text
+    /// [BATCH_ID, BLOCK_COMMITMENT, pad(8)]
+    /// ```
+    ///
+    /// Where:
+    /// - `BATCH_ID` is the batch's [`BatchId`](crate::batch::BatchId).
+    /// - `BLOCK_COMMITMENT` is the commitment of the batch's reference block.
+    pub fn build_input_stack(batch_id: Word, block_commitment: Word) -> StackInputs {
+        let mut inputs: Vec<Felt> = Vec::with_capacity(8);
+        inputs.extend_from_slice(batch_id.as_elements());
+        inputs.extend_from_slice(block_commitment.as_elements());
+
+        StackInputs::new(&inputs).expect("number of stack inputs should be <= 16")
+    }
+
+    /// Builds the stack with the expected batch kernel outputs.
+    ///
+    /// The output stack is defined as:
+    ///
+    /// ```text
+    /// [INPUT_NOTES_COMMITMENT, OUTPUT_NOTES_COMMITMENT, batch_expiration_block_num]
+    /// ```
+    pub fn build_output_stack(
+        input_notes_commitment: Word,
+        output_notes_commitment: Word,
+        batch_expiration_block_num: BlockNumber,
+    ) -> StackOutputs {
+        let mut outputs: Vec<Felt> = Vec::with_capacity(9);
+        outputs.extend_from_slice(input_notes_commitment.as_elements());
+        outputs.extend_from_slice(output_notes_commitment.as_elements());
+        outputs.push(Felt::from(batch_expiration_block_num));
+
+        StackOutputs::new(&outputs).expect("number of stack outputs should be <= 16")
+    }
+
+    /// Extracts the [`BatchOutput`] from the provided stack outputs.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The padding cells (positions 9..16) are not all zero.
+    /// - `batch_expiration_block_num` does not fit into a `u32`.
+    pub fn parse_output_stack(stack: &StackOutputs) -> Result<BatchOutput, BatchOutputError> {
+        let input_notes_commitment = stack
+            .get_word(BatchOutput::INPUT_NOTES_COMMITMENT_WORD_IDX)
+            .expect("input_notes_commitment word missing");
+        let output_notes_commitment = stack
+            .get_word(BatchOutput::OUTPUT_NOTES_COMMITMENT_WORD_IDX)
+            .expect("output_notes_commitment word missing");
+
+        let expiration_felt = stack
+            .get_element(BatchOutput::BATCH_EXPIRATION_BLOCK_NUM_ELEMENT_IDX)
+            .expect("batch_expiration_block_num missing");
+
+        // Every cell after batch_expiration_block_num must be zero padding.
+        if stack[BatchOutput::BATCH_EXPIRATION_BLOCK_NUM_ELEMENT_IDX + 1..]
+            .iter()
+            .any(|&felt| felt != Felt::ZERO)
+        {
+            return Err(BatchOutputError::OutputStackInvalid(
+                "batch_expiration_block_num must be followed by zero padding".into(),
+            ));
+        }
+
+        let batch_expiration_block_num = u32::try_from(expiration_felt.as_canonical_u64())
+            .map_err(|_| BatchOutputError::ExpirationBlockNumberTooLarge(expiration_felt))?
+            .into();
+
+        Ok(BatchOutput::new(
+            input_notes_commitment,
+            output_notes_commitment,
+            batch_expiration_block_num,
+        ))
+    }
+
+    // ADVICE BUILDER
+    // --------------------------------------------------------------------------------------------
+
+    /// Builds the advice inputs (map + stack) consumed by the batch kernel.
+    ///
+    /// The skeleton kernel ignores its advice inputs, so this returns the default empty value.
+    fn build_advice_inputs(_proposed_batch: &ProposedBatch) -> AdviceInputs {
+        AdviceInputs::default()
+    }
+}

crates/miden-protocol/src/batch/mod.rs

@@ -17,3 +17,9 @@ mod ordered_batches;
 pub use ordered_batches::OrderedBatches;
 
 pub(super) mod note_tracker;
+
+mod kernel;
+pub use kernel::BatchKernel;
+
+mod output;
+pub use output::BatchOutput;

crates/miden-protocol/src/batch/output.rs

@@ -0,0 +1,66 @@
+use crate::Word;
+use crate::block::BlockNumber;
+
+// BATCH OUTPUT
+// ================================================================================================
+
+/// The public outputs produced by the batch kernel.
+///
+/// This is the parsed, typed form of the kernel's output stack (see
+/// [`BatchKernel::parse_output_stack`](crate::batch::BatchKernel::parse_output_stack)), mirroring
+/// [`TransactionOutputs`](crate::transaction::TransactionOutputs) for transactions.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BatchOutput {
+    /// The commitment to the batch's input notes.
+    input_notes_commitment: Word,
+    /// The commitment to the batch's output notes.
+    output_notes_commitment: Word,
+    /// The block number at which the batch expires.
+    batch_expiration_block_num: BlockNumber,
+}
+
+impl BatchOutput {
+    // OUTPUT STACK LAYOUT
+    // --------------------------------------------------------------------------------------------
+
+    /// The element index at which the input notes commitment word starts on the output stack.
+    pub const INPUT_NOTES_COMMITMENT_WORD_IDX: usize = 0;
+    /// The element index at which the output notes commitment word starts on the output stack.
+    pub const OUTPUT_NOTES_COMMITMENT_WORD_IDX: usize = 4;
+    /// The element index at which the batch expiration block number is stored on the output stack.
+    pub const BATCH_EXPIRATION_BLOCK_NUM_ELEMENT_IDX: usize = 8;
+
+    // CONSTRUCTOR
+    // --------------------------------------------------------------------------------------------
+
+    /// Returns a new [`BatchOutput`] instantiated from the provided data.
+    pub fn new(
+        input_notes_commitment: Word,
+        output_notes_commitment: Word,
+        batch_expiration_block_num: BlockNumber,
+    ) -> Self {
+        Self {
+            input_notes_commitment,
+            output_notes_commitment,
+            batch_expiration_block_num,
+        }
+    }
+
+    // PUBLIC ACCESSORS
+    // --------------------------------------------------------------------------------------------
+
+    /// Returns the commitment to the batch's input notes.
+    pub fn input_notes_commitment(&self) -> Word {
+        self.input_notes_commitment
+    }
+
+    /// Returns the commitment to the batch's output notes.
+    pub fn output_notes_commitment(&self) -> Word {
+        self.output_notes_commitment
+    }
+
+    /// Returns the block number at which the batch expires.
+    pub fn batch_expiration_block_num(&self) -> BlockNumber {
+        self.batch_expiration_block_num
+    }
+}

crates/miden-protocol/src/batch/proposed_batch.rs

@@ -429,6 +429,11 @@ impl ProposedBatch {
         self.id
     }
 
+    /// Returns the header of the reference block this batch is proposed for.
+    pub fn reference_block_header(&self) -> &BlockHeader {
+        &self.reference_block_header
+    }
+
     /// Returns the block number at which the batch will expire.
     pub fn batch_expiration_block_num(&self) -> BlockNumber {
         self.batch_expiration_block_num