@openzeppelin/miden-multisig-client 0.17.0-rc.2 → 0.17.0

package/src/recovery/recoverNotes.ts

@@ -0,0 +1,288 @@
+/**
+ * Wallet-facing orchestration of the note-recovery primitives.
+ *
+ * After key-based recovery the local Miden store starts empty (or, in a
+ * shared store, its global cursors may already be past this account's
+ * notes). Each recovery primitive rescans one source normal forward sync
+ * would skip: the private-note transport backlog, the notes embedded in
+ * pending consume-notes proposals, and the chain's historical public notes
+ * for the account's tag. `Multisig.recoverNotes` runs them as a single flow
+ * and finishes with a normal sync so recovered notes are verified and ready
+ * to consume.
+ *
+ * The TS counterpart of the Rust SDK's `MultisigClient::recover_notes`,
+ * with matching semantics and report shape.
+ */
+
+import { errorMessage } from '../connectivity.js';
+import { RecoveryCancelledError } from './proposalNoteImport.js';
+import type { NoteImportOutcome } from './proposalNoteImport.js';
+import { BackfillRangeError, type PublicBackfillReport } from './publicNoteBackfill.js';
+import type { TransportRecoveryReport } from './transportDrain.js';
+
+/** One step of the note-recovery flow, used to attribute problems. */
+export type RecoveryStep =
+  | 'transport-drain'
+  | 'proposal-import'
+  | 'public-backfill'
+  | 'sync';
+
+/**
+ * A step of the recovery flow that could not run (or, for the final sync,
+ * did not finish). The flow always continues with the remaining steps; a
+ * problem here means the corresponding report field is absent (or `synced`
+ * is `false`) and rerunning the flow may recover more.
+ */
+export interface RecoveryStepProblem {
+  /** The step that failed. */
+  step: RecoveryStep;
+  /** Human-readable cause. */
+  reason: string;
+  /**
+   * Whether rerunning the flow can plausibly make this step succeed.
+   * Failures reaching this level are I/O failures against GUARDIAN, the
+   * node, or the local store; all but local-store failures are marked
+   * retryable. The flow is idempotent, so retrying is always safe.
+   */
+  retryable: boolean;
+}
+
+/**
+ * Result of `Multisig.recoverNotes`.
+ *
+ * Each strategy's field holds its primitive's own report and is present
+ * exactly when the strategy was enabled and ran; an enabled strategy that
+ * could not run at all is a {@link RecoveryStepProblem} instead. Step
+ * problems never abort the flow.
+ */
+export interface NoteRecoveryReport {
+  /** Report of the transport backlog drain, when that strategy ran. */
+  transport?: TransportRecoveryReport;
+  /**
+   * Per-note outcomes of the proposal-embedded import, when that strategy
+   * ran.
+   */
+  proposalImport?: NoteImportOutcome[];
+  /** Report of the historical public-note backfill, when that strategy ran. */
+  backfill?: PublicBackfillReport;
+  /** Steps that could not run or finish. Empty on a fully clean flow. */
+  problems: RecoveryStepProblem[];
+  /** Whether the final verifying sync completed. */
+  synced: boolean;
+  /**
+   * Total note records newly added to the local store by this flow: the
+   * drain's imports plus every `imported` outcome from the proposal import
+   * and the backfill.
+   */
+  imported: number;
+  /**
+   * Whether rerunning the flow can plausibly recover more: any step
+   * problem, per-note outcome, or strategy report marked retryable.
+   */
+  retryable: boolean;
+}
+
+/**
+ * Options for `Multisig.recoverNotes`. The default runs every strategy over
+ * the full chain history and syncs afterwards.
+ */
+export interface RecoverNotesOptions {
+  /**
+   * Rescan the private-note transport backlog (the standalone
+   * `drainPrivateNoteBacklog`). Default `true`.
+   */
+  transportDrain?: boolean;
+  /**
+   * Import the notes embedded in pending consume-notes proposals
+   * (`Multisig.importNotesFromProposals`). Default `true`.
+   */
+  proposalImport?: boolean;
+  /**
+   * Scan chain history for public notes addressed at the account's tag
+   * (`Multisig.backfillPublicNotesByTag`). Default `true`.
+   */
+  publicBackfill?: boolean;
+  /** First block of the backfill scan; defaults to genesis. */
+  fromBlock?: number;
+  /** Last block of the backfill scan; defaults to the current chain tip. */
+  toBlock?: number;
+  /**
+   * Run a normal sync after the strategies so imported notes are verified
+   * and show up as consumable. Default `true`.
+   */
+  syncAfter?: boolean;
+}
+
+/**
+ * The guardian-switch slice of {@link RecoverNotesOptions}: only the
+ * proposal-embedded note import runs. Internal — the public entry point is
+ * `Multisig.preservePreSwitchProposalNotes`, which adds the switch-specific
+ * safety contract (timeout, cancellation, warnings) around this slice. The
+ * `satisfies` clause forces every non-range option to be listed, so adding
+ * a recovery strategy fails to compile until the switch path decides on it.
+ */
+export const GUARDIAN_SWITCH_RECOVERY_OPTIONS = {
+  transportDrain: false,
+  proposalImport: true,
+  publicBackfill: false,
+  syncAfter: false,
+} satisfies Required<Omit<RecoverNotesOptions, 'fromBlock' | 'toBlock'>>;
+
+/**
+ * The strategy implementations `runNoteRecovery` orchestrates. `Multisig`
+ * wires these to the SDK primitives; tests can substitute stubs.
+ */
+export interface NoteRecoverySteps {
+  /** Drain the private-note transport backlog. */
+  transportDrain: () => Promise<TransportRecoveryReport>;
+  /** Import notes embedded in pending consume-notes proposals. */
+  proposalImport: () => Promise<NoteImportOutcome[]>;
+  /** Backfill historical public notes by tag. */
+  publicBackfill: () => Promise<PublicBackfillReport>;
+  /** Run the final verifying sync. */
+  sync: () => Promise<void>;
+}
+
+function countImported(outcomes: readonly NoteImportOutcome[]): number {
+  return outcomes.filter((o) => o.status === 'imported').length;
+}
+
+/**
+ * Runs the enabled recovery strategies in order — transport drain, proposal
+ * import, public backfill, final sync — folding each strategy-level throw
+ * into a {@link RecoveryStepProblem} so no step failure aborts the flow.
+ *
+ * The optional `cancelled` token makes the run cooperatively cancellable:
+ * the orchestrator checks it before each step, and a
+ * {@link RecoveryCancelledError} from inside a step is recorded as one
+ * non-retryable problem on the interrupted step, after which no further
+ * step runs — cancellation never masquerades as a GUARDIAN or node outage.
+ *
+ * Throws only for an inverted backfill range (a caller error). See
+ * `Multisig.recoverNotes` for the wallet-facing entry point.
+ */
+export async function runNoteRecovery(
+  options: RecoverNotesOptions,
+  steps: NoteRecoverySteps,
+  cancelled?: () => boolean,
+): Promise<NoteRecoveryReport> {
+  if (
+    options.fromBlock !== undefined &&
+    options.toBlock !== undefined &&
+    options.fromBlock > options.toBlock
+  ) {
+    throw new Error(
+      `backfill range is inverted: fromBlock ${options.fromBlock} > toBlock ${options.toBlock}`,
+    );
+  }
+
+  const report: NoteRecoveryReport = {
+    problems: [],
+    synced: false,
+    imported: 0,
+    retryable: false,
+  };
+
+  // Set once a cancellation is observed (token flipped, or a
+  // RecoveryCancelledError surfaced from a step): the remaining steps are
+  // skipped and exactly one problem records the interruption point.
+  let stopped = false;
+  const interrupted = (step: RecoveryStep, err: unknown): boolean => {
+    if (!(err instanceof RecoveryCancelledError)) {
+      return false;
+    }
+    report.problems.push({ step, reason: errorMessage(err), retryable: false });
+    stopped = true;
+    return true;
+  };
+  const startStep = (step: RecoveryStep): boolean => {
+    if (stopped) {
+      return false;
+    }
+    if (cancelled?.()) {
+      report.problems.push({
+        step,
+        reason: 'note recovery stopped before completion by its caller',
+        retryable: false,
+      });
+      stopped = true;
+      return false;
+    }
+    return true;
+  };
+
+  if (options.transportDrain !== false && startStep('transport-drain')) {
+    try {
+      report.transport = await steps.transportDrain();
+    } catch (err) {
+      if (!interrupted('transport-drain', err)) {
+        // The drain's contract: a throw means the local store itself failed,
+        // which a rerun is unlikely to fix.
+        report.problems.push({
+          step: 'transport-drain',
+          reason: errorMessage(err),
+          retryable: false,
+        });
+      }
+    }
+  }
+
+  if (options.proposalImport !== false && startStep('proposal-import')) {
+    try {
+      report.proposalImport = await steps.proposalImport();
+    } catch (err) {
+      if (!interrupted('proposal-import', err)) {
+        report.problems.push({
+          step: 'proposal-import',
+          reason: `failed to list pending proposals: ${errorMessage(err)}`,
+          retryable: true,
+        });
+      }
+    }
+  }
+
+  if (options.publicBackfill !== false && startStep('public-backfill')) {
+    try {
+      report.backfill = await steps.publicBackfill();
+    } catch (err) {
+      if (!interrupted('public-backfill', err)) {
+        // With the fully-explicit range validated above, a throw here is
+        // normally the chain-tip lookup (a node RPC failure, worth retrying);
+        // an invalid range against the resolved tip is a caller error and is
+        // not — mirroring the Rust orchestrator's `InvalidConfig` check.
+        report.problems.push({
+          step: 'public-backfill',
+          reason: errorMessage(err),
+          retryable: !(err instanceof BackfillRangeError),
+        });
+      }
+    }
+  }
+
+  if (options.syncAfter !== false && startStep('sync')) {
+    try {
+      await steps.sync();
+      report.synced = true;
+    } catch (err) {
+      if (!interrupted('sync', err)) {
+        report.problems.push({
+          step: 'sync',
+          reason: `recovery imports succeeded but the verifying sync failed; rerun a sync: ${errorMessage(err)}`,
+          retryable: true,
+        });
+      }
+    }
+  }
+
+  report.imported =
+    (report.transport?.imported ?? 0) +
+    countImported(report.proposalImport ?? []) +
+    countImported(report.backfill?.outcomes ?? []);
+  report.retryable =
+    report.problems.some((p) => p.retryable) ||
+    report.transport?.retryable === true ||
+    (report.proposalImport ?? []).some((o) => o.retryable) ||
+    report.backfill?.retryable === true;
+
+  return report;
+}

package/src/recovery/transportDrain.ts

@@ -0,0 +1,330 @@
+/**
+ * Recovery primitives for restoring note state after device loss.
+ *
+ * After recovery on a fresh device the local store has no note-transport
+ * cursor — and in a shared dirty store another account's sync may have
+ * advanced the cursor past notes belonging to the newly recovered account.
+ * The primitives here rescan sources that normal forward sync would skip.
+ */
+
+import type { MidenClient } from '@miden-sdk/miden-sdk';
+import { errorMessage, isLikelyNetworkError } from '../connectivity.js';
+import { isTransientRpcError } from '../rpc/errors.js';
+
+/**
+ * Outcome class of a private-note transport backlog drain:
+ * - `completed` — the full transport backlog was scanned; every note the
+ *   transport still holds for the tracked tags is now in the local store.
+ * - `unavailable` — the transport could not be consulted at all: it is
+ *   disabled for the injected `MidenClient` (no `noteTransportUrl`
+ *   configured) or unreachable before anything was imported (`imported` is
+ *   always 0 — a connection lost mid-drain after partial progress reports
+ *   `failed` instead). The rest of a recovery flow should proceed without
+ *   transport notes.
+ * - `failed` — the drain started but did not finish; the backlog may be
+ *   partially imported. `retryable` distinguishes transient failures (rerun
+ *   the drain) from permanent ones.
+ */
+export type TransportRecoveryStatus = 'completed' | 'unavailable' | 'failed';
+
+/**
+ * Result of {@link drainPrivateNoteBacklog}.
+ *
+ * Transport problems are reported here rather than thrown so a transport
+ * failure never aborts the rest of a recovery flow.
+ */
+export interface TransportRecoveryReport {
+  /** Outcome class of the drain. */
+  status: TransportRecoveryStatus;
+  /**
+   * Number of note records newly imported into the local store by this
+   * drain. Can be non-zero even on `failed`: batches imported before the
+   * failure stay imported.
+   */
+  imported: number;
+  /**
+   * Whether rerunning the drain can plausibly succeed (transient
+   * connectivity failures, the upstream pagination convergence guard).
+   * Always `false` on `completed`.
+   */
+  retryable: boolean;
+  /** Human-readable cause when the drain did not complete. */
+  reason?: string;
+}
+
+/**
+ * The WASM client surfaces the upstream transport errors as plain messages,
+ * so the message text is the only stable join key (same approach as
+ * `connectivity.ts`). These fragments come from miden-client's
+ * `NoteTransportError` `Display` impls.
+ */
+/** Exported for the drift-guard test, which pins them against the shipped WASM binary. */
+export const TRANSPORT_DISABLED_FRAGMENT = 'note transport is disabled';
+/** Exported for the drift-guard test, which pins them against the shipped WASM binary. */
+export const PAGINATION_GUARD_FRAGMENT = 'did not converge';
+/**
+ * `NoteTransportError::Network`'s Display prefix — the transport service
+ * answered with an error. Exported for the drift-guard test.
+ */
+export const TRANSPORT_NETWORK_FRAGMENT = 'note transport network error';
+/**
+ * `NoteTransportError::Connection`'s Display prefix — endpoint parsing, TLS
+ * configuration, and actual connect failures, indiscriminately. Exported for
+ * the drift-guard test.
+ */
+export const TRANSPORT_CONNECTION_FRAGMENT = 'connection error';
+/**
+ * `RpcError::RequestError`'s Display prefix — a NODE RPC failure (each
+ * fetched batch is imported through the node, so this is a mid-drain import
+ * failure, not a transport outage). Exported for the drift-guard test.
+ */
+export const NODE_RPC_FRAGMENT = 'grpc request failed';
+/**
+ * `RpcError::ConnectionError`'s Display text — the NODE could not be
+ * reached at all, which mid-drain is the same interrupted-import class as
+ * {@link NODE_RPC_FRAGMENT}. Exported for the drift-guard test.
+ */
+export const NODE_CONNECT_FRAGMENT = 'failed to connect to the Miden node';
+/**
+ * The covered-tags bookkeeping key, mirror of miden-client's
+ * `NOTE_TRANSPORT_COVERED_TAGS_KEY` (the JS surface does not re-export it).
+ * Exported for the drift-guard test, which pins it against the shipped WASM
+ * binary so a silent upstream rename cannot degrade the drain to a no-op.
+ */
+export const NOTE_TRANSPORT_COVERED_TAGS_KEY = 'note_transport_covered_tags';
+
+/**
+ * Mirror of miden-client's `Client::MAX_BACKFILL_TAGS_PER_SYNC`: upstream
+ * backfills at most this many uncovered tags per transport sync, deferring
+ * the remainder to the next sync.
+ */
+const MAX_BACKFILL_TAGS_PER_SYNC = 64;
+
+/**
+ * Mirror of the Rust SDK's `CONNECT_PERMANENT_SIGNALS`: connection-failure
+ * wording a retry cannot fix (misconfigured endpoint, TLS/certificate
+ * problems). Everything else connection-shaped is the peer-still-booting
+ * case and stays retryable.
+ */
+const CONNECT_PERMANENT_SIGNALS = ['certificate', 'tls', 'invalid uri', 'unsupported scheme'];
+/**
+ * `ClientError::StoreError`'s Display prefix in the WASM error chain.
+ * Exported for the drift-guard test, which pins it against the shipped WASM
+ * binary.
+ */
+export const STORE_ERROR_FRAGMENT = 'storage error';
+
+/**
+ * IndexedDB/Dexie error names that mean the local store itself failed —
+ * these must reject (matching the Rust `StoreError` branch), never be folded
+ * into a transport report.
+ */
+const STORE_ERROR_NAMES = ['QuotaExceededError', 'DatabaseClosedError', 'ReadOnlyError', 'TransactionInactiveError'];
+
+/**
+ * Does this failure mean the local store is broken (as opposed to a
+ * transport/node problem)? Kept deliberately narrow: `AbortError` counts
+ * only when its message points at an IndexedDB transaction/database abort —
+ * network requests also abort, and those stay transport-classified.
+ */
+function isLocalStoreError(err: unknown): boolean {
+  const message = errorMessage(err);
+  const lower = message.toLowerCase();
+  if (lower.includes(STORE_ERROR_FRAGMENT)) return true;
+  const name =
+    typeof err === 'object' && err !== null && 'name' in err && typeof err.name === 'string'
+      ? err.name
+      : undefined;
+  if (name !== undefined && STORE_ERROR_NAMES.includes(name)) return true;
+  // The WASM bridge may stringify the underlying store error into the
+  // message rather than preserving the name.
+  if (STORE_ERROR_NAMES.some((storeName) => message.includes(storeName))) return true;
+  if (name === 'AbortError' && (lower.includes('transaction') || lower.includes('database'))) {
+    return true;
+  }
+  return false;
+}
+
+interface DrainFailure {
+  status: TransportRecoveryStatus;
+  retryable: boolean;
+  reason: string;
+  /**
+   * `false` when the failure proves nothing was fetched (disabled transport
+   * throws before any scan), so the store does not need re-counting.
+   */
+  scanned: boolean;
+}
+
+function classifyDrainFailure(err: unknown): DrainFailure {
+  const reason = errorMessage(err);
+  const lower = reason.toLowerCase();
+  // No transport configured — retrying cannot help until the MidenClient is
+  // rebuilt with a `noteTransportUrl`. Thrown before anything is fetched.
+  if (lower.includes(TRANSPORT_DISABLED_FRAGMENT)) {
+    return { status: 'unavailable', retryable: false, reason, scanned: false };
+  }
+  // The upstream convergence guard tripped (the server cursor kept advancing
+  // for 1000 iterations without an empty batch) — a server-side bug, not an
+  // honest backlog. Retryable in the sense that a rerun is safe (imports are
+  // idempotent) and succeeds once the server recovers.
+  if (lower.includes(PAGINATION_GUARD_FRAGMENT)) {
+    return { status: 'failed', retryable: true, reason, scanned: true };
+  }
+  // A NODE RPC failure: each fetched batch is imported through the node
+  // (inclusion-proof lookup), so this interrupted the drain mid-way — the
+  // transport itself was reachable. Mirrors the Rust `ClientError::RpcError`
+  // arm: report `failed`, with the shared RPC classifier deciding whether a
+  // rerun can help.
+  if (lower.includes(NODE_RPC_FRAGMENT) || lower.includes(NODE_CONNECT_FRAGMENT.toLowerCase())) {
+    return { status: 'failed', retryable: isTransientRpcError(err), reason, scanned: true };
+  }
+  // The transport answered with an error — worth retrying once the service
+  // recovers.
+  if (lower.includes(TRANSPORT_NETWORK_FRAGMENT)) {
+    return { status: 'unavailable', retryable: true, reason, scanned: true };
+  }
+  // `Connection` wraps endpoint parsing, TLS configuration, and actual
+  // connect failures indiscriminately; permanent wording (mirroring the Rust
+  // SDK's cause-chain classifier) must not tell a recovery flow to loop
+  // retrying a client that can never connect.
+  if (lower.includes(TRANSPORT_CONNECTION_FRAGMENT)) {
+    const permanent = CONNECT_PERMANENT_SIGNALS.some((signal) => lower.includes(signal));
+    return { status: 'unavailable', retryable: !permanent, reason, scanned: true };
+  }
+  // Remaining connectivity-shaped wording (e.g. a raw fetch failure): the
+  // transport could not be reached; worth retrying once connectivity
+  // returns.
+  if (isLikelyNetworkError(err)) {
+    return { status: 'unavailable', retryable: true, reason, scanned: true };
+  }
+  return { status: 'failed', retryable: false, reason, scanned: true };
+}
+
+/**
+ * Restores the covered-tags value after a failed drain: returning it to its
+ * pre-drain state keeps a client that synced fine before the attempt
+ * syncing fine after it. Unlike the Rust twin — which merges the snapshot
+ * with whatever the interrupted backfill re-covered — this restores the
+ * snapshot verbatim (the WASM surface exposes the set only as an opaque
+ * value); at worst the next successful drain re-covers tags the failed
+ * attempt already handled, which is idempotent. A failed restoring write
+ * throws: the store is left with its bookkeeping cleared and subsequent
+ * normal syncs may re-drain (and re-fail on) old history — a local-store
+ * environment failure the caller must not fold into a transport report.
+ */
+async function restoreCoveredTags(
+  midenClient: MidenClient,
+  snapshot: unknown,
+  drainReason: string,
+): Promise<void> {
+  if (snapshot === null || snapshot === undefined) return;
+  try {
+    await midenClient.settings.set(NOTE_TRANSPORT_COVERED_TAGS_KEY, snapshot);
+  } catch (restoreError) {
+    throw new Error(
+      `the transport drain failed (${drainReason}) and restoring the covered-tags bookkeeping also failed (${errorMessage(restoreError)}); subsequent syncs may re-drain old transport history`,
+    );
+  }
+}
+
+/**
+ * Rescans the full private-note transport backlog for every tracked note tag
+ * and imports what it finds, regardless of the stored transport
+ * cursor. Counterpart of `MultisigClient::drain_private_note_backlog`
+ * in the Rust SDK; the WASM boundary exposes only error message text, so
+ * failure classification here is message-based, keyed on the upstream
+ * Display prefixes pinned by the drift-guard test.
+ *
+ * Use after account recovery, passing the **same** `MidenClient` instance
+ * that was injected into `MultisigClient`: a fresh store has no transport
+ * cursor, and in a shared store another account's sync may have advanced the
+ * cursor past this account's notes. The drain is idempotent, tag-scoped (the
+ * recovered account must already be in the store so its note tag is tracked
+ * — `MultisigClient.load` does this), and never regresses an
+ * already-advanced cursor.
+ *
+ * Transport recovery is bounded by the transport service's retention:
+ * senders may bypass the transport entirely and relayed blobs are pruned
+ * after the retention window, so this is a best-effort rescan, **not** a
+ * backup. Transport-disabled and transport-unreachable outcomes are reported
+ * in the {@link TransportRecoveryReport} rather than thrown; this function
+ * only throws when the local store itself fails.
+ *
+ * The rescan runs as many transport syncs as the upstream per-sync tag
+ * backfill cap requires to cover every tracked tag, and a failed drain
+ * restores the pre-drain covered-tags bookkeeping so normal sync keeps
+ * working exactly as it did before the attempt.
+ */
+export async function drainPrivateNoteBacklog(
+  midenClient: MidenClient,
+): Promise<TransportRecoveryReport> {
+  const before = (await midenClient.notes.list()).length;
+  // Records are never removed by a drain, so the length delta is the count
+  // of newly imported records. Caveat: it is a store delta — notes imported
+  // by concurrent activity on the same store (a background sync, another
+  // tab) during the drain are attributed to it.
+  const importedSince = async (): Promise<number> =>
+    Math.max((await midenClient.notes.list()).length - before, 0);
+
+  // Snapshot the covered-tags value before clearing it: the clear is
+  // durable, and upstream re-marks a tag covered only after its backfill
+  // succeeds — so without a restore, a drain that fails on a tag with a
+  // permanently bad relay blob would leave every tag uncovered and make
+  // every subsequent normal sync re-attempt (and fail) the same backfill.
+  // Store errors here propagate like the count above.
+  const coveredSnapshot = await midenClient.settings.get(NOTE_TRANSPORT_COVERED_TAGS_KEY);
+  let cleared = false;
+
+  try {
+    // The incremental fetch doubles as the transport probe: miden-sdk 0.16's
+    // syncNoteTransport silently no-ops when the transport is disabled, but
+    // this drain must report `unavailable`, and fetchPrivate still throws
+    // the upstream disabled error.
+    await midenClient.notes.fetchPrivate();
+    // miden-sdk 0.16 replaced the explicit full drain with covered-tag
+    // bookkeeping inside syncNoteTransport: every tag not yet marked covered
+    // is drained from the start with a local cursor (the global cursor is
+    // never regressed), then the steady-state fetch runs. Clearing the
+    // covered-tags marker first forces that full per-tag re-drain — exactly
+    // the recovery semantic this primitive promises. Imports dedupe, so
+    // re-draining already-seen history is harmless.
+    await midenClient.settings.remove(NOTE_TRANSPORT_COVERED_TAGS_KEY);
+    cleared = true;
+    // Upstream backfills at most `MAX_BACKFILL_TAGS_PER_SYNC` uncovered tags
+    // per sync, so run enough passes to cover every tracked tag before
+    // reporting the backlog fully scanned.
+    const tagCount = (await midenClient.tags.list()).length;
+    const passes = Math.max(1, Math.ceil(tagCount / MAX_BACKFILL_TAGS_PER_SYNC));
+    for (let pass = 0; pass < passes; pass += 1) {
+      await midenClient.syncNoteTransport();
+    }
+  } catch (err) {
+    // A broken local store is an environment failure, not a transport
+    // outcome: the whole recovery flow needs to know, so it propagates
+    // (matching the Rust `StoreError` branch) instead of being folded into
+    // the report.
+    if (isLocalStoreError(err)) {
+      throw err;
+    }
+    const { status, retryable, reason, scanned } = classifyDrainFailure(err);
+    if (cleared) {
+      await restoreCoveredTags(midenClient, coveredSnapshot, reason);
+    }
+    // Count even when the drain failed: each fetched batch is imported as it
+    // arrives, so notes recovered before the failure stay in the store. A
+    // disabled transport throws before fetching anything, so skip the
+    // re-count entirely.
+    const imported = scanned ? await importedSince() : 0;
+    if (status === 'unavailable' && imported > 0) {
+      // `unavailable` promises "nothing was imported"; a connection lost
+      // mid-drain after partial progress is an interrupted drain, so report
+      // it as a failure — keeping the classified retryability, like the
+      // Rust twin.
+      return { status: 'failed', imported, retryable, reason };
+    }
+    return { status, imported, retryable, reason };
+  }
+
+  return { status: 'completed', imported: await importedSince(), retryable: false };
+}

package/src/transaction/consumeNotes.ts

@@ -39,7 +39,10 @@ export function buildConsumeNotesTransactionRequestFromNotes(
 
   let txBuilder = new TransactionRequestBuilder();
   txBuilder = txBuilder.withInputNotes(noteAndArgsArray);
-  txBuilder = txBuilder.withAuthArg(authSaltForBuilder);
+  txBuilder = txBuilder.withFeeConversionSalt(authSaltForBuilder);
+  // Borrows rather than consumes: the glue passes `__wbg_ptr` without taking it,
+  // so the handle stays ours to release once the builder has read it.
+  authSaltForBuilder.free?.();
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);

package/src/transaction/p2id.ts

@@ -166,7 +166,10 @@ export function buildP2idTransactionRequest(
 
   let txBuilder = new TransactionRequestBuilder();
   txBuilder = txBuilder.withOwnOutputNotes(outputNotes);
-  txBuilder = txBuilder.withAuthArg(authSaltForBuilder);
+  txBuilder = txBuilder.withFeeConversionSalt(authSaltForBuilder);
+  // Borrows rather than consumes: the glue passes `__wbg_ptr` without taking it,
+  // so the handle stays ours to release once the builder has read it.
+  authSaltForBuilder.free?.();
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);

package/src/transaction/summary.ts

@@ -9,11 +9,11 @@ import { getRawMidenClient } from '../raw-client.js';
 import { base64ToUint8Array, uint8ArrayToBase64 } from '../utils/encoding.js';
 
 /**
- * Index of the first user param carrying the auth-arg salt. The guarded-multisig
+ * Index of the first user param carrying the auth args. The guarded-multisig
  * auth component zeroes user params 0-2 and fills 3-6 with the auth args, matching
  * `push.0.0.0` ahead of `multisig::auth_tx` in `guarded_multisig.masm`.
  */
-const SALT_USER_PARAM_OFFSET = 3;
+const AUTH_ARG_USER_PARAM_OFFSET = 3;
 
 /**
  * Captures a `ChainAnchor` for the request at the current sync height and
@@ -98,13 +98,19 @@ export function chainAnchorFromBase64(anchorBase64: string): ChainAnchor {
 }
 
 /**
- * Reads the auth-arg salt back out of a transaction summary.
+ * Reads the auth args back out of a transaction summary.
  *
  * Since miden-protocol 0.16-rc the summary binds seven user-defined elements
  * instead of a dedicated salt word. The guarded-multisig auth component zeroes
- * the leading three and passes the auth args as the trailing four, so the salt
- * is the tail of `userParams()`.
+ * the leading three and passes the auth args as the trailing four, so the auth
+ * args are the tail of `userParams()`.
+ *
+ * This is the auth-arg word, *not* the proposal salt. When the request declares
+ * a fee conversion salt, miden-client uses it to commit the native conversion
+ * info under `hash(CONVERSION_INFO || SALT)`. That commitment is not invertible
+ * to the salt. Keep the salt alongside the proposal — `ProposalMetadata.saltHex`
+ * — rather than trying to recover it from the summary.
  */
-export function summarySalt(summary: TransactionSummary): Word {
-  return Word.newFromFelts(summary.userParams().slice(SALT_USER_PARAM_OFFSET));
+export function summaryAuthArg(summary: TransactionSummary): Word {
+  return Word.newFromFelts(summary.userParams().slice(AUTH_ARG_USER_PARAM_OFFSET));
 }