@openzeppelin/miden-multisig-client 0.17.0 → 0.18.0-rc.1

package/dist/multisig.js

@@ -6,15 +6,17 @@
  */
 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, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
+import { Account, AccountId, AdviceMap, FeltArray, Note, NoteExportFormat, NoteFile, Signature, TransactionRequest, TransactionSummary, Word, } from '@miden-sdk/miden-sdk';
+import { chainAnchorFromBase64, chainAnchorToBase64, executeForSummary, executeForSummaryAt, summaryApprovalExpirationBlockNum, summarySalt, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
 import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
+import { validateMultisigConfig } from './account/builder.js';
+import { ensureNotesAuthenticated } from './transaction/noteAuthentication.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';
 import { ConsumeNotesMetadataOversizeError, LegacyConsumeNotesNoteMissingError, NoteBindingMismatchError, UnsupportedMetadataVersionError, } from './multisig/consumeNotesErrors.js';
 import { noteFromBase64, noteToBase64 } from './utils/encoding.js';
 import { base64ToUint8Array, uint8ArrayToBase64, normalizeHexWord, } from './utils/encoding.js';
-import { assertEcdsaSignatureRecoverable, buildSignatureAdviceEntry, normalizeSignerCommitment, signatureHexToBytes, tryComputeEcdsaCommitmentHex, } from './utils/signature.js';
+import { assertEcdsaSignatureRecoverable, buildEip712SignatureAdviceEntry, buildSignatureAdviceEntry, normalizeSignerCommitment, signatureHexToBytes, tryComputeEcdsaCommitmentHex, } from './utils/signature.js';
 import { computeCommitmentFromTxSummary, accountIdToHex } from './multisig/helpers.js';
 import { buildGuardianSignatureFromSigner } from './multisig/signing.js';
 import { AccountInspector, assertCompleteDetectedConfig } from './inspector.js';
@@ -29,7 +31,9 @@ import { getRawMidenClient, getTransactionProver, requireMidenRpcEndpoint, } fro
 import { resolveProverConfig, } from './prover/config.js';
 import { ProverWorkflow } from './prover/workflow.js';
 import { resolveRpcConfig, } from './rpc/config.js';
+import { isTransientRpcError } from './rpc/errors.js';
 import { retryRpcRead } from './rpc/retry.js';
+import { isSafeToAdoptGuardianState, readOnChainCommitment } from './state/adopt.js';
 /**
  * Represents a multisig account with GUARDIAN integration.
  */
@@ -72,6 +76,39 @@ function resolveProposalNonce(method, options, legacyArgs = []) {
     }
     return options.nonce ?? Date.now();
 }
+function proposalRequestBinding(summary, anchor, saltHex) {
+    const boundBlockNum = anchor.blockNum();
+    return {
+        saltHex: normalizeHexWord(saltHex),
+        boundBlockNum,
+        approvalExpirationDelta: approvalExpirationDeltaOf(summaryApprovalExpirationBlockNum(summary), boundBlockNum),
+    };
+}
+/**
+ * The approval expiration delta a rebuild has to pass: the absolute expiration
+ * block the summary binds, relative to the bound block. `undefined` for an
+ * approval that never expires.
+ */
+function approvalExpirationDeltaOf(expirationBlockNum, boundBlockNum) {
+    if (expirationBlockNum === undefined) {
+        return undefined;
+    }
+    const delta = expirationBlockNum - boundBlockNum;
+    if (delta < 1) {
+        throw new Error(`Invalid proposal: approval expires at block ${expirationBlockNum}, at or before the ` +
+            `block ${boundBlockNum} its summary binds`);
+    }
+    return delta;
+}
+function summarySaltHex(summary) {
+    const salt = summarySalt(summary);
+    try {
+        return normalizeHexWord(salt.toHex());
+    }
+    finally {
+        salt.free?.();
+    }
+}
 /**
  * Deadline for `Multisig.preservePreSwitchProposalNotes`: no client in the
  * stack applies request deadlines, and a half-dead old GUARDIAN must not
@@ -88,6 +125,12 @@ const PRE_SWITCH_IMPORT_TIMED_OUT = Symbol('pre-switch proposal-note import time
 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;
+/**
+ * Consecutive successful listings that must omit a guardian-known proposal
+ * not yet listed (a fresh create during read-your-writes lag, or one
+ * orphaned by a GUARDIAN repoint) before the sync prunes it.
+ */
+const UNREPORTED_LISTING_MISS_LIMIT = 2;
 export class Multisig {
     account;
     threshold;
@@ -104,6 +147,24 @@ export class Multisig {
     _accountId;
     midenRpcEndpoint;
     proposals = new Map();
+    /** Ids GUARDIAN returned on the most recent sync; these prune immediately when dropped. */
+    lastReportedProposalIds = new Set();
+    /**
+     * Ids GUARDIAN is known to hold: acknowledged `createProposal` pushes,
+     * acknowledged `signProposal` signatures, plus every listed id. Only these
+     * are subject to miss-based pruning; offline creations and imports GUARDIAN
+     * never received are exempt.
+     */
+    guardianKnownProposalIds = new Set();
+    /**
+     * Consecutive successful listings that omitted a guardian-known proposal
+     * not yet listed; at {@link UNREPORTED_LISTING_MISS_LIMIT} it is pruned.
+     */
+    unreportedMissCounts = new Map();
+    /** Bumped by {@link setGuardianClient}; a sync spanning a bump aborts unapplied. */
+    syncGeneration = 0;
+    /** Pending sync shared by overlapping {@link syncProposals} callers. */
+    syncProposalsInFlight;
     constructor(account, config, guardian, signer, midenClient, accountId, midenRpcEndpoint, proverConfig, rpcConfig) {
         this.account = account;
         this.threshold = config.threshold;
@@ -251,6 +312,17 @@ export class Multisig {
             threshold,
         }));
     }
+    /**
+     * The request options every `create*Proposal` hands its builder: the account,
+     * the caller's approval expiration, and the signer's scheme.
+     */
+    proposalRequestOptions(options) {
+        return {
+            accountId: this._accountId,
+            approvalExpirationDelta: options.approvalExpirationDelta,
+            signatureScheme: this.signer.scheme,
+        };
+    }
     warnOnOverrideDilution(newNumSigners) {
         const current = this.signerCommitments.length;
         for (const { procedure, threshold } of this.overridesDilutedBySignerGrowth(newNumSigners)) {
@@ -267,11 +339,23 @@ export class Multisig {
      * survive a switch, and the notes embedded in them can only be imported
      * while the old GUARDIAN is still the current client.
      *
+     * Repointing abandons a {@link syncProposals} still in flight: it rejects
+     * without applying its listing, though its request to the old GUARDIAN is
+     * not cancelled, so callers already awaiting it see the rejection only
+     * once that response settles. The reported-id and miss-count bookkeeping
+     * is reset; the set of ids GUARDIAN is known to hold is kept on purpose,
+     * so proposals orphaned by the repoint expire through the two-miss rule
+     * instead of lingering.
+     *
      * @param guardianClient - The new GUARDIAN HTTP client
      */
     setGuardianClient(guardianClient) {
         this.guardian = guardianClient;
         this.guardian.setSigner(this.signer);
+        this.syncGeneration += 1;
+        this.syncProposalsInFlight = undefined;
+        this.lastReportedProposalIds = new Set();
+        this.unreportedMissCounts = new Map();
     }
     /**
      * Fetch the current account state from GUARDIAN.
@@ -359,51 +443,15 @@ export class Multisig {
      * not match the on-chain commitment.
      */
     async isSafeToOverwriteLocalState(incomingAccount, localAccount) {
-        if (localAccount) {
-            const localNonce = localAccount.nonce().asInt();
-            const incomingNonce = incomingAccount.nonce().asInt();
-            if (incomingNonce < localNonce) {
-                return false;
-            }
-            if (incomingNonce === localNonce) {
-                throw new Error(`Refusing to overwrite local state: incoming nonce ${incomingNonce.toString()} equals local nonce ${localNonce.toString()} but commitments differ for account ${this._accountId}`);
-            }
-        }
-        const accountId = AccountId.fromHex(this._accountId);
-        const onChainCommitment = await this.getOnChainCommitment(accountId);
-        if (!onChainCommitment) {
-            return true;
-        }
-        const incomingCommitment = normalizeHexWord(incomingAccount.to_commitment().toHex());
-        if (incomingCommitment !== onChainCommitment) {
-            throw new Error(`Refusing to overwrite local state: incoming commitment does not match on-chain commitment for account ${this._accountId}`);
-        }
-        return true;
+        return isSafeToAdoptGuardianState({
+            accountId: this._accountId,
+            incomingAccount,
+            localAccount,
+            readCommitment: () => this.getOnChainCommitment(AccountId.fromHex(this._accountId)),
+        });
     }
     async getOnChainCommitment(accountId) {
-        const rpcClient = new RpcClient(new Endpoint(this.getMidenRpcEndpoint()));
-        try {
-            const accountDetails = await retryRpcRead(() => rpcClient.getAccountDetails(accountId), this.rpcConfig);
-            // If the account is not found or its commitment is zero, means that the account is not deployed yet
-            if (!accountDetails) {
-                return null;
-            }
-            const commitment = normalizeHexWord(accountDetails.commitment().toHex());
-            const zeroCommitment = `0x${'0'.repeat(64)}`;
-            if (commitment === zeroCommitment) {
-                return null;
-            }
-            return commitment;
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (message.includes('null pointer passed to rust') ||
-                message.includes('No account header record found for given ID') ||
-                message.toLowerCase().includes('not found')) {
-                return null;
-            }
-            throw error;
-        }
+        return readOnChainCommitment(this.getMidenRpcEndpoint(), accountId, this.rpcConfig);
     }
     /**
      * Sync the local store with the Miden node, then reload the cached account
@@ -474,18 +522,119 @@ export class Multisig {
         }
     }
     /**
-     * Sync proposals from the GUARDIAN server.
+     * Sync proposals from the GUARDIAN server, reconciling the local cache to
+     * the response. GUARDIAN reports only pending proposals, so a proposal it
+     * reported on an earlier sync and now omits is pruned immediately. A
+     * proposal GUARDIAN holds but has not listed yet (a fresh `createProposal`
+     * its read-your-writes has not caught up with, or a proposal orphaned by a
+     * {@link setGuardianClient} repoint) is pruned only after
+     * {@link UNREPORTED_LISTING_MISS_LIMIT} consecutive listings omit it.
+     * Proposals GUARDIAN never received (an `importProposal`, or a
+     * `createSwitchGuardianProposalOffline`) are not pruned by listings; an
+     * import graduates to the pruned classes once GUARDIAN acknowledges it
+     * (listed, or a successful online `signProposal`).
+     * Proposals cached or replaced after the sync started are not evaluated
+     * by it.
+     *
+     * Every synced proposal's metadata is checked against its signed summary
+     * and the outcome is recorded in {@link Proposal.verification}. One that
+     * fails is still cached and returned, so a single stale or corrupt
+     * proposal cannot hide the others (issue #462: once the node prunes a
+     * proposal's anchor block its re-execution fails for everyone). `failed`
+     * with `retryable: true` means a transient node error, worth syncing
+     * again; `retryable: false` means the proposal cannot be reproduced and
+     * must be re-proposed. `signProposal` and `executeProposal` re-verify and
+     * refuse a failed proposal. A failed proposal still counts as reported, so
+     * it is pruned like any other once GUARDIAN stops listing it.
+     *
+     * The response is parsed in full before the cache or the pruning state
+     * changes; a payload that does not parse at all rejects and leaves both
+     * untouched, so malformed GUARDIAN data is never silently dropped.
+     * Signatures added to a cached proposal while the sync was verifying are
+     * preserved by its apply, and a proposal executed locally in that window
+     * stays `finalized` rather than reverting to the listed pending state.
+     * Overlapping callers share the same in-flight promise. A sync that spans a {@link setGuardianClient} repoint rejects
+     * without applying its listing.
+     *
+     * Nonce-based staleness hiding is the caller's job (see the examples'
+     * `filterVisibleProposals`): callers of this shared client disagree on
+     * whether a proposal's `nonce` is the pre-execution or the next account
+     * nonce, so the Rust client's `proposal.nonce <= account.nonce()` filter
+     * cannot be applied here. This is an intentional TS/Rust surface
+     * difference.
      */
-    async syncProposals() {
+    syncProposals() {
+        if (this.syncProposalsInFlight) {
+            return this.syncProposalsInFlight;
+        }
+        const inFlight = this.reconcileProposals().finally(() => {
+            if (this.syncProposalsInFlight === inFlight) {
+                this.syncProposalsInFlight = undefined;
+            }
+        });
+        this.syncProposalsInFlight = inFlight;
+        return inFlight;
+    }
+    async reconcileProposals() {
+        const generation = this.syncGeneration;
+        const candidates = new Map(this.proposals);
         const deltas = await this.guardian.getDeltaProposals(this._accountId);
         const factory = this.proposalFactory();
+        const reported = new Map();
         for (const delta of deltas) {
             const proposalId = normalizeHexWord(computeCommitmentFromTxSummary(delta.deltaPayload.txSummary.data));
             const existingProposal = this.proposals.get(proposalId);
             const proposal = factory.fromDelta(delta, proposalId, existingProposal?.metadata, existingProposal?.signatures ?? []);
-            await this.verifyProposalMetadataBinding(proposal);
+            // The outcome lands on the proposal either way; a failure is reported
+            // there rather than failing the sync.
+            await this.verifyProposalMetadataBinding(proposal).catch(() => undefined);
+            reported.set(proposal.id, { delta, verified: proposal });
+        }
+        if (generation !== this.syncGeneration) {
+            throw new Error('Sync aborted: the GUARDIAN client was replaced while the sync was in flight');
+        }
+        const applied = [];
+        for (const { delta, verified } of reported.values()) {
+            const current = this.proposals.get(verified.id);
+            if (current?.status === 'finalized') {
+                applied.push(current);
+                continue;
+            }
+            applied.push(current === undefined
+                ? verified
+                : {
+                    ...factory.fromDelta(delta, verified.id, verified.metadata, current.signatures),
+                    verification: verified.verification,
+                });
+        }
+        for (const proposal of applied) {
             this.proposals.set(proposal.id, proposal);
+            this.guardianKnownProposalIds.add(proposal.id);
+        }
+        const missCounts = new Map();
+        for (const [id, snapshot] of candidates) {
+            if (reported.has(id) || this.proposals.get(id) !== snapshot) {
+                continue;
+            }
+            if (this.lastReportedProposalIds.has(id)) {
+                this.proposals.delete(id);
+                this.guardianKnownProposalIds.delete(id);
+                continue;
+            }
+            if (!this.guardianKnownProposalIds.has(id)) {
+                continue;
+            }
+            const misses = (this.unreportedMissCounts.get(id) ?? 0) + 1;
+            if (misses >= UNREPORTED_LISTING_MISS_LIMIT) {
+                this.proposals.delete(id);
+                this.guardianKnownProposalIds.delete(id);
+            }
+            else {
+                missCounts.set(id, misses);
+            }
         }
+        this.unreportedMissCounts = missCounts;
+        this.lastReportedProposalIds = new Set(reported.keys());
         return Array.from(this.proposals.values());
     }
     /**
@@ -539,7 +688,10 @@ export class Multisig {
         return { proposals, skipped };
     }
     /**
-     * List all known proposals
+     * Returns the proposals cached by the most recent {@link syncProposals}
+     * call, plus any locally created or imported proposals GUARDIAN has not
+     * reported yet (see {@link syncProposals} for their retention). Not a
+     * durable history: proposals GUARDIAN no longer reports were pruned.
      */
     listProposals() {
         return Array.from(this.proposals.values());
@@ -565,6 +717,7 @@ export class Multisig {
         const proposal = this.proposalFactory().fromDelta(response.delta, response.commitment, metadata);
         await this.verifyProposalMetadataBinding(proposal);
         this.proposals.set(proposal.id, proposal);
+        this.guardianKnownProposalIds.add(proposal.id);
         return proposal;
     }
     /**
@@ -579,8 +732,16 @@ export class Multisig {
         const webClient = await this.getRawClient();
         const targetThreshold = options.newThreshold ?? this.threshold;
         const targetSignerCommitments = [...this.signerCommitments, newCommitment];
+        // What `update_signers_and_threshold` rejects on-chain, and what the auth
+        // procedure asserts on every transaction after the update, checked before
+        // any signature is collected.
+        validateMultisigConfig({
+            threshold: targetThreshold,
+            signerCommitments: targetSignerCommitments,
+            guardianCommitment: this.guardianCommitment,
+        });
         this.warnOnOverrideDilution(targetSignerCommitments.length);
-        const { request, salt } = await buildUpdateSignersTransactionRequest(webClient, targetThreshold, targetSignerCommitments, { signatureScheme: this.signer.scheme });
+        const { request, salt } = await buildUpdateSignersTransactionRequest(webClient, targetThreshold, targetSignerCommitments, this.proposalRequestOptions(options));
         const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
         const chainAnchor = chainAnchorToBase64(anchor);
         anchor.free();
@@ -618,7 +779,7 @@ export class Multisig {
         if (targetThreshold < 1 || targetThreshold > targetSignerCommitments.length) {
             throw new Error(`Invalid threshold ${targetThreshold}. Must be between 1 and ${targetSignerCommitments.length}`);
         }
-        const { request, salt } = await buildUpdateSignersTransactionRequest(webClient, targetThreshold, targetSignerCommitments, { signatureScheme: this.signer.scheme });
+        const { request, salt } = await buildUpdateSignersTransactionRequest(webClient, targetThreshold, targetSignerCommitments, this.proposalRequestOptions(options));
         const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
         const chainAnchor = chainAnchorToBase64(anchor);
         anchor.free();
@@ -649,7 +810,7 @@ export class Multisig {
         if (newThreshold === this.threshold) {
             throw new Error('New threshold is the same as current threshold');
         }
-        const { request, salt } = await buildUpdateSignersTransactionRequest(webClient, newThreshold, this.signerCommitments, { signatureScheme: this.signer.scheme });
+        const { request, salt } = await buildUpdateSignersTransactionRequest(webClient, newThreshold, this.signerCommitments, this.proposalRequestOptions(options));
         const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
         const chainAnchor = chainAnchorToBase64(anchor);
         anchor.free();
@@ -678,7 +839,7 @@ export class Multisig {
         if (currentOverride !== undefined && currentOverride === targetThreshold) {
             throw new Error(`Procedure ${targetProcedure} already has threshold override ${targetThreshold}`);
         }
-        const { request, salt } = await buildUpdateProcedureThresholdTransactionRequest(webClient, targetProcedure, targetThreshold, { signatureScheme: this.signer.scheme });
+        const { request, salt } = await buildUpdateProcedureThresholdTransactionRequest(webClient, targetProcedure, targetThreshold, this.proposalRequestOptions(options));
         const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
         const chainAnchor = chainAnchorToBase64(anchor);
         anchor.free();
@@ -706,7 +867,7 @@ export class Multisig {
      */
     async createSwitchGuardianProposal(newGuardianEndpoint, newGuardianPubkey, options = {}) {
         const proposalNonce = resolveProposalNonce('createSwitchGuardianProposal', options);
-        const { summaryBase64, metadata } = await this.buildSwitchGuardianSummary(newGuardianEndpoint, newGuardianPubkey);
+        const { summaryBase64, metadata } = await this.buildSwitchGuardianSummary(newGuardianEndpoint, newGuardianPubkey, options.approvalExpirationDelta);
         // 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.
@@ -718,10 +879,21 @@ export class Multisig {
      * 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) {
+    async buildSwitchGuardianSummary(newGuardianEndpoint, newGuardianPubkey, approvalExpirationDelta) {
         const webClient = await this.getRawClient();
+        // What `auth_tx_guarded_multisig` asserts after a guardian rotation, checked
+        // before any signature is collected.
+        validateMultisigConfig({
+            threshold: this.threshold,
+            signerCommitments: [...this.signerCommitments],
+            guardianCommitment: newGuardianPubkey,
+        });
         await this.verifyGuardianEndpointCommitment(newGuardianEndpoint, newGuardianPubkey);
-        const { request, salt } = await buildUpdateGuardianTransactionRequest(webClient, newGuardianPubkey, { signatureScheme: this.signer.scheme });
+        const { request, salt } = await buildUpdateGuardianTransactionRequest(webClient, newGuardianPubkey, {
+            accountId: this._accountId,
+            approvalExpirationDelta,
+            signatureScheme: this.signer.scheme,
+        });
         const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
         const chainAnchor = chainAnchorToBase64(anchor);
         anchor.free();
@@ -770,7 +942,7 @@ export class Multisig {
         // 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 { summaryBase64, metadata } = await this.buildSwitchGuardianSummary(newGuardianEndpoint, newGuardianPubkey, options.approvalExpirationDelta);
         const exported = {
             accountId: this._accountId,
             nonce: proposalNonce,
@@ -808,8 +980,12 @@ export class Multisig {
             }
             fetchedNotes.push(inputNoteRecord.toNote());
         }
+        // Canonical consumption mode is authenticated (issue #409): the summary this
+        // proposal signs must be the one every cosigner's rebuild reproduces, so
+        // the notes are authenticated here first, before the anchor is captured.
+        await this.ensureNotesAuthenticated(fetchedNotes);
         const embeddedNotes = fetchedNotes.map((n) => noteToBase64(n));
-        const { request, salt } = buildConsumeNotesTransactionRequestFromNotes(fetchedNotes);
+        const { request, salt } = await buildConsumeNotesTransactionRequestFromNotes(webClient, fetchedNotes, this.proposalRequestOptions(options));
         const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
         const chainAnchor = chainAnchorToBase64(anchor);
         anchor.free();
@@ -854,7 +1030,7 @@ export class Multisig {
         // Forward everything but the nonce, so a note option added to
         // CreateP2idProposalOptions can't be silently dropped before the builder.
         const { nonce: _nonce, ...noteOptions } = options;
-        const { request, salt } = buildP2idTransactionRequest(this._accountId, recipientId, faucetId, amount, noteOptions);
+        const { request, salt } = await buildP2idTransactionRequest(webClient, this._accountId, recipientId, faucetId, amount, noteOptions);
         const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
         const chainAnchor = chainAnchorToBase64(anchor);
         anchor.free();
@@ -1021,6 +1197,17 @@ export class Multisig {
      * store, reusing this client's Miden RPC endpoint and retry
      * configuration.
      */
+    /**
+     * Puts the local store in the canonical (authenticated) consumption mode
+     * for `notes`, fetching missing inclusion proofs from this client's Miden
+     * node; see {@link ensureNotesAuthenticated}.
+     */
+    async ensureNotesAuthenticated(notes) {
+        await ensureNotesAuthenticated(this.midenClient, notes, {
+            midenRpcEndpoint: this.getMidenRpcEndpoint(),
+            rpc: { retry: { maxAttempts: this.rpcConfig.maxAttempts } },
+        });
+    }
     async importNotesFromProposals(proposals, cancelled) {
         return importNotesFromProposalsStandalone(this.midenClient, proposals, {
             midenRpcEndpoint: this.getMidenRpcEndpoint(),
@@ -1294,6 +1481,7 @@ export class Multisig {
         const signedProposal = factory.fromDelta(signedDelta, normalizedProposalId, proposal.metadata, proposal.signatures);
         await this.verifyProposalMetadataBinding(signedProposal);
         this.proposals.set(signedProposal.id, signedProposal);
+        this.guardianKnownProposalIds.add(signedProposal.id);
         return signedProposal;
     }
     async getProposalForSigning(proposalId, normalizedProposalId) {
@@ -1305,7 +1493,8 @@ export class Multisig {
         return this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
     }
     async createTransactionProposalRequest(proposalId) {
-        const { finalRequest } = await this.prepareProposalExecution(proposalId);
+        const { finalRequest, anchor } = await this.prepareProposalExecution(proposalId);
+        anchor.free();
         return finalRequest;
     }
     /**
@@ -1314,20 +1503,18 @@ export class Multisig {
      * @param proposalId - The proposal commitment/ID
      */
     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.
-        const accountId = AccountId.fromHex(this._accountId);
-        const anchor = this.requireProposalAnchor(proposalId, proposal.metadata);
+        const { metadata, finalRequest, proposal, anchor } = await this.prepareProposalExecution(proposalId);
         try {
-            await this.proverWorkflow.submitAt(accountId, finalRequest, anchor);
+            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.
+            await this.proverWorkflow.submitAt(AccountId.fromHex(this._accountId), finalRequest, anchor);
         }
         finally {
             anchor.free();
@@ -1371,7 +1558,7 @@ export class Multisig {
                 throw new Error(`Transaction executed successfully but failed to register on new GUARDIAN: ${message}`);
             }
         }
-        proposal.status = 'finalized';
+        this.proposals.set(proposal.id, { ...proposal, status: 'finalized' });
     }
     /**
      * Submit an integration-built transaction (advice already injected). Mirrors
@@ -1482,8 +1669,24 @@ export class Multisig {
         if (derivedCommitmentHex !== signedCommitmentHex) {
             throw new Error(`Custom proposal binding mismatch: expected ${signedCommitmentHex}, got ${derivedCommitmentHex}`);
         }
+        await this.assertApprovalNotExpired(proposalId, txSummary);
         return this.assembleCustomAdvice(proposalId, signaturesForExecution, signedCommitmentHex, delta);
     }
+    buildCosignerAdviceEntry(cosignerSig, signerCommitment, txCommitmentHex) {
+        const approval = cosignerSig.signature;
+        const txCommitment = Word.fromHex(txCommitmentHex);
+        if (approval.scheme === 'ecdsa' && approval.messageFormat === 'eip712') {
+            if (!approval.publicKey) {
+                throw new Error(`ECDSA proposal signature for ${cosignerSig.signerId} is missing publicKey`);
+            }
+            return buildEip712SignatureAdviceEntry(signerCommitment, txCommitment, approval.signature, approval.publicKey);
+        }
+        const signature = Signature.deserialize(signatureHexToBytes(approval.signature, approval.scheme));
+        if (approval.scheme === 'ecdsa' && approval.publicKey) {
+            assertEcdsaSignatureRecoverable(approval.signature, txCommitmentHex, approval.publicKey);
+        }
+        return buildSignatureAdviceEntry(signerCommitment, txCommitment, signature);
+    }
     async assembleCustomAdvice(proposalId, signaturesForExecution, normalizedTxCommitmentHex, delta) {
         const normalizedSignerCommitments = new Set(this.signerCommitments.map((commitment) => normalizeHexWord(commitment)));
         const adviceMap = new AdviceMap();
@@ -1505,12 +1708,7 @@ export class Multisig {
                 }
             }
             const signerCommitment = Word.fromHex(signerCommitmentHex);
-            const sigBytes = signatureHexToBytes(cosignerSig.signature.signature, cosignerSig.signature.scheme);
-            const signature = Signature.deserialize(sigBytes);
-            if (cosignerSig.signature.scheme === 'ecdsa' && ecdsaPublicKey) {
-                assertEcdsaSignatureRecoverable(cosignerSig.signature.signature, normalizedTxCommitmentHex, ecdsaPublicKey);
-            }
-            const { key, values } = buildSignatureAdviceEntry(signerCommitment, createTxCommitmentWord(), signature);
+            const { key, values } = this.buildCosignerAdviceEntry(cosignerSig, signerCommitment, normalizedTxCommitmentHex);
             const keyHex = normalizeHexWord(key.toHex());
             if (adviceMapKeys.has(keyHex)) {
                 throw new Error(`Duplicate advice-map key detected for proposal ${proposalId}`);
@@ -1554,6 +1752,10 @@ export class Multisig {
         const normalizedProposalId = normalizeHexWord(proposalId);
         return this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
     }
+    /**
+     * The returned `anchor` is the block the request has to execute at; the
+     * caller owns it and frees it once submitted.
+     */
     async prepareProposalExecution(proposalId) {
         const proposal = this.getLocalProposal(proposalId);
         if (!proposal) {
@@ -1601,6 +1803,7 @@ export class Multisig {
             throw new Error(`Proposal ${proposalId} tx_summary commitment ${normalizedTxCommitmentHex} ` +
                 'does not match the proposal id it belongs to');
         }
+        await this.assertApprovalNotExpired(proposalId, txSummary);
         const normalizedSignerCommitments = new Set(this.signerCommitments.map((commitment) => normalizeHexWord(commitment)));
         const adviceMap = new AdviceMap();
         const adviceMapKeys = new Set();
@@ -1623,12 +1826,7 @@ export class Multisig {
                 }
             }
             const signerCommitment = Word.fromHex(signerCommitmentHex);
-            const sigBytes = signatureHexToBytes(cosignerSig.signature.signature, cosignerSig.signature.scheme);
-            const signature = Signature.deserialize(sigBytes);
-            if (cosignerSig.signature.scheme === 'ecdsa' && ecdsaPublicKey) {
-                assertEcdsaSignatureRecoverable(cosignerSig.signature.signature, normalizedTxCommitmentHex, ecdsaPublicKey);
-            }
-            const { key, values } = buildSignatureAdviceEntry(signerCommitment, createTxCommitmentWord(), signature);
+            const { key, values } = this.buildCosignerAdviceEntry(cosignerSig, signerCommitment, normalizedTxCommitmentHex);
             const keyHex = normalizeHexWord(key.toHex());
             if (adviceMapKeys.has(keyHex)) {
                 throw new Error(`Duplicate advice-map key detected for proposal ${proposalId}`);
@@ -1674,17 +1872,15 @@ 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));
-        let finalRequest;
+        const anchor = this.requireProposalAnchor(proposalId, metadata);
         try {
-            finalRequest = await this.buildTransactionRequestFromMetadata(metadata, executionSalt, adviceMap);
+            const finalRequest = await this.buildTransactionRequestFromMetadata(metadata, proposalRequestBinding(txSummary, anchor, saltHex), adviceMap);
+            return { finalRequest, metadata, proposal, anchor };
         }
-        finally {
-            executionSalt.free?.();
+        catch (error) {
+            anchor.free();
+            throw error;
         }
-        return { finalRequest, metadata, proposal };
     }
     /**
      * Export a proposal for offline signing
@@ -1699,6 +1895,8 @@ export class Multisig {
                 signatureHex: s.signature.signature,
                 scheme: s.signature.scheme,
                 publicKey: s.signature.scheme === 'ecdsa' ? s.signature.publicKey : undefined,
+                ...(s.signature.scheme === 'ecdsa' && s.signature.messageFormat
+                    ? { messageFormat: s.signature.messageFormat } : {}),
                 timestamp: s.timestamp,
             }))
             : [];
@@ -1732,6 +1930,8 @@ export class Multisig {
                 signatureHex: s.signature.signature,
                 scheme: s.signature.scheme,
                 publicKey: s.signature.scheme === 'ecdsa' ? s.signature.publicKey : undefined,
+                ...(s.signature.scheme === 'ecdsa' && s.signature.messageFormat
+                    ? { messageFormat: s.signature.messageFormat } : {}),
                 timestamp: s.timestamp,
             })),
             metadata: proposal.metadata,
@@ -1795,13 +1995,17 @@ export class Multisig {
             },
         ];
         const canonicalizedSignatures = new ProposalSignatures(signatures, this.signerCommitments, localSignatureContext).entries();
-        proposal.signatures = canonicalizedSignatures;
-        // Update status
         const proposalType = proposal.metadata?.proposalType;
         const signaturesRequired = proposalType
             ? this.getEffectiveThreshold(proposalType)
             : this.threshold;
-        proposal.status = proposal.signatures.length >= signaturesRequired ? 'ready' : 'pending';
+        // A fresh object rather than an in-place write: a sync that snapshotted
+        // the cache before this signature tells the two apart by identity.
+        this.proposals.set(proposal.id, {
+            ...proposal,
+            signatures: canonicalizedSignatures,
+            status: canonicalizedSignatures.length >= signaturesRequired ? 'ready' : 'pending',
+        });
         // Return updated JSON
         return this.exportProposalToJson(proposal.id);
     }
@@ -1813,7 +2017,29 @@ export class Multisig {
         }
         return txSummaryCommitment;
     }
+    /**
+     * Verifies that a proposal's metadata reconstructs its signed summary
+     * commitment and records the outcome in {@link Proposal.verification}:
+     * `verified`, or `failed` with the message and whether the failure looked
+     * transient. Rethrows the failure so strict callers keep failing closed
+     * while `syncProposals` keeps going with the outcome recorded.
+     */
     async verifyProposalMetadataBinding(proposal) {
+        try {
+            const commitment = await this.checkProposalMetadataBinding(proposal);
+            proposal.verification = { status: 'verified' };
+            return commitment;
+        }
+        catch (error) {
+            proposal.verification = {
+                status: 'failed',
+                retryable: isTransientRpcError(error),
+                message: error instanceof Error ? error.message : String(error),
+            };
+            throw error;
+        }
+    }
+    async checkProposalMetadataBinding(proposal) {
         const txSummaryCommitment = this.ensureProposalCommitmentMatchesSummary(proposal);
         const summary = TransactionSummary.deserialize(base64ToUint8Array(proposal.txSummary));
         // The anchor arrives from an untrusted party via GUARDIAN, so check its
@@ -1833,13 +2059,28 @@ export class Multisig {
                 // integrity guarantee for an opaque proposal.
                 return txSummaryCommitment;
             }
+            // The salt check needs no re-execution, so it runs for every built-in
+            // type, switch_guardian included (as in the Rust SDK): a mismatched salt
+            // would otherwise collect signatures and only fail in the VM.
+            const binding = proposalRequestBinding(summary, anchor, this.requireProposalSaltHex(proposal.id, proposal.metadata));
+            if (summarySaltHex(summary) !== binding.saltHex) {
+                throw new Error(`Invalid proposal: metadata salt does not match the salt bound into the tx_summary for ${proposal.id}`);
+            }
             if (proposal.metadata.proposalType === 'switch_guardian') {
-                // Re-execution would mutate the WASM account twice. The proposal ID and
-                // guardian endpoint commitment provide the binding checks for this type.
+                // Re-execution would mutate the WASM account twice. The proposal ID,
+                // the salt above and the guardian endpoint commitment provide the
+                // binding checks for this type.
                 return txSummaryCommitment;
             }
-            const salt = Word.fromHex(normalizeHexWord(this.requireProposalSaltHex(proposal.id, proposal.metadata)));
-            const request = await this.buildTransactionRequestFromMetadata(proposal.metadata, salt);
+            // A consume-notes summary commits to *authenticated* consumption (see
+            // ensureNotesAuthenticated), which miden-client decides from this store
+            // alone. Put the store in that mode before the rebuild, or a cosigner
+            // that never held these notes reproduces a different commitment.
+            if (proposal.metadata.proposalType === 'consume_notes' &&
+                proposal.metadata.metadataVersion === CONSUME_NOTES_METADATA_VERSION_V2) {
+                await this.ensureNotesAuthenticated(decodeEmbeddedConsumeNotes(proposal.metadata));
+            }
+            const request = await this.buildTransactionRequestFromMetadata(proposal.metadata, binding);
             const webClient = await this.getRawClient();
             const reconstructed = await executeForSummaryAt(webClient, this._accountId, request, anchor);
             const reconstructedCommitment = normalizeHexWord(reconstructed.toCommitment().toHex());
@@ -1862,22 +2103,17 @@ export class Multisig {
      * 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.
+     * The salt goes into the request's multisig auth args and the summary binds it in
+     * its user params, so `summarySalt(summary)` reads the value the cosigners signed
+     * over. It is not a substitute for this field: a request has to be rebuilt before
+     * any summary exists, and a proposal GUARDIAN serves may pair a summary with
+     * metadata that names another salt, which the binding check reports by name.
      */
     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');
+            throw new Error(`Proposal ${proposalId} has no salt; its request cannot be rebuilt without the ` +
+                'salt its auth args and signed summary bind');
         }
         // GUARDIAN serves this field and the response is cast, not parsed, so everything
         // below is untrusted input. A truthiness test is not enough: `normalizeHexWord`
@@ -1912,46 +2148,68 @@ export class Multisig {
         }
         return chainAnchorFromBase64(metadata.chainAnchor);
     }
-    async buildTransactionRequestFromMetadata(metadata, salt, signatureAdviceMap) {
+    /**
+     * An expired approval aborts in the auth procedure only at execution.
+     * The summary carries the deadline, so callers check it against the sync
+     * height before assembling advice or requesting the GUARDIAN ack.
+     */
+    async assertApprovalNotExpired(proposalId, summary) {
+        const expirationBlockNum = summaryApprovalExpirationBlockNum(summary);
+        if (expirationBlockNum === undefined) {
+            return;
+        }
+        const webClient = await this.getRawClient();
+        const syncHeight = await webClient.getSyncHeight();
+        if (syncHeight >= expirationBlockNum) {
+            throw new Error(`Proposal ${proposalId} approval expired at block ${expirationBlockNum}; the chain is at ` +
+                `block ${syncHeight}, so the collected signatures no longer authorize it`);
+        }
+    }
+    /**
+     * Rebuilds a proposal's request from its metadata under `binding`, so the
+     * summary it produces is the one the cosigners signed.
+     */
+    async buildTransactionRequestFromMetadata(metadata, binding, signatureAdviceMap) {
+        // The builders read `.toHex()` and allocate their own Word, so this handle
+        // stays ours; without the release it leaks once per rebuild.
+        const salt = Word.fromHex(binding.saltHex);
+        try {
+            return await this.buildTransactionRequestWithOptions(metadata, {
+                accountId: this._accountId,
+                boundBlockNum: binding.boundBlockNum,
+                approvalExpirationDelta: binding.approvalExpirationDelta,
+                salt,
+                signatureAdviceMap,
+                signatureScheme: this.signer.scheme,
+            });
+        }
+        finally {
+            salt.free?.();
+        }
+    }
+    async buildTransactionRequestWithOptions(metadata, requestOptions) {
         const webClient = await this.getRawClient();
         switch (metadata.proposalType) {
             case 'add_signer':
             case 'remove_signer':
             case 'change_threshold': {
-                const { request } = await buildUpdateSignersTransactionRequest(webClient, metadata.targetThreshold, metadata.targetSignerCommitments, { salt, signatureAdviceMap, signatureScheme: this.signer.scheme });
+                const { request } = await buildUpdateSignersTransactionRequest(webClient, metadata.targetThreshold, metadata.targetSignerCommitments, requestOptions);
                 return request;
             }
             case 'switch_guardian': {
-                const { request } = await buildUpdateGuardianTransactionRequest(webClient, metadata.newGuardianPubkey, { salt, signatureAdviceMap, signatureScheme: this.signer.scheme });
+                const { request } = await buildUpdateGuardianTransactionRequest(webClient, metadata.newGuardianPubkey, requestOptions);
                 return request;
             }
             case 'update_procedure_threshold': {
-                const { request } = await buildUpdateProcedureThresholdTransactionRequest(webClient, metadata.targetProcedure, metadata.targetThreshold, { salt, signatureAdviceMap, signatureScheme: this.signer.scheme });
+                const { request } = await buildUpdateProcedureThresholdTransactionRequest(webClient, metadata.targetProcedure, metadata.targetThreshold, requestOptions);
                 return request;
             }
             case 'consume_notes': {
                 // v1/v2 dispatch for issue #229 / FR-009.
                 const version = metadata.metadataVersion;
                 if (version === CONSUME_NOTES_METADATA_VERSION_V2) {
-                    const embedded = metadata.notes ?? [];
-                    if (embedded.length !== metadata.noteIds.length) {
-                        throw new NoteBindingMismatchError(`consume_notes v2: notes.length=${embedded.length} does not match noteIds.length=${metadata.noteIds.length}`);
-                    }
-                    const decoded = [];
-                    for (let i = 0; i < embedded.length; i++) {
-                        const note = noteFromBase64(embedded[i], Note);
-                        // Normalize both sides; matches the file's other hex comparisons.
-                        const embeddedId = normalizeHexWord(note.id().toString());
-                        const declaredId = normalizeHexWord(metadata.noteIds[i]);
-                        if (embeddedId !== declaredId) {
-                            throw new NoteBindingMismatchError(`consume_notes v2: notes[${i}] id ${embeddedId} != noteIds[${i}] ${declaredId}`);
-                        }
-                        decoded.push(note);
-                    }
-                    const { request } = buildConsumeNotesTransactionRequestFromNotes(decoded, {
-                        salt,
-                        signatureAdviceMap,
-                    });
+                    const decoded = decodeEmbeddedConsumeNotes(metadata);
+                    const { request } = await buildConsumeNotesTransactionRequestFromNotes(webClient, decoded, requestOptions);
                     return request;
                 }
                 if (version === undefined || version === 1) {
@@ -1960,15 +2218,14 @@ export class Multisig {
                         // operator which legacy shape was rejected.
                         throw new UnsupportedMetadataVersionError(version);
                     }
-                    const { request } = await buildConsumeNotesTransactionRequest(webClient, metadata.noteIds, { salt, signatureAdviceMap });
+                    const { request } = await buildConsumeNotesTransactionRequest(webClient, metadata.noteIds, requestOptions);
                     return request;
                 }
                 throw new UnsupportedMetadataVersionError(version);
             }
             case 'p2id': {
-                const { request } = buildP2idTransactionRequest(this._accountId, metadata.recipientId, metadata.faucetId, BigInt(metadata.amount), {
-                    salt,
-                    signatureAdviceMap,
+                const { request } = await buildP2idTransactionRequest(webClient, this._accountId, metadata.recipientId, metadata.faucetId, BigInt(metadata.amount), {
+                    ...requestOptions,
                     noteType: parseP2idNoteType(metadata.noteType),
                     reclaimHeight: metadata.reclaimHeight,
                     timelockHeight: metadata.timelockHeight,
@@ -1980,4 +2237,27 @@ export class Multisig {
         }
     }
 }
+/**
+ * Decodes a v2 `consume_notes` proposal's embedded notes, asserting each one
+ * is the note its declared id names (spec 006 FR-007).
+ */
+function decodeEmbeddedConsumeNotes(metadata) {
+    const embedded = metadata.notes ?? [];
+    const noteIds = metadata.noteIds ?? [];
+    if (embedded.length !== noteIds.length) {
+        throw new NoteBindingMismatchError(`consume_notes v2: notes.length=${embedded.length} does not match noteIds.length=${noteIds.length}`);
+    }
+    const decoded = [];
+    for (let i = 0; i < embedded.length; i++) {
+        const note = noteFromBase64(embedded[i], Note);
+        // Normalize both sides; matches the file's other hex comparisons.
+        const embeddedId = normalizeHexWord(note.id().toString());
+        const declaredId = normalizeHexWord(noteIds[i]);
+        if (embeddedId !== declaredId) {
+            throw new NoteBindingMismatchError(`consume_notes v2: notes[${i}] id ${embeddedId} != noteIds[${i}] ${declaredId}`);
+        }
+        decoded.push(note);
+    }
+    return decoded;
+}
 //# sourceMappingURL=multisig.js.map