@deserialize/multi-vm-wallet 1.3.2 → 1.3.3

package/dist/privacy/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RAILGUN Privacy Module
+ *
+ * Provides zero-knowledge privacy features for the wallet SDK.
+ * Completely independent from savings features.
+ *
+ * Usage:
+ * ```typescript
+ * import { RailgunEngine, RailgunPrivacyWallet } from './privacy';
+ *
+ * // Initialize engine once
+ * await RailgunEngine.initialize({
+ *   walletSource: 'mywallet',
+ *   db,
+ *   artifactStore,
+ *   poiNodeURLs: ['...']
+ * });
+ *
+ * // Create privacy wallet
+ * const walletInfo = await RailgunPrivacyWallet.create(encryptionKey, mnemonic);
+ *
+ * // Use privacy features
+ * const wallet = await RailgunPrivacyWallet.load(encryptionKey, walletInfo.railgunWalletID);
+ * const shieldTx = await wallet.buildShield(...);
+ * ```
+ */
+export { RailgunEngine } from './railgun-engine';
+export { RailgunPrivacyWallet } from './railgun-privacy-wallet';
+export { ArtifactManager } from './artifact-manager';
+export { POIHelper } from './poi-helper';
+export { BroadcasterClient, createBroadcasterFeeCallback } from './broadcaster-client';
+export { RAILGUN_NETWORKS, DEFAULT_POI_NODES, POI_STANDBY_PERIODS, getNetworkConfig, getNetworkConfigByChainId, isNetworkSupported, isChainIdSupported, getSupportedNetworks, getSupportedChainIds, getPOIStandbyPeriod, } from './network-config';
+export type { RailgunDatabase, ArtifactStore, RailgunEngineConfig, PreloadedArtifacts, RailgunWalletInfo, PrivateBalance, BalanceUpdateCallback, ScanProgressCallback, BaseRailgunTransaction, ShieldTransaction, UnshieldTransaction, PrivateTransferTransaction, ShieldOptions, UnshieldOptions, PrivateTransferOptions, POISpendabilityResult, ArtifactDownloadProgress, ArtifactDownloadCallback, ArtifactSyncResult, RailgunNetworkConfig, BroadcasterInfo, BroadcasterFeeCallback, NetworkFees, } from './types';
+export { BalanceBucket } from './types';

package/dist/privacy/index.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * RAILGUN Privacy Module
+ *
+ * Provides zero-knowledge privacy features for the wallet SDK.
+ * Completely independent from savings features.
+ *
+ * Usage:
+ * ```typescript
+ * import { RailgunEngine, RailgunPrivacyWallet } from './privacy';
+ *
+ * // Initialize engine once
+ * await RailgunEngine.initialize({
+ *   walletSource: 'mywallet',
+ *   db,
+ *   artifactStore,
+ *   poiNodeURLs: ['...']
+ * });
+ *
+ * // Create privacy wallet
+ * const walletInfo = await RailgunPrivacyWallet.create(encryptionKey, mnemonic);
+ *
+ * // Use privacy features
+ * const wallet = await RailgunPrivacyWallet.load(encryptionKey, walletInfo.railgunWalletID);
+ * const shieldTx = await wallet.buildShield(...);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BalanceBucket = exports.getPOIStandbyPeriod = exports.getSupportedChainIds = exports.getSupportedNetworks = exports.isChainIdSupported = exports.isNetworkSupported = exports.getNetworkConfigByChainId = exports.getNetworkConfig = exports.POI_STANDBY_PERIODS = exports.DEFAULT_POI_NODES = exports.RAILGUN_NETWORKS = exports.createBroadcasterFeeCallback = exports.BroadcasterClient = exports.POIHelper = exports.ArtifactManager = exports.RailgunPrivacyWallet = exports.RailgunEngine = void 0;
+// Core classes
+var railgun_engine_1 = require("./railgun-engine");
+Object.defineProperty(exports, "RailgunEngine", { enumerable: true, get: function () { return railgun_engine_1.RailgunEngine; } });
+var railgun_privacy_wallet_1 = require("./railgun-privacy-wallet");
+Object.defineProperty(exports, "RailgunPrivacyWallet", { enumerable: true, get: function () { return railgun_privacy_wallet_1.RailgunPrivacyWallet; } });
+var artifact_manager_1 = require("./artifact-manager");
+Object.defineProperty(exports, "ArtifactManager", { enumerable: true, get: function () { return artifact_manager_1.ArtifactManager; } });
+var poi_helper_1 = require("./poi-helper");
+Object.defineProperty(exports, "POIHelper", { enumerable: true, get: function () { return poi_helper_1.POIHelper; } });
+var broadcaster_client_1 = require("./broadcaster-client");
+Object.defineProperty(exports, "BroadcasterClient", { enumerable: true, get: function () { return broadcaster_client_1.BroadcasterClient; } });
+Object.defineProperty(exports, "createBroadcasterFeeCallback", { enumerable: true, get: function () { return broadcaster_client_1.createBroadcasterFeeCallback; } });
+// Network configuration
+var network_config_1 = require("./network-config");
+Object.defineProperty(exports, "RAILGUN_NETWORKS", { enumerable: true, get: function () { return network_config_1.RAILGUN_NETWORKS; } });
+Object.defineProperty(exports, "DEFAULT_POI_NODES", { enumerable: true, get: function () { return network_config_1.DEFAULT_POI_NODES; } });
+Object.defineProperty(exports, "POI_STANDBY_PERIODS", { enumerable: true, get: function () { return network_config_1.POI_STANDBY_PERIODS; } });
+Object.defineProperty(exports, "getNetworkConfig", { enumerable: true, get: function () { return network_config_1.getNetworkConfig; } });
+Object.defineProperty(exports, "getNetworkConfigByChainId", { enumerable: true, get: function () { return network_config_1.getNetworkConfigByChainId; } });
+Object.defineProperty(exports, "isNetworkSupported", { enumerable: true, get: function () { return network_config_1.isNetworkSupported; } });
+Object.defineProperty(exports, "isChainIdSupported", { enumerable: true, get: function () { return network_config_1.isChainIdSupported; } });
+Object.defineProperty(exports, "getSupportedNetworks", { enumerable: true, get: function () { return network_config_1.getSupportedNetworks; } });
+Object.defineProperty(exports, "getSupportedChainIds", { enumerable: true, get: function () { return network_config_1.getSupportedChainIds; } });
+Object.defineProperty(exports, "getPOIStandbyPeriod", { enumerable: true, get: function () { return network_config_1.getPOIStandbyPeriod; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "BalanceBucket", { enumerable: true, get: function () { return types_1.BalanceBucket; } });
+//# sourceMappingURL=index.js.map

package/dist/privacy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../utils/privacy/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAEH,eAAe;AACf,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AACtB,mEAAgE;AAAvD,8HAAA,oBAAoB,OAAA;AAC7B,uDAAqD;AAA5C,mHAAA,eAAe,OAAA;AACxB,2CAAyC;AAAhC,uGAAA,SAAS,OAAA;AAClB,2DAAuF;AAA9E,uHAAA,iBAAiB,OAAA;AAAE,kIAAA,4BAA4B,OAAA;AAExD,wBAAwB;AACxB,mDAW0B;AAVxB,kHAAA,gBAAgB,OAAA;AAChB,mHAAA,iBAAiB,OAAA;AACjB,qHAAA,mBAAmB,OAAA;AACnB,kHAAA,gBAAgB,OAAA;AAChB,2HAAA,yBAAyB,OAAA;AACzB,oHAAA,kBAAkB,OAAA;AAClB,oHAAA,kBAAkB,OAAA;AAClB,sHAAA,oBAAoB,OAAA;AACpB,sHAAA,oBAAoB,OAAA;AACpB,qHAAA,mBAAmB,OAAA;AA8BrB,iCAAwC;AAA/B,sGAAA,aAAa,OAAA"}

package/dist/privacy/network-config.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+import { NetworkName } from '@railgun-community/shared-models';
+import { RailgunNetworkConfig } from './types';
+/**
+ * All RAILGUN supported networks
+ */
+export declare const RAILGUN_NETWORKS: Record<string, RailgunNetworkConfig>;
+/**
+ * Get RAILGUN network config by NetworkName
+ */
+export declare function getNetworkConfig(network: NetworkName): RailgunNetworkConfig | undefined;
+/**
+ * Get RAILGUN network config by chain ID
+ */
+export declare function getNetworkConfigByChainId(chainId: number): RailgunNetworkConfig | undefined;
+/**
+ * Check if a network is supported by RAILGUN
+ */
+export declare function isNetworkSupported(network: NetworkName): boolean;
+/**
+ * Check if a chain ID is supported by RAILGUN
+ */
+export declare function isChainIdSupported(chainId: number): boolean;
+/**
+ * Get all supported NetworkName values
+ */
+export declare function getSupportedNetworks(): NetworkName[];
+/**
+ * Get all supported chain IDs
+ */
+export declare function getSupportedChainIds(): number[];
+/**
+ * Default POI (Proof of Innocence) aggregator nodes
+ */
+export declare const DEFAULT_POI_NODES: string[];
+/**
+ * POI standby periods (in milliseconds)
+ */
+export declare const POI_STANDBY_PERIODS: {
+    mainnet: number;
+    testnet: number;
+};
+/**
+ * Get POI standby period for a network
+ */
+export declare function getPOIStandbyPeriod(network: NetworkName): number;

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