@velumdotcash/sdk 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Velum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @velumdotcash/sdk
+
+TypeScript SDK for private payments on Solana using Zero-Knowledge proofs.
+
+## Installation
+
+```bash
+npm install @velumdotcash/sdk
+```
+
+## Quick Start
+
+```typescript
+import { PrivacyCash } from "@velumdotcash/sdk";
+
+// Initialize with wallet signature (browser)
+const sdk = new PrivacyCash({
+  RPC_url: "https://api.mainnet-beta.solana.com",
+  publicKey: walletPublicKey,
+  signature: walletSignature,
+  transactionSigner: async (tx) => wallet.signTransaction(tx),
+});
+
+// Or with keypair (Node.js / scripts)
+const sdk = new PrivacyCash({
+  RPC_url: "https://api.mainnet-beta.solana.com",
+  owner: keypair,
+});
+```
+
+## API Reference
+
+### Deposits
+
+```typescript
+// Deposit SOL
+await sdk.deposit({ lamports: 10_000_000 });
+
+// Deposit USDC
+await sdk.depositUSDC({ base_units: 1_000_000 });
+
+// Deposit any SPL token
+await sdk.depositSPL({ base_units: 1_000_000, mintAddress: "..." });
+
+// Deposit to a third-party recipient
+await sdk.deposit({
+  lamports: 10_000_000,
+  recipientUtxoPublicKey: "...",
+  recipientEncryptionKey: encryptionKeyBytes,
+});
+```
+
+### Withdrawals
+
+```typescript
+// Withdraw SOL
+await sdk.withdraw({ lamports: 10_000_000, recipientAddress: "..." });
+
+// Withdraw USDC
+await sdk.withdrawUSDC({ base_units: 1_000_000, recipientAddress: "..." });
+
+// Withdraw any SPL token
+await sdk.withdrawSPL({
+  base_units: 1_000_000,
+  mintAddress: "...",
+  recipientAddress: "...",
+});
+```
+
+### Balance
+
+```typescript
+const sol = await sdk.getPrivateBalance();
+console.log(sol.lamports);
+
+const usdc = await sdk.getPrivateBalanceUSDC();
+console.log(usdc.base_units);
+
+const spl = await sdk.getPrivateBalanceSpl(mintAddress);
+console.log(spl.base_units);
+```
+
+### Key Derivation
+
+```typescript
+// Get public keys for receiving payments
+const encryptionKey = sdk.getAsymmetricPublicKey(); // Uint8Array
+const utxoPubkey = await sdk.getShieldedPublicKey(); // string
+```
+
+## Browser Usage
+
+The SDK works in browsers with wallet adapter integration. Circuit files (WASM + zkey) must be served from your application's public directory.
+
+```typescript
+const sdk = new PrivacyCash({
+  RPC_url: rpcEndpoint,
+  publicKey: walletPublicKey,
+  signature: walletSignature,
+  transactionSigner: async (tx) => wallet.signTransaction(tx),
+  circuitPath: "/circuit", // path to circuit files in public/
+});
+```
+
+## Node.js Usage
+
+For server-side scripts and testing:
+
+```typescript
+import { Keypair } from "@solana/web3.js";
+
+const keypair = Keypair.fromSecretKey(secretKey);
+const sdk = new PrivacyCash({
+  RPC_url: process.env.SOLANA_RPC_URL!,
+  owner: keypair,
+  storage: new LocalStorage("./cache"),
+  circuitPath: "./circuits",
+  enableDebug: true,
+});
+```
+
+## Error Handling
+
+```typescript
+import {
+  InsufficientBalanceError,
+  ZKProofError,
+  NetworkError,
+  TransactionTimeoutError,
+} from "@velumdotcash/sdk";
+
+try {
+  await sdk.deposit({ lamports: amount });
+} catch (err) {
+  if (err instanceof InsufficientBalanceError) { /* ... */ }
+  if (err instanceof ZKProofError) { /* ... */ }
+}
+```
+
+## License
+
+ISC

package/dist/__tests__/paylink.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Integration tests for Privacy Paylink third-party deposit functionality
+ *
+ * These tests verify that:
+ * 1. Utxo can be created with only a public key (no private key)
+ * 2. Asymmetric encryption works correctly
+ * 3. Third-party deposits work end-to-end
+ */
+export {};

package/dist/__tests__/paylink.test.js

@@ -0,0 +1,254 @@
+/**
+ * Integration tests for Privacy Paylink third-party deposit functionality
+ *
+ * These tests verify that:
+ * 1. Utxo can be created with only a public key (no private key)
+ * 2. Asymmetric encryption works correctly
+ * 3. Third-party deposits work end-to-end
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { Utxo } from "../models/utxo";
+import { Keypair } from "../models/keypair";
+import { EncryptionService } from "../utils/encryption";
+import { WasmFactory } from "@lightprotocol/hasher.rs";
+import BN from "bn.js";
+import nacl from "tweetnacl";
+describe("Paylink Core Functionality", () => {
+    let lightWasm;
+    beforeAll(async () => {
+        // Initialize WASM - required for all crypto operations
+        lightWasm = await WasmFactory.getInstance();
+    });
+    describe("Utxo pubkey-only mode", () => {
+        it("should create Utxo with only publicKey", async () => {
+            // Generate a keypair to get a valid public key
+            const keypair = await Keypair.generateNew(lightWasm);
+            const pubkey = keypair.pubkey;
+            // Create Utxo with only the public key
+            const utxo = new Utxo({
+                lightWasm,
+                amount: new BN(1000000),
+                publicKey: pubkey,
+            });
+            expect(utxo.pubkey.toString()).toBe(pubkey.toString());
+            expect(utxo.amount.toNumber()).toBe(1000000);
+        });
+        it("should allow getCommitment() with pubkey-only Utxo", async () => {
+            const keypair = await Keypair.generateNew(lightWasm);
+            const utxo = new Utxo({
+                lightWasm,
+                amount: new BN(500000),
+                publicKey: keypair.pubkey,
+            });
+            // getCommitment should work without private key (async)
+            const commitment = await utxo.getCommitment();
+            expect(commitment).toBeDefined();
+            expect(typeof commitment).toBe("string");
+        });
+        it("should throw on getNullifier() with pubkey-only Utxo", async () => {
+            const keypair = await Keypair.generateNew(lightWasm);
+            const utxo = new Utxo({
+                lightWasm,
+                amount: new BN(500000),
+                publicKey: keypair.pubkey,
+            });
+            // getNullifier requires private key, should throw
+            await expect(utxo.getNullifier()).rejects.toThrow();
+        });
+        it("should work normally with full keypair", async () => {
+            const keypair = await Keypair.generateNew(lightWasm);
+            const utxo = new Utxo({
+                lightWasm,
+                amount: new BN(1000000),
+                keypair: keypair,
+            });
+            // Both should work with full keypair
+            const commitment = await utxo.getCommitment();
+            const nullifier = await utxo.getNullifier();
+            expect(commitment).toBeDefined();
+            expect(nullifier).toBeDefined();
+        });
+    });
+    describe("Asymmetric Encryption", () => {
+        let aliceEncryption;
+        let bobEncryption;
+        beforeAll(async () => {
+            // Simulate two different wallets by deriving from different signatures
+            const aliceSignature = nacl.randomBytes(64);
+            const bobSignature = nacl.randomBytes(64);
+            aliceEncryption = new EncryptionService();
+            aliceEncryption.deriveEncryptionKeyFromSignature(aliceSignature);
+            bobEncryption = new EncryptionService();
+            bobEncryption.deriveEncryptionKeyFromSignature(bobSignature);
+        });
+        it("should get asymmetric public key", () => {
+            const alicePubKey = aliceEncryption.getAsymmetricPublicKey();
+            expect(alicePubKey).toBeDefined();
+            expect(alicePubKey.length).toBe(32); // X25519 public key is 32 bytes
+        });
+        it("should encrypt for recipient using asymmetric encryption", () => {
+            const alicePubKey = aliceEncryption.getAsymmetricPublicKey();
+            const testData = Buffer.from("Hello Alice, this is a secret message!");
+            // Bob encrypts for Alice
+            const encrypted = bobEncryption.encryptAsymmetric(testData, alicePubKey);
+            expect(encrypted).toBeDefined();
+            expect(encrypted.length).toBeGreaterThan(testData.length); // Should have nonce + ephemeral key overhead
+        });
+        it("should decrypt via decryptUtxo for V3 encrypted data", async () => {
+            const alicePubKey = aliceEncryption.getAsymmetricPublicKey();
+            // Create a simple UTXO to encrypt
+            const keypair = await Keypair.generateNew(lightWasm);
+            const utxo = new Utxo({
+                lightWasm,
+                amount: new BN(1_000_000_000),
+                publicKey: keypair.pubkey,
+            });
+            // Bob encrypts UTXO for Alice using asymmetric encryption
+            const encrypted = bobEncryption.encryptUtxo(utxo, alicePubKey);
+            // Verify it's V3 format (first byte should be 0x03 is at the end of the 8-byte buffer)
+            expect(encrypted[7]).toBe(0x03);
+            // Alice can decrypt via decryptUtxo (handles V3 internally)
+            const decrypted = await aliceEncryption.decryptUtxo(encrypted, lightWasm);
+            expect(decrypted).toBeDefined();
+            expect(decrypted.amount.toString()).toBe(utxo.amount.toString());
+        });
+        it("should fail decryption with wrong key", async () => {
+            const alicePubKey = aliceEncryption.getAsymmetricPublicKey();
+            const keypair = await Keypair.generateNew(lightWasm);
+            const utxo = new Utxo({
+                lightWasm,
+                amount: new BN(1_000_000_000),
+                publicKey: keypair.pubkey,
+            });
+            // Bob encrypts for Alice
+            const encrypted = bobEncryption.encryptUtxo(utxo, alicePubKey);
+            // Bob tries to decrypt his own encrypted data for Alice - should fail
+            try {
+                await bobEncryption.decryptUtxo(encrypted, lightWasm);
+                expect(true).toBe(false); // Should not reach here
+            }
+            catch (e) {
+                expect(e).toBeDefined();
+            }
+        });
+    });
+    describe("UTXO Encryption for Third-Party", () => {
+        let senderEncryption;
+        let recipientEncryption;
+        let recipientKeypair;
+        beforeAll(async () => {
+            const senderSignature = nacl.randomBytes(64);
+            const recipientSignature = nacl.randomBytes(64);
+            senderEncryption = new EncryptionService();
+            senderEncryption.deriveEncryptionKeyFromSignature(senderSignature);
+            recipientEncryption = new EncryptionService();
+            recipientEncryption.deriveEncryptionKeyFromSignature(recipientSignature);
+            recipientKeypair = await Keypair.generateNew(lightWasm);
+        });
+        it("should encrypt UTXO for recipient", () => {
+            const recipientEncKey = recipientEncryption.getAsymmetricPublicKey();
+            // Create UTXO owned by recipient
+            const utxo = new Utxo({
+                lightWasm,
+                amount: new BN(1_000_000_000), // 1 SOL
+                publicKey: recipientKeypair.pubkey,
+            });
+            // Sender encrypts UTXO data for recipient
+            const encrypted = senderEncryption.encryptUtxo(utxo, recipientEncKey);
+            expect(encrypted).toBeDefined();
+            expect(encrypted.length).toBeGreaterThan(0);
+            // First byte should be V3 version marker (0x03 is at the end of the 8-byte buffer)
+            expect(encrypted[7]).toBe(0x03);
+        });
+        it("should allow recipient to decrypt UTXO", async () => {
+            // For this test to work, recipientKeypair must match what EncryptionService derives
+            const recipientPrivKey = recipientEncryption.getUtxoPrivateKeyV2();
+            // Re-instantiate the keypair that matches the encryption service
+            const derivedRecipientKeypair = new Keypair(recipientPrivKey, lightWasm);
+            const recipientEncKey = recipientEncryption.getAsymmetricPublicKey();
+            // Create UTXO owned by recipient
+            const originalAmount = new BN(2_500_000_000); // 2.5 SOL
+            const utxo = new Utxo({
+                lightWasm,
+                amount: originalAmount,
+                publicKey: derivedRecipientKeypair.pubkey,
+            });
+            // Sender encrypts for recipient
+            const encrypted = senderEncryption.encryptUtxo(utxo, recipientEncKey);
+            // Recipient decrypts
+            const decryptedUtxo = await recipientEncryption.decryptUtxo(encrypted, lightWasm);
+            expect(decryptedUtxo).toBeDefined();
+            expect(decryptedUtxo.amount.toString()).toBe(originalAmount.toString());
+            expect(decryptedUtxo.pubkey.toString()).toBe(derivedRecipientKeypair.pubkey.toString());
+        });
+        it("should not allow sender to decrypt their own encrypted UTXO for recipient", async () => {
+            const recipientEncKey = recipientEncryption.getAsymmetricPublicKey();
+            const utxo = new Utxo({
+                lightWasm,
+                amount: new BN(1_000_000_000),
+                publicKey: recipientKeypair.pubkey,
+            });
+            // Sender encrypts for recipient
+            const encrypted = senderEncryption.encryptUtxo(utxo, recipientEncKey);
+            // Sender tries to decrypt - should fail
+            try {
+                await senderEncryption.decryptUtxo(encrypted, lightWasm);
+                // If we get here, it failed to throw
+                expect(true).toBe(false);
+            }
+            catch (error) {
+                expect(error).toBeDefined();
+            }
+        });
+    });
+    describe("End-to-End Paylink Flow (Unit)", () => {
+        it("should support complete paylink flow", async () => {
+            // === RECIPIENT GENERATES PAYLINK ===
+            const recipientSignature = nacl.randomBytes(64);
+            const recipientEncryption = new EncryptionService();
+            recipientEncryption.deriveEncryptionKeyFromSignature(recipientSignature);
+            const recipientUtxoKeypair = await Keypair.generateNew(lightWasm);
+            // These would be encoded in the paylink URL
+            const paylinkData = {
+                recipientUtxoPubkey: recipientUtxoKeypair.pubkey.toString(),
+                recipientEncryptionKey: Buffer.from(recipientEncryption.getAsymmetricPublicKey()).toString("base64"),
+                token: "SOL",
+                amount: null, // Open amount
+            };
+            // === SENDER PAYS VIA PAYLINK ===
+            const senderSignature = nacl.randomBytes(64);
+            const senderEncryption = new EncryptionService();
+            senderEncryption.deriveEncryptionKeyFromSignature(senderSignature);
+            // Sender decodes paylink data
+            const recipientPubkey = new BN(paylinkData.recipientUtxoPubkey);
+            const recipientEncKey = new Uint8Array(Buffer.from(paylinkData.recipientEncryptionKey, "base64"));
+            // Sender creates UTXO for recipient
+            const paymentAmount = new BN(5_000_000_000); // 5 SOL
+            const outputUtxo = new Utxo({
+                lightWasm,
+                amount: paymentAmount,
+                publicKey: recipientPubkey,
+            });
+            // Sender encrypts UTXO for recipient
+            const encryptedOutput = senderEncryption.encryptUtxo(outputUtxo, recipientEncKey);
+            // Verify commitment can be computed (needed for on-chain)
+            const commitment = await outputUtxo.getCommitment();
+            expect(commitment).toBeDefined();
+            // === RECIPIENT CLAIMS ===
+            // Recipient scans encrypted outputs and tries to decrypt
+            const decryptedUtxo = await recipientEncryption.decryptUtxo(encryptedOutput, lightWasm);
+            expect(decryptedUtxo).toBeDefined();
+            expect(decryptedUtxo.amount.toString()).toBe(paymentAmount.toString());
+            // Recipient can now use their keypair to spend (would need full keypair for nullifier)
+            // In real flow, recipient would reconstruct UTXO with their full keypair
+            const spendableUtxo = new Utxo({
+                lightWasm,
+                amount: decryptedUtxo.amount,
+                keypair: recipientUtxoKeypair, // Full keypair for spending
+            });
+            // Now recipient can compute nullifier for spending
+            const nullifier = await spendableUtxo.getNullifier();
+            expect(nullifier).toBeDefined();
+        });
+    });
+});

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+type Config = {
+    withdraw_fee_rate: number;
+    withdraw_rent_fee: number;
+    deposit_fee_rate: number;
+    usdc_withdraw_rent_fee: number;
+    rent_fees: any;
+};
+export declare function getConfig<K extends keyof Config>(key: K): Promise<Config[K]>;
+export {};

package/dist/config.js

@@ -0,0 +1,12 @@
+import { RELAYER_API_URL } from "./utils/constants.js";
+let config;
+export async function getConfig(key) {
+    if (!config) {
+        const res = await fetch(RELAYER_API_URL + '/config');
+        config = await res.json();
+    }
+    if (typeof config[key] == 'undefined') {
+        throw new Error(`can not get ${key} from ${RELAYER_API_URL}/config`);
+    }
+    return config[key];
+}

package/dist/deposit.d.ts

@@ -0,0 +1,22 @@
+import { Connection, PublicKey, VersionedTransaction } from "@solana/web3.js";
+import BN from "bn.js";
+import * as hasher from "@lightprotocol/hasher.rs";
+import { EncryptionService } from "./utils/encryption.js";
+type DepositParams = {
+    publicKey: PublicKey;
+    connection: Connection;
+    amount_in_lamports: number;
+    storage: Storage;
+    encryptionService: EncryptionService;
+    keyBasePath: string;
+    lightWasm: hasher.LightWasm;
+    referrer?: string;
+    signer?: PublicKey;
+    transactionSigner: (tx: VersionedTransaction) => Promise<VersionedTransaction>;
+    recipientUtxoPublicKey?: BN | string;
+    recipientEncryptionKey?: Uint8Array;
+};
+export declare function deposit({ lightWasm, storage, keyBasePath, publicKey, connection, amount_in_lamports, encryptionService, transactionSigner, referrer, signer, recipientUtxoPublicKey, recipientEncryptionKey, }: DepositParams): Promise<{
+    tx: string;
+}>;
+export {};