@openzeppelin/miden-multisig-client 0.12.6 → 0.12.7

package/src/client.ts

@@ -1,49 +1,14 @@
-/**
- * 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 { PsmHttpClient, type SignatureScheme } 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;
@@ -53,29 +18,19 @@ export class MultisigClient {
     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.
-   */
+  async initialize(scheme?: SignatureScheme): Promise<{ psmCommitment: string; psmPublicKey?: string }> {
+    const { commitment, pubkey } = await this._psmClient.getPubkey(scheme);
+    return { psmCommitment: commitment, psmPublicKey: pubkey };
+  }
+
   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);
 
@@ -84,13 +39,6 @@ export class MultisigClient {
     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);
 
@@ -108,12 +56,15 @@ export class MultisigClient {
     }
     const account = Account.deserialize(accountBytes);
 
-    const detected = AccountInspector.fromAccount(account);
+    const detectedScheme: SignatureScheme = signer.scheme;
+
+    const detected = AccountInspector.fromAccount(account, detectedScheme);
     const config: MultisigConfig = {
       threshold: detected.threshold,
       signerCommitments: detected.signerCommitments,
       psmCommitment: detected.psmCommitment ?? '',
       psmEnabled: detected.psmEnabled,
+      signatureScheme: detected.signatureScheme,
       procedureThresholds: Array.from(detected.procedureThresholds.entries()).map(
         ([procedure, threshold]) => ({ procedure, threshold })
       ),

package/src/index.ts

@@ -1,47 +1,3 @@
-/**
- * @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';
@@ -55,7 +11,7 @@ export {
 
 export { PsmHttpClient, PsmHttpError } from '@openzeppelin/psm-client';
 
-export { FalconSigner } from './signer.js';
+export { FalconSigner, EcdsaSigner } from './signer.js';
 
 export {
   createMultisigAccount,
@@ -68,6 +24,8 @@ export {
 
 export {
   PROCEDURE_ROOTS,
+  PROCEDURE_ROOTS_FALCON,
+  PROCEDURE_ROOTS_ECDSA,
   getProcedureRoot,
   isProcedureName,
   getProcedureNames,
@@ -75,39 +33,32 @@ export {
 } from './procedures.js';
 
 export type {
-  // Account types
   MultisigAccountState,
   MultisigConfig,
   CreateAccountResult,
   ProcedureThreshold,
-
-  // Proposal types
-  Proposal,
-  ProposalStatus,
-  ProposalSignatureEntry,
+  TransactionProposal,
+  TransactionProposalStatus,
+  TransactionProposalSignature,
+  ExportedTransactionProposal,
+  SignTransactionProposalParams,
+  SyncResult,
+  TransactionProposalResult,
   ProposalMetadata,
   ProposalType,
-  ExportedProposal,
-
-  // Transaction types
   TransactionType,
-
-  // Note types
   ConsumableNote,
   NoteAsset,
-
-  // Signature types
   FalconSignature,
+  EcdsaSignature,
+  ProposalSignature,
+  SignatureScheme,
   Signer,
-
-  // PSM API types
   AuthConfig,
   DeltaObject,
   DeltaStatus,
   StateObject,
   CosignerSignature,
-
-  // Request/Response types
   ConfigureRequest,
   ConfigureResponse,
   DeltaProposalRequest,

package/src/inspector.ts

@@ -1,11 +1,8 @@
-/**
- * Account Inspector - Inspects account storage to detect multisig configuration.
- */
-
 import { Account, Word } from '@demox-labs/miden-sdk';
 import { base64ToUint8Array } from './utils/encoding.js';
 import { wordElementToBigInt, wordToHex } from './utils/word.js';
 import { getProcedureRoot, getProcedureNames, type ProcedureName } from './procedures.js';
+import type { SignatureScheme } from './types.js';
 
 export interface VaultBalance {
   faucetId: string;
@@ -20,44 +17,19 @@ export interface DetectedMultisigConfig {
   psmCommitment: string | null;
   vaultBalances: VaultBalance[];
   procedureThresholds: Map<ProcedureName, number>;
+  signatureScheme: SignatureScheme;
 }
 
-/**
- * Inspects an account to detect its multisig configuration.
- *
- * @example
- * ```typescript
- * // From base64-encoded state
- * const config = AccountInspector.fromBase64(stateDataBase64);
- * console.log(`${config.threshold}-of-${config.numSigners} multisig`);
- *
- * // From Miden SDK Account
- * const config = AccountInspector.fromAccount(account);
- * ```
- */
 export class AccountInspector {
   private constructor() {}
 
-  /**
-   * Inspect a base64-encoded serialized account.
-   *
-   * @param base64Data - Base64-encoded Account bytes
-   * @returns Detected multisig configuration
-   */
-  static fromBase64(base64Data: string): DetectedMultisigConfig {
+  static fromBase64(base64Data: string, signatureScheme: SignatureScheme = 'falcon'): DetectedMultisigConfig {
     const bytes = base64ToUint8Array(base64Data);
     const account = Account.deserialize(bytes);
-    return AccountInspector.fromAccount(account);
+    return AccountInspector.fromAccount(account, signatureScheme);
   }
 
-  /**
-   * Inspect a Miden SDK Account object.
-   *
-   * @param account - The Account object from Miden SDK
-   * @returns Detected multisig configuration
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  static fromAccount(account: Account): DetectedMultisigConfig {
+  static fromAccount(account: Account, signatureScheme: SignatureScheme = 'falcon'): DetectedMultisigConfig {
     const storage = account.storage();
 
     const slot0 = storage.getItem(0) as Word;
@@ -72,8 +44,8 @@ export class AccountInspector {
         if (commitment) {
           signerCommitments.push(wordToHex(commitment));
         }
-      } catch (error) {
-        console.warn(error);
+      } catch {
+        // Signer not found in storage map
       }
     }
 
@@ -92,8 +64,8 @@ export class AccountInspector {
           psmCommitment = wordToHex(psmKey);
         }
       }
-    } catch (error) {
-      console.warn(error);
+    } catch {
+      // PSM not configured
     }
 
     const vaultBalances: VaultBalance[] = [];
@@ -106,16 +78,14 @@ export class AccountInspector {
           amount: BigInt(asset.amount()),
         });
       }
-    } catch (error) {
-      console.warn(error);
+    } catch {
+      // Vault access failed
     }
 
-    // Read procedure threshold overrides from storage slot 3
-    // Storage layout: slot 3 is a map of PROC_ROOT => [threshold, 0, 0, 0]
     const procedureThresholds = new Map<ProcedureName, number>();
-    for (const procName of getProcedureNames()) {
+    for (const procName of getProcedureNames(signatureScheme)) {
       try {
-        const rootHex = getProcedureRoot(procName);
+        const rootHex = getProcedureRoot(procName, signatureScheme);
         const rootWord = Word.fromHex(rootHex);
         const value = storage.getMapItem(3, rootWord) as Word;
         if (value) {
@@ -125,7 +95,7 @@ export class AccountInspector {
           }
         }
       } catch {
-        // Procedure threshold not set - use default
+        // Not set
       }
     }
 
@@ -137,6 +107,7 @@ export class AccountInspector {
       psmCommitment,
       vaultBalances,
       procedureThresholds,
+      signatureScheme,
     };
   }
 }

package/src/multisig/helpers.ts

@@ -1,4 +1,4 @@
-import { Account, TransactionSummary, Word } from '@demox-labs/miden-sdk';
+import { Account, TransactionSummary } from '@demox-labs/miden-sdk';
 import { base64ToUint8Array } from '../utils/encoding.js';
 
 export function computeCommitmentFromTxSummary(txSummaryBase64: string): string {
@@ -7,7 +7,6 @@ export function computeCommitmentFromTxSummary(txSummaryBase64: string): string
   const commitment = summary.toCommitment();
   return commitment.toHex();
 }
-
 export function accountIdToHex(account: Account): string {
   const accountId = account.id();
   const str = accountId.toString();

package/src/multisig.test.ts

@@ -94,6 +94,7 @@ describe('Multisig', () => {
     psm = new PsmHttpClient('http://localhost:3000');
 
     mockSigner = {
+      scheme: 'falcon',
       commitment: '0x' + '1'.repeat(64),
       publicKey: '0x' + '2'.repeat(64),
       signAccountIdWithTimestamp: vi.fn().mockReturnValue('0x' + 'a'.repeat(128)),
@@ -294,7 +295,7 @@ describe('Multisig', () => {
     });
   });
 
-  describe('syncProposals', () => {
+  describe('syncTransactionProposals', () => {
     it('should sync proposals from PSM', async () => {
       const config = {
         threshold: 2,
@@ -339,11 +340,12 @@ describe('Multisig', () => {
         json: async () => ({ proposals: mockProposals }),
       });
 
-      const proposals = await multisig.syncProposals();
+      const proposals = await multisig.syncTransactionProposals();
 
       expect(proposals.length).toBe(1);
       expect(proposals[0].nonce).toBe(1);
       expect(proposals[0].status.type).toBe('pending');
+      expect(proposals[0].commitment).toBe(proposals[0].id);
     });
 
     it('should return ready status when enough signatures', async () => {
@@ -390,13 +392,13 @@ describe('Multisig', () => {
         json: async () => ({ proposals: mockProposals }),
       });
 
-      const proposals = await multisig.syncProposals();
+      const proposals = await multisig.syncTransactionProposals();
 
       expect(proposals[0].status.type).toBe('ready');
     });
   });
 
-  describe('listProposals', () => {
+  describe('listTransactionProposals', () => {
     it('should return empty list initially', () => {
       const config = {
         threshold: 1,
@@ -405,7 +407,7 @@ describe('Multisig', () => {
       };
 
       const multisig = new Multisig(mockAccount, config, psm, mockSigner, mockWebClient);
-      expect(multisig.listProposals()).toEqual([]);
+      expect(multisig.listTransactionProposals()).toEqual([]);
     });
   });
 
@@ -455,7 +457,7 @@ describe('Multisig', () => {
     });
   });
 
-  describe('signProposal', () => {
+  describe('signTransactionProposal', () => {
     it('should sign a proposal', async () => {
       const config = {
         threshold: 1,
@@ -471,7 +473,7 @@ describe('Multisig', () => {
         nonce: 1,
         prev_commitment: '0x' + 'b'.repeat(64),
         delta_payload: {
-          tx_summary: { data: 'base64summary' },
+          tx_summary: { data: 'AQID' },
           signatures: [],
         },
         status: {
@@ -523,21 +525,30 @@ describe('Multisig', () => {
         },
       };
 
+      // Mock for signDeltaProposal
       mockFetch.mockResolvedValueOnce({
         ok: true,
         json: async () => signedDelta,
       });
 
+      // Mock for auto-sync (syncTransactionProposals)
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ proposals: [signedDelta] }),
+      });
+
       const proposalId = '0x' + 'd'.repeat(64);
-      const signedProposal = await multisig.signProposal(proposalId);
+      const proposals = await multisig.signTransactionProposal(proposalId);
 
       expect(mockSigner.signCommitment).toHaveBeenCalledWith(proposalId);
-      expect(signedProposal.signatures.length).toBe(1);
+      expect(proposals.length).toBeGreaterThanOrEqual(1);
+      expect(proposals[0].signatures.length).toBe(1);
+      expect(proposals[0].commitment).toBe(proposals[0].id);
     });
   });
 
-  describe('exportProposal', () => {
-    it('should export proposal for offline signing', async () => {
+  describe('exportTransactionProposalToJson', () => {
+    it('should export proposal to JSON from local cache', async () => {
       const config = {
         threshold: 2,
         signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
@@ -546,6 +557,7 @@ describe('Multisig', () => {
 
       const multisig = new Multisig(mockAccount, config, psm, mockSigner, mockWebClient);
 
+      // First sync proposals to populate local cache
       const mockProposals = [
         {
           account_id: '0x' + 'a'.repeat(30),
@@ -581,16 +593,20 @@ describe('Multisig', () => {
         json: async () => ({ proposals: mockProposals }),
       });
 
+      await multisig.syncTransactionProposals();
+
       // The proposal ID is computed from tx_summary, which is mocked to return 'c'.repeat(64)
-      const exported = await multisig.exportProposal('0x' + 'c'.repeat(64));
+      const json = multisig.exportTransactionProposalToJson('0x' + 'c'.repeat(64));
+      const exported = JSON.parse(json);
 
       expect(exported.accountId).toBe('0x' + 'a'.repeat(30));
       expect(exported.nonce).toBe(1);
       expect(exported.txSummaryBase64).toBe('AQID');
       expect(exported.signatures.length).toBe(1);
+      expect(exported.commitment).toBe('0x' + 'c'.repeat(64));
     });
 
-    it('should throw if proposal not found', async () => {
+    it('should throw if proposal not found in cache', () => {
       const config = {
         threshold: 1,
         signerCommitments: ['0x' + 'a'.repeat(64)],
@@ -599,18 +615,13 @@ describe('Multisig', () => {
 
       const multisig = new Multisig(mockAccount, config, psm, mockSigner, mockWebClient);
 
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        json: async () => ({ proposals: [] }),
-      });
-
-      await expect(
-        multisig.exportProposal('0x' + 'nonexistent'.repeat(5))
-      ).rejects.toThrow('Proposal not found');
+      expect(() =>
+        multisig.exportTransactionProposalToJson('0x' + 'nonexistent'.repeat(5))
+      ).toThrow('Proposal not found');
     });
   });
 
-  describe('executeProposal', () => {
+  describe('executeTransactionProposal', () => {
     it('should throw if proposal not found locally', async () => {
       const config = {
         threshold: 1,
@@ -621,7 +632,7 @@ describe('Multisig', () => {
       const multisig = new Multisig(mockAccount, config, psm, mockSigner, mockWebClient);
 
       await expect(
-        multisig.executeProposal('0x' + 'nonexistent'.repeat(5))
+        multisig.executeTransactionProposal('0x' + 'nonexistent'.repeat(5))
       ).rejects.toThrow('Proposal not found');
     });
 
@@ -670,11 +681,11 @@ describe('Multisig', () => {
         json: async () => ({ proposals: mockProposals }),
       });
 
-      await multisig.syncProposals();
+      await multisig.syncTransactionProposals();
 
       // Proposal ID is mocked to return 'c'.repeat(64)
       await expect(
-        multisig.executeProposal('0x' + 'c'.repeat(64))
+        multisig.executeTransactionProposal('0x' + 'c'.repeat(64))
       ).rejects.toThrow('not ready for execution');
     });
 
@@ -722,7 +733,7 @@ describe('Multisig', () => {
         ok: true,
         json: async () => ({ proposals: [readyDelta] }),
       });
-      await multisig.syncProposals();
+      await multisig.syncTransactionProposals();
 
       // executeProposal: getDeltaProposals
       mockFetch.mockResolvedValueOnce({
@@ -735,7 +746,7 @@ describe('Multisig', () => {
         json: async () => ({ ...readyDelta, ack_sig: null }),
       });
 
-      await expect(multisig.executeProposal(proposalId)).rejects.toThrow(
+      await expect(multisig.executeTransactionProposal(proposalId)).rejects.toThrow(
         'PSM did not return acknowledgment signature'
       );
     });
@@ -794,7 +805,7 @@ describe('Multisig', () => {
         }),
       });
 
-      const syncedProposals = await multisig.syncProposals();
+      const syncedProposals = await multisig.syncTransactionProposals();
       const syncedProposal = syncedProposals.find(p => p.nonce === 1);
 
       expect(syncedProposal?.metadata?.proposalType).toBe('add_signer');
@@ -839,7 +850,7 @@ describe('Multisig', () => {
         json: async () => ({ proposals: mockProposals }),
       });
 
-      const proposals = await multisig.syncProposals();
+      const proposals = await multisig.syncTransactionProposals();
 
       expect(proposals.length).toBe(1);
       expect(proposals[0].metadata?.proposalType).toBe('p2id');
@@ -1041,7 +1052,7 @@ describe('Multisig', () => {
         json: async () => ({ proposals: mockProposalsPending }),
       });
 
-      let proposals = await multisig.syncProposals();
+      let proposals = await multisig.syncTransactionProposals();
       expect(proposals[0].status.type).toBe('pending');
 
       // Second sync with 2 signatures (ready)
@@ -1082,7 +1093,7 @@ describe('Multisig', () => {
         json: async () => ({ proposals: mockProposalsReady }),
       });
 
-      proposals = await multisig.syncProposals();
+      proposals = await multisig.syncTransactionProposals();
       expect(proposals[0].status.type).toBe('ready');
     });
   });
@@ -1175,7 +1186,7 @@ describe('Multisig', () => {
         json: async () => ({ proposals: rustProposals }),
       });
 
-      const proposals = await multisig.syncProposals();
+      const proposals = await multisig.syncTransactionProposals();
 
       expect(proposals.length).toBe(1);
       // The TS client should normalize snake_case to camelCase
@@ -1232,7 +1243,7 @@ describe('Multisig', () => {
         json: async () => ({ proposals: p2idProposals }),
       });
 
-      const proposals = await multisig.syncProposals();
+      const proposals = await multisig.syncTransactionProposals();
 
       expect(proposals.length).toBe(1);
       expect(proposals[0].metadata?.proposalType).toBe('p2id');
@@ -1281,7 +1292,7 @@ describe('Multisig', () => {
         json: async () => ({ proposals: switchPsmProposals }),
       });
 
-      const proposals = await multisig.syncProposals();
+      const proposals = await multisig.syncTransactionProposals();
 
       expect(proposals.length).toBe(1);
       expect(proposals[0].metadata?.proposalType).toBe('switch_psm');