feat(client): distinct ApplyTransactionAfterSubmitFailed error + one retry

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Features
 
+* [FEATURE] Distinct `ApplyTransactionAfterSubmitFailed` error variant for the case where `submit_proven_transaction` succeeds but the local store update fails after a single retry. The error carries the pending `TransactionStoreUpdate` so callers can persist it and re-apply later via `apply_transaction_update` without resubmitting (which the node would reject, since the tx's nullifiers are already consumed by the mempool-accepted copy) ([#2059](https://github.com/0xMiden/miden-client/pull/2059)).
 * [FEATURE][web] Serialize all async `WebClient` JS methods — both the explicit wrappers and every async call that falls through `createClientProxy` to the underlying WASM client (e.g. `getAccount`, `importAccountById`, `getAccountStorage`) — via an internal `_serializeWasmCall` chain. Prevents `"recursive use of an object detected"` panics when an unwrapped read/write races the auto-sync timer or any explicitly-wrapped method. Expose `waitForIdle()` on `MidenClient` so callers can drain in-flight work before mutating non-WASM state ([#2057](https://github.com/0xMiden/miden-client/pull/2057)).
 * [FEATURE][web] Split `@miden-sdk/miden-sdk` into eager and lazy entry points. The default entry (`import from "@miden-sdk/miden-sdk"`) now awaits WASM at module top level via a small shim (`js/eager.js`) — consumers don't need `await MidenClient.ready()` / `isReady` before constructing wasm-bindgen types. The lazy entry (`import from "@miden-sdk/miden-sdk/lazy"`) preserves the previous behavior and is required for Capacitor WKWebView hosts (the custom-scheme handler hangs on TLA) and Next.js SSR. Verified empirically against the Miden Wallet's iOS E2E suite on devnet. `@miden-sdk/react` imports from `/lazy` internally and manages readiness via `isReady`.
 * [FEATURE][web] Expose `lastAuthError()` on `MidenClient` for typed sign-callback failure recovery — preserves the raw thrown value from the JS signCallback so consumers can distinguish locked/rejected/IO-error failure modes ([#2058](https://github.com/0xMiden/miden-client/pull/2058)).

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,19 @@ pub enum ClientError {
         #[source]
         source: RpcError,
     },
+    #[error(
+        "transaction {tx_id} was accepted by the node at block {submission_height} but the local \
+         store update failed after a retry. The pending store update is attached and can be \
+         re-applied later via `apply_transaction_update`; resubmitting the same transaction will \
+         be rejected because the nullifiers are already consumed by the mempool-accepted copy."
+    )]
+    ApplyTransactionAfterSubmitFailed {
+        tx_id: TransactionId,
+        submission_height: BlockNumber,
+        pending_update: Box<crate::transaction::TransactionStoreUpdate>,
+        #[source]
+        source: Box<ClientError>,
+    },
 }
 
 // CONVERSIONS
@@ -228,6 +244,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 accepted by the node at block \
+                         {submission_height} but the local store update failed (twice). The \
+                         pending update is attached to this error as `pending_update`; you can \
+                         re-apply it later via `Client::apply_transaction_update`. Do NOT \
+                         resubmit the same transaction: its nullifiers are already consumed by \
+                         the mempool-accepted copy, so the node will reject the retry."
+                    ),
+                    docs_url: Some(TROUBLESHOOTING_DOC),
+                })
+            },
             _ => None,
         }
     }

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

@@ -226,7 +226,32 @@ where
         let submission_height =
             self.submit_proven_transaction(proven_transaction, &tx_result).await?;
 
-        self.apply_transaction(&tx_result, submission_height).await?;
+        // The transaction has been accepted by the node; the local store update
+        // is a separate step that can fail independently. Build the update once
+        // and retry the write once before surfacing a distinct error that
+        // carries the pending update for caller-driven recovery.
+        //
+        // The update is boxed so it does not inflate the enclosing future
+        // across await points (triggers clippy::large_futures).
+        let tx_update =
+            Box::new(self.get_transaction_store_update(&tx_result, submission_height).await?);
+
+        if let Err(first_err) = self.apply_transaction_update((*tx_update).clone()).await {
+            info!("apply_transaction_update failed once; retrying to cover transient errors");
+            if let Err(second_err) = self.apply_transaction_update((*tx_update).clone()).await {
+                info!(
+                    "apply_transaction_update failed twice for submitted tx {tx_id}; \
+                     returning ApplyTransactionAfterSubmitFailed with the pending update \
+                     attached. First error: {first_err}"
+                );
+                return Err(ClientError::ApplyTransactionAfterSubmitFailed {
+                    tx_id,
+                    submission_height,
+                    pending_update: tx_update,
+                    source: Box::new(second_err),
+                });
+            }
+        }
 
         Ok(tx_id)
     }