feat: add per note consumption checker (#1928)

Author: Fumuran

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.11.5 (2025-10-01)
+
+- Add new `can_consume` method to the `NoteConsumptionChecker` ([#1928](https://github.com/0xMiden/miden-base/pull/1928)).
+
 ## 0.11.4 (2025-09-17)
 
 - Updated `miden-vm` dependencies to `0.17.2` patch version. ([#1905](https://github.com/0xMiden/miden-base/pull/1905))

crates/miden-lib/asm/account_components/multisig_rpo_falcon_512.masm

@@ -9,9 +9,6 @@ use.miden::tx
 
 # Auth Request Constants
 
-# The event to request an authentication signature.
-const.AUTH_REQUEST=131087
-
 # The event emitted when a signature is not found for a required signer.
 const.UNAUTHORIZED_EVENT=131102
 

crates/miden-lib/asm/miden/auth/rpo_falcon512.masm

@@ -9,9 +9,6 @@ use.std::crypto::dsa::rpo_falcon512
 # The event to request an authentication signature.
 const.AUTH_REQUEST=131087
 
-# The event emitted when a signature is not found for a required signer.
-const.UNAUTHORIZED_EVENT=131102
-
 # The slot in this component's storage layout where the public key is stored.
 const.PUBLIC_KEY_SLOT=0
 
@@ -74,8 +71,8 @@ end
 
 #! Verify signatures for all required signers in a loop.
 #!
-#! This procedure iterates through the required number of signers, fetches their public keys
-#! from the provided account storage map slot, verifies their signatures against the transaction message,
+#! This procedure iterates through the required number of signers, fetches their public keys from
+#! the provided account storage map slot, verifies their signatures against the transaction message,
 #! and returns the number of successfully verified signatures.
 #!
 #! Inputs:  [pub_key_slot_idx, num_of_approvers, MSG]

crates/miden-testing/src/kernel_tests/tx/test_account_interface.rs

@@ -14,13 +14,15 @@ use miden_objects::testing::account_id::{
     ACCOUNT_ID_REGULAR_PUBLIC_ACCOUNT_UPDATABLE_CODE,
     ACCOUNT_ID_SENDER,
 };
+use miden_objects::transaction::InputNote;
 use miden_processor::ExecutionError;
 use miden_processor::crypto::RpoRandomCoin;
 use miden_tx::auth::UnreachableAuth;
 use miden_tx::{
     FailedNote,
     NoteConsumptionChecker,
     NoteConsumptionInfo,
+    NoteConsumptionStatus,
     TransactionExecutor,
     TransactionExecutorError,
 };
@@ -285,3 +287,46 @@ async fn check_note_consumability_epilogue_failure() -> anyhow::Result<()> {
     );
     Ok(())
 }
+
+#[tokio::test]
+async fn test_check_note_consumability_without_signatures() -> anyhow::Result<()> {
+    let mut builder = MockChain::builder();
+
+    // Use basic auth which will cause epilogue failure when paired up with unreachable auth.
+    let account = builder.add_existing_wallet(Auth::BasicAuth)?;
+
+    let successful_note = builder.add_p2id_note(
+        ACCOUNT_ID_REGULAR_PUBLIC_ACCOUNT_IMMUTABLE_CODE.try_into().unwrap(),
+        account.id(),
+        &[FungibleAsset::mock(10)],
+        NoteType::Public,
+    )?;
+
+    let mock_chain = builder.build()?;
+    let notes = vec![successful_note.clone()];
+    let tx_context = mock_chain
+        .build_tx_context(TxContextInput::Account(account), &[], &notes)?
+        .build()?;
+
+    let account_id = tx_context.account().id();
+    let block_ref = tx_context.tx_inputs().block_header().block_num();
+    let tx_args = tx_context.tx_args().clone();
+
+    // Use an auth that fails in order to force an epilogue failure when paired up with basic auth.
+    let executor =
+        TransactionExecutor::<'_, '_, _, UnreachableAuth>::new(&tx_context).with_tracing();
+    let notes_checker = NoteConsumptionChecker::new(&executor);
+
+    let consumability_info: NoteConsumptionStatus = notes_checker
+        .can_consume(
+            account_id,
+            block_ref,
+            InputNote::Unauthenticated { note: successful_note },
+            tx_args,
+        )
+        .await?;
+
+    assert_eq!(consumability_info, NoteConsumptionStatus::UnconsumableWithoutAuthorization);
+
+    Ok(())
+}

crates/miden-testing/tests/auth/multisig.rs

@@ -1,3 +1,4 @@
+use assert_matches::assert_matches;
 use miden_lib::account::wallets::BasicWallet;
 use miden_lib::errors::tx_kernel_errors::ERR_TX_ALREADY_EXECUTED;
 use miden_objects::account::{
@@ -19,8 +20,13 @@ use miden_objects::transaction::OutputNote;
 use miden_objects::vm::AdviceMap;
 use miden_objects::{Felt, Hasher, Word};
 use miden_testing::{Auth, MockChainBuilder, assert_transaction_executor_error};
-use miden_tx::TransactionExecutorError;
 use miden_tx::auth::{BasicAuthenticator, SigningInputs, TransactionAuthenticator};
+use miden_tx::{
+    NoteConsumptionChecker,
+    NoteConsumptionStatus,
+    TransactionExecutor,
+    TransactionExecutorError,
+};
 use rand::SeedableRng;
 use rand_chacha::ChaCha20Rng;
 
@@ -325,3 +331,102 @@ async fn test_multisig_replay_protection() -> anyhow::Result<()> {
 
     Ok(())
 }
+
+#[tokio::test]
+async fn test_check_note_consumability_multisig() -> anyhow::Result<()> {
+    // Setup keys and authenticators
+    let (_secret_keys, public_keys, authenticators) = setup_keys_and_authenticators(2, 2)?;
+
+    // Create multisig account
+    let multisig_account = create_multisig_account(2, &public_keys, 10)?;
+
+    let mut mock_chain_builder =
+        MockChainBuilder::with_accounts([multisig_account.clone()]).unwrap();
+
+    let p2id_note = mock_chain_builder.add_p2id_note(
+        ACCOUNT_ID_REGULAR_PUBLIC_ACCOUNT_UPDATABLE_CODE.try_into().unwrap(),
+        multisig_account.id(),
+        &[FungibleAsset::mock(1)],
+        NoteType::Public,
+    )?;
+
+    let mock_chain = mock_chain_builder.build().unwrap();
+
+    let salt = Word::from([Felt::new(1); 4]);
+
+    // get the transaction context without signatures
+    let tx_context_without_signatures = mock_chain
+        .build_tx_context(multisig_account.id(), &[p2id_note.id()], &[])?
+        .auth_args(salt)
+        .build()?;
+
+    let block_ref = tx_context_without_signatures.tx_inputs().block_header().block_num();
+    let tx_args = tx_context_without_signatures.tx_args();
+    let tx_executor = TransactionExecutor::<'_, '_, _, BasicAuthenticator<ChaCha20Rng>>::new(
+        &tx_context_without_signatures,
+    );
+
+    let notes_checker = NoteConsumptionChecker::new(&tx_executor);
+
+    // this check should return `UnconsumableWithoutAuthorization` variant: the note is consumable,
+    // but authentication is failing
+    let unconsumable_without_authorization = notes_checker
+        .can_consume(
+            multisig_account.id(),
+            block_ref,
+            miden_objects::transaction::InputNote::Unauthenticated { note: p2id_note.clone() },
+            tx_args.clone(),
+        )
+        .await?;
+    assert_matches!(
+        unconsumable_without_authorization,
+        NoteConsumptionStatus::UnconsumableWithoutAuthorization
+    );
+
+    // execute the transaction to get the summary
+    let tx_summary = match tx_context_without_signatures.execute().await.unwrap_err() {
+        TransactionExecutorError::Unauthorized(tx_effects) => tx_effects,
+        error => panic!("expected abort with tx effects: {error:?}"),
+    };
+
+    // Get signatures from both approvers
+    let msg = tx_summary.as_ref().to_commitment();
+    let tx_summary = SigningInputs::TransactionSummary(tx_summary);
+
+    let sig_1 = authenticators[0].get_signature(public_keys[0].into(), &tx_summary).await?;
+    let sig_2 = authenticators[1].get_signature(public_keys[1].into(), &tx_summary).await?;
+
+    // Populate advice map with signatures
+    let mut advice_map = AdviceMap::default();
+    advice_map.insert(Hasher::merge(&[public_keys[0].into(), msg]), sig_1);
+    advice_map.insert(Hasher::merge(&[public_keys[1].into(), msg]), sig_2);
+
+    // get the transaction context with signatures
+    let tx_context_with_signatures = mock_chain
+        .build_tx_context(multisig_account.id(), &[p2id_note.id()], &[])?
+        .extend_expected_output_notes(vec![OutputNote::Full(p2id_note)])
+        .extend_advice_map(advice_map.iter().map(|(k, v)| (*k, v.to_vec())))
+        .auth_args(salt)
+        .build()?;
+
+    let block_num = tx_context_with_signatures.tx_inputs().block_header().block_num();
+    let notes = tx_context_with_signatures.tx_inputs().input_notes().clone();
+    let tx_args = tx_context_with_signatures.tx_args().clone();
+
+    let mut tx_executor = TransactionExecutor::new(&tx_context_with_signatures)
+        .with_source_manager(tx_context_with_signatures.source_manager());
+    if let Some(authenticator) = tx_context_with_signatures.authenticator() {
+        tx_executor = tx_executor.with_authenticator(authenticator);
+    }
+
+    let notes_checker = NoteConsumptionChecker::new(&tx_executor);
+
+    // this check should return `Consumable` variant: we provided the signatures, so the transaction
+    // should execute successfully.
+    let consumable_with_authorization = notes_checker
+        .can_consume(multisig_account.id(), block_num, notes.get_note(0).clone(), tx_args)
+        .await?;
+    assert_matches!(consumable_with_authorization, NoteConsumptionStatus::Consumable);
+
+    Ok(())
+}

crates/miden-testing/tests/auth/rpo_falcon_acl.rs

@@ -3,7 +3,6 @@ use core::slice;
 use assert_matches::assert_matches;
 use miden_lib::testing::account_component::MockAccountComponent;
 use miden_lib::testing::note::NoteBuilder;
-use miden_lib::transaction::TransactionKernelError;
 use miden_lib::utils::ScriptBuilder;
 use miden_objects::account::{
     AccountBuilder,
@@ -16,7 +15,6 @@ use miden_objects::account::{
 use miden_objects::testing::account_id::ACCOUNT_ID_SENDER;
 use miden_objects::transaction::OutputNote;
 use miden_objects::{Felt, FieldElement, Word};
-use miden_processor::ExecutionError;
 use miden_testing::{Auth, MockChain};
 use miden_tx::TransactionExecutorError;
 
@@ -164,14 +162,7 @@ fn test_rpo_falcon_acl() -> anyhow::Result<()> {
 
     let executed_tx_no_auth = tx_context_no_auth.execute_blocking();
 
-    assert_matches!(executed_tx_no_auth, Err(TransactionExecutorError::TransactionProgramExecutionFailed(
-        execution_error
-    )) => {
-        assert_matches!(execution_error, ExecutionError::EventError { error, .. } => {
-            let kernel_error = error.downcast_ref::<TransactionKernelError>().unwrap();
-            assert_matches!(kernel_error, TransactionKernelError::MissingAuthenticator);
-        })
-    });
+    assert_matches!(executed_tx_no_auth, Err(TransactionExecutorError::MissingAuthenticator));
 
     // Test 4: Transaction WITHOUT authenticator calling non-trigger procedure (should succeed)
     let tx_context_no_trigger = mock_chain
@@ -256,14 +247,7 @@ fn test_rpo_falcon_acl_with_disallow_unauthorized_input_notes() -> anyhow::Resul
 
     // This should fail with MissingAuthenticator error because input notes are being consumed
     // and allow_unauthorized_input_notes is false
-    assert_matches!(executed_tx_no_auth, Err(TransactionExecutorError::TransactionProgramExecutionFailed(
-        execution_error
-    )) => {
-        assert_matches!(execution_error, ExecutionError::EventError { error, .. } => {
-            let kernel_error = error.downcast_ref::<TransactionKernelError>().unwrap();
-            assert_matches!(kernel_error, TransactionKernelError::MissingAuthenticator);
-        })
-    });
+    assert_matches!(executed_tx_no_auth, Err(TransactionExecutorError::MissingAuthenticator));
 
     Ok(())
 }

crates/miden-tx/src/errors/mod.rs

@@ -38,6 +38,42 @@ pub enum NoteCheckerError {
         failed_note_index: usize,
         error: TransactionExecutorError,
     },
+
+    // new variants were created instead of modifying existing ones do decrease the number of
+    // merge conflicts during the next release
+    #[error("transaction preparation failed: {0}")]
+    TransactionPreparation(#[source] TransactionExecutorError),
+    #[error("transaction execution prologue failed: {0}")]
+    PrologueExecution(#[source] TransactionExecutorError),
+}
+
+// TRANSACTION CHECKER ERROR
+// ================================================================================================
+
+#[derive(Debug, Error)]
+pub(crate) enum TransactionCheckerError {
+    #[error("transaction preparation failed: {0}")]
+    TransactionPreparation(#[source] TransactionExecutorError),
+    #[error("transaction execution prologue failed: {0}")]
+    PrologueExecution(#[source] TransactionExecutorError),
+    #[error("transaction execution epilogue failed: {0}")]
+    EpilogueExecution(#[source] TransactionExecutorError),
+    #[error("transaction note execution failed on note index {failed_note_index}: {error}")]
+    NoteExecution {
+        failed_note_index: usize,
+        error: TransactionExecutorError,
+    },
+}
+
+impl From<TransactionCheckerError> for TransactionExecutorError {
+    fn from(error: TransactionCheckerError) -> Self {
+        match error {
+            TransactionCheckerError::TransactionPreparation(error) => error,
+            TransactionCheckerError::PrologueExecution(error) => error,
+            TransactionCheckerError::EpilogueExecution(error) => error,
+            TransactionCheckerError::NoteExecution { error, .. } => error,
+        }
+    }
 }
 
 // TRANSACTION EXECUTOR ERROR
@@ -101,6 +137,10 @@ pub enum TransactionExecutorError {
     // It is boxed to avoid triggering clippy::result_large_err for functions that return this type.
     #[error("transaction is unauthorized with summary {0:?}")]
     Unauthorized(Box<TransactionSummary>),
+    #[error(
+        "failed to respond to signature requested since no authenticator is assigned to the host"
+    )]
+    MissingAuthenticator,
 }
 
 // TRANSACTION PROVER ERROR

crates/miden-tx/src/executor/mod.rs

@@ -35,7 +35,12 @@ mod data_store;
 pub use data_store::DataStore;
 
 mod notes_checker;
-pub use notes_checker::{FailedNote, NoteConsumptionChecker, NoteConsumptionInfo};
+pub use notes_checker::{
+    FailedNote,
+    NoteConsumptionChecker,
+    NoteConsumptionInfo,
+    NoteConsumptionStatus,
+};
 
 // TRANSACTION EXECUTOR
 // ================================================================================================
@@ -457,6 +462,9 @@ fn map_execution_error(exec_err: ExecutionError) -> TransactionExecutorError {
                         tx_fee: *tx_fee,
                     }
                 },
+                Some(TransactionKernelError::MissingAuthenticator) => {
+                    TransactionExecutorError::MissingAuthenticator
+                },
                 _ => TransactionExecutorError::TransactionProgramExecutionFailed(exec_err),
             }
         },