@veil-cash/sdk 0.1.0

package/src/cli/wallet.ts

@@ -0,0 +1,228 @@
+/**
+ * Wallet utilities for CLI transaction signing
+ */
+
+import { 
+  createWalletClient, 
+  createPublicClient,
+  http, 
+  decodeErrorResult,
+  BaseError,
+  ContractFunctionRevertedError,
+} from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import type { TransactionData } from '../types.js';
+import { ENTRY_ABI } from '../abi.js';
+import { getAddresses } from '../addresses.js';
+
+export interface WalletConfig {
+  privateKey: `0x${string}`;
+  rpcUrl?: string;
+}
+
+export interface SendTransactionResult {
+  hash: `0x${string}`;
+  receipt: {
+    status: 'success' | 'reverted';
+    blockNumber: bigint;
+    gasUsed: bigint;
+  };
+}
+
+/**
+ * Create a wallet client for signing and sending transactions
+ * @returns Wallet and public clients with account and chain
+ * 
+ * Note: Uses `any` return type to avoid viem's complex generic type mismatches
+ * that occur with Base chain's deposit transaction types. Runtime behavior is correct.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createWallet(config: WalletConfig): any {
+  const { privateKey, rpcUrl } = config;
+  
+  const account = privateKeyToAccount(privateKey);
+  const chain = base;
+  const transport = http(rpcUrl);
+
+  const walletClient = createWalletClient({
+    account,
+    chain,
+    transport,
+  });
+
+  const publicClient = createPublicClient({
+    chain,
+    transport,
+  });
+
+  return { walletClient, publicClient, account, chain };
+}
+
+/**
+ * Known custom error selectors (first 4 bytes of keccak256 hash of error signature)
+ */
+const ERROR_SELECTORS: Record<string, string> = {
+  '0x3ee5aeb5': 'DepositsDisabled',
+  '0x8e8f6d6f': 'MinimumDepositNotMet',
+  '0x5cd83192': 'NotAllowedToDeposit',
+  '0x6f5e8818': 'UserNotRegistered',
+  '0x8a2ef116': 'UserAlreadyRegistered',
+  '0x0dc149f0': 'InvalidDepositKey',
+  '0x584a7938': 'InvalidDepositKeyForUser',
+  '0xd92e233d': 'OnlyOwnerCanRegister',
+};
+
+/**
+ * Try to decode a custom error from the ABI or known selectors
+ */
+function decodeCustomError(error: unknown): string | null {
+  // Convert error to string and look for hex data
+  const errorStr = String(error);
+  
+  // Try to find revert data in the error (look for 0x followed by hex)
+  const dataMatch = errorStr.match(/data:\s*(0x[a-fA-F0-9]+)/);
+  if (dataMatch) {
+    const data = dataMatch[1];
+    const selector = data.slice(0, 10).toLowerCase();
+    if (ERROR_SELECTORS[selector]) {
+      return ERROR_SELECTORS[selector];
+    }
+  }
+  
+  if (error instanceof BaseError) {
+    // Check if it's a ContractFunctionRevertedError
+    const revertError = error.walk(err => err instanceof ContractFunctionRevertedError);
+    if (revertError instanceof ContractFunctionRevertedError) {
+      const errorName = revertError.data?.errorName;
+      if (errorName) {
+        return errorName;
+      }
+    }
+    
+    // Try to extract error data from various places
+    const anyError = error as any;
+    const possibleData = anyError.data || anyError.cause?.data || anyError.cause?.cause?.data;
+    
+    if (possibleData && typeof possibleData === 'string' && possibleData.startsWith('0x')) {
+      try {
+        const decoded = decodeErrorResult({
+          abi: ENTRY_ABI,
+          data: possibleData as `0x${string}`,
+        });
+        return decoded.errorName;
+      } catch {
+        // Try selector lookup
+        const selector = possibleData.slice(0, 10).toLowerCase();
+        if (ERROR_SELECTORS[selector]) {
+          return ERROR_SELECTORS[selector];
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Send a transaction and wait for confirmation
+ */
+export async function sendTransaction(
+  config: WalletConfig,
+  tx: TransactionData
+): Promise<SendTransactionResult> {
+  const { walletClient, publicClient, account, chain } = createWallet(config);
+
+  try {
+    // Simulate first to get better error messages
+    await publicClient.call({
+      account,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value,
+    });
+  } catch (error) {
+    // Try to decode custom error
+    const customError = decodeCustomError(error);
+    if (customError) {
+      throw new Error(customError);
+    }
+    // Re-throw with original message if we can't decode
+    throw error;
+  }
+
+  // Send the transaction
+  const hash = await walletClient.sendTransaction({
+    account,
+    chain,
+    to: tx.to,
+    data: tx.data,
+    value: tx.value,
+  });
+
+  // Wait for confirmation
+  const receipt = await publicClient.waitForTransactionReceipt({ hash });
+
+  return {
+    hash,
+    receipt: {
+      status: receipt.status,
+      blockNumber: receipt.blockNumber,
+      gasUsed: receipt.gasUsed,
+    },
+  };
+}
+
+/**
+ * Get the address from a private key
+ */
+export function getAddress(privateKey: `0x${string}`): `0x${string}` {
+  const account = privateKeyToAccount(privateKey);
+  return account.address;
+}
+
+/**
+ * Get ETH balance for an address
+ */
+export async function getBalance(
+  address: `0x${string}`,
+  rpcUrl?: string
+): Promise<bigint> {
+  const transport = http(rpcUrl);
+  const publicClient = createPublicClient({
+    chain: base,
+    transport,
+  });
+
+  return publicClient.getBalance({ address });
+}
+
+/**
+ * Check if an address is already registered (has a deposit key on-chain)
+ */
+export async function isRegistered(
+  address: `0x${string}`,
+  rpcUrl?: string
+): Promise<{ registered: boolean; depositKey: string | null }> {
+  const transport = http(rpcUrl);
+  const publicClient = createPublicClient({
+    chain: base,
+    transport,
+  });
+
+  const addresses = getAddresses();
+  
+  const depositKey = await publicClient.readContract({
+    address: addresses.entry,
+    abi: ENTRY_ABI,
+    functionName: 'depositKeys',
+    args: [address],
+  }) as `0x${string}`;
+
+  // If depositKey has length > 2 (more than just "0x"), user is registered
+  const registered = depositKey && depositKey.length > 2;
+  
+  return {
+    registered,
+    depositKey: registered ? depositKey : null,
+  };
+}

package/src/deposit.ts

@@ -0,0 +1,183 @@
+/**
+ * Deposit functions for Veil SDK
+ * Build transactions for registration and deposits
+ */
+
+import { encodeFunctionData, parseEther, parseUnits } from 'viem';
+import { getAddresses, POOL_CONFIG } from './addresses.js';
+import { ENTRY_ABI, ERC20_ABI } from './abi.js';
+import type { 
+  Token, 
+  TransactionData, 
+} from './types.js';
+
+/**
+ * Build a transaction to register a deposit key
+ * This is a one-time operation that links your address to your keypair
+ * 
+ * @param depositKey - Deposit key from Keypair.depositKey()
+ * @param ownerAddress - Address that will own this deposit key
+ * @returns Transaction data to send
+ * 
+ * @example
+ * ```typescript
+ * const keypair = new Keypair();
+ * const tx = buildRegisterTx(keypair.depositKey(), '0x...');
+ * // Send tx using your wallet (viem, ethers, etc.)
+ * ```
+ */
+export function buildRegisterTx(
+  depositKey: string,
+  ownerAddress: `0x${string}`
+): TransactionData {
+  const addresses = getAddresses();
+  
+  const data = encodeFunctionData({
+    abi: ENTRY_ABI,
+    functionName: 'register',
+    args: [{
+      owner: ownerAddress,
+      depositKey: depositKey as `0x${string}`,
+    }],
+  });
+
+  return {
+    to: addresses.entry,
+    data,
+  };
+}
+
+/**
+ * Build a transaction to deposit ETH
+ * 
+ * @param options - Deposit options
+ * @param options.depositKey - Deposit key from Keypair.depositKey()
+ * @param options.amount - Amount to deposit (human readable, e.g., '0.1')
+ * @returns Transaction data including value to send
+ * 
+ * @example
+ * ```typescript
+ * const tx = buildDepositETHTx({
+ *   depositKey: keypair.depositKey(),
+ *   amount: '0.1',
+ * });
+ * // Send tx with tx.value as the ETH amount
+ * ```
+ */
+export function buildDepositETHTx(options: {
+  depositKey: string;
+  amount: string;
+}): TransactionData {
+  const { depositKey, amount } = options;
+  const addresses = getAddresses();
+  
+  const value = parseEther(amount);
+  
+  const data = encodeFunctionData({
+    abi: ENTRY_ABI,
+    functionName: 'queueETH',
+    args: [depositKey as `0x${string}`],
+  });
+
+  return {
+    to: addresses.entry,
+    data,
+    value,
+  };
+}
+
+/**
+ * Build a transaction to approve USDC for deposit
+ * Must be called before depositUSDC if allowance is insufficient
+ * 
+ * @param options - Approval options
+ * @param options.amount - Amount to approve (human readable, e.g., '100')
+ * @returns Transaction data
+ */
+export function buildApproveUSDCTx(options: {
+  amount: string;
+}): TransactionData {
+  const { amount } = options;
+  const addresses = getAddresses();
+  
+  const amountWei = parseUnits(amount, POOL_CONFIG.usdc.decimals);
+  
+  const data = encodeFunctionData({
+    abi: ERC20_ABI,
+    functionName: 'approve',
+    args: [addresses.entry, amountWei],
+  });
+
+  return {
+    to: addresses.usdcToken,
+    data,
+  };
+}
+
+/**
+ * Build a transaction to deposit USDC
+ * Note: You must approve USDC first using buildApproveUSDCTx
+ * 
+ * @param options - Deposit options
+ * @param options.depositKey - Deposit key from Keypair.depositKey()
+ * @param options.amount - Amount to deposit (human readable, e.g., '100')
+ * @returns Transaction data
+ */
+export function buildDepositUSDCTx(options: {
+  depositKey: string;
+  amount: string;
+}): TransactionData {
+  const { depositKey, amount } = options;
+  const addresses = getAddresses();
+  
+  const amountWei = parseUnits(amount, POOL_CONFIG.usdc.decimals);
+  
+  const data = encodeFunctionData({
+    abi: ENTRY_ABI,
+    functionName: 'queueUSDC',
+    args: [amountWei, depositKey as `0x${string}`],
+  });
+
+  return {
+    to: addresses.entry,
+    data,
+  };
+}
+
+/**
+ * Build a deposit transaction (ETH or USDC)
+ * Convenience function that routes to the correct builder
+ * 
+ * @param options - Deposit options
+ * @returns Transaction data
+ * 
+ * @example
+ * ```typescript
+ * // ETH deposit
+ * const ethTx = buildDepositTx({
+ *   depositKey: keypair.depositKey(),
+ *   amount: '0.1',
+ *   token: 'ETH',
+ * });
+ * 
+ * // USDC deposit (remember to approve first!)
+ * const usdcTx = buildDepositTx({
+ *   depositKey: keypair.depositKey(),
+ *   amount: '100',
+ *   token: 'USDC',
+ * });
+ * ```
+ */
+export function buildDepositTx(options: {
+  depositKey: string;
+  amount: string;
+  token?: Token;
+}): TransactionData {
+  const { token = 'ETH', ...rest } = options;
+  
+  if (token === 'USDC') {
+    return buildDepositUSDCTx(rest);
+  }
+  
+  return buildDepositETHTx(rest);
+}

package/src/index.ts

@@ -0,0 +1,160 @@
+/**
+ * Veil Cash SDK
+ * 
+ * SDK for interacting with Veil Cash privacy pools.
+ * Generate keypairs, register, deposit, withdraw, and transfer privately.
+ * 
+ * @example
+ * ```typescript
+ * import { Keypair, withdraw, transfer, buildWithdrawProof } from '@veil-cash/sdk';
+ * 
+ * // Generate keypair
+ * const keypair = new Keypair();
+ * console.log(keypair.depositKey()); // Register this
+ * console.log(keypair.privkey);      // Save securely!
+ * 
+ * // Withdraw from pool
+ * const result = await withdraw({
+ *   amount: '0.1',
+ *   recipient: '0x1234...',
+ *   keypair,
+ * });
+ * 
+ * // Transfer privately
+ * const transfer = await transfer({
+ *   amount: '0.1',
+ *   recipientAddress: '0x5678...',
+ *   senderKeypair: keypair,
+ * });
+ * ```
+ * 
+ * @packageDocumentation
+ */
+
+// Keypair
+export { Keypair, packEncryptedMessage, unpackEncryptedMessage } from './keypair.js';
+
+// UTXO
+export { Utxo } from './utxo.js';
+export type { UtxoParams } from './utxo.js';
+
+// Deposit functions
+export { 
+  buildRegisterTx,
+  buildDepositETHTx,
+  buildDepositUSDCTx,
+  buildApproveUSDCTx,
+  buildDepositTx,
+} from './deposit.js';
+
+// Balance functions
+export {
+  getQueueBalance,
+  getPrivateBalance,
+} from './balance.js';
+export type { ProgressCallback } from './balance.js';
+
+// Withdraw functions
+export {
+  withdraw,
+  buildWithdrawProof,
+  selectUtxosForWithdraw,
+} from './withdraw.js';
+
+// Transfer functions
+export {
+  transfer,
+  buildTransferProof,
+  checkRecipientRegistration,
+  mergeUtxos,
+} from './transfer.js';
+
+// Transaction preparation (core ZK proof building)
+export {
+  prepareTransaction,
+} from './transaction.js';
+export type {
+  ExtData,
+  ProofArgs,
+  TransactionResult,
+  PrepareTransactionParams,
+} from './transaction.js';
+
+// Merkle tree utilities
+export {
+  buildMerkleTree,
+  getMerklePath,
+  MERKLE_TREE_HEIGHT,
+} from './merkle.js';
+
+// ZK Prover
+export {
+  prove,
+  selectCircuit,
+  CIRCUIT_CONFIG,
+} from './prover.js';
+export type { ProofInput } from './prover.js';
+
+// Addresses and config
+export { 
+  ADDRESSES, 
+  POOL_CONFIG, 
+  getAddresses, 
+  getRelayUrl,
+} from './addresses.js';
+
+// Relay functions
+export {
+  submitRelay,
+  checkRelayHealth,
+  getRelayInfo,
+  RelayError,
+} from './relay.js';
+
+// ABIs
+export { ENTRY_ABI, ERC20_ABI, QUEUE_ABI, POOL_ABI } from './abi.js';
+
+// Utilities
+export { 
+  poseidonHash, 
+  poseidonHash2, 
+  toFixedHex, 
+  toBuffer,
+  randomBN,
+  getExtDataHash,
+  shuffle,
+  FIELD_SIZE,
+} from './utils.js';
+export type { ExtDataInput } from './utils.js';
+
+// Types
+export type {
+  Token,
+  EncryptedMessage,
+  NetworkAddresses,
+  RegisterTxOptions,
+  DepositTxOptions,
+  TransactionData,
+  PoolConfig,
+  PendingDeposit,
+  QueueBalanceResult,
+  UtxoInfo,
+  PrivateBalanceResult,
+  // Relay types
+  RelayPool,
+  RelayType,
+  RelayProofArgs,
+  RelayExtData,
+  RelayMetadata,
+  RelayRequest,
+  RelayResponse,
+  RelayErrorResponse,
+  SubmitRelayOptions,
+  // Withdraw/Transfer types
+  BuildWithdrawProofOptions,
+  BuildTransferProofOptions,
+  ProofBuildResult,
+  WithdrawResult,
+  TransferResult,
+  UtxoSelectionResult,
+} from './types.js';