@openzeppelin/miden-multisig-client 0.12.6

package/src/inspector.ts

@@ -0,0 +1,142 @@
+/**
+ * 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';
+
+export interface VaultBalance {
+  faucetId: string;
+  amount: bigint;
+}
+
+export interface DetectedMultisigConfig {
+  threshold: number;
+  numSigners: number;
+  signerCommitments: string[];
+  psmEnabled: boolean;
+  psmCommitment: string | null;
+  vaultBalances: VaultBalance[];
+  procedureThresholds: Map<ProcedureName, number>;
+}
+
+/**
+ * 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 {
+    const bytes = base64ToUint8Array(base64Data);
+    const account = Account.deserialize(bytes);
+    return AccountInspector.fromAccount(account);
+  }
+
+  /**
+   * 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 {
+    const storage = account.storage();
+
+    const slot0 = storage.getItem(0) as Word;
+    const threshold = Number(wordElementToBigInt(slot0, 0));
+    const numSigners = Number(wordElementToBigInt(slot0, 1));
+
+    const signerCommitments: string[] = [];
+    for (let i = 0; i < numSigners; i++) {
+      try {
+        const key = new Word(new BigUint64Array([BigInt(i), 0n, 0n, 0n]));
+        const commitment = storage.getMapItem(1, key) as Word;
+        if (commitment) {
+          signerCommitments.push(wordToHex(commitment));
+        }
+      } catch (error) {
+        console.warn(error);
+      }
+    }
+
+    let psmEnabled = false;
+    let psmCommitment: string | null = null;
+
+    try {
+      const psmSlot0 = storage.getItem(4) as Word;
+      const selector = Number(wordElementToBigInt(psmSlot0, 0));
+      psmEnabled = selector === 1;
+
+      if (psmEnabled) {
+        const zeroKey = new Word(new BigUint64Array([0n, 0n, 0n, 0n]));
+        const psmKey = storage.getMapItem(5, zeroKey) as Word;
+        if (psmKey) {
+          psmCommitment = wordToHex(psmKey);
+        }
+      }
+    } catch (error) {
+      console.warn(error);
+    }
+
+    const vaultBalances: VaultBalance[] = [];
+    try {
+      const vault = account.vault();
+      const fungibleAssets = vault.fungibleAssets();
+      for (const asset of fungibleAssets) {
+        vaultBalances.push({
+          faucetId: asset.faucetId().toString(),
+          amount: BigInt(asset.amount()),
+        });
+      }
+    } catch (error) {
+      console.warn(error);
+    }
+
+    // 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()) {
+      try {
+        const rootHex = getProcedureRoot(procName);
+        const rootWord = Word.fromHex(rootHex);
+        const value = storage.getMapItem(3, rootWord) as Word;
+        if (value) {
+          const procThreshold = Number(wordElementToBigInt(value, 0));
+          if (procThreshold > 0) {
+            procedureThresholds.set(procName, procThreshold);
+          }
+        }
+      } catch {
+        // Procedure threshold not set - use default
+      }
+    }
+
+    return {
+      threshold,
+      numSigners,
+      signerCommitments,
+      psmEnabled,
+      psmCommitment,
+      vaultBalances,
+      procedureThresholds,
+    };
+  }
+}

package/src/multisig/helpers.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { computeCommitmentFromTxSummary, accountIdToHex } from './helpers.js';
+
+vi.mock('@demox-labs/miden-sdk', () => ({
+  Account: {},
+  TransactionSummary: {
+    deserialize: vi.fn((bytes: Uint8Array) => ({
+      toCommitment: () => ({
+        toHex: () => '0x' + 'c'.repeat(64),
+      }),
+    })),
+  },
+  Word: {},
+}));
+
+describe('multisig helpers', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('computeCommitmentFromTxSummary', () => {
+    it('computes commitment from base64 tx summary', async () => {
+      const base64 = btoa(String.fromCharCode(...new Uint8Array([1, 2, 3])));
+      const commitment = computeCommitmentFromTxSummary(base64);
+
+      expect(commitment).toBe('0x' + 'c'.repeat(64));
+    });
+
+    it('deserializes the tx summary bytes', async () => {
+      const { TransactionSummary } = await import('@demox-labs/miden-sdk');
+      const base64 = btoa(String.fromCharCode(...new Uint8Array([4, 5, 6])));
+
+      computeCommitmentFromTxSummary(base64);
+
+      expect(TransactionSummary.deserialize).toHaveBeenCalledWith(
+        new Uint8Array([4, 5, 6])
+      );
+    });
+
+    it('returns hex string with 0x prefix', () => {
+      const base64 = btoa(String.fromCharCode(...new Uint8Array([1])));
+      const commitment = computeCommitmentFromTxSummary(base64);
+
+      expect(commitment.startsWith('0x')).toBe(true);
+    });
+  });
+
+  describe('accountIdToHex', () => {
+    it('returns account ID string if already hex formatted', () => {
+      const mockAccount = {
+        id: () => ({
+          toString: () => '0xabc123',
+          prefix: () => ({ asInt: () => BigInt(1) }),
+          suffix: () => ({ asInt: () => BigInt(2) }),
+        }),
+      };
+
+      const hex = accountIdToHex(mockAccount as any);
+      expect(hex).toBe('0xabc123');
+    });
+
+    it('handles 0X prefix', () => {
+      const mockAccount = {
+        id: () => ({
+          toString: () => '0Xabc123',
+          prefix: () => ({ asInt: () => BigInt(1) }),
+          suffix: () => ({ asInt: () => BigInt(2) }),
+        }),
+      };
+
+      const hex = accountIdToHex(mockAccount as any);
+      expect(hex).toBe('0Xabc123');
+    });
+
+    it('constructs hex from prefix and suffix if no 0x prefix', () => {
+      const mockAccount = {
+        id: () => ({
+          toString: () => 'not-a-hex',
+          prefix: () => ({ asInt: () => BigInt('0x0102030405060708') }),
+          suffix: () => ({ asInt: () => BigInt('0x0a0b0c0d0e0f1011') }),
+        }),
+      };
+
+      const hex = accountIdToHex(mockAccount as any);
+      expect(hex).toBe('0x01020304050607080a0b0c0d0e0f10');
+    });
+
+    it('pads prefix to 16 hex characters', () => {
+      const mockAccount = {
+        id: () => ({
+          toString: () => 'not-a-hex',
+          prefix: () => ({ asInt: () => BigInt(1) }),
+          suffix: () => ({ asInt: () => BigInt(0) }),
+        }),
+      };
+
+      const hex = accountIdToHex(mockAccount as any);
+      expect(hex).toBe('0x000000000000000100000000000000');
+    });
+
+    it('produces 30-character hex (excluding 0x prefix)', () => {
+      const mockAccount = {
+        id: () => ({
+          toString: () => 'not-a-hex',
+          prefix: () => ({ asInt: () => BigInt('0xffffffffffffffff') }),
+          suffix: () => ({ asInt: () => BigInt('0xffffffffffffffff') }),
+        }),
+      };
+
+      const hex = accountIdToHex(mockAccount as any);
+      expect(hex.length).toBe(32);
+    });
+  });
+});

package/src/multisig/helpers.ts

@@ -0,0 +1,23 @@
+import { Account, TransactionSummary, Word } from '@demox-labs/miden-sdk';
+import { base64ToUint8Array } from '../utils/encoding.js';
+
+export function computeCommitmentFromTxSummary(txSummaryBase64: string): string {
+  const bytes = base64ToUint8Array(txSummaryBase64);
+  const summary = TransactionSummary.deserialize(bytes);
+  const commitment = summary.toCommitment();
+  return commitment.toHex();
+}
+
+export function accountIdToHex(account: Account): string {
+  const accountId = account.id();
+  const str = accountId.toString();
+  if (str.startsWith('0x') || str.startsWith('0X')) {
+    return str;
+  }
+  const prefix = accountId.prefix().asInt();
+  const suffix = accountId.suffix().asInt();
+  const prefixHex = prefix.toString(16).padStart(16, '0');
+  const suffixHex = suffix.toString(16).padStart(16, '0');
+  return `0x${prefixHex}${suffixHex.slice(0, 14)}`;
+}
+