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

package/src/multisig.ts

@@ -44,7 +44,10 @@ import {
   chainAnchorFromBase64,
   chainAnchorToBase64,
   executeForSummary,
-  executeForSummaryAt,
+  executeForSummaryAtTip,
+  isStaleChainError,
+  prepareTipExecution,
+  syncToBoundBlock,
   summaryApprovalExpirationBlockNum,
   summarySalt,
   buildUpdateSignersTransactionRequest,
@@ -157,7 +160,7 @@ export interface CreateProposalOptions {
   /** Proposal nonce; defaults to `Date.now()`. */
   nonce?: number;
   /**
-   * Blocks after the proposal's anchor block by which the transaction must be
+   * Blocks after the block the proposal binds 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).
@@ -808,11 +811,12 @@ export class Multisig {
    * 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
+   * proposal cannot hide the others (issue #462). Verification re-executes
+   * each proposal at the chain tip, so the Miden client is synced once first.
+   * `failed` with `retryable: true` means a transient node error or chain
+   * state this client had not caught up with, 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.
    *
@@ -852,6 +856,14 @@ export class Multisig {
     const factory = this.proposalFactory();
 
     const reported = new Map<string, { delta: (typeof deltas)[number]; verified: Proposal }>();
+    if (deltas.length > 0) {
+      // Verification re-executes at the store's sync height; bring it to the
+      // tip once for the whole listing. Best effort: a node outage then shows
+      // up on each proposal as a retryable failure instead of failing the sync.
+      await this.syncChain().catch((error) =>
+        console.warn('Could not sync the Miden client before verifying proposals', error),
+      );
+    }
     for (const delta of deltas) {
       const proposalId = normalizeHexWord(
         computeCommitmentFromTxSummary(delta.deltaPayload.txSummary.data)
@@ -1972,6 +1984,8 @@ export class Multisig {
 
   async signProposal(proposalId: string): Promise<Proposal> {
     const normalizedProposalId = normalizeHexWord(proposalId);
+    // Verification re-executes the proposal at the store's sync height.
+    await this.syncChain();
     const existingProposal = await this.getProposalForSigning(proposalId, normalizedProposalId);
     if (!existingProposal) {
       throw new Error(`Proposal not found: ${proposalId}`);
@@ -2019,9 +2033,14 @@ export class Multisig {
     return this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
   }
 
+  /**
+   * Builds the final, fully signed request for a ready proposal, for a caller
+   * that proves and submits it with its own pipeline. The request declares the
+   * block its summary binds, so execute it at the chain tip, without an
+   * anchor, on a client synced to at least that block.
+   */
   async createTransactionProposalRequest(proposalId: string): Promise<TransactionRequest> {
-    const { finalRequest, anchor } = await this.prepareProposalExecution(proposalId);
-    anchor.free();
+    const { finalRequest } = await this.prepareProposalExecution(proposalId);
     return finalRequest;
   }
 
@@ -2031,25 +2050,19 @@ export class Multisig {
    * @param proposalId - The proposal commitment/ID
    */
   async executeProposal(proposalId: string): Promise<void> {
-    const { metadata, finalRequest, proposal, anchor } =
-      await this.prepareProposalExecution(proposalId);
-
-    try {
-      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();
-      }
+    const { metadata, finalRequest, proposal } = await this.prepareProposalExecution(proposalId);
 
-      // 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();
+    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 chain tip. The request declares the block the signed
+    // summary binds, so the summary the cosigners signed reproduces there.
+    await this.submitAtTip(finalRequest);
+
     if (metadata.proposalType === 'switch_guardian') {
       if (!metadata.newGuardianEndpoint || !metadata.newGuardianPubkey) {
         throw new Error('Switch GUARDIAN proposal metadata is incomplete after execution');
@@ -2109,11 +2122,12 @@ export class Multisig {
    * Submit an integration-built transaction (advice already injected). Mirrors
    * the Rust `submit_transaction`; used by the custom proposal producer flow
    * after `prepareCustomExecution` rebuilds its request with the returned advice.
-   * The transaction is executed at the proposal's anchored reference block,
-   * since the collected signatures only authorize the summary produced there.
+   * The transaction is executed at the chain tip, so the request has to declare
+   * the block its auth args bind (`feeAwareTransactionRequestBuilder` does).
    */
   async submitTransaction(proposalId: string, request: TransactionRequest): Promise<void> {
     const normalizedProposalId = normalizeHexWord(proposalId);
+    await this.syncChain();
     const delta = await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
     const existing = this.getLocalProposal(proposalId);
     const proposal = this.proposalFactory().fromDelta(
@@ -2135,11 +2149,40 @@ export class Multisig {
           `Proposal ${proposalId} chain anchor does not match the block commitment bound into its tx_summary`,
         );
       }
-
-      await this.proverWorkflow.submitAt(AccountId.fromHex(this._accountId), request, anchor);
     } finally {
       anchor.free();
     }
+    await this.submitAtTip(request);
+  }
+
+  /**
+   * Executes `request` at the chain tip, then proves, submits and applies it,
+   * syncing first when this client is still below the block the request binds.
+   */
+  private async submitAtTip(request: TransactionRequest): Promise<void> {
+    const webClient = await this.getRawClient();
+    await prepareTipExecution(webClient, request, () =>
+      retryRpcRead(() => webClient.syncState(), this.rpcConfig),
+    );
+    await this.proverWorkflow.submit(AccountId.fromHex(this._accountId), request);
+  }
+
+  /**
+   * Brings the Miden client to the chain tip before a proposal is re-executed:
+   * an execution loads foreign accounts, the fee faucet among them, at the
+   * store's sync height, which a node prunes about 50 blocks later.
+   */
+  private async syncChain(): Promise<void> {
+    const webClient = await this.getRawClient();
+    await retryRpcRead(() => webClient.syncState(), this.rpcConfig);
+  }
+
+  /** {@link syncToBoundBlock} with this client's RPC retry policy. */
+  private async syncToBoundBlock(boundBlockNum: number): Promise<void> {
+    const webClient = await this.getRawClient();
+    await syncToBoundBlock(webClient, boundBlockNum, () =>
+      retryRpcRead(() => webClient.syncState(), this.rpcConfig),
+    );
   }
 
   /**
@@ -2203,6 +2246,8 @@ export class Multisig {
     transactionRequestBytes: Uint8Array,
   ): Promise<AdviceMap> {
     const normalizedProposalId = normalizeHexWord(proposalId);
+    // The binding probe re-executes the producer's request at the store's sync height.
+    await this.syncChain();
     const delta = await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
     const existing = this.getLocalProposal(proposalId);
     const proposal = this.proposalFactory().fromDelta(
@@ -2237,13 +2282,11 @@ export class Multisig {
 
     const bindingRequest = deserializeTransactionRequest(transactionRequestBytes);
 
-    // Probe at the proposal's anchored reference block: the signed summary
-    // binds that block's commitment, so probing at the local sync height would
-    // never reproduce it. The anchor arrives from an untrusted party via
-    // GUARDIAN, so its block commitment is checked against the signed summary
-    // before executing against it.
+    // 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);
-    let derivedCommitmentHex: string;
     try {
       const anchorCommitment = normalizeHexWord(anchor.commitment().toHex());
       const summaryBlockCommitment = normalizeHexWord(txSummary.blockCommitment().toHex());
@@ -2252,12 +2295,12 @@ export class Multisig {
           `Custom proposal ${proposalId} chain anchor does not match the block commitment bound into its tx_summary`,
         );
       }
-      const webClient = await this.getRawClient();
-      const derived = await executeForSummaryAt(webClient, this._accountId, bindingRequest, anchor);
-      derivedCommitmentHex = normalizeHexWord(derived.toCommitment().toHex());
     } finally {
       anchor.free();
     }
+    const webClient = await this.getRawClient();
+    const derived = await executeForSummaryAtTip(webClient, this._accountId, bindingRequest);
+    const derivedCommitmentHex = normalizeHexWord(derived.toCommitment().toHex());
     if (derivedCommitmentHex !== signedCommitmentHex) {
       throw new Error(
         `Custom proposal binding mismatch: expected ${signedCommitmentHex}, got ${derivedCommitmentHex}`,
@@ -2396,14 +2439,13 @@ export class Multisig {
   }
 
   /**
-   * The returned `anchor` is the block the request has to execute at; the
-   * caller owns it and frees it once submitted.
+   * The returned request declares the block the signed summary binds, and
+   * executes at the chain tip.
    */
   private async prepareProposalExecution(proposalId: string): Promise<{
     finalRequest: TransactionRequest;
     metadata: ProposalMetadata;
     proposal: Proposal;
-    anchor: ChainAnchor;
   }> {
     const proposal = this.getLocalProposal(proposalId);
     if (!proposal) {
@@ -2411,6 +2453,8 @@ export class Multisig {
     }
 
     this.proposalFactory().assertAccountId(proposal.accountId);
+    // Verification and execution run at the store's sync height.
+    await this.syncChain();
     await this.verifyProposalMetadataBinding(proposal);
 
     const metadata = proposal.metadata;
@@ -2560,17 +2604,21 @@ export class Multisig {
     }
 
     const anchor = this.requireProposalAnchor(proposalId, metadata);
+    let binding: ProposalRequestBinding;
     try {
-      const finalRequest = await this.buildTransactionRequestFromMetadata(
-        metadata,
-        proposalRequestBinding(txSummary, anchor, saltHex),
-        adviceMap,
-      );
-      return { finalRequest, metadata, proposal, anchor };
-    } catch (error) {
+      binding = proposalRequestBinding(txSummary, anchor, saltHex);
+    } finally {
       anchor.free();
-      throw error;
     }
+    // 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 };
   }
 
   /**
@@ -2655,6 +2703,10 @@ export class Multisig {
 
     const proposal = this.proposalFactory().fromExported(exported);
 
+    // Verification re-executes every built-in type at the store's sync height.
+    if (proposal.metadata.proposalType !== 'custom') {
+      await this.syncChain();
+    }
     await this.verifyProposalMetadataBinding(proposal);
     this.proposals.set(proposal.id, proposal);
 
@@ -2695,6 +2747,10 @@ export class Multisig {
       throw new Error('You have already signed this proposal');
     }
 
+    // Verification re-executes every built-in type at the store's sync height.
+    if (proposal.metadata?.proposalType !== 'custom') {
+      await this.syncChain();
+    }
     const commitmentToSign = await this.verifyProposalMetadataBinding(proposal);
 
     // Sign the commitment
@@ -2758,7 +2814,7 @@ export class Multisig {
     } catch (error) {
       proposal.verification = {
         status: 'failed',
-        retryable: isTransientRpcError(error),
+        retryable: isTransientRpcError(error) || isStaleChainError(error),
         message: error instanceof Error ? error.message : String(error),
       };
       throw error;
@@ -2770,10 +2826,11 @@ export class Multisig {
 
     const summary = TransactionSummary.deserialize(base64ToUint8Array(proposal.txSummary));
 
-    // The anchor arrives from an untrusted party via GUARDIAN, so check its
-    // block commitment against the one bound into the signed summary before
-    // anything executes against it. `ChainAnchor.deserialize` already enforced
-    // internal header/chain consistency.
+    // 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());
@@ -2812,6 +2869,13 @@ export class Multisig {
         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);
+      const webClient = await this.getRawClient();
+
       // 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
@@ -2824,8 +2888,7 @@ export class Multisig {
       }
 
       const request = await this.buildTransactionRequestFromMetadata(proposal.metadata, binding);
-      const webClient = await this.getRawClient();
-      const reconstructed = await executeForSummaryAt(webClient, this._accountId, request, anchor);
+      const reconstructed = await executeForSummaryAtTip(webClient, this._accountId, request);
       const reconstructedCommitment = normalizeHexWord(reconstructed.toCommitment().toHex());
 
       if (reconstructedCommitment !== txSummaryCommitment) {
@@ -2838,12 +2901,6 @@ export class Multisig {
     }
   }
 
-  /**
-   * Decodes a proposal's chain anchor. Throws when absent: a proposal without
-   * an anchor was created at an unknown reference block, so its signed summary
-   * cannot be reproduced, verified, or executed. The caller owns the returned
-   * anchor and must `free()` it once done.
-   */
   /**
    * Reads a proposal's salt. Throws when absent, because there is nothing to fall
    * back to.
@@ -2892,12 +2949,17 @@ 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.
+   */
   private requireProposalAnchor(proposalId: string, metadata: ProposalMetadata): ChainAnchor {
     if (!metadata.chainAnchor) {
       throw new Error(
-        `Proposal ${proposalId} has no chain anchor; it was created without ` +
-          'chain-anchored execution and its signed summary cannot be reproduced ' +
-          'at the original reference block',
+        `Proposal ${proposalId} has no chain anchor, which names the block its signed ` +
+          'summary binds; it cannot be verified or executed',
       );
     }
     return chainAnchorFromBase64(metadata.chainAnchor);

package/src/prover/workflow.ts

@@ -1,6 +1,5 @@
 import type {
   AccountId,
-  ChainAnchor,
   MidenClient,
   TransactionRequest,
 } from '@miden-sdk/miden-sdk';
@@ -15,15 +14,13 @@ export class ProverWorkflow {
     private readonly runtime?: RetryRuntime,
   ) {}
 
-  /** Proves, submits, and applies a request at its signed chain anchor. */
-  async submitAt(
-    accountId: AccountId,
-    request: TransactionRequest,
-    anchor: ChainAnchor,
-  ): Promise<void> {
-    const execution = await this.client.transactions.executeRequest(accountId, request, {
-      anchor,
-    });
+  /**
+   * Executes a request at the chain tip, then proves, submits, and applies it.
+   * A multisig proposal's request declares the block its summary binds, so the
+   * signed summary reproduces at the tip.
+   */
+  async submit(accountId: AccountId, request: TransactionRequest): Promise<void> {
+    const execution = await this.client.transactions.executeRequest(accountId, request);
     const proof = await proveWithRetry(execution, this.config, this.runtime);
     const submission = await proof.submit();
     await submission.apply();

package/src/transaction/summary.ts

@@ -5,8 +5,10 @@ import type {
   WasmWebClient,
 } from '@miden-sdk/miden-sdk';
 import { AccountId, ChainAnchor, Word } from '@miden-sdk/miden-sdk';
+import { BoundBlockNotDeclaredError } from '../multisig/authArgErrors.js';
 import { getRawMidenClient } from '../raw-client.js';
 import { base64ToUint8Array, normalizeHexWord, uint8ArrayToBase64 } from '../utils/encoding.js';
+import { requestBoundBlockNum } from './authArgs.js';
 
 /**
  * Layout of the six user params a multisig auth component binds into the
@@ -37,17 +39,51 @@ export class SummaryAnchorMismatchError extends Error {
 }
 
 /**
- * Captures a `ChainAnchor` for the request at the current sync height and
- * executes the transaction against it to obtain the summary awaiting
- * authorization. The anchor is returned alongside the summary so the proposer
- * can ship it with the signed data; cosigners and the executor then reproduce
- * the summary with {@link executeForSummaryAt} regardless of their own sync
- * height.
+ * The Miden client synced and its node still has not produced the block a
+ * proposal binds, so the proposal cannot execute at this client's tip yet.
+ * Worth retrying once the node catches up.
+ */
+export class ChainBehindBoundBlockError extends Error {
+  readonly retryable = true;
+  readonly syncHeight: number;
+  readonly boundBlockNum: number;
+
+  constructor(details: { syncHeight: number; boundBlockNum: number }) {
+    super(
+      `the Miden client synced to block ${details.syncHeight}, below block ` +
+        `${details.boundBlockNum} the proposal binds; its node has not reached that block yet`,
+    );
+    this.name = 'ChainBehindBoundBlockError';
+    this.syncHeight = details.syncHeight;
+    this.boundBlockNum = details.boundBlockNum;
+  }
+}
+
+/**
+ * Whether a failed re-execution came from chain state this client can catch up
+ * with rather than from the proposal itself: a node that has not reached the
+ * bound block yet, or account state the node pruned because this client had
+ * not synced recently. Either clears on a later attempt, which syncs first.
+ */
+export function isStaleChainError(error: unknown): boolean {
+  if (error instanceof ChainBehindBoundBlockError) {
+    return true;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes('has been pruned');
+}
+
+/**
+ * Derives the summary awaiting authorization for a proposal the caller is
+ * creating now, and captures a `ChainAnchor` at the current sync height to ship
+ * with it.
  *
- * The request's auth args bind the block its summary commits to, and this
- * package pins that block to the anchor: a proposer builds at the sync height
- * the anchor is captured at, and a rebuild passes the anchor's block number.
- * The check below is what makes the first half hold.
+ * The summary is derived at the chain tip, like every other execution of a
+ * multisig proposal (see {@link executeForSummaryAtTip}). The anchor still
+ * travels in the proposal: it names the block the request's auth args bind,
+ * which is how a rebuild learns that block, and 0.18.0-rc.1 clients re-execute
+ * at it. A proposer builds at the sync height the anchor is captured at, and
+ * the check below is what makes that hold.
  */
 export function executeForSummary(
   client: MidenClient,
@@ -67,12 +103,11 @@ export async function executeForSummary(
   txRequest: TransactionRequest,
   midenRpcEndpoint?: string,
 ): Promise<{ summary: TransactionSummary; anchor: ChainAnchor }> {
-  const acc = AccountId.fromHex(accountId);
   const rawClient = await getRawMidenClient(client, midenRpcEndpoint);
   const anchor = await rawClient.chainAnchorForRequest(txRequest);
   let summary: TransactionSummary;
   try {
-    summary = await rawClient.executeForSummaryAt(acc, txRequest, anchor);
+    summary = await executeForSummaryAtTip(rawClient, accountId, txRequest);
   } catch (error) {
     anchor.free();
     throw error;
@@ -91,11 +126,120 @@ export async function executeForSummary(
   return { summary, anchor };
 }
 
+/**
+ * Executes a multisig request at the chain tip to obtain the summary awaiting
+ * authorization. This is how cosigners and the executor reproduce a proposal's
+ * summary, whatever block they have synced to.
+ *
+ * Since protocol 0.17 a multisig summary binds the block its auth args name
+ * (the bound block), not the block the transaction executes against, so it
+ * reproduces at any later tip once the bound block is in the transaction's
+ * partial blockchain. The request declares it through `withBlockNumbers`, and
+ * foreign accounts, the fee faucet among them, load at the tip. Re-executing at
+ * the proposal's anchor instead loads them at the bound block, which a node
+ * prunes about 50 blocks later (issue #462).
+ *
+ * The client has to have synced to at least the bound block. When it has not,
+ * this syncs once before executing.
+ *
+ * @throws BoundBlockNotDeclaredError when the request binds a block in its
+ *   multisig auth args without declaring it.
+ */
+export function executeForSummaryAtTip(
+  client: MidenClient,
+  accountId: string,
+  txRequest: TransactionRequest,
+  midenRpcEndpoint: string,
+): Promise<TransactionSummary>;
+export function executeForSummaryAtTip(
+  client: WasmWebClient,
+  accountId: string,
+  txRequest: TransactionRequest,
+  midenRpcEndpoint?: string,
+): Promise<TransactionSummary>;
+export async function executeForSummaryAtTip(
+  client: MidenClient | WasmWebClient,
+  accountId: string,
+  txRequest: TransactionRequest,
+  midenRpcEndpoint?: string,
+): Promise<TransactionSummary> {
+  const rawClient = await getRawMidenClient(client, midenRpcEndpoint);
+  await prepareTipExecution(rawClient, txRequest);
+  return rawClient.executeForSummary(AccountId.fromHex(accountId), txRequest);
+}
+
+/**
+ * Gets `client` ready to execute `request` at the chain tip: checks the
+ * request declares the block its multisig auth args bind, and syncs to that
+ * block (see {@link syncToBoundBlock}).
+ *
+ * @throws BoundBlockNotDeclaredError when the request binds a block in its
+ *   multisig auth args without declaring it.
+ */
+export async function prepareTipExecution(
+  client: WasmWebClient,
+  request: TransactionRequest,
+  syncState?: () => Promise<unknown>,
+): Promise<void> {
+  const boundBlockNum = requireDeclaredBoundBlock(request);
+  if (boundBlockNum !== undefined) {
+    await syncToBoundBlock(client, boundBlockNum, syncState);
+  }
+}
+
+/**
+ * The block `request`'s multisig auth args bind, after checking the request
+ * declares it. `undefined` for a request without multisig auth args, which
+ * has no bound block to declare.
+ *
+ * @throws BoundBlockNotDeclaredError when the block is bound but not declared.
+ */
+export function requireDeclaredBoundBlock(request: TransactionRequest): number | undefined {
+  const boundBlockNum = requestBoundBlockNum(request);
+  if (boundBlockNum !== undefined && !request.blockNumbers().includes(boundBlockNum)) {
+    throw new BoundBlockNotDeclaredError(boundBlockNum);
+  }
+  return boundBlockNum;
+}
+
+/**
+ * Syncs `client` once when its sync height is below `blockNum`, the block a
+ * proposal binds. Execution at a tip below it fails with "requested block N is
+ * after transaction reference block M", and a store that has never synced (a
+ * cosigner that has only just loaded the account) holds no header to rebuild
+ * the request from. `syncState` lets a caller wrap the sync in its own retry
+ * policy.
+ *
+ * This does not make a store that is already past the bound block current. An
+ * execution loads foreign accounts, the fee faucet among them, at the store's
+ * sync height, which a node prunes about 50 blocks later, so the multisig
+ * entry points that re-execute a proposal sync the chain first.
+ *
+ * @throws ChainBehindBoundBlockError when the node has not reached the block.
+ */
+export async function syncToBoundBlock(
+  client: WasmWebClient,
+  blockNum: number,
+  syncState: () => Promise<unknown> = () => client.syncState(),
+): Promise<void> {
+  if ((await client.getSyncHeight()) >= blockNum) {
+    return;
+  }
+  await syncState();
+  const syncHeight = await client.getSyncHeight();
+  if (syncHeight < blockNum) {
+    throw new ChainBehindBoundBlockError({ syncHeight, boundBlockNum: blockNum });
+  }
+}
+
 /**
  * Executes a transaction at the given `ChainAnchor`'s reference block to
- * obtain the summary awaiting authorization: the anchored counterpart of
- * {@link executeForSummary} for cosigners and executors holding a proposal's
- * anchor.
+ * obtain the summary awaiting authorization.
+ *
+ * For a summary that binds the reference block, such as a single-signature
+ * one. A multisig proposal's summary binds its bound block instead and is
+ * reproduced with {@link executeForSummaryAtTip}: re-executing it at an anchor
+ * fails once the node prunes the anchor block's account state.
  */
 export function executeForSummaryAt(
   client: MidenClient,
@@ -134,7 +278,8 @@ export function chainAnchorToBase64(anchor: ChainAnchor): string {
  * Deserializes a `ChainAnchor` from its base64 wire form. `ChainAnchor`
  * deserialization validates the header/chain consistency internally, so a
  * decoded anchor only needs its block commitment checked against the signed
- * transaction summary before it is safe to execute against.
+ * transaction summary before the block it names is taken as the one the
+ * summary binds.
  */
 export function chainAnchorFromBase64(anchorBase64: string): ChainAnchor {
   return ChainAnchor.deserialize(base64ToUint8Array(anchorBase64));

package/src/transaction.ts

@@ -10,11 +10,17 @@ export {
   buildConsumeNotesTransactionRequestFromNotes,
 } from './transaction/consumeNotes.js';
 export {
+  ChainBehindBoundBlockError,
   chainAnchorBlockNum,
   chainAnchorFromBase64,
   chainAnchorToBase64,
   executeForSummary,
   executeForSummaryAt,
+  executeForSummaryAtTip,
+  prepareTipExecution,
+  isStaleChainError,
+  requireDeclaredBoundBlock,
+  syncToBoundBlock,
   summaryApprovalExpirationBlockNum,
   summarySalt,
   SummaryAnchorMismatchError,