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

package/dist/multisig.js

@@ -7,7 +7,7 @@
 import { GuardianHttpClient } from '@openzeppelin/guardian-client';
 import { ProposalSaltMalformedError } from './multisig/authArgErrors.js';
 import { Account, AccountId, AdviceMap, FeltArray, Note, NoteExportFormat, NoteFile, Signature, TransactionRequest, TransactionSummary, Word, } from '@miden-sdk/miden-sdk';
-import { chainAnchorFromBase64, chainAnchorToBase64, executeForSummary, executeForSummaryAt, summaryApprovalExpirationBlockNum, summarySalt, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
+import { chainAnchorFromBase64, chainAnchorToBase64, executeForSummary, executeForSummaryAtTip, isStaleChainError, prepareTipExecution, syncToBoundBlock, summaryApprovalExpirationBlockNum, summarySalt, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idNoteFromMetadata, buildP2idTransactionRequest, parseP2idNoteType, p2idNoteTypeToMetadata, } from './transaction.js';
 import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
 import { validateMultisigConfig } from './account/builder.js';
 import { ensureNotesAuthenticated } from './transaction/noteAuthentication.js';
@@ -539,11 +539,12 @@ export class Multisig {
      * Every synced proposal's metadata is checked against its signed summary
      * and the outcome is recorded in {@link Proposal.verification}. One that
      * fails is still cached and returned, so a single stale or corrupt
-     * proposal cannot hide the others (issue #462: once the node prunes a
-     * proposal's anchor block its re-execution fails for everyone). `failed`
-     * with `retryable: true` means a transient node error, worth syncing
-     * again; `retryable: false` means the proposal cannot be reproduced and
-     * must be re-proposed. `signProposal` and `executeProposal` re-verify and
+     * proposal cannot hide the others (issue #462). Verification re-executes
+     * each proposal at the chain tip, so the Miden client is synced once first.
+     * `failed` with `retryable: true` means a transient node error or chain
+     * state this client had not caught up with, worth syncing again;
+     * `retryable: false` means the proposal cannot be reproduced and must be
+     * re-proposed. `signProposal` and `executeProposal` re-verify and
      * refuse a failed proposal. A failed proposal still counts as reported, so
      * it is pruned like any other once GUARDIAN stops listing it.
      *
@@ -581,6 +582,12 @@ export class Multisig {
         const deltas = await this.guardian.getDeltaProposals(this._accountId);
         const factory = this.proposalFactory();
         const reported = new Map();
+        if (deltas.length > 0) {
+            // Verification re-executes at the store's sync height; bring it to the
+            // tip once for the whole listing. Best effort: a node outage then shows
+            // up on each proposal as a retryable failure instead of failing the sync.
+            await this.syncChain().catch((error) => console.warn('Could not sync the Miden client before verifying proposals', error));
+        }
         for (const delta of deltas) {
             const proposalId = normalizeHexWord(computeCommitmentFromTxSummary(delta.deltaPayload.txSummary.data));
             const existingProposal = this.proposals.get(proposalId);
@@ -1464,6 +1471,8 @@ export class Multisig {
     }
     async signProposal(proposalId) {
         const normalizedProposalId = normalizeHexWord(proposalId);
+        // Verification re-executes the proposal at the store's sync height.
+        await this.syncChain();
         const existingProposal = await this.getProposalForSigning(proposalId, normalizedProposalId);
         if (!existingProposal) {
             throw new Error(`Proposal not found: ${proposalId}`);
@@ -1492,9 +1501,14 @@ export class Multisig {
         await this.syncProposals();
         return this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
     }
+    /**
+     * Builds the final, fully signed request for a ready proposal, for a caller
+     * that proves and submits it with its own pipeline. The request declares the
+     * block its summary binds, so execute it at the chain tip, without an
+     * anchor, on a client synced to at least that block.
+     */
     async createTransactionProposalRequest(proposalId) {
-        const { finalRequest, anchor } = await this.prepareProposalExecution(proposalId);
-        anchor.free();
+        const { finalRequest } = await this.prepareProposalExecution(proposalId);
         return finalRequest;
     }
     /**
@@ -1503,22 +1517,16 @@ export class Multisig {
      * @param proposalId - The proposal commitment/ID
      */
     async executeProposal(proposalId) {
-        const { metadata, finalRequest, proposal, anchor } = await this.prepareProposalExecution(proposalId);
-        try {
-            if (metadata.proposalType === 'switch_guardian') {
-                // #417: import notes embedded in pending proposals from the old
-                // GUARDIAN. Must run before the switch executes and repoints;
-                // best-effort and bounded — see preservePreSwitchProposalNotes.
-                await this.preservePreSwitchProposalNotes();
-            }
-            // Execute at the proposal's anchored reference block, so the summary the
-            // cosigners signed reproduces exactly. The anchor was already checked
-            // against the summary's block commitment during binding verification.
-            await this.proverWorkflow.submitAt(AccountId.fromHex(this._accountId), finalRequest, anchor);
-        }
-        finally {
-            anchor.free();
-        }
+        const { metadata, finalRequest, proposal } = await this.prepareProposalExecution(proposalId);
+        if (metadata.proposalType === 'switch_guardian') {
+            // #417: import notes embedded in pending proposals from the old
+            // GUARDIAN. Must run before the switch executes and repoints;
+            // best-effort and bounded — see preservePreSwitchProposalNotes.
+            await this.preservePreSwitchProposalNotes();
+        }
+        // Execute at the chain tip. The request declares the block the signed
+        // summary binds, so the summary the cosigners signed reproduces there.
+        await this.submitAtTip(finalRequest);
         if (metadata.proposalType === 'switch_guardian') {
             if (!metadata.newGuardianEndpoint || !metadata.newGuardianPubkey) {
                 throw new Error('Switch GUARDIAN proposal metadata is incomplete after execution');
@@ -1564,11 +1572,12 @@ export class Multisig {
      * Submit an integration-built transaction (advice already injected). Mirrors
      * the Rust `submit_transaction`; used by the custom proposal producer flow
      * after `prepareCustomExecution` rebuilds its request with the returned advice.
-     * The transaction is executed at the proposal's anchored reference block,
-     * since the collected signatures only authorize the summary produced there.
+     * The transaction is executed at the chain tip, so the request has to declare
+     * the block its auth args bind (`feeAwareTransactionRequestBuilder` does).
      */
     async submitTransaction(proposalId, request) {
         const normalizedProposalId = normalizeHexWord(proposalId);
+        await this.syncChain();
         const delta = await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
         const existing = this.getLocalProposal(proposalId);
         const proposal = this.proposalFactory().fromDelta(delta, normalizedProposalId, existing?.metadata, existing?.signatures ?? []);
@@ -1580,11 +1589,34 @@ export class Multisig {
             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();
         }
+        await this.submitAtTip(request);
+    }
+    /**
+     * Executes `request` at the chain tip, then proves, submits and applies it,
+     * syncing first when this client is still below the block the request binds.
+     */
+    async submitAtTip(request) {
+        const webClient = await this.getRawClient();
+        await prepareTipExecution(webClient, request, () => retryRpcRead(() => webClient.syncState(), this.rpcConfig));
+        await this.proverWorkflow.submit(AccountId.fromHex(this._accountId), request);
+    }
+    /**
+     * Brings the Miden client to the chain tip before a proposal is re-executed:
+     * an execution loads foreign accounts, the fee faucet among them, at the
+     * store's sync height, which a node prunes about 50 blocks later.
+     */
+    async syncChain() {
+        const webClient = await this.getRawClient();
+        await retryRpcRead(() => webClient.syncState(), this.rpcConfig);
+    }
+    /** {@link syncToBoundBlock} with this client's RPC retry policy. */
+    async syncToBoundBlock(boundBlockNum) {
+        const webClient = await this.getRawClient();
+        await syncToBoundBlock(webClient, boundBlockNum, () => retryRpcRead(() => webClient.syncState(), this.rpcConfig));
     }
     /**
      * Create a proposal from a producer-built transaction the SDK does not model.
@@ -1632,6 +1664,8 @@ export class Multisig {
      */
     async prepareCustomExecution(proposalId, transactionRequestBytes) {
         const normalizedProposalId = normalizeHexWord(proposalId);
+        // The binding probe re-executes the producer's request at the store's sync height.
+        await this.syncChain();
         const delta = await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
         const existing = this.getLocalProposal(proposalId);
         const proposal = this.proposalFactory().fromDelta(delta, normalizedProposalId, existing?.metadata, existing?.signatures ?? []);
@@ -1646,26 +1680,24 @@ export class Multisig {
         const txSummary = TransactionSummary.deserialize(base64ToUint8Array(delta.deltaPayload.txSummary.data));
         const signedCommitmentHex = normalizeHexWord(txSummary.toCommitment().toHex());
         const bindingRequest = deserializeTransactionRequest(transactionRequestBytes);
-        // Probe at the proposal's anchored reference block: the signed summary
-        // binds that block's commitment, so probing at the local sync height would
-        // never reproduce it. The anchor arrives from an untrusted party via
-        // GUARDIAN, so its block commitment is checked against the signed summary
-        // before executing against it.
+        // The anchor arrives from an untrusted party via GUARDIAN, so its block
+        // commitment is checked against the signed summary: it has to name the
+        // block the summary binds. The probe itself runs at the chain tip, where
+        // the request's declared bound block reproduces the signed summary.
         const anchor = this.requireProposalAnchor(proposalId, proposal.metadata);
-        let derivedCommitmentHex;
         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();
         }
+        const webClient = await this.getRawClient();
+        const derived = await executeForSummaryAtTip(webClient, this._accountId, bindingRequest);
+        const derivedCommitmentHex = normalizeHexWord(derived.toCommitment().toHex());
         if (derivedCommitmentHex !== signedCommitmentHex) {
             throw new Error(`Custom proposal binding mismatch: expected ${signedCommitmentHex}, got ${derivedCommitmentHex}`);
         }
@@ -1753,8 +1785,8 @@ export class Multisig {
         return this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
     }
     /**
-     * The returned `anchor` is the block the request has to execute at; the
-     * caller owns it and frees it once submitted.
+     * The returned request declares the block the signed summary binds, and
+     * executes at the chain tip.
      */
     async prepareProposalExecution(proposalId) {
         const proposal = this.getLocalProposal(proposalId);
@@ -1762,6 +1794,8 @@ export class Multisig {
             throw new Error(`Proposal not found: ${proposalId}`);
         }
         this.proposalFactory().assertAccountId(proposal.accountId);
+        // Verification and execution run at the store's sync height.
+        await this.syncChain();
         await this.verifyProposalMetadataBinding(proposal);
         const metadata = proposal.metadata;
         // Reject custom proposals before any advice assembly or GUARDIAN ack push:
@@ -1873,14 +1907,18 @@ export class Multisig {
             await this.verifyGuardianEndpointCommitment(metadata.newGuardianEndpoint, metadata.newGuardianPubkey);
         }
         const anchor = this.requireProposalAnchor(proposalId, metadata);
+        let binding;
         try {
-            const finalRequest = await this.buildTransactionRequestFromMetadata(metadata, proposalRequestBinding(txSummary, anchor, saltHex), adviceMap);
-            return { finalRequest, metadata, proposal, anchor };
+            binding = proposalRequestBinding(txSummary, anchor, saltHex);
         }
-        catch (error) {
+        finally {
             anchor.free();
-            throw error;
         }
+        // A switch_guardian proposal is verified without a rebuild, so this may be
+        // the first time this client needs the chain at the bound block.
+        await this.syncToBoundBlock(binding.boundBlockNum);
+        const finalRequest = await this.buildTransactionRequestFromMetadata(metadata, binding, adviceMap);
+        return { finalRequest, metadata, proposal };
     }
     /**
      * Export a proposal for offline signing
@@ -1950,6 +1988,10 @@ export class Multisig {
             throw new Error('Invalid proposal JSON: missing required fields');
         }
         const proposal = this.proposalFactory().fromExported(exported);
+        // Verification re-executes every built-in type at the store's sync height.
+        if (proposal.metadata.proposalType !== 'custom') {
+            await this.syncChain();
+        }
         await this.verifyProposalMetadataBinding(proposal);
         this.proposals.set(proposal.id, proposal);
         return proposal;
@@ -1982,6 +2024,10 @@ export class Multisig {
         if (alreadySigned) {
             throw new Error('You have already signed this proposal');
         }
+        // Verification re-executes every built-in type at the store's sync height.
+        if (proposal.metadata?.proposalType !== 'custom') {
+            await this.syncChain();
+        }
         const commitmentToSign = await this.verifyProposalMetadataBinding(proposal);
         // Sign the commitment
         const signature = await buildGuardianSignatureFromSigner(this.signer, commitmentToSign);
@@ -2033,7 +2079,7 @@ export class Multisig {
         catch (error) {
             proposal.verification = {
                 status: 'failed',
-                retryable: isTransientRpcError(error),
+                retryable: isTransientRpcError(error) || isStaleChainError(error),
                 message: error instanceof Error ? error.message : String(error),
             };
             throw error;
@@ -2042,10 +2088,11 @@ export class Multisig {
     async checkProposalMetadataBinding(proposal) {
         const txSummaryCommitment = this.ensureProposalCommitmentMatchesSummary(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.
+        // The anchor arrives from an untrusted party via GUARDIAN, so check that it
+        // names the block the signed summary binds: the rebuild below binds the
+        // block it names. Nothing executes against it; the rebuild runs at the
+        // chain tip. `ChainAnchor.deserialize` already enforced internal
+        // header/chain consistency.
         const anchor = this.requireProposalAnchor(proposal.id, proposal.metadata);
         try {
             const anchorCommitment = normalizeHexWord(anchor.commitment().toHex());
@@ -2072,6 +2119,12 @@ export class Multisig {
                 // binding checks for this type.
                 return txSummaryCommitment;
             }
+            // The rebuild reads the chain's fee faucet from the synced protocol
+            // configuration and executes at the tip, so the store has to have synced
+            // to the block the summary binds; a cosigner that has only just loaded
+            // the account has not.
+            await this.syncToBoundBlock(binding.boundBlockNum);
+            const webClient = await this.getRawClient();
             // A consume-notes summary commits to *authenticated* consumption (see
             // ensureNotesAuthenticated), which miden-client decides from this store
             // alone. Put the store in that mode before the rebuild, or a cosigner
@@ -2081,8 +2134,7 @@ export class Multisig {
                 await this.ensureNotesAuthenticated(decodeEmbeddedConsumeNotes(proposal.metadata));
             }
             const request = await this.buildTransactionRequestFromMetadata(proposal.metadata, binding);
-            const webClient = await this.getRawClient();
-            const reconstructed = await executeForSummaryAt(webClient, this._accountId, request, anchor);
+            const reconstructed = await executeForSummaryAtTip(webClient, this._accountId, request);
             const reconstructedCommitment = normalizeHexWord(reconstructed.toCommitment().toHex());
             if (reconstructedCommitment !== txSummaryCommitment) {
                 throw new Error(`Invalid proposal: metadata does not match tx_summary for ${proposal.id}`);
@@ -2093,12 +2145,6 @@ export class Multisig {
             anchor.free();
         }
     }
-    /**
-     * Decodes a proposal's chain anchor. Throws when absent: a proposal without
-     * an anchor was created at an unknown reference block, so its signed summary
-     * cannot be reproduced, verified, or executed. The caller owns the returned
-     * anchor and must `free()` it once done.
-     */
     /**
      * Reads a proposal's salt. Throws when absent, because there is nothing to fall
      * back to.
@@ -2140,11 +2186,16 @@ export class Multisig {
         }
         return saltHex;
     }
+    /**
+     * Decodes a proposal's chain anchor, which names the block its signed summary
+     * binds. Throws when absent: every proposal carries one, so a proposal
+     * without it is malformed and is neither verified nor executed. The caller
+     * owns the returned anchor and must `free()` it once done.
+     */
     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');
+            throw new Error(`Proposal ${proposalId} has no chain anchor, which names the block its signed ` +
+                'summary binds; it cannot be verified or executed');
         }
         return chainAnchorFromBase64(metadata.chainAnchor);
     }