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

package/dist/multisig.js

@@ -5,8 +5,9 @@
  * for proposal management.
  */
 import { GuardianHttpClient } from '@openzeppelin/guardian-client';
+import { ProposalSaltMalformedError } from './multisig/authArgErrors.js';
 import { Account, AccountId, AdviceMap, Endpoint, FeltArray, Note, NoteExportFormat, NoteFile, RpcClient, Signature, TransactionRequest, TransactionSummary, Word, } from '@miden-sdk/miden-sdk';
-import { chainAnchorFromBase64, chainAnchorToBase64, executeForSummary, executeForSummaryAt, summarySalt, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
+import { chainAnchorFromBase64, chainAnchorToBase64, executeForSummary, executeForSummaryAt, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
 import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
 import { CONSUME_NOTES_METADATA_VERSION_V2, MAX_CONSUME_NOTES_METADATA_BYTES, } from './types/proposal.js';
 import { LEGACY_CONSUME_NOTES_ENABLED } from './multisig/config.js';
@@ -20,6 +21,10 @@ 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, } from './recovery/proposalNoteImport.js';
+import { backfillPublicNotesByTag as backfillPublicNotesByTagStandalone, } from './recovery/publicNoteBackfill.js';
+import { drainPrivateNoteBacklog } from './recovery/transportDrain.js';
+import { GUARDIAN_SWITCH_RECOVERY_OPTIONS, runNoteRecovery, } from './recovery/recoverNotes.js';
 import { getRawMidenClient, getTransactionProver, requireMidenRpcEndpoint, } from './raw-client.js';
 import { resolveProverConfig, } from './prover/config.js';
 import { ProverWorkflow } from './prover/workflow.js';
@@ -67,6 +72,22 @@ function resolveProposalNonce(method, options, legacyArgs = []) {
     }
     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;
     threshold;
@@ -241,6 +262,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) {
@@ -379,6 +405,23 @@ export class Multisig {
             throw error;
         }
     }
+    /**
+     * 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.
+     */
+    async syncNetworkOnly() {
+        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;
+    }
     refreshConfigFromAccount(account) {
         if (!account) {
             return;
@@ -445,6 +488,56 @@ 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.
+     */
+    async syncProposalsIsolatingFailures(cancelled) {
+        const deltas = await this.guardian.getDeltaProposals(this._accountId);
+        const factory = this.proposalFactory();
+        let currentNonce;
+        try {
+            currentNonce = this.account.nonce().asInt();
+        }
+        catch {
+            currentNonce = undefined;
+        }
+        const proposals = [];
+        const skipped = [];
+        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
      */
@@ -613,6 +706,19 @@ export class Multisig {
      */
     async createSwitchGuardianProposal(newGuardianEndpoint, newGuardianPubkey, options = {}) {
         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.
+     */
+    async buildSwitchGuardianSummary(newGuardianEndpoint, newGuardianPubkey) {
         const webClient = await this.getRawClient();
         await this.verifyGuardianEndpointCommitment(newGuardianEndpoint, newGuardianPubkey);
         const { request, salt } = await buildUpdateGuardianTransactionRequest(webClient, newGuardianPubkey, { signatureScheme: this.signer.scheme });
@@ -629,9 +735,56 @@ export class Multisig {
             newGuardianEndpoint,
             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, newGuardianPubkey, options = {}) {
+        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 = {
+            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);
     }
     /**
      * Create a "consume notes" proposal to consume notes sent to the multisig account.
@@ -862,6 +1015,189 @@ export class Multisig {
         const noteBytes = new Uint8Array(await file.arrayBuffer());
         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.
+     */
+    async importNotesFromProposals(proposals, cancelled) {
+        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.
+     */
+    async backfillPublicNotesByTag(options = {}) {
+        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 = {}) {
+        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.
+     */
+    buildNoteRecoverySteps(options, cancelled) {
+        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 = 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() {
+        let timer;
+        let graceTimer;
+        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((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((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.
      *
@@ -881,6 +1217,11 @@ export class Multisig {
             !metadata.saltHex) {
             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, metadata.faucetId, BigInt(metadata.amount), parseP2idNoteType(metadata.noteType), metadata.saltHex, { reclaimHeight: metadata.reclaimHeight, timelockHeight: metadata.timelockHeight });
         return note.id().toString();
     }
@@ -974,6 +1315,12 @@ export class Multisig {
      */
     async executeProposal(proposalId) {
         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.
@@ -1009,9 +1356,7 @@ export class Multisig {
                     'will keep serving this account until reconciliation', error);
             }
             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`);
                 }
@@ -1243,9 +1588,19 @@ 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)));
         const adviceMap = new AdviceMap();
         const adviceMapKeys = new Set();
@@ -1319,8 +1674,16 @@ export class Multisig {
         if (metadata.proposalType === 'switch_guardian') {
             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 };
     }
     /**
@@ -1475,9 +1838,7 @@ export class Multisig {
                 // guardian endpoint commitment provide the binding checks for this type.
                 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();
             const reconstructed = await executeForSummaryAt(webClient, this._accountId, request, anchor);
@@ -1497,6 +1858,52 @@ 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.
+     */
+    requireProposalSaltHex(proposalId, metadata) {
+        const saltHex = 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;
+    }
     requireProposalAnchor(proposalId, metadata) {
         if (!metadata.chainAnchor) {
             throw new Error(`Proposal ${proposalId} has no chain anchor; it was created without ` +