@veil-cash/sdk 0.1.0

package/src/keypair.ts

@@ -0,0 +1,170 @@
+/**
+ * Veil Keypair class
+ * Generates and manages keypairs for Veil deposits
+ */
+
+import { ethers } from 'ethers';
+import { poseidonHash, toFixedHex } from './utils.js';
+import type { EncryptedMessage } from './types.js';
+
+// eth-sig-util for x25519 encryption
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ethSigUtil = require('eth-sig-util');
+
+/**
+ * Pack encrypted message into hex string
+ */
+export function packEncryptedMessage(encryptedMessage: EncryptedMessage): string {
+  const nonceBuf = Buffer.from(encryptedMessage.nonce, 'base64');
+  const ephemPublicKeyBuf = Buffer.from(encryptedMessage.ephemPublicKey, 'base64');
+  const ciphertextBuf = Buffer.from(encryptedMessage.ciphertext, 'base64');
+  const messageBuff = Buffer.concat([
+    Buffer.alloc(24 - nonceBuf.length),
+    nonceBuf,
+    Buffer.alloc(32 - ephemPublicKeyBuf.length),
+    ephemPublicKeyBuf,
+    ciphertextBuf,
+  ]);
+  return '0x' + messageBuff.toString('hex');
+}
+
+/**
+ * Unpack hex string into encrypted message
+ */
+export function unpackEncryptedMessage(encryptedMessage: string): EncryptedMessage {
+  if (encryptedMessage.slice(0, 2) === '0x') {
+    encryptedMessage = encryptedMessage.slice(2);
+  }
+  const messageBuff = Buffer.from(encryptedMessage, 'hex');
+  const nonceBuf = messageBuff.slice(0, 24);
+  const ephemPublicKeyBuf = messageBuff.slice(24, 56);
+  const ciphertextBuf = messageBuff.slice(56);
+  return {
+    version: 'x25519-xsalsa20-poly1305',
+    nonce: nonceBuf.toString('base64'),
+    ephemPublicKey: ephemPublicKeyBuf.toString('base64'),
+    ciphertext: ciphertextBuf.toString('base64'),
+  };
+}
+
+/**
+ * Veil Keypair for deposits
+ * 
+ * A keypair consists of:
+ * - Private key: Random 32-byte Ethereum-style key
+ * - Public key: Poseidon hash of the private key
+ * - Encryption key: x25519 public key for encrypted outputs
+ * 
+ * The deposit key (used for registration) is: pubkey + encryptionKey
+ * 
+ * @example
+ * ```typescript
+ * // Generate new keypair
+ * const keypair = new Keypair();
+ * console.log(keypair.depositKey()); // Register this on-chain
+ * console.log(keypair.privkey);      // Store securely!
+ * 
+ * // Restore from existing private key
+ * const restored = new Keypair(savedPrivkey);
+ * ```
+ */
+export class Keypair {
+  /** Private key (null if created from public deposit key only) */
+  public privkey: string | null;
+  
+  /** Public key (Poseidon hash of private key) */
+  public pubkey: bigint;
+  
+  /** x25519 encryption public key */
+  public encryptionKey: string;
+
+  /**
+   * Create a new Keypair
+   * @param privkey - Optional private key. If not provided, generates a random one.
+   */
+  constructor(privkey: string = ethers.Wallet.createRandom().privateKey) {
+    this.privkey = privkey;
+    this.pubkey = poseidonHash([this.privkey]);
+    this.encryptionKey = ethSigUtil.getEncryptionPublicKey(privkey.slice(2));
+  }
+
+  /**
+   * Get the deposit key for this keypair
+   * This is what you register on-chain
+   * @returns Deposit key as hex string (130 chars with 0x prefix)
+   */
+  toString(): string {
+    return toFixedHex(this.pubkey) + Buffer.from(this.encryptionKey, 'base64').toString('hex');
+  }
+
+  /**
+   * Alias for toString() - returns the deposit key
+   * @returns Deposit key as hex string
+   */
+  depositKey(): string {
+    return this.toString();
+  }
+
+  /**
+   * Create a Keypair from a public deposit key (without private key)
+   * Useful for sending transfers to other users
+   * @param str - Deposit key (128 or 130 hex chars)
+   * @returns Keypair instance (privkey will be null)
+   */
+  static fromString(str: string): Keypair {
+    if (str.length === 130) {
+      str = str.slice(2);
+    }
+    if (str.length !== 128) {
+      throw new Error('Invalid deposit key length. Expected 128 hex chars (or 130 with 0x prefix)');
+    }
+    return Object.assign(new Keypair(), {
+      privkey: null,
+      pubkey: BigInt('0x' + str.slice(0, 64)),
+      encryptionKey: Buffer.from(str.slice(64, 128), 'hex').toString('base64'),
+    });
+  }
+
+  /**
+   * Sign a message using the private key
+   * @param commitment - Commitment hash
+   * @param merklePath - Merkle path
+   * @returns Signature as bigint
+   */
+  sign(commitment: string | number | bigint, merklePath: string | number | bigint): bigint {
+    if (!this.privkey) {
+      throw new Error('Cannot sign without private key');
+    }
+    return poseidonHash([this.privkey, commitment, merklePath]);
+  }
+
+  /**
+   * Encrypt data using the encryption key
+   * @param bytes - Data to encrypt
+   * @returns Encrypted data as hex string
+   */
+  encrypt(bytes: Buffer): string {
+    return packEncryptedMessage(
+      ethSigUtil.encrypt(
+        this.encryptionKey, 
+        { data: bytes.toString('base64') }, 
+        'x25519-xsalsa20-poly1305'
+      )
+    );
+  }
+
+  /**
+   * Decrypt data using the private key
+   * @param data - Encrypted data as hex string
+   * @returns Decrypted data as Buffer
+   */
+  decrypt(data: string): Buffer {
+    if (!this.privkey) {
+      throw new Error('Cannot decrypt without private key');
+    }
+    return Buffer.from(
+      ethSigUtil.decrypt(unpackEncryptedMessage(data), this.privkey.slice(2)), 
+      'base64'
+    );
+  }
+}

package/src/merkle.ts

@@ -0,0 +1,71 @@
+/**
+ * Merkle tree utilities for Veil SDK
+ * Build merkle trees from UTXO commitments for ZK proofs
+ */
+
+// @ts-ignore - fixed-merkle-tree doesn't have TypeScript declarations
+import MerkleTree from 'fixed-merkle-tree-legacy';
+import { poseidonHash2, toFixedHex } from './utils.js';
+
+/**
+ * Height of the merkle tree (matches on-chain contract)
+ */
+export const MERKLE_TREE_HEIGHT = 23;
+
+/**
+ * Build a merkle tree from UTXO commitments
+ * Uses Poseidon hash function compatible with on-chain verification
+ * 
+ * @param commitments - Array of commitment hashes (hex strings or bigints)
+ * @returns MerkleTree instance
+ * 
+ * @example
+ * ```typescript
+ * const commitments = await poolContract.getCommitments(0, 1000);
+ * const tree = await buildMerkleTree(commitments);
+ * const root = tree.root();
+ * ```
+ */
+export async function buildMerkleTree(commitments: (string | bigint)[]): Promise<MerkleTree> {
+  // Convert commitments to fixed hex format
+  const leaves = commitments.map((commitment) => toFixedHex(commitment));
+  
+  // Create hash function that uses Poseidon (matching on-chain)
+  const hashFunction = (left: string | bigint, right: string | bigint): string => {
+    const result = poseidonHash2(left, right);
+    return result.toString();
+  };
+  
+  const tree = new MerkleTree(MERKLE_TREE_HEIGHT, leaves, { hashFunction });
+  
+  return tree;
+}
+
+/**
+ * Get merkle path for a commitment
+ * 
+ * @param tree - Merkle tree instance
+ * @param commitment - Commitment to get path for
+ * @returns Path elements and indices
+ */
+export function getMerklePath(tree: MerkleTree, commitment: bigint | string): {
+  pathElements: bigint[];
+  pathIndices: number;
+} {
+  const commitmentHex = toFixedHex(commitment);
+  const index = tree.indexOf(commitmentHex);
+  
+  if (index < 0) {
+    throw new Error(`Commitment ${commitmentHex} not found in merkle tree`);
+  }
+  
+  const { pathElements } = tree.path(index);
+  
+  return {
+    pathElements: pathElements.map((el: string | number | bigint) => BigInt(el)),
+    pathIndices: index,
+  };
+}
+
+// Re-export MerkleTree type for consumers
+export type { MerkleTree };

package/src/prover.ts

@@ -0,0 +1,176 @@
+/**
+ * ZK Proof generation for Veil SDK
+ * Uses snarkjs groth16 to generate proofs for transactions
+ */
+
+import { groth16 } from 'snarkjs';
+import { toFixedHex } from './utils.js';
+import * as path from 'path';
+import * as fs from 'fs';
+import { fileURLToPath } from 'url';
+
+// Type definition for ffjavascript utils
+interface FFJavascriptUtils {
+  stringifyBigInts: (obj: unknown) => unknown;
+  unstringifyBigInts: (obj: unknown) => unknown;
+}
+
+// Dynamic import for ffjavascript
+let utils: FFJavascriptUtils | null = null;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const ffjavascript = require('ffjavascript');
+  utils = ffjavascript.utils;
+} catch {
+  console.warn('ffjavascript not found. Proof generation may not work.');
+}
+
+/**
+ * Input data for ZK proof generation
+ */
+export interface ProofInput {
+  root: bigint;
+  inputNullifier: bigint[];
+  outputCommitment: bigint[];
+  publicAmount: string;
+  extDataHash: bigint;
+  
+  // Input UTXO data
+  inAmount: bigint[];
+  inPrivateKey: (string | null)[];
+  inBlinding: bigint[];
+  inPathIndices: number[];
+  inPathElements: (bigint | number)[][];
+  
+  // Output UTXO data
+  outAmount: bigint[];
+  outBlinding: bigint[];
+  outPubkey: bigint[];
+}
+
+/**
+ * Raw snarkjs proof structure
+ */
+interface SnarkProof {
+  pi_a: [string, string];
+  pi_b: [[string, string], [string, string]];
+  pi_c: [string, string];
+}
+
+interface ProveResult {
+  proof: SnarkProof;
+  publicSignals: string[];
+}
+
+/**
+ * Find the keys directory containing circuit files
+ * Works in both development and installed package scenarios
+ */
+function findKeysDirectory(): string {
+  // Try multiple possible locations
+  const possiblePaths = [
+    // When running from package (installed via npm)
+    path.resolve(__dirname, '..', 'keys'),
+    path.resolve(__dirname, '..', '..', 'keys'),
+    // When running from source
+    path.resolve(process.cwd(), 'keys'),
+    // ESM module path
+  ];
+
+  // Try to get module directory for ESM
+  try {
+    const currentFilePath = fileURLToPath(import.meta.url);
+    const currentDir = path.dirname(currentFilePath);
+    possiblePaths.unshift(path.resolve(currentDir, '..', 'keys'));
+  } catch {
+    // Not ESM environment, use __dirname
+  }
+
+  for (const p of possiblePaths) {
+    if (fs.existsSync(p) && fs.existsSync(path.join(p, 'transaction2.wasm'))) {
+      return p;
+    }
+  }
+
+  throw new Error(
+    'Circuit keys not found. Expected to find keys/ directory with transaction2.wasm and transaction2.zkey files.'
+  );
+}
+
+/**
+ * Generate a ZK proof for a transaction
+ * 
+ * @param input - Proof input data
+ * @param circuitName - Circuit name (e.g., 'transaction2' or 'transaction16')
+ * @returns Serialized proof as hex string
+ * 
+ * @example
+ * ```typescript
+ * const proof = await prove(proofInput, 'transaction2');
+ * // Returns: 0x1234...abcd (256 bytes hex)
+ * ```
+ */
+export async function prove(input: ProofInput, circuitName: string): Promise<string> {
+  if (!utils) {
+    throw new Error('ffjavascript is required for proof generation. Please install it: npm install ffjavascript');
+  }
+
+  const keysDir = findKeysDirectory();
+  const wasmPath = path.join(keysDir, `${circuitName}.wasm`);
+  const zkeyPath = path.join(keysDir, `${circuitName}.zkey`);
+
+  // Verify files exist
+  if (!fs.existsSync(wasmPath)) {
+    throw new Error(`Circuit WASM file not found: ${wasmPath}`);
+  }
+  if (!fs.existsSync(zkeyPath)) {
+    throw new Error(`Circuit zkey file not found: ${zkeyPath}`);
+  }
+
+  // Generate proof using snarkjs
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result = await groth16.fullProve(
+    utils.stringifyBigInts(input) as any,
+    wasmPath,
+    zkeyPath,
+  );
+  const proof = result.proof as unknown as SnarkProof;
+
+  // Serialize proof to hex string format expected by on-chain verifier
+  // Format: pi_a[0] + pi_a[1] + pi_b[0][1] + pi_b[0][0] + pi_b[1][1] + pi_b[1][0] + pi_c[0] + pi_c[1]
+  return (
+    '0x' +
+    toFixedHex(proof.pi_a[0]).slice(2) +
+    toFixedHex(proof.pi_a[1]).slice(2) +
+    toFixedHex(proof.pi_b[0][1]).slice(2) +
+    toFixedHex(proof.pi_b[0][0]).slice(2) +
+    toFixedHex(proof.pi_b[1][1]).slice(2) +
+    toFixedHex(proof.pi_b[1][0]).slice(2) +
+    toFixedHex(proof.pi_c[0]).slice(2) +
+    toFixedHex(proof.pi_c[1]).slice(2)
+  );
+}
+
+/**
+ * Get the supported circuit names and their max input counts
+ */
+export const CIRCUIT_CONFIG = {
+  transaction2: { maxInputs: 2, maxOutputs: 2 },
+  transaction16: { maxInputs: 16, maxOutputs: 2 },
+} as const;
+
+/**
+ * Select the appropriate circuit based on input count
+ * 
+ * @param inputCount - Number of input UTXOs
+ * @returns Circuit name to use
+ */
+export function selectCircuit(inputCount: number): string {
+  if (inputCount <= 2) {
+    return 'transaction2';
+  } else if (inputCount <= 16) {
+    return 'transaction16';
+  } else {
+    throw new Error(`Too many inputs: ${inputCount}. Maximum supported is 16.`);
+  }
+}

package/src/relay.ts

@@ -0,0 +1,216 @@
+/**
+ * Relay functions for submitting withdrawals and transfers
+ * 
+ * The relay service handles transaction submission for privacy-preserving
+ * withdrawals and transfers from Veil pools.
+ * 
+ * Note: Public API is rate limited to 5 requests per minute per IP.
+ * 
+ * @example
+ * ```typescript
+ * import { submitRelay } from '@veil-cash/sdk';
+ * 
+ * const result = await submitRelay({
+ *   type: 'withdraw',
+ *   pool: 'eth',
+ *   proofArgs: { ... },
+ *   extData: { ... },
+ *   metadata: { amount: '0.1' }
+ * });
+ * 
+ * console.log(result.transactionHash);
+ * ```
+ */
+
+import { getRelayUrl } from './addresses.js';
+import type {
+  RelayPool,
+  RelayResponse,
+  RelayErrorResponse,
+  SubmitRelayOptions,
+} from './types.js';
+
+/**
+ * Error thrown when relay request fails
+ */
+export class RelayError extends Error {
+  /** HTTP status code */
+  statusCode: number;
+  /** Seconds until rate limit resets (only for 429 errors) */
+  retryAfter?: number;
+  /** Network the error occurred on */
+  network?: string;
+
+  constructor(message: string, statusCode: number, retryAfter?: number, network?: string) {
+    super(message);
+    this.name = 'RelayError';
+    this.statusCode = statusCode;
+    this.retryAfter = retryAfter;
+    this.network = network;
+  }
+}
+
+/**
+ * Submit a withdrawal or transfer to the relay service
+ * 
+ * The relay service submits the transaction on behalf of the user,
+ * allowing for privacy-preserving withdrawals and transfers.
+ * 
+ * Rate limit: 5 requests per minute per IP (public API)
+ * 
+ * @param options - Relay options including type, pool, proofArgs, extData
+ * @returns Promise resolving to relay response with transaction hash
+ * @throws RelayError if the request fails
+ * 
+ * @example
+ * ```typescript
+ * // Withdraw ETH
+ * const result = await submitRelay({
+ *   type: 'withdraw',
+ *   pool: 'eth',
+ *   proofArgs: proofData.args,
+ *   extData: proofData.extData,
+ *   metadata: { amount: '0.1', recipient: '0x...' }
+ * });
+ * 
+ * // Transfer USDC
+ * const result = await submitRelay({
+ *   type: 'transfer',
+ *   pool: 'usdc',
+ *   proofArgs: proofData.args,
+ *   extData: proofData.extData,
+ *   metadata: { amount: '100' }
+ * });
+ * ```
+ */
+export async function submitRelay(options: SubmitRelayOptions): Promise<RelayResponse> {
+  const {
+    type,
+    pool = 'eth',
+    proofArgs,
+    extData,
+    metadata,
+    relayUrl: customRelayUrl,
+  } = options;
+
+  // Validate inputs
+  if (type !== 'withdraw' && type !== 'transfer') {
+    throw new RelayError('Invalid type. Must be "withdraw" or "transfer"', 400);
+  }
+
+  if (pool !== 'eth' && pool !== 'usdc') {
+    throw new RelayError('Invalid pool. Must be "eth" or "usdc"', 400);
+  }
+
+  if (!proofArgs || !extData) {
+    throw new RelayError('Missing proofArgs or extData', 400);
+  }
+
+  const relayUrl = customRelayUrl || getRelayUrl();
+  const endpoint = `${relayUrl}/relay/${pool}`;
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      type,
+      proofArgs,
+      extData,
+      metadata,
+    }),
+  });
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    const errorData = data as RelayErrorResponse;
+    throw new RelayError(
+      errorData.error || errorData.message || 'Relay request failed',
+      response.status,
+      errorData.retryAfter,
+      errorData.network
+    );
+  }
+
+  return data as RelayResponse;
+}
+
+/**
+ * Check if relay service is healthy
+ * 
+ * @param relayUrl - Optional custom relay URL
+ * @returns Promise resolving to health status
+ * 
+ * @example
+ * ```typescript
+ * const health = await checkRelayHealth();
+ * console.log(health.status); // 'ok'
+ * console.log(health.network); // 'base'
+ * ```
+ */
+export async function checkRelayHealth(relayUrl?: string): Promise<{
+  status: string;
+  service: string;
+  network: string;
+  timestamp: string;
+}> {
+  const url = relayUrl || getRelayUrl();
+  const response = await fetch(`${url}/health`);
+
+  if (!response.ok) {
+    throw new RelayError('Relay service health check failed', response.status);
+  }
+
+  return response.json() as Promise<{
+    status: string;
+    service: string;
+    network: string;
+    timestamp: string;
+  }>;
+}
+
+/**
+ * Get relay service info
+ * 
+ * @param relayUrl - Optional custom relay URL
+ * @returns Promise resolving to service info including rate limit config
+ * 
+ * @example
+ * ```typescript
+ * const info = await getRelayInfo();
+ * console.log(info.rateLimit.limit); // 5
+ * console.log(info.rateLimit.windowMs); // 60000
+ * ```
+ */
+export async function getRelayInfo(relayUrl?: string): Promise<{
+  service: string;
+  version: string;
+  network: string;
+  endpoints: Record<string, string>;
+  rateLimit: {
+    limit: number;
+    windowMs: number;
+    note: string;
+  };
+}> {
+  const url = relayUrl || getRelayUrl();
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new RelayError('Failed to get relay service info', response.status);
+  }
+
+  return response.json() as Promise<{
+    service: string;
+    version: string;
+    network: string;
+    endpoints: Record<string, string>;
+    rateLimit: {
+      limit: number;
+      windowMs: number;
+      note: string;
+    };
+  }>;
+}