@openzeppelin/miden-multisig-client 0.12.8 → 0.13.0

package/src/inspector.test.ts

@@ -1,17 +1,30 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { AccountInspector } from './inspector.js';
 
+// Storage slot names matching the MASM definitions
+const MULTISIG_SLOT_NAMES = {
+  THRESHOLD_CONFIG: 'openzeppelin::multisig::threshold_config',
+  SIGNER_PUBLIC_KEYS: 'openzeppelin::multisig::signer_public_keys',
+  EXECUTED_TRANSACTIONS: 'openzeppelin::multisig::executed_transactions',
+  PROCEDURE_THRESHOLDS: 'openzeppelin::multisig::procedure_thresholds',
+} as const;
+
+const PSM_SLOT_NAMES = {
+  SELECTOR: 'openzeppelin::psm::selector',
+  PUBLIC_KEY: 'openzeppelin::psm::public_key',
+} as const;
+
 // Mock the Miden SDK
-vi.mock('@demox-labs/miden-sdk', () => {
+vi.mock('@miden-sdk/miden-sdk', () => {
   const createMockWord = (values: bigint[]) => ({
     toU64s: () => values,
     toHex: () => '0x' + values.map(v => v.toString(16).padStart(16, '0')).join(''),
   });
 
-  const createMockStorage = (slots: Map<number, any>, maps: Map<number, Map<string, any>>) => ({
-    getItem: (index: number) => slots.get(index) ?? createMockWord([0n, 0n, 0n, 0n]),
-    getMapItem: (slotIndex: number, key: any) => {
-      const map = maps.get(slotIndex);
+  const createMockStorage = (slots: Map<string, any>, maps: Map<string, Map<string, any>>) => ({
+    getItem: (slotName: string) => slots.get(slotName) ?? createMockWord([0n, 0n, 0n, 0n]),
+    getMapItem: (slotName: string, key: any) => {
+      const map = maps.get(slotName);
       if (!map) throw new Error('Map not found');
       const keyStr = key.toU64s?.()[0]?.toString() ?? '0';
       const value = map.get(keyStr);
@@ -43,13 +56,13 @@ vi.mock('@demox-labs/miden-sdk', () => {
         const psmMap = new Map<string, any>();
         psmMap.set('0', createMockWord([BigInt('0xeeeeeeeeeeeeeeee'), BigInt('0xffffffffffffffff'), BigInt('0x0000000000000001'), BigInt('0x0000000000000002')]));
 
-        const slots = new Map<number, any>();
-        slots.set(0, slot0);
-        slots.set(4, slot4);
+        const slots = new Map<string, any>();
+        slots.set('openzeppelin::multisig::threshold_config', slot0);
+        slots.set('openzeppelin::psm::selector', slot4);
 
-        const maps = new Map<number, Map<string, any>>();
-        maps.set(1, signerMap);
-        maps.set(5, psmMap);
+        const maps = new Map<string, Map<string, any>>();
+        maps.set('openzeppelin::multisig::signer_public_keys', signerMap);
+        maps.set('openzeppelin::psm::public_key', psmMap);
 
         return {
           storage: () => createMockStorage(slots, maps),
@@ -111,7 +124,7 @@ describe('AccountInspector', () => {
 
   describe('fromAccount', () => {
     it('extracts threshold from slot 0', async () => {
-      const { Account } = await import('@demox-labs/miden-sdk');
+      const { Account } = await import('@miden-sdk/miden-sdk');
       const account = Account.deserialize(new Uint8Array([1, 2, 3]));
       const config = AccountInspector.fromAccount(account);
 
@@ -119,7 +132,7 @@ describe('AccountInspector', () => {
     });
 
     it('extracts numSigners from slot 0', async () => {
-      const { Account } = await import('@demox-labs/miden-sdk');
+      const { Account } = await import('@miden-sdk/miden-sdk');
       const account = Account.deserialize(new Uint8Array([1, 2, 3]));
       const config = AccountInspector.fromAccount(account);
 
@@ -134,18 +147,18 @@ describe('AccountInspector edge cases', () => {
   });
 
   it('handles account with PSM disabled', async () => {
-    const { Account } = await import('@demox-labs/miden-sdk');
+    const { Account } = await import('@miden-sdk/miden-sdk');
 
     // Override mock for this test
     vi.mocked(Account.deserialize).mockReturnValueOnce({
       storage: () => ({
-        getItem: (index: number) => {
-          if (index === 0) return { toU64s: () => [1n, 1n, 0n, 0n] };
-          if (index === 4) return { toU64s: () => [0n, 0n, 0n, 0n] }; // PSM disabled
+        getItem: (slotName: string) => {
+          if (slotName === 'openzeppelin::multisig::threshold_config') return { toU64s: () => [1n, 1n, 0n, 0n] };
+          if (slotName === 'openzeppelin::psm::selector') return { toU64s: () => [0n, 0n, 0n, 0n] }; // PSM disabled
           return { toU64s: () => [0n, 0n, 0n, 0n] };
         },
-        getMapItem: (slotIndex: number, key: any) => {
-          if (slotIndex === 1 && key.toU64s?.()[0] === 0n) {
+        getMapItem: (slotName: string, key: any) => {
+          if (slotName === 'openzeppelin::multisig::signer_public_keys' && key.toU64s?.()[0] === 0n) {
             return {
               toHex: () => '0x' + 'a'.repeat(64),
               toU64s: () => [1n, 2n, 3n, 4n],
@@ -167,7 +180,7 @@ describe('AccountInspector edge cases', () => {
   });
 
   it('handles account with empty vault', async () => {
-    const { Account } = await import('@demox-labs/miden-sdk');
+    const { Account } = await import('@miden-sdk/miden-sdk');
 
     vi.mocked(Account.deserialize).mockReturnValueOnce({
       storage: () => ({
@@ -188,13 +201,13 @@ describe('AccountInspector edge cases', () => {
   });
 
   it('handles missing signer map entries gracefully', async () => {
-    const { Account } = await import('@demox-labs/miden-sdk');
+    const { Account } = await import('@miden-sdk/miden-sdk');
 
     vi.mocked(Account.deserialize).mockReturnValueOnce({
       storage: () => ({
-        getItem: (index: number) => {
-          if (index === 0) return { toU64s: () => [2n, 5n, 0n, 0n] }; // threshold=2, numSigners=5
-          if (index === 4) return { toU64s: () => [0n, 0n, 0n, 0n] };
+        getItem: (slotName: string) => {
+          if (slotName === 'openzeppelin::multisig::threshold_config') return { toU64s: () => [2n, 5n, 0n, 0n] }; // threshold=2, numSigners=5
+          if (slotName === 'openzeppelin::psm::selector') return { toU64s: () => [0n, 0n, 0n, 0n] };
           return { toU64s: () => [0n, 0n, 0n, 0n] };
         },
         getMapItem: () => {
@@ -215,7 +228,7 @@ describe('AccountInspector edge cases', () => {
   });
 
   it('handles vault access error gracefully', async () => {
-    const { Account } = await import('@demox-labs/miden-sdk');
+    const { Account } = await import('@miden-sdk/miden-sdk');
 
     vi.mocked(Account.deserialize).mockReturnValueOnce({
       storage: () => ({

package/src/inspector.ts

@@ -1,9 +1,21 @@
-import { Account, Word } from '@demox-labs/miden-sdk';
+import { Account, Word } from '@miden-sdk/miden-sdk';
 import { base64ToUint8Array } from './utils/encoding.js';
 import { wordElementToBigInt, wordToHex } from './utils/word.js';
 import { getProcedureRoot, getProcedureNames, type ProcedureName } from './procedures.js';
 import type { SignatureScheme } from './types.js';
 
+const MULTISIG_SLOT_NAMES = {
+  THRESHOLD_CONFIG: 'openzeppelin::multisig::threshold_config',
+  SIGNER_PUBLIC_KEYS: 'openzeppelin::multisig::signer_public_keys',
+  EXECUTED_TRANSACTIONS: 'openzeppelin::multisig::executed_transactions',
+  PROCEDURE_THRESHOLDS: 'openzeppelin::multisig::procedure_thresholds',
+} as const;
+
+const PSM_SLOT_NAMES = {
+  SELECTOR: 'openzeppelin::psm::selector',
+  PUBLIC_KEY: 'openzeppelin::psm::public_key',
+} as const;
+
 export interface VaultBalance {
   faucetId: string;
   amount: bigint;
@@ -32,7 +44,7 @@ export class AccountInspector {
   static fromAccount(account: Account, signatureScheme: SignatureScheme = 'falcon'): DetectedMultisigConfig {
     const storage = account.storage();
 
-    const slot0 = storage.getItem(0) as Word;
+    const slot0 = storage.getItem(MULTISIG_SLOT_NAMES.THRESHOLD_CONFIG) as Word;
     const threshold = Number(wordElementToBigInt(slot0, 0));
     const numSigners = Number(wordElementToBigInt(slot0, 1));
 
@@ -40,12 +52,11 @@ export class AccountInspector {
     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;
+        const commitment = storage.getMapItem(MULTISIG_SLOT_NAMES.SIGNER_PUBLIC_KEYS, key) as Word;
         if (commitment) {
           signerCommitments.push(wordToHex(commitment));
         }
       } catch {
-        // Signer not found in storage map
       }
     }
 
@@ -53,19 +64,18 @@ export class AccountInspector {
     let psmCommitment: string | null = null;
 
     try {
-      const psmSlot0 = storage.getItem(4) as Word;
+      const psmSlot0 = storage.getItem(PSM_SLOT_NAMES.SELECTOR) 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;
+        const psmKey = storage.getMapItem(PSM_SLOT_NAMES.PUBLIC_KEY, zeroKey) as Word;
         if (psmKey) {
           psmCommitment = wordToHex(psmKey);
         }
       }
     } catch {
-      // PSM not configured
     }
 
     const vaultBalances: VaultBalance[] = [];
@@ -79,7 +89,6 @@ export class AccountInspector {
         });
       }
     } catch {
-      // Vault access failed
     }
 
     const procedureThresholds = new Map<ProcedureName, number>();
@@ -87,7 +96,7 @@ export class AccountInspector {
       try {
         const rootHex = getProcedureRoot(procName, signatureScheme);
         const rootWord = Word.fromHex(rootHex);
-        const value = storage.getMapItem(3, rootWord) as Word;
+        const value = storage.getMapItem(MULTISIG_SLOT_NAMES.PROCEDURE_THRESHOLDS, rootWord) as Word;
         if (value) {
           const procThreshold = Number(wordElementToBigInt(value, 0));
           if (procThreshold > 0) {
@@ -95,7 +104,6 @@ export class AccountInspector {
           }
         }
       } catch {
-        // Not set
       }
     }
 

package/src/multisig/helpers.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { computeCommitmentFromTxSummary, accountIdToHex } from './helpers.js';
 
-vi.mock('@demox-labs/miden-sdk', () => ({
+vi.mock('@miden-sdk/miden-sdk', () => ({
   Account: {},
   TransactionSummary: {
     deserialize: vi.fn((bytes: Uint8Array) => ({
@@ -27,7 +27,7 @@ describe('multisig helpers', () => {
     });
 
     it('deserializes the tx summary bytes', async () => {
-      const { TransactionSummary } = await import('@demox-labs/miden-sdk');
+      const { TransactionSummary } = await import('@miden-sdk/miden-sdk');
       const base64 = btoa(String.fromCharCode(...new Uint8Array([4, 5, 6])));
 
       computeCommitmentFromTxSummary(base64);

package/src/multisig/helpers.ts

@@ -1,4 +1,4 @@
-import { Account, TransactionSummary } from '@demox-labs/miden-sdk';
+import { Account, TransactionSummary, Word } from '@miden-sdk/miden-sdk';
 import { base64ToUint8Array } from '../utils/encoding.js';
 
 export function computeCommitmentFromTxSummary(txSummaryBase64: string): string {
@@ -7,6 +7,7 @@ export function computeCommitmentFromTxSummary(txSummaryBase64: string): string
   const commitment = summary.toCommitment();
   return commitment.toHex();
 }
+
 export function accountIdToHex(account: Account): string {
   const accountId = account.id();
   const str = accountId.toString();

package/src/multisig/proposal/execution.ts

@@ -0,0 +1,320 @@
+import { type DeltaObject, type PsmHttpClient } from '@openzeppelin/psm-client';
+import type { WebClient, TransactionRequest } from '@miden-sdk/miden-sdk';
+import {
+  AccountId,
+  AdviceMap,
+  FeltArray,
+  Signature,
+  TransactionSummary,
+  Word,
+} from '@miden-sdk/miden-sdk';
+import type { ProposalType, TransactionProposal } from '../../types.js';
+import {
+  buildConsumeNotesTransactionRequest,
+  buildP2idTransactionRequest,
+  buildUpdatePsmTransactionRequest,
+  buildUpdateSignersTransactionRequest,
+} from '../../transaction.js';
+import { base64ToUint8Array, normalizeHexWord } from '../../utils/encoding.js';
+import {
+  buildSignatureAdviceEntry,
+  signatureHexToBytes,
+  tryComputeEcdsaCommitmentHex,
+} from '../../utils/signature.js';
+import { computeCommitmentFromTxSummary } from '../helpers.js';
+
+interface ResolveExecutionSourceResult {
+  delta?: DeltaObject;
+  txSummaryBase64: string;
+}
+
+interface PrepareExecutionResult {
+  txSummary: TransactionSummary;
+  saltHex: string;
+  txCommitmentHex: string;
+}
+
+interface ExecuteProposalWorkflowParams {
+  proposal: TransactionProposal;
+  accountId: string;
+  threshold: number;
+  signerCommitments: string[];
+  psmCommitment: string;
+  psmPublicKey?: string;
+  signatureScheme: 'falcon' | 'ecdsa';
+  getEffectiveThreshold: (proposalType: ProposalType) => number;
+  psm: PsmHttpClient;
+  webClient: WebClient;
+}
+
+export async function executeProposalWorkflow(
+  params: ExecuteProposalWorkflowParams,
+): Promise<void> {
+  ensureProposalReady(
+    params.proposal,
+    params.threshold,
+    params.getEffectiveThreshold,
+  );
+
+  const isSwitchPsm = params.proposal.metadata.proposalType === 'switch_psm';
+  const executionSource = await resolveExecutionSource(
+    params.psm,
+    params.accountId,
+    params.proposal,
+    isSwitchPsm,
+  );
+  const executionData = prepareExecutionData(executionSource.txSummaryBase64);
+
+  const adviceMap = buildCosignerAdviceMap(
+    params.proposal,
+    params.signerCommitments,
+    executionData.txCommitmentHex,
+  );
+
+  if (!isSwitchPsm && executionSource.delta) {
+    await appendPsmAckAdvice(
+      params.psm,
+      executionSource.delta,
+      params.psmCommitment,
+      params.psmPublicKey,
+      params.signatureScheme,
+      executionData.txCommitmentHex,
+      adviceMap,
+    );
+  }
+
+  const finalRequest = await buildFinalRequest(
+    params,
+    executionData.saltHex,
+    adviceMap,
+  );
+  await submitTransaction(params.webClient, params.accountId, finalRequest);
+}
+
+function ensureProposalReady(
+  proposal: TransactionProposal,
+  defaultThreshold: number,
+  getEffectiveThreshold: (proposalType: ProposalType) => number,
+): void {
+  const proposalType = proposal.metadata?.proposalType;
+  const effectiveThreshold = proposalType
+    ? getEffectiveThreshold(proposalType)
+    : defaultThreshold;
+
+  if (proposal.signatures.length < effectiveThreshold) {
+    throw new Error('Proposal is not ready for execution. Still pending signatures.');
+  }
+}
+
+async function resolveExecutionSource(
+  psm: PsmHttpClient,
+  accountId: string,
+  proposal: TransactionProposal,
+  isSwitchPsm: boolean,
+): Promise<ResolveExecutionSourceResult> {
+  if (isSwitchPsm) {
+    return { txSummaryBase64: proposal.txSummary };
+  }
+
+  const deltas = await psm.getDeltaProposals(accountId);
+  const delta = deltas.find(
+    (d) => computeCommitmentFromTxSummary(d.deltaPayload.txSummary.data) === proposal.commitment,
+  );
+
+  if (!delta) {
+    throw new Error(`Proposal not found on server: ${proposal.commitment}`);
+  }
+
+  return {
+    delta,
+    txSummaryBase64: delta.deltaPayload.txSummary.data,
+  };
+}
+
+function prepareExecutionData(txSummaryBase64: string): PrepareExecutionResult {
+  const txSummaryBytes = base64ToUint8Array(txSummaryBase64);
+  const txSummary = TransactionSummary.deserialize(txSummaryBytes);
+  const saltHex = txSummary.salt().toHex();
+  const txCommitmentHex = txSummary.toCommitment().toHex();
+  return { txSummary, saltHex, txCommitmentHex };
+}
+
+function buildCosignerAdviceMap(
+  proposal: TransactionProposal,
+  signerCommitments: string[],
+  txCommitmentHex: string,
+): AdviceMap {
+  const adviceMap = new AdviceMap();
+  const normalizedSignerCommitments = new Set(
+    signerCommitments.map((c) => normalizeHexWord(c)),
+  );
+
+  for (const cosignerSig of proposal.signatures) {
+    let signerCommitmentHex = normalizeHexWord(cosignerSig.signerId);
+    if (cosignerSig.signature.scheme === 'ecdsa' && cosignerSig.signature.publicKey) {
+      const derived = tryComputeEcdsaCommitmentHex(cosignerSig.signature.publicKey);
+      if (derived && derived !== signerCommitmentHex) {
+        if (!normalizedSignerCommitments.has(derived)) {
+          throw new Error(
+            `ECDSA public key commitment mismatch: derived commitment ${derived} is not in signerCommitments.`,
+          );
+        }
+        signerCommitmentHex = derived;
+      }
+    }
+
+    const signerCommitment = Word.fromHex(signerCommitmentHex);
+    const sigBytes = signatureHexToBytes(
+      cosignerSig.signature.signature,
+      cosignerSig.signature.scheme,
+    );
+    const signature = Signature.deserialize(sigBytes);
+    const txCommitment = Word.fromHex(normalizeHexWord(txCommitmentHex));
+    const isEcdsa =
+      cosignerSig.signature.scheme === 'ecdsa' && cosignerSig.signature.publicKey;
+
+    const { key, values } = buildSignatureAdviceEntry(
+      signerCommitment,
+      txCommitment,
+      signature,
+      isEcdsa ? cosignerSig.signature.publicKey : undefined,
+      isEcdsa ? cosignerSig.signature.signature : undefined,
+    );
+    adviceMap.insert(key, new FeltArray(values));
+  }
+
+  return adviceMap;
+}
+
+async function appendPsmAckAdvice(
+  psm: PsmHttpClient,
+  delta: DeltaObject,
+  psmCommitmentHex: string,
+  psmPublicKey: string | undefined,
+  defaultAckScheme: 'falcon' | 'ecdsa',
+  txCommitmentHex: string,
+  adviceMap: AdviceMap,
+): Promise<void> {
+  const executionDelta = {
+    ...delta,
+    deltaPayload: delta.deltaPayload.txSummary,
+  };
+
+  const pushResult = await psm.pushDelta(executionDelta);
+  const ackSigHex = pushResult.ackSig;
+  if (!ackSigHex) {
+    throw new Error('PSM did not return acknowledgment signature');
+  }
+
+  const psmAckScheme: 'ecdsa' | 'falcon' =
+    (pushResult.ackScheme as 'ecdsa' | 'falcon') || defaultAckScheme;
+  const ackPubkey = pushResult.ackPubkey || psmPublicKey;
+  const normalizedPsmCommitment = normalizeHexWord(psmCommitmentHex);
+
+  if (psmAckScheme === 'ecdsa' && ackPubkey) {
+    const derived = tryComputeEcdsaCommitmentHex(ackPubkey);
+    if (derived && derived !== normalizedPsmCommitment) {
+      throw new Error('PSM public key commitment mismatch');
+    }
+  }
+
+  const psmCommitment = Word.fromHex(normalizedPsmCommitment);
+  const ackSigBytes = signatureHexToBytes(ackSigHex, psmAckScheme);
+  const ackSignature = Signature.deserialize(ackSigBytes);
+  const txCommitment = Word.fromHex(normalizeHexWord(txCommitmentHex));
+  const isAckEcdsa = psmAckScheme === 'ecdsa' && ackPubkey;
+  const { key, values } = buildSignatureAdviceEntry(
+    psmCommitment,
+    txCommitment,
+    ackSignature,
+    isAckEcdsa ? ackPubkey : undefined,
+    isAckEcdsa ? ackSigHex : undefined,
+  );
+  adviceMap.insert(key, new FeltArray(values));
+}
+
+async function buildFinalRequest(
+  params: ExecuteProposalWorkflowParams,
+  saltHex: string,
+  adviceMap: AdviceMap,
+): Promise<TransactionRequest> {
+  const metadata = params.proposal.metadata;
+  const normalizedSalt = Word.fromHex(normalizeHexWord(saltHex));
+
+  switch (metadata.proposalType) {
+    case 'consume_notes': {
+      if (!metadata.noteIds || metadata.noteIds.length === 0) {
+        throw new Error(
+          'Proposal missing noteIds. Was it created with createConsumeNotesProposal?',
+        );
+      }
+      const { request } = await buildConsumeNotesTransactionRequest(
+        params.webClient,
+        metadata.noteIds,
+        { salt: normalizedSalt, signatureAdviceMap: adviceMap },
+      );
+      return request;
+    }
+    case 'switch_psm': {
+      if (!metadata.newPsmPubkey) {
+        throw new Error(
+          'Proposal missing newPsmPubkey. Was it created with createSwitchPsmProposal?',
+        );
+      }
+      const { request } = await buildUpdatePsmTransactionRequest(
+        params.webClient,
+        metadata.newPsmPubkey,
+        {
+          salt: normalizedSalt,
+          signatureAdviceMap: adviceMap,
+          signatureScheme: params.signatureScheme,
+        },
+      );
+      return request;
+    }
+    case 'p2id': {
+      if (!metadata.recipientId || !metadata.faucetId || !metadata.amount) {
+        throw new Error(
+          'Proposal missing P2ID metadata (recipientId, faucetId, amount). Was it created with createP2idProposal?',
+        );
+      }
+      const { request } = buildP2idTransactionRequest(
+        params.accountId,
+        metadata.recipientId,
+        metadata.faucetId,
+        BigInt(metadata.amount),
+        { salt: normalizedSalt, signatureAdviceMap: adviceMap },
+      );
+      return request;
+    }
+    case 'unknown':
+      throw new Error(
+        'Cannot execute proposal with unknown type. The proposal must have been imported without proper metadata.',
+      );
+    default: {
+      const { request } = await buildUpdateSignersTransactionRequest(
+        params.webClient,
+        metadata.targetThreshold,
+        metadata.targetSignerCommitments,
+        {
+          salt: normalizedSalt,
+          signatureAdviceMap: adviceMap,
+          signatureScheme: params.signatureScheme,
+        },
+      );
+      return request;
+    }
+  }
+}
+
+async function submitTransaction(
+  webClient: WebClient,
+  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);
+}