@deserialize/multi-vm-wallet 1.3.2 → 1.3.4

package/dist/privacy/railgun-engine.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * RAILGUN Engine Singleton
+ *
+ * Manages the global RAILGUN privacy engine initialization.
+ * Must be initialized once before using any privacy features.
+ *
+ * STATELESS: Does not store configuration or state beyond initialization flag.
+ * Implementer controls when/how to initialize.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RailgunEngine = void 0;
+const wallet_1 = require("@railgun-community/wallet");
+/**
+ * RAILGUN Engine Singleton
+ *
+ * Manages the global RAILGUN privacy engine initialization.
+ * Must be initialized once before using any privacy features.
+ *
+ * STATELESS: Does not store any configuration or state.
+ * Implementer controls when/how to initialize.
+ */
+class RailgunEngine {
+    static initialized = false;
+    static config = null;
+    /**
+     * Initialize RAILGUN privacy engine
+     *
+     * This is a one-time setup that must be called before any privacy operations.
+     * Implementer provides database and artifact storage.
+     *
+     * @param config - Engine configuration
+     * @param preloadedArtifacts - Optional pre-downloaded circuits
+     *
+     * @throws Error if already initialized or if configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * import LevelDB from 'level-js';
+     * import { ArtifactManager } from './artifact-manager';
+     *
+     * const db = new LevelDB('./railgun-data');
+     * const artifactStore = ArtifactManager.createArtifactStore(
+     *   './artifacts',
+     *   { readFile, writeFile, exists, mkdir }
+     * );
+     *
+     * await RailgunEngine.initialize({
+     *   walletSource: 'mywallet',
+     *   db,
+     *   artifactStore,
+     *   poiNodeURLs: ['https://ppoi-agg.horsewithsixlegs.xyz'],
+     *   useNativeArtifacts: false,
+     *   skipMerkletreeScans: false
+     * });
+     * ```
+     */
+    static async initialize(config, preloadedArtifacts) {
+        if (this.initialized) {
+            throw new Error('RAILGUN engine already initialized');
+        }
+        // Validate configuration
+        this.validateConfig(config);
+        // If preloaded artifacts provided, populate artifact store
+        if (preloadedArtifacts) {
+            await this.preloadArtifacts(config.artifactStore, preloadedArtifacts);
+        }
+        // Start RAILGUN engine
+        await (0, wallet_1.startRailgunEngine)(config.walletSource, config.db, config.shouldDebug ?? false, config.artifactStore, config.useNativeArtifacts ?? false, config.skipMerkletreeScans ?? false, config.poiNodeURLs, config.customPOILists ?? [], config.verboseScanLogging ?? false);
+        this.initialized = true;
+        this.config = config;
+    }
+    /**
+     * Shutdown RAILGUN engine
+     *
+     * Cleanup resources and stop the engine.
+     * After shutdown, initialize() must be called again to use privacy features.
+     */
+    static async shutdown() {
+        if (!this.initialized) {
+            return;
+        }
+        await (0, wallet_1.stopRailgunEngine)();
+        this.initialized = false;
+        this.config = null;
+    }
+    /**
+     * Check if engine is initialized
+     */
+    static isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get current configuration (read-only)
+     * Returns null if not initialized
+     */
+    static getConfig() {
+        return this.config ? { ...this.config } : null;
+    }
+    /**
+     * Load network provider and RAILGUN contracts
+     *
+     * Must be called for each network before using it.
+     * Returns network fees.
+     *
+     * @param network - Network to load
+     * @param rpcProvider - ethers.js provider for the network
+     * @param pollingInterval - RPC polling interval in seconds (default: 10)
+     * @returns Network fees (shield, unshield, NFT in basis points)
+     *
+     * @example
+     * ```typescript
+     * import { JsonRpcProvider } from 'ethers';
+     * import { NetworkName } from '@railgun-community/shared-models';
+     *
+     * const provider = new JsonRpcProvider('https://eth-mainnet.g.alchemy.com/v2/...');
+     * const fees = await RailgunEngine.loadNetwork(
+     *   NetworkName.Ethereum,
+     *   provider
+     * );
+     *
+     * console.log(`Shield fee: ${fees.shield / 100}%`); // 0.25%
+     * ```
+     */
+    static async loadNetwork(network, rpcProvider, // ethers.Provider
+    pollingInterval = 10) {
+        this.ensureInitialized();
+        const feesSerialized = await (0, wallet_1.loadProvider)(rpcProvider, network, pollingInterval);
+        return {
+            shield: feesSerialized.deposit,
+            unshield: feesSerialized.withdraw,
+            nft: feesSerialized.nft,
+        };
+    }
+    /**
+     * Set balance update callback
+     *
+     * Called when private balances change for any wallet.
+     *
+     * @param callback - Function to call on balance updates
+     *
+     * @example
+     * ```typescript
+     * RailgunEngine.setOnBalanceUpdate((balances, walletID, network) => {
+     *   console.log(`Wallet ${walletID} on ${network}:`, balances);
+     *   updateUI(balances);
+     * });
+     * ```
+     */
+    static setOnBalanceUpdate(callback) {
+        this.ensureInitialized();
+        (0, wallet_1.setOnBalanceUpdateCallback)(callback);
+    }
+    /**
+     * Set merkletree scan progress callback
+     *
+     * Called during blockchain scanning for private transactions.
+     *
+     * @param callback - Function to call with scan progress
+     *
+     * @example
+     * ```typescript
+     * RailgunEngine.setOnScanProgress((progress, network) => {
+     *   console.log(`Scanning ${network}: ${progress}%`);
+     *   updateProgressBar(progress);
+     * });
+     * ```
+     */
+    static setOnScanProgress(callback) {
+        this.ensureInitialized();
+        (0, wallet_1.setOnMerkletreeScanCallback)(callback);
+    }
+    // ===== PRIVATE HELPERS =====
+    static ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('RAILGUN engine not initialized. Call RailgunEngine.initialize() first.');
+        }
+    }
+    static validateConfig(config) {
+        if (!config.walletSource || config.walletSource.length > 16) {
+            throw new Error('walletSource must be 1-16 characters');
+        }
+        if (config.walletSource !== config.walletSource.toLowerCase()) {
+            throw new Error('walletSource must be lowercase');
+        }
+        if (!config.db) {
+            throw new Error('db (LevelDB instance) is required');
+        }
+        if (!config.artifactStore) {
+            throw new Error('artifactStore is required');
+        }
+        if (!config.poiNodeURLs || config.poiNodeURLs.length === 0) {
+            throw new Error('At least one POI node URL is required');
+        }
+    }
+    static async preloadArtifacts(artifactStore, preloaded) {
+        for (const [path, content] of preloaded.artifacts.entries()) {
+            const dir = path.substring(0, path.lastIndexOf('/'));
+            const filename = path.substring(path.lastIndexOf('/') + 1);
+            await artifactStore.storeFile(dir, filename, content);
+        }
+    }
+}
+exports.RailgunEngine = RailgunEngine;
+//# sourceMappingURL=railgun-engine.js.map

package/dist/privacy/railgun-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"railgun-engine.js","sourceRoot":"","sources":["../../utils/privacy/railgun-engine.ts"],"names":[],"mappings":"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"}

package/dist/privacy/railgun-privacy-wallet.d.ts

@@ -0,0 +1,288 @@
+/**
+ * RAILGUN Privacy Wallet
+ *
+ * Core class for RAILGUN privacy operations:
+ * - Create/load private wallets
+ * - Shield (public → private)
+ * - Unshield (private → public)
+ * - Private transfers (private → private)
+ * - Query private balances
+ *
+ * STATELESS: Does not store wallet data.
+ * Implementer must store RailgunWalletInfo and manage encryption keys.
+ */
+import { NetworkName } from '@railgun-community/shared-models';
+import { RailgunWalletInfo, ShieldTransaction, UnshieldTransaction, PrivateTransferTransaction, ShieldOptions, UnshieldOptions, PrivateTransferOptions, PrivateBalance } from './types';
+/**
+ * RAILGUN Privacy Wallet
+ *
+ * Provides privacy features for a single RAILGUN wallet.
+ * Wallets are encrypted and stored in the LevelDB database.
+ *
+ * STATELESS DESIGN:
+ * - Does NOT store wallet data internally
+ * - All operations require explicit parameters
+ * - Implementer manages RailgunWalletInfo storage
+ */
+export declare class RailgunPrivacyWallet {
+    private railgunWalletID;
+    private railgunAddress;
+    /**
+     * Private constructor - use static create() or load() methods
+     */
+    private constructor();
+    /**
+     * Create a new RAILGUN wallet from mnemonic
+     *
+     * IMPORTANT: This creates an encrypted wallet in the LevelDB database.
+     * Returns RailgunWalletInfo that MUST be stored by implementer.
+     *
+     * @param encryptionKey - Key to encrypt wallet (derive from user password)
+     * @param mnemonic - BIP-39 mnemonic phrase
+     * @param creationBlockNumbers - Optional block numbers per chain for faster syncing
+     *
+     * @returns RailgunWalletInfo to store
+     *
+     * @example
+     * ```typescript
+     * import { Wallet } from 'ethers';
+     *
+     * const mnemonic = Wallet.createRandom().mnemonic.phrase;
+     * const encryptionKey = deriveKeyFromPassword(userPassword);
+     *
+     * const walletInfo = await RailgunPrivacyWallet.create(
+     *   encryptionKey,
+     *   mnemonic
+     * );
+     *
+     * // Implementer stores this
+     * await storage.save({
+     *   railgunWalletID: walletInfo.railgunWalletID,
+     *   railgunAddress: walletInfo.railgunAddress,
+     *   viewingPrivateKey: encrypt(walletInfo.viewingPrivateKey),
+     *   spendingPublicKey: walletInfo.spendingPublicKey
+     * });
+     * ```
+     */
+    static create(encryptionKey: string, mnemonic: string, creationBlockNumbers?: Record<string, number>): Promise<RailgunWalletInfo>;
+    /**
+     * Load existing RAILGUN wallet by ID
+     *
+     * Retrieves wallet from LevelDB database.
+     * Implementer must have stored railgunWalletID from create().
+     *
+     * @param encryptionKey - Same key used during creation
+     * @param railgunWalletID - Wallet ID from RailgunWalletInfo
+     *
+     * @returns RailgunPrivacyWallet instance
+     *
+     * @example
+     * ```typescript
+     * const stored = await storage.get(userId);
+     * const encryptionKey = deriveKeyFromPassword(userPassword);
+     *
+     * const wallet = await RailgunPrivacyWallet.load(
+     *   encryptionKey,
+     *   stored.railgunWalletID
+     * );
+     * ```
+     */
+    static load(encryptionKey: string, railgunWalletID: string): Promise<RailgunPrivacyWallet>;
+    /**
+     * Create RAILGUN wallet for specific BIP-44 account index
+     *
+     * Useful for linking privacy to savings pockets or account indices.
+     *
+     * @param encryptionKey - Encryption key
+     * @param mnemonic - BIP-39 mnemonic
+     * @param accountIndex - BIP-44 account index
+     * @param creationBlockNumbers - Optional block numbers
+     *
+     * @returns RailgunWalletInfo to store
+     *
+     * @example
+     * ```typescript
+     * // Create privacy wallet for savings account #1
+     * const walletInfo = await RailgunPrivacyWallet.createForAccount(
+     *   encryptionKey,
+     *   mnemonic,
+     *   1 // Same index as savings pocket
+     * );
+     * ```
+     */
+    static createForAccount(encryptionKey: string, mnemonic: string, accountIndex: number, creationBlockNumbers?: Record<string, number>): Promise<RailgunWalletInfo>;
+    /**
+     * Build shield transaction (ERC-20)
+     *
+     * Shields ERC-20 tokens from public address into this RAILGUN wallet.
+     * NO PROOF REQUIRED - direct contract interaction.
+     *
+     * Fees: 0.25% shield fee
+     * Standby: 1 hour on mainnet before spendable
+     *
+     * @param fromAddress - Public address sending tokens
+     * @param tokenAddress - ERC-20 contract address
+     * @param amount - Amount to shield (in smallest units)
+     * @param network - Network name
+     * @param options - Shield options
+     *
+     * @returns Shield transaction ready for broadcast
+     *
+     * @example
+     * ```typescript
+     * const shieldTx = await wallet.buildShield(
+     *   publicAddress,
+     *   USDC_ADDRESS,
+     *   parseUnits("100", 6), // 100 USDC
+     *   NetworkName.Ethereum
+     * );
+     *
+     * // Broadcast using standard wallet
+     * await publicWallet.sendTransaction(shieldTx);
+     * ```
+     */
+    buildShield(fromAddress: string, tokenAddress: string, amount: bigint, network: NetworkName, options?: ShieldOptions): Promise<ShieldTransaction>;
+    /**
+     * Build shield transaction (base token)
+     *
+     * Shields native token (ETH, MATIC, BNB) into RAILGUN.
+     *
+     * @param fromAddress - Public address
+     * @param amount - Amount to shield (in wei)
+     * @param network - Network name
+     * @param options - Shield options
+     *
+     * @returns Shield transaction
+     */
+    buildShieldBaseToken(fromAddress: string, amount: bigint, network: NetworkName, options?: ShieldOptions): Promise<ShieldTransaction>;
+    /**
+     * Build unshield transaction (ERC-20)
+     *
+     * Unshields ERC-20 tokens from RAILGUN to public address.
+     * REQUIRES PROOF GENERATION (20-30 seconds).
+     *
+     * Fees: 0.25% unshield fee
+     *
+     * @param toAddress - Public address to receive tokens
+     * @param tokenAddress - ERC-20 contract address
+     * @param amount - Amount to unshield
+     * @param network - Network name
+     * @param encryptionKey - Wallet encryption key
+     * @param options - Unshield options
+     *
+     * @returns Unshield transaction with proof
+     *
+     * @example
+     * ```typescript
+     * const unshieldTx = await wallet.buildUnshield(
+     *   recipientAddress,
+     *   USDC_ADDRESS,
+     *   parseUnits("50", 6),
+     *   NetworkName.Ethereum,
+     *   encryptionKey,
+     *   {
+     *     onProgress: (p) => console.log(`Proof: ${p}%`)
+     *   }
+     * );
+     *
+     * // Broadcast
+     * await wallet.sendTransaction(unshieldTx);
+     * ```
+     */
+    buildUnshield(toAddress: string, tokenAddress: string, amount: bigint, network: NetworkName, encryptionKey: string, options?: UnshieldOptions): Promise<UnshieldTransaction>;
+    /**
+     * Build private transfer transaction
+     *
+     * Transfers tokens from this RAILGUN wallet to another 0zk address.
+     * Fully encrypted - sender, receiver, amount all hidden.
+     * REQUIRES PROOF GENERATION (20-30 seconds).
+     *
+     * @param toRailgunAddress - Recipient's 0zk address
+     * @param tokenAddress - ERC-20 contract address
+     * @param amount - Amount to transfer
+     * @param network - Network name
+     * @param encryptionKey - Wallet encryption key
+     * @param options - Transfer options (broadcasterFee REQUIRED for anonymity)
+     *
+     * @returns Private transfer transaction with proof
+     *
+     * @example
+     * ```typescript
+     * const transferTx = await wallet.buildPrivateTransfer(
+     *   "0zk1234...",
+     *   USDC_ADDRESS,
+     *   parseUnits("25", 6),
+     *   NetworkName.Ethereum,
+     *   encryptionKey,
+     *   {
+     *     broadcasterFee: {
+     *       tokenAddress: USDC_ADDRESS,
+     *       amount: parseUnits("0.1", 6)
+     *     },
+     *     onProgress: (p) => console.log(`${p}%`)
+     *   }
+     * );
+     *
+     * // Submit via broadcaster for anonymity
+     * await broadcasterClient.submitTransaction(transferTx);
+     * ```
+     */
+    buildPrivateTransfer(toRailgunAddress: string, tokenAddress: string, amount: bigint, network: NetworkName, encryptionKey: string, options: PrivateTransferOptions): Promise<PrivateTransferTransaction>;
+    /**
+     * Scan blockchain for new private transactions
+     *
+     * Must be called before getBalances() to get latest data.
+     * Scans merkletree for encrypted notes belonging to this wallet.
+     *
+     * @param network - Network to scan
+     *
+     * @example
+     * ```typescript
+     * await wallet.scanTransactions(NetworkName.Ethereum);
+     * const balances = await wallet.getBalances(NetworkName.Ethereum);
+     * ```
+     */
+    scanTransactions(network: NetworkName): Promise<void>;
+    /**
+     * Get private balances for this wallet
+     *
+     * Returns balances grouped by POI bucket status.
+     * Call scanTransactions() first for latest data.
+     *
+     * @param network - Network to query
+     * @param tokenAddresses - Optional filter for specific tokens
+     *
+     * @returns Array of private balances
+     *
+     * @example
+     * ```typescript
+     * const balances = await wallet.getBalances(
+     *   NetworkName.Ethereum,
+     *   [USDC_ADDRESS, DAI_ADDRESS]
+     * );
+     *
+     * const spendable = balances.filter(b => b.bucket === BalanceBucket.Spendable);
+     * ```
+     */
+    getBalances(network: NetworkName, tokenAddresses?: string[]): Promise<PrivateBalance[]>;
+    /**
+     * Get balance for single token
+     *
+     * @param network - Network to query
+     * @param tokenAddress - Token contract address
+     *
+     * @returns Total balance across all buckets
+     */
+    getBalance(network: NetworkName, tokenAddress: string): Promise<bigint>;
+    /**
+     * Get spendable balance only
+     *
+     * @param network - Network to query
+     * @param tokenAddress - Token contract address
+     *
+     * @returns Spendable balance (excludes pending/blocked)
+     */
+    getSpendableBalance(network: NetworkName, tokenAddress: string): Promise<bigint>;
+    getRailgunAddress(): string;
+    getRailgunWalletID(): string;
+}