@hula-privacy/mixer 0.1.0

package/src/wallet.ts

@@ -0,0 +1,475 @@
+/**
+ * Wallet management for Hula Privacy Protocol
+ * 
+ * High-level wallet abstraction that manages keys, UTXOs, and syncing
+ */
+
+import { PublicKey, Connection, Keypair, type TransactionInstruction } from "@solana/web3.js";
+import type { Program } from "@coral-xyz/anchor";
+
+import {
+  initPoseidon,
+  isPoseidonInitialized,
+  deriveKeys,
+  generateSpendingKey,
+  deriveSpendingKeyFromSignature,
+  pubkeyToBigInt,
+} from "./crypto";
+import { syncUTXOs, deserializeUTXO, selectUTXOs, calculateBalance } from "./utxo";
+import { buildTransaction, buildTransactionAccounts, toAnchorPublicInputs } from "./transaction";
+import { getRelayerClient, setDefaultRelayerUrl } from "./api";
+import type {
+  WalletKeys,
+  UTXO,
+  SerializableUTXO,
+  HulaSDKConfig,
+  TransactionRequest,
+  SyncProgress,
+  SyncResult,
+} from "./types";
+
+// ============================================================================
+// HulaWallet Class
+// ============================================================================
+
+/**
+ * Hula Privacy Wallet
+ * 
+ * High-level abstraction for managing privacy transactions
+ */
+export class HulaWallet {
+  private connection: Connection;
+  private relayerUrl: string;
+  private keys: WalletKeys;
+  private utxos: SerializableUTXO[] = [];
+  private lastSyncedSlot: string = "0";
+  private initialized: boolean = false;
+
+  private constructor(
+    connection: Connection,
+    relayerUrl: string,
+    keys: WalletKeys
+  ) {
+    this.connection = connection;
+    this.relayerUrl = relayerUrl;
+    this.keys = keys;
+  }
+
+  /**
+   * Create a new wallet with a random spending key
+   */
+  static async create(config: HulaSDKConfig): Promise<HulaWallet> {
+    await initPoseidon();
+
+    const connection = new Connection(config.rpcUrl, "confirmed");
+    const relayerUrl = config.relayerUrl;
+    setDefaultRelayerUrl(relayerUrl);
+
+    const spendingKey = generateSpendingKey();
+    const keys = deriveKeys(spendingKey);
+
+    const wallet = new HulaWallet(connection, relayerUrl, keys);
+    wallet.initialized = true;
+    return wallet;
+  }
+
+  /**
+   * Create a wallet from an existing spending key
+   */
+  static async fromSpendingKey(
+    spendingKey: bigint,
+    config: HulaSDKConfig
+  ): Promise<HulaWallet> {
+    await initPoseidon();
+
+    const connection = new Connection(config.rpcUrl, "confirmed");
+    const relayerUrl = config.relayerUrl;
+    setDefaultRelayerUrl(relayerUrl);
+
+    const keys = deriveKeys(spendingKey);
+
+    const wallet = new HulaWallet(connection, relayerUrl, keys);
+    wallet.initialized = true;
+    return wallet;
+  }
+
+  /**
+   * Create a wallet from a Solana signature (deterministic derivation)
+   * 
+   * This allows recovery as long as the user can sign with their Solana wallet.
+   */
+  static async fromSignature(
+    signature: Uint8Array,
+    config: HulaSDKConfig
+  ): Promise<HulaWallet> {
+    await initPoseidon();
+
+    const connection = new Connection(config.rpcUrl, "confirmed");
+    const relayerUrl = config.relayerUrl;
+    setDefaultRelayerUrl(relayerUrl);
+
+    const spendingKey = deriveSpendingKeyFromSignature(signature);
+    const keys = deriveKeys(spendingKey);
+
+    const wallet = new HulaWallet(connection, relayerUrl, keys);
+    wallet.initialized = true;
+    return wallet;
+  }
+
+  // ============================================================================
+  // Getters
+  // ============================================================================
+
+  /**
+   * Get wallet's owner hash (public identifier)
+   */
+  get owner(): bigint {
+    return this.keys.owner;
+  }
+
+  /**
+   * Get wallet's owner hash as hex string
+   */
+  get ownerHex(): string {
+    return this.keys.owner.toString(16).padStart(64, "0");
+  }
+
+  /**
+   * Get wallet's encryption public key
+   */
+  get encryptionPublicKey(): Uint8Array {
+    return this.keys.encryptionKeyPair.publicKey;
+  }
+
+  /**
+   * Get spending key (CAREFUL - this is sensitive!)
+   */
+  get spendingKey(): bigint {
+    return this.keys.spendingKey;
+  }
+
+  /**
+   * Get all wallet keys
+   */
+  get walletKeys(): WalletKeys {
+    return this.keys;
+  }
+
+  // ============================================================================
+  // UTXO Management
+  // ============================================================================
+
+  /**
+   * Sync wallet with relayer
+   * 
+   * Fetches new encrypted notes and checks for spent UTXOs.
+   */
+  async sync(onProgress?: (progress: SyncProgress) => void): Promise<SyncResult> {
+    if (!this.initialized) {
+      throw new Error("Wallet not initialized");
+    }
+
+    onProgress?.({ stage: "notes", current: 0, total: 100 });
+
+    try {
+      const { newUTXOs, spentUTXOs } = await syncUTXOs(
+        this.keys,
+        this.utxos,
+        this.relayerUrl,
+        this.lastSyncedSlot !== "0" ? this.lastSyncedSlot : undefined
+      );
+
+      // Add new UTXOs
+      this.utxos.push(...newUTXOs);
+
+      // Mark spent UTXOs
+      for (const spentId of spentUTXOs) {
+        const utxo = this.utxos.find(u => u.commitment === spentId);
+        if (utxo) {
+          utxo.spent = true;
+        }
+      }
+
+      // Update last synced slot
+      const client = getRelayerClient(this.relayerUrl);
+      const stats = await client.getStats();
+      // Use current state as sync point
+      this.lastSyncedSlot = Date.now().toString(); // Simplified
+
+      onProgress?.({ stage: "complete", current: 100, total: 100 });
+
+      return {
+        newUtxos: newUTXOs.length,
+        spentUtxos: spentUTXOs.length,
+        errors: [],
+      };
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : "Sync failed";
+      onProgress?.({ stage: "complete", current: 100, total: 100 });
+      return {
+        newUtxos: 0,
+        spentUtxos: 0,
+        errors: [errorMsg],
+      };
+    }
+  }
+
+  /**
+   * Get all unspent UTXOs
+   */
+  getUnspentUTXOs(): UTXO[] {
+    return this.utxos
+      .filter(u => !u.spent)
+      .map(deserializeUTXO);
+  }
+
+  /**
+   * Get all UTXOs (including spent)
+   */
+  getAllUTXOs(): SerializableUTXO[] {
+    return [...this.utxos];
+  }
+
+  /**
+   * Get balance for a specific mint
+   */
+  getBalance(mint: PublicKey): bigint {
+    const mintBigInt = pubkeyToBigInt(mint);
+    const unspent = this.getUnspentUTXOs();
+    return calculateBalance(unspent, mintBigInt);
+  }
+
+  /**
+   * Import UTXOs (for wallet recovery or manual import)
+   */
+  importUTXOs(utxos: SerializableUTXO[]): void {
+    this.utxos.push(...utxos);
+  }
+
+  /**
+   * Export UTXOs for backup
+   */
+  exportUTXOs(): SerializableUTXO[] {
+    return [...this.utxos];
+  }
+
+  // ============================================================================
+  // Transaction Building
+  // ============================================================================
+
+  /**
+   * Deposit tokens into the privacy pool
+   */
+  async deposit(
+    mint: PublicKey,
+    amount: bigint
+  ): Promise<{
+    transaction: ReturnType<typeof buildTransaction> extends Promise<infer T> ? T : never;
+    instructions: TransactionInstruction[];
+  }> {
+    const tx = await buildTransaction(
+      {
+        mint,
+        depositAmount: amount,
+        outputs: [], // Change will be created automatically
+      },
+      this.keys,
+      this.relayerUrl
+    );
+
+    const { accounts, preInstructions, inputTreeIndex } = buildTransactionAccounts(
+      tx,
+      PublicKey.default, // Payer will be set by caller
+      mint,
+      amount,
+      0n
+    );
+
+    return { transaction: tx, instructions: preInstructions };
+  }
+
+  /**
+   * Transfer tokens privately
+   */
+  async transfer(
+    mint: PublicKey,
+    amount: bigint,
+    recipientOwner: bigint,
+    recipientEncryptionPubKey: Uint8Array
+  ): Promise<{
+    transaction: ReturnType<typeof buildTransaction> extends Promise<infer T> ? T : never;
+    instructions: TransactionInstruction[];
+  }> {
+    const mintBigInt = pubkeyToBigInt(mint);
+    const unspent = this.getUnspentUTXOs().filter(
+      u => u.mintTokenAddress === mintBigInt
+    );
+    const inputUtxos = selectUTXOs(unspent, amount, mintBigInt);
+
+    const tx = await buildTransaction(
+      {
+        mint,
+        inputUtxos,
+        outputs: [
+          {
+            owner: recipientOwner,
+            amount,
+            encryptionPubKey: recipientEncryptionPubKey,
+          },
+        ],
+      },
+      this.keys,
+      this.relayerUrl
+    );
+
+    const { preInstructions } = buildTransactionAccounts(
+      tx,
+      PublicKey.default,
+      mint,
+      0n,
+      0n
+    );
+
+    return { transaction: tx, instructions: preInstructions };
+  }
+
+  /**
+   * Withdraw tokens from the privacy pool to a public address
+   */
+  async withdraw(
+    mint: PublicKey,
+    amount: bigint,
+    recipient: PublicKey
+  ): Promise<{
+    transaction: ReturnType<typeof buildTransaction> extends Promise<infer T> ? T : never;
+    instructions: TransactionInstruction[];
+  }> {
+    const mintBigInt = pubkeyToBigInt(mint);
+    const unspent = this.getUnspentUTXOs().filter(
+      u => u.mintTokenAddress === mintBigInt
+    );
+    const inputUtxos = selectUTXOs(unspent, amount, mintBigInt);
+
+    const tx = await buildTransaction(
+      {
+        mint,
+        inputUtxos,
+        withdrawAmount: amount,
+        recipient,
+      },
+      this.keys,
+      this.relayerUrl
+    );
+
+    const { preInstructions } = buildTransactionAccounts(
+      tx,
+      PublicKey.default,
+      mint,
+      0n,
+      amount,
+      recipient
+    );
+
+    return { transaction: tx, instructions: preInstructions };
+  }
+
+  /**
+   * Build a custom transaction
+   */
+  async buildTransaction(request: Omit<TransactionRequest, "mint"> & { mint: PublicKey }): Promise<{
+    transaction: ReturnType<typeof buildTransaction> extends Promise<infer T> ? T : never;
+    instructions: TransactionInstruction[];
+  }> {
+    const tx = await buildTransaction(request, this.keys, this.relayerUrl);
+
+    const { preInstructions } = buildTransactionAccounts(
+      tx,
+      PublicKey.default,
+      request.mint,
+      request.depositAmount ?? 0n,
+      request.withdrawAmount ?? 0n,
+      request.recipient
+    );
+
+    return { transaction: tx, instructions: preInstructions };
+  }
+
+  // ============================================================================
+  // Transaction Submission
+  // ============================================================================
+
+  /**
+   * Submit a transaction using an Anchor program
+   * 
+   * @param program - Anchor program instance (any type to avoid IDL complexity)
+   * @param payer - Keypair for signing
+   * @param builtTx - Built transaction from buildTransaction()
+   * @param mint - Token mint
+   * @param depositAmount - Amount being deposited (if any)
+   * @param withdrawAmount - Amount being withdrawn (if any)
+   * @param recipient - Recipient for withdrawal (if any)
+   */
+  async submitTransaction(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    program: Program<any>,
+    payer: Keypair,
+    builtTx: Awaited<ReturnType<typeof buildTransaction>>,
+    mint: PublicKey,
+    depositAmount: bigint = 0n,
+    withdrawAmount: bigint = 0n,
+    recipient?: PublicKey
+  ): Promise<string> {
+    const { accounts, preInstructions, inputTreeIndex } = buildTransactionAccounts(
+      builtTx,
+      payer.publicKey,
+      mint,
+      depositAmount,
+      withdrawAmount,
+      recipient
+    );
+
+    const publicInputs = toAnchorPublicInputs(builtTx);
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tx = await (program.methods as any)
+      .transact(
+        inputTreeIndex,
+        Array.from(builtTx.proof),
+        publicInputs,
+        builtTx.encryptedNotes
+      )
+      .accounts(accounts)
+      .preInstructions(preInstructions)
+      .signers([payer])
+      .rpc();
+
+    // Mark input UTXOs as spent locally
+    for (const _utxo of builtTx.outputUtxos) {
+      // Find corresponding input UTXOs and mark spent
+      // (In practice, track by commitment)
+    }
+
+    return tx;
+  }
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Create a deterministic message for wallet key derivation
+ */
+export function getKeyDerivationMessage(): Uint8Array {
+  return new TextEncoder().encode("Hula Privacy Wallet Key Derivation v1");
+}
+
+/**
+ * Quick initialization for SDK usage
+ */
+export async function initHulaSDK(): Promise<void> {
+  if (!isPoseidonInitialized()) {
+    await initPoseidon();
+  }
+}
+