@openzeppelin/miden-multisig-client 0.12.6

package/masm/psm.masm

@@ -0,0 +1,178 @@
+# Private State Manager (PSM) Authentication Component
+#
+# This component provides PSM signature verification for accounts.
+# It can be used standalone or in conjunction with other auth components like multisig.
+
+use miden::active_account
+use miden::native_account
+
+# Type definitions for v0.12 syntax
+type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
+
+# IMPORTANT SECURITY NOTES
+# --------------------------------------------------------------------------------
+# - The selector in `PSM_SELECTOR_SLOT` controls whether the extra PSM signature
+#   is enforced:
+#     * PSM_ON  => exactly one valid PSM signature is required.
+#     * PSM_OFF => PSM signature is skipped for that call.
+#
+# - `verify_psm_signature` reads the selector from initial storage state.
+#   This means changes made during the same transaction won't affect the check.
+#
+# - `enable_psm` / `disable_psm` procedures allow explicit control over PSM state.
+#
+# - `update_psm_public_key`:
+#     * Installs a new PSM public key in the map at `PSM_PUBLIC_KEY_MAP_SLOT`.
+#     * Does not itself perform any signature checks.
+#     * To update the key without requiring PSM signature, ensure selector is OFF.
+#
+# Storage Layout
+# --------------------------------------------------------------------------------
+#
+# +---------------------+---------------+
+# |     DESCRIPTION     |     SLOT      |
+# +---------------------+---------------+
+# | PSM SELECTOR (word) |       0       |
+# | PSM PUBLIC KEY MAP  |       1       |
+# +---------------------+---------------+
+#
+# - PSM_SELECTOR_SLOT (0):
+#     * Stores a word that is compared against [1, 0, 0, 0] (PSM_ON).
+#     * Any value != PSM_ON is treated as PSM_OFF.
+#
+# - PSM_PUBLIC_KEY_MAP_SLOT (1):
+#     * A map from a fixed key [0, 0, 0, 0] to the single PSM public key:
+#         [0, 0, 0, 0] => PSM_PUBLIC_KEY
+#     * PSM_PUBLIC_KEY is a RPO Falcon 512 public key represented as a word.
+
+# CONSTANTS
+# =================================================================================================
+
+# Slot where the PSM selector flag is stored:
+# - PSM_ON  => PSM signature required
+# - PSM_OFF => PSM signature skipped
+const PSM_SELECTOR_SLOT = 0
+
+# Map slot for PSM public key
+# Uses exactly one PSM public key at index [0, 0, 0, 0]
+# [0, 0, 0, 0] => PSM_PUBLIC_KEY
+const PSM_PUBLIC_KEY_MAP_SLOT = 1
+
+# Selector flag values
+const PSM_ON = [1, 0, 0, 0]
+const PSM_OFF = [0, 0, 0, 0]
+
+# The event emitted when a signature is not found for a required signer.
+const AUTH_UNAUTHORIZED_EVENT = event("miden::auth::unauthorized")
+
+# PSM PROCEDURES
+# =================================================================================================
+
+#! Enable PSM verification by setting the selector to ON.
+#!
+#! Operand stack inputs: []
+#! Outputs: []
+#!
+#! Notes:
+#! - Sets PSM_SELECTOR_SLOT to PSM_ON (1)
+#! - After this, transactions will require PSM signature verification
+proc.enable_psm
+    push.PSM_ON
+    # => [PSM_ON]
+
+    push.PSM_SELECTOR_SLOT
+    # => [PSM_SELECTOR_SLOT, PSM_ON]
+
+    exec.native_account::set_item
+    # => [OLD_ROOT]
+
+    dropw
+    # => []
+end
+
+#! Disable PSM verification by setting the selector to OFF.
+#!
+#! Operand stack inputs: []
+#! Outputs: []
+#!
+#! Notes:
+#! - Sets PSM_SELECTOR_SLOT to PSM_OFF (0)
+#! - After this, transactions will NOT require PSM signature verification
+proc.disable_psm
+    push.PSM_OFF
+    # => [PSM_OFF]
+
+    push.PSM_SELECTOR_SLOT
+    # => [PSM_SELECTOR_SLOT, PSM_OFF]
+
+    exec.native_account::set_item
+    # => [OLD_ROOT]
+
+    dropw
+    # => []
+end
+
+#! Update the PSM public key.
+#!
+#! Operand stack inputs: []
+#! Advice stack inputs:  [PUB_KEY]
+#!   - PUB_KEY is the new PSM RPO Falcon 512 public key
+#!
+#! Notes:
+#! - Stores PUB_KEY into PSM_PUBLIC_KEY_MAP_SLOT:
+#!      [0, 0, 0, 0] => PSM_PUBLIC_KEY
+#! - To update the key without requiring PSM signature, ensure
+#!   PSM_SELECTOR_SLOT = 0 (OFF) before calling this.
+pub proc update_psm_public_key
+    exec.disable_psm
+    # ------ Update the PSM public key ------
+    adv_loadw
+    # => [PUB_KEY]
+
+    push.0.0.0.0
+    # => [MAP_KEY, PUB_KEY]
+    # Note that MAP_KEY is [0, 0, 0, 0] for a single PSM_KEY
+
+    push.PSM_PUBLIC_KEY_MAP_SLOT
+    # => [index, MAP_KEY, PUB_KEY]
+
+    exec.native_account::set_map_item
+    # => [OLD_MAP_ROOT, OLD_MAP_VALUE]
+
+    dropw dropw
+    # => []
+end
+
+#! Conditionally verify a "PSM" signature against a stored public key hash.
+#! The condition is controlled by the selector at PSM_SELECTOR_SLOT.
+#!
+#! Inputs:  [MSG]
+#! Outputs: [MSG]
+#!
+#! Panics if:
+#! - Selector is ON but the provided PSM signature is invalid or missing.
+#!
+#! Notes:
+#! - MSG is TX_SUMMARY_COMMITMENT provided by auth procedure
+#! - If selector is OFF (0), PSM verification is skipped
+#! - Selector value is read from initial storage state
+pub proc verify_psm_signature(msg: BeWord)
+    push.PSM_SELECTOR_SLOT
+    exec.active_account::get_item
+    drop drop drop
+    # => [selector, MSG]
+
+    push.1 eq
+    if.true
+        push.1
+        push.PSM_PUBLIC_KEY_MAP_SLOT
+        exec.::miden::auth::rpo_falcon512::verify_signatures
+        push.1 neq
+        if.true
+            emit.AUTH_UNAUTHORIZED_EVENT
+            push.0 assert.err="invalid PSM signature"
+        end
+    end
+    # => [MSG]
+    exec.enable_psm
+end

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@openzeppelin/miden-multisig-client",
+  "version": "0.12.6",
+  "description": "TypeScript SDK for Miden multisig accounts with PSM integration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "masm"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@openzeppelin/psm-client": "^0.12.6"
+  },
+  "peerDependencies": {
+    "@demox-labs/miden-sdk": "^0.12.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/account/builder.ts

@@ -0,0 +1,112 @@
+/**
+ * Account builder for creating multisig accounts with PSM authentication.
+ *
+ * This module provides functionality to create multisig accounts.
+ */
+
+import {
+  AccountBuilder,
+  AccountComponent,
+  AccountType,
+  AccountStorageMode,
+  type WebClient,
+} from '@demox-labs/miden-sdk';
+import type { MultisigConfig, CreateAccountResult } from '../types.js';
+import { buildMultisigStorageSlots, buildPsmStorageSlots } from './storage.js';
+import { MULTISIG_MASM, PSM_MASM } from './masm.js';
+
+/**
+ * Creates a multisig account with PSM 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 multisigSlots = buildMultisigStorageSlots(config);
+  const psmSlots = buildPsmStorageSlots(config);
+
+  const psmBuilder = webClient.createScriptBuilder();
+  const psmComponent = AccountComponent
+    .compile(PSM_MASM, psmBuilder, psmSlots)
+    .withSupportsAllTypes();
+
+  const multisigBuilder = webClient.createScriptBuilder();
+  const psmLib = multisigBuilder.buildLibrary('openzeppelin::psm', PSM_MASM);
+  multisigBuilder.linkStaticLibrary(psmLib);
+  const multisigComponent = AccountComponent
+    .compile(MULTISIG_MASM, multisigBuilder, multisigSlots)
+    .withSupportsAllTypes();
+
+  // Generate random seed
+  const seed = new Uint8Array(32);
+  crypto.getRandomValues(seed);
+
+  const storageMode = config.storageMode === 'public'
+    ? AccountStorageMode.public()
+    : AccountStorageMode.private();
+
+  const accountBuilder = new AccountBuilder(seed)
+    .accountType(AccountType.RegularAccountUpdatableCode)
+    .storageMode(storageMode)
+    .withAuthComponent(multisigComponent)
+    .withComponent(psmComponent)
+    .withBasicWalletComponent();
+
+  const result = accountBuilder.build();
+
+  await webClient.newAccount(result.account, false);
+
+  return {
+    account: result.account,
+    seed,
+  };
+}
+
+/**
+ * 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');
+  }
+  if (config.signerCommitments.length === 0) {
+    throw new Error('at least one signer commitment is required');
+  }
+  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');
+  }
+
+  // Validate procedure thresholds if provided
+  if (config.procedureThresholds) {
+    const seen = new Set<string>();
+    for (const pt of config.procedureThresholds) {
+      if (pt.threshold < 1) {
+        throw new Error('procedure threshold must be at least 1');
+      }
+      if (pt.threshold > config.signerCommitments.length) {
+        throw new Error(
+          `procedure threshold (${pt.threshold}) cannot exceed number of signers (${config.signerCommitments.length})`
+        );
+      }
+
+      if (seen.has(pt.procedure)) {
+        throw new Error(`duplicate procedure threshold for: ${pt.procedure}`);
+      }
+      seen.add(pt.procedure);
+    }
+  }
+}

package/src/account/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Account creation and management utilities.
+ */
+
+export {
+  createMultisigAccount,
+  validateMultisigConfig,
+} from './builder.js';
+
+export {
+  buildMultisigStorageSlots,
+  buildPsmStorageSlots,
+  storageLayoutBuilder,
+  StorageLayoutBuilder,
+} from './storage.js';