@openzeppelin/miden-multisig-client 0.15.2 → 0.16.1

package/dist/multisig.test.js

@@ -2,10 +2,11 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { Multisig } from './multisig.js';
 import { GuardianHttpClient } from '@openzeppelin/guardian-client';
 import { buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildUpdateSignersTransactionRequest, 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
 vi.mock('@miden-sdk/miden-sdk', () => ({
@@ -15,6 +16,18 @@ vi.mock('@miden-sdk/miden-sdk', () => ({
     AccountId: {
         fromHex: vi.fn((hex) => ({ toString: () => hex })),
     },
+    NoteType: {
+        Private: 0,
+        Public: 1,
+    },
+    NoteExportFormat: {
+        Id: 0,
+        Full: 1,
+        Details: 2,
+    },
+    NoteFile: {
+        deserialize: mockNoteFileDeserialize,
+    },
     TransactionSummary: {
         deserialize: vi.fn().mockReturnValue({
             toCommitment: () => ({
@@ -79,6 +92,19 @@ 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) => {
+        if (value === undefined || value === 'public')
+            return 1;
+        if (value === 'private')
+            return 0;
+        throw new Error(`unsupported metadata.noteType '${value}': expected 'public' or 'private'`);
+    }),
+    p2idNoteTypeToMetadata: vi.fn((noteType) => (noteType === 0 ? 'private' : undefined)),
 }));
 vi.mock('./utils/signature.js', async () => {
     const actual = await vi.importActual('./utils/signature.js');
@@ -106,6 +132,7 @@ vi.mock('./inspector.js', () => ({
 // Mock fetch for GUARDIAN client
 const mockFetch = vi.fn();
 vi.stubGlobal('fetch', mockFetch);
+const MIDEN_RPC_ENDPOINT = 'https://rpc.devnet.miden.io';
 function mockedAccount(commitmentHex, nonce = 0) {
     return {
         commitment: () => ({
@@ -124,6 +151,9 @@ describe('Multisig', () => {
     let mockSigner;
     let mockAccount;
     let mockWebClient;
+    function createTestMultisig(config, signer = mockSigner, accountId, proverConfig) {
+        return new Multisig(mockAccount, config, guardian, signer, mockWebClient, accountId, MIDEN_RPC_ENDPOINT, proverConfig);
+    }
     beforeEach(() => {
         mockFetch.mockReset();
         vi.mocked(executeForSummary).mockResolvedValue({
@@ -176,13 +206,36 @@ 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, request) => {
+            const result = await mockWebClient.executeTransaction(accountId, request);
+            return {
+                result,
+                prove: async (options) => {
+                    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', () => {
         it('should create Multisig with account', () => {
@@ -191,7 +244,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             expect(multisig.threshold).toBe(2);
             expect(multisig.signerCommitments).toEqual(config.signerCommitments);
             expect(multisig.guardianCommitment).toBe(config.guardianCommitment);
@@ -204,10 +257,18 @@ describe('Multisig', () => {
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
             const accountId = '0x' + 'd'.repeat(30);
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient, accountId);
+            const multisig = createTestMultisig(config, mockSigner, accountId);
             expect(multisig.account).toBe(mockAccount);
             expect(multisig.accountId).toBe(accountId);
         });
+        it('should reject a missing Miden RPC endpoint immediately', () => {
+            const config = {
+                threshold: 2,
+                signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
+                guardianCommitment: '0x' + 'c'.repeat(64),
+            };
+            expect(() => new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient, undefined, undefined)).toThrow('missing required configuration: midenRpcEndpoint');
+        });
     });
     describe('accountId', () => {
         it('should return account ID from account', () => {
@@ -216,7 +277,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             expect(multisig.accountId).toBe('0x' + 'a'.repeat(30));
         });
         it('should return provided account ID when constructor override is set', () => {
@@ -226,7 +287,7 @@ describe('Multisig', () => {
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
             const accountId = '0x' + 'e'.repeat(30);
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient, accountId);
+            const multisig = createTestMultisig(config, mockSigner, accountId);
             expect(multisig.accountId).toBe(accountId);
         });
     });
@@ -237,7 +298,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             expect(multisig.signerCommitment).toBe(mockSigner.commitment);
         });
     });
@@ -248,7 +309,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => ({
@@ -399,14 +460,15 @@ describe('Multisig', () => {
             await expect(multisig.syncState()).rejects.toThrow('Refusing to overwrite local state');
             expect(mockWebClient.newAccount).not.toHaveBeenCalled();
         });
-        it('should throw when incoming state nonce is lower than local nonce', async () => {
+        it('keeps local state and refreshes config from it when GUARDIAN nonce is behind local', async () => {
             const config = {
                 threshold: 1,
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
             const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient, undefined, 'https://rpc.devnet.miden.io');
-            mockWebClient.getAccount.mockResolvedValueOnce(mockedAccount('0x' + 'a'.repeat(64), 3));
+            const localAccount = mockedAccount('0x' + 'a'.repeat(64), 3);
+            mockWebClient.getAccount.mockResolvedValueOnce(localAccount);
             mockAccountDeserialize.mockReturnValueOnce(mockedAccount('0x' + 'b'.repeat(64), 2));
             mockFetch.mockResolvedValueOnce({
                 ok: true,
@@ -418,8 +480,23 @@ describe('Multisig', () => {
                     updated_at: '2024-01-02T00:00:00Z',
                 }),
             });
-            await expect(multisig.syncState()).rejects.toThrow('incoming nonce 2 is not greater than local nonce 3');
+            mockDetectConfig.mockReturnValueOnce({
+                threshold: 2,
+                numSigners: 2,
+                signerCommitments: ['0x' + '1'.repeat(64), '0x' + '2'.repeat(64)],
+                guardianEnabled: true,
+                guardianCommitment: '0x' + 'd'.repeat(64),
+                vaultBalances: [],
+                procedureThresholds: new Map(),
+            });
+            // GUARDIAN behind local (nonce 2 < 3): no throw, local kept, no overwrite,
+            // and the decision needs no on-chain round-trip.
+            await expect(multisig.syncState()).resolves.toBeDefined();
             expect(mockWebClient.newAccount).not.toHaveBeenCalled();
+            expect(mockRpcGetAccountDetails).not.toHaveBeenCalled();
+            // Config refreshed from the authoritative local account (UI unfreezes).
+            expect(multisig.account).toBe(localAccount);
+            expect(multisig.threshold).toBe(2);
         });
         it('should throw when incoming state nonce equals local nonce but commitment differs', async () => {
             const config = {
@@ -440,8 +517,35 @@ describe('Multisig', () => {
                     updated_at: '2024-01-02T00:00:00Z',
                 }),
             });
-            await expect(multisig.syncState()).rejects.toThrow('incoming nonce 2 is not greater than local nonce 2');
+            await expect(multisig.syncState()).rejects.toThrow('incoming nonce 2 equals local nonce 2 but commitments differ');
+            expect(mockWebClient.newAccount).not.toHaveBeenCalled();
+        });
+        it('unfreezes Multisig.account after execute when GUARDIAN still lags by one nonce (regression, #343)', async () => {
+            const config = {
+                threshold: 1,
+                signerCommitments: ['0x' + 'a'.repeat(64)],
+                guardianCommitment: '0x' + 'c'.repeat(64),
+            };
+            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient, undefined, 'https://rpc.devnet.miden.io');
+            // Post-execute: local advanced to nonce 1, GUARDIAN still reports nonce 0
+            // (candidate not canonicalized yet). Before the fix this threw and left
+            // Multisig.account frozen at the pre-execute snapshot.
+            const localAccount = mockedAccount('0x' + 'a'.repeat(64), 1);
+            mockWebClient.getAccount.mockResolvedValueOnce(localAccount);
+            mockAccountDeserialize.mockReturnValueOnce(mockedAccount('0x' + 'b'.repeat(64), 0));
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({
+                    account_id: multisig.accountId,
+                    commitment: '0x' + 'b'.repeat(64),
+                    state_json: { data: 'AQID' },
+                    created_at: '2024-01-01T00:00:00Z',
+                    updated_at: '2024-01-02T00:00:00Z',
+                }),
+            });
+            await expect(multisig.syncState()).resolves.toBeDefined();
             expect(mockWebClient.newAccount).not.toHaveBeenCalled();
+            expect(multisig.account).toBe(localAccount);
         });
     });
     describe('verifyStateCommitment', () => {
@@ -490,7 +594,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => ({
@@ -513,7 +617,7 @@ describe('Multisig', () => {
                 scheme: 'ecdsa',
             };
             guardian.setSigner(ecdsaSigner);
-            const multisig = new Multisig(mockAccount, config, guardian, ecdsaSigner, mockWebClient);
+            const multisig = createTestMultisig(config, ecdsaSigner);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => ({
@@ -537,7 +641,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient, '0x' + 'e'.repeat(30));
+            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient, '0x' + 'e'.repeat(30), MIDEN_RPC_ENDPOINT);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => ({
@@ -553,7 +657,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => ({
@@ -571,7 +675,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockProposals = [
                 {
                     account_id: '0x' + 'a'.repeat(30),
@@ -616,7 +720,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockProposals = [
                 {
                     account_id: '0x' + 'a'.repeat(30),
@@ -659,7 +763,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => ({
@@ -701,7 +805,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockProposals = [
                 {
                     account_id: '0x' + 'a'.repeat(30),
@@ -743,7 +847,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockProposals = [
                 {
                     account_id: '0x' + 'a'.repeat(30),
@@ -792,7 +896,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             expect(multisig.listProposals()).toEqual([]);
         });
     });
@@ -803,7 +907,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -841,7 +945,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -877,7 +981,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -927,7 +1031,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -960,6 +1064,178 @@ describe('Multisig', () => {
             const proposal = await multisig.createP2idProposal('0xrecipient', '0xfaucet', 100n, 1);
             expect(proposal.metadata.description).toBe('Send 100 of asset 0xfaucet... to 0xrecipien...');
         });
+        it('threads a private noteType into the request and wire metadata (issue #322)', async () => {
+            const { executeForSummary, buildP2idTransactionRequest } = await import('./transaction.js');
+            const { NoteType } = await import('@miden-sdk/miden-sdk');
+            vi.mocked(executeForSummary).mockResolvedValue({
+                toCommitment: () => ({
+                    toHex: () => '0x' + 'c'.repeat(64),
+                }),
+                serialize: () => new Uint8Array([1, 2, 3]),
+            });
+            const config = {
+                threshold: 1,
+                signerCommitments: ['0x' + 'a'.repeat(64)],
+                guardianCommitment: '0x' + 'c'.repeat(64),
+            };
+            const multisig = createTestMultisig(config);
+            const mockDelta = {
+                account_id: '0x' + 'a'.repeat(30),
+                nonce: 1,
+                prev_commitment: '0x' + 'b'.repeat(64),
+                delta_payload: {
+                    tx_summary: { data: 'AQID' },
+                    signatures: [],
+                    metadata: {
+                        proposal_type: 'p2id',
+                        recipient_id: '0xrecipient',
+                        faucet_id: '0xfaucet',
+                        amount: '100',
+                        note_type: 'private',
+                        description: '',
+                    },
+                },
+                status: {
+                    status: 'pending',
+                    timestamp: '2024-01-01T00:00:00Z',
+                    proposer_id: '0x' + 'c'.repeat(64),
+                    cosigner_sigs: [],
+                },
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({
+                    delta: mockDelta,
+                    commitment: '0x' + 'c'.repeat(64),
+                }),
+            });
+            const proposal = await multisig.createP2idProposal('0xrecipient', '0xfaucet', 100n, 1, {
+                noteType: NoteType.Private,
+            });
+            // Propose path builds the private note...
+            expect(vi.mocked(buildP2idTransactionRequest)).toHaveBeenCalledWith(expect.any(String), '0xrecipient', '0xfaucet', 100n, expect.anything(), { noteType: NoteType.Private });
+            // ...and the rebuild-from-metadata path parses note_type back to Private.
+            const lastCall = vi.mocked(buildP2idTransactionRequest).mock.calls.at(-1);
+            expect(lastCall[5]).toMatchObject({ noteType: NoteType.Private });
+            // The pushed wire metadata carries note_type so cosigners rebuild the
+            // same private note at verification/execution.
+            const pushBody = JSON.parse(mockFetch.mock.calls.at(-1)[1].body);
+            expect(pushBody.delta_payload.metadata.note_type).toBe('private');
+            expect(proposal.metadata.proposalType).toBe('p2id');
+            expect(proposal.metadata.noteType).toBe('private');
+        });
+    });
+    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',
+                },
+            };
+            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' },
+            };
+            await expect(multisig.getP2idNoteId(proposal)).rejects.toThrow(/requires a P2ID proposal/);
+        });
     });
     describe('createChangeThresholdProposal', () => {
         it('passes the signer scheme to update-signers requests', async () => {
@@ -1007,7 +1283,7 @@ describe('Multisig', () => {
                     commitment: '0x' + 'c'.repeat(64),
                 }),
             });
-            const multisig = new Multisig(mockAccount, config, guardian, ecdsaSigner, mockWebClient);
+            const multisig = createTestMultisig(config, ecdsaSigner);
             await multisig.createChangeThresholdProposal(2, 1);
             expect(buildUpdateSignersTransactionRequest).toHaveBeenCalledWith(mockWebClient, 2, config.signerCommitments, { signatureScheme: 'ecdsa' });
         });
@@ -1022,7 +1298,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const newGuardianPubkey = '0x' + '1'.repeat(64);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
@@ -1062,7 +1338,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => ({ commitment: '0x' + '2'.repeat(64) }),
@@ -1084,7 +1360,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, ecdsaSigner, mockWebClient);
+            const multisig = createTestMultisig(config, ecdsaSigner);
             const newGuardianCommitment = '0x' + '1'.repeat(64);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
@@ -1126,7 +1402,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -1181,7 +1457,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, ecdsaSigner, mockWebClient);
+            const multisig = createTestMultisig(config, ecdsaSigner);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -1221,7 +1497,7 @@ describe('Multisig', () => {
                 signerCommitments: [mockSigner.commitment],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             // First create a proposal
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
@@ -1290,7 +1566,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -1332,7 +1608,7 @@ describe('Multisig', () => {
                 signerCommitments: [mockSigner.commitment],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'd'.repeat(64);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
@@ -1373,7 +1649,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             vi.mocked(executeForSummary).mockResolvedValueOnce({
                 toCommitment: () => ({
                     toHex: () => '0x' + 'f'.repeat(64),
@@ -1401,7 +1677,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             vi.mocked(executeForSummary).mockResolvedValueOnce({
                 toCommitment: () => ({
                     toHex: () => '0x' + 'c'.repeat(64),
@@ -1441,7 +1717,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockProposals = [
                 {
                     account_id: '0x' + 'a'.repeat(30),
@@ -1488,7 +1764,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const publicKey = '0x' + 'd'.repeat(66);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
@@ -1541,12 +1817,18 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             mockFetch.mockResolvedValueOnce({
                 ok: false,
                 status: 404,
                 statusText: 'Not Found',
-                text: async () => 'Proposal not found',
+                // Feature 009: only a conforming { code, message, meta } envelope is
+                // folded into the error message; raw text bodies are dropped.
+                text: async () => JSON.stringify({
+                    code: 'GUARDIAN_PROPOSAL_NOT_FOUND',
+                    message: 'Proposal not found',
+                    meta: { retryable: false },
+                }),
             });
             await expect(multisig.exportProposal('0x' + 'nonexistent'.repeat(5))).rejects.toThrow('Proposal not found');
         });
@@ -1558,7 +1840,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const exported = {
                 accountId: multisig.accountId,
                 nonce: 1,
@@ -1585,7 +1867,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const publicKey = '0x' + 'd'.repeat(66);
             const proposal = await multisig.importProposal(JSON.stringify({
                 accountId: multisig.accountId,
@@ -1626,7 +1908,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             await expect(multisig.importProposal(JSON.stringify({
                 accountId: multisig.accountId,
                 nonce: 1,
@@ -1653,7 +1935,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), mockSigner.commitment],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const exported = {
                 accountId: multisig.accountId,
                 nonce: 1,
@@ -1689,7 +1971,7 @@ describe('Multisig', () => {
                 scheme: 'ecdsa',
                 publicKey: '0x' + '2'.repeat(66),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, ecdsaSigner, mockWebClient);
+            const multisig = createTestMultisig(config, ecdsaSigner);
             const cachedProposalId = '0x' + 'c'.repeat(64);
             const requestedProposalId = '0x' + 'C'.repeat(64);
             const cosignerPubkey = '0x' + '3'.repeat(66);
@@ -1781,7 +2063,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             const newGuardianPubkey = '0x' + '1'.repeat(64);
             const finalRequest = { kind: 'final-switch-guardian-request' };
@@ -1829,7 +2111,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             await expect(multisig.createTransactionProposalRequest('0x' + 'nonexistent'.repeat(5))).rejects.toThrow('Proposal not found');
         });
         it('should throw if proposal is still pending', async () => {
@@ -1838,7 +2120,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockProposals = [
                 {
                     account_id: '0x' + 'a'.repeat(30),
@@ -1881,7 +2163,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             vi.mocked(executeForSummary).mockResolvedValueOnce({
                 toCommitment: () => ({
@@ -1917,7 +2199,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             multisig.proposals.set(proposalId, {
                 id: proposalId,
@@ -1952,7 +2234,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             multisig.proposals.set(proposalId, {
                 id: proposalId,
@@ -2012,7 +2294,7 @@ describe('Multisig', () => {
                     signerCommitments: ['0x' + 'a'.repeat(64)],
                     guardianCommitment: '0x' + 'c'.repeat(64),
                 };
-                const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+                const multisig = createTestMultisig(config);
                 const proposalId = '0x' + 'c'.repeat(64);
                 const finalRequest = { kind: 'fresh-message-word-request' };
                 vi.mocked(buildUpdateSignersTransactionRequest)
@@ -2105,7 +2387,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             multisig.proposals.set(proposalId, {
                 id: proposalId,
@@ -2142,7 +2424,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             await expect(multisig.executeProposal('0x' + 'nonexistent'.repeat(5))).rejects.toThrow('Proposal not found');
         });
         it('should throw if proposal is still pending', async () => {
@@ -2151,7 +2433,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             // Sync with pending proposal (only 1 signature)
             const mockProposals = [
                 {
@@ -2196,7 +2478,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const readyDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -2258,7 +2540,11 @@ describe('Multisig', () => {
                 scheme: 'ecdsa',
                 publicKey: '0x' + '2'.repeat(66),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, ecdsaSigner, mockWebClient);
+            const multisig = createTestMultisig(config, ecdsaSigner, undefined, {
+                kind: 'remote',
+                maxAttempts: 2,
+                createProver: () => ({}),
+            });
             const proposalId = '0x' + 'c'.repeat(64);
             const cosignerPubkey = '0x' + '3'.repeat(66);
             const ackPubkey = '0x' + '4'.repeat(66);
@@ -2321,9 +2607,22 @@ 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, cosignerSignature, 'ecdsa');
             expect(vi.mocked(signatureHexToBytes)).toHaveBeenNthCalledWith(2, ackSignature, 'ecdsa');
             expect(vi.mocked(buildSignatureAdviceEntry)).toHaveBeenNthCalledWith(1, expect.anything(), expect.anything(), expect.anything(), cosignerPubkey, cosignerSignature);
@@ -2344,7 +2643,7 @@ describe('Multisig', () => {
                 scheme: 'ecdsa',
                 publicKey: '0x' + '2'.repeat(66),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, ecdsaSigner, mockWebClient);
+            const multisig = createTestMultisig(config, ecdsaSigner);
             const proposalId = '0x' + 'c'.repeat(64);
             const cosignerPubkey = '0x' + '3'.repeat(66);
             const ackPubkey = '0x' + '4'.repeat(66);
@@ -2404,8 +2703,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, cosignerSignature, 'ecdsa');
             expect(vi.mocked(signatureHexToBytes)).toHaveBeenNthCalledWith(2, ackSignature, 'ecdsa');
             expect(vi.mocked(buildSignatureAdviceEntry)).toHaveBeenNthCalledWith(1, expect.anything(), expect.anything(), expect.anything(), cosignerPubkey, cosignerSignature);
@@ -2417,7 +2719,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             const newGuardianPubkey = '0x' + '1'.repeat(64);
             multisig.proposals.set(proposalId, {
@@ -2485,9 +2787,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 () => {
             const config = {
@@ -2495,7 +2799,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             const newGuardianPubkey = '0x' + '1'.repeat(64);
             multisig.proposals.set(proposalId, {
@@ -2531,9 +2835,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 () => {
             const config = {
@@ -2541,7 +2847,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             multisig.proposals.set(proposalId, {
                 id: proposalId,
@@ -2576,7 +2882,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             multisig.proposals.set(proposalId, {
                 id: proposalId,
@@ -2621,7 +2927,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const proposalId = '0x' + 'c'.repeat(64);
             multisig.proposals.set(proposalId, {
                 id: proposalId,
@@ -2651,6 +2957,38 @@ describe('Multisig', () => {
             await expect(multisig.executeProposal(proposalId)).rejects.toThrow('Duplicate advice-map key detected');
         });
     });
+    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: () => ({}),
+            });
+            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({});
+                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]);
         function customDelta(proposalType, cosignerSigs) {
@@ -2687,7 +3025,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const builtinDelta = {
                 ...customDelta('change_threshold', [falconSig('0x' + 'a'.repeat(64))]),
             };
@@ -2709,7 +3047,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => customDelta('b2agg', [falconSig('0x' + 'a'.repeat(64))]),
@@ -2722,7 +3060,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             // Signed commitment comes from TransactionSummary.deserialize -> 'c' * 64.
             // Make the binding request derive a different commitment so the check fails.
             vi.mocked(executeForSummary).mockResolvedValueOnce({
@@ -2743,7 +3081,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const ready = customDelta('b2agg', [falconSig('0x' + 'a'.repeat(64))]);
             // getDeltaProposal
             mockFetch.mockResolvedValueOnce({
@@ -2765,7 +3103,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             // Create a proposal with metadata
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
@@ -2818,7 +3156,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             // Sync proposals - no local proposals exist
             const mockProposals = [
                 {
@@ -2859,7 +3197,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -2901,7 +3239,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -2945,7 +3283,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const mockDelta = {
                 account_id: '0x' + 'a'.repeat(30),
                 nonce: 1,
@@ -2990,7 +3328,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             // First sync with 1 signature (pending)
             const mockProposalsPending = [
                 {
@@ -3074,7 +3412,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64), '0x' + 'c'.repeat(64)],
                 guardianCommitment: '0x' + 'd'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             expect(multisig.threshold).toBe(3);
         });
         it('should expose signerCommitments', () => {
@@ -3084,7 +3422,7 @@ describe('Multisig', () => {
                 signerCommitments,
                 guardianCommitment: '0x' + 'd'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             expect(multisig.signerCommitments).toEqual(signerCommitments);
         });
         it('should expose guardianCommitment', () => {
@@ -3094,7 +3432,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment,
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             expect(multisig.guardianCommitment).toBe(guardianCommitment);
         });
         it('should expose account when provided', () => {
@@ -3103,7 +3441,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'd'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             expect(multisig.account).toBe(mockAccount);
         });
     });
@@ -3114,7 +3452,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             // Simulates a GUARDIAN response with canonical snake_case metadata
             const rustProposals = [
                 {
@@ -3158,7 +3496,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             // P2ID proposal with canonical snake_case fields
             const p2idProposals = [
                 {
@@ -3209,7 +3547,7 @@ describe('Multisig', () => {
                 signerCommitments: ['0x' + 'a'.repeat(64)],
                 guardianCommitment: '0x' + 'c'.repeat(64),
             };
-            const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+            const multisig = createTestMultisig(config);
             const switchGuardianProposals = [
                 {
                     account_id: '0x' + 'a'.repeat(30),