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: [
+#!   BLOCK_COMMITMENT,
+#!   BATCH_ID,
+#!   pad(8),
+#! ]
+#!
+#! Outputs: [
+#!   INPUT_NOTES_COMMITMENT,
+#!   BATCH_NOTE_TREE_ROOT,
+#!   batch_expiration_block_num,
+#!   pad(7),
+#! ]
+#!
+#! Where:
+#! - BLOCK_COMMITMENT is the commitment of the batch's reference block.
+#! - BATCH_ID is the batch's `BatchId`, the commitment to its transactions.
+#! - INPUT_NOTES_COMMITMENT will be the sequential hash over every transaction's input note
+#!   commitments. In this skeleton it is the empty word.
+#! - BATCH_NOTE_TREE_ROOT will be the root of the batch note tree built over every transaction's
+#!   output notes. 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,109 @@
+use alloc::vec::Vec;
+
+use miden_core::program::Kernel;
+
+use crate::batch::{BatchId, ProposedBatch};
+use crate::block::BlockNumber;
+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 `[BLOCK_COMMITMENT, BATCH_ID]` as public inputs and emits
+/// `[INPUT_NOTES_COMMITMENT, BATCH_NOTE_TREE_ROOT, 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();
+
+        let stack_inputs = Self::build_input_stack(block_commitment, batch_id);
+        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
+    /// [BLOCK_COMMITMENT, BATCH_ID, pad(8)]
+    /// ```
+    ///
+    /// Where:
+    /// - `BLOCK_COMMITMENT` is the commitment of the batch's reference block.
+    /// - `BATCH_ID` is the batch's [`BatchId`].
+    pub fn build_input_stack(block_commitment: Word, batch_id: BatchId) -> StackInputs {
+        let mut inputs: Vec<Felt> = Vec::with_capacity(8);
+        inputs.extend_from_slice(block_commitment.as_elements());
+        inputs.extend_from_slice(batch_id.as_word().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, BATCH_NOTE_TREE_ROOT, batch_expiration_block_num]
+    /// ```
+    pub fn build_output_stack(
+        input_notes_commitment: Word,
+        batch_note_tree_root: 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(batch_note_tree_root.as_elements());
+        outputs.push(Felt::from(batch_expiration_block_num));
+
+        StackOutputs::new(&outputs).expect("number of stack outputs should be <= 16")
+    }
+
+    // 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::BatchOutputs;