@hula-privacy/mixer 0.1.0

package/README.md

@@ -0,0 +1,290 @@
+# Hula Privacy SDK
+
+Complete toolkit for privacy transactions on Solana using ZK proofs and UTXOs.
+
+## Installation
+
+```bash
+npm install @hula/sdk
+# or
+bun add @hula/sdk
+```
+
+## Quick Start
+
+```typescript
+import { HulaWallet, initHulaSDK, getKeyDerivationMessage } from '@hula/sdk';
+
+// Initialize SDK (loads Poseidon hasher)
+await initHulaSDK();
+
+// Create wallet from Phantom signature (deterministic derivation)
+const message = getKeyDerivationMessage();
+const signature = await wallet.signMessage(message);
+const hulaWallet = await HulaWallet.fromSignature(signature, {
+  rpcUrl: 'https://api.devnet.solana.com',
+  relayerUrl: 'http://localhost:3001',
+});
+
+// Or create a new wallet with random keys
+const newWallet = await HulaWallet.create({
+  rpcUrl: 'https://api.devnet.solana.com',
+  relayerUrl: 'http://localhost:3001',
+});
+
+// Get wallet public identifier
+console.log('Owner hash:', hulaWallet.ownerHex);
+console.log('Encryption pubkey:', Buffer.from(hulaWallet.encryptionPublicKey).toString('hex'));
+```
+
+## Syncing UTXOs
+
+The wallet syncs with the relayer to discover your UTXOs from encrypted notes:
+
+```typescript
+// Sync wallet to find your UTXOs
+const result = await hulaWallet.sync((progress) => {
+  console.log(`Syncing: ${progress.stage} ${progress.current}/${progress.total}`);
+});
+
+console.log(`Found ${result.newUtxos} new UTXOs`);
+console.log(`Marked ${result.spentUtxos} UTXOs as spent`);
+
+// Check balance
+const balance = hulaWallet.getBalance(mintAddress);
+console.log('Private balance:', balance);
+```
+
+## Transactions
+
+### Deposit (Public → Private)
+
+```typescript
+const { transaction } = await hulaWallet.deposit(mintAddress, 1_000_000n);
+
+// Submit transaction using your preferred method
+// The transaction object contains proof, public inputs, etc.
+```
+
+### Transfer (Private → Private)
+
+```typescript
+// Get recipient's public info
+const recipientOwner = BigInt('0x...');  // Recipient's owner hash
+const recipientEncPubKey = new Uint8Array([...]); // Recipient's encryption pubkey
+
+const { transaction } = await hulaWallet.transfer(
+  mintAddress,
+  500_000n,
+  recipientOwner,
+  recipientEncPubKey
+);
+```
+
+### Withdraw (Private → Public)
+
+```typescript
+const recipientPubkey = new PublicKey('...');
+
+const { transaction } = await hulaWallet.withdraw(
+  mintAddress,
+  200_000n,
+  recipientPubkey
+);
+```
+
+## Low-Level API
+
+For more control, use the low-level functions directly:
+
+### Key Derivation
+
+```typescript
+import { generateSpendingKey, deriveKeys, initPoseidon } from '@hula/sdk';
+
+await initPoseidon();
+
+const spendingKey = generateSpendingKey();
+const keys = deriveKeys(spendingKey);
+
+console.log('Owner:', keys.owner.toString(16));
+console.log('Viewing key:', keys.viewingKey.toString(16));
+console.log('Encryption pubkey:', Buffer.from(keys.encryptionKeyPair.publicKey).toString('hex'));
+```
+
+### UTXO Management
+
+```typescript
+import { createUTXO, computeCommitment, computeNullifier } from '@hula/sdk';
+
+// Create a UTXO
+const utxo = createUTXO(
+  1_000_000n,        // value
+  mintBigInt,        // mint address as bigint
+  keys.owner,        // owner hash
+  0,                 // leaf index
+  0                  // tree index
+);
+
+// Compute commitment manually
+const commitment = computeCommitment(
+  utxo.value,
+  utxo.mintTokenAddress,
+  utxo.owner,
+  utxo.secret
+);
+
+// Compute nullifier for spending
+const nullifier = computeNullifier(
+  keys.spendingKey,
+  utxo.commitment,
+  utxo.leafIndex
+);
+```
+
+### Merkle Tree Operations
+
+```typescript
+import { 
+  fetchMerklePath, 
+  fetchMerkleRoot,
+  computeMerklePathFromLeaves,
+  getCurrentTreeIndex 
+} from '@hula/sdk';
+
+// Get current tree index
+const treeIndex = await getCurrentTreeIndex('http://localhost:3001');
+
+// Fetch merkle root
+const root = await fetchMerkleRoot(treeIndex);
+
+// Fetch merkle path for a specific leaf
+const path = await fetchMerklePath(treeIndex, leafIndex);
+
+// Or compute locally from leaves
+const leaves = [commitment1, commitment2, ...];
+const localPath = computeMerklePathFromLeaves(leafIndex, leaves);
+```
+
+### Relayer API
+
+```typescript
+import { RelayerClient, getRelayerClient } from '@hula/sdk';
+
+const client = getRelayerClient('http://localhost:3001');
+
+// Get pool state
+const pool = await client.getPool();
+console.log('Current tree:', pool.currentTreeIndex);
+console.log('Total commitments:', pool.commitmentCount);
+
+// Get leaves for a tree
+const leaves = await client.getAllLeavesForTree(0);
+
+// Check if nullifier is spent
+const { spent } = await client.checkNullifier(nullifierHex);
+
+// Get encrypted notes
+const notes = await client.getAllNotes();
+```
+
+### Proof Generation
+
+```typescript
+import { generateProof, setCircuitPaths } from '@hula/sdk';
+
+// Set circuit paths (if not in default locations)
+setCircuitPaths(
+  '/path/to/transaction.wasm',
+  '/path/to/transaction_final.zkey'
+);
+
+// Generate proof
+const { proof, publicSignals } = await generateProof(circuitInputs);
+```
+
+## Configuration
+
+### Circuit Files
+
+The SDK looks for circuit files in these locations:
+
+1. `./circuits/build/transaction_js/transaction.wasm`
+2. `./circuits/build/keys/transaction_final.zkey`
+3. `./assets/transaction.wasm` and `./assets/transaction_final.zkey`
+
+You can also set custom paths:
+
+```typescript
+import { setCircuitPaths } from '@hula/sdk';
+
+setCircuitPaths('/custom/path/transaction.wasm', '/custom/path/transaction.zkey');
+```
+
+### Default Relayer URL
+
+```typescript
+import { setDefaultRelayerUrl } from '@hula/sdk';
+
+setDefaultRelayerUrl('https://relayer.hulaprivacy.io');
+```
+
+## Types
+
+All types are exported for TypeScript users:
+
+```typescript
+import type {
+  UTXO,
+  SerializableUTXO,
+  WalletKeys,
+  EncryptedNote,
+  MerklePath,
+  CircuitInputs,
+  TransactionRequest,
+  BuiltTransaction,
+  HulaSDKConfig,
+} from '@hula/sdk';
+```
+
+## Building
+
+```bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Architecture
+
+```
+sdk/src/
+├── index.ts        # Main exports
+├── types.ts        # Type definitions
+├── constants.ts    # Program IDs, seeds, circuit params
+├── api.ts          # Relayer API client
+├── crypto.ts       # Poseidon, key derivation, encryption
+├── merkle.ts       # Merkle tree operations
+├── utxo.ts         # UTXO management
+├── proof.ts        # ZK proof generation
+├── transaction.ts  # Transaction building
+└── wallet.ts       # High-level wallet abstraction
+```
+
+## Security Considerations
+
+1. **Spending Key**: The spending key is the master secret. Never share it or store it insecurely.
+2. **Wallet Recovery**: Using `fromSignature()` allows deterministic recovery from a Solana wallet signature.
+3. **Local Storage**: When storing UTXOs locally, use appropriate encryption.
+4. **Note Encryption**: Encrypted notes allow recipients to discover UTXOs sent to them.
+
+## License
+
+MIT
+
+

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hula-privacy/mixer",
+  "version": "0.1.0",
+  "description": "Hula Privacy Protocol SDK - Complete toolkit for private transactions on Solana",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@coral-xyz/anchor": "^0.30.1",
+    "@noble/hashes": "^1.3.0",
+    "@solana/spl-token": "^0.4.9",
+    "@solana/web3.js": "^1.95.4",
+    "circomlibjs": "^0.1.7",
+    "snarkjs": "^0.7.5",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/snarkjs": "^0.7.8",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@coral-xyz/anchor": ">=0.29.0",
+    "@solana/web3.js": ">=1.90.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "solana",
+    "privacy",
+    "zk-snark",
+    "utxo",
+    "hula"
+  ],
+  "license": "MIT"
+}

package/src/api.ts

@@ -0,0 +1,276 @@
+/**
+ * Relayer API Client
+ * 
+ * Fetches data from the relayer with cursor-based pagination
+ */
+
+import type {
+  PaginatedResponse,
+  PoolData,
+  TreeData,
+  LeafData,
+  TransactionData,
+  NoteData,
+  StatsData,
+} from "./types";
+
+const DEFAULT_API_URL = "http://localhost:3001";
+
+/**
+ * API client for the Hula Privacy relayer
+ */
+export class RelayerClient {
+  private baseUrl: string;
+
+  constructor(baseUrl: string = DEFAULT_API_URL) {
+    this.baseUrl = baseUrl.replace(/\/$/, ""); // Remove trailing slash
+  }
+
+  private async fetch<T>(path: string, init?: RequestInit): Promise<T> {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        ...init?.headers,
+      },
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({ error: "Unknown error" })) as { error?: string };
+      throw new Error(errorData.error || `HTTP ${response.status}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  // ============================================================================
+  // Health & Stats
+  // ============================================================================
+
+  /**
+   * Health check
+   */
+  async health(): Promise<{ status: string; timestamp: string }> {
+    return this.fetch("/health");
+  }
+
+  /**
+   * Get protocol stats
+   */
+  async getStats(): Promise<StatsData> {
+    return this.fetch("/api/stats");
+  }
+
+  // ============================================================================
+  // Pool
+  // ============================================================================
+
+  /**
+   * Get pool data
+   */
+  async getPool(): Promise<PoolData> {
+    return this.fetch("/api/pool");
+  }
+
+  // ============================================================================
+  // Trees
+  // ============================================================================
+
+  /**
+   * Get all merkle trees
+   */
+  async getTrees(): Promise<{ trees: TreeData[] }> {
+    return this.fetch("/api/trees");
+  }
+
+  /**
+   * Get tree by index
+   */
+  async getTree(treeIndex: number): Promise<TreeData> {
+    return this.fetch(`/api/trees/${treeIndex}`);
+  }
+
+  // ============================================================================
+  // Leaves / Commitments
+  // ============================================================================
+
+  /**
+   * Get leaves with cursor pagination
+   */
+  async getLeaves(
+    cursor?: string,
+    limit?: number,
+    treeIndex?: number
+  ): Promise<PaginatedResponse<LeafData>> {
+    const params = new URLSearchParams();
+    if (cursor) params.set("cursor", cursor);
+    if (limit) params.set("limit", String(limit));
+    if (treeIndex !== undefined) params.set("treeIndex", String(treeIndex));
+
+    return this.fetch(`/api/leaves?${params}`);
+  }
+
+  /**
+   * Get leaves after a specific index (for syncing)
+   */
+  async getLeavesAfter(
+    treeIndex: number,
+    afterLeafIndex: number,
+    limit?: number
+  ): Promise<{
+    items: { treeIndex: number; leafIndex: number; commitment: string; slot: string }[];
+    hasMore: boolean;
+    lastLeafIndex: number;
+  }> {
+    const params = new URLSearchParams();
+    params.set("treeIndex", String(treeIndex));
+    params.set("afterLeafIndex", String(afterLeafIndex));
+    if (limit) params.set("limit", String(limit));
+
+    return this.fetch(`/api/leaves/after?${params}`);
+  }
+
+  /**
+   * Get all leaves for a tree (auto-paginated)
+   */
+  async getAllLeavesForTree(treeIndex: number): Promise<LeafData[]> {
+    const allLeaves: LeafData[] = [];
+    let cursor: string | undefined;
+
+    while (true) {
+      const response = await this.getLeaves(cursor, 100, treeIndex);
+      allLeaves.push(...response.items);
+
+      if (!response.hasMore || !response.nextCursor) break;
+      cursor = response.nextCursor;
+    }
+
+    return allLeaves;
+  }
+
+  /**
+   * Get all commitment values for a tree as bigints
+   */
+  async getCommitmentsForTree(treeIndex: number): Promise<bigint[]> {
+    const leaves = await this.getAllLeavesForTree(treeIndex);
+    // Sort by leafIndex to ensure correct order
+    leaves.sort((a, b) => a.leafIndex - b.leafIndex);
+    return leaves.map(l => BigInt(l.commitment));
+  }
+
+  // ============================================================================
+  // Transactions
+  // ============================================================================
+
+  /**
+   * Get transactions with cursor pagination
+   */
+  async getTransactions(
+    cursor?: string,
+    limit?: number,
+    mint?: string
+  ): Promise<PaginatedResponse<TransactionData>> {
+    const params = new URLSearchParams();
+    if (cursor) params.set("cursor", cursor);
+    if (limit) params.set("limit", String(limit));
+    if (mint) params.set("mint", mint);
+
+    return this.fetch(`/api/transactions?${params}`);
+  }
+
+  /**
+   * Get transaction by signature
+   */
+  async getTransaction(signature: string): Promise<TransactionData> {
+    return this.fetch(`/api/transactions/${signature}`);
+  }
+
+  // ============================================================================
+  // Nullifiers
+  // ============================================================================
+
+  /**
+   * Check if nullifier is spent
+   */
+  async checkNullifier(nullifier: string): Promise<{
+    nullifier: string;
+    spent: boolean;
+    spentAt?: string;
+  }> {
+    return this.fetch(`/api/nullifiers/check?nullifier=${encodeURIComponent(nullifier)}`);
+  }
+
+  /**
+   * Check multiple nullifiers at once
+   */
+  async checkNullifiersBatch(
+    nullifiers: string[]
+  ): Promise<{ results: { nullifier: string; spent: boolean }[] }> {
+    return this.fetch("/api/nullifiers/check-batch", {
+      method: "POST",
+      body: JSON.stringify({ nullifiers }),
+    });
+  }
+
+  // ============================================================================
+  // Encrypted Notes
+  // ============================================================================
+
+  /**
+   * Get encrypted notes with cursor pagination
+   */
+  async getNotes(
+    cursor?: string,
+    limit?: number,
+    afterSlot?: string
+  ): Promise<PaginatedResponse<NoteData>> {
+    const params = new URLSearchParams();
+    if (cursor) params.set("cursor", cursor);
+    if (limit) params.set("limit", String(limit));
+    if (afterSlot) params.set("afterSlot", afterSlot);
+
+    return this.fetch(`/api/notes?${params}`);
+  }
+
+  /**
+   * Get all notes (auto-paginated)
+   */
+  async getAllNotes(afterSlot?: string): Promise<NoteData[]> {
+    const allNotes: NoteData[] = [];
+    let cursor: string | undefined;
+
+    while (true) {
+      const response = await this.getNotes(cursor, 100, afterSlot);
+      allNotes.push(...response.items);
+
+      if (!response.hasMore || !response.nextCursor) break;
+      cursor = response.nextCursor;
+    }
+
+    return allNotes;
+  }
+}
+
+// Default singleton instance
+let defaultClient: RelayerClient | null = null;
+
+/**
+ * Get or create the default relayer client
+ */
+export function getRelayerClient(url?: string): RelayerClient {
+  if (url) {
+    return new RelayerClient(url);
+  }
+  if (!defaultClient) {
+    defaultClient = new RelayerClient();
+  }
+  return defaultClient;
+}
+
+/**
+ * Set the default relayer URL
+ */
+export function setDefaultRelayerUrl(url: string): void {
+  defaultClient = new RelayerClient(url);
+}
+