@openzeppelin/miden-multisig-client 0.13.0 → 0.13.2

package/src/inspector.ts

@@ -1,9 +1,13 @@
+/**
+ * Account Inspector - Inspects account storage to detect multisig configuration.
+ */
+
 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';
 
+// 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',
@@ -11,9 +15,9 @@ const MULTISIG_SLOT_NAMES = {
   PROCEDURE_THRESHOLDS: 'openzeppelin::multisig::procedure_thresholds',
 } as const;
 
-const PSM_SLOT_NAMES = {
-  SELECTOR: 'openzeppelin::psm::selector',
-  PUBLIC_KEY: 'openzeppelin::psm::public_key',
+const GUARDIAN_SLOT_NAMES = {
+  SELECTOR: 'openzeppelin::guardian::selector',
+  PUBLIC_KEY: 'openzeppelin::guardian::public_key',
 } as const;
 
 export interface VaultBalance {
@@ -25,23 +29,48 @@ export interface DetectedMultisigConfig {
   threshold: number;
   numSigners: number;
   signerCommitments: string[];
-  psmEnabled: boolean;
-  psmCommitment: string | null;
+  guardianEnabled: boolean;
+  guardianCommitment: string | null;
   vaultBalances: VaultBalance[];
   procedureThresholds: Map<ProcedureName, number>;
-  signatureScheme: SignatureScheme;
 }
 
+/**
+ * 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() {}
 
-  static fromBase64(base64Data: string, signatureScheme: SignatureScheme = 'falcon'): DetectedMultisigConfig {
-    const bytes = base64ToUint8Array(base64Data);
-    const account = Account.deserialize(bytes);
-    return AccountInspector.fromAccount(account, signatureScheme);
+  /**
+   * 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);
   }
 
-  static fromAccount(account: Account, signatureScheme: SignatureScheme = 'falcon'): DetectedMultisigConfig {
+  /**
+   * 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(MULTISIG_SLOT_NAMES.THRESHOLD_CONFIG) as Word;
@@ -56,26 +85,28 @@ export class AccountInspector {
         if (commitment) {
           signerCommitments.push(wordToHex(commitment));
         }
-      } catch {
+      } catch (error) {
+        console.warn(error);
       }
     }
 
-    let psmEnabled = false;
-    let psmCommitment: string | null = null;
+    let guardianEnabled = false;
+    let guardianCommitment: string | null = null;
 
     try {
-      const psmSlot0 = storage.getItem(PSM_SLOT_NAMES.SELECTOR) as Word;
-      const selector = Number(wordElementToBigInt(psmSlot0, 0));
-      psmEnabled = selector === 1;
+      const guardianSlot0 = storage.getItem(GUARDIAN_SLOT_NAMES.SELECTOR) as Word;
+      const selector = Number(wordElementToBigInt(guardianSlot0, 0));
+      guardianEnabled = selector === 1;
 
-      if (psmEnabled) {
+      if (guardianEnabled) {
         const zeroKey = new Word(new BigUint64Array([0n, 0n, 0n, 0n]));
-        const psmKey = storage.getMapItem(PSM_SLOT_NAMES.PUBLIC_KEY, zeroKey) as Word;
-        if (psmKey) {
-          psmCommitment = wordToHex(psmKey);
+        const guardianKey = storage.getMapItem(GUARDIAN_SLOT_NAMES.PUBLIC_KEY, zeroKey) as Word;
+        if (guardianKey) {
+          guardianCommitment = wordToHex(guardianKey);
         }
       }
-    } catch {
+    } catch (error) {
+      console.warn(error);
     }
 
     const vaultBalances: VaultBalance[] = [];
@@ -88,13 +119,16 @@ export class AccountInspector {
           amount: BigInt(asset.amount()),
         });
       }
-    } catch {
+    } 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(signatureScheme)) {
+    for (const procName of getProcedureNames()) {
       try {
-        const rootHex = getProcedureRoot(procName, signatureScheme);
+        const rootHex = getProcedureRoot(procName);
         const rootWord = Word.fromHex(rootHex);
         const value = storage.getMapItem(MULTISIG_SLOT_NAMES.PROCEDURE_THRESHOLDS, rootWord) as Word;
         if (value) {
@@ -104,6 +138,7 @@ export class AccountInspector {
           }
         }
       } catch {
+        // Procedure threshold not set - use default
       }
     }
 
@@ -111,11 +146,10 @@ export class AccountInspector {
       threshold,
       numSigners,
       signerCommitments,
-      psmEnabled,
-      psmCommitment,
+      guardianEnabled,
+      guardianCommitment,
       vaultBalances,
       procedureThresholds,
-      signatureScheme,
     };
   }
 }

package/src/multisig/proposal/execution.ts

@@ -1,4 +1,4 @@
-import { type DeltaObject, type PsmHttpClient } from '@openzeppelin/psm-client';
+import { type DeltaObject, type GuardianHttpClient } from '@openzeppelin/guardian-client';
 import type { WebClient, TransactionRequest } from '@miden-sdk/miden-sdk';
 import {
   AccountId,
@@ -12,7 +12,8 @@ import type { ProposalType, TransactionProposal } from '../../types.js';
 import {
   buildConsumeNotesTransactionRequest,
   buildP2idTransactionRequest,
-  buildUpdatePsmTransactionRequest,
+  buildUpdateGuardianTransactionRequest,
+  buildUpdateProcedureThresholdTransactionRequest,
   buildUpdateSignersTransactionRequest,
 } from '../../transaction.js';
 import { base64ToUint8Array, normalizeHexWord } from '../../utils/encoding.js';
@@ -39,11 +40,11 @@ interface ExecuteProposalWorkflowParams {
   accountId: string;
   threshold: number;
   signerCommitments: string[];
-  psmCommitment: string;
-  psmPublicKey?: string;
+  guardianCommitment: string;
+  guardianPublicKey?: string;
   signatureScheme: 'falcon' | 'ecdsa';
   getEffectiveThreshold: (proposalType: ProposalType) => number;
-  psm: PsmHttpClient;
+  guardian: GuardianHttpClient;
   webClient: WebClient;
 }
 
@@ -56,12 +57,12 @@ export async function executeProposalWorkflow(
     params.getEffectiveThreshold,
   );
 
-  const isSwitchPsm = params.proposal.metadata.proposalType === 'switch_psm';
+  const isSwitchGuardian = params.proposal.metadata.proposalType === 'switch_guardian';
   const executionSource = await resolveExecutionSource(
-    params.psm,
+    params.guardian,
     params.accountId,
     params.proposal,
-    isSwitchPsm,
+    isSwitchGuardian,
   );
   const executionData = prepareExecutionData(executionSource.txSummaryBase64);
 
@@ -71,12 +72,12 @@ export async function executeProposalWorkflow(
     executionData.txCommitmentHex,
   );
 
-  if (!isSwitchPsm && executionSource.delta) {
-    await appendPsmAckAdvice(
-      params.psm,
+  if (!isSwitchGuardian && executionSource.delta) {
+    await appendGuardianAckAdvice(
+      params.guardian,
       executionSource.delta,
-      params.psmCommitment,
-      params.psmPublicKey,
+      params.guardianCommitment,
+      params.guardianPublicKey,
       params.signatureScheme,
       executionData.txCommitmentHex,
       adviceMap,
@@ -91,6 +92,50 @@ export async function executeProposalWorkflow(
   await submitTransaction(params.webClient, params.accountId, finalRequest);
 }
 
+
+export async function createTransactionProposalRequest(
+  params: ExecuteProposalWorkflowParams,
+): Promise<TransactionRequest> {
+  ensureProposalReady(
+    params.proposal,
+    params.threshold,
+    params.getEffectiveThreshold,
+  );
+
+  const isSwitchGuardian = params.proposal.metadata.proposalType === 'switch_guardian';
+  const executionSource = await resolveExecutionSource(
+    params.guardian,
+    params.accountId,
+    params.proposal,
+    isSwitchGuardian,
+  );
+  const executionData = prepareExecutionData(executionSource.txSummaryBase64);
+
+  const adviceMap = buildCosignerAdviceMap(
+    params.proposal,
+    params.signerCommitments,
+    executionData.txCommitmentHex,
+  );
+
+  if (!isSwitchGuardian && executionSource.delta) {
+    await appendGuardianAckAdvice(
+      params.guardian,
+      executionSource.delta,
+      params.guardianCommitment,
+      params.guardianPublicKey,
+      params.signatureScheme,
+      executionData.txCommitmentHex,
+      adviceMap,
+    );
+  }
+
+  return await buildFinalRequest(
+    params,
+    executionData.saltHex,
+    adviceMap,
+  );
+}
+
 function ensureProposalReady(
   proposal: TransactionProposal,
   defaultThreshold: number,
@@ -107,16 +152,16 @@ function ensureProposalReady(
 }
 
 async function resolveExecutionSource(
-  psm: PsmHttpClient,
+  guardian: GuardianHttpClient,
   accountId: string,
   proposal: TransactionProposal,
-  isSwitchPsm: boolean,
+  isSwitchGuardian: boolean,
 ): Promise<ResolveExecutionSourceResult> {
-  if (isSwitchPsm) {
+  if (isSwitchGuardian) {
     return { txSummaryBase64: proposal.txSummary };
   }
 
-  const deltas = await psm.getDeltaProposals(accountId);
+  const deltas = await guardian.getDeltaProposals(accountId);
   const delta = deltas.find(
     (d) => computeCommitmentFromTxSummary(d.deltaPayload.txSummary.data) === proposal.commitment,
   );
@@ -170,14 +215,17 @@ function buildCosignerAdviceMap(
     );
     const signature = Signature.deserialize(sigBytes);
     const txCommitment = Word.fromHex(normalizeHexWord(txCommitmentHex));
-    const isEcdsa =
-      cosignerSig.signature.scheme === 'ecdsa' && cosignerSig.signature.publicKey;
+    const ecdsaPublicKey =
+      cosignerSig.signature.scheme === 'ecdsa'
+        ? cosignerSig.signature.publicKey
+        : undefined;
+    const isEcdsa = cosignerSig.signature.scheme === 'ecdsa' && Boolean(ecdsaPublicKey);
 
     const { key, values } = buildSignatureAdviceEntry(
       signerCommitment,
       txCommitment,
       signature,
-      isEcdsa ? cosignerSig.signature.publicKey : undefined,
+      ecdsaPublicKey,
       isEcdsa ? cosignerSig.signature.signature : undefined,
     );
     adviceMap.insert(key, new FeltArray(values));
@@ -186,11 +234,11 @@ function buildCosignerAdviceMap(
   return adviceMap;
 }
 
-async function appendPsmAckAdvice(
-  psm: PsmHttpClient,
+async function appendGuardianAckAdvice(
+  guardian: GuardianHttpClient,
   delta: DeltaObject,
-  psmCommitmentHex: string,
-  psmPublicKey: string | undefined,
+  guardianCommitmentHex: string,
+  guardianPublicKey: string | undefined,
   defaultAckScheme: 'falcon' | 'ecdsa',
   txCommitmentHex: string,
   adviceMap: AdviceMap,
@@ -200,31 +248,31 @@ async function appendPsmAckAdvice(
     deltaPayload: delta.deltaPayload.txSummary,
   };
 
-  const pushResult = await psm.pushDelta(executionDelta);
+  const pushResult = await guardian.pushDelta(executionDelta);
   const ackSigHex = pushResult.ackSig;
   if (!ackSigHex) {
-    throw new Error('PSM did not return acknowledgment signature');
+    throw new Error('GUARDIAN did not return acknowledgment signature');
   }
 
-  const psmAckScheme: 'ecdsa' | 'falcon' =
+  const guardianAckScheme: 'ecdsa' | 'falcon' =
     (pushResult.ackScheme as 'ecdsa' | 'falcon') || defaultAckScheme;
-  const ackPubkey = pushResult.ackPubkey || psmPublicKey;
-  const normalizedPsmCommitment = normalizeHexWord(psmCommitmentHex);
+  const ackPubkey = pushResult.ackPubkey || guardianPublicKey;
+  const normalizedGuardianCommitment = normalizeHexWord(guardianCommitmentHex);
 
-  if (psmAckScheme === 'ecdsa' && ackPubkey) {
+  if (guardianAckScheme === 'ecdsa' && ackPubkey) {
     const derived = tryComputeEcdsaCommitmentHex(ackPubkey);
-    if (derived && derived !== normalizedPsmCommitment) {
-      throw new Error('PSM public key commitment mismatch');
+    if (derived && derived !== normalizedGuardianCommitment) {
+      throw new Error('GUARDIAN public key commitment mismatch');
     }
   }
 
-  const psmCommitment = Word.fromHex(normalizedPsmCommitment);
-  const ackSigBytes = signatureHexToBytes(ackSigHex, psmAckScheme);
+  const guardianCommitment = Word.fromHex(normalizedGuardianCommitment);
+  const ackSigBytes = signatureHexToBytes(ackSigHex, guardianAckScheme);
   const ackSignature = Signature.deserialize(ackSigBytes);
   const txCommitment = Word.fromHex(normalizeHexWord(txCommitmentHex));
-  const isAckEcdsa = psmAckScheme === 'ecdsa' && ackPubkey;
+  const isAckEcdsa = guardianAckScheme === 'ecdsa' && ackPubkey;
   const { key, values } = buildSignatureAdviceEntry(
-    psmCommitment,
+    guardianCommitment,
     txCommitment,
     ackSignature,
     isAckEcdsa ? ackPubkey : undefined,
@@ -255,15 +303,28 @@ async function buildFinalRequest(
       );
       return request;
     }
-    case 'switch_psm': {
-      if (!metadata.newPsmPubkey) {
+    case 'switch_guardian': {
+      if (!metadata.newGuardianPubkey) {
         throw new Error(
-          'Proposal missing newPsmPubkey. Was it created with createSwitchPsmProposal?',
+          'Proposal missing newGuardianPubkey. Was it created with createSwitchGuardianProposal?',
         );
       }
-      const { request } = await buildUpdatePsmTransactionRequest(
+      const { request } = await buildUpdateGuardianTransactionRequest(
         params.webClient,
-        metadata.newPsmPubkey,
+        metadata.newGuardianPubkey,
+        {
+          salt: normalizedSalt,
+          signatureAdviceMap: adviceMap,
+          signatureScheme: params.signatureScheme,
+        },
+      );
+      return request;
+    }
+    case 'update_procedure_threshold': {
+      const { request } = await buildUpdateProcedureThresholdTransactionRequest(
+        params.webClient,
+        metadata.targetProcedure,
+        metadata.targetThreshold,
         {
           salt: normalizedSalt,
           signatureAdviceMap: adviceMap,

package/src/multisig/proposal/parser.ts

@@ -1,8 +1,8 @@
 import type {
   DeltaObject,
   DeltaStatus,
-  ProposalMetadata as PsmProposalMetadata,
-} from '@openzeppelin/psm-client';
+  ProposalMetadata as GuardianProposalMetadata,
+} from '@openzeppelin/guardian-client';
 import type {
   ProposalMetadata,
   ProposalType,
@@ -11,8 +11,8 @@ import type {
   TransactionProposalStatus,
 } from '../../types.js';
 
-export function buildPsmMetadata(metadata: ProposalMetadata): PsmProposalMetadata {
-  const base: PsmProposalMetadata = {
+export function buildGuardianMetadata(metadata: ProposalMetadata): GuardianProposalMetadata {
+  const base: GuardianProposalMetadata = {
     proposalType: metadata.proposalType,
     description: metadata.description,
     salt: metadata.saltHex,
@@ -31,13 +31,13 @@ export function buildPsmMetadata(metadata: ProposalMetadata): PsmProposalMetadat
         faucetId: metadata.faucetId,
         amount: metadata.amount,
       };
-    case 'switch_psm':
+    case 'switch_guardian':
       return {
         ...base,
         targetThreshold: metadata.targetThreshold,
         signerCommitments: metadata.targetSignerCommitments,
-        newPsmPubkey: metadata.newPsmPubkey,
-        newPsmEndpoint: metadata.newPsmEndpoint,
+        newGuardianPubkey: metadata.newGuardianPubkey,
+        newGuardianEndpoint: metadata.newGuardianEndpoint,
       };
     case 'add_signer':
     case 'remove_signer':
@@ -54,46 +54,46 @@ export function buildPsmMetadata(metadata: ProposalMetadata): PsmProposalMetadat
   }
 }
 
-export function fromPsmMetadata(psm: PsmProposalMetadata): ProposalMetadata | undefined {
-  if (!psm.proposalType) return undefined;
+export function fromGuardianMetadata(guardian: GuardianProposalMetadata): ProposalMetadata | undefined {
+  if (!guardian.proposalType) return undefined;
 
   const base = {
-    description: psm.description ?? '',
-    saltHex: psm.salt,
+    description: guardian.description ?? '',
+    saltHex: guardian.salt,
   };
 
-  switch (psm.proposalType) {
+  switch (guardian.proposalType) {
     case 'p2id':
       return {
         ...base,
         proposalType: 'p2id',
-        recipientId: psm.recipientId ?? '',
-        faucetId: psm.faucetId ?? '',
-        amount: psm.amount ?? '0',
+        recipientId: guardian.recipientId ?? '',
+        faucetId: guardian.faucetId ?? '',
+        amount: guardian.amount ?? '0',
       };
     case 'consume_notes':
       return {
         ...base,
         proposalType: 'consume_notes',
-        noteIds: psm.noteIds ?? [],
+        noteIds: guardian.noteIds ?? [],
       };
-    case 'switch_psm':
+    case 'switch_guardian':
       return {
         ...base,
-        proposalType: 'switch_psm',
-        newPsmPubkey: psm.newPsmPubkey ?? '',
-        newPsmEndpoint: psm.newPsmEndpoint,
-        targetThreshold: psm.targetThreshold,
-        targetSignerCommitments: psm.signerCommitments,
+        proposalType: 'switch_guardian',
+        newGuardianPubkey: guardian.newGuardianPubkey ?? '',
+        newGuardianEndpoint: guardian.newGuardianEndpoint,
+        targetThreshold: guardian.targetThreshold,
+        targetSignerCommitments: guardian.signerCommitments,
       };
     case 'add_signer':
     case 'remove_signer':
     case 'change_threshold':
       return {
         ...base,
-        proposalType: psm.proposalType,
-        targetThreshold: psm.targetThreshold ?? 0,
-        targetSignerCommitments: psm.signerCommitments ?? [],
+        proposalType: guardian.proposalType,
+        targetThreshold: guardian.targetThreshold ?? 0,
+        targetSignerCommitments: guardian.signerCommitments ?? [],
       };
     default:
       return undefined;
@@ -178,7 +178,7 @@ export function resolveMetadata(
 ): ProposalMetadata | undefined {
   if (existingMetadata) return existingMetadata;
   if (!delta.deltaPayload.metadata) return undefined;
-  return fromPsmMetadata(delta.deltaPayload.metadata);
+  return fromGuardianMetadata(delta.deltaPayload.metadata);
 }
 
 export function signatureRequirementForProposal(

package/src/multisig/signing.ts

@@ -1,7 +1,7 @@
-import type { ProposalSignature, Signer } from '@openzeppelin/psm-client';
+import type { ProposalSignature, Signer } from '@openzeppelin/guardian-client';
 import type { SignatureScheme } from '../types.js';
 
-export function toPsmSignature(
+export function toGuardianSignature(
   scheme: SignatureScheme,
   signatureHex: string,
   publicKey?: string,
@@ -15,10 +15,10 @@ export function toPsmSignature(
   return { scheme: 'falcon', signature: signatureHex };
 }
 
-export async function buildPsmSignatureFromSigner(
+export async function buildGuardianSignatureFromSigner(
   signer: Signer,
   commitment: string,
 ): Promise<ProposalSignature> {
   const signatureHex = await signer.signCommitment(commitment);
-  return toPsmSignature(signer.scheme, signatureHex, signer.publicKey);
+  return toGuardianSignature(signer.scheme, signatureHex, signer.publicKey);
 }