@openzeppelin/miden-multisig-client 0.13.1 → 0.13.3

package/src/transaction/updateProcedureThreshold.ts

@@ -0,0 +1,97 @@
+import {
+  Felt,
+  FeltArray,
+  Rpo256,
+  TransactionRequest,
+  TransactionRequestBuilder,
+  TransactionScript,
+  WebClient,
+  Word,
+  Word as WordType,
+} from '@miden-sdk/miden-sdk';
+import {
+  MULTISIG_ECDSA_MASM,
+  MULTISIG_MASM,
+} from '../account/masm/auth.js';
+import { getProcedureRoot, type ProcedureName } from '../procedures.js';
+import { normalizeHexWord } from '../utils/encoding.js';
+import { randomWord } from '../utils/random.js';
+import type { SignatureOptions } from './options.js';
+import type { SignatureScheme } from '../types.js';
+
+function buildProcedureThresholdAdvice(
+  procedure: ProcedureName,
+  threshold: number,
+): { configHash: Word; payload: FeltArray } {
+  const procedureRoot = WordType.fromHex(normalizeHexWord(getProcedureRoot(procedure)));
+  const payload = new FeltArray([
+    ...procedureRoot.toFelts(),
+    new Felt(BigInt(threshold)),
+    new Felt(0n),
+    new Felt(0n),
+    new Felt(0n),
+  ]);
+  const configHash = Rpo256.hashElements(payload);
+  return { configHash, payload };
+}
+
+function buildUpdateProcedureThresholdScript(
+  webClient: WebClient,
+  procedure: ProcedureName,
+  threshold: number,
+  signatureScheme: SignatureScheme,
+): TransactionScript {
+  const libBuilder = webClient.createCodeBuilder();
+  const multisigMasm = signatureScheme === 'ecdsa' ? MULTISIG_ECDSA_MASM : MULTISIG_MASM;
+
+  const multisigLib = libBuilder.buildLibrary('auth::multisig', multisigMasm);
+  libBuilder.linkDynamicLibrary(multisigLib);
+  const procedureRoot = normalizeHexWord(getProcedureRoot(procedure));
+
+  const scriptSource = `
+use auth::multisig
+
+begin
+    push.${procedureRoot}
+    push.${threshold}
+    call.multisig::update_procedure_threshold
+    dropw
+    drop
+end
+  `;
+
+  return libBuilder.compileTxScript(scriptSource);
+}
+
+export async function buildUpdateProcedureThresholdTransactionRequest(
+  webClient: WebClient,
+  procedure: ProcedureName,
+  threshold: number,
+  options: SignatureOptions = {},
+): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }> {
+  const signatureScheme = options.signatureScheme ?? 'falcon';
+  const { configHash } = buildProcedureThresholdAdvice(procedure, threshold);
+
+  const script = buildUpdateProcedureThresholdScript(
+    webClient,
+    procedure,
+    threshold,
+    signatureScheme,
+  );
+  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
+  const authSalt = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  let txBuilder = new TransactionRequestBuilder();
+  txBuilder = txBuilder.withCustomScript(script);
+  txBuilder = txBuilder.withAuthArg(authSalt);
+
+  if (options.signatureAdviceMap) {
+    txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
+  }
+
+  return {
+    request: txBuilder.build(),
+    salt: WordType.fromHex(normalizeHexWord(authSaltHex)),
+    configHash,
+  };
+}

package/src/transaction/updateSigners.ts

@@ -10,10 +10,14 @@ import {
   Word,
   Word as WordType,
 } from '@miden-sdk/miden-sdk';
-import { MULTISIG_ECDSA_MASM, MULTISIG_MASM, PSM_ECDSA_MASM, PSM_MASM } from '../account/masm.js';
+import {
+  MULTISIG_ECDSA_MASM,
+  MULTISIG_MASM,
+} from '../account/masm/auth.js';
 import { normalizeHexWord } from '../utils/encoding.js';
 import { randomWord } from '../utils/random.js';
 import type { SignatureOptions } from './options.js';
+import type { SignatureScheme } from '../types.js';
 
 function buildMultisigConfigAdvice(
   threshold: number,
@@ -35,31 +39,14 @@ function buildMultisigConfigAdvice(
   return { configHash, payload };
 }
 
-function buildUpdateSignersFalconScript(webClient: WebClient): TransactionScript {
-  const libBuilder = webClient.createCodeBuilder();
-  const psmLib = libBuilder.buildLibrary('openzeppelin::psm', PSM_MASM);
-  libBuilder.linkStaticLibrary(psmLib);
-
-  const multisigLib = libBuilder.buildLibrary('auth::multisig', MULTISIG_MASM);
-  libBuilder.linkDynamicLibrary(multisigLib);
-
-  const scriptSource = `
-use auth::multisig
-
-begin
-    call.multisig::update_signers_and_threshold
-end
-  `;
-
-  return libBuilder.compileTxScript(scriptSource);
-}
-
-function buildUpdateSignersEcdsaScript(webClient: WebClient): TransactionScript {
+function buildUpdateSignersScript(
+  webClient: WebClient,
+  signatureScheme: SignatureScheme,
+): TransactionScript {
   const libBuilder = webClient.createCodeBuilder();
-  const psmLib = libBuilder.buildLibrary('openzeppelin::psm_ecdsa', PSM_ECDSA_MASM);
-  libBuilder.linkStaticLibrary(psmLib);
+  const multisigMasm = signatureScheme === 'ecdsa' ? MULTISIG_ECDSA_MASM : MULTISIG_MASM;
 
-  const multisigLib = libBuilder.buildLibrary('auth::multisig', MULTISIG_ECDSA_MASM);
+  const multisigLib = libBuilder.buildLibrary('auth::multisig', multisigMasm);
   libBuilder.linkDynamicLibrary(multisigLib);
 
   const scriptSource = `
@@ -89,9 +76,7 @@ export async function buildUpdateSignersTransactionRequest(
   const advice = new AdviceMap();
   advice.insert(configHashForAdvice, payload);
 
-  const script = signatureScheme === 'ecdsa'
-    ? buildUpdateSignersEcdsaScript(webClient)
-    : buildUpdateSignersFalconScript(webClient);
+  const script = buildUpdateSignersScript(webClient, signatureScheme);
 
   const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
 

package/src/transaction.ts

@@ -6,9 +6,11 @@ export {
   buildP2idTransactionRequest,
 } from './transaction/p2id.js';
 export {
-  buildUpdatePsmTransactionRequest,
-} from './transaction/updatePsm.js';
+  buildUpdateGuardianTransactionRequest,
+} from './transaction/updateGuardian.js';
+export {
+  buildUpdateProcedureThresholdTransactionRequest,
+} from './transaction/updateProcedureThreshold.js';
 export {
   buildUpdateSignersTransactionRequest,
 } from './transaction/updateSigners.js';
-

package/src/types/proposal.ts

@@ -1,21 +1,32 @@
-import type { ProposalType as PsmProposalType, SignatureScheme } from '@openzeppelin/psm-client';
-export type ProposalType = Exclude<PsmProposalType, 'custom'>;
+import type {
+  ProposalSignature,
+  ProposalType as GuardianProposalType,
+  SignatureScheme,
+} from '@openzeppelin/guardian-client';
+import type { ProcedureName } from '../procedures.js';
+
+export type ProposalType = Exclude<GuardianProposalType, 'custom'>;
+
+export type ProposalStatus = 'pending' | 'ready' | 'finalized';
 
 export type TransactionProposalStatus =
   | { type: 'pending'; signaturesCollected: number; signaturesRequired: number; signers: string[] }
   | { type: 'ready' }
   | { type: 'finalized' };
 
-export interface TransactionProposalSignature {
+export interface ProposalSignatureEntry {
   signerId: string;
-  signature: { scheme: 'falcon' | 'ecdsa'; signature: string; publicKey?: string };
+  signature: ProposalSignature;
   timestamp: string;
 }
 
+export type TransactionProposalSignature = ProposalSignatureEntry;
+
 interface BaseProposalMetadata {
   proposalType: ProposalType;
   description: string;
   saltHex?: string;
+  requiredSignatures?: number;
 }
 
 export interface UpdateSignersProposalMetadata extends BaseProposalMetadata {
@@ -24,14 +35,20 @@ export interface UpdateSignersProposalMetadata extends BaseProposalMetadata {
   targetSignerCommitments: string[];
 }
 
-export interface SwitchPsmProposalMetadata extends BaseProposalMetadata {
-  proposalType: 'switch_psm';
-  newPsmPubkey: string;
-  newPsmEndpoint?: string;
+export interface SwitchGuardianProposalMetadata extends BaseProposalMetadata {
+  proposalType: 'switch_guardian';
+  newGuardianPubkey: string;
+  newGuardianEndpoint?: string;
   targetThreshold?: number;
   targetSignerCommitments?: string[];
 }
 
+export interface UpdateProcedureThresholdProposalMetadata extends BaseProposalMetadata {
+  proposalType: 'update_procedure_threshold';
+  targetProcedure: ProcedureName;
+  targetThreshold: number;
+}
+
 export interface ConsumeNotesProposalMetadata extends BaseProposalMetadata {
   proposalType: 'consume_notes';
   noteIds: string[];
@@ -50,11 +67,22 @@ export interface UnknownProposalMetadata extends BaseProposalMetadata {
 
 export type ProposalMetadata =
   | UpdateSignersProposalMetadata
-  | SwitchPsmProposalMetadata
+  | SwitchGuardianProposalMetadata
+  | UpdateProcedureThresholdProposalMetadata
   | ConsumeNotesProposalMetadata
   | P2IdProposalMetadata
   | UnknownProposalMetadata;
 
+export interface Proposal {
+  id: string;
+  accountId: string;
+  nonce: number;
+  status: ProposalStatus;
+  txSummary: string;
+  signatures: ProposalSignatureEntry[];
+  metadata: ProposalMetadata;
+}
+
 export interface TransactionProposal {
   id: string;
   commitment: string;
@@ -66,7 +94,7 @@ export interface TransactionProposal {
   metadata: ProposalMetadata;
 }
 
-export interface ExportedTransactionProposal {
+export interface ExportedProposal {
   accountId: string;
   nonce: number;
   commitment: string;
@@ -74,11 +102,15 @@ export interface ExportedTransactionProposal {
   signatures: Array<{
     commitment: string;
     signatureHex: string;
+    scheme?: SignatureScheme;
+    publicKey?: string;
     timestamp?: string;
   }>;
-  metadata?: ProposalMetadata;
+  metadata: ProposalMetadata;
 }
 
+export type ExportedTransactionProposal = ExportedProposal;
+
 export interface SignTransactionProposalParams {
   commitment: string;
   signature: string;

package/src/types.ts

@@ -1,9 +1,9 @@
 import type { Account } from '@miden-sdk/miden-sdk';
-import type { SignatureScheme } from '@openzeppelin/psm-client';
+import type { SignatureScheme } from '@openzeppelin/guardian-client';
 import type { ProcedureName } from './procedures.js';
-import type { TransactionProposal } from './types/proposal.js';
 import type { AccountState } from './multisig.js';
 import type { DetectedMultisigConfig } from './inspector.js';
+import type { TransactionProposal } from './types/proposal.js';
 
 export type {
   Signer,
@@ -23,16 +23,20 @@ export type {
   DeltaProposalResponse,
   ProposalsResponse,
   SignProposalRequest,
-} from '@openzeppelin/psm-client';
+} from '@openzeppelin/guardian-client';
 
 export type {
-  TransactionProposal,
-  TransactionProposalStatus,
-  TransactionProposalSignature,
+  ExportedProposal,
   ExportedTransactionProposal,
-  SignTransactionProposalParams,
+  Proposal,
   ProposalMetadata,
+  ProposalSignatureEntry,
+  ProposalStatus,
   ProposalType,
+  SignTransactionProposalParams,
+  TransactionProposal,
+  TransactionProposalSignature,
+  TransactionProposalStatus,
 } from './types/proposal.js';
 
 export interface SyncResult {
@@ -54,20 +58,33 @@ export interface MultisigAccountState {
   cosignerCommitments: string[];
 }
 
+/**
+ * Per-procedure threshold override.
+ *
+ * @example
+ * ```typescript
+ * const thresholds: ProcedureThreshold[] = [
+ *   { procedure: 'receive_asset', threshold: 1 },
+ *   { procedure: 'update_signers', threshold: 3 },
+ * ];
+ * ```
+ */
 export interface ProcedureThreshold {
   procedure: ProcedureName;
+  /** Threshold for this procedure (1 to numSigners) */
   threshold: number;
 }
 
 export interface MultisigConfig {
   threshold: number;
   signerCommitments: string[];
-  psmCommitment: string;
-  psmPublicKey?: string;
-  psmEnabled?: boolean;
+  guardianCommitment: string;
+  guardianPublicKey?: string;
+  guardianEnabled?: boolean;
   storageMode?: 'private' | 'public';
   procedureThresholds?: ProcedureThreshold[];
   signatureScheme?: SignatureScheme;
+  seed?: Uint8Array
 }
 
 export interface CreateAccountResult {
@@ -78,7 +95,8 @@ export interface CreateAccountResult {
 export type TransactionType =
   | { type: 'p2id'; recipient: string; faucetId: string; amount: bigint }
   | { type: 'consumeNotes'; noteIds: string[] }
-  | { type: 'updateSigners'; newThreshold: number; newSignerCommitments: string[] };
+  | { type: 'updateSigners'; newThreshold: number; newSignerCommitments: string[] }
+  | { type: 'updateProcedureThreshold'; procedure: ProcedureName; threshold: number };
 
 export interface NoteAsset {
   faucetId: string;

package/src/utils/digest.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { AuthDigest } from './digest.js';
+
+vi.mock('@miden-sdk/miden-sdk', () => ({
+  AccountId: {
+    fromHex: vi.fn(() => ({
+      prefix: () => ({ label: 'prefix' }),
+      suffix: () => ({ label: 'suffix' }),
+    })),
+  },
+  Felt: vi.fn().mockImplementation((value: bigint) => ({ value })),
+  FeltArray: vi.fn().mockImplementation((elements: unknown[]) => elements),
+  Word: {
+    fromHex: vi.fn((hex: string) => ({
+      toHex: () => hex,
+      toFelts: () => [],
+    })),
+  },
+  Rpo256: {
+    hashElements: vi.fn().mockReturnValue({
+      toHex: () => '0x' + 'aa'.repeat(32),
+      toFelts: () => [],
+    }),
+  },
+}));
+
+describe('AuthDigest', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('uses the legacy 4-felt digest for account auth', async () => {
+    const { FeltArray, Rpo256 } = await import('@miden-sdk/miden-sdk');
+
+    AuthDigest.fromAccountIdWithTimestamp('0x' + 'ab'.repeat(15), 1700000000);
+
+    expect(FeltArray).toHaveBeenCalledWith([
+      { label: 'prefix' },
+      { label: 'suffix' },
+      { value: 1700000000n },
+      { value: 0n },
+    ]);
+    expect(Rpo256.hashElements).toHaveBeenCalledTimes(1);
+  });
+
+  it('includes the request payload hash for request-bound auth', async () => {
+    const { Rpo256 } = await import('@miden-sdk/miden-sdk');
+
+    AuthDigest.fromRequest('0x' + 'ab'.repeat(15), 1700000000, {
+      toBytes: () => new Uint8Array([1, 2, 3, 4]),
+    } as never);
+
+    expect(Rpo256.hashElements).toHaveBeenCalledTimes(2);
+  });
+});

package/src/utils/digest.ts

@@ -1,3 +1,4 @@
+import type { RequestAuthPayload } from '@openzeppelin/guardian-client';
 import { AccountId, Felt, FeltArray, Rpo256, Word } from '@miden-sdk/miden-sdk';
 
 export class AuthDigest {
@@ -11,7 +12,35 @@ export class AuthDigest {
       prefix,
       suffix,
       new Felt(BigInt(timestamp)),
-      new Felt(BigInt(0)),
+      new Felt(0n),
+    ]);
+
+    return Rpo256.hashElements(feltArray);
+  }
+
+  static fromRequest(accountId: string, timestamp: number, requestPayload: RequestAuthPayload): Word {
+    return AuthDigest.fromAccountIdTimestampAndPayloadWord(
+      accountId,
+      timestamp,
+      AuthDigest.payloadWordFromBytes(requestPayload.toBytes()),
+    );
+  }
+
+  private static fromAccountIdTimestampAndPayloadWord(
+    accountId: string,
+    timestamp: number,
+    payloadWord: Word,
+  ): Word {
+    const paddedHex = accountId.startsWith('0x') ? accountId : `0x${accountId}`;
+    const parsedAccountId = AccountId.fromHex(paddedHex);
+    const prefix = parsedAccountId.prefix();
+    const suffix = parsedAccountId.suffix();
+
+    const feltArray = new FeltArray([
+      prefix,
+      suffix,
+      new Felt(BigInt(timestamp)),
+      ...payloadWord.toFelts(),
     ]);
 
     return Rpo256.hashElements(feltArray);
@@ -22,4 +51,25 @@ export class AuthDigest {
     const cleanHex = paddedHex.slice(2).padStart(64, '0');
     return Word.fromHex(`0x${cleanHex}`);
   }
+
+  private static emptyPayloadWord(): Word {
+    return Word.fromHex(`0x${'0'.repeat(64)}`);
+  }
+
+  private static payloadWordFromBytes(bytes: Uint8Array): Word {
+    if (bytes.length === 0) {
+      return AuthDigest.emptyPayloadWord();
+    }
+
+    const payloadElements: Felt[] = [];
+    for (let i = 0; i < bytes.length; i += 8) {
+      let packed = 0n;
+      for (let j = 0; j < 8 && i + j < bytes.length; j += 1) {
+        packed |= BigInt(bytes[i + j]) << (8n * BigInt(j));
+      }
+      payloadElements.push(new Felt(packed));
+    }
+
+    return Rpo256.hashElements(new FeltArray(payloadElements));
+  }
 }

package/src/utils/signature.ts

@@ -1,9 +1,12 @@
 import { AdviceMap, Felt, FeltArray, Rpo256, Signature, Word } from '@miden-sdk/miden-sdk';
 import * as midenSdk from '@miden-sdk/miden-sdk';
 import { hexToBytes, normalizeHexWord } from './encoding.js';
-import type { SignatureScheme } from '../types.js';
+import type { ProposalSignatureEntry, SignatureScheme } from '../types.js';
 
-export function signatureHexToBytes(hex: string, scheme: SignatureScheme = 'falcon'): Uint8Array {
+export function signatureHexToBytes(
+  hex: string,
+  scheme: SignatureScheme = 'falcon',
+): Uint8Array {
   const sigBytes = hexToBytes(hex);
   const withPrefix = new Uint8Array(sigBytes.length + 1);
   withPrefix[0] = scheme === 'ecdsa' ? 1 : 0;
@@ -15,7 +18,7 @@ function bytesToPackedU32Felts(bytes: Uint8Array): Felt[] {
   const felts: Felt[] = [];
   for (let i = 0; i < bytes.length; i += 4) {
     let packed = 0;
-    for (let j = 0; j < 4 && i + j < bytes.length; j++) {
+    for (let j = 0; j < 4 && i + j < bytes.length; j += 1) {
       packed |= bytes[i + j] << (j * 8);
     }
     felts.push(new Felt(BigInt(packed >>> 0)));
@@ -87,7 +90,7 @@ export function verifyEcdsaCommitment(
     const packedU32Values: number[] = [];
     for (let i = 0; i < bytes.length; i += 4) {
       let packed = 0;
-      for (let j = 0; j < 4 && i + j < bytes.length; j++) {
+      for (let j = 0; j < 4 && i + j < bytes.length; j += 1) {
         packed |= bytes[i + j] << (j * 8);
       }
       packedU32Values.push(packed >>> 0);
@@ -101,19 +104,22 @@ export function verifyEcdsaCommitment(
     return {
       match: computedHex === expectedNorm,
       computedHex,
-      packedFelts: packedU32Values.map(v => v.toString()),
+      packedFelts: packedU32Values.map((value) => value.toString()),
     };
-  } catch (e) {
+  } catch (error) {
     return {
       match: false,
-      computedHex: `ERROR: ${e}`,
+      computedHex: `ERROR: ${error}`,
       packedFelts: [],
-      error: String(e),
+      error: String(error),
     };
   }
 }
 
-export function mergeSignatureAdviceMaps(advice: AdviceMap, entries: Array<{ key: Word; values: Felt[] }>): AdviceMap {
+export function mergeSignatureAdviceMaps(
+  advice: AdviceMap,
+  entries: Array<{ key: Word; values: Felt[] }>,
+): AdviceMap {
   for (const entry of entries) {
     advice.insert(entry.key, new FeltArray(entry.values));
   }
@@ -123,3 +129,35 @@ export function mergeSignatureAdviceMaps(advice: AdviceMap, entries: Array<{ key
 export function toWord(hex: string): Word {
   return Word.fromHex(normalizeHexWord(hex));
 }
+
+export function normalizeSignerCommitment(signerId: string): string {
+  const hex = signerId.startsWith('0x') || signerId.startsWith('0X')
+    ? signerId.slice(2)
+    : signerId;
+
+  if (hex.length !== 64 || !/^[0-9a-fA-F]+$/.test(hex)) {
+    throw new Error(`expected signerId as 32-byte hex, got ${signerId}`);
+  }
+
+  return normalizeHexWord(signerId);
+}
+
+export function canonicalizeSignature(
+  signature: ProposalSignatureEntry,
+  signerCommitments: Set<string>,
+): ProposalSignatureEntry {
+  try {
+    const signerId = normalizeSignerCommitment(signature.signerId);
+    if (!signerCommitments.has(signerId)) {
+      throw new Error(`signer ${signerId} is not part of this multisig`);
+    }
+
+    return {
+      ...signature,
+      signerId,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(message);
+  }
+}

package/src/utils/word.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { wordElementToBigInt, wordToHex, wordToBytes } from './word.js';
+import { wordElementToBigInt, wordToHex } from './word.js';
 import { Word } from '@miden-sdk/miden-sdk';
 
 // Mock the Miden SDK Word class
@@ -61,58 +61,4 @@ describe('word utilities', () => {
       expect(hex).toBe(originalHex);
     });
   });
-
-  describe('wordToBytes', () => {
-    it('should convert a word with known felt values to LE bytes', () => {
-      const word = {
-        toFelts: () => [
-          { asInt: () => 1n },
-          { asInt: () => 2n },
-          { asInt: () => 3n },
-          { asInt: () => 4n },
-        ],
-      };
-      const bytes = wordToBytes(word);
-      expect(bytes.length).toBe(32);
-      expect(bytes[0]).toBe(1);
-      expect(bytes[1]).toBe(0);
-      expect(bytes[8]).toBe(2);
-      expect(bytes[16]).toBe(3);
-      expect(bytes[24]).toBe(4);
-    });
-
-    it('should encode felts in little-endian order', () => {
-      const word = {
-        toFelts: () => [
-          { asInt: () => 0x0102030405060708n },
-          { asInt: () => 0n },
-          { asInt: () => 0n },
-          { asInt: () => 0n },
-        ],
-      };
-      const bytes = wordToBytes(word);
-      expect(bytes[0]).toBe(0x08);
-      expect(bytes[1]).toBe(0x07);
-      expect(bytes[2]).toBe(0x06);
-      expect(bytes[3]).toBe(0x05);
-      expect(bytes[4]).toBe(0x04);
-      expect(bytes[5]).toBe(0x03);
-      expect(bytes[6]).toBe(0x02);
-      expect(bytes[7]).toBe(0x01);
-    });
-
-    it('should handle zero felts', () => {
-      const word = {
-        toFelts: () => [
-          { asInt: () => 0n },
-          { asInt: () => 0n },
-          { asInt: () => 0n },
-          { asInt: () => 0n },
-        ],
-      };
-      const bytes = wordToBytes(word);
-      expect(bytes.length).toBe(32);
-      expect(bytes.every((b) => b === 0)).toBe(true);
-    });
-  });
 });