@openzeppelin/miden-multisig-client 0.15.2 → 0.16.0

package/dist/multisig.test.js

@@ -15,6 +15,10 @@ vi.mock('@miden-sdk/miden-sdk', () => ({
     AccountId: {
         fromHex: vi.fn((hex) => ({ toString: () => hex })),
     },
+    NoteType: {
+        Private: 0,
+        Public: 1,
+    },
     TransactionSummary: {
         deserialize: vi.fn().mockReturnValue({
             toCommitment: () => ({
@@ -79,6 +83,16 @@ vi.mock('./transaction.js', () => ({
         request: {},
         salt: { toHex: () => '0x' + 'd'.repeat(64) },
     }),
+    // 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 +120,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 +139,9 @@ describe('Multisig', () => {
     let mockSigner;
     let mockAccount;
     let mockWebClient;
+    function createTestMultisig(config, signer = mockSigner, accountId) {
+        return new Multisig(mockAccount, config, guardian, signer, mockWebClient, accountId, MIDEN_RPC_ENDPOINT);
+    }
     beforeEach(() => {
         mockFetch.mockReset();
         vi.mocked(executeForSummary).mockResolvedValue({
@@ -191,7 +209,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 +222,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 +242,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 +252,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 +263,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 +274,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 +425,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 +445,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,9 +482,36 @@ 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', () => {
         it('should pass when local and on-chain commitments match', async () => {
@@ -490,7 +559,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 +582,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 +606,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 +622,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 +640,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 +685,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 +728,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 +770,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 +812,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 +861,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 +872,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 +910,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 +946,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 +996,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 +1029,66 @@ 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('createChangeThresholdProposal', () => {
         it('passes the signer scheme to update-signers requests', async () => {
@@ -1007,7 +1136,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 +1151,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 +1191,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 +1213,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 +1255,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 +1310,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 +1350,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 +1419,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 +1461,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 +1502,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 +1530,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 +1570,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 +1617,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 +1670,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 +1693,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 +1720,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 +1761,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 +1788,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 +1824,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 +1916,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 +1964,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 +1973,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 +2016,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 +2052,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 +2087,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 +2147,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 +2240,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 +2277,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 +2286,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 +2331,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 +2393,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);
@@ -2344,7 +2479,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);
@@ -2417,7 +2552,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, {
@@ -2495,7 +2630,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, {
@@ -2541,7 +2676,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 +2711,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 +2756,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,
@@ -2687,7 +2822,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 +2844,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 +2857,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 +2878,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 +2900,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 +2953,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 +2994,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 +3036,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 +3080,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 +3125,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 +3209,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 +3219,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 +3229,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 +3238,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 +3249,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 +3293,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 +3344,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),