pwc-sdk-wallet 0.6.3

package/dist/config/chains.d.ts

@@ -0,0 +1,233 @@
+import { ethers } from 'ethers';
+/**
+ * Set global RPC configuration from mobile app (highest priority)
+ * @param config - RPC URLs configuration
+ */
+export declare function setGlobalRPCConfig(config: Record<string, string>): void;
+/**
+ * Set global explorer configuration from mobile app (highest priority)
+ * @param config - Explorer URLs configuration
+ */
+export declare function setGlobalExplorerConfig(config: Record<string, string>): void;
+/**
+ * Get global RPC configuration
+ * @returns Current global RPC configuration
+ */
+export declare function getGlobalRPCConfig(): Record<string, string>;
+/**
+ * Get global explorer configuration
+ * @returns Current global explorer configuration
+ */
+export declare function getGlobalExplorerConfig(): Record<string, string>;
+/**
+ * Clear global configurations
+ */
+export declare function clearGlobalConfigs(): void;
+/**
+ * Interface representing chain configuration
+ */
+export interface ChainConfig {
+    name: string;
+    rpcUrl: string;
+    explorerUrl: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    type: 'evm' | 'solana';
+}
+/**
+ * Configuration object containing all supported blockchain networks.
+ * Each chain has its RPC URL, explorer URL, native currency details, and type.
+ * RPC URLs can be customized via environment variables.
+ */
+export declare const SUPPORTED_CHAINS: {
+    readonly '1': {
+        readonly name: "Ethereum";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        readonly type: "evm";
+    };
+    readonly '56': {
+        readonly name: "BNB Smart Chain";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "BNB";
+            readonly symbol: "BNB";
+            readonly decimals: 18;
+        };
+        readonly type: "evm";
+    };
+    readonly '137': {
+        readonly name: "Polygon";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "MATIC";
+            readonly symbol: "MATIC";
+            readonly decimals: 18;
+        };
+        readonly type: "evm";
+    };
+    readonly '42161': {
+        readonly name: "Arbitrum One";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        readonly type: "evm";
+    };
+    readonly '10': {
+        readonly name: "OP Mainnet";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        readonly type: "evm";
+    };
+    readonly '8453': {
+        readonly name: "Base";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        readonly type: "evm";
+    };
+    readonly solana: {
+        readonly name: "Solana";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "SOL";
+            readonly symbol: "SOL";
+            readonly decimals: 9;
+        };
+        readonly type: "solana";
+    };
+    readonly 'solana-devnet': {
+        readonly name: "Solana Devnet";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "SOL";
+            readonly symbol: "SOL";
+            readonly decimals: 9;
+        };
+        readonly type: "solana";
+    };
+    readonly '97': {
+        readonly name: "BNB Smart Chain Testnet";
+        readonly rpcUrl: string;
+        readonly explorerUrl: string;
+        readonly nativeCurrency: {
+            readonly name: "BNB";
+            readonly symbol: "tBNB";
+            readonly decimals: 18;
+        };
+        readonly type: "evm";
+    };
+};
+/**
+ * Type representing the supported chain IDs.
+ * Can be either EVM chain IDs (as strings) or Solana network identifiers.
+ */
+export type ChainId = keyof typeof SUPPORTED_CHAINS;
+/**
+ * Type representing the blockchain type.
+ * 'evm' for Ethereum-compatible chains, 'solana' for Solana blockchain.
+ */
+export type ChainType = 'evm' | 'solana';
+/**
+ * Creates and returns an ethers.js provider for the specified EVM chain.
+ * @param chainId - The chain ID to create a provider for (must be an EVM chain)
+ * @returns An ethers.js JsonRpcProvider instance for the specified chain
+ * @throws Error if the chain is not supported or is not an EVM chain
+ */
+export declare const getProvider: (chainId: ChainId) => ethers.JsonRpcProvider;
+/**
+ * BIP-44 derivation paths for different blockchain types.
+ * Used for deterministic wallet generation from mnemonics.
+ */
+export declare const DERIVATION_PATHS: {
+    /** Standard EVM derivation path following BIP-44 */
+    readonly EVM: "m/44'/60'/0'/0/0";
+    /** Solana derivation path following BIP-44 with hardened derivation */
+    readonly SOLANA: "m/44'/501'/0'/0'";
+};
+/**
+ * Register a custom chain (new chain not in built-in list)
+ * @param chainId - Custom chain ID (e.g., 'custom-1', 'my-chain')
+ * @param config - Complete chain configuration
+ */
+export declare function registerCustomChain(chainId: string, config: ChainConfig): void;
+/**
+ * Override a built-in chain configuration
+ * @param chainId - Built-in chain ID to override
+ * @param override - Partial configuration to override (only specify fields to change)
+ * @throws Error if chainId is not a built-in chain
+ */
+export declare function overrideChain(chainId: string, override: Partial<ChainConfig>): void;
+/**
+ * Override multiple built-in chains at once
+ * @param overrides - Object containing multiple chain overrides
+ */
+export declare function overrideChains(overrides: Record<string, Partial<ChainConfig>>): void;
+/**
+ * Get chain configuration with priority: Custom > Override > Built-in
+ * @param chainId - Chain ID to get configuration for
+ * @returns Chain configuration
+ * @throws Error if chain is not found
+ */
+export declare function getChainConfig(chainId: string): ChainConfig;
+/**
+ * Setup chain configurations with overrides and custom chains
+ * @param options - Configuration options
+ */
+export declare function setupChainConfigs(options: {
+    overrides?: Record<string, Partial<ChainConfig>>;
+    customChains?: Record<string, ChainConfig>;
+}): void;
+/**
+ * Get all available chains (built-in + custom)
+ * @returns Object containing all chain configurations
+ */
+export declare function getAllAvailableChains(): Record<string, ChainConfig>;
+/**
+ * Clear all custom chains
+ */
+export declare function clearCustomChains(): void;
+/**
+ * Clear all chain overrides
+ */
+export declare function clearOverrides(): void;
+/**
+ * Clear override for a specific chain
+ * @param chainId - Chain ID to clear override for
+ */
+export declare function clearOverride(chainId: string): void;
+/**
+ * Get all custom chains
+ * @returns Object containing custom chain configurations
+ */
+export declare function getCustomChains(): Record<string, ChainConfig>;
+/**
+ * Get all chain overrides
+ * @returns Object containing chain override configurations
+ */
+export declare function getOverrides(): Record<string, Partial<ChainConfig>>;

package/dist/config/chains.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DERIVATION_PATHS = exports.getProvider = exports.SUPPORTED_CHAINS = void 0;
+exports.setGlobalRPCConfig = setGlobalRPCConfig;
+exports.setGlobalExplorerConfig = setGlobalExplorerConfig;
+exports.getGlobalRPCConfig = getGlobalRPCConfig;
+exports.getGlobalExplorerConfig = getGlobalExplorerConfig;
+exports.clearGlobalConfigs = clearGlobalConfigs;
+exports.registerCustomChain = registerCustomChain;
+exports.overrideChain = overrideChain;
+exports.overrideChains = overrideChains;
+exports.getChainConfig = getChainConfig;
+exports.setupChainConfigs = setupChainConfigs;
+exports.getAllAvailableChains = getAllAvailableChains;
+exports.clearCustomChains = clearCustomChains;
+exports.clearOverrides = clearOverrides;
+exports.clearOverride = clearOverride;
+exports.getCustomChains = getCustomChains;
+exports.getOverrides = getOverrides;
+const ethers_1 = require("ethers");
+// Global config registry for mobile app overrides
+let GLOBAL_RPC_CONFIG = {};
+let GLOBAL_EXPLORER_CONFIG = {};
+/**
+ * Set global RPC configuration from mobile app (highest priority)
+ * @param config - RPC URLs configuration
+ */
+function setGlobalRPCConfig(config) {
+    GLOBAL_RPC_CONFIG = { ...GLOBAL_RPC_CONFIG, ...config };
+}
+/**
+ * Set global explorer configuration from mobile app (highest priority)
+ * @param config - Explorer URLs configuration
+ */
+function setGlobalExplorerConfig(config) {
+    GLOBAL_EXPLORER_CONFIG = { ...GLOBAL_EXPLORER_CONFIG, ...config };
+}
+/**
+ * Get global RPC configuration
+ * @returns Current global RPC configuration
+ */
+function getGlobalRPCConfig() {
+    return { ...GLOBAL_RPC_CONFIG };
+}
+/**
+ * Get global explorer configuration
+ * @returns Current global explorer configuration
+ */
+function getGlobalExplorerConfig() {
+    return { ...GLOBAL_EXPLORER_CONFIG };
+}
+/**
+ * Clear global configurations
+ */
+function clearGlobalConfigs() {
+    GLOBAL_RPC_CONFIG = {};
+    GLOBAL_EXPLORER_CONFIG = {};
+}
+/**
+ * Environment-based configuration for RPC URLs
+ * Allows customization via environment variables with fallbacks to public RPCs
+ * Priority: Mobile App Config > Environment Variables > SDK Defaults
+ */
+const getRpcUrl = (chainId, defaultUrl) => {
+    // Priority: Mobile App Config > Environment Variables > SDK Defaults
+    return GLOBAL_RPC_CONFIG[chainId] ||
+        process.env[`RPC_URL_${chainId}`] ||
+        defaultUrl;
+};
+const getExplorerUrl = (chainId, defaultUrl) => {
+    // Priority: Mobile App Config > Environment Variables > SDK Defaults
+    return GLOBAL_EXPLORER_CONFIG[chainId] ||
+        process.env[`EXPLORER_URL_${chainId}`] ||
+        defaultUrl;
+};
+/**
+ * Configuration object containing all supported blockchain networks.
+ * Each chain has its RPC URL, explorer URL, native currency details, and type.
+ * RPC URLs can be customized via environment variables.
+ */
+exports.SUPPORTED_CHAINS = {
+    '1': {
+        name: 'Ethereum',
+        rpcUrl: getRpcUrl('1', 'https://eth.llamarpc.com'),
+        explorerUrl: getExplorerUrl('1', 'https://etherscan.io'),
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        type: 'evm'
+    },
+    '56': {
+        name: 'BNB Smart Chain',
+        rpcUrl: getRpcUrl('56', 'https://bsc-dataseed.binance.org/'),
+        explorerUrl: getExplorerUrl('56', 'https://bscscan.com'),
+        nativeCurrency: { name: 'BNB', symbol: 'BNB', decimals: 18 },
+        type: 'evm'
+    },
+    '137': {
+        name: 'Polygon',
+        rpcUrl: getRpcUrl('137', 'https://polygon-rpc.com/'),
+        explorerUrl: getExplorerUrl('137', 'https://polygonscan.com'),
+        nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
+        type: 'evm'
+    },
+    '42161': {
+        name: 'Arbitrum One',
+        rpcUrl: getRpcUrl('42161', 'https://arb1.arbitrum.io/rpc'),
+        explorerUrl: getExplorerUrl('42161', 'https://arbiscan.io'),
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        type: 'evm'
+    },
+    '10': {
+        name: 'OP Mainnet',
+        rpcUrl: getRpcUrl('10', 'https://mainnet.optimism.io'),
+        explorerUrl: getExplorerUrl('10', 'https://optimistic.etherscan.io'),
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        type: 'evm'
+    },
+    '8453': {
+        name: 'Base',
+        rpcUrl: getRpcUrl('8453', 'https://mainnet.base.org'),
+        explorerUrl: getExplorerUrl('8453', 'https://basescan.org'),
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        type: 'evm'
+    },
+    'solana': {
+        name: 'Solana',
+        rpcUrl: getRpcUrl('solana', 'https://api.mainnet-beta.solana.com'),
+        explorerUrl: getExplorerUrl('solana', 'https://solscan.io'),
+        nativeCurrency: { name: 'SOL', symbol: 'SOL', decimals: 9 },
+        type: 'solana'
+    },
+    'solana-devnet': {
+        name: 'Solana Devnet',
+        rpcUrl: getRpcUrl('solana-devnet', 'https://api.devnet.solana.com'),
+        explorerUrl: getExplorerUrl('solana-devnet', 'https://solscan.io?cluster=devnet'),
+        nativeCurrency: { name: 'SOL', symbol: 'SOL', decimals: 9 },
+        type: 'solana'
+    },
+    '97': {
+        name: 'BNB Smart Chain Testnet',
+        rpcUrl: getRpcUrl('97', 'https://bsc-testnet-dataseed.bnbchain.org'),
+        explorerUrl: getExplorerUrl('97', 'https://testnet.bscscan.com'),
+        nativeCurrency: { name: 'BNB', symbol: 'tBNB', decimals: 18 },
+        type: 'evm'
+    }
+};
+/**
+ * Creates and returns an ethers.js provider for the specified EVM chain.
+ * @param chainId - The chain ID to create a provider for (must be an EVM chain)
+ * @returns An ethers.js JsonRpcProvider instance for the specified chain
+ * @throws Error if the chain is not supported or is not an EVM chain
+ */
+const getProvider = (chainId) => {
+    const chainInfo = exports.SUPPORTED_CHAINS[chainId];
+    if (!chainInfo) {
+        throw new Error(`Unsupported chain: ${chainId}`);
+    }
+    if (chainInfo.type !== 'evm') {
+        throw new Error(`Chain ${chainId} is not an EVM chain`);
+    }
+    return new ethers_1.ethers.JsonRpcProvider(chainInfo.rpcUrl);
+};
+exports.getProvider = getProvider;
+/**
+ * BIP-44 derivation paths for different blockchain types.
+ * Used for deterministic wallet generation from mnemonics.
+ */
+exports.DERIVATION_PATHS = {
+    /** Standard EVM derivation path following BIP-44 */
+    EVM: "m/44'/60'/0'/0/0",
+    /** Solana derivation path following BIP-44 with hardened derivation */
+    SOLANA: "m/44'/501'/0'/0'", // Solana BIP-44 path
+};
+// Global registry for custom chains and overrides
+let CUSTOM_CHAINS = {};
+let CHAIN_OVERRIDES = {};
+/**
+ * Register a custom chain (new chain not in built-in list)
+ * @param chainId - Custom chain ID (e.g., 'custom-1', 'my-chain')
+ * @param config - Complete chain configuration
+ */
+function registerCustomChain(chainId, config) {
+    CUSTOM_CHAINS[chainId] = config;
+}
+/**
+ * Override a built-in chain configuration
+ * @param chainId - Built-in chain ID to override
+ * @param override - Partial configuration to override (only specify fields to change)
+ * @throws Error if chainId is not a built-in chain
+ */
+function overrideChain(chainId, override) {
+    const supportedChains = exports.SUPPORTED_CHAINS;
+    if (!supportedChains[chainId]) {
+        throw new Error(`Cannot override chain ${chainId} - not a built-in chain`);
+    }
+    CHAIN_OVERRIDES[chainId] = override;
+}
+/**
+ * Override multiple built-in chains at once
+ * @param overrides - Object containing multiple chain overrides
+ */
+function overrideChains(overrides) {
+    Object.entries(overrides).forEach(([chainId, override]) => {
+        overrideChain(chainId, override);
+    });
+}
+/**
+ * Get chain configuration with priority: Custom > Override > Built-in
+ * @param chainId - Chain ID to get configuration for
+ * @returns Chain configuration
+ * @throws Error if chain is not found
+ */
+function getChainConfig(chainId) {
+    // 1. Check custom chains first (highest priority)
+    if (CUSTOM_CHAINS[chainId]) {
+        return CUSTOM_CHAINS[chainId];
+    }
+    // 2. Check overrides
+    if (CHAIN_OVERRIDES[chainId]) {
+        const baseConfig = exports.SUPPORTED_CHAINS[chainId];
+        if (!baseConfig) {
+            throw new Error(`Chain ${chainId} not found`);
+        }
+        return { ...baseConfig, ...CHAIN_OVERRIDES[chainId] };
+    }
+    // 3. Check built-in chains
+    const builtInConfig = exports.SUPPORTED_CHAINS[chainId];
+    if (!builtInConfig) {
+        throw new Error(`Chain ${chainId} not found`);
+    }
+    return builtInConfig;
+}
+/**
+ * Setup chain configurations with overrides and custom chains
+ * @param options - Configuration options
+ */
+function setupChainConfigs(options) {
+    if (options.overrides) {
+        overrideChains(options.overrides);
+    }
+    if (options.customChains) {
+        Object.entries(options.customChains).forEach(([chainId, config]) => {
+            registerCustomChain(chainId, config);
+        });
+    }
+}
+/**
+ * Get all available chains (built-in + custom)
+ * @returns Object containing all chain configurations
+ */
+function getAllAvailableChains() {
+    return { ...exports.SUPPORTED_CHAINS, ...CUSTOM_CHAINS };
+}
+/**
+ * Clear all custom chains
+ */
+function clearCustomChains() {
+    CUSTOM_CHAINS = {};
+}
+/**
+ * Clear all chain overrides
+ */
+function clearOverrides() {
+    CHAIN_OVERRIDES = {};
+}
+/**
+ * Clear override for a specific chain
+ * @param chainId - Chain ID to clear override for
+ */
+function clearOverride(chainId) {
+    delete CHAIN_OVERRIDES[chainId];
+}
+/**
+ * Get all custom chains
+ * @returns Object containing custom chain configurations
+ */
+function getCustomChains() {
+    return { ...CUSTOM_CHAINS };
+}
+/**
+ * Get all chain overrides
+ * @returns Object containing chain override configurations
+ */
+function getOverrides() {
+    return { ...CHAIN_OVERRIDES };
+}

package/dist/config/constants.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Configuration constants for PWC Wallet SDK
+ */
+/**
+ * Configuration object for vanity wallet generation.
+ * Contains default settings and limits for generating wallets with specific address prefixes.
+ */
+export declare const VANITY_WALLET_CONFIG: {
+    /** Default prefix for vanity addresses (without '0x' for EVM chains) */
+    readonly DEFAULT_PREFIX: "aaa";
+    /** Maximum attempts for generating vanity wallet before giving up */
+    readonly DEFAULT_MAX_ATTEMPTS: 1000000;
+    /** Whether prefix matching should be case sensitive (false = ignore case) */
+    readonly DEFAULT_CASE_SENSITIVE: false;
+    /** Progress update interval in number of attempts (for progress callbacks) */
+    readonly PROGRESS_UPDATE_INTERVAL: 1000;
+    /** Non-blocking interval to allow event loop to breathe (prevents UI freezing) */
+    readonly NON_BLOCKING_INTERVAL: 10000;
+    /** Maximum prefix length allowed (for performance and security reasons) */
+    readonly MAX_PREFIX_LENGTH: 10;
+    /** Maximum attempts limit as a safety cap to prevent infinite loops */
+    readonly MAX_ATTEMPTS_LIMIT: 10000000;
+    /** Mobile-optimized prefix (much easier to find) */
+    readonly MOBILE_DEFAULT_PREFIX: "a";
+    /** Mobile-optimized max attempts (faster completion) */
+    readonly MOBILE_DEFAULT_MAX_ATTEMPTS: 50000;
+    /** Mobile-optimized progress update interval (more frequent updates) */
+    readonly MOBILE_PROGRESS_UPDATE_INTERVAL: 500;
+    /** Mobile-optimized non-blocking interval (more frequent yields) */
+    readonly MOBILE_NON_BLOCKING_INTERVAL: 1000;
+    /** Batch size for mobile processing (process multiple attempts in batches) */
+    readonly MOBILE_BATCH_SIZE: 100;
+    /** Mobile timeout in milliseconds (prevent infinite running) */
+    readonly MOBILE_TIMEOUT_MS: 30000;
+};
+/**
+ * Security configuration constants
+ */
+export declare const SECURITY_CONFIG: {
+    /** AES key size in bits */
+    readonly AES_KEY_SIZE: 256;
+    /** Salt length in bytes */
+    readonly SALT_LENGTH: 16;
+    /** IV length in bytes */
+    readonly IV_LENGTH: 12;
+    /** Minimum password length */
+    readonly MIN_PASSWORD_LENGTH: 8;
+    /** Maximum vault unlock attempts before lockout */
+    readonly MAX_UNLOCK_ATTEMPTS: 5;
+    /** Lockout duration in milliseconds */
+    readonly LOCKOUT_DURATION: 300000;
+};
+/**
+ * Get PBKDF2 iterations based on environment
+ * @returns Number of iterations (5000 for development, 10000 for production)
+ */
+export declare function getPBKDF2Iterations(): number;
+/**
+ * Network configuration constants
+ */
+export declare const NETWORK_CONFIG: {
+    /** Default timeout for RPC calls in milliseconds */
+    readonly RPC_TIMEOUT: 30000;
+    /** Retry attempts for failed RPC calls */
+    readonly RPC_RETRY_ATTEMPTS: 3;
+    /** Delay between retry attempts in milliseconds */
+    readonly RPC_RETRY_DELAY: 1000;
+    /** Maximum batch size for multi-transfer operations */
+    readonly MAX_BATCH_SIZE: 50;
+    /** Delay between batches in milliseconds */
+    readonly BATCH_DELAY: 500;
+};
+/**
+ * Cache configuration constants
+ */
+export declare const CACHE_CONFIG: {
+    /** Default cache TTL in milliseconds */
+    readonly DEFAULT_TTL: 30000;
+    /** Balance cache TTL in milliseconds */
+    readonly BALANCE_TTL: 60000;
+    /** Token info cache TTL in milliseconds */
+    readonly TOKEN_INFO_TTL: 300000;
+    /** Transaction cache TTL in milliseconds */
+    readonly TRANSACTION_TTL: 600000;
+    /** Maximum cache size in number of entries */
+    readonly MAX_CACHE_SIZE: 1000;
+};
+/**
+ * Validation configuration constants
+ */
+export declare const VALIDATION_CONFIG: {
+    /** Minimum address length */
+    readonly MIN_ADDRESS_LENGTH: 26;
+    /** Maximum address length */
+    readonly MAX_ADDRESS_LENGTH: 44;
+    /** Minimum amount for transfers */
+    readonly MIN_TRANSFER_AMOUNT: "0.000001";
+    /** Maximum amount for transfers (safety limit) */
+    readonly MAX_TRANSFER_AMOUNT: "1000000";
+    /** Maximum decimal places for amounts */
+    readonly MAX_DECIMAL_PLACES: 18;
+};