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

package/src/transaction/summary.ts

@@ -5,23 +5,85 @@ 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, uint8ArrayToBase64 } from '../utils/encoding.js';
+import { base64ToUint8Array, normalizeHexWord, uint8ArrayToBase64 } from '../utils/encoding.js';
+import { requestBoundBlockNum } from './authArgs.js';
 
 /**
- * Index of the first user param carrying the auth args. The guarded-multisig
- * auth component zeroes user params 0-2 and fills 3-6 with the auth args, matching
- * `push.0.0.0` ahead of `multisig::auth_tx` in `guarded_multisig.masm`.
+ * Layout of the six user params a multisig auth component binds into the
+ * transaction summary since protocol 0.17: the approval expiration block (or
+ * zero for an approval that never expires), a zero, then the four salt felts.
  */
-const AUTH_ARG_USER_PARAM_OFFSET = 3;
+const APPROVAL_EXPIRATION_USER_PARAM_INDEX = 0;
+const SALT_USER_PARAM_OFFSET = 2;
 
 /**
- * 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 — which binds the reference block commitment since protocol
- * 0.16 — with {@link executeForSummaryAt} regardless of their own sync height.
+ * The summary binds the block the request's auth args name, and the anchor
+ * the store's sync height at capture. A sync landing between the build and the
+ * capture leaves them one block apart, and every cosigner's anchor check would
+ * then fail on a proposal nothing else is wrong with. Caught here, before the
+ * proposal is pushed, so the proposer rebuilds instead.
+ */
+export class SummaryAnchorMismatchError extends Error {
+  readonly retryable = true;
+
+  constructor(details: { anchorCommitmentHex: string; summaryBlockCommitmentHex: string }) {
+    super(
+      `the transaction summary binds block commitment ${details.summaryBlockCommitmentHex} but ` +
+        `the captured chain anchor is ${details.anchorCommitmentHex}; a sync landed between ` +
+        'building the request and capturing its anchor, so rebuild the request and retry',
+    );
+    this.name = 'SummaryAnchorMismatchError';
+  }
+}
+
+/**
+ * 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 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,
@@ -41,18 +103,143 @@ 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);
-  const summary = await rawClient.executeForSummaryAt(acc, txRequest, anchor);
+  let summary: TransactionSummary;
+  try {
+    summary = await executeForSummaryAtTip(rawClient, accountId, txRequest);
+  } catch (error) {
+    anchor.free();
+    throw error;
+  }
+
+  const anchorCommitment = anchor.commitment();
+  const summaryBlockCommitment = summary.blockCommitment();
+  const anchorCommitmentHex = normalizeHexWord(anchorCommitment.toHex());
+  const summaryBlockCommitmentHex = normalizeHexWord(summaryBlockCommitment.toHex());
+  anchorCommitment.free?.();
+  summaryBlockCommitment.free?.();
+  if (anchorCommitmentHex !== summaryBlockCommitmentHex) {
+    anchor.free();
+    throw new SummaryAnchorMismatchError({ anchorCommitmentHex, summaryBlockCommitmentHex });
+  }
   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,
@@ -91,26 +278,48 @@ 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));
 }
 
 /**
- * Reads the auth args back out of a transaction summary.
- *
- * Since miden-protocol 0.16-rc the summary binds seven user-defined elements
- * instead of a dedicated salt word. The guarded-multisig auth component zeroes
- * the leading three and passes the auth args as the trailing four, so the auth
- * args are the tail of `userParams()`.
+ * The block a proposal's `chainAnchor` names, which is the block its summary
+ * binds: a custom producer rebuilds its request at this block. Decodes the
+ * anchor for the one number and frees it.
+ */
+export function chainAnchorBlockNum(anchorBase64: string): number {
+  const anchor = chainAnchorFromBase64(anchorBase64);
+  try {
+    return anchor.blockNum();
+  } finally {
+    anchor.free();
+  }
+}
+
+/**
+ * Reads the salt a multisig transaction summary binds.
  *
- * This is the auth-arg word, *not* the proposal salt. When the request declares
- * a fee conversion salt, miden-client uses it to commit the native conversion
- * info under `hash(CONVERSION_INFO || SALT)`. That commitment is not invertible
- * to the salt. Keep the salt alongside the proposal — `ProposalMetadata.saltHex`
- * — rather than trying to recover it from the summary.
+ * Since protocol 0.17 the multisig auth components bind the salt itself into
+ * the summary's user params rather than a commitment derived from it, so the
+ * value cosigners signed over is readable again. A proposal still carries the
+ * salt in its metadata, because a request has to be rebuilt before any summary
+ * exists; this reader is the cross-check that the two agree.
+ */
+export function summarySalt(summary: TransactionSummary): Word {
+  return Word.newFromFelts(
+    summary.userParams().slice(SALT_USER_PARAM_OFFSET, SALT_USER_PARAM_OFFSET + 4),
+  );
+}
+
+/**
+ * Reads the block at which the approvers' signatures stop authorizing the
+ * transaction, or `undefined` for an approval that never expires, which is
+ * what this package's builders produce.
  */
-export function summaryAuthArg(summary: TransactionSummary): Word {
-  return Word.newFromFelts(summary.userParams().slice(AUTH_ARG_USER_PARAM_OFFSET));
+export function summaryApprovalExpirationBlockNum(summary: TransactionSummary): number | undefined {
+  const value = summary.userParams()[APPROVAL_EXPIRATION_USER_PARAM_INDEX].asInt();
+  return value === 0n ? undefined : Number(value);
 }

package/src/transaction/updateGuardian.ts

@@ -1,17 +1,15 @@
 import {
   type MidenClient,
   TransactionRequest,
-  TransactionRequestBuilder,
   TransactionScript,
   type WasmWebClient,
   Word,
-  Word as WordType,
 } from '@miden-sdk/miden-sdk';
 import { compileTxScript } from '../raw-client.js';
 import { normalizeHexWord } from '../utils/encoding.js';
-import { randomWord } from '../utils/random.js';
 import { authSchemeId } from '../utils/signature.js';
-import type { MidenClientSignatureOptions, SignatureOptions } from './options.js';
+import { buildMultisigRequest, multisigRequestBuilder } from './authArgs.js';
+import type { MidenClientMultisigRequestOptions, MultisigRequestOptions } from './options.js';
 import type { SignatureScheme } from '../types.js';
 
 async function buildUpdateGuardianScript(
@@ -44,17 +42,17 @@ end
 export function buildUpdateGuardianTransactionRequest(
   client: MidenClient,
   newGuardianPubkey: string,
-  options: MidenClientSignatureOptions,
+  options: MidenClientMultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }>;
 export function buildUpdateGuardianTransactionRequest(
   client: WasmWebClient,
   newGuardianPubkey: string,
-  options?: SignatureOptions,
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }>;
 export async function buildUpdateGuardianTransactionRequest(
   client: MidenClient | WasmWebClient,
   newGuardianPubkey: string,
-  options: SignatureOptions = {},
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }> {
   const signatureScheme = options.signatureScheme ?? 'falcon';
   const script = await buildUpdateGuardianScript(
@@ -64,24 +62,12 @@ export async function buildUpdateGuardianTransactionRequest(
     options.midenRpcEndpoint,
   );
 
-  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  let txBuilder = new TransactionRequestBuilder();
-  txBuilder = txBuilder.withCustomScript(script);
-  txBuilder = txBuilder.withFeeConversionSalt(authSaltForBuilder);
-  // Borrows rather than consumes: the glue passes `__wbg_ptr` without taking it,
-  // so the handle stays ours to release once the builder has read it.
-  authSaltForBuilder.free?.();
+  const { builder, saltHex } = await multisigRequestBuilder(client, options);
+  let txBuilder = builder.withCustomScript(script);
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
   }
 
-  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  return {
-    request: txBuilder.build(),
-    salt: authSaltForReturn,
-  };
+  return buildMultisigRequest(txBuilder, saltHex, options.accountId);
 }

package/src/transaction/updateProcedureThreshold.ts

@@ -4,7 +4,6 @@ import {
   type MidenClient,
   Poseidon2,
   TransactionRequest,
-  TransactionRequestBuilder,
   TransactionScript,
   type WasmWebClient,
   Word,
@@ -13,8 +12,8 @@ import {
 import { getProcedureRoot, type ProcedureName } from '../procedures.js';
 import { compileTxScript } from '../raw-client.js';
 import { normalizeHexWord } from '../utils/encoding.js';
-import { randomWord } from '../utils/random.js';
-import type { MidenClientSignatureOptions, SignatureOptions } from './options.js';
+import { buildMultisigRequest, multisigRequestBuilder } from './authArgs.js';
+import type { MidenClientMultisigRequestOptions, MultisigRequestOptions } from './options.js';
 
 function buildProcedureThresholdFelts(procedure: ProcedureName, threshold: number): Felt[] {
   const procedureRoot = WordType.fromHex(normalizeHexWord(getProcedureRoot(procedure)));
@@ -66,19 +65,19 @@ export function buildUpdateProcedureThresholdTransactionRequest(
   client: MidenClient,
   procedure: ProcedureName,
   threshold: number,
-  options: MidenClientSignatureOptions,
+  options: MidenClientMultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }>;
 export function buildUpdateProcedureThresholdTransactionRequest(
   client: WasmWebClient,
   procedure: ProcedureName,
   threshold: number,
-  options?: SignatureOptions,
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }>;
 export async function buildUpdateProcedureThresholdTransactionRequest(
   client: MidenClient | WasmWebClient,
   procedure: ProcedureName,
   threshold: number,
-  options: SignatureOptions = {},
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }> {
   const configHash = buildProcedureThresholdConfigHash(procedure, threshold);
 
@@ -88,23 +87,12 @@ export async function buildUpdateProcedureThresholdTransactionRequest(
     threshold,
     options.midenRpcEndpoint,
   );
-  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-  const authSalt = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  let txBuilder = new TransactionRequestBuilder();
-  txBuilder = txBuilder.withCustomScript(script);
-  txBuilder = txBuilder.withFeeConversionSalt(authSalt);
-  // Borrows rather than consumes: the glue passes `__wbg_ptr` without taking it,
-  // so the handle stays ours to release once the builder has read it.
-  authSalt.free?.();
+  const { builder, saltHex } = await multisigRequestBuilder(client, options);
+  let txBuilder = builder.withCustomScript(script);
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
   }
 
-  return {
-    request: txBuilder.build(),
-    salt: WordType.fromHex(normalizeHexWord(authSaltHex)),
-    configHash,
-  };
+  return { ...buildMultisigRequest(txBuilder, saltHex, options.accountId), configHash };
 }

package/src/transaction/updateSigners.ts

@@ -5,7 +5,6 @@ import {
   type MidenClient,
   Poseidon2,
   TransactionRequest,
-  TransactionRequestBuilder,
   TransactionScript,
   type WasmWebClient,
   Word,
@@ -13,9 +12,9 @@ import {
 } from '@miden-sdk/miden-sdk';
 import { compileTxScript } from '../raw-client.js';
 import { normalizeHexWord } from '../utils/encoding.js';
-import { randomWord } from '../utils/random.js';
 import { authSchemeId } from '../utils/signature.js';
-import type { MidenClientSignatureOptions, SignatureOptions } from './options.js';
+import { buildMultisigRequest, multisigRequestBuilder } from './authArgs.js';
+import type { MidenClientMultisigRequestOptions, MultisigRequestOptions } from './options.js';
 import type { SignatureScheme } from '../types.js';
 
 function buildMultisigConfigFelts(
@@ -77,19 +76,19 @@ export function buildUpdateSignersTransactionRequest(
   client: MidenClient,
   threshold: number,
   signerCommitments: string[],
-  options: MidenClientSignatureOptions,
+  options: MidenClientMultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }>;
 export function buildUpdateSignersTransactionRequest(
   client: WasmWebClient,
   threshold: number,
   signerCommitments: string[],
-  options?: SignatureOptions,
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }>;
 export async function buildUpdateSignersTransactionRequest(
   client: MidenClient | WasmWebClient,
   threshold: number,
   signerCommitments: string[],
-  options: SignatureOptions = {},
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }> {
   const signatureScheme = options.signatureScheme ?? 'falcon';
   const { configHash: configHashForAdvice, payload } = buildMultisigConfigAdvice(
@@ -115,28 +114,18 @@ export async function buildUpdateSignersTransactionRequest(
 
   const script = await buildUpdateSignersScript(client, options.midenRpcEndpoint);
 
-  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-
-  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  let txBuilder = new TransactionRequestBuilder();
-  txBuilder = txBuilder.withCustomScript(script);
-  txBuilder = txBuilder.withScriptArg(configHashForScript);
-  txBuilder = txBuilder.extendAdviceMap(advice);
-  txBuilder = txBuilder.withFeeConversionSalt(authSaltForBuilder);
-  // Borrows rather than consumes: the glue passes `__wbg_ptr` without taking it,
-  // so the handle stays ours to release once the builder has read it.
-  authSaltForBuilder.free?.();
+  const { builder, saltHex } = await multisigRequestBuilder(client, options);
+  let txBuilder = builder
+    .withCustomScript(script)
+    .withScriptArg(configHashForScript)
+    .extendAdviceMap(advice);
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
   }
 
-  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
-
   return {
-    request: txBuilder.build(),
-    salt: authSaltForReturn,
+    ...buildMultisigRequest(txBuilder, saltHex, options.accountId),
     configHash: configHashForReturn,
   };
 }

package/src/transaction.ts

@@ -1,12 +1,29 @@
+export {
+  MAX_APPROVAL_EXPIRATION_DELTA,
+  buildMultisigRequest,
+  multisigRequestBuilder,
+  requestBoundBlockNum,
+  requestSaltHex,
+} from './transaction/authArgs.js';
 export {
   buildConsumeNotesTransactionRequest,
+  buildConsumeNotesTransactionRequestFromNotes,
 } from './transaction/consumeNotes.js';
 export {
+  ChainBehindBoundBlockError,
+  chainAnchorBlockNum,
   chainAnchorFromBase64,
   chainAnchorToBase64,
   executeForSummary,
   executeForSummaryAt,
-  summaryAuthArg,
+  executeForSummaryAtTip,
+  prepareTipExecution,
+  isStaleChainError,
+  requireDeclaredBoundBlock,
+  syncToBoundBlock,
+  summaryApprovalExpirationBlockNum,
+  summarySalt,
+  SummaryAnchorMismatchError,
 } from './transaction/summary.js';
 export {
   buildP2idNoteFromMetadata,

package/src/types/proposal.ts

@@ -38,11 +38,11 @@ interface BaseProposalMetadata {
   saltHex?: string;
   requiredSignatures?: number;
   /**
-   * Base64-serialized Miden `ChainAnchor` pinning the reference block the
-   * proposal's transaction summary was built at. Required to verify or
-   * execute the proposal: since protocol 0.16 the signed summary binds the
-   * reference block commitment, so it only reproduces when re-executed at
-   * that block.
+   * Base64-serialized Miden `ChainAnchor` at the block the proposal's
+   * transaction summary binds, the proposer's sync height when it built the
+   * request. Required, and checked against the summary's block commitment: a
+   * rebuild binds the block it names. The proposal executes at the chain tip,
+   * not at the anchor; 0.18.0-rc.1 clients still re-execute at it.
    */
   chainAnchor?: string;
 }
@@ -162,6 +162,36 @@ export interface Proposal {
   txSummary: string;
   signatures: ProposalSignatureEntry[];
   metadata: ProposalMetadata;
+  /**
+   * Result of the last summary-binding check on this value. Only the check
+   * itself writes `verified`; a freshly parsed or imported proposal is
+   * `unchecked`. `syncProposals` surfaces failed proposals instead of
+   * failing wholesale (issue #462); `signProposal` and `executeProposal`
+   * re-verify and refuse them.
+   */
+  verification: ProposalVerification;
+}
+
+/**
+ * Outcome of checking a proposal's metadata against its signed summary.
+ * `failed.retryable` is true when the failure came from a transient node or
+ * RPC error, or from chain state this client had not caught up with, so the
+ * same proposal may verify on a later sync; false when the proposal itself
+ * cannot be reproduced (tampered metadata, for example) and it has to be
+ * re-proposed.
+ */
+export type ProposalVerification =
+  | { status: 'unchecked' }
+  | { status: 'verified' }
+  | { status: 'failed'; retryable: boolean; message: string };
+
+/**
+ * True when the proposal is both verified and has met its signature
+ * threshold, i.e. it can be executed. `status` alone keeps meaning
+ * "threshold met": a fully signed proposal can still be dead.
+ */
+export function isProposalActionable(proposal: Proposal): boolean {
+  return proposal.verification.status === 'verified' && proposal.status === 'ready';
 }
 
 export interface TransactionProposal {
@@ -185,6 +215,7 @@ export interface ExportedProposal {
     signatureHex: string;
     scheme?: SignatureScheme;
     publicKey?: string;
+    messageFormat?: 'eip712';
     timestamp?: string;
   }>;
   metadata: ProposalMetadata;