@velumdotcash/sdk 2.0.0 → 2.1.0

package/README.md

@@ -1,6 +1,9 @@
 # @velumdotcash/sdk
 
-TypeScript SDK for private payments on Solana using Zero-Knowledge proofs.
+[![npm](https://img.shields.io/npm/v/@velumdotcash/sdk)](https://www.npmjs.com/package/@velumdotcash/sdk)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+TypeScript SDK for private payments on Solana using Zero-Knowledge proofs. Deposit, withdraw, and transfer shielded funds with ZK-SNARKs.
 
 ## Installation
 
@@ -10,116 +13,125 @@ npm install @velumdotcash/sdk
 
 ## Quick Start
 
+### Browser (with wallet adapter)
+
 ```typescript
 import { PrivacyCash } from "@velumdotcash/sdk";
 
-// Initialize with wallet signature (browser)
+// Sign a deterministic message to derive shielded keys
+const message = new TextEncoder().encode(
+  `Welcome to Velum\n\nSign this message to derive your private encryption keys.\n\nThis request will not trigger a blockchain transaction or cost any fees.\n\nWallet: ${publicKey.toBase58()}`
+);
+const signature = await wallet.signMessage(message);
+
 const sdk = new PrivacyCash({
   RPC_url: "https://api.mainnet-beta.solana.com",
   publicKey: walletPublicKey,
   signature: walletSignature,
   transactionSigner: async (tx) => wallet.signTransaction(tx),
 });
+```
+
+### Node.js (with keypair)
+
+```typescript
+import { Keypair } from "@solana/web3.js";
+import { PrivacyCash } from "@velumdotcash/sdk";
 
-// Or with keypair (Node.js / scripts)
 const sdk = new PrivacyCash({
-  RPC_url: "https://api.mainnet-beta.solana.com",
-  owner: keypair,
+  RPC_url: process.env.SOLANA_RPC_URL!,
+  owner: Keypair.fromSecretKey(secretKey),
+  circuitPath: "./circuits",
 });
 ```
 
-## API Reference
-
-### Deposits
+## Deposits
 
 ```typescript
-// Deposit SOL
-await sdk.deposit({ lamports: 10_000_000 });
+// Deposit SOL to your shielded account
+await sdk.deposit({ lamports: 10_000_000 }); // 0.01 SOL
 
 // Deposit USDC
-await sdk.depositUSDC({ base_units: 1_000_000 });
+await sdk.depositUSDC({ base_units: 1_000_000 }); // 1 USDC
 
 // Deposit any SPL token
-await sdk.depositSPL({ base_units: 1_000_000, mintAddress: "..." });
+await sdk.depositSPL({
+  base_units: 1_000_000,
+  mintAddress: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+});
 
-// Deposit to a third-party recipient
+// Deposit to a third-party recipient (payment link flow)
 await sdk.deposit({
   lamports: 10_000_000,
-  recipientUtxoPublicKey: "...",
-  recipientEncryptionKey: encryptionKeyBytes,
+  recipientUtxoPublicKey: recipientPubkey,
+  recipientEncryptionKey: recipientEncKey,
 });
 ```
 
-### Withdrawals
+## Withdrawals
 
 ```typescript
-// Withdraw SOL
-await sdk.withdraw({ lamports: 10_000_000, recipientAddress: "..." });
+// Withdraw SOL to any address
+await sdk.withdraw({
+  lamports: 10_000_000,
+  recipientAddress: "Destination...",
+});
 
 // Withdraw USDC
-await sdk.withdrawUSDC({ base_units: 1_000_000, recipientAddress: "..." });
+await sdk.withdrawUSDC({
+  base_units: 1_000_000,
+  recipientAddress: "Destination...",
+});
 
 // Withdraw any SPL token
 await sdk.withdrawSPL({
   base_units: 1_000_000,
-  mintAddress: "...",
-  recipientAddress: "...",
+  mintAddress: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+  recipientAddress: "Destination...",
 });
 ```
 
-### Balance
+## Private 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
+## Key Derivation
 
 ```typescript
-// Get public keys for receiving payments
-const encryptionKey = sdk.getAsymmetricPublicKey(); // Uint8Array
-const utxoPubkey = await sdk.getShieldedPublicKey(); // string
+// Get your shielded public keys (share these to receive payments)
+const encryptionKey = sdk.getAsymmetricPublicKey(); // Uint8Array (X25519)
+const utxoPubkey = await sdk.getShieldedPublicKey(); // string (BN254)
 ```
 
-## Browser Usage
+## How It Works
 
-The SDK works in browsers with wallet adapter integration. Circuit files (WASM + zkey) must be served from your application's public directory.
+1. **Key derivation**: A wallet signature deterministically derives two keypairs — BN254 (UTXO ownership) and X25519 (note encryption)
+2. **Deposit**: Funds enter a shielded pool via a ZK-SNARK that proves validity without revealing the amount or recipient
+3. **UTXO creation**: An encrypted note is stored onchain — only the recipient's X25519 key can decrypt it
+4. **Withdraw**: A second ZK proof verifies UTXO ownership without revealing which deposit created it
 
-```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/
-});
-```
+The result: no onchain link between sender and receiver.
 
-## Node.js Usage
+## Circuit Files
 
-For server-side scripts and testing:
+The SDK requires ZK circuit files (`circuit.wasm` ~3MB, `circuit.zkey` ~16MB) for proof generation.
 
-```typescript
-import { Keypair } from "@solana/web3.js";
+**Browser**: Serve from your public directory. Files are lazy-loaded on first deposit/withdraw and cached in IndexedDB.
 
-const keypair = Keypair.fromSecretKey(secretKey);
+```typescript
 const sdk = new PrivacyCash({
-  RPC_url: process.env.SOLANA_RPC_URL!,
-  owner: keypair,
-  storage: new LocalStorage("./cache"),
-  circuitPath: "./circuits",
-  enableDebug: true,
+  // ...
+  circuitPath: "/circuit", // relative to your public dir
 });
 ```
 
-## Error Handling
+**Node.js**: Point to a local directory containing the circuit files.
+
+## Error Types
 
 ```typescript
 import {
@@ -128,15 +140,14 @@ import {
   NetworkError,
   TransactionTimeoutError,
 } from "@velumdotcash/sdk";
-
-try {
-  await sdk.deposit({ lamports: amount });
-} catch (err) {
-  if (err instanceof InsufficientBalanceError) { /* ... */ }
-  if (err instanceof ZKProofError) { /* ... */ }
-}
 ```
 
+## Related
+
+- [`@velumdotcash/api`](https://www.npmjs.com/package/@velumdotcash/api) — Server-side REST client for paylinks and transactions
+- [Developer Guide](https://velum.cash/docs/developer-guide) — Full integration documentation
+- [How It Works](https://velum.cash/docs/how-it-works) — Cryptographic architecture
+
 ## License
 
-ISC
+[MIT](./LICENSE)

package/dist/deposit.js

@@ -8,7 +8,7 @@ import { InsufficientBalanceError, DepositLimitError, TransactionTimeoutError, }
 import { serializeProofAndExtData, } from "./utils/encryption.js";
 import { Keypair as UtxoKeypair } from "./models/keypair.js";
 import { getUtxos } from "./getUtxos.js";
-import { FIELD_SIZE, FEE_RECIPIENT, MERKLE_TREE_DEPTH, RELAYER_API_URL, PROGRAM_ID, ALT_ADDRESS, } from "./utils/constants.js";
+import { FIELD_SIZE, FEE_RECIPIENT, VELUM_FEE_WALLET, VELUM_FEE_BPS, MERKLE_TREE_DEPTH, RELAYER_API_URL, PROGRAM_ID, ALT_ADDRESS, } from "./utils/constants.js";
 import { useExistingALT } from "./utils/address_lookup_table.js";
 import { logger } from "./utils/logger.js";
 // Function to relay pre-signed deposit transaction to indexer backend
@@ -56,15 +56,16 @@ export async function deposit({ lightWasm, storage, keyBasePath, publicKey, conn
     }
     // const amount_in_lamports = amount_in_sol * LAMPORTS_PER_SOL
     const fee_amount_in_lamports = 0;
+    const velum_fee_lamports = Math.ceil(amount_in_lamports * VELUM_FEE_BPS / 10_000);
     logger.debug("Encryption key generated from user keypair");
     logger.debug(`User wallet: ${signer.toString()}`);
     logger.debug(`Deposit amount: ${amount_in_lamports} lamports (${amount_in_lamports / LAMPORTS_PER_SOL} SOL)`);
-    logger.debug(`Calculated fee: ${fee_amount_in_lamports} lamports (${fee_amount_in_lamports / LAMPORTS_PER_SOL} SOL)`);
-    // Check wallet balance
+    logger.debug(`Protocol fee: ${fee_amount_in_lamports} lamports, Velum fee: ${velum_fee_lamports} lamports`);
+    // Check wallet balance (deposit + protocol fee + velum fee)
     const balance = await connection.getBalance(signer);
     logger.debug(`Wallet balance: ${balance / 1e9} SOL`);
-    if (balance < amount_in_lamports + fee_amount_in_lamports) {
-        throw new InsufficientBalanceError(amount_in_lamports + fee_amount_in_lamports, balance);
+    if (balance < amount_in_lamports + fee_amount_in_lamports + velum_fee_lamports) {
+        throw new InsufficientBalanceError(amount_in_lamports + fee_amount_in_lamports + velum_fee_lamports, balance);
     }
     const { treeAccount, treeTokenAccount, globalConfigAccount } = getProgramAccounts();
     // Create the merkle tree with the pre-initialized poseidon hash
@@ -364,12 +365,18 @@ export async function deposit({ lightWasm, storage, keyBasePath, publicKey, conn
     const modifyComputeUnits = ComputeBudgetProgram.setComputeUnitLimit({
         units: 1_000_000,
     });
+    // Velum fee transfer instruction
+    const velumFeeInstruction = SystemProgram.transfer({
+        fromPubkey: signer,
+        toPubkey: VELUM_FEE_WALLET,
+        lamports: velum_fee_lamports,
+    });
     // Create versioned transaction with Address Lookup Table
     const recentBlockhash = await connection.getLatestBlockhash();
     const messageV0 = new TransactionMessage({
         payerKey: signer, // User pays for their own deposit
         recentBlockhash: recentBlockhash.blockhash,
-        instructions: [modifyComputeUnits, depositInstruction],
+        instructions: [modifyComputeUnits, velumFeeInstruction, depositInstruction],
     }).compileToV0Message([lookupTableAccount.value]);
     let versionedTransaction = new VersionedTransaction(messageV0);
     // sign tx

package/dist/depositSPL.js

@@ -7,10 +7,10 @@ import { MerkleTree } from "./utils/merkle_tree.js";
 import { serializeProofAndExtData, } from "./utils/encryption.js";
 import { Keypair as UtxoKeypair } from "./models/keypair.js";
 import { getUtxosSPL } from "./getUtxosSPL.js";
-import { FIELD_SIZE, FEE_RECIPIENT, MERKLE_TREE_DEPTH, RELAYER_API_URL, PROGRAM_ID, ALT_ADDRESS, tokens, } from "./utils/constants.js";
+import { FIELD_SIZE, FEE_RECIPIENT, MERKLE_TREE_DEPTH, RELAYER_API_URL, PROGRAM_ID, ALT_ADDRESS, tokens, VELUM_FEE_WALLET, VELUM_FEE_BPS, } from "./utils/constants.js";
 import { useExistingALT, } from "./utils/address_lookup_table.js";
 import { logger } from "./utils/logger.js";
-import { ASSOCIATED_TOKEN_PROGRAM_ID, TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync, getAccount, } from "@solana/spl-token";
+import { ASSOCIATED_TOKEN_PROGRAM_ID, TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync, getAccount, createTransferInstruction, } from "@solana/spl-token";
 // Function to relay pre-signed deposit transaction to indexer backend
 async function relayDepositToIndexer({ signedTransaction, publicKey, referrer, mintAddress, }) {
     try {
@@ -84,6 +84,7 @@ export async function depositSPL({ lightWasm, storage, keyBasePath, publicKey, c
     }
     // const base_units = amount_in_sol * units_per_token
     const fee_base_units = 0;
+    const velum_fee_base_units = Math.ceil(base_units * VELUM_FEE_BPS / 10_000);
     logger.debug("Encryption key generated from user keypair");
     logger.debug(`User wallet: ${signer.toString()}`);
     logger.debug(`Deposit amount: ${base_units} base_units (${base_units / token.units_per_token}  ${token.name.toUpperCase()})`);
@@ -94,8 +95,8 @@ export async function depositSPL({ lightWasm, storage, keyBasePath, publicKey, c
     logger.debug(`wallet balance: ${balance / token.units_per_token}  ${token.name.toUpperCase()}`);
     logger.debug("balance", balance);
     logger.debug("base_units + fee_base_units", base_units + fee_base_units);
-    if (balance < base_units + fee_base_units) {
-        throw new Error(`Insufficient balance. Need at least ${(base_units + fee_base_units) / token.units_per_token}  ${token.name.toUpperCase()}.`);
+    if (balance < base_units + fee_base_units + velum_fee_base_units) {
+        throw new Error(`Insufficient balance. Need at least ${(base_units + fee_base_units + velum_fee_base_units) / token.units_per_token}  ${token.name.toUpperCase()}.`);
     }
     // Check SOL balance for account rent + transaction fees
     // The program creates a rent-exempt account (~953,520 lamports) during deposit
@@ -412,12 +413,15 @@ export async function depositSPL({ lightWasm, storage, keyBasePath, publicKey, c
     const modifyComputeUnits = ComputeBudgetProgram.setComputeUnitLimit({
         units: 1_000_000,
     });
+    // Velum fee transfer instruction (SPL token)
+    const velumFeeATA = getAssociatedTokenAddressSync(token.pubkey, VELUM_FEE_WALLET);
+    const velumFeeInstruction = createTransferInstruction(signerTokenAccount, velumFeeATA, signer, velum_fee_base_units);
     // Create versioned transaction with Address Lookup Table
     const recentBlockhash = await connection.getLatestBlockhash();
     const messageV0 = new TransactionMessage({
         payerKey: signer, // User pays for their own deposit
         recentBlockhash: recentBlockhash.blockhash,
-        instructions: [modifyComputeUnits, depositInstruction],
+        instructions: [modifyComputeUnits, velumFeeInstruction, depositInstruction],
     }).compileToV0Message([lookupTableAccount.value]);
     let versionedTransaction = new VersionedTransaction(messageV0);
     // sign tx

package/dist/utils/constants.d.ts

@@ -3,6 +3,8 @@ import BN from 'bn.js';
 export declare const FIELD_SIZE: BN;
 export declare const PROGRAM_ID: PublicKey;
 export declare const FEE_RECIPIENT: PublicKey;
+export declare const VELUM_FEE_WALLET: PublicKey;
+export declare const VELUM_FEE_BPS = 15;
 export declare const FETCH_UTXOS_GROUP_SIZE = 20000;
 export declare const TRANSACT_IX_DISCRIMINATOR: Buffer<ArrayBuffer>;
 export declare const TRANSACT_SPL_IX_DISCRIMINATOR: Buffer<ArrayBuffer>;

package/dist/utils/constants.js

@@ -3,6 +3,8 @@ import BN from 'bn.js';
 export const FIELD_SIZE = new BN('21888242871839275222246405745257275088548364400416034343698204186575808495617');
 export const PROGRAM_ID = process.env.NEXT_PUBLIC_PROGRAM_ID ? new PublicKey(process.env.NEXT_PUBLIC_PROGRAM_ID) : new PublicKey('9fhQBbumKEFuXtMBDw8AaQyAjCorLGJQiS3skWZdQyQD');
 export const FEE_RECIPIENT = new PublicKey('AWexibGxNFKTa1b5R5MN4PJr9HWnWRwf8EW9g8cLx3dM');
+export const VELUM_FEE_WALLET = new PublicKey('8CzjWm8yJBMZhBNwQtRMAgvf7xf8TFQMwQGuv4pd4A4s');
+export const VELUM_FEE_BPS = 15; // 0.15% = 15 basis points
 export const FETCH_UTXOS_GROUP_SIZE = 20_000;
 export const TRANSACT_IX_DISCRIMINATOR = Buffer.from([217, 149, 130, 143, 221, 52, 252, 119]);
 export const TRANSACT_SPL_IX_DISCRIMINATOR = Buffer.from([154, 66, 244, 204, 78, 225, 163, 151]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velumdotcash/sdk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "TypeScript SDK for private payments on Solana using Zero-Knowledge proofs",
   "main": "dist/index.js",
   "exports": {