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

package/src/multisig.ts

@@ -27,6 +27,7 @@ import {
   AccountId,
   AdviceMap,
   Endpoint,
+  type Felt,
   FeltArray,
   Note,
   NoteExportFormat,
@@ -44,6 +45,8 @@ import {
   chainAnchorToBase64,
   executeForSummary,
   executeForSummaryAt,
+  summaryApprovalExpirationBlockNum,
+  summarySalt,
   buildUpdateSignersTransactionRequest,
   buildUpdateProcedureThresholdTransactionRequest,
   buildUpdateGuardianTransactionRequest,
@@ -55,9 +58,13 @@ import {
   type P2ideHeightOptions,
 } from './transaction.js';
 import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
+import type { MultisigRequestOptions } from './transaction/options.js';
+import { validateMultisigConfig } from './account/builder.js';
+import { ensureNotesAuthenticated } from './transaction/noteAuthentication.js';
 import {
   CONSUME_NOTES_METADATA_VERSION_V2,
   MAX_CONSUME_NOTES_METADATA_BYTES,
+  type ConsumeNotesProposalMetadata,
 } from './types/proposal.js';
 import { LEGACY_CONSUME_NOTES_ENABLED } from './multisig/config.js';
 import {
@@ -74,6 +81,7 @@ import {
 } from './utils/encoding.js';
 import {
   assertEcdsaSignatureRecoverable,
+  buildEip712SignatureAdviceEntry,
   buildSignatureAdviceEntry,
   normalizeSignerCommitment,
   signatureHexToBytes,
@@ -116,7 +124,9 @@ import {
   resolveRpcConfig,
   type ResolvedRpcConfig,
 } from './rpc/config.js';
+import { isTransientRpcError } from './rpc/errors.js';
 import { retryRpcRead } from './rpc/retry.js';
+import { isSafeToAdoptGuardianState, readOnChainCommitment } from './state/adopt.js';
 
 /**
  * Result of fetching account state from GUARDIAN.
@@ -146,6 +156,13 @@ export interface AccountStateVerificationResult {
 export interface CreateProposalOptions {
   /** Proposal nonce; defaults to `Date.now()`. */
   nonce?: number;
+  /**
+   * Blocks after the proposal's anchor block by which the transaction must be
+   * included; past that the approvers' signatures no longer authorize it. The
+   * summary binds it, so the executing party can neither shorten nor extend it.
+   * Omitted, the approval never expires (the upstream default).
+   */
+  approvalExpirationDelta?: number;
 }
 
 export interface CreateSignerProposalOptions extends CreateProposalOptions {
@@ -211,6 +228,64 @@ function resolveProposalNonce(
   return options.nonce ?? Date.now();
 }
 
+/**
+ * What a rebuild of a proposal's request pins so the signed summary
+ * reproduces: the salt, the block its anchor names, and the approval
+ * expiration the summary binds, as the delta the builders take.
+ */
+interface ProposalRequestBinding {
+  saltHex: string;
+  boundBlockNum: number;
+  approvalExpirationDelta: number | undefined;
+}
+
+function proposalRequestBinding(
+  summary: TransactionSummary,
+  anchor: ChainAnchor,
+  saltHex: string,
+): ProposalRequestBinding {
+  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: number | undefined,
+  boundBlockNum: number,
+): number | undefined {
+  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: TransactionSummary): string {
+  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
@@ -231,6 +306,13 @@ 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: Account;
   threshold: number;
@@ -248,6 +330,24 @@ export class Multisig {
   private readonly _accountId: string;
   private readonly midenRpcEndpoint: string;
   private proposals: Map<string, Proposal> = new Map();
+  /** Ids GUARDIAN returned on the most recent sync; these prune immediately when dropped. */
+  private lastReportedProposalIds: Set<string> = 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.
+   */
+  private guardianKnownProposalIds: Set<string> = new Set();
+  /**
+   * Consecutive successful listings that omitted a guardian-known proposal
+   * not yet listed; at {@link UNREPORTED_LISTING_MISS_LIMIT} it is pruned.
+   */
+  private unreportedMissCounts: Map<string, number> = new Map();
+  /** Bumped by {@link setGuardianClient}; a sync spanning a bump aborts unapplied. */
+  private syncGeneration = 0;
+  /** Pending sync shared by overlapping {@link syncProposals} callers. */
+  private syncProposalsInFlight?: Promise<Proposal[]>;
 
   constructor(
     account: Account,
@@ -435,6 +535,20 @@ export class Multisig {
     }));
   }
 
+  /**
+   * The request options every `create*Proposal` hands its builder: the account,
+   * the caller's approval expiration, and the signer's scheme.
+   */
+  private proposalRequestOptions(options: {
+    approvalExpirationDelta?: number;
+  }): Pick<MultisigRequestOptions, 'accountId' | 'approvalExpirationDelta' | 'signatureScheme'> {
+    return {
+      accountId: this._accountId,
+      approvalExpirationDelta: options.approvalExpirationDelta,
+      signatureScheme: this.signer.scheme,
+    };
+  }
+
   private warnOnOverrideDilution(newNumSigners: number): void {
     const current = this.signerCommitments.length;
     for (const { procedure, threshold } of this.overridesDilutedBySignerGrowth(newNumSigners)) {
@@ -454,11 +568,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: GuardianHttpClient): void {
     this.guardian = guardianClient;
     this.guardian.setSigner(this.signer);
+    this.syncGeneration += 1;
+    this.syncProposalsInFlight = undefined;
+    this.lastReportedProposalIds = new Set();
+    this.unreportedMissCounts = new Map();
   }
 
   /**
@@ -573,66 +699,16 @@ export class Multisig {
     incomingAccount: Account,
     localAccount?: Account,
   ): Promise<boolean> {
-    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)),
+    });
   }
 
   private async getOnChainCommitment(accountId: AccountId): Promise<string | null> {
-    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);
   }
 
   /**
@@ -715,12 +791,67 @@ 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(): Promise<Proposal[]> {
+  syncProposals(): Promise<Proposal[]> {
+    if (this.syncProposalsInFlight) {
+      return this.syncProposalsInFlight;
+    }
+    const inFlight = this.reconcileProposals().finally(() => {
+      if (this.syncProposalsInFlight === inFlight) {
+        this.syncProposalsInFlight = undefined;
+      }
+    });
+    this.syncProposalsInFlight = inFlight;
+    return inFlight;
+  }
+
+  private async reconcileProposals(): Promise<Proposal[]> {
+    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<string, { delta: (typeof deltas)[number]; verified: Proposal }>();
     for (const delta of deltas) {
       const proposalId = normalizeHexWord(
         computeCommitmentFromTxSummary(delta.deltaPayload.txSummary.data)
@@ -732,10 +863,62 @@ export class Multisig {
         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: Proposal[] = [];
+    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<string, number>();
+    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());
   }
@@ -802,7 +985,10 @@ export class Multisig {
   }
 
   /**
-   * 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(): Proposal[] {
     return Array.from(this.proposals.values());
@@ -831,6 +1017,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;
   }
@@ -851,13 +1038,21 @@ 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 },
+      this.proposalRequestOptions(options),
     );
 
     const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
@@ -916,7 +1111,7 @@ export class Multisig {
       webClient,
       targetThreshold,
       targetSignerCommitments,
-      { signatureScheme: this.signer.scheme },
+      this.proposalRequestOptions(options),
     );
 
     const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
@@ -963,7 +1158,7 @@ export class Multisig {
       webClient,
       newThreshold,
       this.signerCommitments,
-      { signatureScheme: this.signer.scheme },
+      this.proposalRequestOptions(options),
     );
 
     const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
@@ -1012,7 +1207,7 @@ export class Multisig {
       webClient,
       targetProcedure,
       targetThreshold,
-      { signatureScheme: this.signer.scheme },
+      this.proposalRequestOptions(options),
     );
 
     const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
@@ -1052,6 +1247,7 @@ export class Multisig {
     const { summaryBase64, metadata } = await this.buildSwitchGuardianSummary(
       newGuardianEndpoint,
       newGuardianPubkey,
+      options.approvalExpirationDelta,
     );
 
     // SwitchGuardian is a regular delta proposal; push it to GUARDIAN so
@@ -1069,14 +1265,26 @@ export class Multisig {
   private async buildSwitchGuardianSummary(
     newGuardianEndpoint: string,
     newGuardianPubkey: string,
+    approvalExpirationDelta: number | undefined,
   ): Promise<{ summaryBase64: string; metadata: ProposalMetadata }> {
     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 },
+      {
+        accountId: this._accountId,
+        approvalExpirationDelta,
+        signatureScheme: this.signer.scheme,
+      },
     );
 
     const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
@@ -1139,6 +1347,7 @@ export class Multisig {
     const { summaryBase64, metadata } = await this.buildSwitchGuardianSummary(
       newGuardianEndpoint,
       newGuardianPubkey,
+      options.approvalExpirationDelta,
     );
 
     const exported: ExportedProposal = {
@@ -1184,9 +1393,17 @@ 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);
@@ -1243,7 +1460,8 @@ 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(
+    const { request, salt } = await buildP2idTransactionRequest(
+      webClient,
       this._accountId,
       recipientId,
       faucetId,
@@ -1441,6 +1659,18 @@ 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}.
+   */
+  private async ensureNotesAuthenticated(notes: readonly Note[]): Promise<void> {
+    await ensureNotesAuthenticated(this.midenClient, notes, {
+      midenRpcEndpoint: this.getMidenRpcEndpoint(),
+      rpc: { retry: { maxAttempts: this.rpcConfig.maxAttempts } },
+    });
+  }
+
   private async importNotesFromProposals(
     proposals: ReadonlyArray<Pick<Proposal, 'id' | 'metadata'>>,
     cancelled?: () => boolean,
@@ -1771,6 +2001,7 @@ export class Multisig {
     await this.verifyProposalMetadataBinding(signedProposal);
 
     this.proposals.set(signedProposal.id, signedProposal);
+    this.guardianKnownProposalIds.add(signedProposal.id);
 
     return signedProposal;
   }
@@ -1789,7 +2020,8 @@ export class Multisig {
   }
 
   async createTransactionProposalRequest(proposalId: string): Promise<TransactionRequest> {
-    const { finalRequest } = await this.prepareProposalExecution(proposalId);
+    const { finalRequest, anchor } = await this.prepareProposalExecution(proposalId);
+    anchor.free();
     return finalRequest;
   }
 
@@ -1799,22 +2031,21 @@ export class Multisig {
    * @param proposalId - The proposal commitment/ID
    */
   async executeProposal(proposalId: string): Promise<void> {
-    const { metadata, finalRequest, proposal } = await this.prepareProposalExecution(proposalId);
+    const { metadata, finalRequest, proposal, anchor } =
+      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);
     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();
     }
@@ -1871,7 +2102,7 @@ export class Multisig {
       }
     }
 
-    proposal.status = 'finalized';
+    this.proposals.set(proposal.id, { ...proposal, status: 'finalized' });
   }
 
   /**
@@ -2033,6 +2264,8 @@ export class Multisig {
       );
     }
 
+    await this.assertApprovalNotExpired(proposalId, txSummary);
+
     return this.assembleCustomAdvice(
       proposalId,
       signaturesForExecution,
@@ -2041,6 +2274,34 @@ export class Multisig {
     );
   }
 
+  private buildCosignerAdviceEntry(
+    cosignerSig: ProposalSignatureEntry,
+    signerCommitment: Word,
+    txCommitmentHex: string,
+  ): { key: Word; values: Felt[] } {
+    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);
+  }
+
   private async assembleCustomAdvice(
     proposalId: string,
     signaturesForExecution: ProposalSignatureEntry[],
@@ -2077,22 +2338,8 @@ 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)) {
@@ -2148,9 +2395,16 @@ export class Multisig {
     return this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
   }
 
-  private async prepareProposalExecution(
-    proposalId: string,
-  ): Promise<{ finalRequest: TransactionRequest; metadata: ProposalMetadata; proposal: Proposal }> {
+  /**
+   * The returned `anchor` is the block the request has to execute at; the
+   * caller owns it and frees it once submitted.
+   */
+  private async prepareProposalExecution(proposalId: string): Promise<{
+    finalRequest: TransactionRequest;
+    metadata: ProposalMetadata;
+    proposal: Proposal;
+    anchor: ChainAnchor;
+  }> {
     const proposal = this.getLocalProposal(proposalId);
     if (!proposal) {
       throw new Error(`Proposal not found: ${proposalId}`);
@@ -2213,6 +2467,8 @@ export class Multisig {
       );
     }
 
+    await this.assertApprovalNotExpired(proposalId, txSummary);
+
     const normalizedSignerCommitments = new Set(
       this.signerCommitments.map((commitment) => normalizeHexWord(commitment)),
     );
@@ -2246,22 +2502,8 @@ 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)) {
@@ -2317,17 +2559,18 @@ 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));
-    let finalRequest;
+    const anchor = this.requireProposalAnchor(proposalId, metadata);
     try {
-      finalRequest = await this.buildTransactionRequestFromMetadata(metadata, executionSalt, adviceMap);
-    } finally {
-      executionSalt.free?.();
+      const finalRequest = await this.buildTransactionRequestFromMetadata(
+        metadata,
+        proposalRequestBinding(txSummary, anchor, saltHex),
+        adviceMap,
+      );
+      return { finalRequest, metadata, proposal, anchor };
+    } catch (error) {
+      anchor.free();
+      throw error;
     }
-
-    return { finalRequest, metadata, proposal };
   }
 
   /**
@@ -2350,6 +2593,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,
           }))
         : [];
@@ -2386,6 +2631,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,
@@ -2467,14 +2714,17 @@ export class Multisig {
       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);
@@ -2493,7 +2743,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.
+   */
   private async verifyProposalMetadataBinding(proposal: Proposal): Promise<string> {
+    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;
+    }
+  }
+
+  private async checkProposalMetadataBinding(proposal: Proposal): Promise<string> {
     const txSummaryCommitment = this.ensureProposalCommitmentMatchesSummary(proposal);
 
     const summary = TransactionSummary.deserialize(base64ToUint8Array(proposal.txSummary));
@@ -2519,17 +2791,39 @@ export class Multisig {
         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)),
-      );
+      // 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, salt);
+      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());
@@ -2554,24 +2848,19 @@ 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.
    */
   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',
+        `Proposal ${proposalId} has no salt; its request cannot be rebuilt without the ` +
+          'salt its auth args and signed summary bind',
       );
     }
 
@@ -2614,13 +2903,60 @@ export class Multisig {
     return chainAnchorFromBase64(metadata.chainAnchor);
   }
 
+  /**
+   * 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.
+   */
+  private async assertApprovalNotExpired(
+    proposalId: string,
+    summary: TransactionSummary,
+  ): Promise<void> {
+    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.
+   */
   private async buildTransactionRequestFromMetadata(
     metadata: ProposalMetadata,
-    salt: Word,
+    binding: ProposalRequestBinding,
     signatureAdviceMap?: AdviceMap,
   ): Promise<TransactionRequest> {
-    const webClient = await this.getRawClient();
+    // 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?.();
+    }
+  }
 
+  private async buildTransactionRequestWithOptions(
+    metadata: ProposalMetadata,
+    requestOptions: MultisigRequestOptions,
+  ): Promise<TransactionRequest> {
+    const webClient = await this.getRawClient();
     switch (metadata.proposalType) {
       case 'add_signer':
       case 'remove_signer':
@@ -2629,7 +2965,7 @@ export class Multisig {
           webClient,
           metadata.targetThreshold,
           metadata.targetSignerCommitments,
-          { salt, signatureAdviceMap, signatureScheme: this.signer.scheme }
+          requestOptions,
         );
         return request;
       }
@@ -2637,7 +2973,7 @@ export class Multisig {
         const { request } = await buildUpdateGuardianTransactionRequest(
           webClient,
           metadata.newGuardianPubkey,
-          { salt, signatureAdviceMap, signatureScheme: this.signer.scheme }
+          requestOptions,
         );
         return request;
       }
@@ -2646,7 +2982,7 @@ export class Multisig {
           webClient,
           metadata.targetProcedure,
           metadata.targetThreshold,
-          { salt, signatureAdviceMap, signatureScheme: this.signer.scheme }
+          requestOptions,
         );
         return request;
       }
@@ -2654,29 +2990,12 @@ export class Multisig {
         // 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: Note[] = [];
-          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) {
@@ -2688,25 +3007,25 @@ export class Multisig {
           const { request } = await buildConsumeNotesTransactionRequest(
             webClient,
             metadata.noteIds,
-            { salt, signatureAdviceMap },
+            requestOptions,
           );
           return request;
         }
         throw new UnsupportedMetadataVersionError(version);
       }
       case 'p2id': {
-        const { request } = buildP2idTransactionRequest(
+        const { request } = await buildP2idTransactionRequest(
+          webClient,
           this._accountId,
           metadata.recipientId,
           metadata.faucetId,
           BigInt(metadata.amount),
           {
-            salt,
-            signatureAdviceMap,
+            ...requestOptions,
             noteType: parseP2idNoteType(metadata.noteType),
             reclaimHeight: metadata.reclaimHeight,
             timelockHeight: metadata.timelockHeight,
-          }
+          },
         );
         return request;
       }
@@ -2718,3 +3037,31 @@ 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: ConsumeNotesProposalMetadata): Note[] {
+  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: Note[] = [];
+  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;
+}