@openzeppelin/miden-multisig-client 0.12.6

package/src/procedures.ts

@@ -0,0 +1,72 @@
+/**
+ * known procedure roots for multisig accounts.
+ *
+ * IMPORTANT: These values are extracted from the TypeScript SDK's compiled MASM output,
+ * NOT from the Rust crate. The SDK may compile MASM differently, resulting in different
+ * procedure roots. Use the debug output from builder.ts to update these values.
+ */
+
+/**
+ * Static mapping of procedure names to their deterministic roots.
+ *
+ * Component ordering: Multisig (auth) -> PSM -> BasicWallet
+ */
+export const PROCEDURE_ROOTS = {
+  // Multisig component procedures
+  /** Update signer list and threshold configuration */
+  update_signers: '0x53d0ad381a193de0cf6af3730141e498274103dfc3b8c8e7367bd49d4a66c72b',
+  /** Authenticate transaction with multisig (Falcon512) */
+  auth_tx: '0x474c613b38001cc36d68557e9d881495d6a461a9027033445c7672c586509026',
+
+  // PSM component procedures
+  /** Update PSM public key */
+  update_psm: '0xb103236807e5bf09c27efc2c5287ca8b03ab9efc1d852b62ebd31f5f1927ec26',
+  /** Verify PSM signature */
+  verify_psm: '0x30727fc23c6105a678fea8b4c1920f35fa85c03f16a0cf98372c8f56701f8a87',
+
+  // BasicWallet procedures
+  /** Send assets from account (move_asset_to_note) */
+  send_asset: '0x0e406b067ed2bcd7de745ca6517f519fd1a9be245f913347ac673ca1db30c1d6',
+  /** Receive assets into account */
+  receive_asset: '0x6f4bdbdc4b13d7ed933d590d88ac9dfb98020c9e917697845b5e169395b76a01',
+} as const;
+
+/**
+ * Valid procedure names that can be used for threshold overrides.
+ */
+export type ProcedureName = keyof typeof PROCEDURE_ROOTS;
+
+/**
+ * Get the procedure root for a given procedure name.
+ *
+ * @param name - The procedure name
+ * @returns The procedure root as a hex string
+ *
+ * @example
+ * ```typescript
+ * const root = getProcedureRoot('receive_asset');
+ * // '0x6f4bdbdc4b13d7ed933d590d88ac9dfb98020c9e917697845b5e169395b76a01'
+ * ```
+ */
+export function getProcedureRoot(name: ProcedureName): string {
+  return PROCEDURE_ROOTS[name];
+}
+
+/**
+ * Check if a string is a valid procedure name.
+ *
+ * @param name - The string to check
+ * @returns true if the string is a valid procedure name
+ */
+export function isProcedureName(name: string): name is ProcedureName {
+  return name in PROCEDURE_ROOTS;
+}
+
+/**
+ * Get all available procedure names.
+ *
+ * @returns Array of all valid procedure names
+ */
+export function getProcedureNames(): ProcedureName[] {
+  return Object.keys(PROCEDURE_ROOTS) as ProcedureName[];
+}

package/src/signer.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { FalconSigner } from './signer.js';
+
+// Mock the Miden SDK
+vi.mock('@demox-labs/miden-sdk', () => {
+  const mockSignature = {
+    serialize: () => new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]),
+  };
+
+  const mockPublicKey = {
+    toCommitment: () => ({
+      toHex: () => '0x' + 'a'.repeat(64),
+    }),
+    serialize: () => new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]),
+  };
+
+  const mockSecretKey = {
+    publicKey: vi.fn().mockReturnValue(mockPublicKey),
+    sign: vi.fn().mockReturnValue(mockSignature),
+  };
+
+  return {
+    SecretKey: {
+      rpoFalconWithRNG: vi.fn().mockReturnValue(mockSecretKey),
+    },
+    Word: {
+      fromHex: vi.fn((hex: string) => ({
+        toHex: () => hex,
+        toFelts: () => [1, 2, 3, 4],
+      })),
+    },
+    AccountId: {
+      fromHex: vi.fn((hex: string) => ({
+        prefix: () => ({ asInt: () => BigInt(1) }),
+        suffix: () => ({ asInt: () => BigInt(2) }),
+      })),
+    },
+    Felt: vi.fn().mockImplementation((v: bigint) => ({ value: v })),
+    FeltArray: vi.fn().mockImplementation((arr: any[]) => arr),
+    Rpo256: {
+      hashElements: vi.fn().mockReturnValue({
+        toHex: () => '0x' + 'b'.repeat(64),
+      }),
+    },
+  };
+});
+
+describe('FalconSigner', () => {
+  let mockSecretKey: any;
+  let signer: FalconSigner;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    const { SecretKey } = await import('@demox-labs/miden-sdk');
+    mockSecretKey = SecretKey.rpoFalconWithRNG(new Uint8Array(32));
+    signer = new FalconSigner(mockSecretKey);
+  });
+
+  describe('constructor', () => {
+    it('extracts commitment from public key', () => {
+      expect(signer.commitment).toBe('0x' + 'a'.repeat(64));
+    });
+
+    it('extracts public key without first byte', () => {
+      // Public key serialized is [0, 1, 2, ...15], slice(1) removes first byte
+      expect(signer.publicKey).toBe('0x0102030405060708090a0b0c0d0e0f');
+    });
+
+    it('calls publicKey method on secret key', () => {
+      expect(mockSecretKey.publicKey).toHaveBeenCalled();
+    });
+  });
+
+  describe('signAccountIdWithTimestamp', () => {
+    it('handles account ID with 0x prefix', () => {
+      const signature = signer.signAccountIdWithTimestamp('0x' + 'a'.repeat(30), 1700000000);
+      expect(signature).toMatch(/^0x[a-f0-9]+$/);
+    });
+
+    it('handles account ID without 0x prefix', () => {
+      const signature = signer.signAccountIdWithTimestamp('a'.repeat(30), 1700000000);
+      expect(signature).toMatch(/^0x[a-f0-9]+$/);
+    });
+
+    it('calls sign method with hashed digest', () => {
+      signer.signAccountIdWithTimestamp('0x' + 'a'.repeat(30), 1700000000);
+      expect(mockSecretKey.sign).toHaveBeenCalled();
+    });
+
+    it('returns signature without first byte', () => {
+      // Signature serialized is [0, 1, 2, ...9], slice(1) returns [1, 2, ...9]
+      const signature = signer.signAccountIdWithTimestamp('0x' + 'a'.repeat(30), 1700000000);
+      expect(signature).toBe('0x010203040506070809');
+    });
+
+    it('includes timestamp in signed payload', async () => {
+      const { Felt, FeltArray } = await import('@demox-labs/miden-sdk');
+      signer.signAccountIdWithTimestamp('0x' + 'a'.repeat(30), 1700000000);
+      // Verify FeltArray was called with timestamp in the third position
+      expect(FeltArray).toHaveBeenCalledWith(expect.arrayContaining([
+        expect.anything(), // prefix
+        expect.anything(), // suffix
+        expect.anything(), // timestamp
+        expect.anything(), // zero padding
+      ]));
+    });
+  });
+
+  describe('signCommitment', () => {
+    it('handles commitment with 0x prefix', () => {
+      const signature = signer.signCommitment('0x' + 'c'.repeat(64));
+      expect(signature).toMatch(/^0x[a-f0-9]+$/);
+    });
+
+    it('handles commitment without 0x prefix', () => {
+      const signature = signer.signCommitment('c'.repeat(64));
+      expect(signature).toMatch(/^0x[a-f0-9]+$/);
+    });
+
+    it('pads short commitment hex to 64 characters', () => {
+      const signature = signer.signCommitment('abc');
+      expect(signature).toMatch(/^0x[a-f0-9]+$/);
+    });
+
+    it('calls sign method with word from hex', () => {
+      signer.signCommitment('0x' + 'c'.repeat(64));
+      expect(mockSecretKey.sign).toHaveBeenCalled();
+    });
+
+    it('returns signature without first byte', () => {
+      const signature = signer.signCommitment('0x' + 'c'.repeat(64));
+      expect(signature).toBe('0x010203040506070809');
+    });
+  });
+});

package/src/signer.ts

@@ -0,0 +1,75 @@
+/**
+ * Falcon Signer implementation for PSM client authentication.
+ *
+ * This implements the Signer interface using the Miden SDK's SecretKey
+ * for Falcon signatures.
+ */
+
+import { SecretKey, Word, AccountId, Felt, FeltArray, Rpo256 } from '@demox-labs/miden-sdk';
+import type { Signer } from './types.js';
+import { bytesToHex } from './utils/encoding.js';
+
+/**
+ * A Falcon signer that implements the Signer interface.
+ *
+ * @example
+ * ```typescript
+ * const secretKey = SecretKey.rpoFalconWithRNG(seed);
+ * const signer = new FalconSigner(secretKey);
+ * console.log(signer.commitment);
+ * ```
+ */
+export class FalconSigner implements Signer {
+  readonly commitment: string;
+  readonly publicKey: string;
+  private readonly secretKey: SecretKey;
+
+  constructor(secretKey: SecretKey) {
+    this.secretKey = secretKey;
+    const pubKey = secretKey.publicKey();
+    this.commitment = pubKey.toCommitment().toHex();
+    const serialized = pubKey.serialize();
+    const falconPubKey = serialized.slice(1);
+    this.publicKey = bytesToHex(falconPubKey);
+  }
+
+  /**
+   * Signs an account ID with a timestamp.
+   * @param accountId - The account ID to sign
+   * @param timestamp - Unix timestamp in milliseconds (use Date.now())
+   * @returns Hex-encoded Falcon signature
+   */
+  signAccountIdWithTimestamp(accountId: string, timestamp: number): string {
+    // Parse the account ID from hex
+    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)),
+      new Felt(BigInt(0)),
+    ]);
+
+    const digest = Rpo256.hashElements(feltArray);
+    const signature = this.secretKey.sign(digest);
+    const signatureBytes = signature.serialize();
+    const falconSignature = signatureBytes.slice(1);
+    return bytesToHex(falconSignature);
+  }
+
+  /**
+   * Signs a commitment/word for proposal signing.
+   */
+  signCommitment(commitmentHex: string): string {
+    const paddedHex = commitmentHex.startsWith('0x') ? commitmentHex : `0x${commitmentHex}`;
+    const cleanHex = paddedHex.slice(2).padStart(64, '0');
+    const word = Word.fromHex(`0x${cleanHex}`);
+    const signature = this.secretKey.sign(word);
+    const signatureBytes = signature.serialize();
+    const falconSignature = signatureBytes.slice(1);
+    return bytesToHex(falconSignature);
+  }
+}

package/src/transaction/consumeNotes.ts

@@ -0,0 +1,41 @@
+import type { TransactionRequest, Word } from '@demox-labs/miden-sdk';
+import { NoteId, NoteIdAndArgs, NoteIdAndArgsArray, TransactionRequestBuilder, Word as WordType } from '@demox-labs/miden-sdk';
+import { randomWord } from '../utils/random.js';
+import { normalizeHexWord } from '../utils/encoding.js';
+import type { SignatureOptions } from './options.js';
+
+export function buildConsumeNotesTransactionRequest(
+  noteIds: string[],
+  options: SignatureOptions = {},
+): { request: TransactionRequest; salt: Word } {
+  if (noteIds.length === 0) {
+    throw new Error('At least one note ID is required');
+  }
+
+  const noteIdAndArgsArray = new NoteIdAndArgsArray();
+  for (const noteIdHex of noteIds) {
+    const noteId = NoteId.fromHex(noteIdHex);
+    const noteIdAndArgs = new NoteIdAndArgs(noteId, null);
+    noteIdAndArgsArray.push(noteIdAndArgs);
+  }
+
+  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
+
+  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  let txBuilder = new TransactionRequestBuilder();
+  txBuilder = txBuilder.withAuthenticatedInputNotes(noteIdAndArgsArray);
+  txBuilder = txBuilder.withAuthArg(authSaltForBuilder);
+
+  if (options.signatureAdviceMap) {
+    txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
+  }
+
+  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  return {
+    request: txBuilder.build(),
+    salt: authSaltForReturn,
+  };
+}
+

package/src/transaction/index.ts

@@ -0,0 +1,7 @@
+export { executeForSummary } from './summary.js';
+export { buildUpdateSignersTransactionRequest } from './updateSigners.js';
+export { buildUpdatePsmTransactionRequest } from './updatePsm.js';
+export { buildConsumeNotesTransactionRequest } from './consumeNotes.js';
+export { buildP2idTransactionRequest } from './p2id.js';
+export type { SignatureOptions } from './options.js';
+

package/src/transaction/options.ts

@@ -0,0 +1,7 @@
+import type { AdviceMap, Word } from '@demox-labs/miden-sdk';
+
+export interface SignatureOptions {
+  salt?: Word;
+  signatureAdviceMap?: AdviceMap;
+}
+

package/src/transaction/p2id.ts

@@ -0,0 +1,105 @@
+import type { TransactionRequest, Word } from '@demox-labs/miden-sdk';
+import {
+  AccountId,
+  Felt,
+  FeltArray,
+  FungibleAsset,
+  MidenArrays,
+  Note,
+  NoteAssets,
+  NoteExecutionHint,
+  NoteInputs,
+  NoteMetadata,
+  NoteRecipient,
+  NoteScript,
+  NoteTag,
+  NoteType,
+  OutputNote,
+  Rpo256,
+  TransactionRequestBuilder,
+  Word as WordType,
+} from '@demox-labs/miden-sdk';
+import { randomWord } from '../utils/random.js';
+import { normalizeHexWord } from '../utils/encoding.js';
+import type { SignatureOptions } from './options.js';
+
+function buildP2idNote(
+  sender: AccountId,
+  recipient: AccountId,
+  noteAssets: NoteAssets,
+  noteType: NoteType,
+  aux: Felt,
+  saltHex: string,
+): Note {
+  const salt = WordType.fromHex(normalizeHexWord(saltHex));
+  const serialNum = Rpo256.hashElements(new FeltArray([
+    ...salt.toFelts(),
+    new Felt(0n),
+  ]));
+
+  const noteScript = NoteScript.p2id();
+  const noteInputs = new NoteInputs(new FeltArray([
+    recipient.suffix(),
+    recipient.prefix(),
+  ]));
+
+  const noteRecipient = new NoteRecipient(serialNum, noteScript, noteInputs);
+  const noteTag = NoteTag.fromAccountId(recipient);
+
+  const noteMetadata = new NoteMetadata(
+    sender,
+    noteType,
+    noteTag,
+    NoteExecutionHint.always(),
+    aux,
+  );
+
+  return new Note(noteAssets, noteMetadata, noteRecipient);
+}
+
+export function buildP2idTransactionRequest(
+  senderId: string,
+  recipientId: string,
+  faucetId: string,
+  amount: bigint,
+  options: SignatureOptions = {},
+): { request: TransactionRequest; salt: Word } {
+  const sender = AccountId.fromHex(senderId);
+  const recipient = AccountId.fromHex(recipientId);
+  const faucet = AccountId.fromHex(faucetId);
+
+  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
+
+  const asset = new FungibleAsset(faucet, amount);
+  const noteAssets = new NoteAssets([asset]);
+
+  const note = buildP2idNote(
+    sender,
+    recipient,
+    noteAssets,
+    NoteType.Public,
+    new Felt(0n),
+    authSaltHex,
+  );
+
+  const outputNote = OutputNote.full(note);
+  const outputNotes = new MidenArrays.OutputNoteArray([outputNote]);
+
+  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  let txBuilder = new TransactionRequestBuilder();
+  txBuilder = txBuilder.withOwnOutputNotes(outputNotes);
+  txBuilder = txBuilder.withAuthArg(authSaltForBuilder);
+
+  if (options.signatureAdviceMap) {
+    txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
+  }
+
+  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  return {
+    request: txBuilder.build(),
+    salt: authSaltForReturn,
+  };
+}
+

package/src/transaction/summary.ts

@@ -0,0 +1,12 @@
+import type { TransactionRequest, TransactionSummary, WebClient } from '@demox-labs/miden-sdk';
+import { AccountId } from '@demox-labs/miden-sdk';
+
+export async function executeForSummary(
+  client: WebClient,
+  accountId: string,
+  txRequest: TransactionRequest,
+): Promise<TransactionSummary> {
+  const acc = AccountId.fromHex(accountId);
+  return (client as any).executeForSummary(acc, txRequest);
+}
+

package/src/transaction/updatePsm.ts

@@ -0,0 +1,69 @@
+import {
+  AdviceMap,
+  FeltArray,
+  TransactionRequest,
+  TransactionRequestBuilder,
+  TransactionScript,
+  WebClient,
+  Word,
+  Word as WordType,
+} from '@demox-labs/miden-sdk';
+import { PSM_MASM } from '../account/masm.js';
+import { normalizeHexWord } from '../utils/encoding.js';
+import { randomWord } from '../utils/random.js';
+import type { SignatureOptions } from './options.js';
+
+function buildUpdatePsmScript(webClient: WebClient): TransactionScript {
+  const libBuilder = webClient.createScriptBuilder();
+  const psmLib = libBuilder.buildLibrary('openzeppelin::psm', PSM_MASM);
+  libBuilder.linkDynamicLibrary(psmLib);
+
+  const scriptSource = `
+use.openzeppelin::psm
+
+begin
+    adv.push_mapval
+    dropw
+    call.psm::update_psm_public_key
+end
+  `;
+
+  return libBuilder.compileTxScript(scriptSource);
+}
+
+export async function buildUpdatePsmTransactionRequest(
+  webClient: WebClient,
+  newPsmPubkey: string,
+  options: SignatureOptions = {},
+): Promise<{ request: TransactionRequest; salt: Word }> {
+  const script = buildUpdatePsmScript(webClient);
+
+  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
+
+  const pubkeyWordForAdvice = WordType.fromHex(normalizeHexWord(newPsmPubkey));
+  const pubkeyWordForFelts = WordType.fromHex(normalizeHexWord(newPsmPubkey));
+  const pubkeyWordForScript = WordType.fromHex(normalizeHexWord(newPsmPubkey));
+
+  const advice = new AdviceMap();
+  advice.insert(pubkeyWordForAdvice, new FeltArray(pubkeyWordForFelts.toFelts()));
+
+  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  let txBuilder = new TransactionRequestBuilder();
+  txBuilder = txBuilder.withCustomScript(script);
+  txBuilder = txBuilder.withScriptArg(pubkeyWordForScript);
+  txBuilder = txBuilder.extendAdviceMap(advice);
+  txBuilder = txBuilder.withAuthArg(authSaltForBuilder);
+
+  if (options.signatureAdviceMap) {
+    txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
+  }
+
+  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  return {
+    request: txBuilder.build(),
+    salt: authSaltForReturn,
+  };
+}
+

package/src/transaction/updateSigners.ts

@@ -0,0 +1,96 @@
+import {
+  AdviceMap,
+  Felt,
+  FeltArray,
+  Rpo256,
+  TransactionRequest,
+  TransactionRequestBuilder,
+  TransactionScript,
+  WebClient,
+  Word,
+  Word as WordType,
+} from '@demox-labs/miden-sdk';
+import { MULTISIG_MASM, PSM_MASM } from '../account/masm.js';
+import { normalizeHexWord } from '../utils/encoding.js';
+import { randomWord } from '../utils/random.js';
+import type { SignatureOptions } from './options.js';
+
+function buildMultisigConfigAdvice(
+  threshold: number,
+  signerCommitments: string[],
+): { configHash: Word; payload: FeltArray } {
+  const numApprovers = signerCommitments.length;
+  const felts: Felt[] = [
+    new Felt(BigInt(threshold)),
+    new Felt(BigInt(numApprovers)),
+    new Felt(0n),
+    new Felt(0n),
+  ];
+  for (const commitment of [...signerCommitments].reverse()) {
+    const word = WordType.fromHex(normalizeHexWord(commitment));
+    felts.push(...word.toFelts());
+  }
+  const payload = new FeltArray(felts);
+  const configHash = Rpo256.hashElements(payload);
+  return { configHash, payload };
+}
+
+function buildUpdateSignersScript(webClient: WebClient): TransactionScript {
+  const libBuilder = webClient.createScriptBuilder();
+  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);
+}
+
+export async function buildUpdateSignersTransactionRequest(
+  webClient: WebClient,
+  threshold: number,
+  signerCommitments: string[],
+  options: SignatureOptions = {},
+): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }> {
+  const { configHash: configHashForAdvice, payload } = buildMultisigConfigAdvice(threshold, signerCommitments);
+
+  const { configHash: configHashForScript } = buildMultisigConfigAdvice(threshold, signerCommitments);
+
+  const { configHash: configHashForReturn } = buildMultisigConfigAdvice(threshold, signerCommitments);
+
+  const advice = new AdviceMap();
+  advice.insert(configHashForAdvice, payload);
+
+  const script = buildUpdateSignersScript(webClient);
+
+  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
+
+  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  let txBuilder = new TransactionRequestBuilder();
+  txBuilder = txBuilder.withCustomScript(script);
+  txBuilder = txBuilder.withScriptArg(configHashForScript);
+  txBuilder = txBuilder.extendAdviceMap(advice);
+  txBuilder = txBuilder.withAuthArg(authSaltForBuilder);
+
+  if (options.signatureAdviceMap) {
+    txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
+  }
+
+  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
+
+  return {
+    request: txBuilder.build(),
+    salt: authSaltForReturn,
+    configHash: configHashForReturn,
+  };
+}
+