@veil-cash/sdk 0.1.0

package/src/types.ts

@@ -0,0 +1,306 @@
+/**
+ * Type definitions for Veil SDK
+ */
+
+/**
+ * Supported tokens
+ */
+export type Token = 'ETH' | 'USDC';
+
+/**
+ * Encrypted message format (x25519-xsalsa20-poly1305)
+ */
+export interface EncryptedMessage {
+  version: string;
+  nonce: string;
+  ephemPublicKey: string;
+  ciphertext: string;
+}
+
+/**
+ * Contract addresses for a network
+ */
+export interface NetworkAddresses {
+  entry: `0x${string}`;
+  ethPool: `0x${string}`;
+  ethQueue: `0x${string}`;
+  usdcPool: `0x${string}`;
+  usdcQueue: `0x${string}`;
+  usdcToken: `0x${string}`;
+  chainId: number;
+  relayUrl: string;
+}
+
+/**
+ * Options for building a register transaction
+ */
+export interface RegisterTxOptions {
+  depositKey: string;
+}
+
+/**
+ * Options for building a deposit transaction
+ */
+export interface DepositTxOptions {
+  depositKey: string;
+  fallbackReceiver: `0x${string}`;
+  amount: string;
+  token?: Token;
+}
+
+/**
+ * Transaction data returned by build functions
+ */
+export interface TransactionData {
+  to: `0x${string}`;
+  data: `0x${string}`;
+  value?: bigint;
+}
+
+/**
+ * Pool configuration
+ */
+export interface PoolConfig {
+  decimals: number;
+  displayDecimals: number;
+  symbol: string;
+  name: string;
+}
+
+/**
+ * Pending deposit from queue contract
+ */
+export interface PendingDeposit {
+  nonce: string;
+  status: 'pending' | 'accepted' | 'rejected' | 'refunded';
+  amount: string;
+  amountWei: string;
+  timestamp: string;
+}
+
+/**
+ * Result from getQueueBalance
+ */
+export interface QueueBalanceResult {
+  address: string;
+  queueBalance: string;
+  queueBalanceWei: string;
+  pendingDeposits: PendingDeposit[];
+  pendingCount: number;
+}
+
+/**
+ * UTXO info for private balance
+ */
+export interface UtxoInfo {
+  index: number;
+  amount: string;
+  amountWei: string;
+  isSpent: boolean;
+}
+
+/**
+ * Result from getPrivateBalance
+ */
+export interface PrivateBalanceResult {
+  privateBalance: string;
+  privateBalanceWei: string;
+  utxoCount: number;
+  spentCount: number;
+  unspentCount: number;
+  utxos: UtxoInfo[];
+}
+
+// =============================================================================
+// Relay Types
+// =============================================================================
+
+/**
+ * Pool type for relay operations
+ */
+export type RelayPool = 'eth' | 'usdc';
+
+/**
+ * Type of relay transaction
+ */
+export type RelayType = 'withdraw' | 'transfer';
+
+/**
+ * Proof arguments for relay transaction
+ */
+export interface RelayProofArgs {
+  proof: string;
+  root: string;
+  inputNullifiers: string[];
+  outputCommitments: [string, string];
+  publicAmount: string;
+  extDataHash: string;
+}
+
+/**
+ * External data for relay transaction
+ */
+export interface RelayExtData {
+  recipient: string;
+  extAmount: string;
+  relayer: string;
+  fee: string;
+  encryptedOutput1: string;
+  encryptedOutput2: string;
+}
+
+/**
+ * Metadata for relay transaction (optional)
+ */
+export interface RelayMetadata {
+  amount?: string;
+  recipient?: string;
+  inputUtxoCount?: number;
+  outputUtxoCount?: number;
+}
+
+/**
+ * Request body for relay service
+ */
+export interface RelayRequest {
+  type: RelayType;
+  proofArgs: RelayProofArgs;
+  extData: RelayExtData;
+  metadata?: RelayMetadata;
+}
+
+/**
+ * Response from relay service
+ */
+export interface RelayResponse {
+  success: boolean;
+  transactionHash: string;
+  blockNumber: string;
+  gasUsed: string;
+  status: string;
+  network: string;
+}
+
+/**
+ * Error response from relay service
+ */
+export interface RelayErrorResponse {
+  error: string;
+  message?: string;
+  retryAfter?: number;
+  network?: string;
+}
+
+/**
+ * Options for submitRelay function
+ */
+export interface SubmitRelayOptions {
+  /** Type of transaction: 'withdraw' or 'transfer' */
+  type: RelayType;
+  /** Pool to use: 'eth' or 'usdc' */
+  pool?: RelayPool;
+  /** Proof arguments generated by ZK prover */
+  proofArgs: RelayProofArgs;
+  /** External data for the transaction */
+  extData: RelayExtData;
+  /** Optional metadata */
+  metadata?: RelayMetadata;
+  /** Custom relay URL (overrides default) */
+  relayUrl?: string;
+}
+
+// =============================================================================
+// Withdraw/Transfer Types
+// =============================================================================
+
+/**
+ * Options for building a withdrawal proof
+ */
+export interface BuildWithdrawProofOptions {
+  /** Amount to withdraw (human readable, e.g., "0.1") */
+  amount: string;
+  /** Recipient address for withdrawal */
+  recipient: `0x${string}`;
+  /** User's keypair for signing */
+  keypair: import('./keypair.js').Keypair;
+  /** Optional RPC URL */
+  rpcUrl?: string;
+  /** Progress callback */
+  onProgress?: (stage: string, detail?: string) => void;
+}
+
+/**
+ * Options for building a transfer proof
+ */
+export interface BuildTransferProofOptions {
+  /** Amount to transfer (human readable, e.g., "0.1") */
+  amount: string;
+  /** Recipient's address (must be registered) */
+  recipientAddress: `0x${string}`;
+  /** Sender's keypair */
+  senderKeypair: import('./keypair.js').Keypair;
+  /** Optional RPC URL */
+  rpcUrl?: string;
+  /** Progress callback */
+  onProgress?: (stage: string, detail?: string) => void;
+}
+
+/**
+ * Result from building a withdrawal or transfer proof
+ */
+export interface ProofBuildResult {
+  /** Proof arguments for on-chain verification */
+  proofArgs: RelayProofArgs;
+  /** External data for transaction */
+  extData: RelayExtData;
+  /** Number of input UTXOs used */
+  inputCount: number;
+  /** Number of output UTXOs created */
+  outputCount: number;
+  /** Amount being withdrawn/transferred */
+  amount: string;
+}
+
+/**
+ * Result from executing a withdrawal
+ */
+export interface WithdrawResult {
+  /** Whether the withdrawal was successful */
+  success: boolean;
+  /** Transaction hash */
+  transactionHash: string;
+  /** Block number of the transaction */
+  blockNumber: string;
+  /** Amount withdrawn */
+  amount: string;
+  /** Recipient address */
+  recipient: string;
+}
+
+/**
+ * Result from executing a transfer
+ */
+export interface TransferResult {
+  /** Whether the transfer was successful */
+  success: boolean;
+  /** Transaction hash */
+  transactionHash: string;
+  /** Block number of the transaction */
+  blockNumber: string;
+  /** Amount transferred */
+  amount: string;
+  /** Recipient address */
+  recipient: string;
+}
+
+/**
+ * UTXO selection result
+ */
+export interface UtxoSelectionResult {
+  /** Selected UTXOs */
+  selectedUtxos: import('./utxo.js').Utxo[];
+  /** Total amount of selected UTXOs (wei) */
+  totalSelected: bigint;
+  /** Change amount to return to sender (wei) */
+  changeAmount: bigint;
+}

package/src/utils.ts

@@ -0,0 +1,151 @@
+/**
+ * Crypto utilities for Veil SDK
+ * Poseidon hash, hex conversion, and random number generation
+ */
+
+import * as crypto from 'crypto';
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const circomlib = require('circomlib');
+const poseidon = circomlib.poseidon;
+
+/**
+ * SNARK scalar field size
+ */
+export const FIELD_SIZE = BigInt(
+  '21888242871839275222246405745257275088548364400416034343698204186575808495617'
+);
+
+/**
+ * Compute Poseidon hash of items
+ * @param items - Array of values to hash (bigint, string, or number)
+ * @returns Poseidon hash as bigint
+ */
+export const poseidonHash = (items: (bigint | string | number)[]): bigint => 
+  BigInt(poseidon(items).toString());
+
+/**
+ * Compute Poseidon hash of two items
+ * @param a - First value
+ * @param b - Second value
+ * @returns Poseidon hash as bigint
+ */
+export const poseidonHash2 = (a: bigint | string | number, b: bigint | string | number): bigint => 
+  poseidonHash([a, b]);
+
+/**
+ * Generate random bigint of specified byte length
+ * @param nbytes - Number of bytes (default: 31)
+ * @returns Random bigint
+ */
+export const randomBN = (nbytes: number = 31): bigint => {
+  const bytes = crypto.randomBytes(nbytes);
+  let hex = '0x';
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, '0');
+  }
+  return BigInt(hex);
+};
+
+/**
+ * Convert bigint/string/number/Buffer to fixed-length hex string
+ * @param number - Value to convert
+ * @param length - Output byte length (default: 32)
+ * @returns Hex string with 0x prefix
+ */
+export function toFixedHex(number: bigint | string | number | Buffer, length: number = 32): string {
+  let hexValue: string;
+  
+  if (number instanceof Buffer) {
+    hexValue = number.toString('hex');
+  } else {
+    let bigIntValue = BigInt(number as bigint | string | number);
+    
+    if (bigIntValue < 0n) {
+      // For negative numbers, use two's complement
+      const maxValue = 1n << BigInt(length * 8);
+      bigIntValue = maxValue + bigIntValue;
+    }
+    
+    hexValue = bigIntValue.toString(16);
+  }
+  
+  return '0x' + hexValue.padStart(length * 2, '0');
+}
+
+/**
+ * Convert value to Buffer of specified byte length
+ * @param value - Value to convert
+ * @param length - Output byte length
+ * @returns Buffer
+ */
+export const toBuffer = (value: bigint | string | number, length: number): Buffer => {
+  const bigIntValue = BigInt(value);
+  const hex = bigIntValue.toString(16).padStart(length * 2, '0');
+  return Buffer.from(hex, 'hex');
+};
+
+/**
+ * External data input for hash calculation
+ */
+export interface ExtDataInput {
+  recipient: string | bigint;
+  extAmount: bigint;
+  relayer: string | bigint;
+  fee: bigint;
+  encryptedOutput1: string;
+  encryptedOutput2: string;
+}
+
+/**
+ * Calculate hash of external data for ZK proof
+ * Uses Solidity-compatible ABI encoding and keccak256 hash
+ * 
+ * @param extData - External data to hash
+ * @returns Hash as bigint (mod FIELD_SIZE)
+ */
+export function getExtDataHash(extData: ExtDataInput): bigint {
+  // Use ethers ABI encoder for Solidity-compatible encoding
+  const { ethers } = require('ethers');
+  const abi = ethers.AbiCoder.defaultAbiCoder();
+
+  // Encode the struct exactly as Solidity would
+  const encodedData = abi.encode(
+    ['tuple(address,int256,address,uint256,bytes,bytes)'],
+    [[
+      extData.recipient,
+      extData.extAmount,
+      extData.relayer, 
+      extData.fee,
+      extData.encryptedOutput1,
+      extData.encryptedOutput2,
+    ]]
+  );
+  
+  const hash = ethers.keccak256(encodedData);
+  return BigInt(hash) % FIELD_SIZE;
+}
+
+/**
+ * Shuffle an array using Fisher-Yates algorithm
+ * Used to randomize input/output order for privacy
+ * 
+ * @param array - Array to shuffle
+ * @returns Shuffled array (mutates and returns same array)
+ */
+export function shuffle<T>(array: T[]): T[] {
+  let currentIndex = array.length;
+  let randomIndex: number;
+
+  // While there remain elements to shuffle...
+  while (currentIndex !== 0) {
+    // Pick a remaining element...
+    randomIndex = Math.floor(Math.random() * currentIndex);
+    currentIndex--;
+
+    // And swap it with the current element
+    [array[currentIndex], array[randomIndex]] = [array[randomIndex], array[currentIndex]];
+  }
+
+  return array;
+}

package/src/utxo.ts

@@ -0,0 +1,119 @@
+/**
+ * UTXO (Unspent Transaction Output) class for Veil SDK
+ * Represents a private balance entry that can be spent
+ */
+
+import { Keypair } from './keypair.js';
+import { poseidonHash, toBuffer, randomBN } from './utils.js';
+
+export interface UtxoParams {
+  amount?: bigint | number | string;
+  keypair?: Keypair;
+  blinding?: bigint;
+  index?: number;
+}
+
+/**
+ * UTXO class - represents a private balance entry
+ * 
+ * A UTXO contains:
+ * - amount: The value in wei
+ * - blinding: Random value for privacy
+ * - keypair: The owner's keypair
+ * - index: Position in the merkle tree (needed for nullifier calculation)
+ * 
+ * @example
+ * ```typescript
+ * // Decrypt an encrypted output
+ * const utxo = Utxo.decrypt(encryptedOutput, keypair);
+ * utxo.index = 5; // Set the merkle tree index
+ * 
+ * // Check if spent
+ * const nullifier = utxo.getNullifier();
+ * const isSpent = await pool.isSpent(nullifier);
+ * ```
+ */
+export class Utxo {
+  public amount: bigint;
+  public blinding: bigint;
+  public keypair: Keypair;
+  public index?: number;
+  private _commitment?: bigint;
+  private _nullifier?: bigint;
+
+  /**
+   * Create a new UTXO
+   * @param params - UTXO parameters
+   */
+  constructor(params: UtxoParams = {}) {
+    const { amount = 0, keypair = new Keypair(), blinding = randomBN(), index } = params;
+    this.amount = BigInt(amount);
+    this.blinding = BigInt(blinding);
+    this.keypair = keypair;
+    this.index = index;
+  }
+
+  /**
+   * Get the commitment for this UTXO
+   * commitment = poseidonHash([amount, pubkey, blinding])
+   * @returns Commitment as bigint
+   */
+  getCommitment(): bigint {
+    if (!this._commitment) {
+      this._commitment = poseidonHash([this.amount, this.keypair.pubkey, this.blinding]);
+    }
+    return this._commitment;
+  }
+
+  /**
+   * Get the nullifier for this UTXO
+   * Requires index and private key to be set
+   * nullifier = poseidonHash([commitment, index, signature])
+   * @returns Nullifier as bigint
+   */
+  getNullifier(): bigint {
+    if (!this._nullifier) {
+      if (
+        this.amount > 0n &&
+        (this.index === undefined || !this.keypair.privkey)
+      ) {
+        throw new Error('Cannot compute nullifier without UTXO index or private key');
+      }
+      const signature = this.keypair.privkey 
+        ? this.keypair.sign(this.getCommitment(), this.index || 0) 
+        : 0n;
+      this._nullifier = poseidonHash([this.getCommitment(), this.index || 0, signature]);
+    }
+    return this._nullifier;
+  }
+
+  /**
+   * Encrypt UTXO data using the keypair
+   * @returns Encrypted data as 0x-prefixed hex string
+   */
+  encrypt(): string {
+    const bytes = Buffer.concat([
+      toBuffer(this.amount, 31),
+      toBuffer(this.blinding, 31),
+    ]);
+    return this.keypair.encrypt(bytes);
+  }
+
+  /**
+   * Decrypt an encrypted output to create a UTXO
+   * Only succeeds if the keypair owns this UTXO
+   * 
+   * @param data - Encrypted output as hex string
+   * @param keypair - Keypair to decrypt with
+   * @returns Decrypted UTXO
+   * @throws If decryption fails (wrong keypair)
+   */
+  static decrypt(data: string, keypair: Keypair): Utxo {
+    const buf = keypair.decrypt(data);
+    return new Utxo({
+      amount: BigInt('0x' + buf.slice(0, 31).toString('hex')),
+      blinding: BigInt('0x' + buf.slice(31, 62).toString('hex')),
+      keypair,
+    });
+  }
+}