@veil-cash/sdk 0.1.0

package/src/transaction.ts

@@ -0,0 +1,260 @@
+/**
+ * Transaction preparation for Veil SDK
+ * Core function to build ZK proofs for withdrawals and transfers
+ */
+
+import { buildMerkleTree, MERKLE_TREE_HEIGHT } from './merkle.js';
+import { prove, selectCircuit, type ProofInput } from './prover.js';
+import { toFixedHex, getExtDataHash, shuffle, FIELD_SIZE } from './utils.js';
+import { Utxo } from './utxo.js';
+
+/**
+ * External data for a transaction (sent alongside proof)
+ */
+export interface ExtData {
+  recipient: string;
+  extAmount: string;
+  relayer: string;
+  fee: string;
+  encryptedOutput1: string;
+  encryptedOutput2: string;
+}
+
+/**
+ * Proof arguments for on-chain verification
+ */
+export interface ProofArgs {
+  proof: string;
+  root: string;
+  inputNullifiers: string[];
+  outputCommitments: string[];
+  publicAmount: string;
+  extDataHash: string;
+}
+
+/**
+ * Result of preparing a transaction
+ */
+export interface TransactionResult {
+  args: ProofArgs;
+  extData: ExtData;
+}
+
+/**
+ * Parameters for preparing a transaction
+ */
+export interface PrepareTransactionParams {
+  /** All commitments from the merkle tree (from pool contract) */
+  commitments: (string | bigint)[];
+  /** Input UTXOs to spend */
+  inputs?: Utxo[];
+  /** Output UTXOs to create */
+  outputs?: Utxo[];
+  /** Transaction fee (usually 0 for relay) */
+  fee?: bigint | number;
+  /** Recipient address for withdrawals (0x0 for transfers) */
+  recipient?: string | bigint | number;
+  /** Relayer address (0x0 for now) */
+  relayer?: string | bigint | number;
+  /** Optional progress callback */
+  onProgress?: (stage: string, detail?: string) => void;
+}
+
+/**
+ * Internal function to generate proof
+ */
+interface GetProofParams {
+  inputs: Utxo[];
+  outputs: Utxo[];
+  tree: ReturnType<typeof buildMerkleTree> extends Promise<infer T> ? T : never;
+  extAmount: bigint;
+  fee: bigint;
+  recipient: string | bigint;
+  relayer: string | bigint;
+  onProgress?: (stage: string, detail?: string) => void;
+}
+
+async function getProof({
+  inputs,
+  outputs,
+  tree,
+  extAmount,
+  fee,
+  recipient,
+  relayer,
+  onProgress,
+}: GetProofParams): Promise<TransactionResult> {
+  // Shuffle inputs and outputs for privacy
+  inputs = shuffle([...inputs]);
+  outputs = shuffle([...outputs]);
+
+  onProgress?.('Building merkle paths...');
+  
+  const inputMerklePathIndices: number[] = [];
+  const inputMerklePathElements: (bigint | number)[][] = [];
+
+  // Get merkle path for each input
+  for (const input of inputs) {
+    if (input.amount > 0n) {
+      const inputIndex = tree.indexOf(toFixedHex(input.getCommitment()));
+      if (inputIndex < 0) {
+        throw new Error(`Input commitment ${toFixedHex(input.getCommitment())} was not found in merkle tree`);
+      }
+      input.index = inputIndex;
+      inputMerklePathIndices.push(inputIndex);
+      inputMerklePathElements.push(
+        tree.path(inputIndex).pathElements.map((el: string | number | bigint) => BigInt(el))
+      );
+    } else {
+      // Empty input (padding) - use zero path
+      inputMerklePathIndices.push(0);
+      inputMerklePathElements.push(new Array(tree.levels).fill(0));
+    }
+  }
+
+  onProgress?.('Encrypting outputs...');
+
+  // Build external data
+  const extData: ExtData = {
+    recipient: toFixedHex(recipient, 20),
+    extAmount: extAmount.toString(),
+    relayer: toFixedHex(relayer, 20),
+    fee: fee.toString(),
+    encryptedOutput1: outputs[0].encrypt(),
+    encryptedOutput2: outputs[1].encrypt(),
+  };
+
+  // Calculate extDataHash using raw values
+  const extDataHashInput = {
+    recipient: recipient,
+    extAmount: extAmount,
+    relayer: relayer,
+    fee: fee,
+    encryptedOutput1: extData.encryptedOutput1,
+    encryptedOutput2: extData.encryptedOutput2,
+  };
+  const extDataHash = getExtDataHash(extDataHashInput);
+
+  // Build proof input
+  const proofInput: ProofInput = {
+    root: BigInt(tree.root()),
+    inputNullifier: inputs.map((x) => x.getNullifier()),
+    outputCommitment: outputs.map((x) => x.getCommitment()),
+    publicAmount: ((BigInt(extAmount) - BigInt(fee) + FIELD_SIZE) % FIELD_SIZE).toString(),
+    extDataHash,
+
+    // Input UTXO data
+    inAmount: inputs.map((x) => x.amount),
+    inPrivateKey: inputs.map((x) => x.keypair.privkey),
+    inBlinding: inputs.map((x) => x.blinding),
+    inPathIndices: inputMerklePathIndices,
+    inPathElements: inputMerklePathElements,
+
+    // Output UTXO data
+    outAmount: outputs.map((x) => x.amount),
+    outBlinding: outputs.map((x) => x.blinding),
+    outPubkey: outputs.map((x) => x.keypair.pubkey),
+  };
+
+  onProgress?.('Generating ZK proof...', `${inputs.length} inputs`);
+
+  // Select circuit based on input count and generate proof
+  const circuitName = selectCircuit(inputs.length);
+  const proof = await prove(proofInput, circuitName);
+
+  // Build proof arguments for on-chain verification
+  const args: ProofArgs = {
+    proof,
+    root: toFixedHex(proofInput.root),
+    inputNullifiers: inputs.map((x) => toFixedHex(x.getNullifier())),
+    outputCommitments: outputs.map((x) => toFixedHex(x.getCommitment())),
+    publicAmount: toFixedHex(proofInput.publicAmount),
+    extDataHash: toFixedHex(extDataHash),
+  };
+
+  onProgress?.('Proof generated successfully');
+
+  return {
+    args,
+    extData,
+  };
+}
+
+/**
+ * Prepare a transaction (withdrawal or transfer)
+ * Builds the ZK proof and external data needed for on-chain execution
+ * 
+ * @param params - Transaction parameters
+ * @returns Proof arguments and external data
+ * 
+ * @example
+ * ```typescript
+ * // Withdrawal: send funds to external address
+ * const result = await prepareTransaction({
+ *   commitments: poolCommitments,
+ *   inputs: [utxo1, utxo2],
+ *   outputs: [changeUtxo], // Just change
+ *   recipient: '0x1234...', // Withdrawal address
+ *   fee: 0,
+ *   relayer: '0x0000...',
+ * });
+ * 
+ * // Transfer: move funds to another Veil user
+ * const result = await prepareTransaction({
+ *   commitments: poolCommitments,
+ *   inputs: [utxo1],
+ *   outputs: [recipientUtxo, changeUtxo],
+ *   recipient: 0, // No external recipient
+ *   fee: 0,
+ *   relayer: '0x0000...',
+ * });
+ * ```
+ */
+export async function prepareTransaction({
+  commitments,
+  inputs = [],
+  outputs = [],
+  fee = 0,
+  recipient = 0,
+  relayer = 0,
+  onProgress,
+}: PrepareTransactionParams): Promise<TransactionResult> {
+  // Validate input/output counts
+  if (inputs.length > 16 || outputs.length > 2) {
+    throw new Error('Incorrect inputs/outputs count. Maximum: 16 inputs, 2 outputs.');
+  }
+
+  // Pad inputs to 2 or 16 with empty UTXOs
+  while (inputs.length !== 2 && inputs.length < 16) {
+    inputs.push(new Utxo());
+  }
+
+  // Pad outputs to 2 with empty UTXOs
+  while (outputs.length < 2) {
+    outputs.push(new Utxo());
+  }
+
+  // Calculate external amount (fee + outputs - inputs)
+  // Positive = withdrawal, Negative = deposit
+  const extAmount = BigInt(fee) +
+    outputs.reduce((sum, x) => sum + x.amount, 0n) -
+    inputs.reduce((sum, x) => sum + x.amount, 0n);
+
+  onProgress?.('Building merkle tree...');
+
+  // Build merkle tree and generate proof
+  const tree = await buildMerkleTree(commitments);
+
+  const result = await getProof({
+    inputs,
+    outputs,
+    tree,
+    extAmount,
+    fee: BigInt(fee),
+    recipient: String(recipient),
+    relayer: String(relayer),
+    onProgress,
+  });
+
+  return result;
+}

package/src/transfer.ts

@@ -0,0 +1,462 @@
+/**
+ * Transfer functions for Veil SDK
+ * Build ZK proofs to transfer funds privately within the pool
+ */
+
+import { createPublicClient, http, parseUnits } from 'viem';
+import { base } from 'viem/chains';
+import { getAddresses, POOL_CONFIG } from './addresses.js';
+import { POOL_ABI, ENTRY_ABI } from './abi.js';
+import { Keypair } from './keypair.js';
+import { Utxo } from './utxo.js';
+import { getPrivateBalance } from './balance.js';
+import { prepareTransaction } from './transaction.js';
+import { submitRelay } from './relay.js';
+import { selectUtxosForWithdraw } from './withdraw.js';
+import type { 
+  BuildTransferProofOptions, 
+  ProofBuildResult, 
+  TransferResult,
+} from './types.js';
+
+/**
+ * Check if a recipient is registered and get their deposit key
+ * 
+ * @param address - Address to check
+ * @param rpcUrl - Optional RPC URL
+ * @returns Whether registered and their deposit key if so
+ * 
+ * @example
+ * ```typescript
+ * const { isRegistered, depositKey } = await checkRecipientRegistration('0x1234...');
+ * if (!isRegistered) {
+ *   console.log('Recipient needs to register first');
+ * }
+ * ```
+ */
+export async function checkRecipientRegistration(
+  address: `0x${string}`,
+  rpcUrl?: string
+): Promise<{ isRegistered: boolean; depositKey?: string }> {
+  const addresses = getAddresses();
+  
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http(rpcUrl),
+  });
+
+  const depositKey = await publicClient.readContract({
+    address: addresses.entry,
+    abi: ENTRY_ABI,
+    functionName: 'depositKeys',
+    args: [address],
+  }) as string;
+
+  // If depositKey exists and is not empty, recipient is registered
+  const isRegistered = !!(depositKey && depositKey !== '0x' && depositKey.length > 2);
+
+  return {
+    isRegistered,
+    depositKey: isRegistered ? depositKey : undefined,
+  };
+}
+
+/**
+ * Fetch all commitments from the pool contract
+ */
+async function fetchCommitments(
+  rpcUrl: string | undefined,
+  poolAddress: `0x${string}`,
+  onProgress?: (stage: string, detail?: string) => void
+): Promise<string[]> {
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http(rpcUrl),
+  });
+
+  onProgress?.('Fetching commitment count...');
+  const nextIndex = await publicClient.readContract({
+    address: poolAddress,
+    abi: POOL_ABI,
+    functionName: 'nextIndex',
+  }) as number;
+
+  if (nextIndex === 0) {
+    return [];
+  }
+
+  const BATCH_SIZE = 5000;
+  const commitments: string[] = [];
+  const totalBatches = Math.ceil(nextIndex / BATCH_SIZE);
+
+  for (let start = 0; start < nextIndex; start += BATCH_SIZE) {
+    const end = Math.min(start + BATCH_SIZE, nextIndex);
+    const batchNum = Math.floor(start / BATCH_SIZE) + 1;
+    onProgress?.('Fetching commitments', `batch ${batchNum}/${totalBatches}`);
+
+    const batch = await publicClient.readContract({
+      address: poolAddress,
+      abi: POOL_ABI,
+      functionName: 'getCommitments',
+      args: [BigInt(start), BigInt(end)],
+    }) as `0x${string}`[];
+
+    commitments.push(...batch.map(c => c.toString()));
+  }
+
+  return commitments;
+}
+
+/**
+ * Build a transfer proof
+ * 
+ * This function:
+ * 1. Verifies the recipient is registered
+ * 2. Fetches the sender's unspent UTXOs
+ * 3. Selects UTXOs to cover the transfer amount
+ * 4. Creates output UTXOs for recipient and change
+ * 5. Builds the ZK proof
+ * 
+ * @param options - Transfer options
+ * @returns Proof data ready for relay submission
+ * 
+ * @example
+ * ```typescript
+ * const senderKeypair = new Keypair(process.env.VEIL_KEY);
+ * const proof = await buildTransferProof({
+ *   amount: '0.1',
+ *   recipientAddress: '0x1234...',
+ *   senderKeypair,
+ * });
+ * ```
+ */
+export async function buildTransferProof(
+  options: BuildTransferProofOptions
+): Promise<ProofBuildResult> {
+  const {
+    amount,
+    recipientAddress,
+    senderKeypair,
+    rpcUrl,
+    onProgress,
+  } = options;
+
+  const addresses = getAddresses();
+  const poolConfig = POOL_CONFIG.eth;
+  const poolAddress = addresses.ethPool;
+
+  // 1. Check recipient is registered and get their deposit key
+  onProgress?.('Checking recipient registration...');
+  const { isRegistered, depositKey } = await checkRecipientRegistration(
+    recipientAddress,
+    rpcUrl
+  );
+
+  if (!isRegistered || !depositKey) {
+    throw new Error(`Recipient ${recipientAddress} is not registered. They need to register first.`);
+  }
+
+  // 2. Get sender's unspent UTXOs
+  onProgress?.('Fetching your UTXOs...');
+  const balanceResult = await getPrivateBalance({
+    keypair: senderKeypair,
+    rpcUrl,
+    onProgress,
+  });
+
+  const unspentUtxoInfos = balanceResult.utxos.filter(u => !u.isSpent);
+  if (unspentUtxoInfos.length === 0) {
+    throw new Error('No unspent UTXOs available for transfer');
+  }
+
+  // Re-decrypt UTXOs to get full Utxo objects
+  onProgress?.('Preparing UTXOs...');
+  
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http(rpcUrl),
+  });
+
+  const utxos: Utxo[] = [];
+  for (const utxoInfo of unspentUtxoInfos) {
+    const encryptedOutputs = await publicClient.readContract({
+      address: poolAddress,
+      abi: POOL_ABI,
+      functionName: 'getEncryptedOutputs',
+      args: [BigInt(utxoInfo.index), BigInt(utxoInfo.index + 1)],
+    }) as string[];
+
+    if (encryptedOutputs.length > 0) {
+      try {
+        const utxo = Utxo.decrypt(encryptedOutputs[0], senderKeypair);
+        utxo.index = utxoInfo.index;
+        utxos.push(utxo);
+      } catch {
+        // Skip if decryption fails
+      }
+    }
+  }
+
+  if (utxos.length === 0) {
+    throw new Error('Failed to decrypt UTXOs');
+  }
+
+  // 3. Select UTXOs for transfer
+  onProgress?.('Selecting UTXOs...');
+  const { selectedUtxos, changeAmount } = selectUtxosForWithdraw(
+    utxos,
+    amount,
+    poolConfig.decimals
+  );
+
+  // 4. Create output UTXOs
+  const outputs: Utxo[] = [];
+  const transferWei = parseUnits(amount, poolConfig.decimals);
+
+  // Create recipient UTXO using their deposit key
+  const recipientKeypair = Keypair.fromString(depositKey);
+  const recipientUtxo = new Utxo({
+    amount: transferWei,
+    keypair: recipientKeypair,
+  });
+  outputs.push(recipientUtxo);
+
+  // Create change UTXO for sender if needed
+  if (changeAmount > 0n) {
+    const changeUtxo = new Utxo({
+      amount: changeAmount,
+      keypair: senderKeypair,
+    });
+    outputs.push(changeUtxo);
+  }
+
+  // 5. Fetch all commitments from pool
+  const commitments = await fetchCommitments(rpcUrl, poolAddress, onProgress);
+
+  // 6. Build the ZK proof
+  // For transfers, recipient field is 0x0 (no external withdrawal)
+  onProgress?.('Building ZK proof...');
+  const result = await prepareTransaction({
+    commitments,
+    inputs: selectedUtxos,
+    outputs,
+    fee: 0,
+    recipient: '0x0000000000000000000000000000000000000000',
+    relayer: '0x0000000000000000000000000000000000000000',
+    onProgress,
+  });
+
+  return {
+    proofArgs: {
+      proof: result.args.proof,
+      root: result.args.root,
+      inputNullifiers: result.args.inputNullifiers,
+      outputCommitments: result.args.outputCommitments as [string, string],
+      publicAmount: result.args.publicAmount,
+      extDataHash: result.args.extDataHash,
+    },
+    extData: result.extData,
+    inputCount: selectedUtxos.length,
+    outputCount: outputs.length,
+    amount,
+  };
+}
+
+/**
+ * Execute a transfer by building proof and submitting to relay
+ * 
+ * @param options - Transfer options
+ * @returns Transfer result with transaction hash
+ * 
+ * @example
+ * ```typescript
+ * const senderKeypair = new Keypair(process.env.VEIL_KEY);
+ * const result = await transfer({
+ *   amount: '0.1',
+ *   recipientAddress: '0x1234...',
+ *   senderKeypair,
+ * });
+ * 
+ * console.log(`Transfer tx: ${result.transactionHash}`);
+ * ```
+ */
+export async function transfer(
+  options: BuildTransferProofOptions
+): Promise<TransferResult> {
+  const { amount, recipientAddress, onProgress } = options;
+
+  // Build the proof
+  const proof = await buildTransferProof(options);
+
+  // Submit to relay
+  onProgress?.('Submitting to relay...');
+  const relayResult = await submitRelay({
+    type: 'transfer',
+    pool: 'eth',
+    proofArgs: proof.proofArgs,
+    extData: proof.extData,
+    metadata: {
+      amount,
+      recipient: recipientAddress,
+      inputUtxoCount: proof.inputCount,
+      outputUtxoCount: proof.outputCount,
+    },
+  });
+
+  return {
+    success: relayResult.success,
+    transactionHash: relayResult.transactionHash,
+    blockNumber: relayResult.blockNumber,
+    amount,
+    recipient: recipientAddress,
+  };
+}
+
+/**
+ * Merge UTXOs by doing a self-transfer
+ * This consolidates multiple small UTXOs into fewer larger ones
+ * 
+ * Unlike regular transfers, merge doesn't need a recipient address - 
+ * it uses the sender's keypair directly to create the output UTXO.
+ * 
+ * @param options - Merge options
+ * @returns Transfer result
+ * 
+ * @example
+ * ```typescript
+ * const keypair = new Keypair(process.env.VEIL_KEY);
+ * const result = await mergeUtxos({
+ *   amount: '0.5', // Total amount to consolidate
+ *   keypair,
+ * });
+ * ```
+ */
+export async function mergeUtxos(options: {
+  amount: string;
+  keypair: Keypair;
+  rpcUrl?: string;
+  onProgress?: (stage: string, detail?: string) => void;
+}): Promise<TransferResult> {
+  const { amount, keypair, rpcUrl, onProgress } = options;
+
+  const addresses = getAddresses();
+  const poolConfig = POOL_CONFIG.eth;
+  const poolAddress = addresses.ethPool;
+
+  // 1. Get sender's unspent UTXOs
+  onProgress?.('Fetching your UTXOs...');
+  const balanceResult = await getPrivateBalance({
+    keypair,
+    rpcUrl,
+    onProgress,
+  });
+
+  const unspentUtxoInfos = balanceResult.utxos.filter(u => !u.isSpent);
+  if (unspentUtxoInfos.length === 0) {
+    throw new Error('No unspent UTXOs available for merge');
+  }
+
+  // Re-decrypt UTXOs to get full Utxo objects
+  onProgress?.('Preparing UTXOs...');
+  
+  const publicClient = createPublicClient({
+    chain: base,
+    transport: http(rpcUrl),
+  });
+
+  const utxos: Utxo[] = [];
+  for (const utxoInfo of unspentUtxoInfos) {
+    const encryptedOutputs = await publicClient.readContract({
+      address: poolAddress,
+      abi: POOL_ABI,
+      functionName: 'getEncryptedOutputs',
+      args: [BigInt(utxoInfo.index), BigInt(utxoInfo.index + 1)],
+    }) as string[];
+
+    if (encryptedOutputs.length > 0) {
+      try {
+        const utxo = Utxo.decrypt(encryptedOutputs[0], keypair);
+        utxo.index = utxoInfo.index;
+        utxos.push(utxo);
+      } catch {
+        // Skip if decryption fails
+      }
+    }
+  }
+
+  if (utxos.length === 0) {
+    throw new Error('Failed to decrypt UTXOs');
+  }
+
+  // 2. Select UTXOs for merge
+  onProgress?.('Selecting UTXOs...');
+  const { selectedUtxos, changeAmount } = selectUtxosForWithdraw(
+    utxos,
+    amount,
+    poolConfig.decimals
+  );
+
+  // 3. Create output UTXO - use sender's keypair directly (self-transfer)
+  const outputs: Utxo[] = [];
+  const mergeWei = parseUnits(amount, poolConfig.decimals);
+
+  // Create merged UTXO using own keypair
+  const mergedUtxo = new Utxo({
+    amount: mergeWei,
+    keypair: keypair,
+  });
+  outputs.push(mergedUtxo);
+
+  // Create change UTXO if needed
+  if (changeAmount > 0n) {
+    const changeUtxo = new Utxo({
+      amount: changeAmount,
+      keypair: keypair,
+    });
+    outputs.push(changeUtxo);
+  }
+
+  // 4. Fetch all commitments from pool
+  const commitments = await fetchCommitments(rpcUrl, poolAddress, onProgress);
+
+  // 5. Build the ZK proof (recipient = 0x0 for self-transfer)
+  onProgress?.('Building ZK proof...');
+  const result = await prepareTransaction({
+    commitments,
+    inputs: selectedUtxos,
+    outputs,
+    fee: 0,
+    recipient: '0x0000000000000000000000000000000000000000',
+    relayer: '0x0000000000000000000000000000000000000000',
+    onProgress,
+  });
+
+  // 6. Submit to relay
+  onProgress?.('Submitting to relay...');
+  const relayResult = await submitRelay({
+    type: 'transfer',
+    pool: 'eth',
+    proofArgs: {
+      proof: result.args.proof,
+      root: result.args.root,
+      inputNullifiers: result.args.inputNullifiers,
+      outputCommitments: result.args.outputCommitments as [string, string],
+      publicAmount: result.args.publicAmount,
+      extDataHash: result.args.extDataHash,
+    },
+    extData: result.extData,
+    metadata: {
+      amount,
+      inputUtxoCount: selectedUtxos.length,
+      outputUtxoCount: outputs.length,
+    },
+  });
+
+  return {
+    success: relayResult.success,
+    transactionHash: relayResult.transactionHash,
+    blockNumber: relayResult.blockNumber,
+    amount,
+    recipient: 'self',
+  };
+}