@velumdotcash/sdk 2.0.0

package/dist/errors.js

@@ -0,0 +1,127 @@
+/**
+ * Custom error classes for Privacy Cash SDK
+ *
+ * These provide typed errors with:
+ * - Error codes for logging/analytics
+ * - Recoverable flag to indicate if retry is possible
+ * - Cause preservation for debugging
+ */
+/**
+ * Base error class for all Privacy Cash errors
+ */
+export class PrivacyCashError extends Error {
+    code;
+    recoverable;
+    cause;
+    constructor(message, code, recoverable = false, cause) {
+        super(message);
+        this.code = code;
+        this.recoverable = recoverable;
+        this.cause = cause;
+        this.name = "PrivacyCashError";
+        // Maintains proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * ZK proof generation errors
+ * These are generally not recoverable without fixing inputs
+ */
+export class ZKProofError extends PrivacyCashError {
+    constructor(message, code = "ZK_GENERIC", cause) {
+        super(message, code, false, cause);
+        this.name = "ZKProofError";
+    }
+}
+/**
+ * Network/RPC related errors
+ * These are often recoverable with retry
+ */
+export class NetworkError extends PrivacyCashError {
+    constructor(message, code = "NETWORK_GENERIC", cause) {
+        super(message, code, true, cause);
+        this.name = "NetworkError";
+    }
+}
+/**
+ * Insufficient balance for operation
+ */
+export class InsufficientBalanceError extends PrivacyCashError {
+    required;
+    available;
+    token;
+    constructor(required, available, token = "SOL") {
+        super(`Insufficient ${token} balance: need ${required} lamports, have ${available}`, "INSUFFICIENT_BALANCE", false);
+        this.required = required;
+        this.available = available;
+        this.token = token;
+        this.name = "InsufficientBalanceError";
+    }
+}
+/**
+ * Deposit limit exceeded
+ */
+export class DepositLimitError extends PrivacyCashError {
+    limit;
+    attempted;
+    constructor(limit, attempted) {
+        super(`Deposit limit exceeded: max ${limit} lamports, attempted ${attempted}`, "DEPOSIT_LIMIT_EXCEEDED", false);
+        this.limit = limit;
+        this.attempted = attempted;
+        this.name = "DepositLimitError";
+    }
+}
+/**
+ * Transaction confirmation timeout
+ */
+export class TransactionTimeoutError extends PrivacyCashError {
+    signature;
+    constructor(message, signature) {
+        super(message, "TRANSACTION_TIMEOUT", true);
+        this.signature = signature;
+        this.name = "TransactionTimeoutError";
+    }
+}
+/**
+ * UTXO related errors
+ */
+export class UTXOError extends PrivacyCashError {
+    constructor(message, code = "UTXO_GENERIC", cause) {
+        super(message, code, false, cause);
+        this.name = "UTXOError";
+    }
+}
+/**
+ * Encryption/decryption errors
+ */
+export class EncryptionError extends PrivacyCashError {
+    constructor(message, code = "ENCRYPTION_GENERIC", cause) {
+        super(message, code, false, cause);
+        this.name = "EncryptionError";
+    }
+}
+/**
+ * Relayer API errors
+ */
+export class RelayerError extends PrivacyCashError {
+    statusCode;
+    constructor(message, statusCode, cause) {
+        super(message, "RELAYER_ERROR", true, cause);
+        this.statusCode = statusCode;
+        this.name = "RelayerError";
+    }
+}
+/**
+ * Helper to wrap unknown errors
+ */
+export function wrapError(error, fallbackMessage) {
+    if (error instanceof PrivacyCashError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new PrivacyCashError(error.message || fallbackMessage, "UNKNOWN_ERROR", false, error);
+    }
+    return new PrivacyCashError(typeof error === "string" ? error : fallbackMessage, "UNKNOWN_ERROR", false);
+}

package/dist/exportUtils.d.ts

@@ -0,0 +1,10 @@
+export { getConfig } from './config.js';
+export { deposit } from './deposit.js';
+export { withdraw } from './withdraw.js';
+export { EncryptionService } from './utils/encryption.js';
+export { setLogger } from './utils/logger.js';
+export { getBalanceFromUtxos, getUtxos, localstorageKey } from './getUtxos.js';
+export { depositSPL } from './depositSPL.js';
+export { withdrawSPL } from './withdrawSPL.js';
+export { getBalanceFromUtxosSPL, getUtxosSPL } from './getUtxosSPL.js';
+export { type TokenList, type SplList, tokens } from './utils/constants.js';

package/dist/exportUtils.js

@@ -0,0 +1,10 @@
+export { getConfig } from './config.js';
+export { deposit } from './deposit.js';
+export { withdraw } from './withdraw.js';
+export { EncryptionService } from './utils/encryption.js';
+export { setLogger } from './utils/logger.js';
+export { getBalanceFromUtxos, getUtxos, localstorageKey } from './getUtxos.js';
+export { depositSPL } from './depositSPL.js';
+export { withdrawSPL } from './withdrawSPL.js';
+export { getBalanceFromUtxosSPL, getUtxosSPL } from './getUtxosSPL.js';
+export { tokens } from './utils/constants.js';

package/dist/getUtxos.d.ts

@@ -0,0 +1,30 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { Utxo } from "./models/utxo.js";
+import { EncryptionService } from "./utils/encryption.js";
+export declare function localstorageKey(key: PublicKey): string;
+/**
+ * Fetch and decrypt all UTXOs for a user
+ * @param signed The user's signature
+ * @param connection Solana connection to fetch on-chain commitment accounts
+ * @param setStatus A global state updator. Set live status message showing on webpage
+ * @returns Array of decrypted UTXOs that belong to the user
+ */
+export declare function getUtxos({ publicKey, connection, encryptionService, storage, abortSignal, offset, }: {
+    publicKey: PublicKey;
+    connection: Connection;
+    encryptionService: EncryptionService;
+    storage: Storage;
+    abortSignal?: AbortSignal;
+    offset?: number;
+}): Promise<Utxo[]>;
+/**
+ * Check if a UTXO has been spent
+ * @param connection Solana connection
+ * @param utxo The UTXO to check
+ * @param retries Number of retries remaining (default 3)
+ * @returns Promise<boolean> true if spent, false if unspent
+ */
+export declare function isUtxoSpent(connection: Connection, utxo: Utxo, retries?: number): Promise<boolean>;
+export declare function getBalanceFromUtxos(utxos: Utxo[]): {
+    lamports: number;
+};

package/dist/getUtxos.js

@@ -0,0 +1,335 @@
+import { PublicKey, } from "@solana/web3.js";
+import BN from "bn.js";
+import { Keypair as UtxoKeypair } from "./models/keypair.js";
+import { WasmFactory } from "@lightprotocol/hasher.rs";
+//@ts-ignore
+import * as ffjavascript from "ffjavascript";
+import { FETCH_UTXOS_GROUP_SIZE, RELAYER_API_URL, LSK_ENCRYPTED_OUTPUTS, LSK_FETCH_OFFSET, PROGRAM_ID, } from "./utils/constants.js";
+import { logger } from "./utils/logger.js";
+import { debugLogger } from "./utils/debug-logger.js";
+// Use type assertion for the utility functions (same pattern as in get_verification_keys.ts)
+const utils = ffjavascript.utils;
+const { unstringifyBigInts, leInt2Buff } = utils;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(() => {
+        resolve("ok");
+    }, ms));
+}
+export function localstorageKey(key) {
+    return PROGRAM_ID.toString().substring(0, 6) + key.toString();
+}
+let roundStartIndex = 0;
+let decryptionTaskFinished = 0;
+/**
+ * Fetch and decrypt all UTXOs for a user
+ * @param signed The user's signature
+ * @param connection Solana connection to fetch on-chain commitment accounts
+ * @param setStatus A global state updator. Set live status message showing on webpage
+ * @returns Array of decrypted UTXOs that belong to the user
+ */
+export async function getUtxos({ publicKey, connection, encryptionService, storage, abortSignal, offset, }) {
+    let valid_utxos = [];
+    let valid_strings = [];
+    let history_indexes = [];
+    let offsetStr = storage.getItem(LSK_FETCH_OFFSET + localstorageKey(publicKey));
+    if (offsetStr) {
+        roundStartIndex = Number(offsetStr);
+    }
+    else {
+        roundStartIndex = 0;
+    }
+    decryptionTaskFinished = 0;
+    if (!offset) {
+        offset = 0;
+    }
+    roundStartIndex = Math.max(offset, roundStartIndex);
+    while (true) {
+        if (abortSignal?.aborted) {
+            throw new Error("aborted");
+        }
+        let offsetStr = storage.getItem(LSK_FETCH_OFFSET + localstorageKey(publicKey));
+        let fetch_utxo_offset = offsetStr ? Number(offsetStr) : 0;
+        if (offset) {
+            fetch_utxo_offset = Math.max(offset, fetch_utxo_offset);
+        }
+        let fetch_utxo_end = fetch_utxo_offset + FETCH_UTXOS_GROUP_SIZE;
+        let fetch_utxo_url = `${RELAYER_API_URL}/utxos/range?start=${fetch_utxo_offset}&end=${fetch_utxo_end}`;
+        let fetched = await fetchUserUtxos({
+            publicKey,
+            connection,
+            url: fetch_utxo_url,
+            encryptionService,
+            storage,
+            initOffset: offset,
+        });
+        let am = 0;
+        const nonZeroUtxos = [];
+        const nonZeroEncrypted = [];
+        for (let [k, utxo] of fetched.utxos.entries()) {
+            history_indexes.push(utxo.index);
+            if (utxo.amount.toNumber() > 0) {
+                nonZeroUtxos.push(utxo);
+                nonZeroEncrypted.push(fetched.encryptedOutputs[k]);
+            }
+        }
+        if (nonZeroUtxos.length > 0) {
+            const spentFlags = await areUtxosSpent(connection, nonZeroUtxos);
+            for (let i = 0; i < nonZeroUtxos.length; i++) {
+                if (!spentFlags[i]) {
+                    logger.debug(`found unspent encrypted_output ${nonZeroEncrypted[i]}`);
+                    am += nonZeroUtxos[i].amount.toNumber();
+                    valid_utxos.push(nonZeroUtxos[i]);
+                    valid_strings.push(nonZeroEncrypted[i]);
+                }
+            }
+        }
+        storage.setItem(LSK_FETCH_OFFSET + localstorageKey(publicKey), (fetch_utxo_offset + fetched.len).toString());
+        if (!fetched.hasMore) {
+            break;
+        }
+        await sleep(20);
+    }
+    // get history index
+    let historyKey = "tradeHistory" + localstorageKey(publicKey);
+    let rec = storage.getItem(historyKey);
+    let recIndexes = [];
+    if (rec?.length) {
+        recIndexes = rec.split(",").map((n) => Number(n));
+    }
+    if (recIndexes.length) {
+        history_indexes = [...history_indexes, ...recIndexes];
+    }
+    let unique_history_indexes = Array.from(new Set(history_indexes));
+    let top20 = unique_history_indexes.sort((a, b) => b - a).slice(0, 20);
+    if (top20.length) {
+        storage.setItem(historyKey, top20.join(","));
+    }
+    // store valid strings
+    logger.debug(`valid_strings len before set: ${valid_strings.length}`);
+    valid_strings = [...new Set(valid_strings)];
+    logger.debug(`valid_strings len after set: ${valid_strings.length}`);
+    storage.setItem(LSK_ENCRYPTED_OUTPUTS + localstorageKey(publicKey), JSON.stringify(valid_strings));
+    return valid_utxos;
+}
+async function fetchUserUtxos({ publicKey, connection, url, storage, encryptionService, initOffset, }) {
+    const lightWasm = await WasmFactory.getInstance();
+    // Derive the UTXO keypair from the wallet keypair
+    const utxoPrivateKey = encryptionService.deriveUtxoPrivateKey();
+    const utxoKeypair = new UtxoKeypair(utxoPrivateKey, lightWasm);
+    // Fetch all UTXOs from the API
+    let encryptedOutputs = [];
+    logger.debug("fetching utxo data", url);
+    let res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`HTTP error! status: ${res.status}`);
+    const data = await res.json();
+    logger.debug("got utxo data");
+    if (!data) {
+        throw new Error("API returned empty data");
+    }
+    else if (Array.isArray(data)) {
+        // Handle the case where the API returns an array of UTXOs
+        const utxos = data;
+        // Extract encrypted outputs from the array of UTXOs
+        encryptedOutputs = utxos
+            .filter((utxo) => utxo.encrypted_output)
+            .map((utxo) => utxo.encrypted_output);
+    }
+    else if (typeof data === "object" && data.encrypted_outputs) {
+        // Handle the case where the API returns an object with encrypted_outputs array
+        const apiResponse = data;
+        encryptedOutputs = apiResponse.encrypted_outputs;
+    }
+    else {
+        throw new Error(`API returned unexpected data format: ${JSON.stringify(data).substring(0, 100)}...`);
+    }
+    // Try to decrypt each encrypted output
+    const myUtxos = [];
+    const myEncryptedOutputs = [];
+    let decryptionAttempts = 0;
+    let successfulDecryptions = 0;
+    let cachedStringNum = 0;
+    let cachedString = storage.getItem(LSK_ENCRYPTED_OUTPUTS + localstorageKey(publicKey));
+    if (cachedString) {
+        cachedStringNum = JSON.parse(cachedString).length;
+    }
+    let decryptionTaskTotal = data.total + cachedStringNum - roundStartIndex;
+    let batchRes = await decrypt_outputs(encryptedOutputs, encryptionService, utxoKeypair, lightWasm);
+    decryptionTaskFinished += encryptedOutputs.length;
+    logger.debug("batchReslen", batchRes.length);
+    for (let i = 0; i < batchRes.length; i++) {
+        let dres = batchRes[i];
+        if (dres.status == "decrypted" && dres.utxo) {
+            myUtxos.push(dres.utxo);
+            myEncryptedOutputs.push(dres.encryptedOutput);
+        }
+    }
+    logger.info(`(decrypting cached utxo: ${decryptionTaskFinished + 1}/${decryptionTaskTotal}...)`);
+    // check cached string when no more fetching tasks
+    if (!data.hasMore) {
+        if (cachedString) {
+            let cachedEncryptedOutputs = JSON.parse(cachedString);
+            if (decryptionTaskFinished % 100 == 0) {
+                logger.info(`(decrypting cached utxo: ${decryptionTaskFinished + 1}/${decryptionTaskTotal}...)`);
+            }
+            let batchRes = await decrypt_outputs(cachedEncryptedOutputs, encryptionService, utxoKeypair, lightWasm);
+            decryptionTaskFinished += cachedEncryptedOutputs.length;
+            logger.debug("cachedbatchReslen", batchRes.length, " source", cachedEncryptedOutputs.length);
+            for (let i = 0; i < batchRes.length; i++) {
+                let dres = batchRes[i];
+                if (dres.status == "decrypted" && dres.utxo) {
+                    myUtxos.push(dres.utxo);
+                    myEncryptedOutputs.push(dres.encryptedOutput);
+                }
+            }
+        }
+    }
+    return {
+        encryptedOutputs: myEncryptedOutputs,
+        utxos: myUtxos,
+        hasMore: data.hasMore,
+        len: encryptedOutputs.length,
+    };
+}
+/**
+ * Check if a UTXO has been spent
+ * @param connection Solana connection
+ * @param utxo The UTXO to check
+ * @param retries Number of retries remaining (default 3)
+ * @returns Promise<boolean> true if spent, false if unspent
+ */
+export async function isUtxoSpent(connection, utxo, retries = 3) {
+    try {
+        // Get the nullifier for this UTXO
+        const nullifier = await utxo.getNullifier();
+        logger.debug(`Checking if UTXO with nullifier ${nullifier} is spent`);
+        // Convert decimal nullifier string to byte array (same format as in proofs)
+        // This matches how commitments are handled and how the Rust code expects the seeds
+        const nullifierBytes = Array.from(leInt2Buff(unstringifyBigInts(nullifier), 32)).reverse();
+        // Try nullifier0 seed
+        const [nullifier0PDA] = PublicKey.findProgramAddressSync([Buffer.from("nullifier0"), Buffer.from(nullifierBytes)], PROGRAM_ID);
+        logger.debug(`Derived nullifier0 PDA: ${nullifier0PDA.toBase58()}`);
+        const nullifier0Account = await connection.getAccountInfo(nullifier0PDA);
+        if (nullifier0Account !== null) {
+            logger.debug(`UTXO is spent (nullifier0 account exists)`);
+            return true;
+        }
+        const [nullifier1PDA] = PublicKey.findProgramAddressSync([Buffer.from("nullifier1"), Buffer.from(nullifierBytes)], PROGRAM_ID);
+        logger.debug(`Derived nullifier1 PDA: ${nullifier1PDA.toBase58()}`);
+        const nullifier1Account = await connection.getAccountInfo(nullifier1PDA);
+        if (nullifier1Account !== null) {
+            logger.debug(`UTXO is spent (nullifier1 account exists)`);
+            return true;
+        }
+        return false;
+    }
+    catch (error) {
+        console.error("Error checking if UTXO is spent:", error);
+        if (retries <= 0) {
+            console.error("Max retries reached for isUtxoSpent, returning false");
+            return false; // Assume unspent if we can't verify
+        }
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+        return await isUtxoSpent(connection, utxo, retries - 1);
+    }
+}
+async function areUtxosSpent(connection, utxos) {
+    try {
+        const allPDAs = [];
+        for (let i = 0; i < utxos.length; i++) {
+            const utxo = utxos[i];
+            const nullifier = await utxo.getNullifier();
+            const nullifierBytes = Array.from(leInt2Buff(unstringifyBigInts(nullifier), 32)).reverse();
+            const [nullifier0PDA] = PublicKey.findProgramAddressSync([Buffer.from("nullifier0"), Buffer.from(nullifierBytes)], PROGRAM_ID);
+            const [nullifier1PDA] = PublicKey.findProgramAddressSync([Buffer.from("nullifier1"), Buffer.from(nullifierBytes)], PROGRAM_ID);
+            allPDAs.push({ utxoIndex: i, pda: nullifier0PDA });
+            allPDAs.push({ utxoIndex: i, pda: nullifier1PDA });
+        }
+        const results = await connection.getMultipleAccountsInfo(allPDAs.map((x) => x.pda));
+        const spentFlags = new Array(utxos.length).fill(false);
+        for (let i = 0; i < allPDAs.length; i++) {
+            if (results[i] !== null) {
+                spentFlags[allPDAs[i].utxoIndex] = true;
+            }
+        }
+        return spentFlags;
+    }
+    catch (error) {
+        console.error("Error checking if UTXOs are spent:", error);
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+        return await areUtxosSpent(connection, utxos);
+    }
+}
+// Calculate total balance
+export function getBalanceFromUtxos(utxos) {
+    const totalBalance = utxos.reduce((sum, utxo) => sum.add(utxo.amount), new BN(0));
+    // const LAMPORTS_PER_SOL = new BN(1_000_000_000);
+    // const balanceInSol = totalBalance.div(LAMPORTS_PER_SOL);
+    // const remainderLamports = totalBalance.mod(LAMPORTS_PER_SOL);
+    return { lamports: totalBalance.toNumber() };
+}
+async function decrypt_outputs(encryptedOutputs, encryptionService, utxoKeypair, lightWasm) {
+    let results = [];
+    let skippedCount = 0;
+    let failedCount = 0;
+    let successCount = 0;
+    // decrypt all UTXO
+    for (const encryptedOutput of encryptedOutputs) {
+        if (!encryptedOutput) {
+            results.push({ status: "skipped" });
+            skippedCount++;
+            debugLogger.recordDecryptionSkipped();
+            continue;
+        }
+        debugLogger.recordDecryptionAttempt();
+        try {
+            const utxo = await encryptionService.decryptUtxo(encryptedOutput, lightWasm);
+            // decryptUtxo returns null for schema version mismatch (early termination)
+            if (utxo === null) {
+                results.push({ status: "skipped" });
+                skippedCount++;
+                debugLogger.recordDecryptionSkipped();
+                continue;
+            }
+            results.push({ status: "decrypted", utxo, encryptedOutput });
+            successCount++;
+            debugLogger.recordDecryptionSuccess();
+        }
+        catch (error) {
+            // Record the failure with full context instead of silently swallowing
+            debugLogger.recordDecryptionFailure(error, encryptedOutput);
+            results.push({ status: "unDecrypted" });
+            failedCount++;
+        }
+    }
+    // Log batch summary
+    debugLogger.utxoBatchSummary(encryptedOutputs.length, successCount, skippedCount, failedCount);
+    results = results.filter((r) => r.status == "decrypted");
+    if (!results.length) {
+        return [];
+    }
+    // update utxo index
+    if (results.length > 0) {
+        let encrypted_outputs = results.map((r) => r.encryptedOutput);
+        let url = RELAYER_API_URL + `/utxos/indices`;
+        let res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ encrypted_outputs }),
+        });
+        let j = await res.json();
+        if (!j.indices ||
+            !Array.isArray(j.indices) ||
+            j.indices.length != encrypted_outputs.length) {
+            throw new Error("failed fetching /utxos/indices");
+        }
+        for (let i = 0; i < results.length; i++) {
+            let utxo = results[i].utxo;
+            if (utxo.index !== j.indices[i] && typeof j.indices[i] == "number") {
+                logger.debug(`Updated UTXO index from ${utxo.index} to ${j.indices[i]}`);
+                utxo.index = j.indices[i];
+            }
+        }
+    }
+    return results;
+}

package/dist/getUtxosSPL.d.ts

@@ -0,0 +1,34 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { Utxo } from "./models/utxo.js";
+import { EncryptionService } from "./utils/encryption.js";
+export declare function localstorageKey(key: PublicKey): string;
+/**
+ * Fetch and decrypt all UTXOs for a user
+ * @param signed The user's signature
+ * @param connection Solana connection to fetch on-chain commitment accounts
+ * @param setStatus A global state updator. Set live status message showing on webpage
+ * @returns Array of decrypted UTXOs that belong to the user
+ */
+export declare function getUtxosSPL({ publicKey, connection, encryptionService, storage, abortSignal, offset, mintAddress, }: {
+    publicKey: PublicKey;
+    connection: Connection;
+    encryptionService: EncryptionService;
+    storage: Storage;
+    mintAddress: PublicKey | string;
+    abortSignal?: AbortSignal;
+    offset?: number;
+}): Promise<Utxo[]>;
+/**
+ * Check if a UTXO has been spent
+ * @param connection Solana connection
+ * @param utxo The UTXO to check
+ * @param retries Number of retries remaining (default 3)
+ * @returns Promise<boolean> true if spent, false if unspent
+ */
+export declare function isUtxoSpent(connection: Connection, utxo: Utxo, retries?: number): Promise<boolean>;
+export declare function getBalanceFromUtxosSPL(utxos: Utxo[]): {
+    base_units: number;
+    amount: number;
+    /** @deprecated use base_units instead */
+    lamports: number;
+};