diff --git a/CHANGELOG.md b/CHANGELOG.md index 860d5cf257..aca0a5e54d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,9 @@ ## 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. +- The batch kernel now verifies the batch's transaction list against its `BATCH_ID`, verifies each transaction header, and computes the batch `INPUT_NOTES_COMMITMENT` ([#2905](https://github.com/0xMiden/protocol/pull/2905)). +- The batch kernel now emits `batch_expiration_block_num`, the running minimum of its transactions' expiration block numbers, cross-checked against the proposed batch ([#3019](https://github.com/0xMiden/protocol/pull/3019)). - [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)). diff --git a/Cargo.lock b/Cargo.lock index 0466718c67..28a44d58e6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2103,7 +2103,9 @@ dependencies = [ name = "miden-tx-batch-prover" version = "0.16.0" dependencies = [ + "miden-processor", "miden-protocol", + "miden-prover", ] [[package]] diff --git a/crates/miden-protocol/asm/kernels/batch/lib/memory.masm b/crates/miden-protocol/asm/kernels/batch/lib/memory.masm new file mode 100644 index 0000000000..0f0ad7846a --- /dev/null +++ b/crates/miden-protocol/asm/kernels/batch/lib/memory.masm @@ -0,0 +1,234 @@ +# MEMORY LAYOUT +# ================================================================================================= +# +# Below is the memory layout used by the batch kernel: +# +# +-------------------+-------------------------+----------------------------------+ +# | Address range | Constant | Contents | +# +-------------------+-------------------------+----------------------------------+ +# | 0 | NUM_TRANSACTIONS_PTR | num_transactions (1 felt). | +# | 1 | BATCH_EXPIRATION_PTR | batch_expiration_block_num, | +# | | | the running min over all txs. | +# | 4..8 | BATCH_HASHER_RATE0_PTR | RATE0 of the batch-level | +# | | | poseidon2 hasher state. | +# | 8..12 | BATCH_HASHER_RATE1_PTR | RATE1 of the batch-level hasher. | +# | 12..16 | BATCH_HASHER_CAP_PTR | CAPACITY of the batch-level | +# | | | hasher. | +# | 16 | SCRATCH_WORDS_COUNT_PTR | num_words piped into | +# | | | TX_NOTES_SCRATCH_PTR for the | +# | | | current transaction. | +# | 17 | SCRATCH_WORD_INDEX_PTR | current iteration cursor for the | +# | | | scratch absorption loop. | +# | 20..8212 | TX_TUPLES_PTR | Layer 1 piped data: per | +# | | | transaction `[tx_id[4], | +# | | | account_id_prefix, | +# | | | account_id_suffix, 0, 0]` | +# | | | (8 felts each, sized for up to | +# | | | 1024 transactions). | +# | 8212..32788 | TX_HEADERS_PTR | Layer 2 piped data: per | +# | | | transaction the felt sequence | +# | | | TransactionId::new hashes | +# | | | (24 felts each, sized for up to | +# | | | 1024 transactions). | +# | 32788..40980 | TX_NOTES_SCRATCH_PTR | Per-transaction scratch space | +# | | | for Layer 3 / Layer 3' note | +# | | | data (overwritten each tx). | +# +-------------------+-------------------------+----------------------------------+ + +# BOOK KEEPING +# ================================================================================================= + +#! Single-felt slot holding `num_transactions` after Layer 1 verification. +const NUM_TRANSACTIONS_PTR=0 + +#! Single-felt slot holding `batch_expiration_block_num`: the running minimum of every +#! transaction's `expiration_block_num`, initialised to `u32::MAX`. +const BATCH_EXPIRATION_PTR=1 + +# BATCH HASHER STATE +# ================================================================================================= + +#! Word holding the RATE0 portion of the batch-level poseidon2 hasher state. +const BATCH_HASHER_RATE0_PTR=4 + +#! Word holding the RATE1 portion of the batch-level poseidon2 hasher state. +const BATCH_HASHER_RATE1_PTR=8 + +#! Word holding the CAPACITY portion of the batch-level poseidon2 hasher state. +const BATCH_HASHER_CAP_PTR=12 + +# SCRATCH BOOKKEEPING +# ================================================================================================= + +#! Number of words piped into TX_NOTES_SCRATCH_PTR for the transaction whose Layer 3 / 3' is +#! being absorbed. +const SCRATCH_WORDS_COUNT_PTR=16 + +#! Iteration cursor (index in words) into TX_NOTES_SCRATCH_PTR for the absorption loop. +const SCRATCH_WORD_INDEX_PTR=17 + +# PIPED DATA REGIONS +# ================================================================================================= + +#! Base of the Layer 1 piped data region. Per transaction, 8 felts: +#! `[tx_id[4], account_id_prefix, account_id_suffix, 0, 0]`. +pub const TX_TUPLES_PTR=20 + +#! Number of felts each transaction occupies in TX_TUPLES_PTR. +const TX_TUPLE_FELT_LEN=8 + +#! Base of the Layer 2 piped data region. Per transaction, 24 felts: +#! `[INIT[4], FINAL[4], INPUT_NOTES_COMMITMENT[4], OUTPUT_NOTES_COMMITMENT[4], FEE_ASSET[8]]`. +#! This must match the felt-sequence layout of `TransactionId::new`. +const TX_HEADERS_PTR=8212 + +#! Number of felts each transaction occupies in TX_HEADERS_PTR. +const TX_HEADER_FELT_LEN=24 + +#! Felt offset within a transaction header where INPUT_NOTES_COMMITMENT starts. +const TX_HEADER_INPUT_NOTES_OFFSET=8 + +#! Felt offset within a transaction header where OUTPUT_NOTES_COMMITMENT starts. +const TX_HEADER_OUTPUT_NOTES_OFFSET=12 + +#! Per-transaction scratch space for Layer 3 note data, overwritten between iterations. +pub const TX_NOTES_SCRATCH_PTR=32788 + +# NUM TRANSACTIONS +# ================================================================================================= + +#! Stores `num_transactions`. +#! +#! Inputs: [num_transactions] +#! Outputs: [] +pub proc set_num_transactions + mem_store.NUM_TRANSACTIONS_PTR +end + +#! Returns `num_transactions`. +#! +#! Inputs: [] +#! Outputs: [num_transactions] +pub proc get_num_transactions + mem_load.NUM_TRANSACTIONS_PTR +end + +# BATCH EXPIRATION BLOCK NUM +# ================================================================================================= + +#! Stores `batch_expiration_block_num`. +#! +#! Inputs: [batch_expiration_block_num] +#! Outputs: [] +pub proc set_batch_expiration_block_num + mem_store.BATCH_EXPIRATION_PTR +end + +#! Returns `batch_expiration_block_num`. +#! +#! Inputs: [] +#! Outputs: [batch_expiration_block_num] +pub proc get_batch_expiration_block_num + mem_load.BATCH_EXPIRATION_PTR +end + +# BATCH HASHER STATE +# ================================================================================================= + +#! Persists the batch hasher state from the operand stack into memory. +#! +#! Inputs: [RATE0, RATE1, CAPACITY] +#! Outputs: [] +pub proc save_batch_hasher_state + mem_storew_le.BATCH_HASHER_RATE0_PTR dropw + mem_storew_le.BATCH_HASHER_RATE1_PTR dropw + mem_storew_le.BATCH_HASHER_CAP_PTR dropw +end + +#! Loads the batch hasher state from memory onto the operand stack. +#! +#! Inputs: [] +#! Outputs: [RATE0, RATE1, CAPACITY] +pub proc load_batch_hasher_state + padw mem_loadw_le.BATCH_HASHER_CAP_PTR + padw mem_loadw_le.BATCH_HASHER_RATE1_PTR + padw mem_loadw_le.BATCH_HASHER_RATE0_PTR +end + +# SCRATCH BOOKKEEPING +# ================================================================================================= + +#! Stores the count (in words) of data piped into the per-transaction scratch. +#! +#! Inputs: [num_words] +#! Outputs: [] +pub proc set_scratch_words_count + mem_store.SCRATCH_WORDS_COUNT_PTR +end + +#! Returns the count (in words) of data piped into the per-transaction scratch. +#! +#! Inputs: [] +#! Outputs: [num_words] +pub proc get_scratch_words_count + mem_load.SCRATCH_WORDS_COUNT_PTR +end + +#! Stores the absorption iteration cursor (index in words). +#! +#! Inputs: [word_index] +#! Outputs: [] +pub proc set_scratch_word_index + mem_store.SCRATCH_WORD_INDEX_PTR +end + +#! Returns the absorption iteration cursor (index in words). +#! +#! Inputs: [] +#! Outputs: [word_index] +pub proc get_scratch_word_index + mem_load.SCRATCH_WORD_INDEX_PTR +end + +# TRANSACTION TUPLE / HEADER ACCESSORS +# ================================================================================================= + +#! Returns a pointer to transaction `tx_index`'s entry in TX_TUPLES_PTR. +#! +#! Inputs: [tx_index] +#! Outputs: [tx_tuple_ptr] +pub proc tx_tuple_ptr + mul.TX_TUPLE_FELT_LEN add.TX_TUPLES_PTR +end + +#! Returns the verified `tx_id` for transaction `tx_index` (loaded from TX_TUPLES_PTR). +#! +#! Inputs: [tx_index] +#! Outputs: [TX_ID] +pub proc get_tx_id + exec.tx_tuple_ptr padw movup.4 mem_loadw_le +end + +#! Returns a pointer to transaction `tx_index`'s entry in TX_HEADERS_PTR. +#! +#! Inputs: [tx_index] +#! Outputs: [tx_header_ptr] +pub proc tx_header_ptr + mul.TX_HEADER_FELT_LEN add.TX_HEADERS_PTR +end + +#! Returns the verified per-transaction INPUT_NOTES_COMMITMENT for transaction `tx_index`. +#! +#! Inputs: [tx_index] +#! Outputs: [INPUT_NOTES_COMMITMENT_i] +pub proc get_tx_input_notes_commitment + exec.tx_header_ptr add.TX_HEADER_INPUT_NOTES_OFFSET padw movup.4 mem_loadw_le +end + +#! Returns the verified per-transaction OUTPUT_NOTES_COMMITMENT for transaction `tx_index`. +#! +#! Inputs: [tx_index] +#! Outputs: [OUTPUT_NOTES_COMMITMENT_i] +pub proc get_tx_output_notes_commitment + exec.tx_header_ptr add.TX_HEADER_OUTPUT_NOTES_OFFSET padw movup.4 mem_loadw_le +end diff --git a/crates/miden-protocol/asm/kernels/batch/lib/note_tracker.masm b/crates/miden-protocol/asm/kernels/batch/lib/note_tracker.masm new file mode 100644 index 0000000000..1b5f4853a6 --- /dev/null +++ b/crates/miden-protocol/asm/kernels/batch/lib/note_tracker.masm @@ -0,0 +1,137 @@ +use miden::core::mem +use miden::core::crypto::hashes::poseidon2 +use miden::core::word + +use miden::batch_kernel::memory +use miden::batch_kernel::memory::TX_NOTES_SCRATCH_PTR + +# ABSORPTION HELPER +# ================================================================================================= + +#! Absorbs the contents of [`memory::TX_NOTES_SCRATCH_PTR`] into the batch hasher state held in +#! [`memory::BATCH_HASHER_*_PTR`] memory slots. +#! +#! The scratch region is read as `(NULLIFIER, EMPTY_OR_NOTE_ID)` 8-felt tuples, in the order they +#! were piped (which matches `build_input_note_commitment` in Rust). +#! +#! The number of words to absorb is read from [`memory::SCRATCH_WORDS_COUNT_PTR`]. +#! +#! Inputs: [] +#! Outputs: [] +proc absorb_scratch_into_batch_hasher + push.0 exec.memory::set_scratch_word_index + + exec.memory::load_batch_hasher_state + # => [RATE0, RATE1, CAPACITY] + + exec.memory::get_scratch_word_index + exec.memory::get_scratch_words_count + u32lt + # => [should_loop, RATE0, RATE1, CAPACITY] + + while.true + exec.memory::get_scratch_word_index + mul.4 add.TX_NOTES_SCRATCH_PTR + # => [scratch_ptr, RATE0, RATE1, CAPACITY] + + padw dup.4 mem_loadw_le + # => [DATA1, scratch_ptr, RATE0, RATE1, CAPACITY] + + padw dup.8 add.4 mem_loadw_le + # => [DATA2, DATA1, scratch_ptr, RATE0, RATE1, CAPACITY] + + movup.8 drop + # => [DATA2, DATA1, RATE0, RATE1, CAPACITY] + + # Replace RATE0 + RATE1 with DATA1 + DATA2 (DATA1 first, DATA2 second), then permute. + swapdw + dropw dropw + swapw + exec.poseidon2::permute + # => [RATE0', RATE1', CAPACITY'] + + exec.memory::get_scratch_word_index add.2 exec.memory::set_scratch_word_index + exec.memory::get_scratch_word_index + exec.memory::get_scratch_words_count + u32lt + # => [should_loop, RATE0, RATE1, CAPACITY] + end + + exec.memory::save_batch_hasher_state +end + +# INPUT NOTES COMMITMENT +# ================================================================================================= + +#! Computes the batch's INPUT_NOTES_COMMITMENT. +#! +#! For each transaction in transaction order, verifies the per-transaction +#! `INPUT_NOTES_COMMITMENT_i` against its advice-map value (the `(NULLIFIER, EMPTY_OR_COMMITMENT)` +#! tuple list), then absorbs that verified data into the batch-level sequential hasher. +#! +#! Inputs: [] +#! Outputs: [INPUT_NOTES_COMMITMENT] +#! +#! Panics if a transaction's `(NULLIFIER, EMPTY_OR_COMMITMENT)` tuple list piped from the advice map +#! does not hash to its verified per-tx `INPUT_NOTES_COMMITMENT_i`. +#! +#! TODO: erase intra-batch unauthenticated notes from the absorbed sequence (see +#! `InputOutputNoteTracker::from_transactions`). +#! TODO: re-sort + dedupe by nullifier so the result equals +#! `proposed_batch.input_notes().commitment()`. +#! TODO: authenticate unauthenticated input notes against `BLOCK_HASH`'s chain MMR. +#! TODO: enforce `MAX_INPUT_NOTES_PER_BATCH`. +pub proc compute_input_notes_commitment + exec.poseidon2::init_no_padding + exec.memory::save_batch_hasher_state + + exec.memory::get_num_transactions + push.0 + # => [tx_index, num_transactions] + + dup.1 dup.1 neq + # => [should_loop, tx_index, num_transactions] + + while.true + dup exec.memory::get_tx_input_notes_commitment + # => [INPUT_NOTES_COMMITMENT_i, tx_index, num_transactions] + + dupw exec.word::eqz + # => [is_empty, INPUT_NOTES_COMMITMENT_i, tx_index, num_transactions] + + if.true + dropw + else + push.TX_NOTES_SCRATCH_PTR movdn.4 + # => [INPUT_NOTES_COMMITMENT_i, tx_notes_scratch_ptr, tx_index, num_transactions] + + adv.push_mapvaln + adv_push div.4 + # => [num_words, INPUT_NOTES_COMMITMENT_i, tx_notes_scratch_ptr, tx_index, num_transactions] + + dup exec.memory::set_scratch_words_count + + movup.5 swap + # => [num_words, tx_notes_scratch_ptr, INPUT_NOTES_COMMITMENT_i, tx_index, num_transactions] + + # Pipe the note data into scratch, asserting its poseidon2 hash equals + # INPUT_NOTES_COMMITMENT_i. + exec.mem::pipe_preimage_to_memory + # => [end_ptr, tx_index, num_transactions] + drop + + exec.absorb_scratch_into_batch_hasher + end + # => [tx_index, num_transactions] + + add.1 + dup.1 dup.1 neq + # => [should_loop, tx_index, num_transactions] + end + + drop drop + + exec.memory::load_batch_hasher_state + exec.poseidon2::squeeze_digest + # => [INPUT_NOTES_COMMITMENT] +end diff --git a/crates/miden-protocol/asm/kernels/batch/lib/prologue.masm b/crates/miden-protocol/asm/kernels/batch/lib/prologue.masm new file mode 100644 index 0000000000..b2350fd4f5 --- /dev/null +++ b/crates/miden-protocol/asm/kernels/batch/lib/prologue.masm @@ -0,0 +1,136 @@ +use miden::core::mem + +use miden::batch_kernel::memory +use miden::batch_kernel::memory::TX_TUPLES_PTR + +# CONSTANTS +# ================================================================================================= + +#! Maximum value of `batch_expiration_block_num`, used as the running-min initialiser. +const MAX_BLOCK_NUM=0xFFFFFFFF + +# PROLOGUE +# ================================================================================================= + +#! Loads and verifies the batch's structural commitments from the advice provider. +#! +#! Performs two steps: +#! - Layer 1: pipes the `(tx_id, account_id)` tuples from the advice map keyed by `BATCH_ID` into +#! [`memory::TX_TUPLES_PTR`], asserting that the sequential hash of the piped data matches +#! `BATCH_ID`. The number of transactions is derived from the piped length and stored in +#! [`memory::NUM_TRANSACTIONS_PTR`]. +#! - Layer 2: for each transaction, pipes the felt sequence hashed by `TransactionId::new` from the +#! advice map keyed by the verified `tx_id`, asserting that the sequential hash matches the +#! `tx_id`. Each transaction's data is written into [`memory::TX_HEADERS_PTR`] at the appropriate +#! per-tx offset. For each transaction, pops its `expiration_block_num` from the advice stack and +#! updates the running minimum in [`memory::BATCH_EXPIRATION_PTR`]. +#! +#! `BATCH_ID` is the batch's `BatchId` value, i.e. the sequential hash of the `(tx_id, account_id)` +#! tuples committing to the transactions in the batch. +#! +#! Inputs: +#! Operand stack: [BATCH_ID] +#! Advice map: +#! BATCH_ID |-> [(tx_id_0, account_id_0_pair), (tx_id_1, account_id_1_pair), ...] +#! For each verified tx_id_i: +#! tx_id_i |-> [INIT_i, FINAL_i, INPUT_NOTES_COMMITMENT_i, OUTPUT_NOTES_COMMITMENT_i, +#! FEE_ASSET_i] +#! Advice stack: [expiration_block_num_0, expiration_block_num_1, ...] +#! +#! Outputs: +#! Operand stack: [] +#! +#! Panics if: +#! - the `(tx_id, account_id)` tuple list piped from the advice map does not hash to `BATCH_ID`. +#! - a transaction's `(INIT, FINAL, INPUT_NOTES_COMMITMENT, OUTPUT_NOTES_COMMITMENT, FEE_ASSET)` +#! data piped from the advice map does not hash to its `tx_id`. +#! +#! TODO: verify that each transaction's reference block is contained in the chain MMR rooted at +#! BLOCK_COMMITMENT. +#! TODO: verify that the partial-blockchain peaks hash matches the block header's chain commitment. +#! TODO: assert each `expiration_block_num_i > reference_block_num`. +#! TODO: derive each `expiration_block_num_i` from data committed-to in the verified transaction +#! header rather than from the unverified advice stack. +pub proc prepare_batch + # Layer 1: pipe BATCH_ID's mapped value to tx_tuples_ptr + verify. + # --------------------------------------------------------------------------------------------- + + # => [BATCH_ID] + push.TX_TUPLES_PTR movdn.4 + # => [BATCH_ID, tx_tuples_ptr] + + adv.push_mapvaln + # AS => [len_felts, data...] + + adv_push div.4 + # => [num_words, BATCH_ID, tx_tuples_ptr] + + # num_transactions = num_words / 2 (each tx contributes 2 words: tx_id + account_id_pair). + dup div.2 exec.memory::set_num_transactions + + movup.5 swap + # => [num_words, tx_tuples_ptr, BATCH_ID] + + # Pipe the tuples into memory, asserting their poseidon2 hash equals BATCH_ID. + exec.mem::pipe_preimage_to_memory + # => [end_ptr] + drop + + # Initialise batch_expiration_block_num to u32::MAX. + # --------------------------------------------------------------------------------------------- + + push.MAX_BLOCK_NUM exec.memory::set_batch_expiration_block_num + + # Layer 2: for each transaction, pipe + verify its header, accumulate expiration min. + # --------------------------------------------------------------------------------------------- + + exec.memory::get_num_transactions + push.0 + # => [tx_index, num_transactions] + + dup.1 dup.1 neq + # => [should_loop, tx_index, num_transactions] + + while.true + dup exec.memory::get_tx_id + # => [TX_ID, tx_index, num_transactions] + + dup.4 exec.memory::tx_header_ptr movdn.4 + # => [TX_ID, tx_header_ptr, tx_index, num_transactions] + + adv.push_mapvaln + adv_push div.4 + # => [num_words, TX_ID, tx_header_ptr, tx_index, num_transactions] + + movup.5 swap + # => [num_words, tx_header_ptr, TX_ID, tx_index, num_transactions] + + # Pipe the header into memory, asserting its poseidon2 hash equals TX_ID. + exec.mem::pipe_preimage_to_memory + # => [end_ptr, tx_index, num_transactions] + drop + + # Accumulate the expiration running-min from the advice stack. + adv_push + # => [expiration, tx_index, num_transactions] + + dup exec.memory::get_batch_expiration_block_num + # => [current_min, expiration, expiration, tx_index, num_transactions] + + u32lt + # => [is_new_min, expiration, tx_index, num_transactions] + + if.true + exec.memory::set_batch_expiration_block_num + else + drop + end + # => [tx_index, num_transactions] + + add.1 + dup.1 dup.1 neq + # => [should_loop, tx_index, num_transactions] + end + + drop drop +end diff --git a/crates/miden-protocol/asm/kernels/batch/main.masm b/crates/miden-protocol/asm/kernels/batch/main.masm new file mode 100644 index 0000000000..b751b733fc --- /dev/null +++ b/crates/miden-protocol/asm/kernels/batch/main.masm @@ -0,0 +1,95 @@ +use miden::core::sys + +use miden::batch_kernel::memory +use miden::batch_kernel::note_tracker +use miden::batch_kernel::prologue + +# MAIN +# ================================================================================================= + +#! Batch kernel program. +#! +#! 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 reconstructs the per-transaction data +#! from the advice provider, anchoring the reconstruction in the public `BATCH_ID`, and emits the +#! batch's `INPUT_NOTES_COMMITMENT` and its effective `batch_expiration_block_num`. +#! +#! Reconstruction is a recursive unhashing chain. Each layer of advice data is keyed by a hash that +#! the previous layer's verification produced, so once `BATCH_ID` is anchored to the public input, +#! every felt that feeds `INPUT_NOTES_COMMITMENT` is transitively committed-to: +#! +#! `BATCH_ID` (public input) -> `(tx_id, account_id)` tuple list +#! each `tx_id` -> per-tx +#! `(INIT, FINAL, INPUT_NOTES_COMMITMENT_i, OUTPUT_NOTES_COMMITMENT_i, FEE_ASSET)` +#! each `INPUT_NOTES_COMMITMENT_i` -> `(NULLIFIER, EMPTY_OR_COMMITMENT)` tuples +#! +#! Each layer is loaded via `adv.push_mapvaln` keyed by the previously-verified hash and asserted +#! against that hash via `assert_eqw`. Only verified data feeds into the batch output. +#! +#! 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 sequential hash of the `(tx_id, account_id)` tuples +#! committing to the transactions in the batch. +#! - INPUT_NOTES_COMMITMENT is the sequential hash over every transaction's +#! `(NULLIFIER, EMPTY_OR_COMMITMENT)` tuples. +#! - BATCH_NOTE_TREE_ROOT is currently not wired up (empty word). +#! - batch_expiration_block_num is the minimum of every transaction's `expiration_block_num`. +#! +#! TODO: verify BLOCK_COMMITMENT against block header data via the same pipe-and-verify pattern. +#! TODO: authenticate unauthenticated input notes against BLOCK_COMMITMENT's chain MMR. +#! TODO: erase intra-batch unauthenticated notes from INPUT_NOTES_COMMITMENT. +#! TODO: emit BATCH_NOTE_TREE_ROOT (the batch note tree SMT root). +#! TODO: derive batch_expiration_block_num from verified data rather than the unverified advice +#! stack (see `prologue::prepare_batch`). +#! TODO: aggregate per-account updates and emit a separate ACCOUNT_UPDATES_COMMITMENT output. +#! TODO: recursively verify each transaction's `ExecutionProof`. +proc main + # => [BLOCK_COMMITMENT, BATCH_ID, pad(8)] + + # TODO: verify BLOCK_COMMITMENT against block header data via the pipe-and-verify pattern. + dropw + # => [BATCH_ID, pad(12)] + + exec.prologue::prepare_batch + # => [pad(16)] + + exec.note_tracker::compute_input_notes_commitment + # => [INPUT_NOTES_COMMITMENT, pad(16)] + + # Assemble the output region [INPUT_NOTES_COMMITMENT, BATCH_NOTE_TREE_ROOT, expiration]. The + # BATCH_NOTE_TREE_ROOT word stays empty for now (wired up in a follow-up PR). + padw + # => [BATCH_NOTE_TREE_ROOT, INPUT_NOTES_COMMITMENT, pad(16)] + + exec.memory::get_batch_expiration_block_num + # => [batch_expiration_block_num, BATCH_NOTE_TREE_ROOT, INPUT_NOTES_COMMITMENT, pad(16)] + + movdn.8 + # => [BATCH_NOTE_TREE_ROOT, INPUT_NOTES_COMMITMENT, batch_expiration_block_num, pad(16)] + + swapw + # => [INPUT_NOTES_COMMITMENT, BATCH_NOTE_TREE_ROOT, batch_expiration_block_num, pad(16)] + + # batch_expiration_block_num is a single felt, so the output region (9 felts) is not + # word-aligned and the surplus padding cannot be dropped in whole words; truncate the operand + # stack to the 16-felt output [INPUT_NOTES_COMMITMENT, BATCH_NOTE_TREE_ROOT, + # batch_expiration_block_num, pad(7)]. + exec.sys::truncate_stack +end + +begin + exec.main +end diff --git a/crates/miden-protocol/build.rs b/crates/miden-protocol/build.rs index f116980634..f1ff5283b7 100644 --- a/crates/miden-protocol/build.rs +++ b/crates/miden-protocol/build.rs @@ -20,8 +20,10 @@ 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"; +const BATCH_KERNEL_NAMESPACE: &str = "miden::batch_kernel"; const KERNEL_PROCEDURES_RS_FILE: &str = "procedures.rs"; const TX_KERNEL_ERRORS_RS_FILE: &str = "tx_kernel_errors.rs"; @@ -85,6 +87,9 @@ 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)?; @@ -92,6 +97,28 @@ fn main() -> Result<()> { 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. +/// +/// The modules under `kernels/batch/lib/` are statically linked under the `miden::batch_kernel` +/// namespace so `main.masm` can `use` them. +fn compile_batch_kernel(source_dir: &Path, target_dir: &Path) -> Result<()> { + let batch_kernel_dir = source_dir.join(ASM_BATCH_KERNEL_DIR); + let lib_dir = batch_kernel_dir.join("lib"); + let main_file_path = batch_kernel_dir.join("main.masm"); + + let mut assembler = build_assembler(None)?; + assembler.compile_and_statically_link_from_dir(&lib_dir, BATCH_KERNEL_NAMESPACE)?; + + 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 // ================================================================================================ diff --git a/crates/miden-protocol/src/batch/batch_id.rs b/crates/miden-protocol/src/batch/batch_id.rs index 39cfe42255..b3f7c10762 100644 --- a/crates/miden-protocol/src/batch/batch_id.rs +++ b/crates/miden-protocol/src/batch/batch_id.rs @@ -37,14 +37,26 @@ impl BatchId { /// Calculates a batch ID from the given transaction ID and account ID tuple. pub fn from_ids(iter: impl IntoIterator) -> Self { + Self(Hasher::hash_elements(&Self::hash_input_elements(iter))) + } + + /// Returns the felt sequence that [`Self::from_ids`] hashes to produce a [`BatchId`]. + /// + /// The layout is, for each `(transaction_id, account_id)` pair in iteration order: + /// `[transaction_id[4], account_id_prefix, account_id_suffix, 0, 0]` + /// + /// The batch kernel pipes this same felt sequence from the advice provider to memory and + /// asserts the resulting hash matches the public input `BATCH_ID`. + pub(crate) fn hash_input_elements( + iter: impl IntoIterator, + ) -> Vec { let mut elements: Vec = Vec::new(); for (tx_id, account_id) in iter { elements.extend_from_slice(tx_id.as_elements()); let [account_id_prefix, account_id_suffix] = <[Felt; 2]>::from(account_id); elements.extend_from_slice(&[account_id_prefix, account_id_suffix, ZERO, ZERO]); } - - Self(Hasher::hash_elements(&elements)) + elements } } diff --git a/crates/miden-protocol/src/batch/kernel.rs b/crates/miden-protocol/src/batch/kernel.rs new file mode 100644 index 0000000000..81a5c7cc2d --- /dev/null +++ b/crates/miden-protocol/src/batch/kernel.rs @@ -0,0 +1,168 @@ +use alloc::vec::Vec; + +use miden_core::program::Kernel; + +use crate::batch::{BatchId, ProposedBatch}; +use crate::block::BlockNumber; +use crate::transaction::TransactionId; +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 = 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 = 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 = 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 consumed by the batch kernel. + /// + /// The kernel reconstructs and verifies the batch's `INPUT_NOTES_COMMITMENT` by walking a + /// layered advice map, each layer keyed by a hash the previous layer verified: + /// - `BATCH_ID` -> the `(tx_id, account_id)` tuple list (matching + /// `BatchId::hash_input_elements`). + /// - each `tx_id` -> the transaction header felt sequence (matching + /// `TransactionId::input_elements`). + /// - each per-tx `INPUT_NOTES_COMMITMENT` -> the `(NULLIFIER, EMPTY_OR_COMMITMENT)` tuples. + /// + /// It also pushes each transaction's `expiration_block_num` onto the advice stack, from which + /// the kernel accumulates the batch-wide running minimum. + /// + /// The per-tx output-notes layer is wired up in a follow-up PR. + fn build_advice_inputs(proposed_batch: &ProposedBatch) -> AdviceInputs { + let mut advice_inputs = AdviceInputs::default(); + + // Layer 1: BATCH_ID -> [(tx_id, account_id) tuples]. + let layer1_data = BatchId::hash_input_elements( + proposed_batch.transactions().iter().map(|tx| (tx.id(), tx.account_id())), + ); + advice_inputs.map.extend([(proposed_batch.id().as_word(), layer1_data)]); + + for tx in proposed_batch.transactions().iter() { + // Layer 2: tx_id -> the felt sequence TransactionId::new hashes. + let header_data = TransactionId::input_elements( + tx.account_update().initial_state_commitment(), + tx.account_update().final_state_commitment(), + tx.input_notes().commitment(), + tx.output_notes().commitment(), + tx.fee(), + ); + advice_inputs.map.extend([(tx.id().as_word(), header_data.to_vec())]); + + // Layer 3: per-tx INPUT_NOTES_COMMITMENT -> [(NULLIFIER, EMPTY_OR_NOTE_ID) tuples]. + // This must reproduce `build_input_note_commitment` exactly: per note, the nullifier + // followed by the note ID (or the empty word for authenticated notes). + let input_notes_commitment = tx.input_notes().commitment(); + if input_notes_commitment != Word::empty() { + let mut notes_commitment_preimage_data: Vec = + Vec::with_capacity(usize::from(tx.input_notes().num_notes()) * 8); + for note_commit in tx.input_notes().iter() { + notes_commitment_preimage_data + .extend_from_slice(note_commit.nullifier().as_word().as_elements()); + let note_id_or_empty = + note_commit.header().map_or(Word::empty(), |header| header.id().as_word()); + notes_commitment_preimage_data + .extend_from_slice(note_id_or_empty.as_elements()); + } + advice_inputs + .map + .extend([(input_notes_commitment, notes_commitment_preimage_data)]); + } + } + + // Advice stack: each transaction's expiration_block_num, in transaction order. The kernel + // pops one per transaction and accumulates the running minimum; order is irrelevant to the + // resulting minimum. + for tx in proposed_batch.transactions().iter() { + advice_inputs.stack.push(Felt::from(tx.expiration_block_num())); + } + + advice_inputs + } +} diff --git a/crates/miden-protocol/src/batch/mod.rs b/crates/miden-protocol/src/batch/mod.rs index 24916522eb..f8235397e8 100644 --- a/crates/miden-protocol/src/batch/mod.rs +++ b/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; diff --git a/crates/miden-protocol/src/batch/output.rs b/crates/miden-protocol/src/batch/output.rs new file mode 100644 index 0000000000..7759472b80 --- /dev/null +++ b/crates/miden-protocol/src/batch/output.rs @@ -0,0 +1,202 @@ +use crate::block::BlockNumber; +use crate::errors::BatchOutputError; +use crate::vm::StackOutputs; +use crate::{Felt, Word}; + +// BATCH OUTPUTS +// ================================================================================================ + +/// The public outputs produced by the batch kernel. +/// +/// This is the parsed, typed form of the kernel's output stack. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct BatchOutputs { + /// The commitment to the batch's input notes. + input_notes_commitment: Word, + /// The root of the batch's note tree (the [`BatchNoteTree`](crate::batch::BatchNoteTree)) over + /// the batch's output notes. + batch_note_tree_root: Word, + /// The block number at which the batch expires. + batch_expiration_block_num: BlockNumber, +} + +impl BatchOutputs { + // 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 batch note tree root word starts on the output stack. + pub const BATCH_NOTE_TREE_ROOT_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 [`BatchOutputs`] instantiated from the provided data. + pub fn new( + input_notes_commitment: Word, + batch_note_tree_root: Word, + batch_expiration_block_num: BlockNumber, + ) -> Self { + Self { + input_notes_commitment, + batch_note_tree_root, + batch_expiration_block_num, + } + } + + // PARSER + // -------------------------------------------------------------------------------------------- + + /// Parses the batch kernel's output stack into a [`BatchOutputs`]. + /// + /// # Errors + /// + /// Returns [`BatchOutputError::OutputStackInvalid`] if: + /// - a required output word or element is missing from the stack; + /// - the cells following `batch_expiration_block_num` (positions 9..16) are not all zero. + /// + /// Returns [`BatchOutputError::ExpirationBlockNumberTooLarge`] if `batch_expiration_block_num` + /// does not fit into a `u32`. + pub fn parse(stack: &StackOutputs) -> Result { + let input_notes_commitment = + stack.get_word(Self::INPUT_NOTES_COMMITMENT_WORD_IDX).ok_or_else(|| { + BatchOutputError::OutputStackInvalid( + "input notes commitment word missing from output stack".into(), + ) + })?; + let batch_note_tree_root = + stack.get_word(Self::BATCH_NOTE_TREE_ROOT_WORD_IDX).ok_or_else(|| { + BatchOutputError::OutputStackInvalid( + "batch note tree root word missing from output stack".into(), + ) + })?; + + let expiration_felt = + stack.get_element(Self::BATCH_EXPIRATION_BLOCK_NUM_ELEMENT_IDX).ok_or_else(|| { + BatchOutputError::OutputStackInvalid( + "batch expiration block number missing from output stack".into(), + ) + })?; + + // Every cell after batch_expiration_block_num must be zero padding. + if stack[Self::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(Self::new( + input_notes_commitment, + batch_note_tree_root, + 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 root of the batch's note tree. + pub fn batch_note_tree_root(&self) -> Word { + self.batch_note_tree_root + } + + /// Returns the block number at which the batch expires. + pub fn batch_expiration_block_num(&self) -> BlockNumber { + self.batch_expiration_block_num + } +} + +// TESTS +// ================================================================================================ + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parse_returns_outputs_for_well_formed_stack() { + let input_notes_commitment = + Word::from([Felt::from(1u32), Felt::from(2u32), Felt::from(3u32), Felt::from(4u32)]); + let batch_note_tree_root = + Word::from([Felt::from(5u32), Felt::from(6u32), Felt::from(7u32), Felt::from(8u32)]); + let elements = [ + Felt::from(1u32), + Felt::from(2u32), + Felt::from(3u32), + Felt::from(4u32), + Felt::from(5u32), + Felt::from(6u32), + Felt::from(7u32), + Felt::from(8u32), + Felt::from(1234u32), + ]; + let stack = StackOutputs::new(&elements).unwrap(); + + let outputs = BatchOutputs::parse(&stack).unwrap(); + + assert_eq!(outputs.input_notes_commitment(), input_notes_commitment); + assert_eq!(outputs.batch_note_tree_root(), batch_note_tree_root); + assert_eq!(outputs.batch_expiration_block_num(), BlockNumber::from(1234u32)); + } + + #[test] + fn parse_rejects_non_zero_padding() { + // A valid 9-element output followed by a non-zero felt in the padding region (>= idx 9). + let elements = [ + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::from(7u32), + Felt::from(1u32), + ]; + let stack = StackOutputs::new(&elements).unwrap(); + + assert!(matches!( + BatchOutputs::parse(&stack), + Err(BatchOutputError::OutputStackInvalid(_)) + )); + } + + #[test] + fn parse_rejects_oversized_expiration() { + // An expiration value that does not fit into a u32. + let oversized = Felt::from(u32::MAX) + Felt::from(1u32); + let elements = [ + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + Felt::ZERO, + oversized, + ]; + let stack = StackOutputs::new(&elements).unwrap(); + + assert!(matches!( + BatchOutputs::parse(&stack), + Err(BatchOutputError::ExpirationBlockNumberTooLarge(_)) + )); + } +} diff --git a/crates/miden-protocol/src/batch/proposed_batch.rs b/crates/miden-protocol/src/batch/proposed_batch.rs index 5065b96660..e16560cfa7 100644 --- a/crates/miden-protocol/src/batch/proposed_batch.rs +++ b/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 diff --git a/crates/miden-protocol/src/batch/proven_batch.rs b/crates/miden-protocol/src/batch/proven_batch.rs index 32a0bf9d18..753ceaf67a 100644 --- a/crates/miden-protocol/src/batch/proven_batch.rs +++ b/crates/miden-protocol/src/batch/proven_batch.rs @@ -15,11 +15,11 @@ use crate::utils::serde::{ DeserializationError, Serializable, }; +use crate::vm::ExecutionProof; use crate::{MIN_PROOF_SECURITY_LEVEL, Word}; /// A transaction batch with an execution proof. -/// Currently, there is no proof attached. Future versions will extend this structure to include -/// a proof artifact once recursive proving is implemented. +/// Currently, this only carries a skeleton proof which does not attest to anything meaningful. #[derive(Debug, Clone, PartialEq, Eq)] pub struct ProvenBatch { id: BatchId, @@ -30,6 +30,7 @@ pub struct ProvenBatch { output_notes: Vec, batch_expiration_block_num: BlockNumber, transactions: OrderedTransactionHeaders, + proof: ExecutionProof, } impl ProvenBatch { @@ -45,6 +46,7 @@ impl ProvenBatch { /// /// Returns an error if the batch expiration block number is not greater than the reference /// block number. + #[allow(clippy::too_many_arguments)] pub fn new_unchecked( id: BatchId, reference_block_commitment: Word, @@ -54,6 +56,7 @@ impl ProvenBatch { output_notes: Vec, batch_expiration_block_num: BlockNumber, transactions: OrderedTransactionHeaders, + proof: ExecutionProof, ) -> Result { // Check that the batch expiration block number is greater than the reference block number. if batch_expiration_block_num <= reference_block_num { @@ -72,6 +75,7 @@ impl ProvenBatch { output_notes, batch_expiration_block_num, transactions, + proof, }) } @@ -144,6 +148,11 @@ impl ProvenBatch { &self.transactions } + /// Returns the execution proof attached to this batch. + pub fn proof(&self) -> &ExecutionProof { + &self.proof + } + // MUTATORS // -------------------------------------------------------------------------------------------- @@ -166,6 +175,7 @@ impl Serializable for ProvenBatch { self.output_notes.write_into(target); self.batch_expiration_block_num.write_into(target); self.transactions.write_into(target); + self.proof.write_into(target); } } @@ -179,6 +189,7 @@ impl Deserializable for ProvenBatch { let output_notes = Vec::::read_from(source)?; let batch_expiration_block_num = BlockNumber::read_from(source)?; let transactions = OrderedTransactionHeaders::read_from(source)?; + let proof = ExecutionProof::read_from(source)?; Self::new_unchecked( id, @@ -189,6 +200,7 @@ impl Deserializable for ProvenBatch { output_notes, batch_expiration_block_num, transactions, + proof, ) .map_err(|e| DeserializationError::UnknownError(e.to_string())) } diff --git a/crates/miden-protocol/src/errors/mod.rs b/crates/miden-protocol/src/errors/mod.rs index 84142d394d..59e0f0d67c 100644 --- a/crates/miden-protocol/src/errors/mod.rs +++ b/crates/miden-protocol/src/errors/mod.rs @@ -9,6 +9,7 @@ use miden_core::mast::MastForestError; use miden_crypto::merkle::mmr::MmrError; use miden_crypto::merkle::smt::{SmtLeafError, SmtProofError}; use miden_crypto::utils::HexParseError; +use miden_processor::ExecutionError; use miden_verifier::VerificationError; use thiserror::Error; @@ -1091,6 +1092,28 @@ pub enum ProvenBatchError { batch_expiration_block_num: BlockNumber, reference_block_num: BlockNumber, }, + #[error("batch kernel execution failed")] + BatchKernelExecutionFailed(#[source] ExecutionError), + #[error("batch kernel produced an invalid output stack")] + BatchKernelOutputInvalid(#[source] BatchOutputError), + #[error( + "batch kernel computed expiration block number {actual} but the proposed batch expected {expected}" + )] + BatchExpirationMismatch { + actual: BlockNumber, + expected: BlockNumber, + }, +} + +// BATCH OUTPUT ERROR +// ================================================================================================ + +#[derive(Debug, Error)] +pub enum BatchOutputError { + #[error("batch kernel output stack is invalid: {0}")] + OutputStackInvalid(String), + #[error("batch expiration block number {0} does not fit into a u32")] + ExpirationBlockNumberTooLarge(Felt), } // PROPOSED BLOCK ERROR diff --git a/crates/miden-protocol/src/transaction/transaction_id.rs b/crates/miden-protocol/src/transaction/transaction_id.rs index 4313e6c465..14b5f538ee 100644 --- a/crates/miden-protocol/src/transaction/transaction_id.rs +++ b/crates/miden-protocol/src/transaction/transaction_id.rs @@ -35,6 +35,9 @@ use crate::utils::serde::{ pub struct TransactionId(Word); impl TransactionId { + /// Length of the felt sequence hashed by [`Self::new`] / [`Self::input_elements`]. + pub(crate) const INPUT_ELEMENTS_LEN: usize = 6 * WORD_SIZE; + /// Returns a new [TransactionId] instantiated from the provided transaction components. pub fn new( init_account_commitment: Word, @@ -43,13 +46,36 @@ impl TransactionId { output_notes_commitment: Word, fee_asset: FungibleAsset, ) -> Self { - let mut elements = [ZERO; 6 * WORD_SIZE]; + Self(Hasher::hash_elements(&Self::input_elements( + init_account_commitment, + final_account_commitment, + input_notes_commitment, + output_notes_commitment, + fee_asset, + ))) + } + + /// Returns the felt sequence that [`Self::new`] hashes to produce a [`TransactionId`]. + /// + /// The layout is: + /// `[INIT[4], FINAL[4], INPUT_NOTES_COMMITMENT[4], OUTPUT_NOTES_COMMITMENT[4], FEE_ASSET[8]]` + /// + /// The batch kernel pipes this same felt sequence from the advice provider to memory and + /// asserts the resulting hash matches a previously-verified `tx_id`. + pub(crate) fn input_elements( + init_account_commitment: Word, + final_account_commitment: Word, + input_notes_commitment: Word, + output_notes_commitment: Word, + fee_asset: FungibleAsset, + ) -> [Felt; Self::INPUT_ELEMENTS_LEN] { + let mut elements = [ZERO; Self::INPUT_ELEMENTS_LEN]; elements[..4].copy_from_slice(init_account_commitment.as_elements()); elements[4..8].copy_from_slice(final_account_commitment.as_elements()); elements[8..12].copy_from_slice(input_notes_commitment.as_elements()); elements[12..16].copy_from_slice(output_notes_commitment.as_elements()); elements[16..].copy_from_slice(&Asset::from(fee_asset).as_elements()); - Self(Hasher::hash_elements(&elements)) + elements } } diff --git a/crates/miden-testing/src/kernel_tests/batch/mod.rs b/crates/miden-testing/src/kernel_tests/batch/mod.rs index 2832ae06cd..0dd9aaa47b 100644 --- a/crates/miden-testing/src/kernel_tests/batch/mod.rs +++ b/crates/miden-testing/src/kernel_tests/batch/mod.rs @@ -1,2 +1,3 @@ pub(super) mod proposed_batch; mod proven_tx_builder; +mod test_batch_kernel; diff --git a/crates/miden-testing/src/kernel_tests/batch/proposed_batch.rs b/crates/miden-testing/src/kernel_tests/batch/proposed_batch.rs index 9cf1c72f84..7ced384e04 100644 --- a/crates/miden-testing/src/kernel_tests/batch/proposed_batch.rs +++ b/crates/miden-testing/src/kernel_tests/batch/proposed_batch.rs @@ -55,14 +55,14 @@ pub fn mock_output_note(num: u8) -> OutputNote { RawOutputNote::Full(mock_note(num)).into_output_note().unwrap() } -struct TestSetup { - chain: MockChain, - account1: Account, - account2: Account, - note1: Note, +pub struct TestSetup { + pub chain: MockChain, + pub account1: Account, + pub account2: Account, + pub note1: Note, } -fn setup_chain() -> TestSetup { +pub fn setup_chain() -> TestSetup { let mut builder = MockChain::builder(); let account1 = generate_account(&mut builder); let account2 = generate_account(&mut builder); diff --git a/crates/miden-testing/src/kernel_tests/batch/test_batch_kernel.rs b/crates/miden-testing/src/kernel_tests/batch/test_batch_kernel.rs new file mode 100644 index 0000000000..05e6188c79 --- /dev/null +++ b/crates/miden-testing/src/kernel_tests/batch/test_batch_kernel.rs @@ -0,0 +1,195 @@ +use alloc::sync::Arc; +use alloc::vec::Vec; +use std::collections::BTreeMap; + +use anyhow::Context; +use miden_protocol::batch::{BatchKernel, ProposedBatch}; +use miden_protocol::block::BlockNumber; +use miden_protocol::vm::AdviceInputs; +use miden_protocol::{Felt, Hasher, Word}; +use miden_tx_batch_prover::{BatchExecutor, LocalBatchProver}; + +use super::proposed_batch::{TestSetup, mock_note, mock_output_note, setup_chain}; +use super::proven_tx_builder::MockProvenTxBuilder; + +// SETUP HELPERS +// ================================================================================================ + +/// Builds a two-transaction batch: +/// - tx1 (account1): consumes one authenticated input note, produces one output note. +/// - tx2 (account2): consumes one unauthenticated input note, produces two output notes. +pub(super) fn two_tx_batch(setup: &mut TestSetup) -> anyhow::Result { + let block1 = setup.chain.block_header(1); + let block2 = setup.chain.prove_next_block()?; + + let tx1 = MockProvenTxBuilder::with_account( + setup.account1.id(), + Word::empty(), + setup.account1.to_commitment(), + ) + .reference_block(&block1) + .authenticated_notes(vec![setup.note1.clone()]) + .output_notes(vec![mock_output_note(80)]) + .expiration_block_num(BlockNumber::from(1234u32)) + .build()?; + + let tx2_input = mock_note(81); + let tx2 = MockProvenTxBuilder::with_account( + setup.account2.id(), + Word::empty(), + setup.account2.to_commitment(), + ) + .reference_block(&block1) + .unauthenticated_notes(vec![tx2_input]) + .output_notes(vec![mock_output_note(82), mock_output_note(83)]) + .expiration_block_num(BlockNumber::from(800u32)) + .build()?; + + Ok(ProposedBatch::new_unverified( + [tx1, tx2].into_iter().map(Arc::new).collect(), + block2.header().clone(), + setup.chain.latest_partial_blockchain(), + BTreeMap::default(), + )?) +} + +// EXPECTED-VALUE HELPERS +// ================================================================================================ + +/// Sequential hash over `(NULLIFIER, EMPTY_OR_NOTE_ID)` tuples for every input note in every +/// transaction in transaction order, mirroring the kernel's per-tx absorption. +/// +/// We cannot compare against `ProposedBatch::input_notes().commitment()` yet: that commitment is +/// over the batch-level input notes re-sorted and deduped by nullifier, whereas the kernel +/// currently absorbs notes in transaction order without that re-sort/dedupe (tracked as a TODO in +/// `note_tracker.masm`). The two coincide only when transaction order already matches nullifier +/// order; this helper reproduces exactly what the kernel computes today. +fn expected_input_notes_commitment(batch: &ProposedBatch) -> Word { + let mut elements: Vec = Vec::new(); + for tx in batch.transactions() { + for commit in tx.input_notes().iter() { + elements.extend_from_slice(commit.nullifier().as_word().as_elements()); + let note_id_or_empty = + commit.header().map_or(Word::empty(), |header| header.id().as_word()); + elements.extend_from_slice(note_id_or_empty.as_elements()); + } + } + if elements.is_empty() { + Word::empty() + } else { + Hasher::hash_elements(&elements) + } +} + +// TAMPERING HELPERS +// ================================================================================================ + +/// Builds an advice-inputs override that corrupts the advice-map entry stored under `key`, so the +/// kernel's hash check against `key` fails. Fed to [`BatchExecutor::extend_advice_inputs`] to drive +/// the kernel's rejection paths through the normal executor (mirroring how the transaction-kernel +/// tests inject tampered advice via `extend_advice_inputs`; see `test_prologue.rs`). +fn tampered_advice_for(batch: &ProposedBatch, key: Word) -> AdviceInputs { + let (_, advice_inputs) = BatchKernel::prepare_inputs(batch); + let mut tampered: Vec = advice_inputs + .map + .get(&key) + .expect("advice-map entry for key") + .iter() + .copied() + .collect(); + tampered[0] += Felt::from(1u32); + AdviceInputs::default().with_map([(key, tampered)]) +} + +// HAPPY PATH +// ================================================================================================ + +/// The batch kernel reconstructs every transaction's input notes from the advice provider, anchors +/// them in `BATCH_ID`, and emits the batch's `INPUT_NOTES_COMMITMENT` and the running-min +/// `batch_expiration_block_num`. The batch note tree root is not wired up yet, so it remains empty. +#[test] +fn batch_kernel_emits_input_notes_commitment_and_expiration() -> anyhow::Result<()> { + let mut setup = setup_chain(); + let batch = two_tx_batch(&mut setup)?; + let expected_input_notes_commitment = expected_input_notes_commitment(&batch); + // The expected expiration is the minimum over the batch's transactions, which the proposed + // batch derives independently of the kernel. + let expected_expiration = batch.batch_expiration_block_num(); + + let executed = BatchExecutor::new().execute(batch).context("batch execution failed")?; + let output = executed.batch_outputs(); + + assert_eq!(output.input_notes_commitment(), expected_input_notes_commitment); + assert_eq!(output.batch_note_tree_root(), Word::empty()); + assert_eq!(output.batch_expiration_block_num(), expected_expiration); + // Sanity check: the min of the two transactions' expirations (1234 and 800). + assert_eq!(output.batch_expiration_block_num(), BlockNumber::from(800u32)); + + Ok(()) +} + +/// Executing a batch and then proving it produces a [`ProvenBatch`] carrying the kernel's proof. +#[test] +fn batch_executor_then_prover_produces_proven_batch() -> anyhow::Result<()> { + let mut setup = setup_chain(); + let batch = two_tx_batch(&mut setup)?; + let expected_id = batch.id(); + + let executed = BatchExecutor::new().execute(batch).context("batch execution failed")?; + let proven = LocalBatchProver::new().prove(executed).context("batch proving failed")?; + + assert_eq!(proven.id(), expected_id); + + Ok(()) +} + +// NEGATIVE TESTS +// ================================================================================================ +// +// Each test injects a tampered advice-map entry through `BatchExecutor::extend_advice_inputs` and +// asserts the kernel aborts. The executor builds consistent advice from the (valid) `ProposedBatch` +// and the override then corrupts a single layer's entry, breaking that layer's hash check. + +/// Tampering the `BATCH_ID` -> `(tx_id, account_id)` tuples breaks the Layer 1 hash check. +#[test] +fn batch_kernel_rejects_tampered_layer_1() -> anyhow::Result<()> { + let mut setup = setup_chain(); + let batch = two_tx_batch(&mut setup)?; + + let override_advice = tampered_advice_for(&batch, batch.id().as_word()); + + let result = BatchExecutor::new().extend_advice_inputs(override_advice).execute(batch); + assert!(result.is_err(), "kernel must abort on a tampered transaction list"); + + Ok(()) +} + +/// Tampering a verified `tx_id`'s header data breaks the Layer 2 hash check. +#[test] +fn batch_kernel_rejects_tampered_layer_2() -> anyhow::Result<()> { + let mut setup = setup_chain(); + let batch = two_tx_batch(&mut setup)?; + + let tx0_id = batch.transactions()[0].id().as_word(); + let override_advice = tampered_advice_for(&batch, tx0_id); + + let result = BatchExecutor::new().extend_advice_inputs(override_advice).execute(batch); + assert!(result.is_err(), "kernel must abort on a tampered transaction header"); + + Ok(()) +} + +/// Tampering a transaction's input-notes data breaks the Layer 3 (input-notes commitment) check. +#[test] +fn batch_kernel_rejects_tampered_input_notes() -> anyhow::Result<()> { + let mut setup = setup_chain(); + let batch = two_tx_batch(&mut setup)?; + + let key = batch.transactions()[0].input_notes().commitment(); + let override_advice = tampered_advice_for(&batch, key); + + let result = BatchExecutor::new().extend_advice_inputs(override_advice).execute(batch); + assert!(result.is_err(), "kernel must abort on tampered input-notes data"); + + Ok(()) +} diff --git a/crates/miden-testing/src/mock_chain/chain.rs b/crates/miden-testing/src/mock_chain/chain.rs index 72fb63a02d..6e692e1ed2 100644 --- a/crates/miden-testing/src/mock_chain/chain.rs +++ b/crates/miden-testing/src/mock_chain/chain.rs @@ -532,7 +532,7 @@ impl MockChain { proposed_batch: ProposedBatch, ) -> anyhow::Result { let batch_prover = LocalBatchProver::new(); - Ok(batch_prover.prove(proposed_batch)?) + Ok(batch_prover.prove_dummy(proposed_batch)?) } // BLOCK APIS diff --git a/crates/miden-tx-batch-prover/Cargo.toml b/crates/miden-tx-batch-prover/Cargo.toml index 3072b80fa8..8bce000c82 100644 --- a/crates/miden-tx-batch-prover/Cargo.toml +++ b/crates/miden-tx-batch-prover/Cargo.toml @@ -15,12 +15,16 @@ version.workspace = true [lib] bench = false doctest = false -test = false [features] default = ["std"] -std = ["miden-protocol/std"] -testing = [] +std = ["miden-processor/std", "miden-protocol/std", "miden-prover/std"] +testing = ["miden-processor/testing", "miden-protocol/testing"] [dependencies] -miden-protocol = { workspace = true } +miden-processor = { workspace = true } +miden-protocol = { workspace = true } +miden-prover = { workspace = true } + +[dev-dependencies] +miden-protocol = { features = ["testing"], workspace = true } diff --git a/crates/miden-tx-batch-prover/src/batch_executor.rs b/crates/miden-tx-batch-prover/src/batch_executor.rs new file mode 100644 index 0000000000..a37a5fb76c --- /dev/null +++ b/crates/miden-tx-batch-prover/src/batch_executor.rs @@ -0,0 +1,88 @@ +use miden_processor::{DefaultHost, ExecutionError, ExecutionOptions, FastProcessor}; +use miden_protocol::CoreLibrary; +use miden_protocol::batch::{BatchKernel, BatchOutputs, ProposedBatch}; +use miden_protocol::errors::ProvenBatchError; +use miden_protocol::vm::AdviceInputs; + +use crate::ExecutedBatch; + +// BATCH EXECUTOR +// ================================================================================================ + +/// Executes the batch kernel over a [`ProposedBatch`], producing an [`ExecutedBatch`]. +#[derive(Clone, Default)] +pub struct BatchExecutor { + /// Extra advice inputs merged onto those derived from the proposed batch before execution. + advice_inputs: AdviceInputs, +} + +impl BatchExecutor { + /// Creates a new [`BatchExecutor`] instance. + pub fn new() -> Self { + Self::default() + } + + /// Extends the advice inputs merged onto those derived from the proposed batch before + /// execution. Entries provided here override matching keys from the derived advice. + /// + /// This is primarily a testing hook for exercising the batch kernel's rejection paths by + /// injecting tampered advice, mirroring + /// [`TransactionContextBuilder::extend_advice_inputs`](https://docs.rs/miden-testing). + pub fn extend_advice_inputs(mut self, advice_inputs: AdviceInputs) -> Self { + self.advice_inputs.extend(advice_inputs); + self + } + + /// Runs the batch kernel over the [`ProposedBatch`], returning an [`ExecutedBatch`] that can be + /// passed to [`LocalBatchProver::prove`](crate::LocalBatchProver::prove). + /// + /// # Errors + /// + /// Returns an error if: + /// - the batch kernel program fails to execute; + /// - the kernel output stack fails to parse. + pub fn execute( + &self, + proposed_batch: ProposedBatch, + ) -> Result { + let (stack_inputs, mut advice_inputs) = BatchKernel::prepare_inputs(&proposed_batch); + // Merge any caller-provided advice, overriding matching keys from the derived advice. + advice_inputs.extend(self.advice_inputs.clone()); + + let processor = FastProcessor::new_with_options( + stack_inputs, + advice_inputs, + ExecutionOptions::default(), + ) + .map_err(ExecutionError::advice_error_no_context) + .map_err(ProvenBatchError::BatchKernelExecutionFailed)?; + + // The batch kernel calls `miden::core` procedures (poseidon2, mem, ...), so the core + // library must be available to the host at runtime. + let mut host = DefaultHost::default(); + host.load_library(CoreLibrary::default().mast_forest()) + .expect("loading the core library into the host should succeed"); + + let trace_inputs = processor + .execute_trace_inputs_sync(&BatchKernel::main(), &mut host) + .map_err(ProvenBatchError::BatchKernelExecutionFailed)?; + + // Parse and validate the output stack shape (padding cells are zero and the expiration + // fits in u32). + let batch_outputs = BatchOutputs::parse(trace_inputs.stack_outputs()) + .map_err(ProvenBatchError::BatchKernelOutputInvalid)?; + + // Cross-check the kernel's running-min expiration against the value the proposed batch + // independently derived from its transactions. + let expected_expiration = proposed_batch.batch_expiration_block_num(); + let actual_expiration = batch_outputs.batch_expiration_block_num(); + if actual_expiration != expected_expiration { + return Err(ProvenBatchError::BatchExpirationMismatch { + actual: actual_expiration, + expected: expected_expiration, + }); + } + + Ok(ExecutedBatch::new(proposed_batch, trace_inputs, batch_outputs)) + } +} diff --git a/crates/miden-tx-batch-prover/src/executed_batch.rs b/crates/miden-tx-batch-prover/src/executed_batch.rs new file mode 100644 index 0000000000..7bbf365060 --- /dev/null +++ b/crates/miden-tx-batch-prover/src/executed_batch.rs @@ -0,0 +1,48 @@ +use miden_processor::TraceBuildInputs; +use miden_protocol::batch::{BatchOutputs, ProposedBatch}; + +// EXECUTED BATCH +// ================================================================================================ + +/// A [`ProposedBatch`] whose batch kernel has been executed, but not yet proven. +/// +/// Produced by [`BatchExecutor::execute`](crate::BatchExecutor::execute) and consumed by +/// [`LocalBatchProver::prove`](crate::LocalBatchProver::prove). It carries the executed batch's +/// trace inputs so that proving only needs to build the trace and generate the proof. +pub struct ExecutedBatch { + proposed_batch: ProposedBatch, + trace_inputs: TraceBuildInputs, + batch_outputs: BatchOutputs, +} + +impl ExecutedBatch { + /// Creates a new [`ExecutedBatch`] from the proposed batch, the trace inputs and the public + /// outputs produced by executing the batch kernel over it. + pub(crate) fn new( + proposed_batch: ProposedBatch, + trace_inputs: TraceBuildInputs, + batch_outputs: BatchOutputs, + ) -> Self { + Self { + proposed_batch, + trace_inputs, + batch_outputs, + } + } + + /// Returns the [`ProposedBatch`] this batch was executed from. + pub fn proposed_batch(&self) -> &ProposedBatch { + &self.proposed_batch + } + + /// Returns the public outputs produced by the batch kernel. + pub fn batch_outputs(&self) -> &BatchOutputs { + &self.batch_outputs + } + + /// Consumes the executed batch, returning the proposed batch and the trace inputs needed to + /// prove it. + pub(crate) fn into_parts(self) -> (ProposedBatch, TraceBuildInputs) { + (self.proposed_batch, self.trace_inputs) + } +} diff --git a/crates/miden-tx-batch-prover/src/lib.rs b/crates/miden-tx-batch-prover/src/lib.rs index 368056917b..fc966fcb90 100644 --- a/crates/miden-tx-batch-prover/src/lib.rs +++ b/crates/miden-tx-batch-prover/src/lib.rs @@ -5,5 +5,11 @@ extern crate alloc; #[cfg(feature = "std")] extern crate std; +mod batch_executor; +pub use batch_executor::BatchExecutor; + +mod executed_batch; +pub use executed_batch::ExecutedBatch; + mod local_batch_prover; pub use local_batch_prover::LocalBatchProver; diff --git a/crates/miden-tx-batch-prover/src/local_batch_prover.rs b/crates/miden-tx-batch-prover/src/local_batch_prover.rs index b9811d7ca6..8eec60af3b 100644 --- a/crates/miden-tx-batch-prover/src/local_batch_prover.rs +++ b/crates/miden-tx-batch-prover/src/local_batch_prover.rs @@ -1,25 +1,64 @@ use miden_protocol::batch::{ProposedBatch, ProvenBatch}; use miden_protocol::errors::ProvenBatchError; +use miden_prover::{ExecutionProof, ProvingOptions, TraceProvingInputs, prove_from_trace_sync}; + +use crate::ExecutedBatch; // LOCAL BATCH PROVER // ================================================================================================ -/// A local prover for transaction batches, proving the transactions in a [`ProposedBatch`] and -/// returning a [`ProvenBatch`]. +/// A local prover for transaction batches. +/// +/// Proves an [`ExecutedBatch`] (produced by [`BatchExecutor`](crate::BatchExecutor)) into a +/// [`ProvenBatch`] carrying an [`ExecutionProof`] over the batch's public commitments. #[derive(Clone, Default)] -pub struct LocalBatchProver; +pub struct LocalBatchProver { + proving_options: ProvingOptions, +} impl LocalBatchProver { /// Creates a new [`LocalBatchProver`] instance. pub fn new() -> Self { - Self + Self::default() } - /// Converts the provided [`ProposedBatch`] into a [`ProvenBatch`]. + /// Proves the [`ExecutedBatch`] into a [`ProvenBatch`]. + /// + /// Builds the execution trace from the executed batch and generates the proof, attaching it to + /// the returned [`ProvenBatch`]. The kernel's public outputs are not yet cross-checked against + /// the proposed batch's expected values. /// - /// The batch's transactions are verified when the [`ProposedBatch`] is constructed, so this - /// currently only repackages the batch. Recursive proving is not yet implemented. - pub fn prove(&self, proposed_batch: ProposedBatch) -> Result { + /// # Errors + /// + /// Returns an error if proof generation fails. + pub fn prove(&self, executed_batch: ExecutedBatch) -> Result { + let (proposed_batch, trace_inputs) = executed_batch.into_parts(); + + let (_stack_outputs, proof) = prove_from_trace_sync(TraceProvingInputs::new( + trace_inputs, + self.proving_options.clone(), + )) + .map_err(ProvenBatchError::BatchKernelExecutionFailed)?; + + Self::build_proven_batch(proposed_batch, proof) + } + + /// Returns a [`ProvenBatch`] built from the proposed batch with a dummy [`ExecutionProof`] + /// attached, without running the batch kernel. + #[cfg(any(feature = "testing", test))] + pub fn prove_dummy( + &self, + proposed_batch: ProposedBatch, + ) -> Result { + Self::build_proven_batch(proposed_batch, ExecutionProof::new_dummy()) + } + + /// Combines the parts of a [`ProposedBatch`] with the produced [`ExecutionProof`] into a + /// [`ProvenBatch`]. + fn build_proven_batch( + proposed_batch: ProposedBatch, + proof: ExecutionProof, + ) -> Result { let tx_headers = proposed_batch.transaction_headers(); let ( _transactions, @@ -42,6 +81,7 @@ impl LocalBatchProver { output_notes, batch_expiration_block_num, tx_headers, + proof, ) } }