@openzeppelin/miden-multisig-client 0.13.3 → 0.14.3

package/src/account/storage.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const { storageMaps, storageSlotMap } = vi.hoisted(() => {
+  const storageMaps: Array<{ entries: Array<{ key: unknown; value: unknown }> }> = [];
+  const storageSlotMap = vi.fn((name, map) => ({ kind: 'map', name, map }));
+
+  return { storageMaps, storageSlotMap };
+});
+
+vi.mock('@miden-sdk/miden-sdk', () => {
+  class MockWord {
+    data: BigUint64Array | string;
+
+    constructor(data: BigUint64Array | string) {
+      this.data = data;
+    }
+
+    static fromHex(hex: string) {
+      return new MockWord(hex);
+    }
+  }
+
+  class MockStorageMap {
+    entries: Array<{ key: unknown; value: unknown }> = [];
+
+    constructor() {
+      storageMaps.push(this);
+    }
+
+    insert(key: unknown, value: unknown) {
+      this.entries.push({ key, value });
+    }
+  }
+
+  return {
+    Word: MockWord,
+    StorageMap: MockStorageMap,
+    StorageSlot: {
+      fromValue: vi.fn((name, value) => ({ kind: 'value', name, value })),
+      map: storageSlotMap,
+    },
+  };
+});
+
+describe('buildMultisigStorageSlots', () => {
+  beforeEach(() => {
+    storageMaps.length = 0;
+    storageSlotMap.mockClear();
+  });
+
+  it('keeps single-signer public-key and scheme maps to the configured signer count', async () => {
+    const { buildMultisigStorageSlots } = await import('./storage.js');
+
+    buildMultisigStorageSlots({
+      threshold: 1,
+      signerCommitments: ['0x' + '1'.repeat(64)],
+      guardianCommitment: '0x' + '2'.repeat(64),
+      signatureScheme: 'falcon',
+    });
+
+    const signersMap = storageMaps[0];
+    const signerSchemesMap = storageMaps[1];
+
+    expect(signersMap.entries).toHaveLength(1);
+    expect(signerSchemesMap.entries).toHaveLength(1);
+    expect(signersMap.entries[0].key).toMatchObject({
+      data: new BigUint64Array([0n, 0n, 0n, 0n]),
+    });
+    expect(signerSchemesMap.entries[0].key).toMatchObject({
+      data: new BigUint64Array([0n, 0n, 0n, 0n]),
+    });
+  });
+
+  it('does not pad signer maps when there are already multiple signers', async () => {
+    const { buildMultisigStorageSlots } = await import('./storage.js');
+
+    buildMultisigStorageSlots({
+      threshold: 1,
+      signerCommitments: ['0x' + '1'.repeat(64), '0x' + '3'.repeat(64)],
+      guardianCommitment: '0x' + '2'.repeat(64),
+      signatureScheme: 'falcon',
+    });
+
+    const signersMap = storageMaps[0];
+    const signerSchemesMap = storageMaps[1];
+
+    expect(signersMap.entries).toHaveLength(2);
+    expect(signerSchemesMap.entries).toHaveLength(2);
+  });
+});

package/src/account/storage.ts

@@ -7,6 +7,7 @@ import { getProcedureRoot } from '../procedures.js';
 const MULTISIG_SLOT_NAMES = {
   THRESHOLD_CONFIG: 'openzeppelin::multisig::threshold_config',
   SIGNER_PUBLIC_KEYS: 'openzeppelin::multisig::signer_public_keys',
+  SIGNER_SCHEME_IDS: 'openzeppelin::multisig::signer_scheme_ids',
   EXECUTED_TRANSACTIONS: 'openzeppelin::multisig::executed_transactions',
   PROCEDURE_THRESHOLDS: 'openzeppelin::multisig::procedure_thresholds',
 } as const;
@@ -14,11 +15,17 @@ const MULTISIG_SLOT_NAMES = {
 const GUARDIAN_SLOT_NAMES = {
   SELECTOR: 'openzeppelin::guardian::selector',
   PUBLIC_KEY: 'openzeppelin::guardian::public_key',
+  SCHEME_ID: 'openzeppelin::guardian::scheme_id',
 } as const;
 
+function signerMapKey(index: bigint): Word {
+  return new Word(new BigUint64Array([index, 0n, 0n, 0n]));
+}
+
 export class StorageLayoutBuilder {
   buildMultisigSlots(config: MultisigConfig): StorageSlot[] {
     const numSigners = config.signerCommitments.length;
+    const schemeId = config.signatureScheme === 'ecdsa' ? 1n : 2n;
     const slot0Word = new Word(
       new BigUint64Array([
         BigInt(config.threshold),
@@ -31,13 +38,21 @@ export class StorageLayoutBuilder {
 
     const signersMap = new StorageMap();
     config.signerCommitments.forEach((commitment, index) => {
-      const key = new Word(new BigUint64Array([BigInt(index), 0n, 0n, 0n]));
+      const key = signerMapKey(BigInt(index));
       const value = Word.fromHex(ensureHexPrefix(commitment));
       signersMap.insert(key, value);
     });
     const slot1 = StorageSlot.map(MULTISIG_SLOT_NAMES.SIGNER_PUBLIC_KEYS, signersMap);
 
-    const slot2 = StorageSlot.map(MULTISIG_SLOT_NAMES.EXECUTED_TRANSACTIONS, new StorageMap());
+    const signerSchemesMap = new StorageMap();
+    config.signerCommitments.forEach((_, index) => {
+      const key = signerMapKey(BigInt(index));
+      const value = new Word(new BigUint64Array([schemeId, 0n, 0n, 0n]));
+      signerSchemesMap.insert(key, value);
+    });
+    const slot2 = StorageSlot.map(MULTISIG_SLOT_NAMES.SIGNER_SCHEME_IDS, signerSchemesMap);
+
+    const slot3 = StorageSlot.map(MULTISIG_SLOT_NAMES.EXECUTED_TRANSACTIONS, new StorageMap());
 
     // Map entries: PROC_ROOT => [proc_threshold, 0, 0, 0]
     // Use SDK's Word.fromHex to match how account code procedure roots are represented
@@ -50,23 +65,29 @@ export class StorageLayoutBuilder {
         procThresholdMap.insert(key, value);
       }
     }
-    const slot3 = StorageSlot.map(MULTISIG_SLOT_NAMES.PROCEDURE_THRESHOLDS, procThresholdMap);
+    const slot4 = StorageSlot.map(MULTISIG_SLOT_NAMES.PROCEDURE_THRESHOLDS, procThresholdMap);
 
-    return [slot0, slot1, slot2, slot3];
+    return [slot0, slot1, slot2, slot3, slot4];
   }
 
   buildGuardianSlots(config: MultisigConfig): StorageSlot[] {
     const selector = config.guardianEnabled !== false ? 1n : 0n;
+    const schemeId = config.signatureScheme === 'ecdsa' ? 1n : 2n;
     const selectorWord = new Word(new BigUint64Array([selector, 0n, 0n, 0n]));
     const slot0 = StorageSlot.fromValue(GUARDIAN_SLOT_NAMES.SELECTOR, selectorWord);
 
     const guardianKeyMap = new StorageMap();
-    const zeroKey = new Word(new BigUint64Array([0n, 0n, 0n, 0n]));
+    const zeroKey = signerMapKey(0n);
     const guardianKey = Word.fromHex(ensureHexPrefix(config.guardianCommitment));
     guardianKeyMap.insert(zeroKey, guardianKey);
     const slot1 = StorageSlot.map(GUARDIAN_SLOT_NAMES.PUBLIC_KEY, guardianKeyMap);
 
-    return [slot0, slot1];
+    const guardianSchemeMap = new StorageMap();
+    const guardianScheme = new Word(new BigUint64Array([schemeId, 0n, 0n, 0n]));
+    guardianSchemeMap.insert(zeroKey, guardianScheme);
+    const slot2 = StorageSlot.map(GUARDIAN_SLOT_NAMES.SCHEME_ID, guardianSchemeMap);
+
+    return [slot0, slot1, slot2];
   }
 }
 

package/src/client.test.ts

@@ -63,14 +63,13 @@ describe('MultisigClient', () => {
     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),
+      accounts: {
+        get: vi.fn().mockResolvedValue(null),
+        insert: vi.fn().mockResolvedValue(undefined),
+      },
+      keystore: {
+        insert: vi.fn().mockResolvedValue(undefined),
+      },
     };
 
     mockSigner = {
@@ -132,6 +131,23 @@ describe('MultisigClient', () => {
       const multisig = await client.create(config, mockSigner);
       expect(multisig.signerCommitment).toBe(mockSigner.commitment);
     });
+
+    it('binds the signer auth key to the created account when supported', async () => {
+      const client = new MultisigClient(webClient);
+      const bindAccountKey = vi.fn().mockResolvedValue(undefined);
+      const bindingSigner = {
+        ...mockSigner,
+        bindAccountKey,
+      };
+
+      await client.create({
+        threshold: 1,
+        signerCommitments: ['0x' + 'a'.repeat(64)],
+        guardianCommitment: '0x' + 'c'.repeat(64),
+      }, bindingSigner);
+
+      expect(bindAccountKey).toHaveBeenCalledWith(webClient, '0x' + 'a'.repeat(30));
+    });
   });
 
   describe('load', () => {
@@ -160,6 +176,8 @@ describe('MultisigClient', () => {
       expect(multisig.signerCommitments).toEqual(['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)]);
       expect(multisig.guardianCommitment).toBe('0x' + 'c'.repeat(64));
       expect(multisig.account).not.toBeNull();
+      expect(webClient.accounts.get).toHaveBeenCalledTimes(1);
+      expect(webClient.accounts.insert).toHaveBeenCalledTimes(1);
     });
 
     it('should throw if account not found on GUARDIAN', async () => {
@@ -204,6 +222,32 @@ describe('MultisigClient', () => {
       const multisig = await client.load(accountId, mockSigner);
 
       await expect(multisig.registerOnGuardian()).resolves.toBeUndefined();
+      expect(webClient.accounts.get).toHaveBeenCalledTimes(1);
+      expect(webClient.accounts.insert).toHaveBeenCalledTimes(1);
+    });
+
+    it('binds the signer auth key after loading an account when supported', async () => {
+      const client = new MultisigClient(webClient);
+      const bindAccountKey = vi.fn().mockResolvedValue(undefined);
+      const bindingSigner = {
+        ...mockSigner,
+        bindAccountKey,
+      };
+
+      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',
+        }),
+      });
+
+      await client.load('0x' + 'd'.repeat(30), bindingSigner);
+
+      expect(bindAccountKey).toHaveBeenCalledWith(webClient, '0x' + 'd'.repeat(30));
     });
   });
 });

package/src/client.ts

@@ -5,13 +5,29 @@
  * to create new multisig accounts and load existing ones.
  */
 
-import { type WebClient, Account, AccountId } from '@miden-sdk/miden-sdk';
+import { type MidenClient, Account, AccountId } from '@miden-sdk/miden-sdk';
 import { GuardianHttpClient } from '@openzeppelin/guardian-client';
 import { Multisig } from './multisig.js';
 import { createMultisigAccount } from './account/index.js';
 import { AccountInspector } from './inspector.js';
+import { getRawMidenClient, resolveMidenRpcEndpoint } from './raw-client.js';
 import type { MultisigConfig, Signer } from './types.js';
 
+interface AccountKeyBindingSigner {
+  bindAccountKey?(midenClient: MidenClient, accountId: string): Promise<void>;
+}
+
+async function bindSignerAccountKey(
+  signer: Signer,
+  midenClient: MidenClient,
+  accountId: string,
+): Promise<void> {
+  const bindingSigner = signer as Signer & AccountKeyBindingSigner;
+  if (typeof bindingSigner.bindAccountKey === 'function') {
+    await bindingSigner.bindAccountKey(midenClient, accountId);
+  }
+}
+
 /**
  * Configuration for MultisigClient.
  */
@@ -28,17 +44,17 @@ export interface MultisigClientConfig {
  * @example
  * ```typescript
  * import { MultisigClient, FalconSigner } from '@openzeppelin/miden-multisig-client';
- * import { WebClient, SecretKey } from '@miden-sdk/miden-sdk';
+ * import { MidenClient, AuthSecretKey } from '@miden-sdk/miden-sdk';
  *
  * // Initialize
- * const webClient = await WebClient.createClient('https://rpc.testnet.miden.io:443');
- * const secretKey = SecretKey.rpoFalconWithRNG(seed);
+ * const midenClient = await MidenClient.createDevnet();
+ * const secretKey = AuthSecretKey.rpoFalconWithRNG(seed);
  * const signer = new FalconSigner(secretKey);
  *
  * // Create client
- * const client = new MultisigClient(webClient, {
+ * const client = new MultisigClient(midenClient, {
  *   guardianEndpoint: 'http://localhost:3000',
- *   midenRpcEndpoint: 'https://rpc.testnet.miden.io:443',
+ *   midenRpcEndpoint: 'https://rpc.devnet.miden.io',
  * });
  *
  * // Get GUARDIAN pubkey for config
@@ -50,13 +66,13 @@ export interface MultisigClientConfig {
  * ```
  */
 export class MultisigClient {
-  private readonly webClient: WebClient;
-  private readonly midenRpcEndpoint?: string;
+  private readonly midenClient: MidenClient;
+  private readonly midenRpcEndpoint: string;
   private _guardianClient: GuardianHttpClient;
 
-  constructor(webClient: WebClient, config: MultisigClientConfig = {}) {
-    this.webClient = webClient;
-    this.midenRpcEndpoint = config.midenRpcEndpoint;
+  constructor(midenClient: MidenClient, config: MultisigClientConfig = {}) {
+    this.midenClient = midenClient;
+    this.midenRpcEndpoint = resolveMidenRpcEndpoint(config.midenRpcEndpoint);
     this._guardianClient = new GuardianHttpClient(config.guardianEndpoint ?? 'http://localhost:3000');
   }
 
@@ -86,14 +102,20 @@ export class MultisigClient {
   async create(config: MultisigConfig, signer: Signer): Promise<Multisig> {
     this._guardianClient.setSigner(signer);
 
-    const { account } = await createMultisigAccount(this.webClient, config);
+    const { account } = await createMultisigAccount(
+      this.midenClient,
+      config,
+      this.midenRpcEndpoint,
+    );
+    const accountId = account.id().toString();
+    await bindSignerAccountKey(signer, this.midenClient, accountId);
 
     return new Multisig(
       account,
       config,
       this._guardianClient,
       signer,
-      this.webClient,
+      this.midenClient,
       undefined,
       this.midenRpcEndpoint
     );
@@ -134,17 +156,18 @@ export class MultisigClient {
       ),
     };
 
-    const existingAccount = await this.webClient.getAccount(AccountId.fromHex(accountId));
+    const existingAccount = await this.midenClient.accounts.get(AccountId.fromHex(accountId));
     if (!existingAccount) {
-        await this.webClient.newAccount(account, true);
+      await this.midenClient.accounts.insert({ account, overwrite: true });
     }
+    await bindSignerAccountKey(signer, this.midenClient, accountId);
 
     return new Multisig(
       account,
       config,
       this._guardianClient,
       signer,
-      this.webClient,
+      this.midenClient,
       accountId,
       this.midenRpcEndpoint
     );

package/src/index.ts

@@ -9,27 +9,21 @@
  *   MultisigClient,
  *   FalconSigner,
  * } from '@openzeppelin/miden-multisig-client';
- * import { WebClient, SecretKey } from '@miden-sdk/miden-sdk';
+ * import { MidenClient, AuthSecretKey } from '@miden-sdk/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);
+ * const midenClient = await MidenClient.createDevnet();
+ * const secretKey = AuthSecretKey.rpoFalconWithRNG(undefined);
  *
  * // Store in miden-sdk's keystore
- * await webClient.addAccountSecretKeyToWebStore(secretKey);
+ * await midenClient.keystore.insert(secretKey.publicKey(), secretKey);
  *
  * // Create a signer
  * const signer = new FalconSigner(secretKey);
  *
  * // Create multisig client
- * const client = new MultisigClient(webClient, {
+ * const client = new MultisigClient(midenClient, {
  *   guardianEndpoint: 'http://localhost:3000',
- *   midenRpcEndpoint: 'https://rpc.testnet.miden.io:443',
+ *   midenRpcEndpoint: 'https://rpc.devnet.miden.io',
  * });
  *
  * // Get GUARDIAN pubkey for config

package/src/multisig/proposal/execution.ts

@@ -1,7 +1,10 @@
 import { type DeltaObject, type GuardianHttpClient } from '@openzeppelin/guardian-client';
-import type { WebClient, TransactionRequest } from '@miden-sdk/miden-sdk';
+import type {
+  MidenClient,
+  TransactionProver,
+  TransactionRequest,
+} from '@miden-sdk/miden-sdk';
 import {
-  AccountId,
   AdviceMap,
   FeltArray,
   Signature,
@@ -45,7 +48,8 @@ interface ExecuteProposalWorkflowParams {
   signatureScheme: 'falcon' | 'ecdsa';
   getEffectiveThreshold: (proposalType: ProposalType) => number;
   guardian: GuardianHttpClient;
-  webClient: WebClient;
+  midenClient: MidenClient;
+  transactionProver?: TransactionProver | null;
 }
 
 export async function executeProposalWorkflow(
@@ -89,7 +93,11 @@ export async function executeProposalWorkflow(
     executionData.saltHex,
     adviceMap,
   );
-  await submitTransaction(params.webClient, params.accountId, finalRequest);
+  await submitTransaction(
+    params.midenClient,
+    params.accountId,
+    finalRequest,
+  );
 }
 
 
@@ -297,7 +305,7 @@ async function buildFinalRequest(
         );
       }
       const { request } = await buildConsumeNotesTransactionRequest(
-        params.webClient,
+        params.midenClient,
         metadata.noteIds,
         { salt: normalizedSalt, signatureAdviceMap: adviceMap },
       );
@@ -310,7 +318,7 @@ async function buildFinalRequest(
         );
       }
       const { request } = await buildUpdateGuardianTransactionRequest(
-        params.webClient,
+        params.midenClient,
         metadata.newGuardianPubkey,
         {
           salt: normalizedSalt,
@@ -322,7 +330,7 @@ async function buildFinalRequest(
     }
     case 'update_procedure_threshold': {
       const { request } = await buildUpdateProcedureThresholdTransactionRequest(
-        params.webClient,
+        params.midenClient,
         metadata.targetProcedure,
         metadata.targetThreshold,
         {
@@ -354,7 +362,7 @@ async function buildFinalRequest(
       );
     default: {
       const { request } = await buildUpdateSignersTransactionRequest(
-        params.webClient,
+        params.midenClient,
         metadata.targetThreshold,
         metadata.targetSignerCommitments,
         {
@@ -369,13 +377,9 @@ async function buildFinalRequest(
 }
 
 async function submitTransaction(
-  webClient: WebClient,
+  midenClient: MidenClient,
   accountIdHex: string,
   request: TransactionRequest,
 ): Promise<void> {
-  const accountId = AccountId.fromHex(accountIdHex);
-  const result = await webClient.executeTransaction(accountId, request);
-  const proven = await webClient.proveTransaction(result, null);
-  const submissionHeight = await webClient.submitProvenTransaction(proven, result);
-  await webClient.applyTransaction(result, submissionHeight);
+  await midenClient.transactions.submit(accountIdHex, request);
 }