@openzeppelin/miden-multisig-client 0.18.0 → 0.18.2

package/dist/multisig.js

@@ -4,10 +4,10 @@
  * This class wraps a Miden SDK Account and provides GUARDIAN integration
  * for proposal management.
  */
-import { GuardianHttpClient } from '@openzeppelin/guardian-client';
-import { ProposalSaltMalformedError } from './multisig/authArgErrors.js';
+import { GuardianHttpClient, GuardianHttpError } from '@openzeppelin/guardian-client';
+import { BoundBlockMismatchError, ProposalSaltMalformedError } from './multisig/authArgErrors.js';
 import { Account, AccountId, AdviceMap, FeltArray, Note, NoteExportFormat, NoteFile, Signature, TransactionRequest, TransactionSummary, Word, } from '@miden-sdk/miden-sdk';
-import { chainAnchorFromBase64, chainAnchorToBase64, executeForSummary, executeForSummaryAtTip, isStaleChainError, prepareTipExecution, syncToBoundBlock, summaryApprovalExpirationBlockNum, summarySalt, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
+import { executeForSummaryAtTip, isStaleChainError, prepareTipExecution, syncToBoundBlock, summaryApprovalExpirationBlockNum, summaryBoundBlockNum, 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';
@@ -63,21 +63,18 @@ function deserializeTransactionRequest(bytes) {
     }
 }
 /**
- * Single home for the proposal-nonce default, plus a runtime guard for
- * pre-#387 positional callers. Untyped JS passing the old `nonce` number (or
- * a legacy trailing argument) would otherwise bind it as the options bag and
- * silently fall back to every default — a public note instead of a private
- * one, or the current threshold instead of the requested one — so it must
- * fail loudly instead.
+ * Runtime guard for pre-#387 positional callers. Untyped JS passing the old
+ * `nonce` number (or a legacy trailing argument) would otherwise bind it as
+ * the options bag and silently fall back to every default — a public note
+ * instead of a private one, or the current threshold instead of the
+ * requested one — so it must fail loudly instead.
  */
-function resolveProposalNonce(method, options, legacyArgs = []) {
+function assertProposalOptionsBag(method, options, legacyArgs = []) {
     if (typeof options !== 'object' || options === null || legacyArgs.length > 0) {
         throw new Error(`${method}: positional optional parameters were replaced by a trailing options object (issue #387); pass { nonce, ... } instead`);
     }
-    return options.nonce ?? Date.now();
 }
-function proposalRequestBinding(summary, anchor, saltHex) {
-    const boundBlockNum = anchor.blockNum();
+function proposalRequestBinding(summary, boundBlockNum, saltHex) {
     return {
         saltHex: normalizeHexWord(saltHex),
         boundBlockNum,
@@ -125,6 +122,8 @@ 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;
+/** Block numbers are `u32` on chain. */
+const MAX_BLOCK_NUM = 0xffff_ffff;
 /**
  * Consecutive successful listings that must omit a guardian-known proposal
  * not yet listed (a fresh create during read-your-writes lag, or one
@@ -223,6 +222,55 @@ export class Multisig {
     readStoreAccount() {
         return retryRpcRead(() => this.midenClient.accounts.get(this._accountId), this.rpcConfig);
     }
+    /**
+     * The nonce a proposal is labelled with: `options.nonce`, or the store
+     * account's nonce plus one, the nonce the executed transaction will
+     * have. That is what the Rust SDK labels with, what the stale-proposal
+     * filters compare with the account nonce, and what GUARDIAN's candidate
+     * queue requires of a proposal built on its tail (issue #17). Through
+     * 0.18.0 the default was `Date.now()`, a key no admission rule
+     * could relate to the account's state. The label is read after any sync
+     * the method performs (note authentication, the offline switch's node
+     * sync), on the account the summary is then built from; a caller that
+     * has just read that account passes it to save the store read.
+     */
+    async resolveProposalNonce(method, options, legacyArgs = [], account) {
+        assertProposalOptionsBag(method, options, legacyArgs);
+        if (options.nonce !== undefined && options.nonce !== null) {
+            return options.nonce;
+        }
+        const labelled = account ?? (await this.getStoreAccount());
+        const next = labelled.nonce().asInt() + 1n;
+        if (next > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new Error(`${method}: the account nonce ${next - 1n} is too large to label a proposal with as a number; pass options.nonce`);
+        }
+        return Number(next);
+    }
+    /**
+     * Refuses to execute a proposal GUARDIAN pinned to a state other than the
+     * one this client holds. The transaction executes on this client's own
+     * record of the account while the execution push names the pinned base,
+     * so the two have to be the same state. A proposal pinned to a state the
+     * account has since left was made for that state, and its transaction
+     * would otherwise run again on the current one. One pinned to a state this
+     * client does not hold (a server that queues chained candidates pins a
+     * proposal to the newest queued candidate's post-state) would be admitted
+     * behind that candidate while the transaction itself lands on the older
+     * state, leaving GUARDIAN behind the chain.
+     */
+    async assertExecutesOnPinnedBase(proposalId, pinnedBase) {
+        const local = await this.localAccountCommitment();
+        const pinned = normalizeHexWord(pinnedBase);
+        if (local !== pinned) {
+            throw new Error(`Proposal ${proposalId} was made for account state ${pinned}, but this client's account is at ${local}: ` +
+                'sync the account (syncState) and retry, or create a new proposal if the account has moved past that state');
+        }
+        return local;
+    }
+    /** The commitment of this client's record of the account. */
+    async localAccountCommitment() {
+        return normalizeHexWord((await this.getStoreAccount()).to_commitment().toHex());
+    }
     /**
      * Read the current ordered signer public-key commitments from account
      * storage (store-backed state, falling back to the snapshot).
@@ -319,6 +367,17 @@ export class Multisig {
             signatureScheme: this.signer.scheme,
         };
     }
+    /**
+     * Derives a new proposal's summary at the chain tip, with the block it binds
+     * for the proposal's `boundBlockNum`.
+     */
+    async deriveProposalSummary(request) {
+        const summary = await executeForSummaryAtTip(this.midenClient, this._accountId, request);
+        return {
+            summaryBase64: uint8ArrayToBase64(summary.serialize()),
+            boundBlockNum: summaryBoundBlockNum(summary),
+        };
+    }
     warnOnOverrideDilution(newNumSigners) {
         const current = this.signerCommitments.length;
         for (const { procedure, threshold } of this.overridesDilutedBySignerGrowth(newNumSigners)) {
@@ -582,10 +641,11 @@ export class Multisig {
      * 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
+     * `filterVisibleProposals`). This SDK labels a proposal with the account's
+     * next nonce by default, as the Rust SDK does, but a caller may label with
+     * its own `nonce` (and proposals made through 0.18.0 carry a
+     * timestamp), so the Rust client's `proposal.nonce <= account.nonce()`
+     * filter is not applied here. This is an intentional TS/Rust surface
      * difference.
      */
     syncProposals() {
@@ -617,8 +677,10 @@ export class Multisig {
             const existingProposal = this.proposals.get(proposalId);
             const proposal = factory.fromDelta(delta, proposalId, existingProposal?.metadata, existingProposal?.signatures ?? []);
             // The outcome lands on the proposal either way; a failure is reported
-            // there rather than failing the sync.
-            await this.verifyProposalMetadataBinding(proposal).catch(() => undefined);
+            // there rather than failing the sync. The chain was synced once above,
+            // so a bound block past that height stays a retryable failure until the
+            // next listing instead of costing a sync per proposal.
+            await this.verifyProposalMetadataBinding(proposal, async () => undefined).catch(() => undefined);
             reported.set(proposal.id, { delta, verified: proposal });
         }
         if (generation !== this.syncGeneration) {
@@ -690,6 +752,10 @@ export class Multisig {
         catch {
             currentNonce = undefined;
         }
+        // At most one chain sync for the whole listing, however many proposals
+        // bind a block above the store's sync height.
+        let listingSync;
+        const syncOnce = () => (listingSync ??= this.syncChain());
         const proposals = [];
         const skipped = [];
         for (let position = 0; position < deltas.length; position += 1) {
@@ -706,7 +772,7 @@ export class Multisig {
                 if (currentNonce !== undefined && BigInt(proposal.nonce) <= currentNonce) {
                     continue;
                 }
-                await this.verifyProposalMetadataBinding(proposal);
+                await this.verifyProposalMetadataBinding(proposal, syncOnce);
                 proposals.push(proposal);
             }
             catch (error) {
@@ -759,7 +825,7 @@ export class Multisig {
      *   current threshold)
      */
     async createAddSignerProposal(newCommitment, options = {}, ...legacyArgs) {
-        const proposalNonce = resolveProposalNonce('createAddSignerProposal', options, legacyArgs);
+        assertProposalOptionsBag('createAddSignerProposal', options, legacyArgs);
         const targetThreshold = options.newThreshold ?? this.threshold;
         const targetSignerCommitments = [...this.signerCommitments, newCommitment];
         // What `update_signers_and_threshold` rejects on-chain, and what the auth
@@ -772,12 +838,10 @@ export class Multisig {
         });
         this.warnOnOverrideDilution(targetSignerCommitments.length);
         const { request, salt } = await buildUpdateSignersTransactionRequest(this.midenClient, targetThreshold, targetSignerCommitments, this.proposalRequestOptions(options));
-        const { summary, anchor } = await executeForSummary(this.midenClient, this._accountId, request);
-        const chainAnchor = chainAnchorToBase64(anchor);
-        anchor.free();
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = await this.resolveProposalNonce('createAddSignerProposal', options);
+        const { summaryBase64, boundBlockNum } = await this.deriveProposalSummary(request);
         const metadata = {
-            chainAnchor,
+            boundBlockNum,
             proposalType: 'add_signer',
             targetThreshold,
             targetSignerCommitments,
@@ -795,7 +859,7 @@ export class Multisig {
      *   min of current threshold and new signer count)
      */
     async createRemoveSignerProposal(signerToRemove, options = {}, ...legacyArgs) {
-        const proposalNonce = resolveProposalNonce('createRemoveSignerProposal', options, legacyArgs);
+        assertProposalOptionsBag('createRemoveSignerProposal', options, legacyArgs);
         const normalizedRemove = signerToRemove.toLowerCase();
         const targetSignerCommitments = this.signerCommitments.filter((c) => c.toLowerCase() !== normalizedRemove);
         if (targetSignerCommitments.length === this.signerCommitments.length) {
@@ -809,12 +873,10 @@ export class Multisig {
             throw new Error(`Invalid threshold ${targetThreshold}. Must be between 1 and ${targetSignerCommitments.length}`);
         }
         const { request, salt } = await buildUpdateSignersTransactionRequest(this.midenClient, targetThreshold, targetSignerCommitments, this.proposalRequestOptions(options));
-        const { summary, anchor } = await executeForSummary(this.midenClient, this._accountId, request);
-        const chainAnchor = chainAnchorToBase64(anchor);
-        anchor.free();
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = await this.resolveProposalNonce('createRemoveSignerProposal', options);
+        const { summaryBase64, boundBlockNum } = await this.deriveProposalSummary(request);
         const metadata = {
-            chainAnchor,
+            boundBlockNum,
             proposalType: 'remove_signer',
             targetThreshold,
             targetSignerCommitments,
@@ -831,7 +893,7 @@ export class Multisig {
      * @param options - Optional settings: `nonce`
      */
     async createChangeThresholdProposal(newThreshold, options = {}) {
-        const proposalNonce = resolveProposalNonce('createChangeThresholdProposal', options);
+        assertProposalOptionsBag('createChangeThresholdProposal', options);
         if (newThreshold < 1 || newThreshold > this.signerCommitments.length) {
             throw new Error(`Invalid threshold ${newThreshold}. Must be between 1 and ${this.signerCommitments.length}`);
         }
@@ -839,12 +901,10 @@ export class Multisig {
             throw new Error('New threshold is the same as current threshold');
         }
         const { request, salt } = await buildUpdateSignersTransactionRequest(this.midenClient, newThreshold, this.signerCommitments, this.proposalRequestOptions(options));
-        const { summary, anchor } = await executeForSummary(this.midenClient, this._accountId, request);
-        const chainAnchor = chainAnchorToBase64(anchor);
-        anchor.free();
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = await this.resolveProposalNonce('createChangeThresholdProposal', options);
+        const { summaryBase64, boundBlockNum } = await this.deriveProposalSummary(request);
         const metadata = {
-            chainAnchor,
+            boundBlockNum,
             proposalType: 'change_threshold',
             targetThreshold: newThreshold,
             targetSignerCommitments: this.signerCommitments,
@@ -855,7 +915,7 @@ export class Multisig {
         return this.createProposal(proposalNonce, summaryBase64, metadata);
     }
     async createUpdateProcedureThresholdProposal(targetProcedure, targetThreshold, options = {}) {
-        const proposalNonce = resolveProposalNonce('createUpdateProcedureThresholdProposal', options);
+        assertProposalOptionsBag('createUpdateProcedureThresholdProposal', options);
         if (targetThreshold < 0 || targetThreshold > this.signerCommitments.length) {
             throw new Error(`Invalid threshold ${targetThreshold}. Must be between 0 and ${this.signerCommitments.length}`);
         }
@@ -867,15 +927,13 @@ export class Multisig {
             throw new Error(`Procedure ${targetProcedure} already has threshold override ${targetThreshold}`);
         }
         const { request, salt } = await buildUpdateProcedureThresholdTransactionRequest(this.midenClient, targetProcedure, targetThreshold, this.proposalRequestOptions(options));
-        const { summary, anchor } = await executeForSummary(this.midenClient, this._accountId, request);
-        const chainAnchor = chainAnchorToBase64(anchor);
-        anchor.free();
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = await this.resolveProposalNonce('createUpdateProcedureThresholdProposal', options);
+        const { summaryBase64, boundBlockNum } = await this.deriveProposalSummary(request);
         const action = targetThreshold === 0
             ? `Clear threshold override for ${targetProcedure}`
             : `Set ${targetProcedure} threshold override to ${targetThreshold}`;
         const metadata = {
-            chainAnchor,
+            boundBlockNum,
             proposalType: 'update_procedure_threshold',
             targetProcedure,
             targetThreshold,
@@ -893,11 +951,12 @@ export class Multisig {
      * @param options - Optional settings: `nonce`
      */
     async createSwitchGuardianProposal(newGuardianEndpoint, newGuardianPubkey, options = {}) {
-        const proposalNonce = resolveProposalNonce('createSwitchGuardianProposal', options);
+        assertProposalOptionsBag('createSwitchGuardianProposal', options);
         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.
+        const proposalNonce = await this.resolveProposalNonce('createSwitchGuardianProposal', options);
         return this.createProposal(proposalNonce, summaryBase64, metadata);
     }
     /**
@@ -920,12 +979,9 @@ export class Multisig {
             approvalExpirationDelta,
             signatureScheme: this.signer.scheme,
         });
-        const { summary, anchor } = await executeForSummary(this.midenClient, this._accountId, request);
-        const chainAnchor = chainAnchorToBase64(anchor);
-        anchor.free();
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const { summaryBase64, boundBlockNum } = await this.deriveProposalSummary(request);
         const metadata = {
-            chainAnchor,
+            boundBlockNum,
             proposalType: 'switch_guardian',
             saltHex: salt.toHex(),
             requiredSignatures: this.getEffectiveThreshold('switch_guardian'),
@@ -961,13 +1017,14 @@ export class Multisig {
      * @param options - Optional settings: `nonce`
      */
     async createSwitchGuardianProposalOffline(newGuardianEndpoint, newGuardianPubkey, options = {}) {
-        const proposalNonce = resolveProposalNonce('createSwitchGuardianProposalOffline', options);
+        assertProposalOptionsBag('createSwitchGuardianProposalOffline', options);
         // Sync with the Miden node and refresh the cached account/config before
         // building (mirrors the Rust `sync_network_only`): with no GUARDIAN push
         // to reject a stale delta at creation, a summary built from stale local
         // state — or a readiness threshold read from stale config — would only
         // fail at execution, after the whole side-channel cosigning ceremony.
-        await this.syncNetworkOnly();
+        const synced = await this.syncNetworkOnly();
+        const proposalNonce = await this.resolveProposalNonce('createSwitchGuardianProposalOffline', options, [], synced);
         const { summaryBase64, metadata } = await this.buildSwitchGuardianSummary(newGuardianEndpoint, newGuardianPubkey, options.approvalExpirationDelta);
         const exported = {
             accountId: this._accountId,
@@ -991,7 +1048,7 @@ export class Multisig {
      * @param options - Optional settings: `nonce`
      */
     async createConsumeNotesProposal(noteIds, options = {}) {
-        const proposalNonce = resolveProposalNonce('createConsumeNotesProposal', options);
+        assertProposalOptionsBag('createConsumeNotesProposal', options);
         if (noteIds.length === 0) {
             throw new Error('At least one note ID is required');
         }
@@ -1006,16 +1063,14 @@ export class Multisig {
         }
         // 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.
+        // the notes are authenticated here first, before the summary is derived.
         await this.ensureNotesAuthenticated(fetchedNotes);
+        const proposalNonce = await this.resolveProposalNonce('createConsumeNotesProposal', options);
         const embeddedNotes = fetchedNotes.map((n) => noteToBase64(n));
         const { request, salt } = await buildConsumeNotesTransactionRequestFromNotes(this.midenClient, fetchedNotes, this.proposalRequestOptions(options));
-        const { summary, anchor } = await executeForSummary(this.midenClient, this._accountId, request);
-        const chainAnchor = chainAnchorToBase64(anchor);
-        anchor.free();
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const { summaryBase64, boundBlockNum } = await this.deriveProposalSummary(request);
         const metadata = {
-            chainAnchor,
+            boundBlockNum,
             proposalType: 'consume_notes',
             noteIds,
             metadataVersion: CONSUME_NOTES_METADATA_VERSION_V2,
@@ -1046,7 +1101,7 @@ export class Multisig {
      *   `reclaimHeight`/`timelockHeight` build a P2IDE note (issue #366)
      */
     async createP2idProposal(recipientId, faucetId, amount, options = {}, ...legacyArgs) {
-        const proposalNonce = resolveProposalNonce('createP2idProposal', options, legacyArgs);
+        assertProposalOptionsBag('createP2idProposal', options, legacyArgs);
         if (amount <= 0n) {
             throw new Error('Amount must be greater than 0');
         }
@@ -1054,12 +1109,10 @@ export class Multisig {
         // CreateP2idProposalOptions can't be silently dropped before the builder.
         const { nonce: _nonce, ...noteOptions } = options;
         const { request, salt } = await buildP2idTransactionRequest(this.midenClient, this._accountId, recipientId, faucetId, amount, noteOptions);
-        const { summary, anchor } = await executeForSummary(this.midenClient, this._accountId, request);
-        const chainAnchor = chainAnchorToBase64(anchor);
-        anchor.free();
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = await this.resolveProposalNonce('createP2idProposal', options);
+        const { summaryBase64, boundBlockNum } = await this.deriveProposalSummary(request);
         const metadata = {
-            chainAnchor,
+            boundBlockNum,
             proposalType: 'p2id',
             saltHex: salt.toHex(),
             requiredSignatures: this.getEffectiveThreshold('p2id'),
@@ -1514,7 +1567,7 @@ export class Multisig {
      * @param proposalId - The proposal commitment/ID
      */
     async executeProposal(proposalId) {
-        const { metadata, finalRequest, proposal } = await this.prepareProposalExecution(proposalId);
+        const { metadata, finalRequest, proposal, executedBase } = 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;
@@ -1531,13 +1584,16 @@ export class Multisig {
             // Canonicalize the executed delta on the pre-switch GUARDIAN (clears the
             // pending proposal). Must run before `this.guardian` is repointed below.
             // Best-effort: an unreachable old GUARDIAN must not block the switch, so
-            // errors are swallowed (mirrors the Rust execute path).
+            // errors are swallowed (mirrors the Rust execute path, which names the
+            // state it executed on and sends the summary it holds; GUARDIAN assigns
+            // the status).
             try {
-                const normalizedProposalId = normalizeHexWord(proposal.id);
-                const switchDelta = await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
                 await this.guardian.pushDelta({
-                    ...switchDelta,
-                    deltaPayload: switchDelta.deltaPayload.txSummary,
+                    accountId: this._accountId,
+                    nonce: proposal.nonce,
+                    prevCommitment: executedBase,
+                    deltaPayload: { data: proposal.txSummary },
+                    status: { status: 'candidate', timestamp: new Date().toISOString() },
                 });
             }
             catch (error) {
@@ -1577,19 +1633,9 @@ export class Multisig {
         await this.syncChain();
         const delta = await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
         const existing = this.getLocalProposal(proposalId);
-        const proposal = this.proposalFactory().fromDelta(delta, normalizedProposalId, existing?.metadata, existing?.signatures ?? []);
-        const anchor = this.requireProposalAnchor(proposalId, proposal.metadata);
-        try {
-            const anchorCommitment = normalizeHexWord(anchor.commitment().toHex());
-            const txSummary = TransactionSummary.deserialize(base64ToUint8Array(delta.deltaPayload.txSummary.data));
-            const summaryBlockCommitment = normalizeHexWord(txSummary.blockCommitment().toHex());
-            if (anchorCommitment !== summaryBlockCommitment) {
-                throw new Error(`Proposal ${proposalId} chain anchor does not match the block commitment bound into its tx_summary`);
-            }
-        }
-        finally {
-            anchor.free();
-        }
+        // Parsed for its id check: a proposal GUARDIAN does not serve, or whose id
+        // is not its summary's commitment, is not submitted (as in the Rust SDK).
+        this.proposalFactory().fromDelta(delta, normalizedProposalId, existing?.metadata, existing?.signatures ?? []);
         await this.submitAtTip(request);
     }
     /**
@@ -1608,9 +1654,12 @@ export class Multisig {
     async syncChain() {
         await retryRpcRead(() => this.midenClient.syncChain(), this.rpcConfig);
     }
-    /** {@link syncToBoundBlock} with this client's RPC retry policy. */
-    async syncToBoundBlock(boundBlockNum) {
-        await syncToBoundBlock(this.midenClient, boundBlockNum, () => this.syncChain());
+    /**
+     * {@link syncToBoundBlock} with this client's RPC retry policy. A listing
+     * passes its own `syncChain` so it syncs at most once for all its proposals.
+     */
+    async syncToBoundBlock(boundBlockNum, syncChain = () => this.syncChain()) {
+        await syncToBoundBlock(this.midenClient, boundBlockNum, syncChain);
     }
     /**
      * Create a proposal from a producer-built transaction the SDK does not model.
@@ -1620,7 +1669,7 @@ export class Multisig {
      * `prepareCustomExecution`.
      */
     async createCustomProposal(transactionRequestBytes, proposalType, options = {}) {
-        const proposalNonce = resolveProposalNonce('createCustomProposal', options);
+        assertProposalOptionsBag('createCustomProposal', options);
         const label = proposalType.trim().toLowerCase();
         if (label.length === 0) {
             throw new Error('proposalType must not be empty');
@@ -1632,12 +1681,10 @@ export class Multisig {
             throw new Error(`'${label}' is a built-in proposal type; use the typed proposal API instead`);
         }
         const request = deserializeTransactionRequest(transactionRequestBytes);
-        const { summary, anchor } = await executeForSummary(this.midenClient, this._accountId, request);
-        const chainAnchor = chainAnchorToBase64(anchor);
-        anchor.free();
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = await this.resolveProposalNonce('createCustomProposal', options);
+        const { summaryBase64, boundBlockNum } = await this.deriveProposalSummary(request);
         const metadata = {
-            chainAnchor,
+            boundBlockNum,
             proposalType: 'custom',
             description: '',
             rawProposalType: label,
@@ -1670,24 +1717,11 @@ export class Multisig {
         if (signaturesForExecution.length < effectiveThreshold) {
             throw new Error(`Proposal is not ready for execution: have ${signaturesForExecution.length} of ${effectiveThreshold} required signatures.`);
         }
+        await this.assertExecutesOnPinnedBase(proposalId, delta.prevCommitment);
         const txSummary = TransactionSummary.deserialize(base64ToUint8Array(delta.deltaPayload.txSummary.data));
+        this.requireProposalBoundBlockNum(proposal.id, proposal.metadata, txSummary);
         const signedCommitmentHex = normalizeHexWord(txSummary.toCommitment().toHex());
         const bindingRequest = deserializeTransactionRequest(transactionRequestBytes);
-        // The anchor arrives from an untrusted party via GUARDIAN, so its block
-        // commitment is checked against the signed summary: it has to name the
-        // block the summary binds. The probe itself runs at the chain tip, where
-        // the request's declared bound block reproduces the signed summary.
-        const anchor = this.requireProposalAnchor(proposalId, proposal.metadata);
-        try {
-            const anchorCommitment = normalizeHexWord(anchor.commitment().toHex());
-            const summaryBlockCommitment = normalizeHexWord(txSummary.blockCommitment().toHex());
-            if (anchorCommitment !== summaryBlockCommitment) {
-                throw new Error(`Custom proposal ${proposalId} chain anchor does not match the block commitment bound into its tx_summary`);
-            }
-        }
-        finally {
-            anchor.free();
-        }
         const derived = await executeForSummaryAtTip(this.midenClient, this._accountId, bindingRequest);
         const derivedCommitmentHex = normalizeHexWord(derived.toCommitment().toHex());
         if (derivedCommitmentHex !== signedCommitmentHex) {
@@ -1809,11 +1843,15 @@ export class Multisig {
         let delta;
         if (isSwitchGuardian) {
             txSummaryBase64 = proposal.txSummary;
+            delta = await this.servedSwitchProposal(normalizedProposalId);
         }
         else {
             delta = await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
             txSummaryBase64 = delta.deltaPayload.txSummary.data;
         }
+        const executedBase = delta
+            ? await this.assertExecutesOnPinnedBase(proposalId, delta.prevCommitment)
+            : await this.localAccountCommitment();
         const txSummaryBytes = base64ToUint8Array(txSummaryBase64);
         const txSummary = TransactionSummary.deserialize(txSummaryBytes);
         const saltHex = this.requireProposalSaltHex(proposalId, metadata);
@@ -1898,19 +1936,37 @@ export class Multisig {
         if (metadata.proposalType === 'switch_guardian') {
             await this.verifyGuardianEndpointCommitment(metadata.newGuardianEndpoint, metadata.newGuardianPubkey);
         }
-        const anchor = this.requireProposalAnchor(proposalId, metadata);
-        let binding;
-        try {
-            binding = proposalRequestBinding(txSummary, anchor, saltHex);
-        }
-        finally {
-            anchor.free();
-        }
+        const binding = proposalRequestBinding(txSummary, this.requireProposalBoundBlockNum(proposalId, metadata, txSummary), saltHex);
         // A switch_guardian proposal is verified without a rebuild, so this may be
         // the first time this client needs the chain at the bound block.
         await this.syncToBoundBlock(binding.boundBlockNum);
         const finalRequest = await this.buildTransactionRequestFromMetadata(metadata, binding, adviceMap);
-        return { finalRequest, metadata, proposal };
+        return { finalRequest, metadata, proposal, executedBase };
+    }
+    /**
+     * A switch_guardian proposal as the pre-switch GUARDIAN serves it, so the
+     * state it pinned the proposal to is checked as for every other type, or
+     * `undefined` when that GUARDIAN does not serve it. Not holding the
+     * proposal (one made offline) is the designed offline case. Any other
+     * failure, whether the GUARDIAN is unreachable or answers with an error
+     * (an authentication failure, a paused or released account, rate limiting,
+     * a server fault), is warned about. In every one of those cases the switch
+     * then executes from its cached summary without the check: rotating away
+     * from a GUARDIAN that is down or refusing service is what the switch
+     * exists for, so that GUARDIAN cannot be what blocks it.
+     */
+    async servedSwitchProposal(normalizedProposalId) {
+        try {
+            return await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
+        }
+        catch (error) {
+            if (error instanceof GuardianHttpError && error.code === 'proposal_not_found') {
+                return undefined;
+            }
+            console.warn('The pre-switch GUARDIAN did not serve the switch proposal; executing it without ' +
+                'checking the state it was pinned to', error);
+            return undefined;
+        }
     }
     /**
      * Export a proposal for offline signing
@@ -2062,9 +2118,9 @@ export class Multisig {
      * transient. Rethrows the failure so strict callers keep failing closed
      * while `syncProposals` keeps going with the outcome recorded.
      */
-    async verifyProposalMetadataBinding(proposal) {
+    async verifyProposalMetadataBinding(proposal, syncChain) {
         try {
-            const commitment = await this.checkProposalMetadataBinding(proposal);
+            const commitment = await this.checkProposalMetadataBinding(proposal, syncChain);
             proposal.verification = { status: 'verified' };
             return commitment;
         }
@@ -2077,64 +2133,48 @@ export class Multisig {
             throw error;
         }
     }
-    async checkProposalMetadataBinding(proposal) {
+    async checkProposalMetadataBinding(proposal, syncChain) {
         const txSummaryCommitment = this.ensureProposalCommitmentMatchesSummary(proposal);
         const summary = TransactionSummary.deserialize(base64ToUint8Array(proposal.txSummary));
-        // The anchor arrives from an untrusted party via GUARDIAN, so check that it
-        // names the block the signed summary binds: the rebuild below binds the
-        // block it names. Nothing executes against it; the rebuild runs at the
-        // chain tip. `ChainAnchor.deserialize` already enforced internal
-        // header/chain consistency.
-        const anchor = this.requireProposalAnchor(proposal.id, proposal.metadata);
-        try {
-            const anchorCommitment = normalizeHexWord(anchor.commitment().toHex());
-            const summaryBlockCommitment = normalizeHexWord(summary.blockCommitment().toHex());
-            if (anchorCommitment !== summaryBlockCommitment) {
-                throw new Error(`Invalid proposal: chain anchor does not match the block commitment bound into the tx_summary for ${proposal.id}`);
-            }
-            if (proposal.metadata.proposalType === 'custom') {
-                // Custom proposals have no per-type reconstruction recipe;
-                // the id ↔ tx_summary commitment match above is the only available
-                // 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,
-                // the salt above and the guardian endpoint commitment provide the
-                // binding checks for this type.
-                return txSummaryCommitment;
-            }
-            // The rebuild reads the chain's fee faucet from the synced protocol
-            // configuration and executes at the tip, so the store has to have synced
-            // to the block the summary binds; a cosigner that has only just loaded
-            // the account has not.
-            await this.syncToBoundBlock(binding.boundBlockNum);
-            // 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 reconstructed = await executeForSummaryAtTip(this.midenClient, this._accountId, request);
-            const reconstructedCommitment = normalizeHexWord(reconstructed.toCommitment().toHex());
-            if (reconstructedCommitment !== txSummaryCommitment) {
-                throw new Error(`Invalid proposal: metadata does not match tx_summary for ${proposal.id}`);
-            }
+        const boundBlockNum = this.requireProposalBoundBlockNum(proposal.id, proposal.metadata, summary);
+        if (proposal.metadata.proposalType === 'custom') {
+            // Custom proposals have no per-type reconstruction recipe; the id and
+            // bound-block checks above are the only available integrity guarantee
+            // for an opaque proposal.
             return txSummaryCommitment;
         }
-        finally {
-            anchor.free();
+        // The salt check needs no re-execution, so it runs for every built-in
+        // type, switch_guardian included (as in the Rust SDK).
+        const binding = proposalRequestBinding(summary, boundBlockNum, 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,
+            // the salt above and the guardian endpoint commitment provide the
+            // binding checks for this type.
+            return txSummaryCommitment;
+        }
+        // The rebuild reads the chain's fee faucet from the synced protocol
+        // configuration and executes at the tip, so the store has to have synced
+        // to the block the summary binds; a cosigner that has only just loaded
+        // the account has not.
+        await this.syncToBoundBlock(binding.boundBlockNum, syncChain);
+        // 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 reconstructed = await executeForSummaryAtTip(this.midenClient, this._accountId, request);
+        const reconstructedCommitment = normalizeHexWord(reconstructed.toCommitment().toHex());
+        if (reconstructedCommitment !== txSummaryCommitment) {
+            throw new Error(`Invalid proposal: metadata does not match tx_summary for ${proposal.id}`);
         }
+        return txSummaryCommitment;
     }
     /**
      * Reads a proposal's salt. Throws when absent, because there is nothing to fall
@@ -2178,17 +2218,43 @@ export class Multisig {
         return saltHex;
     }
     /**
-     * Decodes a proposal's chain anchor, which names the block its signed summary
-     * binds. Throws when absent: every proposal carries one, so a proposal
-     * without it is malformed and is neither verified nor executed. The caller
-     * owns the returned anchor and must `free()` it once done.
+     * The block a proposal's signed summary binds, read from the summary as the
+     * Rust SDK does.
+     *
+     * GUARDIAN serves `boundBlockNum` unsigned and the response is cast, not
+     * parsed. An absent value, from a proposal a 0.18.0 client made, is accepted;
+     * a legacy `chainAnchor` is not read. A present value has to be a block
+     * number equal to the summary's, for every proposal type, so a wrong one is
+     * refused by name before anything executes or is signed.
+     *
+     * @throws BoundBlockMismatchError when the served value names another block.
      */
-    requireProposalAnchor(proposalId, metadata) {
-        if (!metadata.chainAnchor) {
-            throw new Error(`Proposal ${proposalId} has no chain anchor, which names the block its signed ` +
-                'summary binds; it cannot be verified or executed');
+    requireProposalBoundBlockNum(proposalId, metadata, summary) {
+        const declared = this.servedBoundBlockNum(proposalId, metadata);
+        const boundBlockNum = summaryBoundBlockNum(summary);
+        if (declared !== undefined && declared !== boundBlockNum) {
+            throw new BoundBlockMismatchError({
+                proposalId,
+                declaredBoundBlockNum: declared,
+                boundBlockNum,
+            });
+        }
+        return boundBlockNum;
+    }
+    /** The served `boundBlockNum`, `undefined` when absent; throws when malformed. */
+    servedBoundBlockNum(proposalId, metadata) {
+        const boundBlockNum = metadata.boundBlockNum;
+        if (boundBlockNum === undefined || boundBlockNum === null) {
+            return undefined;
+        }
+        if (typeof boundBlockNum !== 'number' ||
+            !Number.isInteger(boundBlockNum) ||
+            boundBlockNum < 0 ||
+            boundBlockNum > MAX_BLOCK_NUM) {
+            throw new Error(`Proposal ${proposalId} has a malformed boundBlockNum '${String(boundBlockNum)}': ` +
+                `expected an integer between 0 and ${MAX_BLOCK_NUM}`);
         }
-        return chainAnchorFromBase64(metadata.chainAnchor);
+        return boundBlockNum;
     }
     /**
      * An expired approval aborts in the auth procedure only at execution.