@hula-privacy/mixer 0.1.0

package/src/constants.ts

@@ -0,0 +1,108 @@
+/**
+ * Constants for Hula Privacy Protocol
+ */
+
+import { PublicKey } from "@solana/web3.js";
+
+// ============================================================================
+// Program Constants
+// ============================================================================
+
+/** Hula Privacy Program ID */
+export const PROGRAM_ID = new PublicKey("tnJ9AAxNau3BRBTe7NzXpv8DeYyiogvGd8YPnCiuarA");
+
+/** Token 2022 Program ID */
+export const TOKEN_2022_PROGRAM_ID = new PublicKey(
+  "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
+);
+
+// ============================================================================
+// PDA Seeds
+// ============================================================================
+
+export const POOL_SEED = Buffer.from("hula_pool");
+export const VAULT_SEED = Buffer.from("vault");
+export const MERKLE_TREE_SEED = Buffer.from("merkle_tree");
+export const NULLIFIER_SEED = Buffer.from("nullifier");
+
+// ============================================================================
+// Circuit Parameters
+// ============================================================================
+
+/** Number of input UTXOs in circuit */
+export const NUM_INPUT_UTXOS = 2;
+
+/** Number of output UTXOs in circuit */
+export const NUM_OUTPUT_UTXOS = 2;
+
+/** Depth of merkle tree */
+export const MERKLE_TREE_DEPTH = 10;
+
+/** Maximum leaves per tree (2^DEPTH) */
+export const MAX_LEAVES = 1 << MERKLE_TREE_DEPTH;
+
+/** Size of proof in bytes */
+export const PROOF_SIZE = 256;
+
+// ============================================================================
+// Domain Separators (matching circuits/keys.circom)
+// ============================================================================
+
+export const DOMAIN_OWNER = 0n;
+export const DOMAIN_VIEWING = 1n;
+export const DOMAIN_NULLIFIER = 2n;
+export const DOMAIN_ENCRYPTION = 3n;
+
+// ============================================================================
+// Crypto Constants
+// ============================================================================
+
+/** BN254 field prime */
+export const FIELD_PRIME = BigInt(
+  "21888242871839275222246405745257275088548364400416034343698204186575808495617"
+);
+
+// ============================================================================
+// PDA Derivation Functions
+// ============================================================================
+
+/**
+ * Derive Pool PDA
+ */
+export function getPoolPDA(): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync([POOL_SEED], PROGRAM_ID);
+}
+
+/**
+ * Derive Merkle Tree PDA for a specific tree index
+ */
+export function getMerkleTreePDA(treeIndex: number = 0): [PublicKey, number] {
+  const treeIndexBuffer = Buffer.alloc(4);
+  treeIndexBuffer.writeUInt32LE(treeIndex, 0);
+  return PublicKey.findProgramAddressSync(
+    [MERKLE_TREE_SEED, treeIndexBuffer],
+    PROGRAM_ID
+  );
+}
+
+/**
+ * Derive Vault PDA for a specific mint
+ */
+export function getVaultPDA(mint: PublicKey): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync(
+    [VAULT_SEED, mint.toBytes()],
+    PROGRAM_ID
+  );
+}
+
+/**
+ * Derive Nullifier PDA for a nullifier hash
+ */
+export function getNullifierPDA(nullifier: Uint8Array): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync(
+    [NULLIFIER_SEED, nullifier],
+    PROGRAM_ID
+  );
+}
+
+

package/src/crypto.ts

@@ -0,0 +1,293 @@
+/**
+ * Cryptographic utilities for Hula Privacy Protocol
+ * 
+ * Includes Poseidon hashing, key derivation, and encryption
+ */
+
+import { buildPoseidon, type Poseidon } from "circomlibjs";
+import * as nacl from "tweetnacl";
+import { sha256 } from "@noble/hashes/sha256";
+import {
+  DOMAIN_OWNER,
+  DOMAIN_VIEWING,
+  DOMAIN_NULLIFIER,
+  DOMAIN_ENCRYPTION,
+  FIELD_PRIME,
+} from "./constants";
+import type { WalletKeys, EncryptedNote } from "./types";
+
+// ============================================================================
+// Poseidon Hasher
+// ============================================================================
+
+let poseidonInstance: Poseidon | null = null;
+
+/**
+ * Initialize Poseidon hasher (must be called once before using hash functions)
+ */
+export async function initPoseidon(): Promise<void> {
+  if (!poseidonInstance) {
+    poseidonInstance = await buildPoseidon();
+  }
+}
+
+/**
+ * Check if Poseidon is initialized
+ */
+export function isPoseidonInitialized(): boolean {
+  return poseidonInstance !== null;
+}
+
+/**
+ * Get Poseidon instance (throws if not initialized)
+ */
+export function getPoseidon(): Poseidon {
+  if (!poseidonInstance) {
+    throw new Error("Poseidon not initialized. Call initPoseidon() first.");
+  }
+  return poseidonInstance;
+}
+
+/**
+ * Poseidon hash of inputs
+ */
+export function poseidonHash(inputs: bigint[]): bigint {
+  const poseidon = getPoseidon();
+  const hash = poseidon(inputs.map(x => poseidon.F.e(x)));
+  return poseidon.F.toObject(hash);
+}
+
+// ============================================================================
+// Byte Conversion Utilities
+// ============================================================================
+
+/**
+ * Convert bytes to bigint (big-endian)
+ */
+export function bytesToBigInt(bytes: Uint8Array): bigint {
+  let result = 0n;
+  for (let i = 0; i < bytes.length; i++) {
+    result = (result << 8n) + BigInt(bytes[i]);
+  }
+  return result;
+}
+
+/**
+ * Convert bigint to bytes (big-endian)
+ */
+export function bigIntToBytes(value: bigint, length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  let v = value;
+  for (let i = length - 1; i >= 0; i--) {
+    bytes[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return bytes;
+}
+
+/**
+ * Convert bigint to 32-byte array (big-endian)
+ */
+export function bigIntToBytes32(value: bigint): Uint8Array {
+  return bigIntToBytes(value, 32);
+}
+
+/**
+ * Convert hex string to bytes
+ */
+export function hexToBytes(hex: string): Uint8Array {
+  const cleaned = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(cleaned.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(cleaned.substr(i * 2, 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Convert bytes to hex string
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Convert PublicKey to bigint
+ */
+export function pubkeyToBigInt(pubkey: { toBytes(): Uint8Array }): bigint {
+  return bytesToBigInt(pubkey.toBytes());
+}
+
+// ============================================================================
+// Key Generation & Derivation
+// ============================================================================
+
+/**
+ * Generate a new random spending key
+ */
+export function generateSpendingKey(): bigint {
+  const randomBytes = nacl.randomBytes(32);
+  return bytesToBigInt(randomBytes) % (2n ** 253n);
+}
+
+/**
+ * Derive all wallet keys from spending key
+ */
+export function deriveKeys(spendingKey: bigint): WalletKeys {
+  const owner = poseidonHash([spendingKey, DOMAIN_OWNER]);
+  const viewingKey = poseidonHash([spendingKey, DOMAIN_VIEWING]);
+  const nullifierKey = poseidonHash([spendingKey, DOMAIN_NULLIFIER]);
+  const encryptionSeed = poseidonHash([spendingKey, DOMAIN_ENCRYPTION]);
+
+  // Derive X25519 keypair from encryption seed
+  const seedBytes = bigIntToBytes(encryptionSeed, 32);
+  const hashedSeed = sha256(seedBytes);
+  const encryptionKeyPair = nacl.box.keyPair.fromSecretKey(hashedSeed);
+
+  return {
+    spendingKey,
+    owner,
+    viewingKey,
+    nullifierKey,
+    encryptionKeyPair,
+  };
+}
+
+/**
+ * Derive spending key from wallet signature
+ * 
+ * This allows deterministic key derivation from a Solana wallet signature,
+ * enabling wallet recovery as long as the user has access to their wallet.
+ */
+export function deriveSpendingKeyFromSignature(signature: Uint8Array): bigint {
+  if (signature.length < 64) {
+    throw new Error("Signature must be at least 64 bytes");
+  }
+  
+  // Use SHA-256 of the signature to derive the spending key
+  const hash = sha256(signature);
+  return bytesToBigInt(hash) % FIELD_PRIME;
+}
+
+// ============================================================================
+// Note Encryption
+// ============================================================================
+
+/**
+ * Encrypt a note for a recipient
+ * 
+ * The note contains the UTXO data needed for the recipient to claim it.
+ */
+export function encryptNote(
+  noteData: {
+    value: bigint;
+    mintTokenAddress: bigint;
+    secret: bigint;
+    leafIndex: number;
+  },
+  recipientEncryptionPubKey: Uint8Array
+): EncryptedNote {
+  const payload = {
+    value: noteData.value.toString(),
+    mintTokenAddress: noteData.mintTokenAddress.toString(),
+    secret: noteData.secret.toString(),
+    leafIndex: noteData.leafIndex,
+  };
+
+  const message = new TextEncoder().encode(JSON.stringify(payload));
+  const nonce = nacl.randomBytes(24);
+  const ephemeralKeyPair = nacl.box.keyPair();
+
+  const ciphertext = nacl.box(
+    message,
+    nonce,
+    recipientEncryptionPubKey,
+    ephemeralKeyPair.secretKey
+  );
+
+  return {
+    ephemeralPubKey: ephemeralKeyPair.publicKey,
+    ciphertext,
+    nonce,
+  };
+}
+
+/**
+ * Decrypt an encrypted note
+ * 
+ * Returns null if decryption fails (not intended for this recipient)
+ */
+export function decryptNote(
+  encryptedNote: EncryptedNote,
+  encryptionSecretKey: Uint8Array
+): { value: bigint; mintTokenAddress: bigint; secret: bigint; leafIndex: number } | null {
+  try {
+    const decrypted = nacl.box.open(
+      encryptedNote.ciphertext,
+      encryptedNote.nonce,
+      encryptedNote.ephemeralPubKey,
+      encryptionSecretKey
+    );
+
+    if (!decrypted) return null;
+
+    const noteData = JSON.parse(new TextDecoder().decode(decrypted));
+    return {
+      value: BigInt(noteData.value),
+      mintTokenAddress: BigInt(noteData.mintTokenAddress),
+      secret: BigInt(noteData.secret),
+      leafIndex: noteData.leafIndex,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Serialize encrypted note for on-chain storage
+ */
+export function serializeEncryptedNote(note: EncryptedNote): Uint8Array {
+  const totalLength = 32 + 24 + 2 + note.ciphertext.length;
+  const buffer = new Uint8Array(totalLength);
+
+  buffer.set(note.ephemeralPubKey, 0);
+  buffer.set(note.nonce, 32);
+
+  // Ciphertext length (2 bytes, big-endian)
+  buffer[56] = (note.ciphertext.length >> 8) & 0xff;
+  buffer[57] = note.ciphertext.length & 0xff;
+
+  buffer.set(note.ciphertext, 58);
+
+  return buffer;
+}
+
+/**
+ * Deserialize encrypted note from on-chain data
+ */
+export function deserializeEncryptedNote(data: Uint8Array): EncryptedNote {
+  const ephemeralPubKey = data.slice(0, 32);
+  const nonce = data.slice(32, 56);
+  const ciphertextLength = (data[56] << 8) | data[57];
+  const ciphertext = data.slice(58, 58 + ciphertextLength);
+
+  return { ephemeralPubKey, nonce, ciphertext };
+}
+
+// ============================================================================
+// Formatting Utilities
+// ============================================================================
+
+/**
+ * Format a commitment/nullifier for display (truncated hex)
+ */
+export function formatCommitment(value: bigint | Uint8Array, length: number = 16): string {
+  if (value instanceof Uint8Array) {
+    return `0x${bytesToHex(value).slice(0, length)}...`;
+  }
+  return `0x${value.toString(16).padStart(64, "0").slice(0, length)}...`;
+}
+
+

package/src/index.ts

@@ -0,0 +1,185 @@
+/**
+ * Hula Privacy SDK
+ * 
+ * Complete toolkit for privacy transactions on Solana.
+ * 
+ * @example
+ * ```typescript
+ * import { HulaWallet, initHulaSDK } from '@hula/sdk';
+ * 
+ * // Initialize SDK
+ * await initHulaSDK();
+ * 
+ * // Create wallet from Phantom signature
+ * const signature = await phantom.signMessage(getKeyDerivationMessage());
+ * const wallet = await HulaWallet.fromSignature(signature, {
+ *   rpcUrl: 'https://api.devnet.solana.com',
+ *   relayerUrl: 'https://relayer.hulaprivacy.io',
+ * });
+ * 
+ * // Sync wallet to find your UTXOs
+ * await wallet.sync();
+ * 
+ * // Check balance
+ * const balance = wallet.getBalance(mintAddress);
+ * console.log('Private balance:', balance);
+ * 
+ * // Deposit tokens
+ * const depositTx = await wallet.deposit(mintAddress, 1000000n);
+ * 
+ * // Transfer privately
+ * const transferTx = await wallet.transfer(
+ *   mintAddress,
+ *   500000n,
+ *   recipientOwnerHash,
+ *   recipientEncryptionPubKey
+ * );
+ * 
+ * // Withdraw to public address
+ * const withdrawTx = await wallet.withdraw(
+ *   mintAddress,
+ *   200000n,
+ *   recipientPublicKey
+ * );
+ * ```
+ */
+
+// ============================================================================
+// Main Exports
+// ============================================================================
+
+// Wallet
+export { HulaWallet, initHulaSDK, getKeyDerivationMessage } from "./wallet";
+
+// Relayer API
+export { RelayerClient, getRelayerClient, setDefaultRelayerUrl } from "./api";
+
+// Crypto
+export {
+  initPoseidon,
+  isPoseidonInitialized,
+  getPoseidon,
+  poseidonHash,
+  deriveKeys,
+  generateSpendingKey,
+  deriveSpendingKeyFromSignature,
+  encryptNote,
+  decryptNote,
+  serializeEncryptedNote,
+  deserializeEncryptedNote,
+  bytesToBigInt,
+  bigIntToBytes,
+  bigIntToBytes32,
+  bytesToHex,
+  hexToBytes,
+  pubkeyToBigInt,
+  formatCommitment,
+} from "./crypto";
+
+// UTXO
+export {
+  computeCommitment,
+  computeNullifier,
+  computeNullifierFromKeys,
+  createUTXO,
+  createDummyUTXO,
+  serializeUTXO,
+  deserializeUTXO,
+  scanNotesForUTXOs,
+  syncUTXOs,
+  selectUTXOs,
+  calculateBalance,
+} from "./utxo";
+
+// Merkle
+export {
+  computeZeros,
+  getZeroAtLevel,
+  getEmptyTreeRoot,
+  computeMerklePathFromLeaves,
+  computeMerkleRoot,
+  verifyMerklePath,
+  fetchMerklePath,
+  fetchMerkleRoot,
+  getNextLeafIndex,
+  getCurrentTreeIndex,
+} from "./merkle";
+
+// Proof
+export {
+  setCircuitPaths,
+  getCircuitPaths,
+  verifyCircuitFiles,
+  parseProof,
+  generateProof,
+  generateProofInMemory,
+} from "./proof";
+
+// Transaction
+export {
+  buildTransaction,
+  buildTransactionAccounts,
+  toAnchorPublicInputs,
+} from "./transaction";
+
+// Constants
+export {
+  PROGRAM_ID,
+  TOKEN_2022_PROGRAM_ID,
+  POOL_SEED,
+  VAULT_SEED,
+  MERKLE_TREE_SEED,
+  NULLIFIER_SEED,
+  NUM_INPUT_UTXOS,
+  NUM_OUTPUT_UTXOS,
+  MERKLE_TREE_DEPTH,
+  MAX_LEAVES,
+  PROOF_SIZE,
+  DOMAIN_OWNER,
+  DOMAIN_VIEWING,
+  DOMAIN_NULLIFIER,
+  DOMAIN_ENCRYPTION,
+  FIELD_PRIME,
+  getPoolPDA,
+  getMerkleTreePDA,
+  getVaultPDA,
+  getNullifierPDA,
+} from "./constants";
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type {
+  // Core types
+  UTXO,
+  SerializableUTXO,
+  WalletKeys,
+  EncryptedNote,
+  
+  // Merkle types
+  MerklePath,
+  LeafData,
+  
+  // Transaction types
+  CircuitInputs,
+  PublicInputs,
+  OutputSpec,
+  TransactionRequest,
+  BuiltTransaction,
+  
+  // API types
+  PaginatedResponse,
+  PoolData,
+  TreeData,
+  TransactionData,
+  NoteData,
+  StatsData,
+  
+  // Config types
+  HulaSDKConfig,
+  SyncProgress,
+  SyncResult,
+} from "./types";
+
+