feat(client): distinct ApplyTransactionAfterSubmitFailed error + one retry

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Features
 
+* [FEATURE] Distinct `ApplyTransactionAfterSubmitFailed` error variant with one apply retry, so callers know a submitted tx landed on-chain and should not be re-submitted ([#2059](https://github.com/0xMiden/miden-client/pull/2059)).
 * [FEATURE][web] Added `"custom"` operation to `preview()` so users can dry-run any pre-built `TransactionRequest`, not just send/mint/consume/swap ([#2052](https://github.com/0xMiden/miden-client/pull/2052)).
 
 ## 0.14.3 (2026-04-16)

crates/rust-client/src/errors.rs

@@ -1,9 +1,11 @@
+use alloc::boxed::Box;
 use alloc::string::{String, ToString};
 use alloc::vec::Vec;
 use core::fmt;
 
 use miden_protocol::Word;
 use miden_protocol::account::AccountId;
+use miden_protocol::block::BlockNumber;
 use miden_protocol::crypto::merkle::MerkleError;
 pub use miden_protocol::errors::{AccountError, AccountIdError, AssetError, NetworkIdError};
 use miden_protocol::errors::{
@@ -13,6 +15,7 @@ use miden_protocol::errors::{
     TransactionScriptError,
 };
 use miden_protocol::note::{NoteId, NoteTag};
+use miden_protocol::transaction::TransactionId;
 use miden_standards::account::interface::AccountInterfaceError;
 // RE-EXPORTS
 // ================================================================================================
@@ -165,6 +168,18 @@ pub enum ClientError {
         #[source]
         source: RpcError,
     },
+    #[error(
+        "transaction {tx_id} was submitted to the network at block {submission_height} but \
+         apply_transaction failed when writing local state. The on-chain effect is durable; the \
+         next successful sync will reconcile note states via ConsumedExternal. Do NOT retry the \
+         same transaction."
+    )]
+    ApplyTransactionAfterSubmitFailed {
+        tx_id: TransactionId,
+        submission_height: BlockNumber,
+        #[source]
+        source: Box<ClientError>,
+    },
 }
 
 // CONVERSIONS
@@ -228,6 +243,19 @@ impl From<&ClientError> for Option<ErrorHint> {
                           or provide the seed when importing.".to_string(),
                 docs_url: Some(TROUBLESHOOTING_DOC),
             }),
+            ClientError::ApplyTransactionAfterSubmitFailed { tx_id, submission_height, .. } => {
+                Some(ErrorHint {
+                    message: format!(
+                        "Transaction {tx_id} was submitted to the network at block \
+                         {submission_height} but the local apply step (which writes the new \
+                         note states and account commitment to the store) failed. The on-chain \
+                         effect is permanent — do NOT resubmit. Run `sync` to reconcile local \
+                         state; input notes consumed by this transaction will be detected via \
+                         their nullifiers and transitioned to ConsumedExternal automatically."
+                    ),
+                    docs_url: Some(TROUBLESHOOTING_DOC),
+                })
+            },
             _ => None,
         }
     }

crates/rust-client/src/transaction/mod.rs

@@ -226,7 +226,34 @@ where
         let submission_height =
             self.submit_proven_transaction(proven_transaction, &tx_result).await?;
 
-        self.apply_transaction(&tx_result, submission_height).await?;
+        // From this point on, the transaction is live on the network: the
+        // sender's account state has changed and the input note
+        // nullifiers will be recorded in the nullifier SMT. If
+        // apply_transaction fails (e.g. transient IDB write error), the
+        // local state disagrees with chain until the next sync
+        // reconciles it.
+        //
+        // Try apply once more before surfacing a distinct error that
+        // tells the caller "the tx landed on chain, don't retry it."
+        // A small subset of apply failures (IDB quota spike, connection
+        // reset on the store worker) clear immediately.
+        if let Err(first_err) = self.apply_transaction(&tx_result, submission_height).await {
+            info!("apply_transaction failed once; retrying to cover transient errors");
+            if let Err(second_err) =
+                self.apply_transaction(&tx_result, submission_height).await
+            {
+                info!(
+                    "apply_transaction failed twice for submitted tx {tx_id}; surfacing \
+                     ApplyTransactionAfterSubmitFailed so the caller can rely on the next \
+                     sync to reconcile local state. First error: {first_err}"
+                );
+                return Err(ClientError::ApplyTransactionAfterSubmitFailed {
+                    tx_id,
+                    submission_height,
+                    source: Box::new(second_err),
+                });
+            }
+        }
 
         Ok(tx_id)
     }