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

package/src/multisig.ts

@@ -16,6 +16,7 @@ import type {
   ProposalSignatureEntry,
   ProposalType,
 } from './types.js';
+import { ProposalSaltMalformedError } from './multisig/authArgErrors.js';
 import type { ProcedureName } from './procedures.js';
 import type {
   MidenClient,
@@ -43,7 +44,6 @@ import {
   chainAnchorToBase64,
   executeForSummary,
   executeForSummaryAt,
-  summarySalt,
   buildUpdateSignersTransactionRequest,
   buildUpdateProcedureThresholdTransactionRequest,
   buildUpdateGuardianTransactionRequest,
@@ -85,6 +85,23 @@ import { AccountInspector, assertCompleteDetectedConfig } from './inspector.js';
 import { ProposalFactory } from './proposal/factory.js';
 import { ProposalMetadataCodec } from './proposal/metadata.js';
 import { ProposalSignatures } from './proposal/signatures.js';
+import {
+  importNotesFromProposals as importNotesFromProposalsStandalone,
+  throwIfCancelled,
+  type NoteImportOutcome,
+} from './recovery/proposalNoteImport.js';
+import {
+  backfillPublicNotesByTag as backfillPublicNotesByTagStandalone,
+  type PublicBackfillReport,
+} from './recovery/publicNoteBackfill.js';
+import { drainPrivateNoteBacklog } from './recovery/transportDrain.js';
+import {
+  GUARDIAN_SWITCH_RECOVERY_OPTIONS,
+  runNoteRecovery,
+  type NoteRecoveryReport,
+  type NoteRecoverySteps,
+  type RecoverNotesOptions,
+} from './recovery/recoverNotes.js';
 import {
   getRawMidenClient,
   getTransactionProver,
@@ -194,6 +211,26 @@ function resolveProposalNonce(
   return options.nonce ?? Date.now();
 }
 
+/**
+ * Deadline for `Multisig.preservePreSwitchProposalNotes`: no client in the
+ * stack applies request deadlines, and a half-dead old GUARDIAN must not
+ * stall the switch. Mirror of the Rust SDK's `PRE_SWITCH_IMPORT_TIMEOUT`.
+ */
+const PRE_SWITCH_IMPORT_TIMEOUT_MS = 30_000;
+
+/** Race sentinel for the pre-switch import timeout. */
+const PRE_SWITCH_IMPORT_TIMED_OUT = Symbol('pre-switch proposal-note import timed out');
+
+/**
+ * How long the switch waits after the timeout for the cancelled flow's one
+ * uninterruptible in-flight operation to settle, so it cannot overlap the
+ * switch transaction on the shared client.
+ */
+const PRE_SWITCH_SETTLE_GRACE_MS = 5_000;
+
+/** A `Word` is four field elements: 64 hex digits. Anything longer is not a salt. */
+const MAX_SALT_HEX_DIGITS = 64;
+
 export class Multisig {
   account: Account;
   threshold: number;
@@ -412,6 +449,11 @@ export class Multisig {
   /**
    * Update the GUARDIAN client used by this Multisig instance.
    *
+   * When repointing to a different GUARDIAN provider after a switch, call
+   * {@link preservePreSwitchProposalNotes} first: pending proposals do not
+   * survive a switch, and the notes embedded in them can only be imported
+   * while the old GUARDIAN is still the current client.
+   *
    * @param guardianClient - The new GUARDIAN HTTP client
    */
   setGuardianClient(guardianClient: GuardianHttpClient): void {
@@ -593,6 +635,27 @@ export class Multisig {
     }
   }
 
+  /**
+   * Sync the local store with the Miden node, then reload the cached account
+   * and multisig config from it (mirrors the Rust `sync_network_only`).
+   * Without the refresh, a summary would be built against the freshly synced
+   * store while readiness thresholds and signature validation still read the
+   * stale cached config. Returns the store-backed account, or `null` when the
+   * store has no record for this account (the cached config is then kept, as
+   * in `getStoreAccount`); callers that require the account decide how to
+   * fail.
+   */
+  private async syncNetworkOnly(): Promise<Account | null> {
+    const webClient = await this.getRawClient();
+    await retryRpcRead(() => webClient.syncState(), this.rpcConfig);
+    const account = await retryRpcRead(
+      () => webClient.getAccount(AccountId.fromHex(this._accountId)),
+      this.rpcConfig,
+    );
+    this.refreshConfigFromAccount(account ?? null);
+    return account ?? null;
+  }
+
   private refreshConfigFromAccount(account: Account | null): void {
     if (!account) {
       return;
@@ -677,6 +740,67 @@ export class Multisig {
     return Array.from(this.proposals.values());
   }
 
+  /**
+   * {@link syncProposals} variant for the recovery flow: per-proposal
+   * failures (a payload that does not parse, a metadata binding that does
+   * not verify) are isolated as skip reasons instead of failing the whole
+   * listing, so one corrupt proposal cannot block recovering notes from the
+   * healthy ones. The strict listing stays the signing-path behavior, where
+   * a malformed proposal must surface loudly. Proposals at or below the
+   * account's committed nonce are dropped (already executed or superseded,
+   * matching the Rust SDK's listing), and the shared proposal cache is left
+   * untouched. GUARDIAN being unreachable still throws — there is nothing
+   * to isolate without a listing.
+   */
+  private async syncProposalsIsolatingFailures(cancelled?: () => boolean): Promise<{
+    proposals: Proposal[];
+    skipped: Array<{ identifier: string; reason: string }>;
+  }> {
+    const deltas = await this.guardian.getDeltaProposals(this._accountId);
+    const factory = this.proposalFactory();
+
+    let currentNonce: bigint | undefined;
+    try {
+      currentNonce = this.account.nonce().asInt();
+    } catch {
+      currentNonce = undefined;
+    }
+
+    const proposals: Proposal[] = [];
+    const skipped: Array<{ identifier: string; reason: string }> = [];
+    for (let position = 0; position < deltas.length; position += 1) {
+      throwIfCancelled(cancelled);
+      const delta = deltas[position];
+      const identifier = `proposal at nonce ${delta.nonce} (#${position})`;
+      try {
+        const proposalId = normalizeHexWord(
+          computeCommitmentFromTxSummary(delta.deltaPayload.txSummary.data)
+        );
+        const existingProposal = this.proposals.get(proposalId);
+        const proposal = factory.fromDelta(
+          delta,
+          proposalId,
+          existingProposal?.metadata,
+          existingProposal?.signatures ?? [],
+        );
+        // Stale-nonce check before the binding verification (matching the
+        // Rust listing): the verification re-executes consume proposals in
+        // the VM, which is wasted on proposals already executed/superseded.
+        if (currentNonce !== undefined && BigInt(proposal.nonce) <= currentNonce) {
+          continue;
+        }
+        await this.verifyProposalMetadataBinding(proposal);
+        proposals.push(proposal);
+      } catch (error) {
+        skipped.push({
+          identifier,
+          reason: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    return { proposals, skipped };
+  }
+
   /**
    * List all known proposals
    */
@@ -925,6 +1049,27 @@ export class Multisig {
     options: CreateProposalOptions = {},
   ): Promise<Proposal> {
     const proposalNonce = resolveProposalNonce('createSwitchGuardianProposal', options);
+    const { summaryBase64, metadata } = await this.buildSwitchGuardianSummary(
+      newGuardianEndpoint,
+      newGuardianPubkey,
+    );
+
+    // SwitchGuardian is a regular delta proposal; push it to GUARDIAN so
+    // sign/execute (which fetch from GUARDIAN) can find it. To leave an
+    // unreachable GUARDIAN, use createSwitchGuardianProposalOffline instead.
+    return this.createProposal(proposalNonce, summaryBase64, metadata);
+  }
+
+  /**
+   * Shared build step for both switch-GUARDIAN creation paths: verify the new
+   * endpoint's `/pubkey` commitment, then execute the update-guardian request
+   * for its summary and metadata. Kept in one place so the online and offline
+   * proposals for the same operation can never drift apart.
+   */
+  private async buildSwitchGuardianSummary(
+    newGuardianEndpoint: string,
+    newGuardianPubkey: string,
+  ): Promise<{ summaryBase64: string; metadata: ProposalMetadata }> {
     const webClient = await this.getRawClient();
     await this.verifyGuardianEndpointCommitment(newGuardianEndpoint, newGuardianPubkey);
 
@@ -949,9 +1094,68 @@ export class Multisig {
       description: `Switch GUARDIAN to ${newGuardianEndpoint}`,
     };
 
-    // SwitchGuardian is a regular delta proposal; push it to GUARDIAN so
-    // sign/execute (which fetch from GUARDIAN) can find it.
-    return this.createProposal(proposalNonce, summaryBase64, metadata);
+    return { summaryBase64, metadata };
+  }
+
+  /**
+   * Create a "switch GUARDIAN" proposal fully offline — nothing is pushed to
+   * the current GUARDIAN, so an account can leave an unreachable operator
+   * (issue #433; mirrors the Rust `create_proposal_offline`).
+   *
+   * The transaction summary is built and signed locally, the proposal is
+   * cached for `signProposalOffline` / `executeProposal`, and the returned
+   * `ExportedProposal` (which already includes the proposer's signature) can
+   * be `JSON.stringify`-ed and shared with cosigners for `importProposal`.
+   *
+   * Only switch-GUARDIAN proposals can be created offline: every other
+   * proposal type requires a GUARDIAN acknowledgment at execution, so a
+   * proposal the GUARDIAN never saw could collect signatures but never
+   * execute. The new endpoint must be reachable — its `/pubkey` commitment
+   * is verified before anything is built or signed.
+   *
+   * Note: executeProposal's best-effort canonicalization push cannot reach a
+   * proposal the current GUARDIAN never received, so even if that GUARDIAN is
+   * back up at execution time it keeps serving the account until background
+   * reconciliation (issue #305) — same outcome as executing while it is down.
+   *
+   * @param newGuardianEndpoint - The new GUARDIAN server endpoint URL
+   * @param newGuardianPubkey - The new GUARDIAN server's public key commitment (hex)
+   * @param options - Optional settings: `nonce`
+   */
+  async createSwitchGuardianProposalOffline(
+    newGuardianEndpoint: string,
+    newGuardianPubkey: string,
+    options: CreateProposalOptions = {},
+  ): Promise<ExportedProposal> {
+    const proposalNonce = resolveProposalNonce('createSwitchGuardianProposalOffline', options);
+
+    // Sync with the Miden node and refresh the cached account/config before
+    // building (mirrors the Rust `sync_network_only`): with no GUARDIAN push
+    // to reject a stale delta at creation, a summary built from stale local
+    // state — or a readiness threshold read from stale config — would only
+    // fail at execution, after the whole side-channel cosigning ceremony.
+    await this.syncNetworkOnly();
+
+    const { summaryBase64, metadata } = await this.buildSwitchGuardianSummary(
+      newGuardianEndpoint,
+      newGuardianPubkey,
+    );
+
+    const exported: ExportedProposal = {
+      accountId: this._accountId,
+      nonce: proposalNonce,
+      commitment: computeCommitmentFromTxSummary(summaryBase64),
+      txSummaryBase64: summaryBase64,
+      signatures: [],
+      metadata,
+    };
+
+    // Reuse the cosigner-side machinery end to end: importProposal validates
+    // and caches exactly as it would on a cosigner's client, and
+    // signProposalOffline adds the proposer's signature and re-exports.
+    const proposal = await this.importProposal(JSON.stringify(exported));
+    const signedJson = await this.signProposalOffline(proposal.id);
+    return JSON.parse(signedJson) as ExportedProposal;
   }
 
   /**
@@ -1231,6 +1435,218 @@ export class Multisig {
     return this.importNoteFromBytes(noteBytes);
   }
 
+  /**
+   * Proposal-import strategy of {@link recoverNotes}: import the notes
+   * embedded in the given v2 consume-notes proposals into the local Miden
+   * store, reusing this client's Miden RPC endpoint and retry
+   * configuration.
+   */
+  private async importNotesFromProposals(
+    proposals: ReadonlyArray<Pick<Proposal, 'id' | 'metadata'>>,
+    cancelled?: () => boolean,
+  ): Promise<NoteImportOutcome[]> {
+    return importNotesFromProposalsStandalone(this.midenClient, proposals, {
+      midenRpcEndpoint: this.getMidenRpcEndpoint(),
+      rpc: { retry: { maxAttempts: this.rpcConfig.maxAttempts } },
+      cancelled,
+    });
+  }
+
+  /**
+   * Public-backfill strategy of {@link recoverNotes}: scan a historical
+   * block range for public notes addressed at this account's standard note
+   * tag and import them with their on-chain inclusion proofs, reusing this
+   * client's Miden RPC endpoint and retry configuration.
+   */
+  private async backfillPublicNotesByTag(
+    options: { fromBlock?: number; toBlock?: number } = {},
+  ): Promise<PublicBackfillReport> {
+    return backfillPublicNotesByTagStandalone(this.midenClient, {
+      accountId: this._accountId,
+      midenRpcEndpoint: this.getMidenRpcEndpoint(),
+      rpc: { retry: { maxAttempts: this.rpcConfig.maxAttempts } },
+      ...(options.fromBlock !== undefined ? { fromBlock: options.fromBlock } : {}),
+      ...(options.toBlock !== undefined ? { toBlock: options.toBlock } : {}),
+    });
+  }
+
+  /**
+   * Run the note-recovery strategies as a single wallet-facing flow,
+   * typically right after key-based recovery loaded the account — the TS
+   * counterpart of the Rust SDK's `MultisigClient::recover_notes`.
+   *
+   * By default every strategy runs — the private-note transport backlog
+   * drain, the proposal-embedded note import, and the historical
+   * public-note backfill over the whole chain — followed by a normal sync
+   * (chain sync plus GUARDIAN state sync) that verifies whatever was
+   * imported. Pass {@link RecoverNotesOptions} to choose strategies, bound
+   * the backfill's block range, or skip the final sync.
+   *
+   * No strategy failure aborts the flow: each primitive already reports
+   * per-note and per-source problems instead of throwing, and a strategy
+   * that cannot run at all (GUARDIAN unreachable while listing proposals,
+   * chain tip unresolvable, a broken local store) becomes a
+   * `RecoveryStepProblem` entry in the report while the remaining
+   * strategies still run. The flow is idempotent — rerunning re-imports
+   * nothing that already arrived — so a report with `retryable: true` can
+   * simply be retried. Throws only for an inverted backfill range.
+   */
+  async recoverNotes(options: RecoverNotesOptions = {}): Promise<NoteRecoveryReport> {
+    return runNoteRecovery(options, this.buildNoteRecoverySteps(options));
+  }
+
+  /**
+   * The strategy implementations {@link recoverNotes} hands to
+   * `runNoteRecovery`. The optional `cancelled` token is the pre-switch
+   * import's cooperative cancellation: `runNoteRecovery` checks it before
+   * starting each step, and the proposal-import step threads it into its
+   * listing and import loops so they stop at their next checkpoint too.
+   */
+  private buildNoteRecoverySteps(
+    options: RecoverNotesOptions,
+    cancelled?: () => boolean,
+  ): NoteRecoverySteps {
+    return {
+      transportDrain: () => drainPrivateNoteBacklog(this.midenClient),
+      proposalImport: async () => {
+        // The lenient listing isolates per-proposal parse/binding failures
+        // as skip reasons, so one corrupt proposal cannot block recovering
+        // notes from the healthy ones; those skips surface as `invalid`
+        // outcomes alongside the per-note ones.
+        const { proposals, skipped } = await this.syncProposalsIsolatingFailures(cancelled);
+        const outcomes: NoteImportOutcome[] = skipped.map(({ identifier, reason }) => ({
+          identifier,
+          source: 'proposal',
+          status: 'invalid',
+          reason,
+        }));
+        throwIfCancelled(cancelled);
+        outcomes.push(...(await this.importNotesFromProposals(proposals, cancelled)));
+        return outcomes;
+      },
+      publicBackfill: async () => {
+        // Importing a proof into a store that has never seen the chain
+        // fails, and neither key-based recovery nor `load()` syncs on its
+        // own — so sync the chain state first. Incremental, so cheap when
+        // the store is already synced.
+        try {
+          await this.midenClient.syncChain();
+        } catch (error) {
+          throw new Error(
+            `failed to sync the chain state the backfill imports against: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+        return this.backfillPublicNotesByTag({
+          ...(options.fromBlock !== undefined ? { fromBlock: options.fromBlock } : {}),
+          ...(options.toBlock !== undefined ? { toBlock: options.toBlock } : {}),
+        });
+      },
+      sync: async () => {
+        // Parity with the Rust flow's `sync()`: the transport fetch plus the
+        // chain sync (`MidenClient.sync()` runs both, fail-fast), then the
+        // GUARDIAN state sync.
+        await this.midenClient.sync();
+        await this.syncState();
+      },
+    };
+  }
+
+  /**
+   * Import the notes embedded in the old GUARDIAN's pending consume-notes
+   * proposals while they are still reachable: pending proposals do not
+   * survive a guardian switch, making them the one recovery source
+   * {@link recoverNotes} loses once the client repoints (issue #417).
+   *
+   * Run automatically by {@link executeProposal} on the switch path, before
+   * the switch transaction executes; call it yourself before repointing a
+   * client by hand via {@link setGuardianClient}. Best-effort by contract:
+   * problems are warned, never thrown, and the flow runs under a timeout
+   * with cooperative cancellation plus a bounded settle grace, so a hung
+   * old GUARDIAN can neither block the switch nor overlap it on the shared
+   * client. Returns the recovery report, or `undefined` when the flow could
+   * not run or timed out. Mirror of the Rust SDK's
+   * `preserve_pre_switch_proposal_notes`; full rationale and semantics in
+   * "Preserving Notes Across a Guardian Switch" (docs/MULTISIG_SDK.md).
+   */
+  async preservePreSwitchProposalNotes(): Promise<NoteRecoveryReport | undefined> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let graceTimer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+    try {
+      const cancelled = () => timedOut;
+      const flow = runNoteRecovery(
+        GUARDIAN_SWITCH_RECOVERY_OPTIONS,
+        this.buildNoteRecoverySteps(GUARDIAN_SWITCH_RECOVERY_OPTIONS, cancelled),
+        cancelled,
+      );
+      const outcome = await Promise.race([
+        flow,
+        new Promise<typeof PRE_SWITCH_IMPORT_TIMED_OUT>((resolve) => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            resolve(PRE_SWITCH_IMPORT_TIMED_OUT);
+          }, PRE_SWITCH_IMPORT_TIMEOUT_MS);
+        }),
+      ]);
+      if (outcome === PRE_SWITCH_IMPORT_TIMED_OUT) {
+        console.warn(
+          `Pre-switch proposal-note import timed out after ${PRE_SWITCH_IMPORT_TIMEOUT_MS}ms ` +
+            'and was cancelled; notes embedded in pending proposals may be ' +
+            'unrecoverable after the GUARDIAN switch',
+        );
+        // The token stops all new work; give the one uninterruptible
+        // in-flight operation a bounded grace to settle. The result is
+        // unobserved, and a rejection must not go unhandled.
+        await Promise.race([
+          flow.catch(() => {}),
+          new Promise<void>((resolve) => {
+            graceTimer = setTimeout(resolve, PRE_SWITCH_SETTLE_GRACE_MS);
+          }),
+        ]);
+        return undefined;
+      }
+      for (const problem of outcome.problems) {
+        console.warn(
+          `Pre-switch proposal-note import step '${problem.step}' did not finish; ` +
+            'notes embedded in pending proposals may be unrecoverable after the ' +
+            'GUARDIAN switch',
+          problem.reason,
+        );
+      }
+      // Per-note failures never reach `problems` — and this is the last
+      // moment the notes are reachable, so "retryable" cannot help: the
+      // source is gone once the client repoints. They must be observable now.
+      for (const noteOutcome of outcome.proposalImport ?? []) {
+        if (noteOutcome.status === 'invalid' || noteOutcome.status === 'failed') {
+          console.warn(
+            `Pre-switch import could not preserve embedded note ${noteOutcome.identifier} ` +
+              `(${noteOutcome.status}); it may be unrecoverable after the GUARDIAN switch`,
+            noteOutcome.reason,
+          );
+        }
+      }
+      return outcome;
+    } catch (error) {
+      // runNoteRecovery only throws for caller errors (inverted backfill
+      // range, never passed here), but the switch must survive anything.
+      console.warn(
+        'Pre-switch proposal-note import could not run; notes embedded in pending ' +
+          'proposals may be unrecoverable after the GUARDIAN switch',
+        error,
+      );
+      return undefined;
+    } finally {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      if (graceTimer !== undefined) {
+        clearTimeout(graceTimer);
+      }
+    }
+  }
+
   /**
    * Compute the ID of the note a P2ID proposal will create when executed.
    *
@@ -1253,6 +1669,12 @@ export class Multisig {
       throw new Error('getP2idNoteId requires a P2ID proposal with recipient, faucet, amount, and salt metadata');
     }
 
+    // Validate before deriving. Unlike the rebuild paths there is no commitment check
+    // downstream of this note id -- it goes straight out to a recipient — so a salt that
+    // silently padded to the zero word would produce a plausible id for a note that does
+    // not exist, with nothing to catch it.
+    this.requireProposalSaltHex(proposal.id, metadata);
+
     const note = buildP2idNoteFromMetadata(
       this._accountId,
       metadata.recipientId,
@@ -1379,6 +1801,13 @@ export class Multisig {
   async executeProposal(proposalId: string): Promise<void> {
     const { metadata, finalRequest, proposal } = await this.prepareProposalExecution(proposalId);
 
+    if (metadata.proposalType === 'switch_guardian') {
+      // #417: import notes embedded in pending proposals from the old
+      // GUARDIAN. Must run before the switch executes and repoints;
+      // best-effort and bounded — see preservePreSwitchProposalNotes.
+      await this.preservePreSwitchProposalNotes();
+    }
+
     // Execute at the proposal's anchored reference block, so the summary the
     // cosigners signed reproduces exactly. The anchor was already checked
     // against the summary's block commitment during binding verification.
@@ -1421,13 +1850,7 @@ export class Multisig {
       }
 
       try {
-        const webClient = await this.getRawClient();
-        await retryRpcRead(() => webClient.syncState(), this.rpcConfig);
-
-        const updatedAccount = await retryRpcRead(
-          () => webClient.getAccount(accountId),
-          this.rpcConfig,
-        );
+        const updatedAccount = await this.syncNetworkOnly();
         if (!updatedAccount) {
           throw new Error(
             `Updated account ${this._accountId} is missing from local client`
@@ -1773,9 +2196,23 @@ export class Multisig {
 
     const txSummaryBytes = base64ToUint8Array(txSummaryBase64);
     const txSummary = TransactionSummary.deserialize(txSummaryBytes);
-    const saltHex = summarySalt(txSummary).toHex();
+    const saltHex = this.requireProposalSaltHex(proposalId, metadata);
     const txCommitmentHex = txSummary.toCommitment().toHex();
     const normalizedTxCommitmentHex = normalizeHexWord(txCommitmentHex);
+
+    // This summary was re-fetched from GUARDIAN, not taken from the verified proposal:
+    // `ensureProposalCommitmentMatchesSummary` pins the CACHED `proposal.txSummary` to the
+    // id, and nothing pinned this one. It goes on to key the advice map and drive the
+    // rebuild, so an unrelated summary served here would have signatures collected against
+    // one transaction and advice assembled for another. On an ECDSA roster the
+    // recoverability check would notice; on a Falcon roster nothing else compares them.
+    if (normalizedTxCommitmentHex !== normalizeHexWord(proposalId)) {
+      throw new Error(
+        `Proposal ${proposalId} tx_summary commitment ${normalizedTxCommitmentHex} ` +
+          'does not match the proposal id it belongs to',
+      );
+    }
+
     const normalizedSignerCommitments = new Set(
       this.signerCommitments.map((commitment) => normalizeHexWord(commitment)),
     );
@@ -1880,12 +2317,15 @@ export class Multisig {
       await this.verifyGuardianEndpointCommitment(metadata.newGuardianEndpoint, metadata.newGuardianPubkey);
     }
 
+    // The builders read `.toHex()` and allocate their own Word, so this handle stays
+    // ours; without the release it leaks once per execute.
     const executionSalt = Word.fromHex(normalizeHexWord(saltHex));
-    const finalRequest = await this.buildTransactionRequestFromMetadata(
-      metadata,
-      executionSalt,
-      adviceMap,
-    );
+    let finalRequest;
+    try {
+      finalRequest = await this.buildTransactionRequestFromMetadata(metadata, executionSalt, adviceMap);
+    } finally {
+      executionSalt.free?.();
+    }
 
     return { finalRequest, metadata, proposal };
   }
@@ -2085,9 +2525,9 @@ export class Multisig {
         return txSummaryCommitment;
       }
 
-      const salt = proposal.metadata.saltHex
-        ? Word.fromHex(normalizeHexWord(proposal.metadata.saltHex))
-        : summarySalt(summary);
+      const salt = Word.fromHex(
+        normalizeHexWord(this.requireProposalSaltHex(proposal.id, proposal.metadata)),
+      );
 
       const request = await this.buildTransactionRequestFromMetadata(proposal.metadata, salt);
       const webClient = await this.getRawClient();
@@ -2110,6 +2550,59 @@ export class Multisig {
    * cannot be reproduced, verified, or executed. The caller owns the returned
    * anchor and must `free()` it once done.
    */
+  /**
+   * Reads a proposal's salt. Throws when absent, because there is nothing to fall
+   * back to.
+   *
+   * The request declares this salt through `withFeeConversionSalt`, and miden-client
+   * commits `hash(CONVERSION_INFO || SALT)` into the auth arg from it. The summary
+   * therefore carries the COMMITMENT, and a commitment is not invertible to the salt
+   * it was built from -- so `summaryAuthArg(summary)` cannot stand in here. It used
+   * to: before the request declared a salt the auth arg WAS the bare salt, which is
+   * why the fallback this replaces was correct when it was written.
+   *
+   * A declared salt also bypasses miden-client's zero-fee early return, so this holds
+   * on a chain that charges nothing exactly as on one that charges.
+   */
+  private requireProposalSaltHex(proposalId: string, metadata: ProposalMetadata): string {
+    const saltHex: unknown = metadata.saltHex;
+
+    if (saltHex === undefined || saltHex === null || saltHex === '') {
+      throw new Error(
+        `Proposal ${proposalId} has no salt; its request cannot be rebuilt because ` +
+          'the auth arg commits hash(CONVERSION_INFO || SALT) and is not invertible ' +
+          'to the salt',
+      );
+    }
+
+    // GUARDIAN serves this field and the response is cast, not parsed, so everything
+    // below is untrusted input. A truthiness test is not enough: `normalizeHexWord`
+    // left-pads, so `'0x'` and `'0X'` are truthy and pad to the ZERO word -- a salt
+    // nobody chose, which rebuilds a different request and reports itself as a summary
+    // mismatch. A non-string throws out of the hex helpers instead, and an unbounded
+    // string is a logging hazard the error type already guards against.
+    if (typeof saltHex !== 'string') {
+      throw new ProposalSaltMalformedError({
+        proposalId,
+        saltHex,
+        reason: `expected a hex string, got ${typeof saltHex}`,
+      });
+    }
+    const digits = saltHex.replace(/^0[xX]/, '');
+    if (digits.length === 0 || digits.length > MAX_SALT_HEX_DIGITS || !/^[0-9a-fA-F]+$/.test(digits)) {
+      throw new ProposalSaltMalformedError({
+        proposalId,
+        saltHex,
+        reason:
+          digits.length === 0
+            ? 'a hex prefix with no digits is the zero word, not a salt'
+            : `expected 1 to ${MAX_SALT_HEX_DIGITS} hex digits`,
+      });
+    }
+
+    return saltHex;
+  }
+
   private requireProposalAnchor(proposalId: string, metadata: ProposalMetadata): ChainAnchor {
     if (!metadata.chainAnchor) {
       throw new Error(

package/src/procedures.ts

@@ -13,7 +13,7 @@
 export const PROCEDURE_ROOTS = {
   update_signers: '0xa261cfd3c8791ac5abe1e78e14eade2f20789d73ab1c23c430418de59bc3380e',
   update_procedure_threshold: '0x97587c61d49313b1d5a3c8b7437e0080e67ed9bd9d3e7206bcae562f934ccd03',
-  auth_tx: '0xa6aa6f69d9358535272ba433cd48d20628a5c69598e00c6dd01a22e83a5f15df',
+  auth_tx: '0x43fb07d62ed26993b7b13c7b411db62c5b5acffa2813e989608c41a72d7185ec',
   update_guardian: '0x0a614ff7c81a561cbd2a4c2d9482031a7a841ca5de33349daed23a9d871b3675',
   send_asset: '0x595bc83258726a66bd904912cfd5186c07cbd902dfbc115b7d6bc8105efc57e3',
   receive_asset: '0x34a56dd18f6fe5aab63198b9dcfc6467e793ebabb37d56b994b902504635da13',