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

package/src/multisig.ts

@@ -5,7 +5,7 @@
  * for proposal management.
  */
 
-import { GuardianHttpClient, type AbandonCandidateResponse, type AbandonStatus, type DeltaObject, type ProposalSignature, type Signer, type AuthConfig, type StateObject } from '@openzeppelin/guardian-client';
+import { GuardianHttpClient, type AbandonCandidateResponse, type AbandonStatus, type DeltaObject, type HistoryOptions, type HistoryPage, type ProposalSignature, type Signer, type AuthConfig, type StateObject } from '@openzeppelin/guardian-client';
 import type {
   ConsumableNote,
   ExportedProposal,
@@ -36,9 +36,14 @@ import {
   TransactionRequest,
   TransactionSummary,
   Word,
+  type ChainAnchor,
 } from '@miden-sdk/miden-sdk';
 import {
+  chainAnchorFromBase64,
+  chainAnchorToBase64,
   executeForSummary,
+  executeForSummaryAt,
+  summarySalt,
   buildUpdateSignersTransactionRequest,
   buildUpdateProcedureThresholdTransactionRequest,
   buildUpdateGuardianTransactionRequest,
@@ -47,6 +52,7 @@ import {
   buildP2idTransactionRequest,
   parseP2idNoteType,
   p2idNoteTypeToMetadata,
+  type P2ideHeightOptions,
 } from './transaction.js';
 import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
 import {
@@ -67,6 +73,7 @@ import {
   normalizeHexWord,
 } from './utils/encoding.js';
 import {
+  assertEcdsaSignatureRecoverable,
   buildSignatureAdviceEntry,
   normalizeSignerCommitment,
   signatureHexToBytes,
@@ -74,7 +81,7 @@ import {
 } from './utils/signature.js';
 import { computeCommitmentFromTxSummary, accountIdToHex } from './multisig/helpers.js';
 import { buildGuardianSignatureFromSigner } from './multisig/signing.js';
-import { AccountInspector } from './inspector.js';
+import { AccountInspector, assertCompleteDetectedConfig } from './inspector.js';
 import { ProposalFactory } from './proposal/factory.js';
 import { ProposalMetadataCodec } from './proposal/metadata.js';
 import { ProposalSignatures } from './proposal/signatures.js';
@@ -88,6 +95,11 @@ import {
   type ResolvedProverConfig,
 } from './prover/config.js';
 import { ProverWorkflow } from './prover/workflow.js';
+import {
+  resolveRpcConfig,
+  type ResolvedRpcConfig,
+} from './rpc/config.js';
+import { retryRpcRead } from './rpc/retry.js';
 
 /**
  * Result of fetching account state from GUARDIAN.
@@ -109,6 +121,29 @@ export interface AccountStateVerificationResult {
   onChainCommitment: string;
 }
 
+/**
+ * Options shared by the `create*Proposal` family (issue #387). Every optional
+ * knob lives in a single trailing options bag, so call sites never need
+ * positional `undefined` holes to reach a later option.
+ */
+export interface CreateProposalOptions {
+  /** Proposal nonce; defaults to `Date.now()`. */
+  nonce?: number;
+}
+
+export interface CreateSignerProposalOptions extends CreateProposalOptions {
+  /**
+   * New signing threshold. Defaults to the current threshold on add, and to
+   * `min(current threshold, remaining signer count)` on remove.
+   */
+  newThreshold?: number;
+}
+
+export interface CreateP2idProposalOptions extends CreateProposalOptions, P2ideHeightOptions {
+  /** Visibility of the created note. Defaults to `NoteType.Public` (issue #322). */
+  noteType?: NoteType;
+}
+
 /**
  * Represents a multisig account with GUARDIAN integration.
  */
@@ -138,6 +173,27 @@ function deserializeTransactionRequest(bytes: Uint8Array): TransactionRequest {
   }
 }
 
+/**
+ * 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.
+ */
+function resolveProposalNonce(
+  method: string,
+  options: CreateProposalOptions,
+  legacyArgs: readonly unknown[] = [],
+): number {
+  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();
+}
+
 export class Multisig {
   account: Account;
   threshold: number;
@@ -151,6 +207,7 @@ export class Multisig {
   private readonly midenClient: MidenClient;
   private readonly rawClientPromise: Promise<WasmWebClient>;
   private readonly proverWorkflow: ProverWorkflow;
+  private readonly rpcConfig: ResolvedRpcConfig;
   private readonly _accountId: string;
   private readonly midenRpcEndpoint: string;
   private proposals: Map<string, Proposal> = new Map();
@@ -164,6 +221,7 @@ export class Multisig {
     accountId: string | undefined,
     midenRpcEndpoint: string,
     proverConfig?: ResolvedProverConfig,
+    rpcConfig?: ResolvedRpcConfig,
   ) {
     this.account = account;
     this.threshold = config.threshold;
@@ -183,6 +241,7 @@ export class Multisig {
       this.midenClient,
       proverConfig ?? resolveProverConfig(undefined, getTransactionProver(midenClient)),
     );
+    this.rpcConfig = rpcConfig ?? resolveRpcConfig(undefined);
   }
 
   private getMidenRpcEndpoint(): string {
@@ -238,7 +297,37 @@ export class Multisig {
    */
   async getStoreAccount(): Promise<Account> {
     const webClient = await this.getRawClient();
-    return (await webClient.getAccount(AccountId.fromHex(this._accountId))) ?? this.account;
+    const stored = await retryRpcRead(
+      () => webClient.getAccount(AccountId.fromHex(this._accountId)),
+      this.rpcConfig,
+    );
+    return stored ?? this.account;
+  }
+
+  /**
+   * Read the current ordered signer public-key commitments from account
+   * storage (store-backed state, falling back to the snapshot).
+   *
+   * Commitments are ordered by signer index as currently stored; indices
+   * re-pack when signers are removed, so index 0 is the creation-time first
+   * key only until the first membership change. Unlike the
+   * `signerCommitments` field, which reflects the config detected at
+   * construction / last sync, this reads the account state directly.
+   * See `AccountInspector.getSignerPublicKeyCommitments` (issue #306).
+   */
+  async getSignerPublicKeyCommitments(): Promise<string[]> {
+    const account = await this.getStoreAccount();
+    return AccountInspector.getSignerPublicKeyCommitments(account);
+  }
+
+  /**
+   * Read the current guardian public-key commitment from account storage.
+   * The guarded-multisig always includes a guardian, so this throws (rather
+   * than returning null) when the entry is missing.
+   */
+  async getGuardianPublicKeyCommitment(): Promise<string> {
+    const account = await this.getStoreAccount();
+    return AccountInspector.getGuardianPublicKeyCommitment(account);
   }
 
   /**
@@ -283,6 +372,43 @@ export class Multisig {
     return this.procedureThresholds.get(procedure) ?? this.threshold;
   }
 
+  /**
+   * Per-procedure threshold overrides whose effective signing ratio is diluted
+   * by growing the signer set to `newNumSigners`.
+   *
+   * Overrides are absolute signature counts, not ratios, and the on-chain
+   * `update_signers_and_threshold` procedure does not re-scale them: growing
+   * the approver set silently lowers every override's effective signing ratio
+   * (a 2-of-2 override becomes 2-of-n). Callers creating a proposal that grows
+   * the signer set should surface these overrides and suggest raising them via
+   * an update-procedure-threshold proposal alongside the growth.
+   *
+   * @param newNumSigners - Signer-set size the proposal produces
+   * @returns The configured overrides, or an empty list when the set does not grow
+   */
+  overridesDilutedBySignerGrowth(
+    newNumSigners: number,
+  ): Array<{ procedure: ProcedureName; threshold: number }> {
+    if (newNumSigners <= this.signerCommitments.length) {
+      return [];
+    }
+    return Array.from(this.procedureThresholds.entries()).map(([procedure, threshold]) => ({
+      procedure,
+      threshold,
+    }));
+  }
+
+  private warnOnOverrideDilution(newNumSigners: number): void {
+    const current = this.signerCommitments.length;
+    for (const { procedure, threshold } of this.overridesDilutedBySignerGrowth(newNumSigners)) {
+      console.warn(
+        `growing the signer set dilutes the ${procedure} threshold override ` +
+          `(${threshold}-of-${current} becomes ${threshold}-of-${newNumSigners}); consider raising it ` +
+          `via an update-procedure-threshold proposal alongside the signer update`,
+      );
+    }
+  }
+
   /**
    * Update the GUARDIAN client used by this Multisig instance.
    *
@@ -326,7 +452,10 @@ export class Multisig {
     const state = await this.fetchState();
     const accountId = AccountId.fromHex(this._accountId);
     const webClient = await this.getRawClient();
-    const localAccount = await webClient.getAccount(accountId);
+    const localAccount = await retryRpcRead(
+      () => webClient.getAccount(accountId),
+      this.rpcConfig,
+    );
     let accountForConfigRefresh: Account | null = localAccount ?? null;
 
     const guardianCommitment = normalizeHexWord(state.commitment);
@@ -351,7 +480,10 @@ export class Multisig {
   async verifyStateCommitment(): Promise<AccountStateVerificationResult> {
     const accountId = AccountId.fromHex(this._accountId);
     const webClient = await this.getRawClient();
-    const localAccount = await webClient.getAccount(accountId);
+    const localAccount = await retryRpcRead(
+      () => webClient.getAccount(accountId),
+      this.rpcConfig,
+    );
 
     if (!localAccount) {
       throw new Error(
@@ -434,7 +566,10 @@ export class Multisig {
     const rpcClient = new RpcClient(new Endpoint(this.getMidenRpcEndpoint()));
 
     try {
-      const accountDetails = await rpcClient.getAccountDetails(accountId);
+      const accountDetails = await retryRpcRead(
+        () => rpcClient.getAccountDetails(accountId),
+        this.rpcConfig,
+      );
       // If the account is not found or its commitment is zero, means that the account is not deployed yet
       if (!accountDetails) {
         return null;
@@ -465,12 +600,14 @@ export class Multisig {
 
     try {
       const detected = AccountInspector.fromAccount(account);
+      // Fail closed on a partial read: adopting a truncated signer set would
+      // let membership proposals rewrite the account without the omitted
+      // keys. The catch below keeps the previously validated config instead.
+      assertCompleteDetectedConfig(detected);
       this.account = account;
       this.threshold = detected.threshold;
       this.signerCommitments = detected.signerCommitments;
-      if (detected.guardianCommitment) {
-        this.guardianCommitment = detected.guardianCommitment;
-      }
+      this.guardianCommitment = detected.guardianCommitment;
       this.procedureThresholds = new Map(detected.procedureThresholds);
     } catch (error) {
       console.warn('Failed to refresh multisig config from account state', error);
@@ -578,17 +715,19 @@ export class Multisig {
    * Create an "add signer" proposal.
    *
    * @param newCommitment - Commitment of the new signer (hex)
-   * @param nonce - Optional proposal nonce (defaults to Date.now())
-   * @param newThreshold - Optional new threshold (defaults to current threshold)
+   * @param options - Optional settings: `nonce`, `newThreshold` (defaults to
+   *   current threshold)
    */
   async createAddSignerProposal(
     newCommitment: string,
-    nonce?: number,
-    newThreshold?: number,
+    options: CreateSignerProposalOptions = {},
+    ...legacyArgs: never[]
   ): Promise<Proposal> {
+    const proposalNonce = resolveProposalNonce('createAddSignerProposal', options, legacyArgs);
     const webClient = await this.getRawClient();
-    const targetThreshold = newThreshold ?? this.threshold;
+    const targetThreshold = options.newThreshold ?? this.threshold;
     const targetSignerCommitments = [...this.signerCommitments, newCommitment];
+    this.warnOnOverrideDilution(targetSignerCommitments.length);
 
     const { request, salt } = await buildUpdateSignersTransactionRequest(
       webClient,
@@ -597,11 +736,13 @@ export class Multisig {
       { signatureScheme: this.signer.scheme },
     );
 
-    const summary = await executeForSummary(webClient, this._accountId, request);
+    const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
+    const chainAnchor = chainAnchorToBase64(anchor);
+    anchor.free();
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-    const proposalNonce = nonce ?? Date.now();
 
     const metadata: ProposalMetadata = {
+      chainAnchor,
       proposalType: 'add_signer',
       targetThreshold,
       targetSignerCommitments,
@@ -617,14 +758,15 @@ export class Multisig {
    * Create a "remove signer" proposal by executing the update_signers script to summary.
    *
    * @param signerToRemove - Commitment of the signer to remove (hex)
-   * @param nonce - Optional proposal nonce (defaults to Date.now())
-   * @param newThreshold - Optional new threshold (defaults to min of current threshold and new signer count)
+   * @param options - Optional settings: `nonce`, `newThreshold` (defaults to
+   *   min of current threshold and new signer count)
    */
   async createRemoveSignerProposal(
     signerToRemove: string,
-    nonce?: number,
-    newThreshold?: number,
+    options: CreateSignerProposalOptions = {},
+    ...legacyArgs: never[]
   ): Promise<Proposal> {
+    const proposalNonce = resolveProposalNonce('createRemoveSignerProposal', options, legacyArgs);
     const webClient = await this.getRawClient();
     const normalizedRemove = signerToRemove.toLowerCase();
     const targetSignerCommitments = this.signerCommitments.filter(
@@ -638,7 +780,7 @@ export class Multisig {
       throw new Error('Cannot remove the last signer');
     }
 
-    const targetThreshold = newThreshold ?? Math.min(this.threshold, targetSignerCommitments.length);
+    const targetThreshold = options.newThreshold ?? Math.min(this.threshold, targetSignerCommitments.length);
 
     if (targetThreshold < 1 || targetThreshold > targetSignerCommitments.length) {
       throw new Error(
@@ -653,11 +795,13 @@ export class Multisig {
       { signatureScheme: this.signer.scheme },
     );
 
-    const summary = await executeForSummary(webClient, this._accountId, request);
+    const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
+    const chainAnchor = chainAnchorToBase64(anchor);
+    anchor.free();
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-    const proposalNonce = nonce ?? Date.now();
 
     const metadata: ProposalMetadata = {
+      chainAnchor,
       proposalType: 'remove_signer',
       targetThreshold,
       targetSignerCommitments,
@@ -673,12 +817,13 @@ export class Multisig {
    * Create a "change threshold" proposal.
    *
    * @param newThreshold - The new threshold value
-   * @param nonce - Optional proposal nonce (defaults to Date.now())
+   * @param options - Optional settings: `nonce`
    */
   async createChangeThresholdProposal(
     newThreshold: number,
-    nonce?: number,
+    options: CreateProposalOptions = {},
   ): Promise<Proposal> {
+    const proposalNonce = resolveProposalNonce('createChangeThresholdProposal', options);
     const webClient = await this.getRawClient();
     if (newThreshold < 1 || newThreshold > this.signerCommitments.length) {
       throw new Error(
@@ -697,11 +842,13 @@ export class Multisig {
       { signatureScheme: this.signer.scheme },
     );
 
-    const summary = await executeForSummary(webClient, this._accountId, request);
+    const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
+    const chainAnchor = chainAnchorToBase64(anchor);
+    anchor.free();
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-    const proposalNonce = nonce ?? Date.now();
 
     const metadata: ProposalMetadata = {
+      chainAnchor,
       proposalType: 'change_threshold',
       targetThreshold: newThreshold,
       targetSignerCommitments: this.signerCommitments,
@@ -716,8 +863,9 @@ export class Multisig {
   async createUpdateProcedureThresholdProposal(
     targetProcedure: ProcedureName,
     targetThreshold: number,
-    nonce?: number,
+    options: CreateProposalOptions = {},
   ): Promise<Proposal> {
+    const proposalNonce = resolveProposalNonce('createUpdateProcedureThresholdProposal', options);
     const webClient = await this.getRawClient();
     if (targetThreshold < 0 || targetThreshold > this.signerCommitments.length) {
       throw new Error(
@@ -743,14 +891,16 @@ export class Multisig {
       { signatureScheme: this.signer.scheme },
     );
 
-    const summary = await executeForSummary(webClient, this._accountId, request);
+    const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
+    const chainAnchor = chainAnchorToBase64(anchor);
+    anchor.free();
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-    const proposalNonce = nonce ?? Date.now();
     const action = targetThreshold === 0
       ? `Clear threshold override for ${targetProcedure}`
       : `Set ${targetProcedure} threshold override to ${targetThreshold}`;
 
     const metadata: ProposalMetadata = {
+      chainAnchor,
       proposalType: 'update_procedure_threshold',
       targetProcedure,
       targetThreshold,
@@ -767,13 +917,14 @@ export class Multisig {
    * 
    * @param newGuardianEndpoint - The new GUARDIAN server endpoint URL
    * @param newGuardianPubkey - The new GUARDIAN server's public key commitment (hex)
-   * @param nonce - Optional proposal nonce (defaults to Date.now())
+   * @param options - Optional settings: `nonce`
    */
   async createSwitchGuardianProposal(
     newGuardianEndpoint: string,
     newGuardianPubkey: string,
-    nonce?: number,
+    options: CreateProposalOptions = {},
   ): Promise<Proposal> {
+    const proposalNonce = resolveProposalNonce('createSwitchGuardianProposal', options);
     const webClient = await this.getRawClient();
     await this.verifyGuardianEndpointCommitment(newGuardianEndpoint, newGuardianPubkey);
 
@@ -783,11 +934,13 @@ export class Multisig {
       { signatureScheme: this.signer.scheme },
     );
 
-    const summary = await executeForSummary(webClient, this._accountId, request);
+    const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
+    const chainAnchor = chainAnchorToBase64(anchor);
+    anchor.free();
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-    const proposalNonce = nonce ?? Date.now();
 
     const metadata: ProposalMetadata = {
+      chainAnchor,
       proposalType: 'switch_guardian',
       saltHex: salt.toHex(),
       requiredSignatures: this.getEffectiveThreshold('switch_guardian'),
@@ -805,12 +958,13 @@ export class Multisig {
    * Create a "consume notes" proposal to consume notes sent to the multisig account.
    *
    * @param noteIds - IDs of the notes to consume (hex strings)
-   * @param nonce - Optional proposal nonce (defaults to Date.now())
+   * @param options - Optional settings: `nonce`
    */
   async createConsumeNotesProposal(
     noteIds: string[],
-    nonce?: number,
+    options: CreateProposalOptions = {},
   ): Promise<Proposal> {
+    const proposalNonce = resolveProposalNonce('createConsumeNotesProposal', options);
     const webClient = await this.getRawClient();
     if (noteIds.length === 0) {
       throw new Error('At least one note ID is required');
@@ -830,11 +984,13 @@ export class Multisig {
 
     const { request, salt } = buildConsumeNotesTransactionRequestFromNotes(fetchedNotes);
 
-    const summary = await executeForSummary(webClient, this._accountId, request);
+    const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
+    const chainAnchor = chainAnchorToBase64(anchor);
+    anchor.free();
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-    const proposalNonce = nonce ?? Date.now();
 
     const metadata: ProposalMetadata = {
+      chainAnchor,
       proposalType: 'consume_notes',
       noteIds,
       metadataVersion: CONSUME_NOTES_METADATA_VERSION_V2,
@@ -863,38 +1019,41 @@ export class Multisig {
    * @param recipientId - Account ID of the recipient (hex string)
    * @param faucetId - Faucet/token account ID (hex string)
    * @param amount - Amount to send
-   * @param nonce - Optional proposal nonce (defaults to Date.now())
-   * @param options - Optional settings; `noteType` selects the created note's
-   *   visibility (defaults to `NoteType.Public`, issue #322)
+   * @param options - Optional settings: `nonce`; `noteType` selects the created
+   *   note's visibility (defaults to `NoteType.Public`, issue #322);
+   *   `reclaimHeight`/`timelockHeight` build a P2IDE note (issue #366)
    */
   async createP2idProposal(
     recipientId: string,
     faucetId: string,
     amount: bigint,
-    nonce?: number,
-    options: { noteType?: NoteType } = {},
+    options: CreateP2idProposalOptions = {},
+    ...legacyArgs: never[]
   ): Promise<Proposal> {
+    const proposalNonce = resolveProposalNonce('createP2idProposal', options, legacyArgs);
     const webClient = await this.getRawClient();
     if (amount <= 0n) {
       throw new Error('Amount must be greater than 0');
     }
 
-    const account = await this.getStoreAccount();
-
+    // Forward everything but the nonce, so a note option added to
+    // CreateP2idProposalOptions can't be silently dropped before the builder.
+    const { nonce: _nonce, ...noteOptions } = options;
     const { request, salt } = buildP2idTransactionRequest(
       this._accountId,
       recipientId,
       faucetId,
       amount,
-      account,
-      { noteType: options.noteType },
+      noteOptions,
     );
 
-    const summary = await executeForSummary(webClient, this._accountId, request);
+    const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
+    const chainAnchor = chainAnchorToBase64(anchor);
+    anchor.free();
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-    const proposalNonce = nonce ?? Date.now();
 
     const metadata: ProposalMetadata = {
+      chainAnchor,
       proposalType: 'p2id',
       saltHex: salt.toHex(),
       requiredSignatures: this.getEffectiveThreshold('p2id'),
@@ -903,6 +1062,9 @@ export class Multisig {
       amount: amount.toString(),
       // Omitted for public notes so the wire shape matches pre-#322 proposals.
       noteType: p2idNoteTypeToMetadata(options.noteType),
+      // Omitted when absent so plain-P2ID payloads keep the pre-#366 wire shape.
+      reclaimHeight: options.reclaimHeight,
+      timelockHeight: options.timelockHeight,
       description: `Send ${amount} of asset ${faucetId.slice(0, 10)}... to ${recipientId.slice(0, 10)}...`,
     };
 
@@ -962,7 +1124,7 @@ export class Multisig {
 
   /**
    * Export a note created by this multisig account as serialized note-file
-   * bytes for out-of-band delivery (issue #356).
+   * bytes for out-of-band delivery.
    *
    * A private note publishes only its commitment on chain, so the recipient
    * can never learn its contents via sync; the sender must hand them the
@@ -1005,7 +1167,7 @@ export class Multisig {
 
   /**
    * Export a note created by this multisig account as a note file downloaded
-   * by the browser (issue #356). Browser-only convenience over
+   * by the browser. Browser-only convenience over
    * {@link exportNoteToBytes}; use that method directly in non-DOM
    * environments.
    *
@@ -1033,7 +1195,7 @@ export class Multisig {
   }
 
   /**
-   * Import a note file received out-of-band (issue #356) so the note can be
+   * Import a note file received out-of-band so the note can be
    * consumed by this multisig account.
    *
    * Sync the Miden client with the network afterwards so the note's on-chain
@@ -1060,7 +1222,7 @@ export class Multisig {
   }
 
   /**
-   * Import a note file received out-of-band (issue #356) from a browser
+   * Import a note file received out-of-band from a browser
    * `File`/`Blob` (e.g. a file-input selection). See
    * {@link importNoteFromBytes} for the returned identifier semantics.
    */
@@ -1075,10 +1237,9 @@ export class Multisig {
    * The P2ID note is rebuilt deterministically from the proposal salt, so the
    * ID is known ahead of execution. For a private P2ID this is the ID to pass
    * to {@link exportNoteToBytes} after executing, so the note file can be delivered
-   * to the recipient out-of-band (issue #356).
+   * to the recipient out-of-band.
    *
-   * Call this before executing the proposal: the asset is derived from the
-   * current vault state, which execution itself changes.
+   * The note ID remains deterministic from the proposal metadata and salt.
    */
   async getP2idNoteId(proposal: Proposal): Promise<string> {
     const metadata = proposal.metadata;
@@ -1092,15 +1253,14 @@ export class Multisig {
       throw new Error('getP2idNoteId requires a P2ID proposal with recipient, faucet, amount, and salt metadata');
     }
 
-    const account = await this.getStoreAccount();
     const note = buildP2idNoteFromMetadata(
       this._accountId,
       metadata.recipientId,
       metadata.faucetId,
       BigInt(metadata.amount),
-      account,
       parseP2idNoteType(metadata.noteType),
       metadata.saltHex,
+      { reclaimHeight: metadata.reclaimHeight, timelockHeight: metadata.timelockHeight },
     );
     return note.id().toString();
   }
@@ -1145,6 +1305,19 @@ export class Multisig {
     return this.guardian.abandonStatus(this._accountId, nonce);
   }
 
+  /**
+   * Fetch one page of this account's canonical delta history
+   * from GUARDIAN (issue #413), newest-first by nonce, with decoded
+   * input/output note summaries. Pass `options.cursor` from a previous
+   * page's `nextCursor` to resume; an absent `nextCursor` means the
+   * feed is exhausted. Served while the account is paused. Only
+   * transactions pushed through GUARDIAN appear — history of
+   * transactions executed elsewhere is not visible to it.
+   */
+  async deltaHistory(options: HistoryOptions = {}): Promise<HistoryPage> {
+    return this.guardian.getDeltaHistory(this._accountId, options);
+  }
+
   async signProposal(proposalId: string): Promise<Proposal> {
     const normalizedProposalId = normalizeHexWord(proposalId);
     const existingProposal = await this.getProposalForSigning(proposalId, normalizedProposalId);
@@ -1206,8 +1379,16 @@ export class Multisig {
   async executeProposal(proposalId: string): Promise<void> {
     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.
     const accountId = AccountId.fromHex(this._accountId);
-    await this.proverWorkflow.submit(accountId, finalRequest);
+    const anchor = this.requireProposalAnchor(proposalId, proposal.metadata);
+    try {
+      await this.proverWorkflow.submitAt(accountId, finalRequest, anchor);
+    } finally {
+      anchor.free();
+    }
 
     if (metadata.proposalType === 'switch_guardian') {
       if (!metadata.newGuardianEndpoint || !metadata.newGuardianPubkey) {
@@ -1228,15 +1409,25 @@ export class Multisig {
           ...switchDelta,
           deltaPayload: switchDelta.deltaPayload.txSummary,
         });
-      } catch {
-        // best-effort; see above
+      } catch (error) {
+        // Best-effort — see above — but the failure must be visible: a
+        // silently lost push leaves the pre-switch GUARDIAN serving this
+        // account (split-brain, issue #305) with nothing to diagnose by.
+        console.warn(
+          'SwitchGuardian delta push to the pre-switch GUARDIAN failed; it ' +
+            'will keep serving this account until reconciliation',
+          error,
+        );
       }
 
       try {
         const webClient = await this.getRawClient();
-        await webClient.syncState();
+        await retryRpcRead(() => webClient.syncState(), this.rpcConfig);
 
-        const updatedAccount = await webClient.getAccount(accountId);
+        const updatedAccount = await retryRpcRead(
+          () => webClient.getAccount(accountId),
+          this.rpcConfig,
+        );
         if (!updatedAccount) {
           throw new Error(
             `Updated account ${this._accountId} is missing from local client`
@@ -1264,14 +1455,42 @@ 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.
    */
-  async submitTransaction(request: TransactionRequest): Promise<void> {
-    await this.proverWorkflow.submit(AccountId.fromHex(this._accountId), request);
+  async submitTransaction(proposalId: string, request: TransactionRequest): Promise<void> {
+    const normalizedProposalId = normalizeHexWord(proposalId);
+    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`,
+        );
+      }
+
+      await this.proverWorkflow.submitAt(AccountId.fromHex(this._accountId), request, anchor);
+    } finally {
+      anchor.free();
+    }
   }
 
   /**
-   * Create a proposal from a producer-built transaction the SDK does not model
-   * (issue #266 producer API). `transactionRequestBytes` is a serialized TransactionRequest;
+   * Create a proposal from a producer-built transaction the SDK does not model.
+   * `transactionRequestBytes` is a serialized TransactionRequest;
    * `proposalType` is a free-form, non-empty label that must not collide with a
    * built-in type. The integration keeps its own recipe to execute later via
    * `prepareCustomExecution`.
@@ -1279,8 +1498,9 @@ export class Multisig {
   async createCustomProposal(
     transactionRequestBytes: Uint8Array,
     proposalType: string,
-    nonce?: number,
+    options: CreateProposalOptions = {},
   ): Promise<Proposal> {
+    const proposalNonce = resolveProposalNonce('createCustomProposal', options);
     const label = proposalType.trim().toLowerCase();
     if (label.length === 0) {
       throw new Error('proposalType must not be empty');
@@ -1298,11 +1518,13 @@ export class Multisig {
 
     const webClient = await this.getRawClient();
     const request = deserializeTransactionRequest(transactionRequestBytes);
-    const summary = await executeForSummary(webClient, this._accountId, request);
+    const { summary, anchor } = await executeForSummary(webClient, this._accountId, request);
+    const chainAnchor = chainAnchorToBase64(anchor);
+    anchor.free();
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-    const proposalNonce = nonce ?? Date.now();
 
     const metadata: ProposalMetadata = {
+      chainAnchor,
       proposalType: 'custom',
       description: '',
       rawProposalType: label,
@@ -1315,7 +1537,7 @@ export class Multisig {
   /**
    * Assemble the validated execution advice (cosigner signatures + GUARDIAN
    * acknowledgment) for a ready custom proposal, so an integration can rebuild
-   * its transaction with its own recipe and submit (issue #266 producer API).
+   * its transaction with its own recipe and submit.
    *
    * `transactionRequestBytes` is the serialized transaction request; it is used only to verify
    * (binding check) that it reproduces the signed commitment, before the
@@ -1361,9 +1583,27 @@ export class Multisig {
 
     const bindingRequest = deserializeTransactionRequest(transactionRequestBytes);
 
-    const webClient = await this.getRawClient();
-    const derived = await executeForSummary(webClient, this._accountId, bindingRequest);
-    const derivedCommitmentHex = normalizeHexWord(derived.toCommitment().toHex());
+    // 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.
+    const anchor = this.requireProposalAnchor(proposalId, proposal.metadata);
+    let derivedCommitmentHex: string;
+    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`,
+        );
+      }
+      const webClient = await this.getRawClient();
+      const derived = await executeForSummaryAt(webClient, this._accountId, bindingRequest, anchor);
+      derivedCommitmentHex = normalizeHexWord(derived.toCommitment().toHex());
+    } finally {
+      anchor.free();
+    }
     if (derivedCommitmentHex !== signedCommitmentHex) {
       throw new Error(
         `Custom proposal binding mismatch: expected ${signedCommitmentHex}, got ${derivedCommitmentHex}`,
@@ -1419,12 +1659,17 @@ export class Multisig {
         cosignerSig.signature.scheme,
       );
       const signature = Signature.deserialize(sigBytes);
+      if (cosignerSig.signature.scheme === 'ecdsa' && ecdsaPublicKey) {
+        assertEcdsaSignatureRecoverable(
+          cosignerSig.signature.signature,
+          normalizedTxCommitmentHex,
+          ecdsaPublicKey,
+        );
+      }
       const { key, values } = buildSignatureAdviceEntry(
         signerCommitment,
         createTxCommitmentWord(),
         signature,
-        ecdsaPublicKey,
-        cosignerSig.signature.scheme === 'ecdsa' ? cosignerSig.signature.signature : undefined,
       );
       const keyHex = normalizeHexWord(key.toHex());
       if (adviceMapKeys.has(keyHex)) {
@@ -1455,12 +1700,13 @@ export class Multisig {
     }
     const ackSigBytes = signatureHexToBytes(ackSigHex, ackScheme);
     const ackSignature = Signature.deserialize(ackSigBytes);
+    if (ackScheme === 'ecdsa' && ackPubkey) {
+      assertEcdsaSignatureRecoverable(ackSigHex, normalizedTxCommitmentHex, ackPubkey);
+    }
     const { key: ackKey, values: ackValues } = buildSignatureAdviceEntry(
       guardianCommitment,
       createTxCommitmentWord(),
       ackSignature,
-      ackScheme === 'ecdsa' ? ackPubkey : undefined,
-      ackScheme === 'ecdsa' ? ackSigHex : undefined,
     );
     const ackKeyHex = normalizeHexWord(ackKey.toHex());
     if (adviceMapKeys.has(ackKeyHex)) {
@@ -1527,7 +1773,7 @@ export class Multisig {
 
     const txSummaryBytes = base64ToUint8Array(txSummaryBase64);
     const txSummary = TransactionSummary.deserialize(txSummaryBytes);
-    const saltHex = txSummary.salt().toHex();
+    const saltHex = summarySalt(txSummary).toHex();
     const txCommitmentHex = txSummary.toCommitment().toHex();
     const normalizedTxCommitmentHex = normalizeHexWord(txCommitmentHex);
     const normalizedSignerCommitments = new Set(
@@ -1568,14 +1814,17 @@ export class Multisig {
         cosignerSig.signature.scheme,
       );
       const signature = Signature.deserialize(sigBytes);
+      if (cosignerSig.signature.scheme === 'ecdsa' && ecdsaPublicKey) {
+        assertEcdsaSignatureRecoverable(
+          cosignerSig.signature.signature,
+          normalizedTxCommitmentHex,
+          ecdsaPublicKey,
+        );
+      }
       const { key, values } = buildSignatureAdviceEntry(
         signerCommitment,
         createTxCommitmentWord(),
         signature,
-        ecdsaPublicKey,
-        cosignerSig.signature.scheme === 'ecdsa'
-          ? cosignerSig.signature.signature
-          : undefined,
       );
       const keyHex = normalizeHexWord(key.toHex());
       if (adviceMapKeys.has(keyHex)) {
@@ -1611,12 +1860,13 @@ export class Multisig {
       }
       const ackSigBytes = signatureHexToBytes(ackSigHex, ackScheme);
       const ackSignature = Signature.deserialize(ackSigBytes);
+      if (ackScheme === 'ecdsa' && ackPubkey) {
+        assertEcdsaSignatureRecoverable(ackSigHex, normalizedTxCommitmentHex, ackPubkey);
+      }
       const { key: ackKey, values: ackValues } = buildSignatureAdviceEntry(
         guardianCommitment,
         createTxCommitmentWord(),
         ackSignature,
-        ackScheme === 'ecdsa' ? ackPubkey : undefined,
-        ackScheme === 'ecdsa' ? ackSigHex : undefined,
       );
       const ackKeyHex = normalizeHexWord(ackKey.toHex());
       if (adviceMapKeys.has(ackKeyHex)) {
@@ -1805,39 +2055,70 @@ export class Multisig {
 
   private async verifyProposalMetadataBinding(proposal: Proposal): Promise<string> {
     const txSummaryCommitment = this.ensureProposalCommitmentMatchesSummary(proposal);
-    if (proposal.metadata.proposalType === 'custom') {
-      // Custom proposals (issue #266) 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;
-    }
-
-    if (proposal.metadata.proposalType === 'switch_guardian') {
-      // Exempt from binding re-execution (mirrors the `custom` exemption above).
-      // The WASM `executeForSummary` leaves the guardian-disabling side effect
-      // applied to the in-session account, so re-execution reconstructs a smaller
-      // delta and falsely rejects with "metadata does not match tx_summary". The
-      // native Rust client does not mutate, so this is an intentional divergence.
-      // The id ↔ tx_summary match above plus `verifyGuardianEndpointCommitment`
-      // at propose/execute time still bind the proposal.
-      return txSummaryCommitment;
-    }
 
     const summary = TransactionSummary.deserialize(base64ToUint8Array(proposal.txSummary));
-    const salt = proposal.metadata.saltHex
-      ? Word.fromHex(normalizeHexWord(proposal.metadata.saltHex))
-      : summary.salt();
 
-    const request = await this.buildTransactionRequestFromMetadata(proposal.metadata, salt);
-    const webClient = await this.getRawClient();
-    const reconstructed = await executeForSummary(webClient, this._accountId, request);
-    const reconstructedCommitment = normalizeHexWord(reconstructed.toCommitment().toHex());
+    // 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.
+    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;
+      }
+
+      if (proposal.metadata.proposalType === 'switch_guardian') {
+        // Re-execution would mutate the WASM account twice. The proposal ID and
+        // guardian endpoint commitment provide the binding checks for this type.
+        return txSummaryCommitment;
+      }
+
+      const salt = proposal.metadata.saltHex
+        ? Word.fromHex(normalizeHexWord(proposal.metadata.saltHex))
+        : summarySalt(summary);
 
-    if (reconstructedCommitment !== txSummaryCommitment) {
-      throw new Error(`Invalid proposal: metadata does not match tx_summary for ${proposal.id}`);
+      const request = await this.buildTransactionRequestFromMetadata(proposal.metadata, salt);
+      const webClient = await this.getRawClient();
+      const reconstructed = await executeForSummaryAt(webClient, this._accountId, request, anchor);
+      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;
+    } finally {
+      anchor.free();
     }
+  }
 
-    return txSummaryCommitment;
+  /**
+   * 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.
+   */
+  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',
+      );
+    }
+    return chainAnchorFromBase64(metadata.chainAnchor);
   }
 
   private async buildTransactionRequestFromMetadata(
@@ -1921,14 +2202,18 @@ export class Multisig {
         throw new UnsupportedMetadataVersionError(version);
       }
       case 'p2id': {
-        const account = await this.getStoreAccount();
         const { request } = buildP2idTransactionRequest(
           this._accountId,
           metadata.recipientId,
           metadata.faucetId,
           BigInt(metadata.amount),
-          account,
-          { salt, signatureAdviceMap, noteType: parseP2idNoteType(metadata.noteType) }
+          {
+            salt,
+            signatureAdviceMap,
+            noteType: parseP2idNoteType(metadata.noteType),
+            reclaimHeight: metadata.reclaimHeight,
+            timelockHeight: metadata.timelockHeight,
+          }
         );
         return request;
       }