@openzeppelin/miden-multisig-client 0.13.0 → 0.13.2

package/masm/{multisig_ecdsa.masm → auth/multisig_ecdsa.masm}

@@ -1,15 +1,10 @@
-# Multi-Signature ECDSA secp256k1 Authentication Component
+# Multi-Signature ECDSA secp256k1 Authentication Core Library
 #
-# This component provides multi-signature authentication for accounts using
-# ECDSA secp256k1 (k256/keccak) signatures instead of RPO Falcon 512.
-# It integrates with the PSM component for optional PSM signature verification.
+# This library provides the reusable multisig procedures used by account wrappers.
 
-use miden::active_account
-use miden::native_account
-use miden::auth
-use openzeppelin::psm_ecdsa
-
-# Type definitions for v0.12 syntax
+use miden::protocol::active_account
+use miden::protocol::native_account
+use miden::standards::auth
 type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
 
 # CONSTANTS
@@ -18,7 +13,7 @@ type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
 # Auth Request Constants
 
 # The event emitted when a signature is not found for a required signer.
-const AUTH_UNAUTHORIZED_EVENT = event("miden::auth::unauthorized")
+const AUTH_UNAUTHORIZED_EVENT=event("miden::auth::unauthorized")
 
 # Storage Layout Constants
 #
@@ -33,29 +28,35 @@ const AUTH_UNAUTHORIZED_EVENT = event("miden::auth::unauthorized")
 # number of approvers are stored as:
 # [default_threshold, num_approvers, 0, 0].
 # The threshold is guaranteed to be less than or equal to num_approvers.
-const THRESHOLD_CONFIG_SLOT = 0
+const THRESHOLD_CONFIG_SLOT=word("openzeppelin::multisig::threshold_config")
 
 # The slot in this component's storage layout where the public keys map is stored.
 # Map entries: [key_index, 0, 0, 0] => APPROVER_PUBLIC_KEY
-const PUBLIC_KEYS_MAP_SLOT = 1
+const PUBLIC_KEYS_MAP_SLOT=word("openzeppelin::multisig::signer_public_keys")
 
 # The slot in this component's storage layout where executed transactions are stored.
 # Map entries: transaction_message => [is_executed, 0, 0, 0]
-const EXECUTED_TXS_SLOT = 2
+const EXECUTED_TXS_SLOT=word("openzeppelin::multisig::executed_transactions")
 
 # The slot in this component's storage layout where procedure thresholds are stored.
 # Map entries: PROC_ROOT => [proc_threshold, 0, 0, 0]
-const PROC_THRESHOLD_ROOTS_SLOT = 3
+const PROC_THRESHOLD_ROOTS_SLOT=word("openzeppelin::multisig::procedure_thresholds")
 
 # Executed Transaction Flag Constant
-const IS_EXECUTED_FLAG = [1, 0, 0, 0]
+const IS_EXECUTED_FLAG=[1, 0, 0, 0]
 
 # ERRORS
-const ERR_TX_ALREADY_EXECUTED = "failed to approve multisig transaction as it was already executed"
+const ERR_TX_ALREADY_EXECUTED="failed to approve multisig transaction as it was already executed"
+
+const ERR_MALFORMED_MULTISIG_CONFIG="number of approvers must be equal to or greater than threshold"
+
+const ERR_ZERO_IN_MULTISIG_CONFIG="number of approvers or threshold must not be zero"
+
+const ERR_PROC_THRESHOLD_NOT_U32="procedure threshold must be a u32 value"
 
-const ERR_MALFORMED_MULTISIG_CONFIG = "number of approvers must be equal to or greater than threshold"
+const ERR_NUM_APPROVERS_OR_PROC_THRESHOLD_NOT_U32="number of approvers and procedure threshold must be u32"
 
-const ERR_ZERO_IN_MULTISIG_CONFIG = "number of approvers or threshold must not be zero"
+const ERR_PROC_THRESHOLD_EXCEEDS_NUM_APPROVERS="procedure threshold exceeds number of approvers"
 
 # MULTISIG PROCEDURES
 # =================================================================================================
@@ -67,21 +68,21 @@ const ERR_ZERO_IN_MULTISIG_CONFIG = "number of approvers or threshold must not b
 #!
 #! Panics if:
 #! - the same transaction has already been executed
-proc assert_new_tx(msg: BeWord)
+pub proc assert_new_tx(msg: BeWord)
     push.IS_EXECUTED_FLAG
     # => [[0, 0, 0, is_executed], MSG]
 
     swapw
     # => [MSG, IS_EXECUTED_FLAG]
 
-    push.EXECUTED_TXS_SLOT
-    # => [index, MSG, IS_EXECUTED_FLAG]
+    push.EXECUTED_TXS_SLOT[0..2]
+    # => [txs_slot_prefix, txs_slot_suffix, MSG, IS_EXECUTED_FLAG]
 
     # Set the key value pair in the map to mark transaction as executed
     exec.native_account::set_map_item
-    # => [OLD_MAP_ROOT, [0, 0, 0, is_executed]]
+    # => [[0, 0, 0, is_executed]]
 
-    dropw drop drop drop
+    drop drop drop
     # => [is_executed]
 
     assertz.err=ERR_TX_ALREADY_EXECUTED
@@ -120,13 +121,13 @@ proc cleanup_pubkey_mapping(init_num_of_approvers: u32, new_num_of_approvers: u3
         padw swapw
         # => [[0, 0, 0, i-1], EMPTY_WORD, i-1, new_num_of_approvers]
 
-        push.PUBLIC_KEYS_MAP_SLOT
-        # => [pub_key_slot_idx, [0, 0, 0, i-1], EMPTY_WORD, i-1, new_num_of_approvers]
+        push.PUBLIC_KEYS_MAP_SLOT[0..2]
+        # => [pub_key_slot_prefix, pub_key_slot_suffix, [0, 0, 0, i-1], EMPTY_WORD, i-1, new_num_of_approvers]
 
         exec.native_account::set_map_item
-        # => [OLD_MAP_ROOT, OLD_MAP_VALUE, i-1, new_num_of_approvers]
+        # => [OLD_MAP_VALUE, i-1, new_num_of_approvers]
 
-        dropw dropw
+        dropw
         # => [i-1, new_num_of_approvers]
 
         dup.1 dup.1
@@ -138,6 +139,85 @@ proc cleanup_pubkey_mapping(init_num_of_approvers: u32, new_num_of_approvers: u3
     # => []
 end
 
+proc get_threshold_and_num_approvers
+    push.THRESHOLD_CONFIG_SLOT[0..2]
+    exec.active_account::get_initial_item
+    # => [0, 0, num_approvers, threshold]
+
+    drop drop
+    # => [num_approvers, threshold]
+
+    swap
+    # => [threshold, num_approvers]
+end
+
+proc assert_proc_thresholds_lte_num_approvers(num_approvers: u32)
+    exec.active_account::get_num_procedures
+    # => [num_procedures, num_approvers]
+
+    dup neq.0
+    # => [should_continue, num_procedures, num_approvers]
+    while.true
+        sub.1 dup
+        # => [proc_index, proc_index, num_approvers]
+
+        exec.active_account::get_procedure_root
+        # => [PROC_ROOT, proc_index, num_approvers]
+
+        push.PROC_THRESHOLD_ROOTS_SLOT[0..2]
+        # => [proc_roots_slot_prefix, proc_roots_slot_suffix, PROC_ROOT, proc_index, num_approvers]
+
+        exec.active_account::get_initial_map_item
+        # => [[0, 0, 0, proc_threshold], proc_index, num_approvers]
+
+        drop drop drop
+        # => [proc_threshold, proc_index, num_approvers]
+
+        dup.2
+        # => [num_approvers, proc_threshold, proc_index, num_approvers]
+
+        u32assert2.err=ERR_PROC_THRESHOLD_NOT_U32
+        u32gt assertz.err=ERR_PROC_THRESHOLD_EXCEEDS_NUM_APPROVERS
+        # => [proc_index, num_approvers]
+
+        dup neq.0
+        # => [should_continue, proc_index, num_approvers]
+    end
+
+    drop drop
+    # => []
+end
+
+# Internal storage helper used by the public `update_procedure_threshold`
+# entrypoint after it receives direct stack arguments.
+proc set_procedure_threshold(proc_threshold: u32, proc_root: BeWord)
+    exec.get_threshold_and_num_approvers
+    # => [threshold, num_approvers, proc_threshold, PROC_ROOT]
+
+    drop
+    # => [num_approvers, proc_threshold, PROC_ROOT]
+
+    dup.1 swap
+    # => [num_approvers, proc_threshold, proc_threshold, PROC_ROOT]
+
+    u32assert2.err=ERR_NUM_APPROVERS_OR_PROC_THRESHOLD_NOT_U32
+    u32gt assertz.err=ERR_PROC_THRESHOLD_EXCEEDS_NUM_APPROVERS
+    # => [proc_threshold, PROC_ROOT]
+
+    push.0.0.0
+    swapw
+    # => [PROC_ROOT, PROC_THRESHOLD_WORD]
+
+    push.PROC_THRESHOLD_ROOTS_SLOT[0..2]
+    # => [proc_roots_slot_prefix, proc_roots_slot_suffix, PROC_ROOT, PROC_THRESHOLD_WORD]
+
+    exec.native_account::set_map_item
+    # => [OLD_VALUE]
+
+    dropw
+    # => []
+end
+
 #! Update threshold config and add / remove approvers
 #!
 #! Inputs:
@@ -156,7 +236,8 @@ end
 #! Locals:
 #! 0: new_num_of_approvers
 #! 1: init_num_of_approvers
-pub proc update_signers_and_threshold.2(multisig_config_hash: BeWord)
+@locals(2)
+pub proc update_signers_and_threshold(multisig_config_hash: BeWord)
     adv.push_mapval
     # => [MULTISIG_CONFIG_HASH, pad(12)]
 
@@ -183,8 +264,14 @@ pub proc update_signers_and_threshold.2(multisig_config_hash: BeWord)
     eq.0 assertz.err=ERR_ZERO_IN_MULTISIG_CONFIG
     # => [MULTISIG_CONFIG, pad(12)]
 
-    push.THRESHOLD_CONFIG_SLOT
-    # => [slot, MULTISIG_CONFIG, pad(12)]
+    loc_load.0
+    # => [num_approvers, MULTISIG_CONFIG, pad(12)]
+
+    exec.assert_proc_thresholds_lte_num_approvers
+    # => [MULTISIG_CONFIG, pad(12)]
+
+    push.THRESHOLD_CONFIG_SLOT[0..2]
+    # => [config_slot_prefix, config_slot_suffix, MULTISIG_CONFIG, pad(12)]
 
     exec.native_account::set_item
     # => [OLD_THRESHOLD_CONFIG, pad(12)]
@@ -210,13 +297,13 @@ pub proc update_signers_and_threshold.2(multisig_config_hash: BeWord)
         swapw
         # => [[0, 0, 0, i-1], PUB_KEY, i-1, pad(12)]
 
-        push.PUBLIC_KEYS_MAP_SLOT
-        # => [pub_key_slot_idx, [0, 0, 0, i-1], PUB_KEY, i-1, pad(12)]
+        push.PUBLIC_KEYS_MAP_SLOT[0..2]
+        # => [pub_key_slot_prefix, pub_key_slot_suffix, [0, 0, 0, i-1], PUB_KEY, i-1, pad(12)]
 
         exec.native_account::set_map_item
-        # => [OLD_MAP_ROOT, OLD_MAP_VALUE, i-1, pad(12)]
+        # => [OLD_VALUE, i-1, pad(12)]
 
-        dropw dropw
+        dropw
         # => [i-1, pad(12)]
 
         dup neq.0
@@ -237,13 +324,25 @@ pub proc update_signers_and_threshold.2(multisig_config_hash: BeWord)
     # => [pad(12)]
 end
 
+#! Update or clear the threshold override for a specific procedure.
+#!
+#! Inputs:
+#!   Operand stack: [proc_threshold, PROC_ROOT]
+#! Outputs:
+#!   Operand stack: []
+#! Invocation: call
+pub proc update_procedure_threshold(proc_threshold: u32, proc_root: BeWord)
+    exec.set_procedure_threshold
+end
+
 # Computes the effective transaction threshold based on called procedures and per-procedure
 # overrides stored in PROC_THRESHOLD_ROOTS_SLOT. Falls back to default_threshold if no
 # overrides apply.
 #
 #! Inputs:  [default_threshold]
 #! Outputs: [transaction_threshold]
-proc compute_transaction_threshold.1(default_threshold: u32) -> u32
+@locals(1)
+proc compute_transaction_threshold(default_threshold: u32) -> u32
     # 1. initialize transaction_threshold = 0
     # 2. iterate through all account procedures
     #   a. check if the procedure was called during the transaction
@@ -282,8 +381,8 @@ proc compute_transaction_threshold.1(default_threshold: u32) -> u32
         if.true
             # => [PROC_ROOT, num_procedures-1, transaction_threshold]
 
-            push.PROC_THRESHOLD_ROOTS_SLOT
-            # => [PROC_THRESHOLD_ROOTS_SLOT, PROC_ROOT, num_procedures-1, transaction_threshold]
+            push.PROC_THRESHOLD_ROOTS_SLOT[0..2]
+            # => [PROC_THRESHOLD_ROOTS_SLOT_prefix, PROC_THRESHOLD_ROOTS_SLOT_suffix, PROC_ROOT, num_procedures-1, transaction_threshold]
 
             # 2b. get the override proc_threshold of that procedure
             # if the procedure has no override threshold, the returned map item will be [0, 0, 0, 0]
@@ -333,8 +432,7 @@ end
 #! 1. Computing the transaction summary message that needs to be signed
 #! 2. Verifying ECDSA signatures from multiple required signers against their public keys
 #! 3. Ensuring the minimum threshold of valid signatures is met
-#! 4. Implementing replay protection by tracking executed transactions
-#! 5. Verifying PSM signature if PSM selector is enabled (via PSM component)
+#! 4. Returning the transaction summary commitment for higher-level wrappers.
 #!
 #! Inputs:
 #!   Operand stack: [SALT]
@@ -344,7 +442,7 @@ end
 #!     h(PUB_KEY_n, MSG): SIG_n
 #!   }
 #! Outputs:
-#!   Operand stack: []
+#!   Operand stack: [TX_SUMMARY_COMMITMENT]
 #!
 #! Where:
 #! - SALT is a cryptographically random nonce that enables multiple concurrent
@@ -356,11 +454,11 @@ end
 #!
 #! Panics if:
 #! - insufficient number of valid signatures (below threshold).
-#! - the same transaction has already been executed (replay protection).
-#! - PSM signature verification fails (if PSM is enabled).
+#! - insufficient number of valid signatures (below threshold).
 #!
-#! Invocation: call
-pub proc auth_tx_ecdsa_multisig.1(salt: BeWord)
+#! Invocation: exec
+@locals(1)
+pub proc auth_tx(salt: BeWord) -> BeWord
     exec.native_account::incr_nonce drop
     # => [SALT]
 
@@ -379,8 +477,8 @@ pub proc auth_tx_ecdsa_multisig.1(salt: BeWord)
 
     # ------ Verifying approver signatures ------
 
-    push.THRESHOLD_CONFIG_SLOT
-    # => [index, TX_SUMMARY_COMMITMENT]
+    push.THRESHOLD_CONFIG_SLOT[0..2]
+    # => [config_slot_prefix, config_slot_suffix, TX_SUMMARY_COMMITMENT]
 
     exec.active_account::get_initial_item
     # => [0, 0, num_of_approvers, default_threshold, TX_SUMMARY_COMMITMENT]
@@ -391,10 +489,10 @@ pub proc auth_tx_ecdsa_multisig.1(salt: BeWord)
     swap movdn.5
     # => [num_of_approvers, TX_SUMMARY_COMMITMENT, default_threshold]
 
-    push.PUBLIC_KEYS_MAP_SLOT
-    # => [pub_key_slot_idx, num_of_approvers, TX_SUMMARY_COMMITMENT, default_threshold]
+    push.PUBLIC_KEYS_MAP_SLOT[0..2]
+    # => [pub_key_slot_prefix, pub_key_slot_suffix, num_of_approvers, TX_SUMMARY_COMMITMENT, default_threshold]
 
-    exec.::miden::auth::ecdsa_k256_keccak::verify_signatures
+    exec.::miden::standards::auth::ecdsa_k256_keccak::verify_signatures
     # => [num_verified_signatures, TX_SUMMARY_COMMITMENT, default_threshold]
 
     # ------ Checking threshold is >= num_verified_signatures ------
@@ -414,11 +512,5 @@ pub proc auth_tx_ecdsa_multisig.1(salt: BeWord)
         push.0 assert.err="insufficient number of signatures"
     end
 
-    # ------ Verifying PSM Signature ------
-    # => [TX_SUMMARY_COMMITMENT]
-    call.psm_ecdsa::verify_psm_signature
-
-    # ------ Writing executed transaction MSG to map ------
     # => [TX_SUMMARY_COMMITMENT]
-    exec.assert_new_tx
 end

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openzeppelin/miden-multisig-client",
-  "version": "0.13.0",
-  "description": "TypeScript SDK for Miden multisig accounts with PSM integration",
+  "version": "0.13.2",
+  "description": "TypeScript SDK for Miden multisig accounts with GUARDIAN integration",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -18,17 +18,19 @@
     "masm"
   ],
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
+    "generate:masm": "node ./scripts/generate-masm.mjs",
+    "build": "npm run generate:masm && tsc",
+    "dev": "npm run generate:masm && tsc --watch",
+    "typecheck": "npm run generate:masm && tsc --noEmit",
     "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "npm run generate:masm && vitest run",
+    "test:watch": "npm run generate:masm && vitest"
   },
   "dependencies": {
-    "@miden-sdk/miden-sdk": "^0.13.0",
+    "@noble/curves": "^1.9.7",
+    "@miden-sdk/miden-sdk": "0.13.0",
     "@noble/hashes": "^2.0.1",
-    "@openzeppelin/psm-client": "^0.13.0"
+    "@openzeppelin/guardian-client": "^0.13.2"
   },
   "devDependencies": {
     "typescript": "^5.7.2",

package/src/account/builder.test.ts

@@ -0,0 +1,165 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createMultisigAccount } from './builder.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';
+
+const {
+  buildMultisigStorageSlots,
+  buildGuardianStorageSlots,
+  withSupportsAllTypes,
+  compileComponent,
+  MockAccountBuilder,
+} = vi.hoisted(() => {
+  const buildMultisigStorageSlots = vi.fn(() => ['multisig-slots']);
+  const buildGuardianStorageSlots = vi.fn(() => ['guardian-slots']);
+  const withSupportsAllTypes = vi.fn((component) => component);
+  const compileComponent = vi.fn((code, slots) => ({
+    code,
+    slots,
+    withSupportsAllTypes: () => withSupportsAllTypes({ code, slots }),
+  }));
+
+  class MockAccountBuilder {
+    accountType() {
+      return this;
+    }
+
+    storageMode() {
+      return this;
+    }
+
+    withAuthComponent() {
+      return this;
+    }
+
+    withComponent() {
+      return this;
+    }
+
+    withBasicWalletComponent() {
+      return this;
+    }
+
+    build() {
+      return {
+        account: { id: () => ({ toString: () => '0x' + 'a'.repeat(30) }) },
+      };
+    }
+  }
+
+  return {
+    buildMultisigStorageSlots,
+    buildGuardianStorageSlots,
+    withSupportsAllTypes,
+    compileComponent,
+    MockAccountBuilder,
+  };
+});
+
+vi.mock('./storage.js', () => ({
+  buildMultisigStorageSlots,
+  buildGuardianStorageSlots,
+}));
+
+vi.mock('@miden-sdk/miden-sdk', () => ({
+  AccountBuilder: MockAccountBuilder,
+  AccountComponent: {
+    compile: compileComponent,
+  },
+  AccountType: {
+    RegularAccountUpdatableCode: 'regular',
+  },
+  AccountStorageMode: {
+    public: () => 'public',
+    private: () => 'private',
+  },
+}));
+
+describe('createMultisigAccount', () => {
+  beforeEach(() => {
+    vi.stubGlobal('crypto', {
+      getRandomValues(buffer: Uint8Array) {
+        return buffer;
+      },
+    });
+    buildMultisigStorageSlots.mockClear();
+    buildGuardianStorageSlots.mockClear();
+    withSupportsAllTypes.mockClear();
+    compileComponent.mockClear();
+  });
+
+  it('uses Falcon MASM by default', async () => {
+    const authBuilder = {
+      buildLibrary: vi.fn((libraryPath, source) => ({ libraryPath, source })),
+      linkStaticLibrary: vi.fn(),
+      compileAccountComponentCode: vi.fn((source) => `auth:${source.slice(0, 16)}`),
+    };
+    const webClient = {
+      createCodeBuilder: vi.fn().mockReturnValue(authBuilder),
+      newAccount: vi.fn(),
+    };
+
+    await createMultisigAccount(webClient as never, {
+      threshold: 1,
+      signerCommitments: ['0x' + '1'.repeat(64)],
+      guardianCommitment: '0x' + '2'.repeat(64),
+    });
+
+    expect(authBuilder.buildLibrary).toHaveBeenNthCalledWith(
+      1,
+      'openzeppelin::auth::guardian',
+      GUARDIAN_MASM,
+    );
+    expect(authBuilder.buildLibrary).toHaveBeenNthCalledWith(
+      2,
+      'openzeppelin::auth::multisig',
+      MULTISIG_MASM,
+    );
+    expect(authBuilder.compileAccountComponentCode).toHaveBeenCalledWith(
+      MULTISIG_GUARDIAN_ACCOUNT_COMPONENT_MASM,
+    );
+    expect(webClient.newAccount).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses ECDSA MASM when requested', async () => {
+    const authBuilder = {
+      buildLibrary: vi.fn((libraryPath, source) => ({ libraryPath, source })),
+      linkStaticLibrary: vi.fn(),
+      compileAccountComponentCode: vi.fn((source) => `auth:${source.slice(0, 16)}`),
+    };
+    const webClient = {
+      createCodeBuilder: vi.fn().mockReturnValue(authBuilder),
+      newAccount: vi.fn(),
+    };
+
+    await createMultisigAccount(webClient as never, {
+      threshold: 1,
+      signerCommitments: ['0x' + '1'.repeat(64)],
+      guardianCommitment: '0x' + '2'.repeat(64),
+      signatureScheme: 'ecdsa',
+    });
+
+    expect(authBuilder.buildLibrary).toHaveBeenNthCalledWith(
+      1,
+      'openzeppelin::auth::guardian_ecdsa',
+      GUARDIAN_ECDSA_MASM,
+    );
+    expect(authBuilder.buildLibrary).toHaveBeenNthCalledWith(
+      2,
+      'openzeppelin::auth::multisig_ecdsa',
+      MULTISIG_ECDSA_MASM,
+    );
+    expect(authBuilder.compileAccountComponentCode).toHaveBeenCalledWith(
+      MULTISIG_GUARDIAN_ECDSA_ACCOUNT_COMPONENT_MASM,
+    );
+    expect(webClient.newAccount).toHaveBeenCalledTimes(1);
+  });
+});