@velumdotcash/sdk 2.0.0

package/dist/index.js

@@ -0,0 +1,436 @@
+import { Connection, Keypair, LAMPORTS_PER_SOL, PublicKey, } from "@solana/web3.js";
+import { deposit } from "./deposit.js";
+import { getBalanceFromUtxos, getUtxos, localstorageKey } from "./getUtxos.js";
+import { getBalanceFromUtxosSPL, getUtxosSPL } from "./getUtxosSPL.js";
+// Re-export error classes for consumers
+export { PrivacyCashError, ZKProofError, NetworkError, InsufficientBalanceError, DepositLimitError, TransactionTimeoutError, } from "./errors.js";
+// Re-export debug logging utilities for consumers
+export { enableDebugLogging, disableDebugLogging, isDebugEnabled, setDebugLogger, enableVerboseLogging, disableVerboseLogging, isVerboseEnabled, } from "./utils/debug-logger.js";
+import { LSK_ENCRYPTED_OUTPUTS, LSK_FETCH_OFFSET, tokens, USDC_MINT, } from "./utils/constants.js";
+import { logger, setLogger } from "./utils/logger.js";
+import { EncryptionService } from "./utils/encryption.js";
+import { enableDebugLogging, disableDebugLogging, isDebugEnabled, debugLogger, } from "./utils/debug-logger.js";
+import { WasmFactory } from "@lightprotocol/hasher.rs";
+import bs58 from "bs58";
+import { withdraw } from "./withdraw.js";
+import { depositSPL } from "./depositSPL.js";
+import { withdrawSPL } from "./withdrawSPL.js";
+import { getAssociatedTokenAddress } from "@solana/spl-token";
+import { Keypair as UtxoKeypair } from "./models/keypair.js";
+export class PrivacyCash {
+    connection;
+    publicKey;
+    encryptionService;
+    keypair;
+    transactionSigner;
+    isRuning = false;
+    status = "";
+    storage;
+    circuitPath;
+    debugMode = false;
+    constructor({ RPC_url, owner, publicKey, signature, transactionSigner, enableDebug, debugLogger: customDebugLogger, storage, circuitPath, }) {
+        this.connection = new Connection(RPC_url, "confirmed");
+        this.encryptionService = new EncryptionService();
+        // Configure debug logging for V3 decryption diagnostics
+        if (customDebugLogger === true) {
+            enableDebugLogging();
+            this.debugMode = true;
+        }
+        else if (typeof customDebugLogger === 'function') {
+            enableDebugLogging(customDebugLogger);
+            this.debugMode = true;
+        }
+        else if (isDebugEnabled()) {
+            // Environment variable is already set
+            this.debugMode = true;
+        }
+        if (owner) {
+            let keypair = getSolanaKeypair(owner);
+            if (!keypair) {
+                throw new Error('param "owner" is not a valid Private Key or Keypair');
+            }
+            this.keypair = keypair;
+            this.publicKey = keypair.publicKey;
+            this.encryptionService.deriveEncryptionKeyFromWallet(this.keypair);
+        }
+        else if (publicKey && signature) {
+            this.publicKey = publicKey;
+            this.encryptionService.deriveEncryptionKeyFromSignature(signature);
+            this.transactionSigner = transactionSigner;
+        }
+        else {
+            throw new Error('Either "owner" (Keypair) or "publicKey" + "signature" must be provided');
+        }
+        if (storage) {
+            this.storage = storage;
+        }
+        else if (typeof window !== "undefined" && window.localStorage) {
+            this.storage = window.localStorage;
+        }
+        else {
+            throw new Error("Storage implementation must be provided in non-browser environments");
+        }
+        this.circuitPath = circuitPath || "/circuit";
+        if (!enableDebug) {
+            this.startStatusRender();
+            this.setLogger((level, message) => {
+                if (level == "info") {
+                    this.status = message;
+                }
+                else if (level == "error") {
+                    console.log("error message: ", message);
+                }
+            });
+        }
+    }
+    /**
+     * Enable debug logging for V3 decryption diagnostics.
+     * Useful for troubleshooting paylink balance issues.
+     * @param customLogger Optional custom logger function
+     */
+    enableDecryptionDebug(customLogger) {
+        enableDebugLogging(customLogger);
+        this.debugMode = true;
+        return this;
+    }
+    /**
+     * Disable debug logging
+     */
+    disableDecryptionDebug() {
+        disableDebugLogging();
+        this.debugMode = false;
+        return this;
+    }
+    /**
+     * Check if debug logging is currently enabled
+     */
+    isDecryptionDebugEnabled() {
+        return this.debugMode || isDebugEnabled();
+    }
+    setLogger(loger) {
+        setLogger(loger);
+        return this;
+    }
+    getSigner() {
+        if (this.transactionSigner) {
+            return this.transactionSigner;
+        }
+        return async (tx) => {
+            if (!this.keypair)
+                throw new Error("No signer available");
+            tx.sign([this.keypair]);
+            return tx;
+        };
+    }
+    /**
+     * Clears the cache of utxos.
+     *
+     * By default, downloaded utxos will be cached in the local storage. Thus the next time when you makes another
+     * deposit or withdraw or getPrivateBalance, the SDK only fetches the utxos that are not in the cache.
+     *
+     * This method clears the cache of utxos.
+     */
+    async clearCache() {
+        if (!this.publicKey) {
+            return this;
+        }
+        this.storage.removeItem(LSK_FETCH_OFFSET + localstorageKey(this.publicKey));
+        this.storage.removeItem(LSK_ENCRYPTED_OUTPUTS + localstorageKey(this.publicKey));
+        // spl
+        for (let token of tokens) {
+            let ata = await getAssociatedTokenAddress(token.pubkey, this.publicKey);
+            this.storage.removeItem(LSK_FETCH_OFFSET + localstorageKey(ata));
+            this.storage.removeItem(LSK_ENCRYPTED_OUTPUTS + localstorageKey(ata));
+        }
+        return this;
+    }
+    /**
+     * Deposit SOL to the Privacy Cash.
+     *
+     * Lamports is the amount of SOL in lamports. e.g. if you want to deposit 0.01 SOL (10000000 lamports), call deposit({ lamports: 10000000 })
+     */
+    async deposit({ lamports, recipientUtxoPublicKey, recipientEncryptionKey, }) {
+        this.isRuning = true;
+        logger.info("start depositting");
+        let lightWasm = await WasmFactory.getInstance();
+        const transactionSigner = this.getSigner();
+        let res = await deposit({
+            lightWasm,
+            amount_in_lamports: lamports,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            publicKey: this.publicKey,
+            transactionSigner,
+            keyBasePath: this.circuitPath,
+            storage: this.storage,
+            recipientUtxoPublicKey,
+            recipientEncryptionKey,
+        });
+        this.isRuning = false;
+        return res;
+    }
+    /**
+     * Deposit USDC to the Privacy Cash.
+     */
+    async depositUSDC({ base_units, recipientUtxoPublicKey, recipientEncryptionKey, }) {
+        this.isRuning = true;
+        logger.info("start depositting");
+        let lightWasm = await WasmFactory.getInstance();
+        const transactionSigner = this.getSigner();
+        let res = await depositSPL({
+            mintAddress: USDC_MINT,
+            lightWasm,
+            base_units: base_units,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            publicKey: this.publicKey,
+            transactionSigner,
+            keyBasePath: this.circuitPath,
+            storage: this.storage,
+            recipientUtxoPublicKey,
+            recipientEncryptionKey,
+        });
+        this.isRuning = false;
+        return res;
+    }
+    /**
+     * Withdraw SOL from the Privacy Cash.
+     *
+     * Lamports is the amount of SOL in lamports. e.g. if you want to withdraw 0.01 SOL (10000000 lamports), call withdraw({ lamports: 10000000 })
+     */
+    async withdraw({ lamports, recipientAddress, referrer, }) {
+        this.isRuning = true;
+        logger.info("start withdrawing");
+        let lightWasm = await WasmFactory.getInstance();
+        let recipient = recipientAddress
+            ? new PublicKey(recipientAddress)
+            : this.publicKey;
+        let res = await withdraw({
+            lightWasm,
+            amount_in_lamports: lamports,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            publicKey: this.publicKey,
+            recipient,
+            keyBasePath: this.circuitPath,
+            storage: this.storage,
+            referrer,
+        });
+        logger.debug(`Withdraw successful. Recipient ${recipient} received ${res.amount_in_lamports / LAMPORTS_PER_SOL} SOL, with ${res.fee_in_lamports / LAMPORTS_PER_SOL} SOL relayers fees`);
+        this.isRuning = false;
+        return res;
+    }
+    /**
+     * Withdraw USDC from the Privacy Cash.
+     *
+     * base_units is the amount of USDC in base unit. e.g. if you want to withdraw 1 USDC (1,000,000 base unit), call withdraw({ base_units: 1000000, recipientAddress: 'some_address' })
+     */
+    async withdrawUSDC({ base_units, recipientAddress, referrer, }) {
+        this.isRuning = true;
+        logger.info("start withdrawing");
+        let lightWasm = await WasmFactory.getInstance();
+        let recipient = recipientAddress
+            ? new PublicKey(recipientAddress)
+            : this.publicKey;
+        let res = await withdrawSPL({
+            mintAddress: USDC_MINT,
+            lightWasm,
+            base_units,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            publicKey: this.publicKey,
+            recipient,
+            keyBasePath: this.circuitPath,
+            storage: this.storage,
+            referrer,
+        });
+        logger.debug(`Withdraw successful. Recipient ${recipient} received ${base_units} USDC units`);
+        this.isRuning = false;
+        return res;
+    }
+    /**
+     * Returns the amount of lamports current wallet has in Privacy Cash.
+     * Also tracks and summarizes any decryption failures for debugging.
+     */
+    async getPrivateBalance(abortSignal) {
+        logger.info("getting private balance");
+        this.isRuning = true;
+        // Start failure tracking for this balance fetch
+        debugLogger.startFailureTracking();
+        let utxos = await getUtxos({
+            publicKey: this.publicKey,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            storage: this.storage,
+            abortSignal,
+        });
+        // End failure tracking and get summary
+        const failureSummary = debugLogger.endFailureTracking();
+        this.isRuning = false;
+        const balance = getBalanceFromUtxos(utxos);
+        return { ...balance, failureSummary };
+    }
+    /**
+     * Returns the amount of base units current wallet has in Privacy Cash.
+     * Also tracks and summarizes any decryption failures for debugging.
+     */
+    async getPrivateBalanceUSDC() {
+        logger.info("getting private balance");
+        this.isRuning = true;
+        // Start failure tracking for this balance fetch
+        debugLogger.startFailureTracking();
+        let utxos = await getUtxosSPL({
+            publicKey: this.publicKey,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            storage: this.storage,
+            mintAddress: USDC_MINT,
+        });
+        // End failure tracking and get summary
+        const failureSummary = debugLogger.endFailureTracking();
+        this.isRuning = false;
+        const balance = getBalanceFromUtxosSPL(utxos);
+        return { ...balance, failureSummary };
+    }
+    /**
+     * Returns the amount of base units current wallet has in Privacy Cash.
+     * Also tracks and summarizes any decryption failures for debugging.
+     */
+    async getPrivateBalanceSpl(mintAddress) {
+        logger.info("getting private balance for SPL token");
+        this.isRuning = true;
+        // Start failure tracking for this balance fetch
+        debugLogger.startFailureTracking();
+        let utxos = await getUtxosSPL({
+            publicKey: this.publicKey,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            storage: this.storage,
+            mintAddress,
+        });
+        // End failure tracking and get summary
+        const failureSummary = debugLogger.endFailureTracking();
+        this.isRuning = false;
+        const balance = getBalanceFromUtxosSPL(utxos);
+        return { ...balance, failureSummary };
+    }
+    /**
+     * Returns true if the code is running in a browser.
+     */
+    isBrowser() {
+        return typeof window !== "undefined";
+    }
+    async startStatusRender() {
+        let frames = ["-", "\\", "|", "/"];
+        let i = 0;
+        while (true) {
+            if (this.isRuning) {
+                let k = i % frames.length;
+                i++;
+                stdWrite(this.status, frames[k]);
+            }
+            await new Promise((r) => setTimeout(r, 250));
+        }
+    }
+    /**
+     * Deposit SPL to the Privacy Cash.
+     */
+    async depositSPL({ base_units, mintAddress, amount, recipientUtxoPublicKey, recipientEncryptionKey, }) {
+        this.isRuning = true;
+        logger.info("start depositting");
+        let lightWasm = await WasmFactory.getInstance();
+        const transactionSigner = this.getSigner();
+        let res = await depositSPL({
+            lightWasm,
+            base_units,
+            amount,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            publicKey: this.publicKey,
+            transactionSigner,
+            keyBasePath: this.circuitPath,
+            storage: this.storage,
+            mintAddress,
+            recipientUtxoPublicKey,
+            recipientEncryptionKey,
+        });
+        this.isRuning = false;
+        return res;
+    }
+    /**
+     * Withdraw SPL from the Privacy Cash.
+     */
+    async withdrawSPL({ base_units, mintAddress, recipientAddress, amount, referrer, }) {
+        this.isRuning = true;
+        logger.info("start withdrawing");
+        let lightWasm = await WasmFactory.getInstance();
+        let recipient = recipientAddress
+            ? new PublicKey(recipientAddress)
+            : this.publicKey;
+        let res = await withdrawSPL({
+            lightWasm,
+            base_units,
+            amount,
+            connection: this.connection,
+            encryptionService: this.encryptionService,
+            publicKey: this.publicKey,
+            recipient,
+            keyBasePath: this.circuitPath,
+            storage: this.storage,
+            mintAddress,
+            referrer,
+        });
+        logger.debug(`Withdraw successful. Recipient ${recipient} received ${base_units} USDC units`);
+        this.isRuning = false;
+        return res;
+    }
+    /**
+     * Returns the asymmetric encryption public key (X25519) for receiving encrypted paylink data.
+     * This key is used by senders to encrypt UTXO data that only this wallet can decrypt.
+     */
+    getAsymmetricPublicKey() {
+        return this.encryptionService.getAsymmetricPublicKey();
+    }
+    /**
+     * Returns the shielded public key (BN254 curve point) for receiving private payments.
+     * This is the UTXO ownership key derived from the wallet signature.
+     */
+    async getShieldedPublicKey() {
+        const lightWasm = await WasmFactory.getInstance();
+        const privateKeyHex = this.encryptionService.getUtxoPrivateKeyV2();
+        const keypair = new UtxoKeypair(privateKeyHex, lightWasm);
+        return keypair.pubkey.toString();
+    }
+}
+function getSolanaKeypair(secret) {
+    try {
+        if (secret instanceof Keypair) {
+            return secret;
+        }
+        let keyArray;
+        if (typeof secret === "string") {
+            keyArray = bs58.decode(secret);
+        }
+        else if (secret instanceof Uint8Array) {
+            keyArray = secret;
+        }
+        else {
+            // number[]
+            keyArray = Uint8Array.from(secret);
+        }
+        if (keyArray.length !== 32 && keyArray.length !== 64) {
+            return null;
+        }
+        return Keypair.fromSecretKey(keyArray);
+    }
+    catch {
+        return null;
+    }
+}
+function stdWrite(status, frame) {
+    if (typeof process !== "undefined" && process.stdout?.write) {
+        let blue = "\x1b[34m";
+        let reset = "\x1b[0m";
+        process.stdout.write(`${frame}status: ${blue}${status}${reset}\r`);
+    }
+}

package/dist/models/keypair.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Keypair module for ZK Cash
+ *
+ * Provides cryptographic keypair functionality for the ZK Cash system
+ * Based on: https://github.com/tornadocash/tornado-nova
+ */
+import BN from 'bn.js';
+import * as hasher from '@lightprotocol/hasher.rs';
+/**
+ * Simplified version of Keypair
+ */
+export declare class Keypair {
+    privkey: BN;
+    pubkey: BN;
+    private lightWasm;
+    constructor(privkeyHex: string, lightWasm: hasher.LightWasm);
+    /**
+    * Sign a message using keypair private key
+    *
+    * @param {string|number|BigNumber} commitment a hex string with commitment
+    * @param {string|number|BigNumber} merklePath a hex string with merkle path
+    * @returns {BigNumber} a hex string with signature
+    */
+    sign(commitment: string, merklePath: string): string;
+    static generateNew(lightWasm: hasher.LightWasm): Promise<Keypair>;
+}

package/dist/models/keypair.js

@@ -0,0 +1,43 @@
+/**
+ * Keypair module for ZK Cash
+ *
+ * Provides cryptographic keypair functionality for the ZK Cash system
+ * Based on: https://github.com/tornadocash/tornado-nova
+ */
+import BN from 'bn.js';
+import { ethers } from 'ethers';
+// Field size constant
+const FIELD_SIZE = new BN('21888242871839275222246405745257275088548364400416034343698204186575808495617');
+/**
+ * Simplified version of Keypair
+ */
+export class Keypair {
+    privkey;
+    pubkey;
+    lightWasm;
+    constructor(privkeyHex, lightWasm) {
+        const rawDecimal = BigInt(privkeyHex);
+        this.privkey = new BN((rawDecimal % BigInt(FIELD_SIZE.toString())).toString());
+        this.lightWasm = lightWasm;
+        // TODO: lazily compute pubkey
+        this.pubkey = new BN(this.lightWasm.poseidonHashString([this.privkey.toString()]));
+    }
+    /**
+    * Sign a message using keypair private key
+    *
+    * @param {string|number|BigNumber} commitment a hex string with commitment
+    * @param {string|number|BigNumber} merklePath a hex string with merkle path
+    * @returns {BigNumber} a hex string with signature
+    */
+    sign(commitment, merklePath) {
+        return this.lightWasm.poseidonHashString([this.privkey.toString(), commitment, merklePath]);
+    }
+    static async generateNew(lightWasm) {
+        // Tornado Cash Nova uses ethers.js to generate a random private key
+        // We can't generate Solana keypairs because it won't fit in the field size
+        // It's OK to use ethereum secret keys, because the secret key is only used for the proof generation.
+        // Namely, it's used to guarantee the uniqueness of the nullifier.
+        const wallet = ethers.Wallet.createRandom();
+        return new Keypair(wallet.privateKey, lightWasm);
+    }
+}

package/dist/models/utxo.d.ts

@@ -0,0 +1,51 @@
+/**
+ * UTXO (Unspent Transaction Output) module for ZK Cash
+ *
+ * Provides UTXO functionality for the ZK Cash system
+ * Based on: https://github.com/tornadocash/tornado-nova
+ */
+import BN from 'bn.js';
+import { Keypair } from './keypair.js';
+import * as hasher from '@lightprotocol/hasher.rs';
+/**
+ * Simplified Utxo class inspired by Tornado Cash Nova
+ * Based on: https://github.com/tornadocash/tornado-nova/blob/f9264eeffe48bf5e04e19d8086ee6ec58cdf0d9e/src/utxo.js
+ */
+export declare class Utxo {
+    amount: BN;
+    blinding: BN;
+    keypair?: Keypair;
+    pubkey: BN;
+    index: number;
+    mintAddress: string;
+    version: 'v1' | 'v2';
+    private lightWasm;
+    constructor({ lightWasm, amount, 
+    /**
+     * Tornado nova doesn't use solana eddsa with curve 25519 but their own "keypair"
+     * which is:
+     * - private key: random [31;u8]
+     * - public key: PoseidonHash(privateKey)
+     *
+     * Generate a new keypair for each UTXO
+     */
+    keypair, publicKey, blinding, // Use fixed value for consistency instead of randomBN()
+    index, mintAddress, // Default to Solana native SOL mint address,
+    version }: {
+        lightWasm: hasher.LightWasm;
+        amount?: BN | number | string;
+        keypair?: Keypair;
+        publicKey?: BN | string;
+        blinding?: BN | number | string;
+        index?: number;
+        mintAddress?: string;
+        version?: 'v1' | 'v2';
+    });
+    getCommitment(): Promise<string>;
+    getNullifier(): Promise<string>;
+    /**
+     * Log all the UTXO's public properties and derived values in JSON format
+     * @returns Promise that resolves once all logging is complete
+     */
+    log(): Promise<void>;
+}

package/dist/models/utxo.js

@@ -0,0 +1,99 @@
+/**
+ * UTXO (Unspent Transaction Output) module for ZK Cash
+ *
+ * Provides UTXO functionality for the ZK Cash system
+ * Based on: https://github.com/tornadocash/tornado-nova
+ */
+import BN from 'bn.js';
+import { Keypair } from './keypair.js';
+import { ethers } from 'ethers';
+import { getMintAddressField } from '../utils/utils.js';
+import { PublicKey } from '@solana/web3.js';
+/**
+ * Simplified Utxo class inspired by Tornado Cash Nova
+ * Based on: https://github.com/tornadocash/tornado-nova/blob/f9264eeffe48bf5e04e19d8086ee6ec58cdf0d9e/src/utxo.js
+ */
+export class Utxo {
+    amount;
+    blinding;
+    keypair;
+    pubkey;
+    index;
+    mintAddress;
+    version;
+    lightWasm;
+    constructor({ lightWasm, amount = new BN(0), 
+    /**
+     * Tornado nova doesn't use solana eddsa with curve 25519 but their own "keypair"
+     * which is:
+     * - private key: random [31;u8]
+     * - public key: PoseidonHash(privateKey)
+     *
+     * Generate a new keypair for each UTXO
+     */
+    keypair, publicKey, blinding = new BN(Math.floor(Math.random() * 1000000000)), // Use fixed value for consistency instead of randomBN()
+    index = 0, mintAddress = '11111111111111111111111111111112', // Default to Solana native SOL mint address,
+    version = 'v2' }) {
+        this.amount = new BN(amount.toString());
+        this.blinding = new BN(blinding.toString());
+        this.lightWasm = lightWasm;
+        if (keypair) {
+            this.keypair = keypair;
+            this.pubkey = keypair.pubkey;
+        }
+        else if (publicKey) {
+            this.pubkey = new BN(publicKey.toString());
+        }
+        else {
+            this.keypair = new Keypair(ethers.Wallet.createRandom().privateKey, lightWasm);
+            this.pubkey = this.keypair.pubkey;
+        }
+        this.index = index;
+        this.mintAddress = mintAddress;
+        this.version = version;
+    }
+    async getCommitment() {
+        // return this.lightWasm.poseidonHashString([this.amount.toString(), this.keypair.pubkey.toString(), this.blinding.toString(), this.mintAddress]);
+        const mintAddressField = getMintAddressField(new PublicKey(this.mintAddress));
+        return this.lightWasm.poseidonHashString([
+            this.amount.toString(),
+            this.pubkey.toString(),
+            this.blinding.toString(),
+            mintAddressField
+        ]);
+    }
+    async getNullifier() {
+        if (!this.keypair) {
+            throw new Error('Cannot generate nullifier without private key');
+        }
+        const commitmentValue = await this.getCommitment();
+        const signature = this.keypair.sign(commitmentValue, new BN(this.index).toString());
+        return this.lightWasm.poseidonHashString([commitmentValue, new BN(this.index).toString(), signature]);
+    }
+    /**
+     * Log all the UTXO's public properties and derived values in JSON format
+     * @returns Promise that resolves once all logging is complete
+     */
+    async log() {
+        // Prepare the UTXO data object
+        const utxoData = {
+            amount: this.amount.toString(),
+            blinding: this.blinding.toString(),
+            index: this.index,
+            mintAddress: this.mintAddress,
+            keypair: {
+                pubkey: this.pubkey.toString()
+            }
+        };
+        // Add derived values
+        try {
+            utxoData.commitment = await this.getCommitment();
+            utxoData.nullifier = await this.getNullifier();
+        }
+        catch (error) {
+            utxoData.error = error.message;
+        }
+        // Output as formatted JSON
+        console.log(JSON.stringify(utxoData, null, 2));
+    }
+}

package/dist/test_paylink_logic.test.d.ts

@@ -0,0 +1 @@
+export {};