feat(batch kernel): wire up INPUT_NOTES_COMMITMENT & note erasure

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### 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 verifies the transaction list against `BATCH_ID` and computes the nullifier-sorted `INPUT_NOTES_COMMITMENT` matching `ProposedBatch::input_notes().commitment()` ([#2905](https://github.com/0xMiden/protocol/pull/2905)).
 
 - [BREAKING] Renamed `AccountStorageDelta` to `AccountStoragePatch` ([#3002](https://github.com/0xMiden/protocol/pull/3002)).
 - [BREAKING] Replaced the per-tree account and nullifier backend traits with shared `SmtBackend` and `SmtBackendReader` traits, split into read-only and read-write capabilities, enabling read-only `LargeSmt`-backed tree views via `reader()` ([#2755](https://github.com/0xMiden/protocol/pull/2755), [#3009](https://github.com/0xMiden/protocol/pull/3009)).

crates/miden-protocol/asm/kernels/batch/lib/memory.masm

@@ -0,0 +1,391 @@
+# MEMORY LAYOUT
+# =================================================================================================
+#
+# Below is the memory layout used by the batch kernel:
+#
+# +-------------------+-------------------------+----------------------------------+
+# | Address range     | Constant                | Contents                         |
+# +-------------------+-------------------------+----------------------------------+
+# | 0                 | NUM_TRANSACTIONS_PTR    | num_transactions (1 felt).       |
+# | 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.         |
+# | 18                | NUM_INPUT_NOTES_PTR     | number of entries in the global  |
+# |                   |                         | input-note list.                 |
+# | 19                | NUM_OUTPUT_NOTES_PTR    | number of entries in the global  |
+# |                   |                         | output-note list.                |
+# | 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).      |
+# | 40980..49172      | INPUT_NOTES_PTR         | Global input-note list, sorted   |
+# |                   |                         | by nullifier: `[NULLIFIER[4],    |
+# |                   |                         | NOTE_ID_OR_EMPTY[4]]` per note   |
+# |                   |                         | (8 felts each, up to 1024).      |
+# | 49172..53268      | INPUT_NOTE_FLAGS_PTR    | Parallel input-note flags:       |
+# |                   |                         | `[erasure, consumption, 0, 0]`   |
+# |                   |                         | per note (4 felts each).         |
+# | 53268..61460      | OUTPUT_NOTES_PTR        | Global output-note list, sorted  |
+# |                   |                         | by note_id: `[NOTE_ID[4], 0,0,   |
+# |                   |                         | 0,0]` per note (8 felts each).   |
+# | 61460..65556      | OUTPUT_NOTE_FLAGS_PTR   | Parallel output-note flags:      |
+# |                   |                         | `[will_be_erased, is_created,    |
+# |                   |                         | linked_input_index, 0]` per note |
+# |                   |                         | (4 felts each).                  |
+# +-------------------+-------------------------+----------------------------------+
+
+# BOOK KEEPING
+# =================================================================================================
+
+#! Single-felt slot holding `num_transactions` after Layer 1 verification.
+const NUM_TRANSACTIONS_PTR=0
+
+# 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
+
+#! Single-felt slot holding the number of entries in the global input-note list.
+const NUM_INPUT_NOTES_PTR=18
+
+#! Single-felt slot holding the number of entries in the global output-note list.
+const NUM_OUTPUT_NOTES_PTR=19
+
+# 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
+
+# GLOBAL NOTE LISTS
+# =================================================================================================
+
+#! Base of the global input-note list, sorted by nullifier. Per note, an 8-felt sorted-array entry
+#!   `[NULLIFIER[4], NOTE_ID_OR_EMPTY[4]]`
+#! where the KEY word is the nullifier (the `sorted_array` lookup key) and the VALUE word is the
+#! note id (for unauthenticated notes) or the empty word. The VALUE word doubles as the second half
+#! of the `(nullifier, note_id_or_empty)` tuple hashed into INPUT_NOTES_COMMITMENT.
+pub const INPUT_NOTES_PTR=40980
+
+#! Number of felts each note occupies in INPUT_NOTES_PTR / OUTPUT_NOTES_PTR (KEY word + VALUE word).
+pub const NOTE_ENTRY_FELT_LEN=8
+
+#! Base of the parallel input-note flags array. Per note, one word `[erasure, consumption, 0, 0]`.
+#! `erasure` is 0 (not erased / external), 1 (expected to be erased, creator not yet seen) or 2
+#! (erased, creator seen). `consumption` is 0 or 1.
+pub const INPUT_NOTE_FLAGS_PTR=49172
+
+#! Number of felts each note occupies in the flag arrays (one word).
+pub const NOTE_FLAGS_FELT_LEN=4
+
+#! Felt offset of the `erasure` flag within an input-note flag word.
+pub const INPUT_NOTE_ERASURE_OFFSET=0
+
+#! Felt offset of the `consumption` flag within an input-note flag word.
+pub const INPUT_NOTE_CONSUMPTION_OFFSET=1
+
+#! Base of the global output-note list, sorted by note id. Per note, an 8-felt sorted-array entry
+#!   `[NOTE_ID[4], 0, 0, 0, 0]`
+#! where the KEY word is the note id (the `sorted_array` lookup key); the VALUE word is unused.
+pub const OUTPUT_NOTES_PTR=53268
+
+#! Base of the parallel output-note flags array. Per note, one word
+#!   `[will_be_erased, is_created, linked_input_index, 0]`.
+pub const OUTPUT_NOTE_FLAGS_PTR=61460
+
+#! Felt offset of the `will_be_erased` flag within an output-note flag word.
+pub const OUTPUT_NOTE_WILL_BE_ERASED_OFFSET=0
+
+#! Felt offset of the `is_created` flag within an output-note flag word.
+pub const OUTPUT_NOTE_IS_CREATED_OFFSET=1
+
+#! Felt offset of the `linked_input_index` field within an output-note flag word.
+pub const OUTPUT_NOTE_LINKED_INPUT_OFFSET=2
+
+# CAPACITY LIMITS
+# =================================================================================================
+
+#! Maximum number of transactions in a batch. The Layer 1/2 piped-data regions are sized to hold
+#! exactly this many transactions.
+pub const MAX_TRANSACTIONS_PER_BATCH=1024
+
+#! Maximum number of entries in a global note list and in a single transaction's note set. The
+#! input/output note regions and the per-transaction scratch region each hold exactly this many
+#! entries. Equals `MAX_INPUT_NOTES_PER_BATCH` = `MAX_OUTPUT_NOTES_PER_BATCH` in `src/constants.rs`.
+pub const MAX_NOTES_PER_BATCH=1024
+
+# 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 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
+
+# GLOBAL NOTE LIST ACCESSORS
+# =================================================================================================
+
+#! Stores the number of entries in the global input-note list.
+#!
+#! Inputs:  [num_input_notes]
+#! Outputs: []
+pub proc set_num_input_notes
+    mem_store.NUM_INPUT_NOTES_PTR
+end
+
+#! Returns the number of entries in the global input-note list.
+#!
+#! Inputs:  []
+#! Outputs: [num_input_notes]
+pub proc get_num_input_notes
+    mem_load.NUM_INPUT_NOTES_PTR
+end
+
+#! Stores the number of entries in the global output-note list.
+#!
+#! Inputs:  [num_output_notes]
+#! Outputs: []
+pub proc set_num_output_notes
+    mem_store.NUM_OUTPUT_NOTES_PTR
+end
+
+#! Returns the number of entries in the global output-note list.
+#!
+#! Inputs:  []
+#! Outputs: [num_output_notes]
+pub proc get_num_output_notes
+    mem_load.NUM_OUTPUT_NOTES_PTR
+end
+
+#! Returns the end pointer of the global input-note list (base + num_input_notes * 8), as required
+#! by `sorted_array::find_key_value`.
+#!
+#! Inputs:  []
+#! Outputs: [input_notes_end_ptr]
+pub proc get_input_notes_end_ptr
+    exec.get_num_input_notes mul.NOTE_ENTRY_FELT_LEN add.INPUT_NOTES_PTR
+end
+
+#! Returns the end pointer of the global output-note list (base + num_output_notes * 8).
+#!
+#! Inputs:  []
+#! Outputs: [output_notes_end_ptr]
+pub proc get_output_notes_end_ptr
+    exec.get_num_output_notes mul.NOTE_ENTRY_FELT_LEN add.OUTPUT_NOTES_PTR
+end
+
+#! Returns a pointer to input-note entry `i` in INPUT_NOTES_PTR.
+#!
+#! Inputs:  [i]
+#! Outputs: [input_note_entry_ptr]
+pub proc input_note_entry_ptr
+    mul.NOTE_ENTRY_FELT_LEN add.INPUT_NOTES_PTR
+end
+
+#! Returns a pointer to output-note entry `i` in OUTPUT_NOTES_PTR.
+#!
+#! Inputs:  [i]
+#! Outputs: [output_note_entry_ptr]
+pub proc output_note_entry_ptr
+    mul.NOTE_ENTRY_FELT_LEN add.OUTPUT_NOTES_PTR
+end
+
+#! Returns a pointer to input-note flag word `i` in INPUT_NOTE_FLAGS_PTR.
+#!
+#! Inputs:  [i]
+#! Outputs: [input_note_flags_ptr]
+pub proc input_note_flags_ptr
+    mul.NOTE_FLAGS_FELT_LEN add.INPUT_NOTE_FLAGS_PTR
+end
+
+#! Returns a pointer to output-note flag word `i` in OUTPUT_NOTE_FLAGS_PTR.
+#!
+#! Inputs:  [i]
+#! Outputs: [output_note_flags_ptr]
+pub proc output_note_flags_ptr
+    mul.NOTE_FLAGS_FELT_LEN add.OUTPUT_NOTE_FLAGS_PTR
+end
+
+#! Converts an input-note `key_ptr` (as returned by `sorted_array::find_key_value`) into its entry
+#! index `(key_ptr - INPUT_NOTES_PTR) / 8`.
+#!
+#! Inputs:  [key_ptr]
+#! Outputs: [i]
+pub proc input_entry_index_from_key_ptr
+    sub.INPUT_NOTES_PTR div.NOTE_ENTRY_FELT_LEN
+end
+
+#! Converts an output-note `key_ptr` into its entry index `(key_ptr - OUTPUT_NOTES_PTR) / 8`.
+#!
+#! Inputs:  [key_ptr]
+#! Outputs: [i]
+pub proc output_entry_index_from_key_ptr
+    sub.OUTPUT_NOTES_PTR div.NOTE_ENTRY_FELT_LEN
+end