@velumdotcash/sdk 2.1.0 → 2.2.0

package/README.md

@@ -5,13 +5,13 @@
 
 TypeScript SDK for private payments on Solana using Zero-Knowledge proofs. Deposit, withdraw, and transfer shielded funds with ZK-SNARKs.
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @velumdotcash/sdk
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
 ### Browser (with wallet adapter)
 
@@ -45,7 +45,7 @@ const sdk = new PrivacyCash({
 });
 ```
 
-## Deposits
+## 💰 Deposits
 
 ```typescript
 // Deposit SOL to your shielded account
@@ -68,7 +68,7 @@ await sdk.deposit({
 });
 ```
 
-## Withdrawals
+## 💸 Withdrawals
 
 ```typescript
 // Withdraw SOL to any address
@@ -91,7 +91,7 @@ await sdk.withdrawSPL({
 });
 ```
 
-## Private Balance
+## 🔒 Private Balance
 
 ```typescript
 const sol = await sdk.getPrivateBalance();
@@ -99,7 +99,7 @@ const usdc = await sdk.getPrivateBalanceUSDC();
 const spl = await sdk.getPrivateBalanceSpl(mintAddress);
 ```
 
-## Key Derivation
+## 🔑 Key Derivation
 
 ```typescript
 // Get your shielded public keys (share these to receive payments)
@@ -107,7 +107,7 @@ const encryptionKey = sdk.getAsymmetricPublicKey(); // Uint8Array (X25519)
 const utxoPubkey = await sdk.getShieldedPublicKey(); // string (BN254)
 ```
 
-## How It Works
+## ⚙️ How It Works
 
 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
@@ -116,7 +116,7 @@ const utxoPubkey = await sdk.getShieldedPublicKey(); // string (BN254)
 
 The result: no onchain link between sender and receiver.
 
-## Circuit Files
+## 📁 Circuit Files
 
 The SDK requires ZK circuit files (`circuit.wasm` ~3MB, `circuit.zkey` ~16MB) for proof generation.
 
@@ -131,7 +131,7 @@ const sdk = new PrivacyCash({
 
 **Node.js**: Point to a local directory containing the circuit files.
 
-## Error Types
+## ⚠️ Error Types
 
 ```typescript
 import {
@@ -142,12 +142,12 @@ import {
 } from "@velumdotcash/sdk";
 ```
 
-## Related
+## 🔗 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
+## 📄 License
 
 [MIT](./LICENSE)

package/dist/config.d.ts

@@ -5,5 +5,16 @@ type Config = {
     usdc_withdraw_rent_fee: number;
     rent_fees: any;
 };
+/**
+ * Get config value with automatic cache refresh
+ */
 export declare function getConfig<K extends keyof Config>(key: K): Promise<Config[K]>;
+/**
+ * Force refresh the config cache
+ */
+export declare function refreshConfig(): Promise<void>;
+/**
+ * Clear the config cache (useful for testing)
+ */
+export declare function clearConfigCache(): void;
 export {};

package/dist/config.js

@@ -1,12 +1,42 @@
 import { RELAYER_API_URL } from "./utils/constants.js";
+// Cache TTL in milliseconds (5 minutes)
+const CONFIG_CACHE_TTL_MS = 5 * 60 * 1000;
 let config;
+let configFetchedAt;
+/**
+ * Check if cached config is still valid
+ */
+function isCacheValid() {
+    if (!config || !configFetchedAt)
+        return false;
+    return Date.now() - configFetchedAt < CONFIG_CACHE_TTL_MS;
+}
+/**
+ * Get config value with automatic cache refresh
+ */
 export async function getConfig(key) {
-    if (!config) {
+    if (!isCacheValid()) {
         const res = await fetch(RELAYER_API_URL + '/config');
         config = await res.json();
+        configFetchedAt = Date.now();
     }
     if (typeof config[key] == 'undefined') {
         throw new Error(`can not get ${key} from ${RELAYER_API_URL}/config`);
     }
     return config[key];
 }
+/**
+ * Force refresh the config cache
+ */
+export async function refreshConfig() {
+    const res = await fetch(RELAYER_API_URL + '/config');
+    config = await res.json();
+    configFetchedAt = Date.now();
+}
+/**
+ * Clear the config cache (useful for testing)
+ */
+export function clearConfigCache() {
+    config = undefined;
+    configFetchedAt = undefined;
+}

package/dist/deposit.js

@@ -11,6 +11,7 @@ import { getUtxos } from "./getUtxos.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";
+import { sleepWithBackoff } from "./utils/retry.js";
 // Function to relay pre-signed deposit transaction to indexer backend
 async function relayDepositToIndexer(signedTransaction, publicKey, referrer) {
     try {
@@ -46,6 +47,27 @@ async function relayDepositToIndexer(signedTransaction, publicKey, referrer) {
     }
 }
 export async function deposit({ lightWasm, storage, keyBasePath, publicKey, connection, amount_in_lamports, encryptionService, transactionSigner, referrer, signer, recipientUtxoPublicKey, recipientEncryptionKey, }) {
+    // Validate recipientUtxoPublicKey if provided (must be within BN254 field)
+    if (recipientUtxoPublicKey !== undefined) {
+        const pubkeyBN = BN.isBN(recipientUtxoPublicKey)
+            ? recipientUtxoPublicKey
+            : new BN(recipientUtxoPublicKey);
+        if (pubkeyBN.isZero()) {
+            throw new Error("Invalid recipientUtxoPublicKey: cannot be zero");
+        }
+        if (pubkeyBN.isNeg()) {
+            throw new Error("Invalid recipientUtxoPublicKey: cannot be negative");
+        }
+        if (pubkeyBN.gte(FIELD_SIZE)) {
+            throw new Error("Invalid recipientUtxoPublicKey: exceeds BN254 field size");
+        }
+    }
+    // Validate recipientEncryptionKey if provided (must be exactly 32 bytes for X25519)
+    if (recipientEncryptionKey !== undefined) {
+        if (!recipientEncryptionKey || recipientEncryptionKey.length !== 32) {
+            throw new Error(`Invalid recipientEncryptionKey: X25519 keys must be exactly 32 bytes, got ${recipientEncryptionKey?.length ?? 0}`);
+        }
+    }
     // check limit
     let limitAmount = await checkDepositLimit(connection);
     if (limitAmount && amount_in_lamports > limitAmount * LAMPORTS_PER_SOL) {
@@ -392,24 +414,29 @@ export async function deposit({ lightWasm, storage, keyBasePath, publicKey, conn
     logger.debug(`Transaction link: https://orbmarkets.io/tx/${signature}`);
     logger.info("Waiting for transaction confirmation...");
     let retryTimes = 0;
-    let itv = 2;
+    const maxRetries = 10;
     const encryptedOutputStr = Buffer.from(encryptedOutput1).toString("hex");
-    let start = Date.now();
+    const start = Date.now();
     while (true) {
         logger.info("Confirming transaction..");
         logger.debug(`retryTimes: ${retryTimes}`);
-        await new Promise((resolve) => setTimeout(resolve, itv * 1000));
+        // Use exponential backoff: 2s, 4s, 8s, 16s, up to 30s max
+        const delayMs = await sleepWithBackoff(retryTimes, {
+            baseDelayMs: 2000,
+            maxDelayMs: 30000,
+        });
+        logger.debug(`Waited ${delayMs}ms before retry`);
         logger.debug("Fetching updated tree state...");
-        let res = await fetch(RELAYER_API_URL + "/utxos/check/" + encryptedOutputStr);
-        let resJson = await res.json();
+        const res = await fetch(RELAYER_API_URL + "/utxos/check/" + encryptedOutputStr);
+        const resJson = await res.json();
         if (resJson.exists) {
             logger.debug(`Top up successfully in ${((Date.now() - start) / 1000).toFixed(2)} seconds!`);
             return { tx: signature };
         }
-        if (retryTimes >= 10) {
-            throw new TransactionTimeoutError(`Transaction confirmation timeout after ${retryTimes * 3} seconds`, signature || undefined);
-        }
         retryTimes++;
+        if (retryTimes >= maxRetries) {
+            throw new TransactionTimeoutError(`Transaction confirmation timeout after ${((Date.now() - start) / 1000).toFixed(0)} seconds`, signature || undefined);
+        }
     }
 }
 async function checkDepositLimit(connection) {

package/dist/depositSPL.js

@@ -10,6 +10,7 @@ import { getUtxosSPL } from "./getUtxosSPL.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 { sleepWithBackoff } from "./utils/retry.js";
 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, }) {
@@ -70,6 +71,27 @@ export async function depositSPL({ lightWasm, storage, keyBasePath, publicKey, c
     if (!signer) {
         signer = publicKey;
     }
+    // Validate recipientUtxoPublicKey if provided (must be within BN254 field)
+    if (recipientUtxoPublicKey !== undefined) {
+        const pubkeyBN = BN.isBN(recipientUtxoPublicKey)
+            ? recipientUtxoPublicKey
+            : new BN(recipientUtxoPublicKey);
+        if (pubkeyBN.isZero()) {
+            throw new Error("Invalid recipientUtxoPublicKey: cannot be zero");
+        }
+        if (pubkeyBN.isNeg()) {
+            throw new Error("Invalid recipientUtxoPublicKey: cannot be negative");
+        }
+        if (pubkeyBN.gte(FIELD_SIZE)) {
+            throw new Error("Invalid recipientUtxoPublicKey: exceeds BN254 field size");
+        }
+    }
+    // Validate recipientEncryptionKey if provided (must be exactly 32 bytes for X25519)
+    if (recipientEncryptionKey !== undefined) {
+        if (!recipientEncryptionKey || recipientEncryptionKey.length !== 32) {
+            throw new Error(`Invalid recipientEncryptionKey: X25519 keys must be exactly 32 bytes, got ${recipientEncryptionKey?.length ?? 0}`);
+        }
+    }
     // let mintInfo = await getMint(connection, token.pubkey)
     // let units_per_token = 10 ** mintInfo.decimals
     let recipient = new PublicKey("AWexibGxNFKTa1b5R5MN4PJr9HWnWRwf8EW9g8cLx3dM");
@@ -424,6 +446,11 @@ export async function depositSPL({ lightWasm, storage, keyBasePath, publicKey, c
         instructions: [modifyComputeUnits, velumFeeInstruction, depositInstruction],
     }).compileToV0Message([lookupTableAccount.value]);
     let versionedTransaction = new VersionedTransaction(messageV0);
+    // Debug: measure exact transaction size before signing
+    const unsignedBytes = versionedTransaction.message.serialize().length;
+    const totalEstimate = unsignedBytes + 1 + 64; // 1 byte sig count + 64 byte signature
+    logger.debug(`Message size: ${unsignedBytes} bytes, estimated tx size: ${totalEstimate}/1232 bytes`);
+    logger.debug(`Static accounts: ${messageV0.staticAccountKeys.length}, ALT writable: ${messageV0.addressTableLookups?.[0]?.writableIndexes?.length ?? 0}, ALT readonly: ${messageV0.addressTableLookups?.[0]?.readonlyIndexes?.length ?? 0}`);
     // sign tx
     versionedTransaction = await transactionSigner(versionedTransaction);
     logger.debug("Transaction signed by user");
@@ -442,29 +469,34 @@ export async function depositSPL({ lightWasm, storage, keyBasePath, publicKey, c
     logger.debug(`Transaction link: https://orbmarkets.io/tx/${signature}`);
     logger.info("Waiting for transaction confirmation...");
     let retryTimes = 0;
-    let itv = 2;
+    const maxRetries = 10;
     const encryptedOutputStr = Buffer.from(encryptedOutput1).toString("hex");
-    let start = Date.now();
+    const start = Date.now();
     while (true) {
         logger.info("Confirming transaction..");
         logger.debug(`retryTimes: ${retryTimes}`);
-        await new Promise((resolve) => setTimeout(resolve, itv * 1000));
+        // Use exponential backoff: 2s, 4s, 8s, 16s, up to 30s max
+        const delayMs = await sleepWithBackoff(retryTimes, {
+            baseDelayMs: 2000,
+            maxDelayMs: 30000,
+        });
+        logger.debug(`Waited ${delayMs}ms before retry`);
         logger.debug("Fetching updated tree state...");
-        let url = RELAYER_API_URL +
+        const url = RELAYER_API_URL +
             "/utxos/check/" +
             encryptedOutputStr +
             "?token=" +
             token.name;
-        let res = await fetch(url);
-        let resJson = await res.json();
+        const res = await fetch(url);
+        const resJson = await res.json();
         if (resJson.exists) {
             logger.debug(`Top up successfully in ${((Date.now() - start) / 1000).toFixed(2)} seconds!`);
             return { tx: signature };
         }
-        if (retryTimes >= 10) {
+        retryTimes++;
+        if (retryTimes >= maxRetries) {
             throw new Error("Refresh the page to see latest balance.");
         }
-        retryTimes++;
     }
 }
 async function checkDepositLimit(connection, treeAccount, token) {

package/dist/models/utxo.d.ts

@@ -29,7 +29,7 @@ export declare class Utxo {
      *
      * Generate a new keypair for each UTXO
      */
-    keypair, publicKey, blinding, // Use fixed value for consistency instead of randomBN()
+    keypair, publicKey, blinding, // Cryptographically secure random blinding
     index, mintAddress, // Default to Solana native SOL mint address,
     version }: {
         lightWasm: hasher.LightWasm;

package/dist/models/utxo.js

@@ -5,10 +5,22 @@
  * Based on: https://github.com/tornadocash/tornado-nova
  */
 import BN from 'bn.js';
+import nacl from 'tweetnacl';
 import { Keypair } from './keypair.js';
 import { ethers } from 'ethers';
 import { getMintAddressField } from '../utils/utils.js';
 import { PublicKey } from '@solana/web3.js';
+import { FIELD_SIZE } from '../utils/constants.js';
+/**
+ * Generate a cryptographically secure random blinding factor.
+ * Uses nacl.randomBytes() instead of Math.random() for security.
+ */
+function generateSecureBlinding() {
+    const randomBytes = nacl.randomBytes(32);
+    const randomBN = new BN(randomBytes);
+    // Reduce modulo FIELD_SIZE to ensure it's within the valid range
+    return randomBN.mod(FIELD_SIZE);
+}
 /**
  * Simplified Utxo class inspired by Tornado Cash Nova
  * Based on: https://github.com/tornadocash/tornado-nova/blob/f9264eeffe48bf5e04e19d8086ee6ec58cdf0d9e/src/utxo.js
@@ -31,7 +43,7 @@ export class Utxo {
      *
      * 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()
+    keypair, publicKey, blinding = generateSecureBlinding(), // Cryptographically secure random blinding
     index = 0, mintAddress = '11111111111111111111111111111112', // Default to Solana native SOL mint address,
     version = 'v2' }) {
         this.amount = new BN(amount.toString());

package/dist/utils/debug-logger.d.ts

@@ -76,7 +76,7 @@ export declare function installDebugCommands(): void;
  * 2. PRIVACY_CASH_DEBUG environment variable is set to 'true' or '1'
  * 3. window.PRIVACY_CASH_DEBUG is set to true, 'true', or '1'
  * 4. Running in development mode (NODE_ENV=development or localhost)
- * 5. URL contains ?privacy_cash_debug=true or ?privacy_cash_debug=1 (production feature)
+ * 5. URL contains ?privacy_cash_debug=true or ?privacy_cash_debug=1 (localhost only)
  */
 export declare function isDebugEnabled(): boolean;
 /**

package/dist/utils/debug-logger.js

@@ -30,13 +30,19 @@ function isDevelopmentMode() {
     return false;
 }
 /**
- * Check URL parameters for debug enablement (production feature)
+ * Check URL parameters for debug enablement (development only)
  * Enables via ?privacy_cash_debug=1 or ?privacy_cash_debug=true
+ * SECURITY: Only works on localhost to prevent information leakage in production
  */
 function checkUrlParamDebugEnabled() {
     if (typeof window === 'undefined' || typeof location === 'undefined') {
         return false;
     }
+    // SECURITY: Only allow URL parameter debugging on localhost
+    // This prevents attackers from enabling debug mode in production via URL manipulation
+    if (location.hostname !== 'localhost' && location.hostname !== '127.0.0.1') {
+        return false;
+    }
     // Only check once to avoid repeated URL parsing
     if (urlParamChecked) {
         return false;
@@ -162,7 +168,7 @@ export function installDebugCommands() {
             console.log(`[PRIVACY-CASH-DEBUG] Status: ${enabled ? 'ENABLED' : 'DISABLED'}`);
             console.log(`[PRIVACY-CASH-DEBUG] Verbose: ${verbose ? 'ENABLED' : 'DISABLED'}`);
             console.log(`[PRIVACY-CASH-DEBUG] Mode: ${mode}`);
-            console.log('[PRIVACY-CASH-DEBUG] To enable: window.privacyCashDebug.enable() or add ?privacy_cash_debug=1 to URL');
+            console.log('[PRIVACY-CASH-DEBUG] To enable: window.privacyCashDebug.enable() (or ?privacy_cash_debug=1 on localhost)');
             console.log('[PRIVACY-CASH-DEBUG] For verbose: window.privacyCashDebug.verbose() or set PRIVACY_CASH_VERBOSE=1');
         }
     };
@@ -179,7 +185,7 @@ if (typeof window !== 'undefined') {
  * 2. PRIVACY_CASH_DEBUG environment variable is set to 'true' or '1'
  * 3. window.PRIVACY_CASH_DEBUG is set to true, 'true', or '1'
  * 4. Running in development mode (NODE_ENV=development or localhost)
- * 5. URL contains ?privacy_cash_debug=true or ?privacy_cash_debug=1 (production feature)
+ * 5. URL contains ?privacy_cash_debug=true or ?privacy_cash_debug=1 (localhost only)
  */
 export function isDebugEnabled() {
     return debugEnabled || checkEnvDebugEnabled() || isDevelopmentMode() || checkUrlParamDebugEnabled();

package/dist/utils/encryption.d.ts

@@ -20,6 +20,8 @@ export declare class EncryptionService {
     static readonly ENCRYPTION_VERSION_V2: Buffer<ArrayBuffer>;
     static readonly ENCRYPTION_VERSION_V3: Buffer<ArrayBuffer>;
     static readonly SIGNATURE_SCHEMA_VERSION: Buffer<ArrayBuffer>;
+    static readonly COMPACT_V2_TAG = 194;
+    static readonly COMPACT_V3_TAG = 195;
     static readonly RECIPIENT_ID_LENGTH = 8;
     private encryptionKeyV1;
     private encryptionKeyV2;
@@ -84,7 +86,7 @@ export declare class EncryptionService {
     /**
      * Encrypt data using Asymmetric Encryption (X25519 + XSalsa20-Poly1305)
      * @param data The data to encrypt
-     * @param recipientPublicKey The recipient's X25519 Public Key
+     * @param recipientPublicKey The recipient's X25519 Public Key (must be exactly 32 bytes)
      */
     encryptAsymmetric(data: Buffer | string, recipientPublicKey: Uint8Array): Buffer;
     /**
@@ -103,14 +105,27 @@ export declare class EncryptionService {
      */
     resetEncryptionKey(): void;
     /**
-     * Encrypt a UTXO using a compact pipe-delimited format
-     * Always uses V2 encryption format. The UTXO's version property is used only for key derivation.
+     * Encrypt a UTXO using compact binary encoding and compact encryption headers.
+     * Plaintext: 77-byte binary [0x01][amount:8][blinding:32][index:4][mint:32]
+     * Encryption: compact V2 (0xC2 tag, AES-GCM) or compact V3 (0xC3 tag, NaCl Box)
      * @param utxo The UTXO to encrypt (includes version property)
      * @param recipientEncryptionKey Optional recipient X25519 public key for asymmetric encryption
      * @returns The encrypted UTXO data as a Buffer
      * @throws Error if the V2 encryption key has not been set
      */
+    private static readonly BINARY_UTXO_FLAG;
+    private static readonly BINARY_UTXO_LENGTH;
     encryptUtxo(utxo: Utxo, recipientEncryptionKey?: Uint8Array): Buffer;
+    /**
+     * Compact V2 symmetric encryption: [0xC2][recipientIdHash(8)][IV(12)][authTag(16)][ciphertext]
+     * Saves 8 bytes vs standard V2 format by using 1-byte tag instead of 8-byte version + 1-byte schema
+     */
+    private encryptUtxoCompactV2;
+    /**
+     * Compact V3 asymmetric encryption: [0xC3][recipientIdHash(8)][ephemeralPK(32)][nonce(24)][ciphertext+MAC]
+     * Saves 8 bytes vs standard V3 format by using 1-byte tag instead of 8-byte version + 1-byte schema
+     */
+    private encryptUtxoCompactV3;
     encryptUtxoDecryptedDoNotUse(utxo: Utxo): Buffer;
     getEncryptionKeyVersion(encryptedData: Buffer | string): 'v1' | 'v2' | 'v3';
     /**
@@ -122,6 +137,14 @@ export declare class EncryptionService {
      * @returns null if schema version matches or is legacy, otherwise the mismatched version byte
      */
     private checkSchemaVersionMismatch;
+    /**
+     * Decrypt compact V2 format: [0xC2][recipientIdHash(8)][IV(12)][authTag(16)][ciphertext]
+     */
+    private decryptCompactV2;
+    /**
+     * Decrypt compact V3 format: [0xC3][recipientIdHash(8)][ephemeralPK(32)][nonce(24)][ciphertext+MAC]
+     */
+    private decryptCompactV3;
     /**
      * Decrypt an encrypted UTXO and parse it to a Utxo instance
      * Automatically detects the UTXO version based on the encryption format

package/dist/utils/encryption.js

@@ -1,3 +1,4 @@
+import { PublicKey } from '@solana/web3.js';
 import nacl from 'tweetnacl';
 import { sha256 } from '@noble/hashes/sha256';
 import { hmac } from '@noble/hashes/hmac';
@@ -20,6 +21,10 @@ export class EncryptionService {
     // Version 0x01: Original format without recipient ID
     // Version 0x02: New format with recipient ID hash for O(1) early termination
     static SIGNATURE_SCHEMA_VERSION = Buffer.from([0x02]); // Schema version 2
+    // Compact encryption tags — single byte replaces 8-byte version + 1-byte schema
+    // Uses high bytes (0xC2/0xC3) to avoid collision with legacy V1 random IV bytes
+    static COMPACT_V2_TAG = 0xC2; // Compact symmetric (AES-256-GCM)
+    static COMPACT_V3_TAG = 0xC3; // Compact asymmetric (nacl.box)
     // Length of recipient ID hash in bytes (first 8 bytes of SHA256(X25519 public key))
     static RECIPIENT_ID_LENGTH = 8;
     encryptionKeyV1 = null;
@@ -114,7 +119,14 @@ export class EncryptionService {
      * @returns true if we should attempt decryption, false to skip
      */
     shouldAttemptDecryption(encryptedBuffer) {
-        // Minimum length for new format: version(8) + schema(1) + recipientId(8) = 17 bytes
+        // Compact format: [tag(1)][recipientIdHash(8)]...
+        if (encryptedBuffer.length >= 9 &&
+            (encryptedBuffer[0] === EncryptionService.COMPACT_V2_TAG || encryptedBuffer[0] === EncryptionService.COMPACT_V3_TAG)) {
+            const storedRecipientId = encryptedBuffer.slice(1, 1 + EncryptionService.RECIPIENT_ID_LENGTH);
+            const ourRecipientId = this.deriveRecipientIdHash();
+            return storedRecipientId.equals(ourRecipientId);
+        }
+        // Minimum length for legacy format: version(8) + schema(1) + recipientId(8) = 17 bytes
         if (encryptedBuffer.length < 17) {
             // Too short for new format, let normal decryption handle it
             return true;
@@ -268,9 +280,13 @@ export class EncryptionService {
     /**
      * Encrypt data using Asymmetric Encryption (X25519 + XSalsa20-Poly1305)
      * @param data The data to encrypt
-     * @param recipientPublicKey The recipient's X25519 Public Key
+     * @param recipientPublicKey The recipient's X25519 Public Key (must be exactly 32 bytes)
      */
     encryptAsymmetric(data, recipientPublicKey) {
+        // Validate X25519 public key length (must be exactly 32 bytes)
+        if (!recipientPublicKey || recipientPublicKey.length !== 32) {
+            throw new Error(`Invalid recipientPublicKey: X25519 public keys must be exactly 32 bytes, got ${recipientPublicKey?.length ?? 0}`);
+        }
         const dataBuffer = typeof data === 'string' ? Buffer.from(data) : data;
         // Log the recipient's X25519 public key being used for encryption (sender side)
         debugLogger.x25519EncryptionKey(hashForLog(recipientPublicKey));
@@ -436,25 +452,83 @@ export class EncryptionService {
         this.walletAddress = null;
     }
     /**
-     * Encrypt a UTXO using a compact pipe-delimited format
-     * Always uses V2 encryption format. The UTXO's version property is used only for key derivation.
+     * Encrypt a UTXO using compact binary encoding and compact encryption headers.
+     * Plaintext: 77-byte binary [0x01][amount:8][blinding:32][index:4][mint:32]
+     * Encryption: compact V2 (0xC2 tag, AES-GCM) or compact V3 (0xC3 tag, NaCl Box)
      * @param utxo The UTXO to encrypt (includes version property)
      * @param recipientEncryptionKey Optional recipient X25519 public key for asymmetric encryption
      * @returns The encrypted UTXO data as a Buffer
      * @throws Error if the V2 encryption key has not been set
      */
+    // Binary format flag for compact UTXO encoding
+    static BINARY_UTXO_FLAG = 0x01;
+    static BINARY_UTXO_LENGTH = 77; // 1 + 8 + 32 + 4 + 32
     encryptUtxo(utxo, recipientEncryptionKey) {
         if (!this.encryptionKeyV2) {
             throw new Error('Encryption key not set. Call setEncryptionKey or deriveEncryptionKeyFromWallet first.');
         }
-        // Create a compact string representation using pipe delimiter
-        // Version is stored in the UTXO model, not in the encrypted content
-        const utxoString = `${utxo.amount.toString()}|${utxo.blinding.toString()}|${utxo.index}|${utxo.mintAddress}`;
+        // Compact binary encoding: [0x01][amount:8 BE][blinding:32 BE][index:4 BE][mintAddress:32 raw]
+        // 77 bytes total — saves ~55 bytes vs pipe-delimited text, keeping SPL deposits in one tx
+        const buf = Buffer.alloc(EncryptionService.BINARY_UTXO_LENGTH);
+        buf[0] = EncryptionService.BINARY_UTXO_FLAG;
+        // Convert via toString() to support both BN instances and plain objects
+        const amountBN = new BN(utxo.amount.toString());
+        const blindingBN = new BN(utxo.blinding.toString());
+        // Amount: 8 bytes big-endian
+        Buffer.from(amountBN.toArray('be', 8)).copy(buf, 1);
+        // Blinding: 32 bytes big-endian
+        Buffer.from(blindingBN.toArray('be', 32)).copy(buf, 9);
+        // Index: 4 bytes big-endian (uint32)
+        buf.writeUInt32BE(utxo.index, 41);
+        // Mint address: 32 bytes raw (base58-decoded Solana public key)
+        const mintAddr = utxo.mintAddress || '11111111111111111111111111111112';
+        Buffer.from(new PublicKey(mintAddr).toBytes()).copy(buf, 45);
+        // Use compact encryption headers (1-byte tag instead of 9-byte version+schema)
+        // Saves 8 bytes per output (16 total) to keep SPL paylink deposits in one tx
         if (recipientEncryptionKey) {
-            return this.encryptAsymmetric(utxoString, recipientEncryptionKey);
+            return this.encryptUtxoCompactV3(buf, recipientEncryptionKey);
+        }
+        return this.encryptUtxoCompactV2(buf);
+    }
+    /**
+     * Compact V2 symmetric encryption: [0xC2][recipientIdHash(8)][IV(12)][authTag(16)][ciphertext]
+     * Saves 8 bytes vs standard V2 format by using 1-byte tag instead of 8-byte version + 1-byte schema
+     */
+    encryptUtxoCompactV2(data) {
+        const key = Buffer.from(this.encryptionKeyV2);
+        const iv = nacl.randomBytes(12);
+        const stream = gcm(key, iv);
+        const encryptedWithTag = stream.encrypt(data);
+        const authTag = Buffer.from(encryptedWithTag.slice(-16));
+        const ciphertext = Buffer.from(encryptedWithTag.slice(0, -16));
+        const recipientIdHash = this.deriveRecipientIdHash();
+        return Buffer.concat([
+            Buffer.from([EncryptionService.COMPACT_V2_TAG]),
+            recipientIdHash,
+            iv,
+            authTag,
+            ciphertext
+        ]);
+    }
+    /**
+     * Compact V3 asymmetric encryption: [0xC3][recipientIdHash(8)][ephemeralPK(32)][nonce(24)][ciphertext+MAC]
+     * Saves 8 bytes vs standard V3 format by using 1-byte tag instead of 8-byte version + 1-byte schema
+     */
+    encryptUtxoCompactV3(data, recipientPublicKey) {
+        if (!recipientPublicKey || recipientPublicKey.length !== 32) {
+            throw new Error(`Invalid recipientPublicKey: X25519 keys must be exactly 32 bytes, got ${recipientPublicKey?.length ?? 0}`);
         }
-        // Always use V2 encryption format (which adds version byte 0x02 at the beginning)
-        return this.encrypt(utxoString);
+        const ephemeralKeypair = nacl.box.keyPair();
+        const nonce = nacl.randomBytes(nacl.box.nonceLength);
+        const encrypted = nacl.box(data, nonce, recipientPublicKey, ephemeralKeypair.secretKey);
+        const recipientIdHash = this.deriveRecipientIdHash(recipientPublicKey);
+        return Buffer.concat([
+            Buffer.from([EncryptionService.COMPACT_V3_TAG]),
+            recipientIdHash,
+            ephemeralKeypair.publicKey,
+            nonce,
+            encrypted
+        ]);
     }
     // Deprecated, only used for testing now
     encryptUtxoDecryptedDoNotUse(utxo) {
@@ -467,6 +541,17 @@ export class EncryptionService {
     getEncryptionKeyVersion(encryptedData) {
         const buffer = typeof encryptedData === 'string' ? Buffer.from(encryptedData, 'hex') : encryptedData;
         const dataHash = hashForLog(buffer);
+        // Check compact format tags first (single byte at position 0)
+        if (buffer.length >= 1) {
+            if (buffer[0] === EncryptionService.COMPACT_V2_TAG) {
+                debugLogger.versionDetected(dataHash, 'v2', buffer.length);
+                return 'v2';
+            }
+            if (buffer[0] === EncryptionService.COMPACT_V3_TAG) {
+                debugLogger.versionDetected(dataHash, 'v3', buffer.length);
+                return 'v3';
+            }
+        }
         // Log the first 8 bytes (version prefix) for debugging
         const prefixBytes = buffer.length >= 8 ? buffer.subarray(0, 8) : buffer;
         const prefixHex = Buffer.from(prefixBytes).toString('hex');
@@ -503,6 +588,11 @@ export class EncryptionService {
         if (encryptionVersion === 'v1') {
             return null;
         }
+        // Compact format has no separate schema version byte — tag encodes everything
+        if (encryptedBuffer.length >= 1 &&
+            (encryptedBuffer[0] === EncryptionService.COMPACT_V2_TAG || encryptedBuffer[0] === EncryptionService.COMPACT_V3_TAG)) {
+            return null;
+        }
         // Check if we have enough bytes to contain schema version
         if (encryptedBuffer.length < 9) {
             return null; // Too short, let decryption handle the error
@@ -531,6 +621,42 @@ export class EncryptionService {
         }
         return null; // Assume legacy format or compatible version, attempt decryption
     }
+    /**
+     * Decrypt compact V2 format: [0xC2][recipientIdHash(8)][IV(12)][authTag(16)][ciphertext]
+     */
+    decryptCompactV2(encryptedBuffer) {
+        if (!this.encryptionKeyV2) {
+            throw new Error('encryptionKeyV2 not set.');
+        }
+        const iv = encryptedBuffer.slice(9, 21);
+        const authTag = encryptedBuffer.slice(21, 37);
+        const ciphertext = encryptedBuffer.slice(37);
+        const key = Buffer.from(this.encryptionKeyV2);
+        const ciphertextWithTag = Buffer.concat([ciphertext, authTag]);
+        try {
+            const stream = gcm(key, iv);
+            return Buffer.from(stream.decrypt(ciphertextWithTag));
+        }
+        catch (error) {
+            throw new Error('Failed to decrypt data. Invalid encryption key or corrupted data.');
+        }
+    }
+    /**
+     * Decrypt compact V3 format: [0xC3][recipientIdHash(8)][ephemeralPK(32)][nonce(24)][ciphertext+MAC]
+     */
+    decryptCompactV3(encryptedBuffer) {
+        if (!this.asymmetricSecretKey) {
+            throw new Error('Asymmetric secret key not set.');
+        }
+        const ephemeralPublicKey = encryptedBuffer.slice(9, 41);
+        const nonce = encryptedBuffer.slice(41, 65);
+        const box = encryptedBuffer.slice(65);
+        const decrypted = nacl.box.open(box, nonce, ephemeralPublicKey, this.asymmetricSecretKey);
+        if (!decrypted) {
+            throw new Error('Failed to decrypt compact V3 data');
+        }
+        return Buffer.from(decrypted);
+    }
     /**
      * Decrypt an encrypted UTXO and parse it to a Utxo instance
      * Automatically detects the UTXO version based on the encryption format
@@ -570,7 +696,18 @@ export class EncryptionService {
             return null;
         }
         let decrypted;
-        if (utxoVersion === 'v3') {
+        // Compact format: single-byte tag at position 0
+        const isCompactV2 = encryptedBuffer[0] === EncryptionService.COMPACT_V2_TAG;
+        const isCompactV3 = encryptedBuffer[0] === EncryptionService.COMPACT_V3_TAG;
+        if (isCompactV2) {
+            decrypted = this.decryptCompactV2(encryptedBuffer);
+            utxoVersion = 'v2';
+        }
+        else if (isCompactV3) {
+            decrypted = this.decryptCompactV3(encryptedBuffer);
+            utxoVersion = 'v2'; // V3 uses V2 private keys for UTXO logic
+        }
+        else if (utxoVersion === 'v3') {
             decrypted = this.decryptV3(encryptedBuffer);
             // V3 also uses V2 private keys for the UTXO logic
             utxoVersion = 'v2';
@@ -584,24 +721,39 @@ export class EncryptionService {
             debugLogger.decryptionFailure(originalVersion, 'LEGACY_FORMAT_SKIPPED', 'Old format UTXO without schema version byte - returning null');
             return null;
         }
-        // Parse the pipe-delimited format: amount|blinding|index|mintAddress
-        const decryptedStr = decrypted.toString();
-        const parts = decryptedStr.split('|');
-        if (parts.length !== 4) {
-            debugLogger.decryptionFailure(originalVersion, 'INVALID_UTXO_FORMAT', `Expected 4 pipe-delimited parts, got ${parts.length}`, {
-                partsCount: parts.length
-            });
-            throw new Error('Invalid UTXO format after decryption');
-        }
-        const [amount, blinding, index, mintAddress] = parts;
-        if (!amount || !blinding || index === undefined || mintAddress === undefined) {
-            debugLogger.decryptionFailure(originalVersion, 'MISSING_UTXO_FIELDS', 'One or more required UTXO fields are missing', {
-                hasAmount: !!amount,
-                hasBlinding: !!blinding,
-                hasIndex: index !== undefined,
-                hasMintAddress: mintAddress !== undefined
-            });
-            throw new Error('Invalid UTXO format after decryption');
+        // Detect format: 0x01 + 77 bytes = compact binary, otherwise legacy pipe-delimited text
+        let amount, blinding, parsedIndex, mintAddress;
+        if (decrypted[0] === EncryptionService.BINARY_UTXO_FLAG && decrypted.length === EncryptionService.BINARY_UTXO_LENGTH) {
+            // Compact binary: [0x01][amount:8 BE][blinding:32 BE][index:4 BE][mintAddress:32 raw]
+            amount = new BN(decrypted.subarray(1, 9), 'be').toString();
+            blinding = new BN(decrypted.subarray(9, 41), 'be').toString();
+            parsedIndex = decrypted.readUInt32BE(41);
+            mintAddress = new PublicKey(decrypted.subarray(45, 77)).toBase58();
+        }
+        else {
+            // Legacy pipe-delimited text: amount|blinding|index|mintAddress
+            const decryptedStr = decrypted.toString();
+            const parts = decryptedStr.split('|');
+            if (parts.length !== 4) {
+                debugLogger.decryptionFailure(originalVersion, 'INVALID_UTXO_FORMAT', `Expected 4 pipe-delimited parts, got ${parts.length}`, {
+                    partsCount: parts.length
+                });
+                throw new Error('Invalid UTXO format after decryption');
+            }
+            const [a, b, idx, mint] = parts;
+            if (!a || !b || idx === undefined || mint === undefined) {
+                debugLogger.decryptionFailure(originalVersion, 'MISSING_UTXO_FIELDS', 'One or more required UTXO fields are missing', {
+                    hasAmount: !!a,
+                    hasBlinding: !!b,
+                    hasIndex: idx !== undefined,
+                    hasMintAddress: mint !== undefined
+                });
+                throw new Error('Invalid UTXO format after decryption');
+            }
+            amount = a;
+            blinding = b;
+            parsedIndex = Number(idx);
+            mintAddress = mint;
         }
         // Get or create a LightWasm instance
         const wasmInstance = lightWasm || await WasmFactory.getInstance();
@@ -612,13 +764,13 @@ export class EncryptionService {
             amount: amount,
             blinding: blinding,
             keypair: new UtxoKeypair(privateKey, wasmInstance),
-            index: Number(index),
+            index: parsedIndex,
             mintAddress: mintAddress,
             version: utxoVersion
         });
         // Log UTXO metadata after successful decryption
         const commitment = await utxo.getCommitment();
-        debugLogger.utxoDecrypted(hashForLog(Buffer.from(commitment)), mintAddress, encryptedBuffer.length, index, originalVersion);
+        debugLogger.utxoDecrypted(hashForLog(Buffer.from(commitment)), mintAddress, encryptedBuffer.length, parsedIndex, originalVersion);
         return utxo;
     }
     getUtxoPrivateKeyWithVersion(version) {

package/dist/utils/retry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Exponential backoff delay calculation
+ *
+ * @param attempt Current attempt number (0-based)
+ * @param baseDelayMs Base delay in milliseconds (default: 2000ms)
+ * @param maxDelayMs Maximum delay cap in milliseconds (default: 30000ms)
+ * @param jitterFactor Random jitter factor 0-1 (default: 0.1 = 10%)
+ * @returns Delay in milliseconds
+ */
+export declare function getExponentialBackoffDelay(attempt: number, baseDelayMs?: number, maxDelayMs?: number, jitterFactor?: number): number;
+/**
+ * Sleep for a specified duration with exponential backoff
+ *
+ * @param attempt Current attempt number (0-based)
+ * @param options Optional configuration
+ */
+export declare function sleepWithBackoff(attempt: number, options?: {
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitterFactor?: number;
+}): Promise<number>;

package/dist/utils/retry.js

@@ -0,0 +1,30 @@
+/**
+ * Exponential backoff delay calculation
+ *
+ * @param attempt Current attempt number (0-based)
+ * @param baseDelayMs Base delay in milliseconds (default: 2000ms)
+ * @param maxDelayMs Maximum delay cap in milliseconds (default: 30000ms)
+ * @param jitterFactor Random jitter factor 0-1 (default: 0.1 = 10%)
+ * @returns Delay in milliseconds
+ */
+export function getExponentialBackoffDelay(attempt, baseDelayMs = 2000, maxDelayMs = 30000, jitterFactor = 0.1) {
+    // Exponential: base * 2^attempt (e.g., 2s, 4s, 8s, 16s, 30s max)
+    const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+    // Cap at maximum delay
+    const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+    // Add jitter to prevent thundering herd
+    const jitter = cappedDelay * jitterFactor * Math.random();
+    const finalDelay = cappedDelay + jitter;
+    return Math.floor(finalDelay);
+}
+/**
+ * Sleep for a specified duration with exponential backoff
+ *
+ * @param attempt Current attempt number (0-based)
+ * @param options Optional configuration
+ */
+export async function sleepWithBackoff(attempt, options) {
+    const delayMs = getExponentialBackoffDelay(attempt, options?.baseDelayMs, options?.maxDelayMs, options?.jitterFactor);
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    return delayMs;
+}

package/dist/withdraw.js

@@ -10,6 +10,7 @@ import { serializeProofAndExtData, } from "./utils/encryption.js";
 import { fetchMerkleProof, findNullifierPDAs, getExtDataHash, getProgramAccounts, queryRemoteTreeState, findCrossCheckNullifierPDAs, } from "./utils/utils.js";
 import { getUtxos } from "./getUtxos.js";
 import { logger } from "./utils/logger.js";
+import { sleepWithBackoff } from "./utils/retry.js";
 import { getConfig } from "./config.js";
 // Indexer API endpoint
 // Function to submit withdraw request to indexer backend
@@ -262,16 +263,21 @@ export async function withdraw({ recipient, lightWasm, storage, publicKey, conne
     // Wait a moment for the transaction to be confirmed
     logger.info("waiting for transaction confirmation...");
     let retryTimes = 0;
-    let itv = 2;
+    const maxRetries = 10;
     const encryptedOutputStr = Buffer.from(encryptedOutput1).toString("hex");
-    let start = Date.now();
+    const start = Date.now();
     while (true) {
         logger.info("Confirming transaction..");
         logger.debug(`retryTimes: ${retryTimes}`);
-        await new Promise((resolve) => setTimeout(resolve, itv * 1000));
+        // Use exponential backoff: 2s, 4s, 8s, 16s, up to 30s max
+        const delayMs = await sleepWithBackoff(retryTimes, {
+            baseDelayMs: 2000,
+            maxDelayMs: 30000,
+        });
+        logger.debug(`Waited ${delayMs}ms before retry`);
         logger.info("Fetching updated tree state...");
-        let res = await fetch(RELAYER_API_URL + "/utxos/check/" + encryptedOutputStr);
-        let resJson = await res.json();
+        const res = await fetch(RELAYER_API_URL + "/utxos/check/" + encryptedOutputStr);
+        const resJson = await res.json();
         logger.debug("resJson:", resJson);
         if (resJson.exists) {
             return {
@@ -282,9 +288,9 @@ export async function withdraw({ recipient, lightWasm, storage, publicKey, conne
                 fee_in_lamports,
             };
         }
-        if (retryTimes >= 10) {
-            throw new TransactionTimeoutError(`Transaction confirmation timeout after ${retryTimes * 3} seconds`, signature);
-        }
         retryTimes++;
+        if (retryTimes >= maxRetries) {
+            throw new TransactionTimeoutError(`Transaction confirmation timeout after ${((Date.now() - start) / 1000).toFixed(0)} seconds`, signature);
+        }
     }
 }

package/dist/withdrawSPL.js

@@ -9,6 +9,7 @@ import { serializeProofAndExtData, } from "./utils/encryption.js";
 import { fetchMerkleProof, findNullifierPDAs, getProgramAccounts, queryRemoteTreeState, findCrossCheckNullifierPDAs, getMintAddressField, getExtDataHash, } from "./utils/utils.js";
 import { getUtxosSPL } from "./getUtxosSPL.js";
 import { logger } from "./utils/logger.js";
+import { sleepWithBackoff } from "./utils/retry.js";
 import { getConfig } from "./config.js";
 import { getAssociatedTokenAddressSync, getMint } from "@solana/spl-token";
 // Indexer API endpoint
@@ -297,20 +298,25 @@ export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, co
     // Wait a moment for the transaction to be confirmed
     logger.info("waiting for transaction confirmation...");
     let retryTimes = 0;
-    let itv = 2;
+    const maxRetries = 10;
     const encryptedOutputStr = Buffer.from(encryptedOutput1).toString("hex");
-    let start = Date.now();
+    const start = Date.now();
     while (true) {
         logger.info("Confirming transaction..");
         logger.debug(`retryTimes: ${retryTimes}`);
-        await new Promise((resolve) => setTimeout(resolve, itv * 1000));
+        // Use exponential backoff: 2s, 4s, 8s, 16s, up to 30s max
+        const delayMs = await sleepWithBackoff(retryTimes, {
+            baseDelayMs: 2000,
+            maxDelayMs: 30000,
+        });
+        logger.debug(`Waited ${delayMs}ms before retry`);
         logger.info("Fetching updated tree state...");
-        let res = await fetch(RELAYER_API_URL +
+        const res = await fetch(RELAYER_API_URL +
             "/utxos/check/" +
             encryptedOutputStr +
             "?token=" +
             token.name);
-        let resJson = await res.json();
+        const resJson = await res.json();
         logger.debug("resJson:", resJson);
         if (resJson.exists) {
             return {
@@ -321,9 +327,9 @@ export async function withdrawSPL({ recipient, lightWasm, storage, publicKey, co
                 fee_base_units,
             };
         }
-        if (retryTimes >= 10) {
+        retryTimes++;
+        if (retryTimes >= maxRetries) {
             throw new Error("Refresh the page to see latest balance.");
         }
-        retryTimes++;
     }
 }

package/package.json

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