@openzeppelin/miden-multisig-client 0.12.6

package/src/transaction.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+
+// Mock Miden SDK before importing transaction module
+vi.mock('@demox-labs/miden-sdk', () => ({
+  AccountId: { fromHex: vi.fn() },
+  AdviceMap: vi.fn(),
+  Felt: vi.fn().mockImplementation((v) => ({ value: v })),
+  FeltArray: vi.fn().mockImplementation((arr) => arr),
+  Rpo256: { hashElements: vi.fn() },
+  Signature: { deserialize: vi.fn() },
+  TransactionRequestBuilder: vi.fn().mockImplementation(() => ({
+    withCustomScript: vi.fn().mockReturnThis(),
+    withScriptArg: vi.fn().mockReturnThis(),
+    extendAdviceMap: vi.fn().mockReturnThis(),
+    withAuthArg: vi.fn().mockReturnThis(),
+    build: vi.fn().mockReturnValue({}),
+  })),
+  Word: {
+    fromHex: vi.fn().mockImplementation((hex: string) => ({
+      toHex: () => hex,
+      toFelts: () => [1, 2, 3, 4],
+    })),
+  },
+}));
+
+// Now import the module under test - use dynamic import to ensure mocks are in place
+let normalizeHexWord: typeof import('./utils/encoding.js').normalizeHexWord;
+let signatureHexToBytes: typeof import('./utils/signature.js').signatureHexToBytes;
+let hexToBytes: typeof import('./utils/encoding.js').hexToBytes;
+
+beforeAll(async () => {
+  const encoding = await import('./utils/encoding.js');
+  const sig = await import('./utils/signature.js');
+  normalizeHexWord = encoding.normalizeHexWord;
+  hexToBytes = encoding.hexToBytes;
+  signatureHexToBytes = sig.signatureHexToBytes;
+});
+
+describe('transaction utilities', () => {
+  describe('normalizeHexWord', () => {
+    it('should handle hex without 0x prefix', () => {
+      const result = normalizeHexWord('abc123');
+      expect(result).toBe('0x' + '0'.repeat(58) + 'abc123');
+    });
+
+    it('should handle hex with 0x prefix', () => {
+      const result = normalizeHexWord('0xabc123');
+      expect(result).toBe('0x' + '0'.repeat(58) + 'abc123');
+    });
+
+    it('should handle hex with 0X prefix', () => {
+      const result = normalizeHexWord('0Xabc123');
+      expect(result).toBe('0x' + '0'.repeat(58) + 'abc123');
+    });
+
+    it('should convert to lowercase', () => {
+      const result = normalizeHexWord('0xABC123DEF');
+      expect(result).toBe('0x' + '0'.repeat(55) + 'abc123def');
+    });
+
+    it('should pad to 64 characters', () => {
+      const result = normalizeHexWord('1');
+      expect(result).toBe('0x' + '0'.repeat(63) + '1');
+      expect(result.length).toBe(66); // 0x + 64 chars
+    });
+
+    it('should preserve full 64-char hex', () => {
+      const fullHex = 'a'.repeat(64);
+      const result = normalizeHexWord(fullHex);
+      expect(result).toBe('0x' + fullHex);
+    });
+
+    it('should preserve full 64-char hex with prefix', () => {
+      const fullHex = 'b'.repeat(64);
+      const result = normalizeHexWord('0x' + fullHex);
+      expect(result).toBe('0x' + fullHex);
+    });
+  });
+
+  describe('hexToBytes', () => {
+    it('should convert hex string to Uint8Array', () => {
+      const result = hexToBytes('deadbeef');
+      expect(result).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    });
+
+    it('should handle 0x prefix', () => {
+      const result = hexToBytes('0xdeadbeef');
+      expect(result).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    });
+
+    it('should handle empty string', () => {
+      const result = hexToBytes('');
+      expect(result).toEqual(new Uint8Array([]));
+    });
+
+    it('should handle single byte', () => {
+      const result = hexToBytes('ff');
+      expect(result).toEqual(new Uint8Array([0xff]));
+    });
+
+    it('should handle zeros', () => {
+      const result = hexToBytes('00000000');
+      expect(result).toEqual(new Uint8Array([0, 0, 0, 0]));
+    });
+
+    it('should handle mixed case', () => {
+      const result = hexToBytes('DeAdBeEf');
+      expect(result).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    });
+  });
+
+  describe('signatureHexToBytes', () => {
+    it('should prepend auth scheme byte (0 = RpoFalcon512)', () => {
+      const result = signatureHexToBytes('deadbeef');
+      expect(result[0]).toBe(0); // RpoFalcon512 scheme byte
+      expect(result.slice(1)).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    });
+
+    it('should handle 0x prefix', () => {
+      const result = signatureHexToBytes('0xaabbccdd');
+      expect(result[0]).toBe(0);
+      expect(result.slice(1)).toEqual(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd]));
+    });
+
+    it('should return correct length', () => {
+      const sigHex = 'a'.repeat(128); // 64 bytes
+      const result = signatureHexToBytes(sigHex);
+      expect(result.length).toBe(65); // 64 bytes + 1 prefix byte
+    });
+
+    it('should handle empty signature', () => {
+      const result = signatureHexToBytes('');
+      expect(result).toEqual(new Uint8Array([0])); // Just the prefix
+    });
+  });
+});

package/src/transaction.ts

@@ -0,0 +1,16 @@
+// Backward-compatible entry point for transaction helpers.
+// The implementations now live in ./transaction/.
+export {
+  buildConsumeNotesTransactionRequest,
+} from './transaction/consumeNotes.js';
+export { executeForSummary } from './transaction/summary.js';
+export {
+  buildP2idTransactionRequest,
+} from './transaction/p2id.js';
+export {
+  buildUpdatePsmTransactionRequest,
+} from './transaction/updatePsm.js';
+export {
+  buildUpdateSignersTransactionRequest,
+} from './transaction/updateSigners.js';
+

package/src/types/proposal.ts

@@ -0,0 +1,80 @@
+import type { ProposalType as PsmProposalType } from '@openzeppelin/psm-client';
+export type ProposalType = Exclude<PsmProposalType, 'custom'>;
+
+export type ProposalStatus =
+  | { type: 'pending'; signaturesCollected: number; signaturesRequired: number; signers: string[] }
+  | { type: 'ready' }
+  | { type: 'finalized' };
+
+export interface ProposalSignatureEntry {
+  signerId: string;
+  signature: { scheme: 'falcon'; signature: string };
+  timestamp: string;
+}
+
+interface BaseProposalMetadata {
+  proposalType: ProposalType;
+  description: string;
+  saltHex?: string;
+}
+
+export interface UpdateSignersProposalMetadata extends BaseProposalMetadata {
+  proposalType: 'add_signer' | 'remove_signer' | 'change_threshold';
+  targetThreshold: number;
+  targetSignerCommitments: string[];
+}
+
+export interface SwitchPsmProposalMetadata extends BaseProposalMetadata {
+  proposalType: 'switch_psm';
+  newPsmPubkey: string;
+  newPsmEndpoint?: string;
+  targetThreshold?: number;
+  targetSignerCommitments?: string[];
+}
+
+export interface ConsumeNotesProposalMetadata extends BaseProposalMetadata {
+  proposalType: 'consume_notes';
+  noteIds: string[];
+}
+
+export interface P2IdProposalMetadata extends BaseProposalMetadata {
+  proposalType: 'p2id';
+  recipientId: string;
+  faucetId: string;
+  amount: string;
+}
+
+export interface UnknownProposalMetadata extends BaseProposalMetadata {
+  proposalType: 'unknown';
+}
+
+export type ProposalMetadata =
+  | UpdateSignersProposalMetadata
+  | SwitchPsmProposalMetadata
+  | ConsumeNotesProposalMetadata
+  | P2IdProposalMetadata
+  | UnknownProposalMetadata;
+
+export interface Proposal {
+  id: string;
+  accountId: string;
+  nonce: number;
+  status: ProposalStatus;
+  txSummary: string;
+  signatures: ProposalSignatureEntry[];
+  metadata: ProposalMetadata;
+}
+
+export interface ExportedProposal {
+  accountId: string;
+  nonce: number;
+  commitment: string;
+  txSummaryBase64: string;
+  signatures: Array<{
+    commitment: string;
+    signatureHex: string;
+    timestamp?: string;
+  }>;
+  metadata?: ProposalMetadata;
+}
+

package/src/types.ts

@@ -0,0 +1,81 @@
+import type { Account } from '@demox-labs/miden-sdk';
+import type { ProcedureName } from './procedures.js';
+
+export type {
+  Signer,
+  FalconSignature,
+  CosignerSignature,
+  AuthConfig,
+  DeltaStatus,
+  DeltaObject,
+  StateObject,
+  ConfigureRequest,
+  ConfigureResponse,
+  PubkeyResponse,
+  DeltaProposalRequest,
+  DeltaProposalResponse,
+  ProposalsResponse,
+  SignProposalRequest,
+} from '@openzeppelin/psm-client';
+
+export type {
+  ExportedProposal,
+  Proposal,
+  ProposalMetadata,
+  ProposalSignatureEntry,
+  ProposalStatus,
+  ProposalType,
+} from './types/proposal.js';
+
+export interface MultisigAccountState {
+  id: string;
+  nonce: number;
+  threshold: number;
+  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;
+  psmEnabled?: boolean;
+  storageMode?: 'private' | 'public';
+  procedureThresholds?: ProcedureThreshold[];
+}
+
+export interface CreateAccountResult {
+  account: Account;
+  seed: Uint8Array;
+}
+
+export type TransactionType =
+  | { type: 'p2id'; recipient: string; faucetId: string; amount: bigint }
+  | { type: 'consumeNotes'; noteIds: string[] }
+  | { type: 'updateSigners'; newThreshold: number; newSignerCommitments: string[] };
+
+export interface NoteAsset {
+  faucetId: string;
+  amount: bigint;
+}
+
+export interface ConsumableNote {
+  id: string;
+  assets: NoteAsset[];
+}

package/src/utils/encoding.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect } from 'vitest';
+import {
+  ensureHexPrefix,
+  normalizeHexWord,
+  bytesToHex,
+  hexToBytes,
+  uint8ArrayToBase64,
+  base64ToUint8Array,
+} from './encoding.js';
+
+describe('encoding utilities', () => {
+  describe('ensureHexPrefix', () => {
+    it('adds 0x prefix when missing', () => {
+      expect(ensureHexPrefix('abc123')).toBe('0xabc123');
+    });
+
+    it('preserves existing 0x prefix', () => {
+      expect(ensureHexPrefix('0xabc123')).toBe('0xabc123');
+    });
+
+    it('preserves existing 0X prefix', () => {
+      expect(ensureHexPrefix('0Xabc123')).toBe('0Xabc123');
+    });
+
+    it('handles empty string', () => {
+      expect(ensureHexPrefix('')).toBe('0x');
+    });
+
+    it('handles single character', () => {
+      expect(ensureHexPrefix('a')).toBe('0xa');
+    });
+  });
+
+  describe('normalizeHexWord', () => {
+    it('pads short hex to 64 characters', () => {
+      const result = normalizeHexWord('abc123');
+      expect(result).toBe('0x' + '0'.repeat(58) + 'abc123');
+      expect(result.length).toBe(66); // 0x + 64 chars
+    });
+
+    it('preserves full 64-char hex', () => {
+      const fullHex = 'a'.repeat(64);
+      expect(normalizeHexWord(fullHex)).toBe('0x' + fullHex);
+    });
+
+    it('handles 0x prefix', () => {
+      expect(normalizeHexWord('0xabc')).toBe('0x' + '0'.repeat(61) + 'abc');
+    });
+
+    it('handles 0X prefix', () => {
+      expect(normalizeHexWord('0Xabc')).toBe('0x' + '0'.repeat(61) + 'abc');
+    });
+
+    it('converts to lowercase', () => {
+      expect(normalizeHexWord('ABC')).toBe('0x' + '0'.repeat(61) + 'abc');
+    });
+
+    it('handles empty string', () => {
+      expect(normalizeHexWord('')).toBe('0x' + '0'.repeat(64));
+    });
+
+    it('handles single digit', () => {
+      expect(normalizeHexWord('1')).toBe('0x' + '0'.repeat(63) + '1');
+    });
+
+    it('handles full 64-char hex with prefix', () => {
+      const fullHex = 'b'.repeat(64);
+      expect(normalizeHexWord('0x' + fullHex)).toBe('0x' + fullHex);
+    });
+  });
+
+  describe('bytesToHex', () => {
+    it('converts Uint8Array to hex string', () => {
+      const bytes = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+      expect(bytesToHex(bytes)).toBe('0xdeadbeef');
+    });
+
+    it('handles empty array', () => {
+      expect(bytesToHex(new Uint8Array([]))).toBe('0x');
+    });
+
+    it('handles single byte', () => {
+      expect(bytesToHex(new Uint8Array([0xff]))).toBe('0xff');
+    });
+
+    it('pads single digit bytes with zero', () => {
+      const bytes = new Uint8Array([0x0a, 0x0b, 0x0c]);
+      expect(bytesToHex(bytes)).toBe('0x0a0b0c');
+    });
+
+    it('handles zeros', () => {
+      const bytes = new Uint8Array([0x00, 0x00, 0x00]);
+      expect(bytesToHex(bytes)).toBe('0x000000');
+    });
+
+    it('handles max byte value', () => {
+      const bytes = new Uint8Array([0xff, 0xff]);
+      expect(bytesToHex(bytes)).toBe('0xffff');
+    });
+
+    it('handles long arrays', () => {
+      const bytes = new Uint8Array(32).fill(0xaa);
+      const result = bytesToHex(bytes);
+      expect(result).toBe('0x' + 'aa'.repeat(32));
+    });
+  });
+
+  describe('hexToBytes', () => {
+    it('converts hex string to Uint8Array', () => {
+      expect(hexToBytes('deadbeef')).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    });
+
+    it('handles 0x prefix', () => {
+      expect(hexToBytes('0xdeadbeef')).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    });
+
+    it('handles 0X prefix', () => {
+      expect(hexToBytes('0Xdeadbeef')).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    });
+
+    it('handles empty string', () => {
+      expect(hexToBytes('')).toEqual(new Uint8Array([]));
+    });
+
+    it('handles empty with prefix', () => {
+      expect(hexToBytes('0x')).toEqual(new Uint8Array([]));
+    });
+
+    it('handles single byte', () => {
+      expect(hexToBytes('ff')).toEqual(new Uint8Array([0xff]));
+    });
+
+    it('handles zeros', () => {
+      expect(hexToBytes('00000000')).toEqual(new Uint8Array([0, 0, 0, 0]));
+    });
+
+    it('handles mixed case', () => {
+      expect(hexToBytes('DeAdBeEf')).toEqual(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
+    });
+
+    it('handles long hex strings', () => {
+      const hex = 'aa'.repeat(32);
+      const result = hexToBytes(hex);
+      expect(result).toEqual(new Uint8Array(32).fill(0xaa));
+    });
+  });
+
+  describe('roundtrip bytesToHex/hexToBytes', () => {
+    it('survives roundtrip bytes -> hex -> bytes', () => {
+      const original = new Uint8Array([0xde, 0xad, 0xbe, 0xef, 0x01, 0x23, 0x45, 0x67]);
+      const hex = bytesToHex(original);
+      const roundtripped = hexToBytes(hex);
+      expect(roundtripped).toEqual(original);
+    });
+
+    it('survives roundtrip hex -> bytes -> hex', () => {
+      const original = '0xdeadbeef01234567';
+      const bytes = hexToBytes(original);
+      const roundtripped = bytesToHex(bytes);
+      expect(roundtripped).toBe(original);
+    });
+  });
+
+  describe('uint8ArrayToBase64', () => {
+    it('converts Uint8Array to base64', () => {
+      const bytes = new Uint8Array([72, 101, 108, 108, 111]); // "Hello"
+      expect(uint8ArrayToBase64(bytes)).toBe('SGVsbG8=');
+    });
+
+    it('handles empty array', () => {
+      expect(uint8ArrayToBase64(new Uint8Array([]))).toBe('');
+    });
+
+    it('handles binary data', () => {
+      const bytes = new Uint8Array([0xff, 0x00, 0xaa, 0x55]);
+      const base64 = uint8ArrayToBase64(bytes);
+      expect(base64).toBeTruthy();
+      // Verify by round-tripping
+      expect(base64ToUint8Array(base64)).toEqual(bytes);
+    });
+
+    it('handles single byte', () => {
+      const bytes = new Uint8Array([65]); // 'A'
+      expect(uint8ArrayToBase64(bytes)).toBe('QQ==');
+    });
+
+    it('handles bytes requiring padding', () => {
+      const bytes = new Uint8Array([1]);
+      const base64 = uint8ArrayToBase64(bytes);
+      expect(base64).toBe('AQ==');
+    });
+  });
+
+  describe('base64ToUint8Array', () => {
+    it('converts base64 to Uint8Array', () => {
+      const base64 = 'SGVsbG8='; // "Hello"
+      expect(base64ToUint8Array(base64)).toEqual(new Uint8Array([72, 101, 108, 108, 111]));
+    });
+
+    it('handles empty string', () => {
+      expect(base64ToUint8Array('')).toEqual(new Uint8Array([]));
+    });
+
+    it('handles binary data', () => {
+      const base64 = '/wCqVQ=='; // [0xff, 0x00, 0xaa, 0x55]
+      expect(base64ToUint8Array(base64)).toEqual(new Uint8Array([0xff, 0x00, 0xaa, 0x55]));
+    });
+
+    it('handles base64 without padding', () => {
+      const base64 = 'YWJj'; // "abc" - no padding needed
+      expect(base64ToUint8Array(base64)).toEqual(new Uint8Array([97, 98, 99]));
+    });
+  });
+
+  describe('roundtrip uint8ArrayToBase64/base64ToUint8Array', () => {
+    it('survives roundtrip bytes -> base64 -> bytes', () => {
+      const original = new Uint8Array([0, 1, 2, 3, 255, 254, 253, 252]);
+      const base64 = uint8ArrayToBase64(original);
+      const roundtripped = base64ToUint8Array(base64);
+      expect(roundtripped).toEqual(original);
+    });
+
+    it('survives roundtrip for large arrays', () => {
+      const original = new Uint8Array(1000);
+      for (let i = 0; i < 1000; i++) {
+        original[i] = i % 256;
+      }
+      const base64 = uint8ArrayToBase64(original);
+      const roundtripped = base64ToUint8Array(base64);
+      expect(roundtripped).toEqual(original);
+    });
+  });
+});

package/src/utils/encoding.ts

@@ -0,0 +1,60 @@
+export function ensureHexPrefix(hex: string): string {
+  return hex.startsWith('0x') || hex.startsWith('0X') ? hex : `0x${hex}`;
+}
+
+export function normalizeHexWord(hex: string): string {
+  let clean = ensureHexPrefix(hex).slice(2).toLowerCase();
+  clean = clean.padStart(64, '0');
+  return `0x${clean}`;
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let hex = '0x';
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, '0');
+  }
+  return hex;
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  const cleanHex = ensureHexPrefix(hex).slice(2);
+  const bytes = new Uint8Array(cleanHex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(cleanHex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+export function uint8ArrayToBase64(bytes: Uint8Array): string {
+  if (typeof btoa === 'function') {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+  const buf: any = (globalThis as any).Buffer;
+  if (buf) {
+    return buf.from(bytes).toString('base64');
+  }
+  throw new Error('No base64 encoder available in this environment');
+}
+
+export function base64ToUint8Array(base64: string): Uint8Array {
+  const binary =
+    typeof atob === 'function'
+      ? atob(base64)
+      : (() => {
+          const buf: any = (globalThis as any).Buffer;
+          if (buf) {
+            return buf.from(base64, 'base64').toString('binary');
+          }
+          throw new Error('No base64 decoder available in this environment');
+        })();
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export * from './encoding.js';
+export * from './random.js';
+export * from './signature.js';
+export * from './word.js';
+

package/src/utils/random.ts

@@ -0,0 +1,15 @@
+import { Word } from '@demox-labs/miden-sdk';
+
+export function randomWord(): Word {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const view = new DataView(bytes.buffer);
+  const u64s = new BigUint64Array([
+    view.getBigUint64(0, true),
+    view.getBigUint64(8, true),
+    view.getBigUint64(16, true),
+    view.getBigUint64(24, true),
+  ]);
+  return new Word(u64s);
+}
+