@deserialize/multi-vm-wallet 1.3.1 → 1.3.3

package/dist/privacy/network-config.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * RAILGUN Network Configurations
+ *
+ * Defines all supported RAILGUN networks with their deployment information.
+ * Based on official RAILGUN deployments as of 2024.
+ *
+ * Supported Networks:
+ * - Ethereum Mainnet
+ * - Polygon (Matic)
+ * - BNB Chain (BSC)
+ * - Arbitrum One
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POI_STANDBY_PERIODS = exports.DEFAULT_POI_NODES = exports.RAILGUN_NETWORKS = void 0;
+exports.getNetworkConfig = getNetworkConfig;
+exports.getNetworkConfigByChainId = getNetworkConfigByChainId;
+exports.isNetworkSupported = isNetworkSupported;
+exports.isChainIdSupported = isChainIdSupported;
+exports.getSupportedNetworks = getSupportedNetworks;
+exports.getSupportedChainIds = getSupportedChainIds;
+exports.getPOIStandbyPeriod = getPOIStandbyPeriod;
+const shared_models_1 = require("@railgun-community/shared-models");
+/**
+ * All RAILGUN supported networks
+ */
+exports.RAILGUN_NETWORKS = {
+    ethereum: {
+        name: shared_models_1.NetworkName.Ethereum,
+        chainId: 1,
+        publicName: 'Ethereum',
+        deploymentBlock: 15725700, // Approximate RAILGUN deployment block
+    },
+    polygon: {
+        name: shared_models_1.NetworkName.Polygon,
+        chainId: 137,
+        publicName: 'Polygon',
+        deploymentBlock: 34715800, // Approximate RAILGUN deployment block
+    },
+    bsc: {
+        name: shared_models_1.NetworkName.BNBChain,
+        chainId: 56,
+        publicName: 'BNB Chain',
+        deploymentBlock: 22550000, // Approximate RAILGUN deployment block
+    },
+    arbitrum: {
+        name: shared_models_1.NetworkName.Arbitrum,
+        chainId: 42161,
+        publicName: 'Arbitrum One',
+        deploymentBlock: 36070000, // Approximate RAILGUN deployment block
+    },
+};
+/**
+ * Get RAILGUN network config by NetworkName
+ */
+function getNetworkConfig(network) {
+    return Object.values(exports.RAILGUN_NETWORKS).find(config => config.name === network);
+}
+/**
+ * Get RAILGUN network config by chain ID
+ */
+function getNetworkConfigByChainId(chainId) {
+    return Object.values(exports.RAILGUN_NETWORKS).find(config => config.chainId === chainId);
+}
+/**
+ * Check if a network is supported by RAILGUN
+ */
+function isNetworkSupported(network) {
+    return !!getNetworkConfig(network);
+}
+/**
+ * Check if a chain ID is supported by RAILGUN
+ */
+function isChainIdSupported(chainId) {
+    return !!getNetworkConfigByChainId(chainId);
+}
+/**
+ * Get all supported NetworkName values
+ */
+function getSupportedNetworks() {
+    return Object.values(exports.RAILGUN_NETWORKS).map(config => config.name);
+}
+/**
+ * Get all supported chain IDs
+ */
+function getSupportedChainIds() {
+    return Object.values(exports.RAILGUN_NETWORKS).map(config => config.chainId);
+}
+/**
+ * Default POI (Proof of Innocence) aggregator nodes
+ */
+exports.DEFAULT_POI_NODES = [
+    'https://ppoi-agg.horsewithsixlegs.xyz', // Test/development node
+    // Add production POI nodes here when available
+];
+/**
+ * POI standby periods (in milliseconds)
+ */
+exports.POI_STANDBY_PERIODS = {
+    mainnet: 60 * 60 * 1000, // 1 hour
+    testnet: 5 * 60 * 1000, // 5 minutes
+};
+/**
+ * Get POI standby period for a network
+ */
+function getPOIStandbyPeriod(network) {
+    // Testnets have shorter periods
+    const testnets = [
+        shared_models_1.NetworkName.EthereumGoerli,
+        shared_models_1.NetworkName.EthereumSepolia,
+        shared_models_1.NetworkName.PolygonMumbai,
+        shared_models_1.NetworkName.ArbitrumGoerli,
+    ];
+    return testnets.includes(network)
+        ? exports.POI_STANDBY_PERIODS.testnet
+        : exports.POI_STANDBY_PERIODS.mainnet;
+}
+//# sourceMappingURL=network-config.js.map

package/dist/privacy/network-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-config.js","sourceRoot":"","sources":["../../utils/privacy/network-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAyCH,4CAEC;AAKD,8DAEC;AAKD,gDAEC;AAKD,gDAEC;AAKD,oDAEC;AAKD,oDAEC;AAqBD,kDAYC;AA7GD,oEAA+D;AAG/D;;GAEG;AACU,QAAA,gBAAgB,GAAyC;IACpE,QAAQ,EAAE;QACR,IAAI,EAAE,2BAAW,CAAC,QAAQ;QAC1B,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,UAAU;QACtB,eAAe,EAAE,QAAQ,EAAE,uCAAuC;KACnE;IAED,OAAO,EAAE;QACP,IAAI,EAAE,2BAAW,CAAC,OAAO;QACzB,OAAO,EAAE,GAAG;QACZ,UAAU,EAAE,SAAS;QACrB,eAAe,EAAE,QAAQ,EAAE,uCAAuC;KACnE;IAED,GAAG,EAAE;QACH,IAAI,EAAE,2BAAW,CAAC,QAAQ;QAC1B,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,WAAW;QACvB,eAAe,EAAE,QAAQ,EAAE,uCAAuC;KACnE;IAED,QAAQ,EAAE;QACR,IAAI,EAAE,2BAAW,CAAC,QAAQ;QAC1B,OAAO,EAAE,KAAK;QACd,UAAU,EAAE,cAAc;QAC1B,eAAe,EAAE,QAAQ,EAAE,uCAAuC;KACnE;CACF,CAAC;AAEF;;GAEG;AACH,SAAgB,gBAAgB,CAAC,OAAoB;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,wBAAgB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;AACjF,CAAC;AAED;;GAEG;AACH,SAAgB,yBAAyB,CAAC,OAAe;IACvD,OAAO,MAAM,CAAC,MAAM,CAAC,wBAAgB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;AACpF,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAAC,OAAoB;IACrD,OAAO,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAAC,OAAe;IAChD,OAAO,CAAC,CAAC,yBAAyB,CAAC,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,SAAgB,oBAAoB;IAClC,OAAO,MAAM,CAAC,MAAM,CAAC,wBAAgB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED;;GAEG;AACH,SAAgB,oBAAoB;IAClC,OAAO,MAAM,CAAC,MAAM,CAAC,wBAAgB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACvE,CAAC;AAED;;GAEG;AACU,QAAA,iBAAiB,GAAG;IAC/B,uCAAuC,EAAE,wBAAwB;IACjE,+CAA+C;CAChD,CAAC;AAEF;;GAEG;AACU,QAAA,mBAAmB,GAAG;IACjC,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,SAAS;IAClC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,YAAY;CACtC,CAAC;AAEF;;GAEG;AACH,SAAgB,mBAAmB,CAAC,OAAoB;IACtD,gCAAgC;IAChC,MAAM,QAAQ,GAAG;QACf,2BAAW,CAAC,cAAc;QAC1B,2BAAW,CAAC,eAAe;QAC3B,2BAAW,CAAC,aAAa;QACzB,2BAAW,CAAC,cAAc;KAC3B,CAAC;IAEF,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC;QAC/B,CAAC,CAAC,2BAAmB,CAAC,OAAO;QAC7B,CAAC,CAAC,2BAAmB,CAAC,OAAO,CAAC;AAClC,CAAC"}

package/dist/privacy/poi-helper.d.ts

@@ -0,0 +1,161 @@
+/**
+ * RAILGUN POI (Proof of Innocence) Helper
+ *
+ * Provides utilities for checking POI status and fund spendability.
+ *
+ * Key Concepts:
+ * - After shielding, funds enter a 1-hour "standby period" on mainnet (5 min on testnets)
+ * - During standby, funds are "ShieldPending" and cannot be spent
+ * - After standby, funds become "Spendable" if POI is valid
+ * - Funds can also be in other states (ShieldBlocked, MissingPOI, etc.)
+ */
+import { NetworkName } from '@railgun-community/shared-models';
+import { BalanceBucket, POISpendabilityResult, PrivateBalance } from './types';
+/**
+ * POIHelper
+ *
+ * Stateless utilities for POI status checking.
+ */
+export declare class POIHelper {
+    /**
+     * Check if funds are spendable
+     *
+     * A balance is spendable if it's in the "Spendable" bucket.
+     *
+     * @param balance - Private balance to check
+     * @returns true if spendable, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const balances = await wallet.getBalances(NetworkName.Ethereum);
+     * const spendable = balances.filter(b => POIHelper.isSpendable(b));
+     * ```
+     */
+    static isSpendable(balance: PrivateBalance): boolean;
+    /**
+     * Check if funds are in standby period
+     *
+     * @param balance - Private balance to check
+     * @returns true if in ShieldPending state
+     */
+    static isInStandby(balance: PrivateBalance): boolean;
+    /**
+     * Check if funds are blocked
+     *
+     * @param balance - Private balance to check
+     * @returns true if in ShieldBlocked state
+     */
+    static isBlocked(balance: PrivateBalance): boolean;
+    /**
+     * Check if funds have POI issues
+     *
+     * @param balance - Private balance to check
+     * @returns true if missing internal or external POI
+     */
+    static hasPOIIssue(balance: PrivateBalance): boolean;
+    /**
+     * Get detailed spendability status
+     *
+     * Returns comprehensive information about whether funds can be spent
+     * and when they will become available.
+     *
+     * @param balance - Private balance to check
+     * @param network - Network name
+     * @param shieldTimestamp - When funds were shielded (milliseconds since epoch)
+     * @returns Detailed spendability result
+     *
+     * @example
+     * ```typescript
+     * const result = POIHelper.getSpendabilityStatus(
+     *   balance,
+     *   NetworkName.Ethereum,
+     *   Date.now() - (30 * 60 * 1000) // Shielded 30 minutes ago
+     * );
+     *
+     * if (!result.isSpendable && result.remainingTime) {
+     *   console.log(`Wait ${result.remainingTime / 1000 / 60} more minutes`);
+     * }
+     * ```
+     */
+    static getSpendabilityStatus(balance: PrivateBalance, network: NetworkName, shieldTimestamp?: number): POISpendabilityResult;
+    /**
+     * Filter balances to only spendable ones
+     *
+     * @param balances - Array of private balances
+     * @returns Only spendable balances
+     *
+     * @example
+     * ```typescript
+     * const allBalances = await wallet.getBalances(NetworkName.Ethereum);
+     * const spendable = POIHelper.filterSpendable(allBalances);
+     * ```
+     */
+    static filterSpendable(balances: PrivateBalance[]): PrivateBalance[];
+    /**
+     * Get total spendable amount for a token
+     *
+     * Sums up all spendable balances for a specific token address.
+     *
+     * @param balances - Array of private balances
+     * @param tokenAddress - Token contract address
+     * @returns Total spendable amount as bigint
+     *
+     * @example
+     * ```typescript
+     * const balances = await wallet.getBalances(NetworkName.Ethereum);
+     * const usdcSpendable = POIHelper.getTotalSpendable(balances, USDC_ADDRESS);
+     * ```
+     */
+    static getTotalSpendable(balances: PrivateBalance[], tokenAddress: string): bigint;
+    /**
+     * Get total amount by bucket
+     *
+     * Sums balances grouped by bucket category.
+     *
+     * @param balances - Array of private balances
+     * @returns Map of bucket to total amount
+     *
+     * @example
+     * ```typescript
+     * const balances = await wallet.getBalances(NetworkName.Ethereum);
+     * const byBucket = POIHelper.getTotalsByBucket(balances);
+     *
+     * console.log(`Spendable: ${byBucket.get(BalanceBucket.Spendable)}`);
+     * console.log(`Pending: ${byBucket.get(BalanceBucket.ShieldPending)}`);
+     * ```
+     */
+    static getTotalsByBucket(balances: PrivateBalance[]): Map<BalanceBucket, bigint>;
+    /**
+     * Estimate time until all balances are spendable
+     *
+     * Calculates the maximum remaining standby time across all pending balances.
+     *
+     * @param balances - Array of private balances
+     * @param network - Network name
+     * @param shieldTimestamps - Map of balance index to shield timestamp
+     * @returns Milliseconds until last balance becomes spendable (0 if all spendable)
+     *
+     * @example
+     * ```typescript
+     * const maxWait = POIHelper.estimateTimeUntilSpendable(
+     *   balances,
+     *   NetworkName.Ethereum,
+     *   shieldTimestamps
+     * );
+     *
+     * if (maxWait > 0) {
+     *   console.log(`Wait ${maxWait / 1000 / 60} minutes for all funds`);
+     * }
+     * ```
+     */
+    static estimateTimeUntilSpendable(balances: PrivateBalance[], network: NetworkName, shieldTimestamps: Map<number, number>): number;
+    /**
+     * Format bucket name for display
+     *
+     * Converts BalanceBucket enum to human-readable string.
+     *
+     * @param bucket - Balance bucket
+     * @returns Human-readable description
+     */
+    static formatBucketName(bucket: BalanceBucket): string;
+}

package/dist/privacy/poi-helper.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * RAILGUN POI (Proof of Innocence) Helper
+ *
+ * Provides utilities for checking POI status and fund spendability.
+ *
+ * Key Concepts:
+ * - After shielding, funds enter a 1-hour "standby period" on mainnet (5 min on testnets)
+ * - During standby, funds are "ShieldPending" and cannot be spent
+ * - After standby, funds become "Spendable" if POI is valid
+ * - Funds can also be in other states (ShieldBlocked, MissingPOI, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POIHelper = void 0;
+const types_1 = require("./types");
+const network_config_1 = require("./network-config");
+/**
+ * POIHelper
+ *
+ * Stateless utilities for POI status checking.
+ */
+class POIHelper {
+    /**
+     * Check if funds are spendable
+     *
+     * A balance is spendable if it's in the "Spendable" bucket.
+     *
+     * @param balance - Private balance to check
+     * @returns true if spendable, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const balances = await wallet.getBalances(NetworkName.Ethereum);
+     * const spendable = balances.filter(b => POIHelper.isSpendable(b));
+     * ```
+     */
+    static isSpendable(balance) {
+        return balance.bucket === types_1.BalanceBucket.Spendable;
+    }
+    /**
+     * Check if funds are in standby period
+     *
+     * @param balance - Private balance to check
+     * @returns true if in ShieldPending state
+     */
+    static isInStandby(balance) {
+        return balance.bucket === types_1.BalanceBucket.ShieldPending;
+    }
+    /**
+     * Check if funds are blocked
+     *
+     * @param balance - Private balance to check
+     * @returns true if in ShieldBlocked state
+     */
+    static isBlocked(balance) {
+        return balance.bucket === types_1.BalanceBucket.ShieldBlocked;
+    }
+    /**
+     * Check if funds have POI issues
+     *
+     * @param balance - Private balance to check
+     * @returns true if missing internal or external POI
+     */
+    static hasPOIIssue(balance) {
+        return (balance.bucket === types_1.BalanceBucket.MissingInternalPOI ||
+            balance.bucket === types_1.BalanceBucket.MissingExternalPOI);
+    }
+    /**
+     * Get detailed spendability status
+     *
+     * Returns comprehensive information about whether funds can be spent
+     * and when they will become available.
+     *
+     * @param balance - Private balance to check
+     * @param network - Network name
+     * @param shieldTimestamp - When funds were shielded (milliseconds since epoch)
+     * @returns Detailed spendability result
+     *
+     * @example
+     * ```typescript
+     * const result = POIHelper.getSpendabilityStatus(
+     *   balance,
+     *   NetworkName.Ethereum,
+     *   Date.now() - (30 * 60 * 1000) // Shielded 30 minutes ago
+     * );
+     *
+     * if (!result.isSpendable && result.remainingTime) {
+     *   console.log(`Wait ${result.remainingTime / 1000 / 60} more minutes`);
+     * }
+     * ```
+     */
+    static getSpendabilityStatus(balance, network, shieldTimestamp) {
+        const bucket = balance.bucket;
+        // Already spendable
+        if (bucket === types_1.BalanceBucket.Spendable) {
+            return {
+                isSpendable: true,
+                bucket,
+            };
+        }
+        // In standby period
+        if (bucket === types_1.BalanceBucket.ShieldPending && shieldTimestamp) {
+            const standbyPeriod = (0, network_config_1.getPOIStandbyPeriod)(network);
+            const elapsed = Date.now() - shieldTimestamp;
+            const remainingTime = Math.max(0, standbyPeriod - elapsed);
+            const estimatedSpendableAt = new Date(shieldTimestamp + standbyPeriod);
+            return {
+                isSpendable: false,
+                bucket,
+                remainingTime,
+                estimatedSpendableAt,
+            };
+        }
+        // Other states (blocked, missing POI, etc.)
+        return {
+            isSpendable: false,
+            bucket,
+        };
+    }
+    /**
+     * Filter balances to only spendable ones
+     *
+     * @param balances - Array of private balances
+     * @returns Only spendable balances
+     *
+     * @example
+     * ```typescript
+     * const allBalances = await wallet.getBalances(NetworkName.Ethereum);
+     * const spendable = POIHelper.filterSpendable(allBalances);
+     * ```
+     */
+    static filterSpendable(balances) {
+        return balances.filter(b => this.isSpendable(b));
+    }
+    /**
+     * Get total spendable amount for a token
+     *
+     * Sums up all spendable balances for a specific token address.
+     *
+     * @param balances - Array of private balances
+     * @param tokenAddress - Token contract address
+     * @returns Total spendable amount as bigint
+     *
+     * @example
+     * ```typescript
+     * const balances = await wallet.getBalances(NetworkName.Ethereum);
+     * const usdcSpendable = POIHelper.getTotalSpendable(balances, USDC_ADDRESS);
+     * ```
+     */
+    static getTotalSpendable(balances, tokenAddress) {
+        return balances
+            .filter(b => b.tokenAddress.toLowerCase() === tokenAddress.toLowerCase())
+            .filter(b => this.isSpendable(b))
+            .reduce((sum, b) => sum + b.amount, 0n);
+    }
+    /**
+     * Get total amount by bucket
+     *
+     * Sums balances grouped by bucket category.
+     *
+     * @param balances - Array of private balances
+     * @returns Map of bucket to total amount
+     *
+     * @example
+     * ```typescript
+     * const balances = await wallet.getBalances(NetworkName.Ethereum);
+     * const byBucket = POIHelper.getTotalsByBucket(balances);
+     *
+     * console.log(`Spendable: ${byBucket.get(BalanceBucket.Spendable)}`);
+     * console.log(`Pending: ${byBucket.get(BalanceBucket.ShieldPending)}`);
+     * ```
+     */
+    static getTotalsByBucket(balances) {
+        const totals = new Map();
+        for (const balance of balances) {
+            const current = totals.get(balance.bucket) || 0n;
+            totals.set(balance.bucket, current + balance.amount);
+        }
+        return totals;
+    }
+    /**
+     * Estimate time until all balances are spendable
+     *
+     * Calculates the maximum remaining standby time across all pending balances.
+     *
+     * @param balances - Array of private balances
+     * @param network - Network name
+     * @param shieldTimestamps - Map of balance index to shield timestamp
+     * @returns Milliseconds until last balance becomes spendable (0 if all spendable)
+     *
+     * @example
+     * ```typescript
+     * const maxWait = POIHelper.estimateTimeUntilSpendable(
+     *   balances,
+     *   NetworkName.Ethereum,
+     *   shieldTimestamps
+     * );
+     *
+     * if (maxWait > 0) {
+     *   console.log(`Wait ${maxWait / 1000 / 60} minutes for all funds`);
+     * }
+     * ```
+     */
+    static estimateTimeUntilSpendable(balances, network, shieldTimestamps) {
+        let maxRemaining = 0;
+        balances.forEach((balance, index) => {
+            if (balance.bucket === types_1.BalanceBucket.ShieldPending) {
+                const shieldTime = shieldTimestamps.get(index);
+                if (shieldTime) {
+                    const status = this.getSpendabilityStatus(balance, network, shieldTime);
+                    if (status.remainingTime) {
+                        maxRemaining = Math.max(maxRemaining, status.remainingTime);
+                    }
+                }
+            }
+        });
+        return maxRemaining;
+    }
+    /**
+     * Format bucket name for display
+     *
+     * Converts BalanceBucket enum to human-readable string.
+     *
+     * @param bucket - Balance bucket
+     * @returns Human-readable description
+     */
+    static formatBucketName(bucket) {
+        switch (bucket) {
+            case types_1.BalanceBucket.Spendable:
+                return 'Ready to spend';
+            case types_1.BalanceBucket.ShieldPending:
+                return 'Pending (standby period)';
+            case types_1.BalanceBucket.ShieldBlocked:
+                return 'Blocked';
+            case types_1.BalanceBucket.ProofSubmitted:
+                return 'Proof submitted';
+            case types_1.BalanceBucket.MissingInternalPOI:
+                return 'Missing internal POI';
+            case types_1.BalanceBucket.MissingExternalPOI:
+                return 'Missing external POI';
+            case types_1.BalanceBucket.Spent:
+                return 'Already spent';
+            default:
+                return 'Unknown status';
+        }
+    }
+}
+exports.POIHelper = POIHelper;
+//# sourceMappingURL=poi-helper.js.map

package/dist/privacy/poi-helper.js.map

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

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

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+import { NetworkName } from '@railgun-community/shared-models';
+import { RailgunEngineConfig, PreloadedArtifacts, ScanProgressCallback, BalanceUpdateCallback, NetworkFees } from './types';
+/**
+ * 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.
+ */
+export declare class RailgunEngine {
+    private static initialized;
+    private static config;
+    /**
+     * 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 initialize(config: RailgunEngineConfig, preloadedArtifacts?: PreloadedArtifacts): Promise<void>;
+    /**
+     * Shutdown RAILGUN engine
+     *
+     * Cleanup resources and stop the engine.
+     * After shutdown, initialize() must be called again to use privacy features.
+     */
+    static shutdown(): Promise<void>;
+    /**
+     * Check if engine is initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Get current configuration (read-only)
+     * Returns null if not initialized
+     */
+    static getConfig(): Readonly<RailgunEngineConfig> | 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 loadNetwork(network: NetworkName, rpcProvider: any, // ethers.Provider
+    pollingInterval?: number): Promise<NetworkFees>;
+    /**
+     * 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: BalanceUpdateCallback): void;
+    /**
+     * 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: ScanProgressCallback): void;
+    private static ensureInitialized;
+    private static validateConfig;
+    private static preloadArtifacts;
+}