@openzeppelin/miden-multisig-client 0.16.0 → 0.16.1

package/src/multisig.test.ts

@@ -8,10 +8,11 @@ import {
   executeForSummary,
 } from './transaction.js';
 
-const { mockRpcGetAccountDetails, mockAccountDeserialize, mockDetectConfig } = vi.hoisted(() => ({
+const { mockRpcGetAccountDetails, mockAccountDeserialize, mockDetectConfig, mockNoteFileDeserialize } = vi.hoisted(() => ({
   mockRpcGetAccountDetails: vi.fn(),
   mockAccountDeserialize: vi.fn(),
   mockDetectConfig: vi.fn(),
+  mockNoteFileDeserialize: vi.fn(),
 }));
 
 // Mock the Miden SDK
@@ -26,6 +27,14 @@ vi.mock('@miden-sdk/miden-sdk', () => ({
     Private: 0,
     Public: 1,
   },
+  NoteExportFormat: {
+    Id: 0,
+    Full: 1,
+    Details: 2,
+  },
+  NoteFile: {
+    deserialize: mockNoteFileDeserialize,
+  },
   TransactionSummary: {
     deserialize: vi.fn().mockReturnValue({
       toCommitment: () => ({
@@ -91,6 +100,9 @@ vi.mock('./transaction.js', () => ({
     request: {},
     salt: { toHex: () => '0x' + 'd'.repeat(64) },
   }),
+  buildP2idNoteFromMetadata: vi.fn().mockReturnValue({
+    id: () => ({ toString: () => '0x' + 'ab'.repeat(32) }),
+  }),
   // Mirrors the real implementations against the mocked NoteType values
   // (Private = 0, Public = 1).
   parseP2idNoteType: vi.fn((value?: string) => {
@@ -156,7 +168,8 @@ describe('Multisig', () => {
   function createTestMultisig(
     config: ConstructorParameters<typeof Multisig>[1],
     signer: Signer = mockSigner,
-    accountId?: string
+    accountId?: string,
+    proverConfig?: ConstructorParameters<typeof Multisig>[7],
   ): Multisig {
     return new Multisig(
       mockAccount,
@@ -165,7 +178,8 @@ describe('Multisig', () => {
       signer,
       mockWebClient,
       accountId,
-      MIDEN_RPC_ENDPOINT
+      MIDEN_RPC_ENDPOINT,
+      proverConfig,
     );
   }
 
@@ -226,13 +240,38 @@ describe('Multisig', () => {
       submitNewTransaction: vi.fn(),
       submitNewTransactionWithProver: vi.fn(),
       transactions: {
-        submit: vi.fn(),
+        executeRequest: vi.fn(),
       },
       getConsumableNotes: vi.fn().mockResolvedValue([]),
       syncState: vi.fn(),
       getAccount: vi.fn().mockResolvedValue(null),
       newAccount: vi.fn(),
     };
+    mockWebClient.transactions.executeRequest.mockImplementation(
+      async (accountId: unknown, request: unknown) => {
+        const result = await mockWebClient.executeTransaction(accountId, request);
+        return {
+          result,
+          prove: async (options?: { prover?: unknown }) => {
+            const proof = options?.prover === undefined
+              ? await mockWebClient.proveTransaction(result)
+              : await mockWebClient.proveTransaction(result, options.prover);
+            return {
+              proof,
+              result,
+              submit: async () => {
+                const blockNumber = await mockWebClient.submitProvenTransaction(proof, result);
+                return {
+                  blockNumber,
+                  result,
+                  apply: () => mockWebClient.applyTransaction(result, blockNumber),
+                };
+              },
+            };
+          },
+        };
+      },
+    );
   });
 
   describe('constructor', () => {
@@ -1398,6 +1437,154 @@ describe('Multisig', () => {
     });
   });
 
+  describe('exportNoteToBytes / importNoteFromBytes (issue #356)', () => {
+    const config = {
+      threshold: 1,
+      signerCommitments: ['0x' + '1'.repeat(64)],
+      guardianCommitment: '0x' + '3'.repeat(64),
+    };
+
+    it('exports the full note with proof when the inclusion proof is known', async () => {
+      const noteFile = { serialize: () => new Uint8Array([9, 9, 9]) };
+      mockWebClient.getOutputNote = vi.fn().mockResolvedValue({
+        inclusionProof: () => ({}),
+      });
+      mockWebClient.exportNoteFile = vi.fn().mockResolvedValue(noteFile);
+
+      const multisig = createTestMultisig(config);
+      const bytes = await multisig.exportNoteToBytes('0x' + 'ab'.repeat(32));
+
+      expect(bytes).toEqual(new Uint8Array([9, 9, 9]));
+      // NoteExportFormat.Full = 1 in the SDK mock
+      expect(mockWebClient.exportNoteFile).toHaveBeenCalledWith('0x' + 'ab'.repeat(32), 1);
+    });
+
+    it('falls back to a details-only export before the note commits on chain', async () => {
+      const noteFile = { serialize: () => new Uint8Array([7]) };
+      mockWebClient.getOutputNote = vi.fn().mockResolvedValue({
+        inclusionProof: () => undefined,
+      });
+      mockWebClient.exportNoteFile = vi.fn().mockResolvedValue(noteFile);
+
+      const multisig = createTestMultisig(config);
+      await multisig.exportNoteToBytes(' 0x' + 'ab'.repeat(32) + ' ');
+
+      // NoteExportFormat.Details = 2 in the SDK mock; the id is trimmed
+      expect(mockWebClient.exportNoteFile).toHaveBeenCalledWith('0x' + 'ab'.repeat(32), 2);
+    });
+
+    it('rejects exporting a note the local store does not know', async () => {
+      mockWebClient.getOutputNote = vi.fn().mockRejectedValue(new Error('no such note'));
+      mockWebClient.exportNoteFile = vi.fn();
+
+      const multisig = createTestMultisig(config);
+      await expect(multisig.exportNoteToBytes('0x' + 'ab'.repeat(32))).rejects.toThrow(
+        /not found in the local store/,
+      );
+      expect(mockWebClient.exportNoteFile).not.toHaveBeenCalled();
+    });
+
+    it('rejects exporting when the store resolves no record', async () => {
+      mockWebClient.getOutputNote = vi.fn().mockResolvedValue(undefined);
+      mockWebClient.exportNoteFile = vi.fn();
+
+      const multisig = createTestMultisig(config);
+      await expect(multisig.exportNoteToBytes('0x' + 'ab'.repeat(32))).rejects.toThrow(
+        /not found in the local store/,
+      );
+      expect(mockWebClient.exportNoteFile).not.toHaveBeenCalled();
+    });
+
+    it('imports note file bytes and returns the resolved identifier', async () => {
+      const decoded = { marker: 'note-file' };
+      mockNoteFileDeserialize.mockReturnValue(decoded);
+      mockWebClient.importNoteFile = vi.fn().mockResolvedValue('0x' + 'cd'.repeat(32));
+
+      const multisig = createTestMultisig(config);
+      const noteId = await multisig.importNoteFromBytes(new Uint8Array([1, 2, 3]));
+
+      expect(mockNoteFileDeserialize).toHaveBeenCalledWith(new Uint8Array([1, 2, 3]));
+      expect(mockWebClient.importNoteFile).toHaveBeenCalledWith(decoded);
+      expect(noteId).toBe('0x' + 'cd'.repeat(32));
+    });
+
+    it('rejects bytes that do not decode as a note file', async () => {
+      mockNoteFileDeserialize.mockImplementation(() => {
+        throw new Error('bad bytes');
+      });
+      mockWebClient.importNoteFile = vi.fn();
+
+      const multisig = createTestMultisig(config);
+      await expect(multisig.importNoteFromBytes(new Uint8Array([0]))).rejects.toThrow(
+        /failed to decode note file: bad bytes/,
+      );
+      expect(mockWebClient.importNoteFile).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('exportNoteToFile / importNoteFromFile (issue #356)', () => {
+    const config = {
+      threshold: 1,
+      signerCommitments: ['0x' + '1'.repeat(64)],
+      guardianCommitment: '0x' + '3'.repeat(64),
+    };
+
+    it('rejects exportNoteToFile outside a browser environment', async () => {
+      const multisig = createTestMultisig(config);
+      await expect(multisig.exportNoteToFile('0x' + 'ab'.repeat(32))).rejects.toThrow(
+        /requires a browser environment/,
+      );
+    });
+
+    it('imports from a File/Blob by delegating to importNoteFromBytes', async () => {
+      const decoded = { marker: 'note-file' };
+      mockNoteFileDeserialize.mockReturnValue(decoded);
+      mockWebClient.importNoteFile = vi.fn().mockResolvedValue('0x' + 'cd'.repeat(32));
+
+      const multisig = createTestMultisig(config);
+      const noteId = await multisig.importNoteFromFile(new Blob([new Uint8Array([1, 2, 3])]));
+
+      expect(mockNoteFileDeserialize).toHaveBeenCalledWith(new Uint8Array([1, 2, 3]));
+      expect(noteId).toBe('0x' + 'cd'.repeat(32));
+    });
+  });
+
+  describe('getP2idNoteId (issue #356)', () => {
+    const config = {
+      threshold: 1,
+      signerCommitments: ['0x' + '1'.repeat(64)],
+      guardianCommitment: '0x' + '3'.repeat(64),
+    };
+
+    it('computes the deterministic note ID from p2id proposal metadata', async () => {
+      const multisig = createTestMultisig(config);
+      const proposal = {
+        metadata: {
+          proposalType: 'p2id',
+          recipientId: '0x' + 'b'.repeat(30),
+          faucetId: '0x' + 'c'.repeat(30),
+          amount: '100',
+          saltHex: '0x' + 'd'.repeat(64),
+          noteType: 'private',
+        },
+      } as any;
+
+      const noteId = await multisig.getP2idNoteId(proposal);
+      expect(noteId).toBe('0x' + 'ab'.repeat(32));
+    });
+
+    it('rejects non-p2id proposals', async () => {
+      const multisig = createTestMultisig(config);
+      const proposal = {
+        metadata: { proposalType: 'consume_notes' },
+      } as any;
+
+      await expect(multisig.getP2idNoteId(proposal)).rejects.toThrow(
+        /requires a P2ID proposal/,
+      );
+    });
+  });
+
   describe('createChangeThresholdProposal', () => {
     it('passes the signer scheme to update-signers requests', async () => {
       vi.mocked(executeForSummary).mockResolvedValue({
@@ -2971,7 +3158,11 @@ describe('Multisig', () => {
         publicKey: '0x' + '2'.repeat(66),
       };
 
-      const multisig = createTestMultisig(config, ecdsaSigner);
+      const multisig = createTestMultisig(config, ecdsaSigner, undefined, {
+        kind: 'remote',
+        maxAttempts: 2,
+        createProver: () => ({} as never),
+      });
       const proposalId = '0x' + 'c'.repeat(64);
       const cosignerPubkey = '0x' + '3'.repeat(66);
       const ackPubkey = '0x' + '4'.repeat(66);
@@ -3036,10 +3227,21 @@ describe('Multisig', () => {
           ack_scheme: 'ecdsa',
         }),
       });
-      mockWebClient.transactions.submit.mockResolvedValueOnce({});
-
-      await expect(multisig.executeProposal(proposalId)).resolves.toBeUndefined();
-      expect(mockWebClient.transactions.submit).toHaveBeenCalledTimes(1);
+      mockWebClient.proveTransaction
+        .mockRejectedValueOnce(Object.assign(new Error('unavailable'), { code: 'Unavailable' }))
+        .mockResolvedValueOnce({});
+      vi.useFakeTimers();
+      try {
+        const execution = multisig.executeProposal(proposalId);
+        await vi.runAllTimersAsync();
+        await expect(execution).resolves.toBeUndefined();
+      } finally {
+        vi.useRealTimers();
+      }
+      expect(mockWebClient.executeTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.proveTransaction).toHaveBeenCalledTimes(2);
+      expect(mockWebClient.submitProvenTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.applyTransaction).toHaveBeenCalledTimes(1);
 
       expect(vi.mocked(signatureHexToBytes)).toHaveBeenNthCalledWith(
         1,
@@ -3151,9 +3353,11 @@ describe('Multisig', () => {
           ack_scheme: 'ecdsa',
         }),
       });
-      mockWebClient.transactions.submit.mockResolvedValueOnce({});
-
       await expect(multisig.executeProposal(proposalId)).resolves.toBeUndefined();
+      expect(mockWebClient.executeTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.proveTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.submitProvenTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.applyTransaction).toHaveBeenCalledTimes(1);
 
       expect(vi.mocked(signatureHexToBytes)).toHaveBeenNthCalledWith(
         1,
@@ -3260,10 +3464,11 @@ describe('Multisig', () => {
         ok: true,
         json: async () => ({ success: true, message: 'ok', ack_pubkey: '0x' + 'f'.repeat(64) }),
       });
-      mockWebClient.transactions.submit.mockResolvedValueOnce({});
-
       await expect(multisig.executeProposal(proposalId)).resolves.toBeUndefined();
-      expect(mockWebClient.transactions.submit).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.executeTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.proveTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.submitProvenTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.applyTransaction).toHaveBeenCalledTimes(1);
     });
 
     it('should still switch GUARDIAN when the pre-switch canonicalization push fails', async () => {
@@ -3311,10 +3516,11 @@ describe('Multisig', () => {
         ok: true,
         json: async () => ({ success: true, message: 'ok', ack_pubkey: '0x' + 'f'.repeat(64) }),
       });
-      mockWebClient.transactions.submit.mockResolvedValueOnce({});
-
       await expect(multisig.executeProposal(proposalId)).resolves.toBeUndefined();
-      expect(mockWebClient.transactions.submit).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.executeTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.proveTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.submitProvenTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.applyTransaction).toHaveBeenCalledTimes(1);
     });
 
     it('should reject switch_guardian execution when endpoint commitment mismatches', async () => {
@@ -3453,6 +3659,45 @@ describe('Multisig', () => {
     });
   });
 
+  describe('submitTransaction', () => {
+    it('uses the configured total proof-attempt budget without repeating other stages', async () => {
+      const multisig = createTestMultisig(
+        {
+          threshold: 1,
+          signerCommitments: ['0x' + 'a'.repeat(64)],
+          guardianCommitment: '0x' + 'c'.repeat(64),
+        },
+        mockSigner,
+        undefined,
+        {
+          kind: 'remote',
+          maxAttempts: 4,
+          createProver: () => ({} as never),
+        },
+      );
+      const transient = Object.assign(new Error('unavailable'), { code: 'Unavailable' });
+      mockWebClient.proveTransaction
+        .mockRejectedValueOnce(transient)
+        .mockRejectedValueOnce(transient)
+        .mockRejectedValueOnce(transient)
+        .mockResolvedValueOnce({});
+
+      vi.useFakeTimers();
+      try {
+        const submission = multisig.submitTransaction({} as never);
+        await vi.runAllTimersAsync();
+        await submission;
+      } finally {
+        vi.useRealTimers();
+      }
+
+      expect(mockWebClient.executeTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.proveTransaction).toHaveBeenCalledTimes(4);
+      expect(mockWebClient.submitProvenTransaction).toHaveBeenCalledTimes(1);
+      expect(mockWebClient.applyTransaction).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('prepareCustomExecution', () => {
     const requestBytes = new Uint8Array([9, 8, 7]);
 

package/src/multisig.ts

@@ -19,7 +19,6 @@ import type {
 import type { ProcedureName } from './procedures.js';
 import type {
   MidenClient,
-  TransactionProver,
   WasmWebClient,
 } from '@miden-sdk/miden-sdk';
 import {
@@ -29,6 +28,8 @@ import {
   Endpoint,
   FeltArray,
   Note,
+  NoteExportFormat,
+  NoteFile,
   NoteType,
   RpcClient,
   Signature,
@@ -42,6 +43,7 @@ import {
   buildUpdateProcedureThresholdTransactionRequest,
   buildUpdateGuardianTransactionRequest,
   buildConsumeNotesTransactionRequest,
+  buildP2idNoteFromMetadata,
   buildP2idTransactionRequest,
   parseP2idNoteType,
   p2idNoteTypeToMetadata,
@@ -81,6 +83,11 @@ import {
   getTransactionProver,
   requireMidenRpcEndpoint,
 } from './raw-client.js';
+import {
+  resolveProverConfig,
+  type ResolvedProverConfig,
+} from './prover/config.js';
+import { ProverWorkflow } from './prover/workflow.js';
 
 /**
  * Result of fetching account state from GUARDIAN.
@@ -143,7 +150,7 @@ export class Multisig {
   private readonly signer: Signer;
   private readonly midenClient: MidenClient;
   private readonly rawClientPromise: Promise<WasmWebClient>;
-  private readonly transactionProver: TransactionProver | null;
+  private readonly proverWorkflow: ProverWorkflow;
   private readonly _accountId: string;
   private readonly midenRpcEndpoint: string;
   private proposals: Map<string, Proposal> = new Map();
@@ -155,7 +162,8 @@ export class Multisig {
     signer: Signer,
     midenClient: MidenClient,
     accountId: string | undefined,
-    midenRpcEndpoint: string
+    midenRpcEndpoint: string,
+    proverConfig?: ResolvedProverConfig,
   ) {
     this.account = account;
     this.threshold = config.threshold;
@@ -170,8 +178,11 @@ export class Multisig {
     this.midenClient = midenClient;
     this._accountId = accountId ?? (account ? accountIdToHex(account) : '');
     this.midenRpcEndpoint = requireMidenRpcEndpoint(midenRpcEndpoint);
-    this.transactionProver = getTransactionProver(midenClient);
     this.rawClientPromise = getRawMidenClient(midenClient, this.midenRpcEndpoint);
+    this.proverWorkflow = new ProverWorkflow(
+      this.midenClient,
+      proverConfig ?? resolveProverConfig(undefined, getTransactionProver(midenClient)),
+    );
   }
 
   private getMidenRpcEndpoint(): string {
@@ -949,6 +960,151 @@ export class Multisig {
     return notes;
   }
 
+  /**
+   * Export a note created by this multisig account as serialized note-file
+   * bytes for out-of-band delivery (issue #356).
+   *
+   * 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
+   * bytes produced here, which they load with {@link importNoteFromBytes}.
+   *
+   * The note must be an output note of this client (created by a transaction
+   * this client executed). When the note's on-chain inclusion proof is
+   * already known (after a post-commit sync) the full note with proof is
+   * exported; otherwise the note details are exported and the importer's
+   * client tracks the note until it commits on chain.
+   *
+   * @param noteId - ID of the note to export (hex string)
+   * @returns Serialized note file bytes
+   */
+  async exportNoteToBytes(noteId: string): Promise<Uint8Array> {
+    const webClient = await this.getRawClient();
+    const trimmedNoteId = noteId.trim();
+
+    let record;
+    try {
+      record = await webClient.getOutputNote(trimmedNoteId);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Output note ${trimmedNoteId} not found in the local store; only notes created by this client can be exported: ${detail}`,
+      );
+    }
+    if (!record) {
+      throw new Error(
+        `Output note ${trimmedNoteId} not found in the local store; only notes created by this client can be exported`,
+      );
+    }
+
+    const format = record.inclusionProof()
+      ? NoteExportFormat.Full
+      : NoteExportFormat.Details;
+    const noteFile = await webClient.exportNoteFile(trimmedNoteId, format);
+    return noteFile.serialize();
+  }
+
+  /**
+   * Export a note created by this multisig account as a note file downloaded
+   * by the browser (issue #356). Browser-only convenience over
+   * {@link exportNoteToBytes}; use that method directly in non-DOM
+   * environments.
+   *
+   * @param noteId - ID of the note to export (hex string)
+   * @param filename - Download filename; defaults to `note_<id>.mno`
+   */
+  async exportNoteToFile(noteId: string, filename?: string): Promise<void> {
+    if (typeof document === 'undefined') {
+      throw new Error('exportNoteToFile requires a browser environment; use exportNoteToBytes instead');
+    }
+
+    const trimmedNoteId = noteId.trim();
+    const noteBytes = await this.exportNoteToBytes(trimmedNoteId);
+
+    const blob = new Blob([noteBytes as BlobPart], { type: 'application/octet-stream' });
+    const url = URL.createObjectURL(blob);
+    try {
+      const anchor = document.createElement('a');
+      anchor.href = url;
+      anchor.download = filename ?? `note_${trimmedNoteId}.mno`;
+      anchor.click();
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+  }
+
+  /**
+   * Import a note file received out-of-band (issue #356) so the note can be
+   * consumed by this multisig account.
+   *
+   * Sync the Miden client with the network afterwards so the note's on-chain
+   * commitment is tracked and the note shows up in {@link getConsumableNotes};
+   * it can then be consumed via {@link createConsumeNotesProposal}.
+   *
+   * @param noteBytes - Serialized note file bytes produced by
+   *   {@link exportNoteToBytes}
+   * @returns The note ID when the file carries one, or the note's details
+   *   commitment for a details-only file
+   */
+  async importNoteFromBytes(noteBytes: Uint8Array): Promise<string> {
+    const webClient = await this.getRawClient();
+
+    let noteFile: NoteFile;
+    try {
+      noteFile = NoteFile.deserialize(noteBytes);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`failed to decode note file: ${detail}`);
+    }
+
+    return webClient.importNoteFile(noteFile);
+  }
+
+  /**
+   * Import a note file received out-of-band (issue #356) from a browser
+   * `File`/`Blob` (e.g. a file-input selection). See
+   * {@link importNoteFromBytes} for the returned identifier semantics.
+   */
+  async importNoteFromFile(file: Blob): Promise<string> {
+    const noteBytes = new Uint8Array(await file.arrayBuffer());
+    return this.importNoteFromBytes(noteBytes);
+  }
+
+  /**
+   * Compute the ID of the note a P2ID proposal will create when executed.
+   *
+   * 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).
+   *
+   * Call this before executing the proposal: the asset is derived from the
+   * current vault state, which execution itself changes.
+   */
+  async getP2idNoteId(proposal: Proposal): Promise<string> {
+    const metadata = proposal.metadata;
+    if (
+      metadata.proposalType !== 'p2id' ||
+      !metadata.recipientId ||
+      !metadata.faucetId ||
+      !metadata.amount ||
+      !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,
+    );
+    return note.id().toString();
+  }
+
   /**
    * Sign a proposal.
    *
@@ -1051,7 +1207,7 @@ export class Multisig {
     const { metadata, finalRequest, proposal } = await this.prepareProposalExecution(proposalId);
 
     const accountId = AccountId.fromHex(this._accountId);
-    await this.midenClient.transactions.submit(accountId, finalRequest);
+    await this.proverWorkflow.submit(accountId, finalRequest);
 
     if (metadata.proposalType === 'switch_guardian') {
       if (!metadata.newGuardianEndpoint || !metadata.newGuardianPubkey) {
@@ -1110,7 +1266,7 @@ export class Multisig {
    * after `prepareCustomExecution` rebuilds its request with the returned advice.
    */
   async submitTransaction(request: TransactionRequest): Promise<void> {
-    await this.midenClient.transactions.submit(AccountId.fromHex(this._accountId), request);
+    await this.proverWorkflow.submit(AccountId.fromHex(this._accountId), request);
   }
 
   /**

package/src/proposal/factory.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import type { DeltaStatus } from '@openzeppelin/guardian-client';
+import { ProposalFactory } from './factory.js';
+
+describe('ProposalFactory.toStatus', () => {
+  const factory = new ProposalFactory({
+    accountId: '0x' + 'a'.repeat(30),
+    signerCommitments: [],
+    resolveRequiredSignatures: () => 2,
+  });
+  // TS `private` is compile-time only; the mapping is worth pinning
+  // without dragging a full tx summary through `fromDelta`.
+  const toStatus = (status: DeltaStatus) =>
+    (factory as unknown as { toStatus: (s: DeltaStatus, t: string, sigs: unknown[]) => string })
+      .toStatus(status, 'p2id', []);
+
+  it('maps every terminal delta status to finalized (issue #345)', () => {
+    // A retained delta left the active candidate path: no longer
+    // signable, so finalized here — whether it landed is resolved by
+    // background reconciliation via the delta status, not the proposal
+    // list.
+    expect(toStatus({ status: 'canonical', timestamp: 't' })).toBe('finalized');
+    // Cast until the published guardian-client types include `retained`.
+    expect(
+      toStatus({
+        status: 'retained',
+        timestamp: 't',
+        reason: 'retry_exhausted',
+      } as unknown as DeltaStatus),
+    ).toBe('finalized');
+    expect(toStatus({ status: 'discarded', timestamp: 't' })).toBe('finalized');
+  });
+
+  it('maps active statuses to pending/ready', () => {
+    expect(toStatus({ status: 'candidate', timestamp: 't' })).toBe('ready');
+    expect(
+      toStatus({ status: 'pending', timestamp: 't', proposerId: 'p', cosignerSigs: [] }),
+    ).toBe('pending');
+  });
+});

package/src/proposal/factory.ts

@@ -156,7 +156,11 @@ export class ProposalFactory {
     proposalType: ProposalType,
     signatures: ProposalSignatureEntry[],
   ): ProposalStatus {
-    switch (status.status) {
+    // The explicit widening keeps this compiling against published
+    // @openzeppelin/guardian-client types that predate the `retained`
+    // status (issue #345); it becomes redundant — but stays correct —
+    // once the lockfile picks up a release that includes it.
+    switch (status.status as DeltaStatus['status'] | 'retained') {
       case 'pending': {
         const signaturesRequired = this.options.resolveRequiredSignatures(proposalType);
         return signatures.length >= signaturesRequired ? 'ready' : 'pending';
@@ -164,6 +168,12 @@ export class ProposalFactory {
       case 'candidate':
         return 'ready';
       case 'canonical':
+      // A retained delta left the active candidate path (issue #345):
+      // no longer signable or submittable, so it is finalized from the
+      // proposal list's point of view. Whether its transaction landed is
+      // resolved by background reconciliation, surfaced via the delta
+      // status, not here.
+      case 'retained':
       case 'discarded':
         return 'finalized';
     }