@hula-privacy/mixer 0.1.0

package/src/types.ts

@@ -0,0 +1,331 @@
+/**
+ * Type definitions for Hula Privacy SDK
+ */
+
+import type { PublicKey, Keypair, Connection } from "@solana/web3.js";
+
+// ============================================================================
+// Cryptographic Types
+// ============================================================================
+
+/**
+ * UTXO (Unspent Transaction Output) in the privacy pool
+ */
+export interface UTXO {
+  /** Amount in raw token units */
+  value: bigint;
+  /** Token mint address as bigint */
+  mintTokenAddress: bigint;
+  /** Owner hash (derived from spending key) */
+  owner: bigint;
+  /** Random blinding factor */
+  secret: bigint;
+  /** Poseidon hash commitment */
+  commitment: bigint;
+  /** Index in the merkle tree */
+  leafIndex: number;
+  /** Which tree this UTXO is in */
+  treeIndex: number;
+}
+
+/**
+ * Serializable UTXO for storage/transmission
+ */
+export interface SerializableUTXO {
+  value: string;
+  mintTokenAddress: string;
+  owner: string;
+  secret: string;
+  commitment: string;
+  leafIndex: number;
+  treeIndex: number;
+  /** Token mint public key */
+  mint: string;
+  /** Whether this UTXO has been spent */
+  spent: boolean;
+  /** Transaction that spent this UTXO */
+  spentTx?: string;
+  /** Transaction that created this UTXO */
+  createdTx: string;
+  /** Timestamp when created */
+  createdAt: string;
+}
+
+/**
+ * Wallet keys derived from spending key
+ */
+export interface WalletKeys {
+  /** Master spending key - KEEP SECRET */
+  spendingKey: bigint;
+  /** Owner hash - public identifier for receiving funds */
+  owner: bigint;
+  /** Viewing key - for decrypting notes */
+  viewingKey: bigint;
+  /** Nullifier key - for computing nullifiers */
+  nullifierKey: bigint;
+  /** X25519 keypair for note encryption */
+  encryptionKeyPair: {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+  };
+}
+
+/**
+ * Encrypted note attached to transactions
+ */
+export interface EncryptedNote {
+  /** Ephemeral public key for ECDH */
+  ephemeralPubKey: Uint8Array;
+  /** Encrypted ciphertext */
+  ciphertext: Uint8Array;
+  /** Nonce for decryption */
+  nonce: Uint8Array;
+}
+
+// ============================================================================
+// Merkle Tree Types
+// ============================================================================
+
+/**
+ * Merkle path for proving inclusion
+ */
+export interface MerklePath {
+  /** Sibling hashes at each level */
+  pathElements: bigint[];
+  /** Direction at each level (0 = left, 1 = right) */
+  pathIndices: number[];
+  /** Root of the tree */
+  root: bigint;
+}
+
+/**
+ * Leaf data from the relayer
+ */
+export interface LeafData {
+  id: string;
+  treeIndex: number;
+  leafIndex: number;
+  commitment: string;
+  slot: string;
+  createdAt: string;
+}
+
+// ============================================================================
+// Transaction Types
+// ============================================================================
+
+/**
+ * Circuit inputs for ZK proof generation
+ */
+export interface CircuitInputs {
+  // Public inputs
+  merkleRoot: string;
+  nullifiers: string[];
+  outputCommitments: string[];
+  publicDeposit: string;
+  publicWithdraw: string;
+  recipient: string;
+  mintTokenAddress: string;
+  fee: string;
+
+  // Private inputs for input UTXOs
+  inputSpendingKeys: string[];
+  inputValues: string[];
+  inputSecrets: string[];
+  inputLeafIndices: string[];
+  inputPathElements: string[][];
+  inputPathIndices: number[][];
+
+  // Private inputs for output UTXOs
+  outputValues: string[];
+  outputOwners: string[];
+  outputSecrets: string[];
+}
+
+/**
+ * Public inputs for the on-chain verifier
+ */
+export interface PublicInputs {
+  merkleRoot: number[];
+  nullifiers: number[][];
+  outputCommitments: number[][];
+  publicDeposit: bigint;
+  publicWithdraw: bigint;
+  recipient: PublicKey;
+  mintTokenAddress: PublicKey;
+  fee: bigint;
+}
+
+/**
+ * Output UTXO specification
+ */
+export interface OutputSpec {
+  /** Owner hash (bigint) or "self" for own wallet */
+  owner: bigint | "self";
+  /** Amount in raw token units */
+  amount: bigint;
+  /** Encryption public key for encrypted note (optional) */
+  encryptionPubKey?: Uint8Array;
+}
+
+/**
+ * Transaction request for building a privacy transaction
+ */
+export interface TransactionRequest {
+  /** Amount to deposit from public wallet */
+  depositAmount?: bigint;
+  /** Input UTXOs to spend */
+  inputUtxos?: UTXO[];
+  /** Output UTXOs to create */
+  outputs?: OutputSpec[];
+  /** Amount to withdraw to public wallet */
+  withdrawAmount?: bigint;
+  /** Recipient public key for withdrawal */
+  recipient?: PublicKey;
+  /** Relayer fee */
+  fee?: bigint;
+  /** Token mint address */
+  mint: PublicKey;
+}
+
+/**
+ * Built transaction ready for submission
+ */
+export interface BuiltTransaction {
+  /** Proof bytes (256 bytes) */
+  proof: Uint8Array;
+  /** Public inputs for the circuit */
+  publicInputs: PublicInputs;
+  /** Encrypted notes for outputs */
+  encryptedNotes: Buffer[];
+  /** Created output UTXOs (for tracking) */
+  outputUtxos: UTXO[];
+  /** Nullifiers being spent */
+  nullifiers: bigint[];
+  /** Input tree index */
+  inputTreeIndex: number;
+  /** Output tree index (current tree) */
+  outputTreeIndex: number;
+}
+
+// ============================================================================
+// Relayer API Types
+// ============================================================================
+
+/**
+ * Paginated response from relayer
+ */
+export interface PaginatedResponse<T> {
+  items: T[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+/**
+ * Pool data from relayer
+ */
+export interface PoolData {
+  authority: string;
+  commitmentCount: string;
+  merkleRoot: string;
+  paused: boolean;
+  currentTreeIndex: number;
+  lastSlot: string;
+}
+
+/**
+ * Tree data from relayer
+ */
+export interface TreeData {
+  id: string;
+  treeIndex: number;
+  nextIndex: number;
+  root: string;
+}
+
+/**
+ * Transaction data from relayer
+ */
+export interface TransactionData {
+  id: string;
+  signature: string;
+  slot: string;
+  blockTime?: string;
+  payer: string;
+  mint: string;
+  outputTreeIndex: number;
+  publicDeposit: string;
+  publicWithdraw: string;
+  fee: string;
+  success: boolean;
+  nullifiers: string[];
+  encryptedNotes: { noteIndex: number; data: string }[];
+}
+
+/**
+ * Encrypted note data from relayer
+ */
+export interface NoteData {
+  id: string;
+  noteIndex: number;
+  encryptedData: string;
+  txSignature: string;
+  slot: string;
+  mint: string;
+  treeIndex: number;
+}
+
+/**
+ * Stats from relayer
+ */
+export interface StatsData {
+  pool: {
+    commitmentCount: string;
+    currentTreeIndex: number;
+    paused: boolean;
+  } | null;
+  treeCount: number;
+  leafCount: number;
+  transactionCount: number;
+  nullifierCount: number;
+}
+
+// ============================================================================
+// SDK Config Types
+// ============================================================================
+
+/**
+ * SDK configuration
+ */
+export interface HulaSDKConfig {
+  /** Solana RPC endpoint */
+  rpcUrl: string;
+  /** Relayer API endpoint */
+  relayerUrl: string;
+  /** Path to circuit WASM file */
+  circuitWasmPath?: string;
+  /** Path to circuit zkey file */
+  circuitZkeyPath?: string;
+  /** Network: localnet | devnet | mainnet */
+  network?: "localnet" | "devnet" | "mainnet";
+}
+
+/**
+ * Wallet sync progress
+ */
+export interface SyncProgress {
+  stage: "notes" | "nullifiers" | "complete";
+  current: number;
+  total: number;
+}
+
+/**
+ * Wallet sync result
+ */
+export interface SyncResult {
+  newUtxos: number;
+  spentUtxos: number;
+  errors: string[];
+}
+
+

package/src/utxo.ts

@@ -0,0 +1,358 @@
+/**
+ * UTXO (Unspent Transaction Output) management
+ * 
+ * Provides functions for creating, scanning, and managing UTXOs
+ */
+
+import { getRelayerClient } from "./api";
+import {
+  poseidonHash,
+  decryptNote,
+  deserializeEncryptedNote,
+  generateSpendingKey,
+  hexToBytes,
+} from "./crypto";
+import { DOMAIN_NULLIFIER } from "./constants";
+import type { UTXO, WalletKeys, SerializableUTXO, NoteData } from "./types";
+
+// ============================================================================
+// Commitment & Nullifier Computation
+// ============================================================================
+
+/**
+ * Compute UTXO commitment
+ * commitment = Poseidon(value, mintTokenAddress, owner, secret)
+ */
+export function computeCommitment(
+  value: bigint,
+  mintTokenAddress: bigint,
+  owner: bigint,
+  secret: bigint
+): bigint {
+  return poseidonHash([value, mintTokenAddress, owner, secret]);
+}
+
+/**
+ * Compute nullifier for spending a UTXO
+ * nullifier = Poseidon(nullifierKey, commitment, leafIndex)
+ */
+export function computeNullifier(
+  spendingKey: bigint,
+  commitment: bigint,
+  leafIndex: number
+): bigint {
+  const nullifierKey = poseidonHash([spendingKey, DOMAIN_NULLIFIER]);
+  return poseidonHash([nullifierKey, commitment, BigInt(leafIndex)]);
+}
+
+/**
+ * Compute nullifier from wallet keys
+ */
+export function computeNullifierFromKeys(
+  keys: WalletKeys,
+  commitment: bigint,
+  leafIndex: number
+): bigint {
+  return poseidonHash([keys.nullifierKey, commitment, BigInt(leafIndex)]);
+}
+
+// ============================================================================
+// UTXO Creation
+// ============================================================================
+
+/**
+ * Create a new UTXO with random secret
+ */
+export function createUTXO(
+  value: bigint,
+  mintTokenAddress: bigint,
+  owner: bigint,
+  leafIndex: number,
+  treeIndex: number = 0
+): UTXO {
+  const secret = generateSpendingKey(); // Random blinding factor
+  const commitment = computeCommitment(value, mintTokenAddress, owner, secret);
+
+  return {
+    value,
+    mintTokenAddress,
+    owner,
+    secret,
+    commitment,
+    leafIndex,
+    treeIndex,
+  };
+}
+
+/**
+ * Create a dummy (zero) UTXO for padding
+ */
+export function createDummyUTXO(): UTXO {
+  return {
+    value: 0n,
+    mintTokenAddress: 0n,
+    owner: 0n,
+    secret: 0n,
+    commitment: 0n,
+    leafIndex: 0,
+    treeIndex: 0,
+  };
+}
+
+// ============================================================================
+// UTXO Serialization
+// ============================================================================
+
+/**
+ * Serialize UTXO for storage
+ */
+export function serializeUTXO(
+  utxo: UTXO,
+  mint: string,
+  createdTx: string,
+  spent: boolean = false,
+  spentTx?: string
+): SerializableUTXO {
+  return {
+    value: utxo.value.toString(),
+    mintTokenAddress: utxo.mintTokenAddress.toString(),
+    owner: utxo.owner.toString(),
+    secret: utxo.secret.toString(),
+    commitment: utxo.commitment.toString(),
+    leafIndex: utxo.leafIndex,
+    treeIndex: utxo.treeIndex,
+    mint,
+    spent,
+    spentTx,
+    createdTx,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Deserialize UTXO from storage
+ */
+export function deserializeUTXO(data: SerializableUTXO): UTXO {
+  return {
+    value: BigInt(data.value),
+    mintTokenAddress: BigInt(data.mintTokenAddress),
+    owner: BigInt(data.owner),
+    secret: BigInt(data.secret),
+    commitment: BigInt(data.commitment),
+    leafIndex: data.leafIndex,
+    treeIndex: data.treeIndex,
+  };
+}
+
+// ============================================================================
+// UTXO Scanning
+// ============================================================================
+
+/**
+ * Scan encrypted notes for UTXOs belonging to this wallet
+ * 
+ * This attempts to decrypt each note with the wallet's encryption key.
+ * If successful, the note belongs to this wallet.
+ */
+export function scanNotesForUTXOs(
+  notes: Array<{
+    encryptedData: string;
+    treeIndex: number;
+    mint: string;
+    txSignature: string;
+  }>,
+  walletKeys: WalletKeys,
+  commitments: Map<number, Map<number, bigint>> // treeIndex -> leafIndex -> commitment
+): SerializableUTXO[] {
+  const foundUTXOs: SerializableUTXO[] = [];
+
+  for (const note of notes) {
+    try {
+      // Parse encrypted note from hex
+      const noteBytes = hexToBytes(note.encryptedData);
+      const encryptedNote = deserializeEncryptedNote(noteBytes);
+
+      // Try to decrypt
+      const decrypted = decryptNote(encryptedNote, walletKeys.encryptionKeyPair.secretKey);
+      if (!decrypted) continue;
+
+      // Successfully decrypted - this is our UTXO
+      const commitment = computeCommitment(
+        decrypted.value,
+        decrypted.mintTokenAddress,
+        walletKeys.owner,
+        decrypted.secret
+      );
+
+      // Verify commitment exists on-chain (optional but recommended)
+      const treeCommitments = commitments.get(note.treeIndex);
+      if (treeCommitments) {
+        const onChainCommitment = treeCommitments.get(decrypted.leafIndex);
+        if (onChainCommitment !== undefined && onChainCommitment !== commitment) {
+          console.warn(`Commitment mismatch for leaf ${decrypted.leafIndex} in tree ${note.treeIndex}`);
+          continue;
+        }
+      }
+
+      foundUTXOs.push({
+        value: decrypted.value.toString(),
+        mintTokenAddress: decrypted.mintTokenAddress.toString(),
+        owner: walletKeys.owner.toString(),
+        secret: decrypted.secret.toString(),
+        commitment: commitment.toString(),
+        leafIndex: decrypted.leafIndex,
+        treeIndex: note.treeIndex,
+        mint: note.mint,
+        spent: false,
+        createdTx: note.txSignature,
+        createdAt: new Date().toISOString(),
+      });
+    } catch (err) {
+      // Failed to decrypt - not our note, skip
+    }
+  }
+
+  return foundUTXOs;
+}
+
+/**
+ * Sync wallet UTXOs from relayer
+ * 
+ * This fetches all encrypted notes and attempts to decrypt them.
+ * Also checks which UTXOs have been spent.
+ */
+export async function syncUTXOs(
+  walletKeys: WalletKeys,
+  existingUTXOs: SerializableUTXO[],
+  relayerUrl?: string,
+  afterSlot?: string
+): Promise<{
+  newUTXOs: SerializableUTXO[];
+  spentUTXOs: string[]; // IDs of UTXOs that are now spent
+}> {
+  const client = getRelayerClient(relayerUrl);
+
+  // Fetch all notes since last sync
+  const notes = await client.getAllNotes(afterSlot);
+
+  // Build commitment map for verification (optional)
+  const pool = await client.getPool();
+  const commitments = new Map<number, Map<number, bigint>>();
+
+  // For each tree, fetch commitments
+  for (let treeIndex = 0; treeIndex <= pool.currentTreeIndex; treeIndex++) {
+    const leaves = await client.getCommitmentsForTree(treeIndex);
+    const treeMap = new Map<number, bigint>();
+    leaves.forEach((commitment, index) => {
+      treeMap.set(index, commitment);
+    });
+    commitments.set(treeIndex, treeMap);
+  }
+
+  // Scan notes for new UTXOs
+  const newUTXOs = scanNotesForUTXOs(
+    notes.map(n => ({
+      encryptedData: n.encryptedData,
+      treeIndex: n.treeIndex,
+      mint: n.mint,
+      txSignature: n.txSignature,
+    })),
+    walletKeys,
+    commitments
+  );
+
+  // Check which existing UTXOs have been spent
+  const unspentUTXOs = existingUTXOs.filter(u => !u.spent);
+  const nullifiersToCheck: string[] = [];
+  const utxoByNullifier = new Map<string, string>();
+
+  for (const utxo of unspentUTXOs) {
+    const commitment = BigInt(utxo.commitment);
+    const nullifier = computeNullifier(
+      walletKeys.spendingKey,
+      commitment,
+      utxo.leafIndex
+    );
+    const nullifierStr = nullifier.toString();
+    nullifiersToCheck.push(nullifierStr);
+    utxoByNullifier.set(nullifierStr, utxo.commitment); // Use commitment as ID
+  }
+
+  const spentUTXOs: string[] = [];
+
+  if (nullifiersToCheck.length > 0) {
+    const batchSize = 50;
+    for (let i = 0; i < nullifiersToCheck.length; i += batchSize) {
+      const batch = nullifiersToCheck.slice(i, i + batchSize);
+      const result = await client.checkNullifiersBatch(batch);
+
+      for (const r of result.results) {
+        if (r.spent) {
+          const utxoId = utxoByNullifier.get(r.nullifier);
+          if (utxoId) {
+            spentUTXOs.push(utxoId);
+          }
+        }
+      }
+    }
+  }
+
+  return { newUTXOs, spentUTXOs };
+}
+
+// ============================================================================
+// UTXO Selection
+// ============================================================================
+
+/**
+ * Select UTXOs for spending (greedy algorithm)
+ * 
+ * Selects the largest UTXOs first until the target amount is reached.
+ */
+export function selectUTXOs(
+  utxos: UTXO[],
+  targetAmount: bigint,
+  mint?: bigint
+): UTXO[] {
+  // Filter by mint if specified
+  const filtered = mint !== undefined
+    ? utxos.filter(u => u.mintTokenAddress === mint)
+    : utxos;
+
+  // Sort by value descending
+  const sorted = [...filtered].sort((a, b) => {
+    if (a.value > b.value) return -1;
+    if (a.value < b.value) return 1;
+    return 0;
+  });
+
+  const selected: UTXO[] = [];
+  let total = 0n;
+
+  for (const utxo of sorted) {
+    if (total >= targetAmount) break;
+    selected.push(utxo);
+    total += utxo.value;
+  }
+
+  if (total < targetAmount) {
+    throw new Error(
+      `Insufficient balance. Need ${targetAmount}, have ${total}`
+    );
+  }
+
+  return selected;
+}
+
+/**
+ * Calculate total balance of UTXOs
+ */
+export function calculateBalance(utxos: UTXO[], mint?: bigint): bigint {
+  const filtered = mint !== undefined
+    ? utxos.filter(u => u.mintTokenAddress === mint)
+    : utxos;
+
+  return filtered.reduce((sum, u) => sum + u.value, 0n);
+}
+
+