@openzeppelin/miden-multisig-client 0.12.6

package/src/client.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { MultisigClient } from './client.js';
+import type { Signer } from './types.js';
+
+// Mock the Miden SDK
+vi.mock('@demox-labs/miden-sdk', () => ({
+  AccountId: {
+    fromHex: vi.fn((hex: string) => ({ toString: () => hex })),
+  },
+  Account: {
+    deserialize: vi.fn(() => ({
+      id: () => ({
+        toString: () => '0x' + 'd'.repeat(30),
+        prefix: () => ({ asInt: () => BigInt(1) }),
+        suffix: () => ({ asInt: () => BigInt(2) }),
+      }),
+      storage: vi.fn(),
+      vault: vi.fn(),
+    })),
+  },
+}));
+
+// Mock the AccountInspector
+vi.mock('./inspector.js', () => ({
+  AccountInspector: {
+    fromAccount: vi.fn(() => ({
+      threshold: 2,
+      numSigners: 2,
+      signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
+      psmEnabled: true,
+      psmCommitment: '0x' + 'c'.repeat(64),
+      vaultBalances: [],
+      procedureThresholds: new Map(),
+    })),
+  },
+}));
+
+// Mock the account creation module
+vi.mock('./account/index.js', () => ({
+  createMultisigAccount: vi.fn().mockResolvedValue({
+    account: {
+      id: () => ({
+        toString: () => '0x' + 'a'.repeat(30),
+        prefix: () => ({ asInt: () => BigInt(1) }),
+        suffix: () => ({ asInt: () => BigInt(2) }),
+      }),
+      serialize: () => new Uint8Array([1, 2, 3]),
+    },
+    seed: new Uint8Array([4, 5, 6]),
+  }),
+}));
+
+// Mock fetch for PSM client
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+describe('MultisigClient', () => {
+  let webClient: any;
+  let mockSigner: Signer;
+
+  beforeEach(() => {
+    mockFetch.mockReset();
+
+    webClient = {
+      createScriptBuilder: vi.fn(),
+      executeTransaction: vi.fn(),
+      proveTransaction: vi.fn(),
+      submitProvenTransaction: vi.fn(),
+      applyTransaction: vi.fn(),
+      syncState: vi.fn(),
+      newAccount: vi.fn(),
+      getAccount: vi.fn().mockResolvedValue(null),
+    };
+
+    mockSigner = {
+      commitment: '0x' + '1'.repeat(64),
+      publicKey: '0x' + '2'.repeat(64),
+      signAccountIdWithTimestamp: vi.fn().mockReturnValue('0x' + 'a'.repeat(128)),
+      signCommitment: vi.fn().mockReturnValue('0x' + 'b'.repeat(128)),
+    };
+  });
+
+  describe('constructor', () => {
+    it('should create client with default PSM endpoint', () => {
+      const client = new MultisigClient(webClient);
+      expect(client).toBeInstanceOf(MultisigClient);
+    });
+
+    it('should create client with custom PSM endpoint', () => {
+      const client = new MultisigClient(webClient, { psmEndpoint: 'http://custom:8080' });
+      expect(client).toBeInstanceOf(MultisigClient);
+    });
+  });
+
+  describe('psmClient getter', () => {
+    it('should expose PSM client for getting pubkey', () => {
+      const client = new MultisigClient(webClient);
+      expect(client.psmClient).toBeDefined();
+    });
+  });
+
+  describe('create', () => {
+    it('should create multisig and return Multisig instance', async () => {
+      const client = new MultisigClient(webClient);
+
+      const config = {
+        threshold: 2,
+        signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
+        psmCommitment: '0x' + 'c'.repeat(64),
+      };
+
+      const multisig = await client.create(config, mockSigner);
+
+      expect(multisig).toBeDefined();
+      expect(multisig.threshold).toBe(2);
+      expect(multisig.signerCommitments).toEqual(config.signerCommitments);
+      expect(multisig.psmCommitment).toBe(config.psmCommitment);
+    });
+
+    it('should set signer on PSM client', async () => {
+      const client = new MultisigClient(webClient);
+
+      const config = {
+        threshold: 1,
+        signerCommitments: ['0x' + 'a'.repeat(64)],
+        psmCommitment: '0x' + 'c'.repeat(64),
+      };
+
+      const multisig = await client.create(config, mockSigner);
+      expect(multisig.signerCommitment).toBe(mockSigner.commitment);
+    });
+  });
+
+  describe('load', () => {
+    it('should load existing multisig account and detect config', async () => {
+      const client = new MultisigClient(webClient);
+
+      // Mock getState response
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          account_id: '0x' + 'd'.repeat(30),
+          commitment: '0x' + 'e'.repeat(64),
+          state_json: { data: 'base64state' },
+          created_at: '2024-01-01T00:00:00Z',
+          updated_at: '2024-01-02T00:00:00Z',
+        }),
+      });
+
+      const accountId = '0x' + 'd'.repeat(30);
+      const multisig = await client.load(accountId, mockSigner);
+
+      expect(multisig).toBeDefined();
+      expect(multisig.accountId).toBe(accountId);
+      // Config is detected from account storage via AccountInspector
+      expect(multisig.threshold).toBe(2);
+      expect(multisig.signerCommitments).toEqual(['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)]);
+      expect(multisig.psmCommitment).toBe('0x' + 'c'.repeat(64));
+      expect(multisig.account).toBeNull(); // Loaded accounts don't have the SDK Account
+    });
+
+    it('should throw if account not found on PSM', async () => {
+      const client = new MultisigClient(webClient);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        text: async () => 'Account not found',
+      });
+
+      await expect(
+        client.load('0xnonexistent', mockSigner)
+      ).rejects.toThrow();
+    });
+  });
+});

package/src/client.ts

@@ -0,0 +1,129 @@
+/**
+ * MultisigClient - Factory for creating and loading multisig accounts.
+ *
+ * This is the main entry point for the multisig SDK. It provides methods
+ * to create new multisig accounts and load existing ones.
+ */
+
+import { type WebClient, Account, AccountId } from '@demox-labs/miden-sdk';
+import { PsmHttpClient } from '@openzeppelin/psm-client';
+import { Multisig } from './multisig.js';
+import { createMultisigAccount } from './account/index.js';
+import { AccountInspector } from './inspector.js';
+import type { MultisigConfig, Signer } from './types.js';
+
+/**
+ * Configuration for MultisigClient.
+ */
+export interface MultisigClientConfig {
+  /** PSM server endpoint */
+  psmEndpoint?: string;
+}
+
+/**
+ * Client for creating and loading multisig accounts.
+ *
+ * @example
+ * ```typescript
+ * import { MultisigClient, FalconSigner } from '@openzeppelin/miden-multisig-client';
+ * import { WebClient, SecretKey } from '@demox-labs/miden-sdk';
+ *
+ * // Initialize
+ * const webClient = await WebClient.createClient('https://rpc.testnet.miden.io:443');
+ * const secretKey = SecretKey.rpoFalconWithRNG(seed);
+ * const signer = new FalconSigner(secretKey);
+ *
+ * // Create client
+ * const client = new MultisigClient(webClient, { psmEndpoint: 'http://localhost:3000' });
+ *
+ * // Get PSM pubkey for config
+ * const psmCommitment = await client.psmClient.getPubkey();
+ *
+ * // Create multisig
+ * const config = { threshold: 2, signerCommitments: [...], psmCommitment };
+ * const multisig = await client.create(config, signer);
+ * ```
+ */
+export class MultisigClient {
+  private readonly webClient: WebClient;
+  private _psmClient: PsmHttpClient;
+
+  constructor(webClient: WebClient, config: MultisigClientConfig = {}) {
+    this.webClient = webClient;
+    this._psmClient = new PsmHttpClient(config.psmEndpoint ?? 'http://localhost:3000');
+  }
+
+  /**
+   * Change the PSM endpoint.
+   * 
+   * @param endpoint - The new PSM server endpoint URL
+   */
+  setPsmEndpoint(endpoint: string): void {
+    this._psmClient = new PsmHttpClient(endpoint);
+  }
+
+  /**
+   * Access the internal PSM client.
+   */
+  get psmClient(): PsmHttpClient {
+    return this._psmClient;
+  }
+
+  /**
+   * Create a new multisig account.
+   *
+   * @param config - Multisig configuration (threshold, signers, PSM commitment)
+   * @param signer - The signer for this client (one of the cosigners)
+   * @returns A Multisig instance wrapping the created account
+   */
+  async create(config: MultisigConfig, signer: Signer): Promise<Multisig> {
+    this._psmClient.setSigner(signer);
+
+    const { account } = await createMultisigAccount(this.webClient, config);
+
+    return new Multisig(account, config, this._psmClient, signer, this.webClient);
+  }
+
+  /**
+   * Load an existing multisig account from PSM.
+   *
+   * @param accountId - The account ID to load
+   * @param signer - The signer for this client
+   * @returns A Multisig instance for the loaded account
+   */
+  async load(accountId: string, signer: Signer): Promise<Multisig> {
+    this._psmClient.setSigner(signer);
+
+    const stateResponse = await this._psmClient.getState(accountId);
+
+    const accountBase64 = stateResponse.stateJson.data;
+    if (!accountBase64) {
+      throw new Error('No account data found in PSM state');
+    }
+
+    const binaryString = atob(accountBase64);
+    const accountBytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      accountBytes[i] = binaryString.charCodeAt(i);
+    }
+    const account = Account.deserialize(accountBytes);
+
+    const detected = AccountInspector.fromAccount(account);
+    const config: MultisigConfig = {
+      threshold: detected.threshold,
+      signerCommitments: detected.signerCommitments,
+      psmCommitment: detected.psmCommitment ?? '',
+      psmEnabled: detected.psmEnabled,
+      procedureThresholds: Array.from(detected.procedureThresholds.entries()).map(
+        ([procedure, threshold]) => ({ procedure, threshold })
+      ),
+    };
+
+    const existingAccount = await this.webClient.getAccount(AccountId.fromHex(accountId));
+    if (!existingAccount) {
+        await this.webClient.newAccount(account, true);
+    }
+
+    return new Multisig(null, config, this._psmClient, signer, this.webClient, accountId);
+  }
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+/**
+ * @openzeppelin/miden-multisig-client
+ *
+ * TypeScript SDK for Miden multisig accounts with PSM (Private State Manager) integration.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   MultisigClient,
+ *   FalconSigner,
+ * } from '@openzeppelin/miden-multisig-client';
+ * import { WebClient, SecretKey } from '@demox-labs/miden-sdk';
+ *
+ * // Initialize WebClient
+ * const webClient = await WebClient.createClient('https://rpc.testnet.miden.io:443');
+ * await webClient.syncState();
+ *
+ * // Generate a key dynamically
+ * const seed = new Uint8Array(32);
+ * crypto.getRandomValues(seed);
+ * const secretKey = SecretKey.rpoFalconWithRNG(seed);
+ *
+ * // Store in miden-sdk's keystore
+ * await webClient.addAccountSecretKeyToWebStore(secretKey);
+ *
+ * // Create a signer
+ * const signer = new FalconSigner(secretKey);
+ *
+ * // Create multisig client
+ * const client = new MultisigClient(webClient, { psmEndpoint: 'http://localhost:3000' });
+ *
+ * // Get PSM pubkey for config
+ * const psmCommitment = await client.psmClient.getPubkey();
+ *
+ * // Create multisig account
+ * const config = { threshold: 2, signerCommitments: [signer.commitment, ...], psmCommitment };
+ * const multisig = await client.create(config, signer);
+ *
+ * // Register on PSM and work with proposals
+ * await multisig.registerOnPsm();
+ * await multisig.syncProposals();
+ * ```
+ */
+
+export { MultisigClient, type MultisigClientConfig } from './client.js';
+export { Multisig, type AccountState } from './multisig.js';
+export { AccountInspector, type DetectedMultisigConfig, type VaultBalance } from './inspector.js';
+export {
+  executeForSummary,
+  buildUpdateSignersTransactionRequest,
+  buildUpdatePsmTransactionRequest,
+  buildConsumeNotesTransactionRequest,
+  buildP2idTransactionRequest,
+} from './transaction.js';
+
+export { PsmHttpClient, PsmHttpError } from '@openzeppelin/psm-client';
+
+export { FalconSigner } from './signer.js';
+
+export {
+  createMultisigAccount,
+  validateMultisigConfig,
+  buildMultisigStorageSlots,
+  buildPsmStorageSlots,
+  storageLayoutBuilder,
+  StorageLayoutBuilder,
+} from './account/index.js';
+
+export {
+  PROCEDURE_ROOTS,
+  getProcedureRoot,
+  isProcedureName,
+  getProcedureNames,
+  type ProcedureName,
+} from './procedures.js';
+
+export type {
+  // Account types
+  MultisigAccountState,
+  MultisigConfig,
+  CreateAccountResult,
+  ProcedureThreshold,
+
+  // Proposal types
+  Proposal,
+  ProposalStatus,
+  ProposalSignatureEntry,
+  ProposalMetadata,
+  ProposalType,
+  ExportedProposal,
+
+  // Transaction types
+  TransactionType,
+
+  // Note types
+  ConsumableNote,
+  NoteAsset,
+
+  // Signature types
+  FalconSignature,
+  Signer,
+
+  // PSM API types
+  AuthConfig,
+  DeltaObject,
+  DeltaStatus,
+  StateObject,
+  CosignerSignature,
+
+  // Request/Response types
+  ConfigureRequest,
+  ConfigureResponse,
+  DeltaProposalRequest,
+  DeltaProposalResponse,
+  ProposalsResponse,
+  PubkeyResponse,
+  SignProposalRequest,
+} from './types.js';

package/src/inspector.test.ts

@@ -0,0 +1,237 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AccountInspector } from './inspector.js';
+
+// Mock the Miden SDK
+vi.mock('@demox-labs/miden-sdk', () => {
+  const createMockWord = (values: bigint[]) => ({
+    toU64s: () => values,
+    toHex: () => '0x' + values.map(v => v.toString(16).padStart(16, '0')).join(''),
+  });
+
+  const createMockStorage = (slots: Map<number, any>, maps: Map<number, Map<string, any>>) => ({
+    getItem: (index: number) => slots.get(index) ?? createMockWord([0n, 0n, 0n, 0n]),
+    getMapItem: (slotIndex: number, key: any) => {
+      const map = maps.get(slotIndex);
+      if (!map) throw new Error('Map not found');
+      const keyStr = key.toU64s?.()[0]?.toString() ?? '0';
+      const value = map.get(keyStr);
+      if (!value) throw new Error('Key not found');
+      return value;
+    },
+  });
+
+  const createMockVault = (assets: Array<{ faucetId: string; amount: bigint }>) => ({
+    fungibleAssets: () => assets.map(a => ({
+      faucetId: () => ({ toString: () => a.faucetId }),
+      amount: () => a.amount,
+    })),
+  });
+
+  return {
+    Account: {
+      deserialize: vi.fn((bytes: Uint8Array) => {
+        // Return different mocked accounts based on test scenario
+        // Default: 2-of-3 multisig with PSM enabled
+        const slot0 = createMockWord([2n, 3n, 0n, 0n]); // threshold=2, numSigners=3
+        const slot4 = createMockWord([1n, 0n, 0n, 0n]); // PSM enabled
+
+        const signerMap = new Map<string, any>();
+        signerMap.set('0', createMockWord([BigInt('0x1111111111111111'), BigInt('0x2222222222222222'), BigInt('0x3333333333333333'), BigInt('0x4444444444444444')]));
+        signerMap.set('1', createMockWord([BigInt('0x5555555555555555'), BigInt('0x6666666666666666'), BigInt('0x7777777777777777'), BigInt('0x8888888888888888')]));
+        signerMap.set('2', createMockWord([BigInt('0xaaaaaaaaaaaaaaaa'), BigInt('0xbbbbbbbbbbbbbbbb'), BigInt('0xcccccccccccccccc'), BigInt('0xdddddddddddddddd')]));
+
+        const psmMap = new Map<string, any>();
+        psmMap.set('0', createMockWord([BigInt('0xeeeeeeeeeeeeeeee'), BigInt('0xffffffffffffffff'), BigInt('0x0000000000000001'), BigInt('0x0000000000000002')]));
+
+        const slots = new Map<number, any>();
+        slots.set(0, slot0);
+        slots.set(4, slot4);
+
+        const maps = new Map<number, Map<string, any>>();
+        maps.set(1, signerMap);
+        maps.set(5, psmMap);
+
+        return {
+          storage: () => createMockStorage(slots, maps),
+          vault: () => createMockVault([
+            { faucetId: '0xfaucet1', amount: 1000n },
+            { faucetId: '0xfaucet2', amount: 500n },
+          ]),
+        };
+      }),
+    },
+    Word: vi.fn().mockImplementation((arr: BigUint64Array) => ({
+      toU64s: () => Array.from(arr),
+      toHex: () => '0x' + Array.from(arr).map(v => v.toString(16).padStart(16, '0')).join(''),
+    })),
+  };
+});
+
+describe('AccountInspector', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('fromBase64', () => {
+    it('deserializes account from base64 and extracts config', () => {
+      const base64 = btoa(String.fromCharCode(...new Uint8Array([1, 2, 3])));
+      const config = AccountInspector.fromBase64(base64);
+
+      expect(config.threshold).toBe(2);
+      expect(config.numSigners).toBe(3);
+    });
+
+    it('extracts PSM status', () => {
+      const base64 = btoa(String.fromCharCode(...new Uint8Array([1, 2, 3])));
+      const config = AccountInspector.fromBase64(base64);
+
+      expect(config.psmEnabled).toBe(true);
+      expect(config.psmCommitment).toMatch(/^0x[a-f0-9]+$/);
+    });
+
+    it('extracts signer commitments', () => {
+      const base64 = btoa(String.fromCharCode(...new Uint8Array([1, 2, 3])));
+      const config = AccountInspector.fromBase64(base64);
+
+      expect(config.signerCommitments).toHaveLength(3);
+      config.signerCommitments.forEach(commitment => {
+        expect(commitment).toMatch(/^0x[a-f0-9]+$/);
+      });
+    });
+
+    it('extracts vault balances', () => {
+      const base64 = btoa(String.fromCharCode(...new Uint8Array([1, 2, 3])));
+      const config = AccountInspector.fromBase64(base64);
+
+      expect(config.vaultBalances).toHaveLength(2);
+      expect(config.vaultBalances[0]).toEqual({ faucetId: '0xfaucet1', amount: 1000n });
+      expect(config.vaultBalances[1]).toEqual({ faucetId: '0xfaucet2', amount: 500n });
+    });
+  });
+
+  describe('fromAccount', () => {
+    it('extracts threshold from slot 0', async () => {
+      const { Account } = await import('@demox-labs/miden-sdk');
+      const account = Account.deserialize(new Uint8Array([1, 2, 3]));
+      const config = AccountInspector.fromAccount(account);
+
+      expect(config.threshold).toBe(2);
+    });
+
+    it('extracts numSigners from slot 0', async () => {
+      const { Account } = await import('@demox-labs/miden-sdk');
+      const account = Account.deserialize(new Uint8Array([1, 2, 3]));
+      const config = AccountInspector.fromAccount(account);
+
+      expect(config.numSigners).toBe(3);
+    });
+  });
+});
+
+describe('AccountInspector edge cases', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('handles account with PSM disabled', async () => {
+    const { Account } = await import('@demox-labs/miden-sdk');
+
+    // Override mock for this test
+    vi.mocked(Account.deserialize).mockReturnValueOnce({
+      storage: () => ({
+        getItem: (index: number) => {
+          if (index === 0) return { toU64s: () => [1n, 1n, 0n, 0n] };
+          if (index === 4) return { toU64s: () => [0n, 0n, 0n, 0n] }; // PSM disabled
+          return { toU64s: () => [0n, 0n, 0n, 0n] };
+        },
+        getMapItem: (slotIndex: number, key: any) => {
+          if (slotIndex === 1 && key.toU64s?.()[0] === 0n) {
+            return {
+              toHex: () => '0x' + 'a'.repeat(64),
+              toU64s: () => [1n, 2n, 3n, 4n],
+            };
+          }
+          throw new Error('Not found');
+        },
+      }),
+      vault: () => ({
+        fungibleAssets: () => [],
+      }),
+    } as any);
+
+    const account = Account.deserialize(new Uint8Array([1, 2, 3]));
+    const config = AccountInspector.fromAccount(account);
+
+    expect(config.psmEnabled).toBe(false);
+    expect(config.psmCommitment).toBeNull();
+  });
+
+  it('handles account with empty vault', async () => {
+    const { Account } = await import('@demox-labs/miden-sdk');
+
+    vi.mocked(Account.deserialize).mockReturnValueOnce({
+      storage: () => ({
+        getItem: () => ({ toU64s: () => [1n, 1n, 0n, 0n] }),
+        getMapItem: () => {
+          throw new Error('Not found');
+        },
+      }),
+      vault: () => ({
+        fungibleAssets: () => [],
+      }),
+    } as any);
+
+    const account = Account.deserialize(new Uint8Array([1, 2, 3]));
+    const config = AccountInspector.fromAccount(account);
+
+    expect(config.vaultBalances).toEqual([]);
+  });
+
+  it('handles missing signer map entries gracefully', async () => {
+    const { Account } = await import('@demox-labs/miden-sdk');
+
+    vi.mocked(Account.deserialize).mockReturnValueOnce({
+      storage: () => ({
+        getItem: (index: number) => {
+          if (index === 0) return { toU64s: () => [2n, 5n, 0n, 0n] }; // threshold=2, numSigners=5
+          if (index === 4) return { toU64s: () => [0n, 0n, 0n, 0n] };
+          return { toU64s: () => [0n, 0n, 0n, 0n] };
+        },
+        getMapItem: () => {
+          throw new Error('Map entry not found');
+        },
+      }),
+      vault: () => ({
+        fungibleAssets: () => [],
+      }),
+    } as any);
+
+    const account = Account.deserialize(new Uint8Array([1, 2, 3]));
+    const config = AccountInspector.fromAccount(account);
+
+    // Should gracefully handle missing entries
+    expect(config.numSigners).toBe(5);
+    expect(config.signerCommitments).toEqual([]); // All entries missing
+  });
+
+  it('handles vault access error gracefully', async () => {
+    const { Account } = await import('@demox-labs/miden-sdk');
+
+    vi.mocked(Account.deserialize).mockReturnValueOnce({
+      storage: () => ({
+        getItem: () => ({ toU64s: () => [1n, 1n, 0n, 0n] }),
+        getMapItem: () => {
+          throw new Error('Not found');
+        },
+      }),
+      vault: () => {
+        throw new Error('Vault access failed');
+      },
+    } as any);
+
+    const account = Account.deserialize(new Uint8Array([1, 2, 3]));
+    const config = AccountInspector.fromAccount(account);
+
+    expect(config.vaultBalances).toEqual([]);
+  });
+});