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

package/dist/multisig.js

@@ -6,23 +6,25 @@
  */
 import { GuardianHttpClient } from '@openzeppelin/guardian-client';
 import { Account, AccountId, AdviceMap, Endpoint, FeltArray, Note, NoteExportFormat, NoteFile, RpcClient, Signature, TransactionRequest, TransactionSummary, Word, } from '@miden-sdk/miden-sdk';
-import { executeForSummary, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
+import { chainAnchorFromBase64, chainAnchorToBase64, executeForSummary, executeForSummaryAt, summarySalt, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
 import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
 import { CONSUME_NOTES_METADATA_VERSION_V2, MAX_CONSUME_NOTES_METADATA_BYTES, } from './types/proposal.js';
 import { LEGACY_CONSUME_NOTES_ENABLED } from './multisig/config.js';
 import { ConsumeNotesMetadataOversizeError, LegacyConsumeNotesNoteMissingError, NoteBindingMismatchError, UnsupportedMetadataVersionError, } from './multisig/consumeNotesErrors.js';
 import { noteFromBase64, noteToBase64 } from './utils/encoding.js';
 import { base64ToUint8Array, uint8ArrayToBase64, normalizeHexWord, } from './utils/encoding.js';
-import { buildSignatureAdviceEntry, normalizeSignerCommitment, signatureHexToBytes, tryComputeEcdsaCommitmentHex, } from './utils/signature.js';
+import { assertEcdsaSignatureRecoverable, buildSignatureAdviceEntry, normalizeSignerCommitment, signatureHexToBytes, tryComputeEcdsaCommitmentHex, } 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';
 import { getRawMidenClient, getTransactionProver, requireMidenRpcEndpoint, } from './raw-client.js';
 import { resolveProverConfig, } from './prover/config.js';
 import { ProverWorkflow } from './prover/workflow.js';
+import { resolveRpcConfig, } from './rpc/config.js';
+import { retryRpcRead } from './rpc/retry.js';
 /**
  * Represents a multisig account with GUARDIAN integration.
  */
@@ -51,6 +53,20 @@ function deserializeTransactionRequest(bytes) {
         throw new Error(`failed to decode transaction request: ${detail}`);
     }
 }
+/**
+ * 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, options, legacyArgs = []) {
+    if (typeof options !== 'object' || options === null || legacyArgs.length > 0) {
+        throw new Error(`${method}: positional optional parameters were replaced by a trailing options object (issue #387); pass { nonce, ... } instead`);
+    }
+    return options.nonce ?? Date.now();
+}
 export class Multisig {
     account;
     threshold;
@@ -63,10 +79,11 @@ export class Multisig {
     midenClient;
     rawClientPromise;
     proverWorkflow;
+    rpcConfig;
     _accountId;
     midenRpcEndpoint;
     proposals = new Map();
-    constructor(account, config, guardian, signer, midenClient, accountId, midenRpcEndpoint, proverConfig) {
+    constructor(account, config, guardian, signer, midenClient, accountId, midenRpcEndpoint, proverConfig, rpcConfig) {
         this.account = account;
         this.threshold = config.threshold;
         this.signerCommitments = config.signerCommitments;
@@ -80,6 +97,7 @@ export class Multisig {
         this.midenRpcEndpoint = requireMidenRpcEndpoint(midenRpcEndpoint);
         this.rawClientPromise = getRawMidenClient(midenClient, this.midenRpcEndpoint);
         this.proverWorkflow = new ProverWorkflow(this.midenClient, proverConfig ?? resolveProverConfig(undefined, getTransactionProver(midenClient)));
+        this.rpcConfig = rpcConfig ?? resolveRpcConfig(undefined);
     }
     getMidenRpcEndpoint() {
         return this.midenRpcEndpoint;
@@ -124,7 +142,32 @@ export class Multisig {
      */
     async getStoreAccount() {
         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() {
+        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() {
+        const account = await this.getStoreAccount();
+        return AccountInspector.getGuardianPublicKeyCommitment(account);
     }
     /**
      * Maps a proposal type to the procedure that determines its threshold.
@@ -164,6 +207,37 @@ 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) {
+        if (newNumSigners <= this.signerCommitments.length) {
+            return [];
+        }
+        return Array.from(this.procedureThresholds.entries()).map(([procedure, threshold]) => ({
+            procedure,
+            threshold,
+        }));
+    }
+    warnOnOverrideDilution(newNumSigners) {
+        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.
      *
@@ -204,7 +278,7 @@ 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 = localAccount ?? null;
         const guardianCommitment = normalizeHexWord(state.commitment);
         const localCommitment = localAccount
@@ -224,7 +298,7 @@ export class Multisig {
     async verifyStateCommitment() {
         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(`Local account state not found for account ${this._accountId}. Sync the account before verifying.`);
         }
@@ -283,7 +357,7 @@ export class Multisig {
     async getOnChainCommitment(accountId) {
         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;
@@ -311,12 +385,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) {
@@ -402,18 +478,22 @@ 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, nonce, newThreshold) {
+    async createAddSignerProposal(newCommitment, options = {}, ...legacyArgs) {
+        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, targetThreshold, targetSignerCommitments, { 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 = {
+            chainAnchor,
             proposalType: 'add_signer',
             targetThreshold,
             targetSignerCommitments,
@@ -427,10 +507,11 @@ 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, nonce, newThreshold) {
+    async createRemoveSignerProposal(signerToRemove, options = {}, ...legacyArgs) {
+        const proposalNonce = resolveProposalNonce('createRemoveSignerProposal', options, legacyArgs);
         const webClient = await this.getRawClient();
         const normalizedRemove = signerToRemove.toLowerCase();
         const targetSignerCommitments = this.signerCommitments.filter((c) => c.toLowerCase() !== normalizedRemove);
@@ -440,15 +521,17 @@ export class Multisig {
         if (targetSignerCommitments.length === 0) {
             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(`Invalid threshold ${targetThreshold}. Must be between 1 and ${targetSignerCommitments.length}`);
         }
         const { request, salt } = await buildUpdateSignersTransactionRequest(webClient, targetThreshold, targetSignerCommitments, { 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 = {
+            chainAnchor,
             proposalType: 'remove_signer',
             targetThreshold,
             targetSignerCommitments,
@@ -462,9 +545,10 @@ 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, nonce) {
+    async createChangeThresholdProposal(newThreshold, options = {}) {
+        const proposalNonce = resolveProposalNonce('createChangeThresholdProposal', options);
         const webClient = await this.getRawClient();
         if (newThreshold < 1 || newThreshold > this.signerCommitments.length) {
             throw new Error(`Invalid threshold ${newThreshold}. Must be between 1 and ${this.signerCommitments.length}`);
@@ -473,10 +557,12 @@ export class Multisig {
             throw new Error('New threshold is the same as current threshold');
         }
         const { request, salt } = await buildUpdateSignersTransactionRequest(webClient, newThreshold, this.signerCommitments, { 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 = {
+            chainAnchor,
             proposalType: 'change_threshold',
             targetThreshold: newThreshold,
             targetSignerCommitments: this.signerCommitments,
@@ -486,7 +572,8 @@ export class Multisig {
         };
         return this.createProposal(proposalNonce, summaryBase64, metadata);
     }
-    async createUpdateProcedureThresholdProposal(targetProcedure, targetThreshold, nonce) {
+    async createUpdateProcedureThresholdProposal(targetProcedure, targetThreshold, options = {}) {
+        const proposalNonce = resolveProposalNonce('createUpdateProcedureThresholdProposal', options);
         const webClient = await this.getRawClient();
         if (targetThreshold < 0 || targetThreshold > this.signerCommitments.length) {
             throw new Error(`Invalid threshold ${targetThreshold}. Must be between 0 and ${this.signerCommitments.length}`);
@@ -499,13 +586,15 @@ export class Multisig {
             throw new Error(`Procedure ${targetProcedure} already has threshold override ${targetThreshold}`);
         }
         const { request, salt } = await buildUpdateProcedureThresholdTransactionRequest(webClient, targetProcedure, targetThreshold, { 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 = {
+            chainAnchor,
             proposalType: 'update_procedure_threshold',
             targetProcedure,
             targetThreshold,
@@ -520,16 +609,19 @@ 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, newGuardianPubkey, nonce) {
+    async createSwitchGuardianProposal(newGuardianEndpoint, newGuardianPubkey, options = {}) {
+        const proposalNonce = resolveProposalNonce('createSwitchGuardianProposal', options);
         const webClient = await this.getRawClient();
         await this.verifyGuardianEndpointCommitment(newGuardianEndpoint, newGuardianPubkey);
         const { request, salt } = await buildUpdateGuardianTransactionRequest(webClient, newGuardianPubkey, { 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 = {
+            chainAnchor,
             proposalType: 'switch_guardian',
             saltHex: salt.toHex(),
             requiredSignatures: this.getEffectiveThreshold('switch_guardian'),
@@ -545,9 +637,10 @@ 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, nonce) {
+    async createConsumeNotesProposal(noteIds, options = {}) {
+        const proposalNonce = resolveProposalNonce('createConsumeNotesProposal', options);
         const webClient = await this.getRawClient();
         if (noteIds.length === 0) {
             throw new Error('At least one note ID is required');
@@ -564,10 +657,12 @@ export class Multisig {
         }
         const embeddedNotes = fetchedNotes.map((n) => noteToBase64(n));
         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 = {
+            chainAnchor,
             proposalType: 'consume_notes',
             noteIds,
             metadataVersion: CONSUME_NOTES_METADATA_VERSION_V2,
@@ -593,21 +688,26 @@ 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, faucetId, amount, nonce, options = {}) {
+    async createP2idProposal(recipientId, faucetId, amount, options = {}, ...legacyArgs) {
+        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();
-        const { request, salt } = buildP2idTransactionRequest(this._accountId, recipientId, faucetId, amount, account, { noteType: options.noteType });
-        const summary = await executeForSummary(webClient, this._accountId, request);
+        // 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, noteOptions);
+        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 = {
+            chainAnchor,
             proposalType: 'p2id',
             saltHex: salt.toHex(),
             requiredSignatures: this.getEffectiveThreshold('p2id'),
@@ -616,6 +716,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)}...`,
         };
         return this.createProposal(proposalNonce, summaryBase64, metadata);
@@ -663,7 +766,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
@@ -700,7 +803,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.
      *
@@ -726,7 +829,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
@@ -751,7 +854,7 @@ export class Multisig {
         return webClient.importNoteFile(noteFile);
     }
     /**
-     * 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.
      */
@@ -765,10 +868,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) {
         const metadata = proposal.metadata;
@@ -779,8 +881,7 @@ export class Multisig {
             !metadata.saltHex) {
             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);
+        const note = buildP2idNoteFromMetadata(this._accountId, metadata.recipientId, metadata.faucetId, BigInt(metadata.amount), parseP2idNoteType(metadata.noteType), metadata.saltHex, { reclaimHeight: metadata.reclaimHeight, timelockHeight: metadata.timelockHeight });
         return note.id().toString();
     }
     /**
@@ -821,6 +922,18 @@ export class Multisig {
     async abandonStatus(nonce) {
         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 = {}) {
+        return this.guardian.getDeltaHistory(this._accountId, options);
+    }
     async signProposal(proposalId) {
         const normalizedProposalId = normalizeHexWord(proposalId);
         const existingProposal = await this.getProposalForSigning(proposalId, normalizedProposalId);
@@ -861,8 +974,17 @@ export class Multisig {
      */
     async executeProposal(proposalId) {
         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) {
                 throw new Error('Switch GUARDIAN proposal metadata is incomplete after execution');
@@ -879,13 +1001,17 @@ export class Multisig {
                     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();
-                const updatedAccount = await webClient.getAccount(accountId);
+                await retryRpcRead(() => webClient.syncState(), this.rpcConfig);
+                const updatedAccount = await retryRpcRead(() => webClient.getAccount(accountId), this.rpcConfig);
                 if (!updatedAccount) {
                     throw new Error(`Updated account ${this._accountId} is missing from local client`);
                 }
@@ -906,18 +1032,37 @@ 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) {
-        await this.proverWorkflow.submit(AccountId.fromHex(this._accountId), request);
+    async submitTransaction(proposalId, request) {
+        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`.
      */
-    async createCustomProposal(transactionRequestBytes, proposalType, nonce) {
+    async createCustomProposal(transactionRequestBytes, proposalType, options = {}) {
+        const proposalNonce = resolveProposalNonce('createCustomProposal', options);
         const label = proposalType.trim().toLowerCase();
         if (label.length === 0) {
             throw new Error('proposalType must not be empty');
@@ -930,10 +1075,12 @@ 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 = {
+            chainAnchor,
             proposalType: 'custom',
             description: '',
             rawProposalType: label,
@@ -944,7 +1091,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
@@ -967,9 +1114,26 @@ export class Multisig {
         const txSummary = TransactionSummary.deserialize(base64ToUint8Array(delta.deltaPayload.txSummary.data));
         const signedCommitmentHex = normalizeHexWord(txSummary.toCommitment().toHex());
         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;
+        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}`);
         }
@@ -998,7 +1162,10 @@ export class Multisig {
             const signerCommitment = Word.fromHex(signerCommitmentHex);
             const sigBytes = signatureHexToBytes(cosignerSig.signature.signature, cosignerSig.signature.scheme);
             const signature = Signature.deserialize(sigBytes);
-            const { key, values } = buildSignatureAdviceEntry(signerCommitment, createTxCommitmentWord(), signature, ecdsaPublicKey, cosignerSig.signature.scheme === 'ecdsa' ? cosignerSig.signature.signature : undefined);
+            if (cosignerSig.signature.scheme === 'ecdsa' && ecdsaPublicKey) {
+                assertEcdsaSignatureRecoverable(cosignerSig.signature.signature, normalizedTxCommitmentHex, ecdsaPublicKey);
+            }
+            const { key, values } = buildSignatureAdviceEntry(signerCommitment, createTxCommitmentWord(), signature);
             const keyHex = normalizeHexWord(key.toHex());
             if (adviceMapKeys.has(keyHex)) {
                 throw new Error(`Duplicate advice-map key detected for proposal ${proposalId}`);
@@ -1026,7 +1193,10 @@ export class Multisig {
         }
         const ackSigBytes = signatureHexToBytes(ackSigHex, ackScheme);
         const ackSignature = Signature.deserialize(ackSigBytes);
-        const { key: ackKey, values: ackValues } = buildSignatureAdviceEntry(guardianCommitment, createTxCommitmentWord(), ackSignature, ackScheme === 'ecdsa' ? ackPubkey : undefined, ackScheme === 'ecdsa' ? ackSigHex : undefined);
+        if (ackScheme === 'ecdsa' && ackPubkey) {
+            assertEcdsaSignatureRecoverable(ackSigHex, normalizedTxCommitmentHex, ackPubkey);
+        }
+        const { key: ackKey, values: ackValues } = buildSignatureAdviceEntry(guardianCommitment, createTxCommitmentWord(), ackSignature);
         const ackKeyHex = normalizeHexWord(ackKey.toHex());
         if (adviceMapKeys.has(ackKeyHex)) {
             throw new Error(`Duplicate advice-map key detected for GUARDIAN acknowledgment in proposal ${proposalId}`);
@@ -1073,7 +1243,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(this.signerCommitments.map((commitment) => normalizeHexWord(commitment)));
@@ -1100,9 +1270,10 @@ export class Multisig {
             const signerCommitment = Word.fromHex(signerCommitmentHex);
             const sigBytes = signatureHexToBytes(cosignerSig.signature.signature, cosignerSig.signature.scheme);
             const signature = Signature.deserialize(sigBytes);
-            const { key, values } = buildSignatureAdviceEntry(signerCommitment, createTxCommitmentWord(), signature, ecdsaPublicKey, cosignerSig.signature.scheme === 'ecdsa'
-                ? cosignerSig.signature.signature
-                : undefined);
+            if (cosignerSig.signature.scheme === 'ecdsa' && ecdsaPublicKey) {
+                assertEcdsaSignatureRecoverable(cosignerSig.signature.signature, normalizedTxCommitmentHex, ecdsaPublicKey);
+            }
+            const { key, values } = buildSignatureAdviceEntry(signerCommitment, createTxCommitmentWord(), signature);
             const keyHex = normalizeHexWord(key.toHex());
             if (adviceMapKeys.has(keyHex)) {
                 throw new Error(`Duplicate advice-map key detected for proposal ${proposalId}`);
@@ -1134,7 +1305,10 @@ export class Multisig {
             }
             const ackSigBytes = signatureHexToBytes(ackSigHex, ackScheme);
             const ackSignature = Signature.deserialize(ackSigBytes);
-            const { key: ackKey, values: ackValues } = buildSignatureAdviceEntry(guardianCommitment, createTxCommitmentWord(), ackSignature, ackScheme === 'ecdsa' ? ackPubkey : undefined, ackScheme === 'ecdsa' ? ackSigHex : undefined);
+            if (ackScheme === 'ecdsa' && ackPubkey) {
+                assertEcdsaSignatureRecoverable(ackSigHex, normalizedTxCommitmentHex, ackPubkey);
+            }
+            const { key: ackKey, values: ackValues } = buildSignatureAdviceEntry(guardianCommitment, createTxCommitmentWord(), ackSignature);
             const ackKeyHex = normalizeHexWord(ackKey.toHex());
             if (adviceMapKeys.has(ackKeyHex)) {
                 throw new Error(`Duplicate advice-map key detected for GUARDIAN acknowledgment in proposal ${proposalId}`);
@@ -1278,34 +1452,58 @@ export class Multisig {
     }
     async verifyProposalMetadataBinding(proposal) {
         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.
+        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.
+        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);
+            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;
         }
-        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;
+        finally {
+            anchor.free();
         }
-        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());
-        if (reconstructedCommitment !== txSummaryCommitment) {
-            throw new Error(`Invalid proposal: metadata does not match tx_summary for ${proposal.id}`);
+    }
+    /**
+     * 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.
+     */
+    requireProposalAnchor(proposalId, metadata) {
+        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 txSummaryCommitment;
+        return chainAnchorFromBase64(metadata.chainAnchor);
     }
     async buildTransactionRequestFromMetadata(metadata, salt, signatureAdviceMap) {
         const webClient = await this.getRawClient();
@@ -1361,8 +1559,13 @@ 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) });
+                const { request } = buildP2idTransactionRequest(this._accountId, metadata.recipientId, metadata.faucetId, BigInt(metadata.amount), {
+                    salt,
+                    signatureAdviceMap,
+                    noteType: parseP2idNoteType(metadata.noteType),
+                    reclaimHeight: metadata.reclaimHeight,
+                    timelockHeight: metadata.timelockHeight,
+                });
                 return request;
             }
             case 'custom':