@openzeppelin/miden-multisig-client 0.13.0 → 0.13.2

package/src/account/builder.ts

@@ -1,3 +1,9 @@
+/**
+ * Account builder for creating multisig accounts with GUARDIAN authentication.
+ *
+ * This module provides functionality to create multisig accounts.
+ */
+
 import {
   AccountBuilder,
   AccountComponent,
@@ -6,38 +12,63 @@ import {
   type WebClient,
 } from '@miden-sdk/miden-sdk';
 import type { MultisigConfig, CreateAccountResult } from '../types.js';
-import { buildMultisigStorageSlots, buildPsmStorageSlots } from './storage.js';
-import { MULTISIG_MASM, MULTISIG_ECDSA_MASM, PSM_MASM, PSM_ECDSA_MASM } from './masm.js';
+import { buildMultisigStorageSlots, buildGuardianStorageSlots } from './storage.js';
+import {
+  MULTISIG_ECDSA_MASM,
+  MULTISIG_MASM,
+  GUARDIAN_ECDSA_MASM,
+  GUARDIAN_MASM,
+} from './masm/auth.js';
+import {
+  MULTISIG_GUARDIAN_ACCOUNT_COMPONENT_MASM,
+  MULTISIG_GUARDIAN_ECDSA_ACCOUNT_COMPONENT_MASM,
+} from './masm/account-components/auth.js';
+import { normalizeSignerCommitment } from '../utils/signature.js';
 
+/**
+ * Creates a multisig account with GUARDIAN authentication.
+ *
+ * @param webClient - Initialized Miden WebClient
+ * @param config - Multisig configuration
+ * @returns The created account and seed
+ */
 export async function createMultisigAccount(
   webClient: WebClient,
   config: MultisigConfig
 ): Promise<CreateAccountResult> {
   validateMultisigConfig(config);
-
   const signatureScheme = config.signatureScheme ?? 'falcon';
-  const multisigSlots = buildMultisigStorageSlots(config);
-  const psmSlots = buildPsmStorageSlots(config);
-
-  const psmBuilder = webClient.createCodeBuilder();
-  const psmMasm = signatureScheme === 'ecdsa' ? PSM_ECDSA_MASM : PSM_MASM;
-  const psmCode = psmBuilder.compileAccountComponentCode(psmMasm);
-  const psmComponent = AccountComponent
-    .compile(psmCode, psmSlots)
-    .withSupportsAllTypes();
-
+  const authSlots = [
+    ...buildMultisigStorageSlots(config),
+    ...buildGuardianStorageSlots(config),
+  ];
+  const guardianMasm = signatureScheme === 'ecdsa' ? GUARDIAN_ECDSA_MASM : GUARDIAN_MASM;
   const multisigMasm = signatureScheme === 'ecdsa' ? MULTISIG_ECDSA_MASM : MULTISIG_MASM;
-  const psmLibraryPath = signatureScheme === 'ecdsa' ? 'openzeppelin::psm_ecdsa' : 'openzeppelin::psm';
-  const multisigBuilder = webClient.createCodeBuilder();
-  const psmLib = multisigBuilder.buildLibrary(psmLibraryPath, psmMasm);
-  multisigBuilder.linkStaticLibrary(psmLib);
-  const multisigCode = multisigBuilder.compileAccountComponentCode(multisigMasm);
-  const multisigComponent = AccountComponent
-    .compile(multisigCode, multisigSlots)
+  const authComponentMasm = signatureScheme === 'ecdsa'
+    ? MULTISIG_GUARDIAN_ECDSA_ACCOUNT_COMPONENT_MASM
+    : MULTISIG_GUARDIAN_ACCOUNT_COMPONENT_MASM;
+  const guardianLibraryPath = signatureScheme === 'ecdsa'
+    ? 'openzeppelin::auth::guardian_ecdsa'
+    : 'openzeppelin::auth::guardian';
+  const multisigLibraryPath = signatureScheme === 'ecdsa'
+    ? 'openzeppelin::auth::multisig_ecdsa'
+    : 'openzeppelin::auth::multisig';
+
+  const authBuilder = webClient.createCodeBuilder();
+  const guardianLib = authBuilder.buildLibrary(guardianLibraryPath, guardianMasm);
+  authBuilder.linkStaticLibrary(guardianLib);
+  const multisigLib = authBuilder.buildLibrary(multisigLibraryPath, multisigMasm);
+  authBuilder.linkStaticLibrary(multisigLib);
+  const authCode = authBuilder.compileAccountComponentCode(authComponentMasm);
+  const authComponent = AccountComponent
+    .compile(authCode, authSlots)
     .withSupportsAllTypes();
 
-  const seed = new Uint8Array(32);
-  crypto.getRandomValues(seed);
+  let seed = config.seed;
+  // Generate random seed if not provided
+  if (!seed) {
+    seed = crypto.getRandomValues(new Uint8Array(32));
+  }
 
   const storageMode = config.storageMode === 'public'
     ? AccountStorageMode.public()
@@ -46,8 +77,7 @@ export async function createMultisigAccount(
   const accountBuilder = new AccountBuilder(seed)
     .accountType(AccountType.RegularAccountUpdatableCode)
     .storageMode(storageMode)
-    .withAuthComponent(multisigComponent)
-    .withComponent(psmComponent)
+    .withAuthComponent(authComponent)
     .withBasicWalletComponent();
 
   const result = accountBuilder.build();
@@ -60,6 +90,12 @@ export async function createMultisigAccount(
   };
 }
 
+/**
+ * Validates a multisig configuration.
+ *
+ * @param config - The configuration to validate
+ * @throws Error if configuration is invalid
+ */
 export function validateMultisigConfig(config: MultisigConfig): void {
   if (config.threshold === 0) {
     throw new Error('threshold must be greater than 0');
@@ -67,25 +103,26 @@ export function validateMultisigConfig(config: MultisigConfig): void {
   if (config.signerCommitments.length === 0) {
     throw new Error('at least one signer commitment is required');
   }
-  for (const commitment of config.signerCommitments) {
-    const stripped = commitment.startsWith('0x') || commitment.startsWith('0X')
-      ? commitment.slice(2)
-      : commitment;
-    if (stripped.length > 64) {
-      throw new Error(
-        `signerCommitments must be 32-byte commitment hex (64 chars), got ${stripped.length} chars`
-      );
+
+  const signerCommitments = new Set<string>();
+  for (const signerCommitment of config.signerCommitments) {
+    const normalizedCommitment = normalizeSignerCommitment(signerCommitment);
+    if (signerCommitments.has(normalizedCommitment)) {
+      throw new Error(`duplicate signer commitment: ${normalizedCommitment}`);
     }
+    signerCommitments.add(normalizedCommitment);
   }
+
   if (config.threshold > config.signerCommitments.length) {
     throw new Error(
       `threshold (${config.threshold}) cannot exceed number of signers (${config.signerCommitments.length})`
     );
   }
-  if (!config.psmCommitment) {
-    throw new Error('PSM commitment is required');
+  if (!config.guardianCommitment) {
+    throw new Error('GUARDIAN commitment is required');
   }
 
+  // Validate procedure thresholds if provided
   if (config.procedureThresholds) {
     const seen = new Set<string>();
     for (const pt of config.procedureThresholds) {

package/src/account/index.ts

@@ -9,7 +9,7 @@ export {
 
 export {
   buildMultisigStorageSlots,
-  buildPsmStorageSlots,
+  buildGuardianStorageSlots,
   storageLayoutBuilder,
   StorageLayoutBuilder,
 } from './storage.js';

package/src/account/masm/account-components/auth.ts

@@ -0,0 +1,70 @@
+// This file is generated by scripts/generate-masm.mjs from the MASM contract sources.
+// Do not edit it by hand.
+
+export const MULTISIG_ACCOUNT_COMPONENT_MASM = `# Multi-Signature RPO Falcon 512 Authentication Component
+
+use openzeppelin::auth::multisig
+
+type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
+
+pub use multisig::update_signers_and_threshold
+pub use multisig::update_procedure_threshold
+
+pub proc auth_tx_multisig(salt: BeWord)
+    exec.multisig::auth_tx
+    exec.multisig::assert_new_tx
+end
+`;
+
+export const MULTISIG_GUARDIAN_ACCOUNT_COMPONENT_MASM = `# Multi-Signature RPO Falcon 512 Authentication Component With GUARDIAN
+
+use openzeppelin::auth::multisig
+use openzeppelin::auth::guardian
+
+type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
+
+pub use multisig::update_signers_and_threshold
+pub use multisig::update_procedure_threshold
+pub use guardian::update_guardian_public_key
+pub use guardian::verify_guardian_signature
+
+pub proc auth_tx_multisig_guardian(salt: BeWord)
+    exec.multisig::auth_tx
+    exec.guardian::verify_guardian_signature
+    exec.multisig::assert_new_tx
+end
+`;
+
+export const MULTISIG_ECDSA_ACCOUNT_COMPONENT_MASM = `# Multi-Signature ECDSA secp256k1 Authentication Component
+
+use openzeppelin::auth::multisig_ecdsa
+
+type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
+
+pub use multisig_ecdsa::update_signers_and_threshold
+pub use multisig_ecdsa::update_procedure_threshold
+
+pub proc auth_tx_multisig_ecdsa(salt: BeWord)
+    exec.multisig_ecdsa::auth_tx
+    exec.multisig_ecdsa::assert_new_tx
+end
+`;
+
+export const MULTISIG_GUARDIAN_ECDSA_ACCOUNT_COMPONENT_MASM = `# Multi-Signature ECDSA secp256k1 Authentication Component With GUARDIAN
+
+use openzeppelin::auth::multisig_ecdsa
+use openzeppelin::auth::guardian_ecdsa
+
+type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
+
+pub use multisig_ecdsa::update_signers_and_threshold
+pub use multisig_ecdsa::update_procedure_threshold
+pub use guardian_ecdsa::update_guardian_public_key
+pub use guardian_ecdsa::verify_guardian_signature
+
+pub proc auth_tx_multisig_guardian_ecdsa(salt: BeWord)
+    exec.multisig_ecdsa::auth_tx
+    exec.guardian_ecdsa::verify_guardian_signature
+    exec.multisig_ecdsa::assert_new_tx
+end
+`;