ton-provider-system 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1686 @@
+import { z } from 'zod';
+import { TonClient } from '@ton/ton';
+import { Address } from '@ton/core';
+
+/**
+ * Unified Provider System - Type Definitions
+ *
+ * Core types for the TON RPC provider management system.
+ * These types are used across all components of the provider system.
+ */
+/**
+ * Supported TON networks
+ */
+type Network = 'testnet' | 'mainnet';
+/**
+ * API version types supported by TON providers
+ * - v2: TON Center HTTP API v2 (JSON-RPC style) - most common
+ * - v4: TON API v4 (ton-community/ton-api-v4) - different format
+ */
+type ApiVersion = 'v2' | 'v3' | 'v4';
+/**
+ * Provider type identifier
+ */
+type ProviderType = 'chainstack' | 'quicknode' | 'toncenter' | 'orbs' | 'onfinality' | 'ankr' | 'getblock' | 'tatum' | 'tonhub' | 'custom';
+/**
+ * Provider endpoint configuration
+ */
+interface ProviderEndpoints {
+    /** API v2 endpoint URL (may contain {key} placeholder) */
+    v2?: string;
+    /** API v3 endpoint URL (may contain {key} placeholder) */
+    v3?: string;
+    /** API v4 endpoint URL */
+    v4?: string;
+    /** WebSocket endpoint URL */
+    ws?: string;
+}
+/**
+ * Single provider definition from rpc.json config
+ */
+interface ProviderConfig {
+    /** Human-readable provider name */
+    name: string;
+    /** Provider type for special handling */
+    type: ProviderType;
+    /** Network this provider serves */
+    network: Network;
+    /** Endpoint URLs */
+    endpoints: ProviderEndpoints;
+    /** Environment variable name for API key (replaces {key} in endpoints) */
+    keyEnvVar?: string;
+    /** Environment variable name for separate API key header */
+    apiKeyEnvVar?: string;
+    /** Requests per second limit */
+    rps: number;
+    /** Priority for selection (lower = higher priority) */
+    priority: number;
+    /** Whether this provider is enabled */
+    enabled: boolean;
+    /** Whether this provider requires dynamic endpoint discovery (e.g., Orbs) */
+    isDynamic?: boolean;
+    /** Optional description or notes */
+    description?: string;
+}
+/**
+ * Default provider order per network
+ */
+interface NetworkDefaults {
+    testnet: string[];
+    mainnet: string[];
+}
+/**
+ * Complete rpc.json configuration file structure
+ */
+interface RpcConfig {
+    /** JSON Schema reference (optional) */
+    $schema?: string;
+    /** Config version */
+    version: string;
+    /** Provider definitions keyed by unique ID */
+    providers: Record<string, ProviderConfig>;
+    /** Default provider order per network */
+    defaults: NetworkDefaults;
+}
+/**
+ * Provider health status
+ */
+type ProviderStatus = 'available' | 'degraded' | 'offline' | 'stale' | 'untested' | 'testing';
+/**
+ * Resolved provider with actual endpoint URLs (env vars replaced)
+ */
+interface ResolvedProvider {
+    /** Unique provider ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Provider type */
+    type: ProviderType;
+    /** Network */
+    network: Network;
+    /** Resolved v2 endpoint URL (ready to use) */
+    endpointV2: string;
+    /** Resolved v3 endpoint URL (if available) */
+    endpointV3?: string;
+    /** Resolved v4 endpoint URL (if available) */
+    endpointV4?: string;
+    /** Resolved WebSocket URL (if available) */
+    endpointWs?: string;
+    /** API key (if separate from URL) */
+    apiKey?: string;
+    /** Requests per second limit */
+    rps: number;
+    /** Priority (lower = higher priority) */
+    priority: number;
+    /** Whether dynamic discovery is needed */
+    isDynamic: boolean;
+}
+/**
+ * Provider health check result
+ */
+interface ProviderHealthResult {
+    /** Provider ID */
+    id: string;
+    /** Network */
+    network: Network;
+    /** Test success */
+    success: boolean;
+    /** Current status */
+    status: ProviderStatus;
+    /** Latency in milliseconds */
+    latencyMs: number | null;
+    /** Current masterchain seqno (block height) */
+    seqno: number | null;
+    /** Blocks behind the best provider (0 = up to date) */
+    blocksBehind: number;
+    /** Timestamp of last test */
+    lastTested: Date | null;
+    /** Cached endpoint URL */
+    cachedEndpoint?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Provider state for runtime tracking
+ */
+interface ProviderState {
+    /** Provider ID */
+    id: string;
+    /** Current health result */
+    health: ProviderHealthResult;
+    /** Current rate limit state */
+    rateLimit: RateLimitState;
+}
+/**
+ * Rate limit configuration
+ */
+interface RateLimitConfig {
+    /** Requests per second */
+    rps: number;
+    /** Burst size (max tokens) */
+    burstSize: number;
+    /** Minimum delay between requests in ms */
+    minDelayMs: number;
+    /** Backoff multiplier on 429 errors */
+    backoffMultiplier: number;
+    /** Maximum backoff delay in ms */
+    maxBackoffMs: number;
+}
+/**
+ * Rate limit state for a provider
+ */
+interface RateLimitState {
+    /** Available tokens */
+    tokens: number;
+    /** Last refill timestamp */
+    lastRefill: number;
+    /** Current backoff delay (0 = no backoff) */
+    currentBackoff: number;
+    /** Consecutive error count */
+    consecutiveErrors: number;
+    /** Whether a request is currently being processed */
+    processing: boolean;
+    /** Pending request resolvers */
+    queueLength: number;
+}
+/**
+ * Provider manager configuration options
+ */
+interface ProviderManagerOptions {
+    /** @deprecated Unused - config is loaded from provider_system/rpc.json */
+    configPath?: string;
+    /** Adapter type: 'node' for Node.js, 'browser' for browser */
+    adapter?: 'node' | 'browser';
+    /** Whether to auto-initialize on first use */
+    autoInit?: boolean;
+    /** Request timeout in ms (default: 10000) */
+    requestTimeoutMs?: number;
+    /** Health check interval in ms (0 = disabled) */
+    healthCheckIntervalMs?: number;
+    /** Maximum blocks behind before marking as stale */
+    maxBlocksBehind?: number;
+    /** Custom logger (default: console) */
+    logger?: Logger;
+}
+/**
+ * Logger interface for custom logging
+ */
+interface Logger {
+    debug: (message: string, data?: Record<string, unknown>) => void;
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+}
+/**
+ * Provider manager state
+ */
+interface ProviderManagerState {
+    /** Current network */
+    network: Network | null;
+    /** Whether initialized */
+    initialized: boolean;
+    /** Whether testing is in progress */
+    isTesting: boolean;
+    /** All provider states */
+    providers: Map<string, ProviderState>;
+    /** Best provider ID per network */
+    bestProviderByNetwork: Map<Network, string>;
+    /** Manually selected provider ID (null = auto) */
+    selectedProviderId: string | null;
+    /** Whether auto-selection is enabled */
+    autoSelect: boolean;
+    /** Custom endpoint override */
+    customEndpoint: string | null;
+}
+/**
+ * State change listener
+ */
+type StateListener = (state: ProviderManagerState) => void;
+/**
+ * TON API getMasterchainInfo response
+ */
+interface MasterchainInfo {
+    /** Current masterchain block seqno */
+    last: {
+        seqno: number;
+        workchain: number;
+        shard: string;
+        root_hash: string;
+        file_hash: string;
+    };
+    /** State root hash */
+    state_root_hash: string;
+    /** Init block */
+    init: {
+        workchain: number;
+        seqno: number;
+        root_hash: string;
+        file_hash: string;
+    };
+}
+/**
+ * Generic TON API response wrapper
+ */
+interface TonApiResponse<T = unknown> {
+    ok: boolean;
+    result?: T;
+    error?: string;
+    code?: number;
+}
+/**
+ * Timeout error class
+ */
+declare class TimeoutError extends Error {
+    readonly operation: string;
+    readonly timeoutMs: number;
+    constructor(operation: string, timeoutMs: number, message?: string);
+}
+/**
+ * Provider error class
+ */
+declare class ProviderError extends Error {
+    readonly providerId: string;
+    readonly operation: string;
+    readonly cause?: Error | undefined;
+    constructor(providerId: string, operation: string, message: string, cause?: Error | undefined);
+}
+/**
+ * Rate limit error class
+ */
+declare class RateLimitError extends Error {
+    readonly providerId: string;
+    readonly retryAfterMs?: number | undefined;
+    constructor(providerId: string, retryAfterMs?: number | undefined);
+}
+/**
+ * Configuration error class
+ */
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Unified Provider System - Configuration Schema
+ *
+ * Zod schema for validating rpc.json configuration files.
+ * Provides type-safe parsing and detailed error messages.
+ */
+
+/**
+ * Network schema
+ */
+declare const NetworkSchema: z.ZodEnum<["testnet", "mainnet"]>;
+/**
+ * Provider type schema
+ */
+declare const ProviderTypeSchema: z.ZodEnum<["chainstack", "quicknode", "toncenter", "orbs", "onfinality", "ankr", "getblock", "tatum", "tonhub", "custom"]>;
+/**
+ * API version schema
+ */
+declare const ApiVersionSchema: z.ZodEnum<["v2", "v3", "v4"]>;
+/**
+ * Single provider configuration schema
+ */
+declare const ProviderConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<["chainstack", "quicknode", "toncenter", "orbs", "onfinality", "ankr", "getblock", "tatum", "tonhub", "custom"]>;
+    network: z.ZodEnum<["testnet", "mainnet"]>;
+    endpoints: z.ZodEffects<z.ZodObject<{
+        v2: z.ZodOptional<z.ZodString>;
+        v3: z.ZodOptional<z.ZodString>;
+        v4: z.ZodOptional<z.ZodString>;
+        ws: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        v2?: string | undefined;
+        v3?: string | undefined;
+        v4?: string | undefined;
+        ws?: string | undefined;
+    }, {
+        v2?: string | undefined;
+        v3?: string | undefined;
+        v4?: string | undefined;
+        ws?: string | undefined;
+    }>, {
+        v2?: string | undefined;
+        v3?: string | undefined;
+        v4?: string | undefined;
+        ws?: string | undefined;
+    }, {
+        v2?: string | undefined;
+        v3?: string | undefined;
+        v4?: string | undefined;
+        ws?: string | undefined;
+    }>;
+    keyEnvVar: z.ZodOptional<z.ZodString>;
+    apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+    rps: z.ZodDefault<z.ZodNumber>;
+    priority: z.ZodDefault<z.ZodNumber>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    isDynamic: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "chainstack" | "quicknode" | "toncenter" | "orbs" | "onfinality" | "ankr" | "getblock" | "tatum" | "tonhub" | "custom";
+    name: string;
+    network: "testnet" | "mainnet";
+    endpoints: {
+        v2?: string | undefined;
+        v3?: string | undefined;
+        v4?: string | undefined;
+        ws?: string | undefined;
+    };
+    rps: number;
+    priority: number;
+    enabled: boolean;
+    isDynamic: boolean;
+    keyEnvVar?: string | undefined;
+    apiKeyEnvVar?: string | undefined;
+    description?: string | undefined;
+}, {
+    type: "chainstack" | "quicknode" | "toncenter" | "orbs" | "onfinality" | "ankr" | "getblock" | "tatum" | "tonhub" | "custom";
+    name: string;
+    network: "testnet" | "mainnet";
+    endpoints: {
+        v2?: string | undefined;
+        v3?: string | undefined;
+        v4?: string | undefined;
+        ws?: string | undefined;
+    };
+    keyEnvVar?: string | undefined;
+    apiKeyEnvVar?: string | undefined;
+    rps?: number | undefined;
+    priority?: number | undefined;
+    enabled?: boolean | undefined;
+    isDynamic?: boolean | undefined;
+    description?: string | undefined;
+}>;
+/**
+ * Complete RPC configuration schema
+ */
+declare const RpcConfigSchema: z.ZodEffects<z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    providers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["chainstack", "quicknode", "toncenter", "orbs", "onfinality", "ankr", "getblock", "tatum", "tonhub", "custom"]>;
+        network: z.ZodEnum<["testnet", "mainnet"]>;
+        endpoints: z.ZodEffects<z.ZodObject<{
+            v2: z.ZodOptional<z.ZodString>;
+            v3: z.ZodOptional<z.ZodString>;
+            v4: z.ZodOptional<z.ZodString>;
+            ws: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        }, {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        }>, {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        }, {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        }>;
+        keyEnvVar: z.ZodOptional<z.ZodString>;
+        apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+        rps: z.ZodDefault<z.ZodNumber>;
+        priority: z.ZodDefault<z.ZodNumber>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        isDynamic: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "chainstack" | "quicknode" | "toncenter" | "orbs" | "onfinality" | "ankr" | "getblock" | "tatum" | "tonhub" | "custom";
+        name: string;
+        network: "testnet" | "mainnet";
+        endpoints: {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        };
+        rps: number;
+        priority: number;
+        enabled: boolean;
+        isDynamic: boolean;
+        keyEnvVar?: string | undefined;
+        apiKeyEnvVar?: string | undefined;
+        description?: string | undefined;
+    }, {
+        type: "chainstack" | "quicknode" | "toncenter" | "orbs" | "onfinality" | "ankr" | "getblock" | "tatum" | "tonhub" | "custom";
+        name: string;
+        network: "testnet" | "mainnet";
+        endpoints: {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        };
+        keyEnvVar?: string | undefined;
+        apiKeyEnvVar?: string | undefined;
+        rps?: number | undefined;
+        priority?: number | undefined;
+        enabled?: boolean | undefined;
+        isDynamic?: boolean | undefined;
+        description?: string | undefined;
+    }>>;
+    defaults: z.ZodObject<{
+        testnet: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        mainnet: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        testnet: string[];
+        mainnet: string[];
+    }, {
+        testnet?: string[] | undefined;
+        mainnet?: string[] | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    providers: Record<string, {
+        type: "chainstack" | "quicknode" | "toncenter" | "orbs" | "onfinality" | "ankr" | "getblock" | "tatum" | "tonhub" | "custom";
+        name: string;
+        network: "testnet" | "mainnet";
+        endpoints: {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        };
+        rps: number;
+        priority: number;
+        enabled: boolean;
+        isDynamic: boolean;
+        keyEnvVar?: string | undefined;
+        apiKeyEnvVar?: string | undefined;
+        description?: string | undefined;
+    }>;
+    defaults: {
+        testnet: string[];
+        mainnet: string[];
+    };
+    $schema?: string | undefined;
+}, {
+    providers: Record<string, {
+        type: "chainstack" | "quicknode" | "toncenter" | "orbs" | "onfinality" | "ankr" | "getblock" | "tatum" | "tonhub" | "custom";
+        name: string;
+        network: "testnet" | "mainnet";
+        endpoints: {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        };
+        keyEnvVar?: string | undefined;
+        apiKeyEnvVar?: string | undefined;
+        rps?: number | undefined;
+        priority?: number | undefined;
+        enabled?: boolean | undefined;
+        isDynamic?: boolean | undefined;
+        description?: string | undefined;
+    }>;
+    defaults: {
+        testnet?: string[] | undefined;
+        mainnet?: string[] | undefined;
+    };
+    $schema?: string | undefined;
+    version?: string | undefined;
+}>, {
+    version: string;
+    providers: Record<string, {
+        type: "chainstack" | "quicknode" | "toncenter" | "orbs" | "onfinality" | "ankr" | "getblock" | "tatum" | "tonhub" | "custom";
+        name: string;
+        network: "testnet" | "mainnet";
+        endpoints: {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        };
+        rps: number;
+        priority: number;
+        enabled: boolean;
+        isDynamic: boolean;
+        keyEnvVar?: string | undefined;
+        apiKeyEnvVar?: string | undefined;
+        description?: string | undefined;
+    }>;
+    defaults: {
+        testnet: string[];
+        mainnet: string[];
+    };
+    $schema?: string | undefined;
+}, {
+    providers: Record<string, {
+        type: "chainstack" | "quicknode" | "toncenter" | "orbs" | "onfinality" | "ankr" | "getblock" | "tatum" | "tonhub" | "custom";
+        name: string;
+        network: "testnet" | "mainnet";
+        endpoints: {
+            v2?: string | undefined;
+            v3?: string | undefined;
+            v4?: string | undefined;
+            ws?: string | undefined;
+        };
+        keyEnvVar?: string | undefined;
+        apiKeyEnvVar?: string | undefined;
+        rps?: number | undefined;
+        priority?: number | undefined;
+        enabled?: boolean | undefined;
+        isDynamic?: boolean | undefined;
+        description?: string | undefined;
+    }>;
+    defaults: {
+        testnet?: string[] | undefined;
+        mainnet?: string[] | undefined;
+    };
+    $schema?: string | undefined;
+    version?: string | undefined;
+}>;
+/**
+ * Parse and validate RPC configuration
+ * @param data - Raw configuration data
+ * @returns Validated RpcConfig
+ * @throws ConfigError on validation failure
+ */
+declare function parseRpcConfig(data: unknown): RpcConfig;
+/**
+ * Validate a single provider configuration
+ * @param id - Provider ID
+ * @param data - Provider configuration data
+ * @returns Validated ProviderConfig
+ */
+declare function parseProviderConfig(id: string, data: unknown): ProviderConfig;
+/**
+ * Create a minimal valid RpcConfig for testing
+ */
+declare function createEmptyConfig(): RpcConfig;
+/**
+ * Merge two RPC configurations (useful for defaults + user config)
+ * @param base - Base configuration
+ * @param override - Override configuration
+ * @returns Merged configuration
+ */
+declare function mergeConfigs(base: RpcConfig, override: Partial<RpcConfig>): RpcConfig;
+/**
+ * Type guard for Network
+ */
+declare function isNetwork(value: unknown): value is Network;
+/**
+ * Type guard for ProviderType
+ */
+declare function isProviderType(value: unknown): value is ProviderType;
+/**
+ * Type guard for ApiVersion
+ */
+declare function isApiVersion(value: unknown): value is ApiVersion;
+
+/**
+ * Unified Provider System - Configuration Parser
+ *
+ * Loads provider definitions from provider_system/rpc.json.
+ * Resolves API keys from environment variables (.env).
+ * Supports both Node.js (file system) and browser (fetch/embedded) environments.
+ */
+
+/**
+ * Get environment variable value.
+ * Works in both Node.js and browser environments.
+ */
+declare function getEnvVar(name: string): string | undefined;
+/**
+ * Resolve {key} placeholder in URL with environment variable value
+ */
+declare function resolveKeyPlaceholder(url: string, keyEnvVar?: string): string;
+/**
+ * Resolve all placeholders in endpoint URLs
+ */
+declare function resolveEndpoints(endpoints: ProviderConfig['endpoints'], keyEnvVar?: string): {
+    v2?: string;
+    v3?: string;
+    v4?: string;
+    ws?: string;
+};
+/**
+ * Convert a ProviderConfig to a ResolvedProvider with actual URLs
+ */
+declare function resolveProvider(id: string, config: ProviderConfig): ResolvedProvider | null;
+/**
+ * Resolve all providers from config
+ */
+declare function resolveAllProviders(config: RpcConfig): ResolvedProvider[];
+/**
+ * Get providers for a specific network
+ */
+declare function getProvidersForNetwork(config: RpcConfig, network: Network): ResolvedProvider[];
+/**
+ * Get providers in default order for a network
+ */
+declare function getDefaultProvidersForNetwork(config: RpcConfig, network: Network): ResolvedProvider[];
+/**
+ * Load RPC config from the built-in rpc.json file (Node.js)
+ */
+declare function loadBuiltinConfig(): Promise<RpcConfig>;
+/**
+ * Load RPC config from a URL (browser-compatible)
+ */
+declare function loadConfigFromUrl(url: string): Promise<RpcConfig>;
+/**
+ * Load RPC config from raw JSON data
+ */
+declare function loadConfigFromData(data: unknown): RpcConfig;
+/**
+ * Auto-detect and load config.
+ * - Browser: checks for embedded __RPC_CONFIG__ or fetches from URL
+ * - Node.js: loads from provider_system/rpc.json
+ */
+declare function loadConfig(): Promise<RpcConfig>;
+/**
+ * Minimal default providers when rpc.json is not available.
+ * These are free public endpoints that don't require API keys.
+ */
+declare const DEFAULT_PROVIDERS: Record<string, ProviderConfig>;
+/**
+ * Create a default config with minimal providers (no API keys required)
+ */
+declare function createDefaultConfig(): RpcConfig;
+/**
+ * Merge user config with defaults
+ */
+declare function mergeWithDefaults(config: RpcConfig): RpcConfig;
+
+/**
+ * Unified Provider System - Provider Registry
+ *
+ * Manages provider definitions, filtering, and lookup.
+ * Acts as a central repository for all available providers.
+ */
+
+/**
+ * Provider Registry
+ *
+ * Manages all provider definitions and provides lookup/filtering capabilities.
+ */
+declare class ProviderRegistry {
+    private config;
+    private providers;
+    private logger;
+    constructor(config?: RpcConfig, logger?: Logger);
+    /**
+     * Load and resolve all providers from config
+     */
+    private loadProviders;
+    /**
+     * Get a provider by ID
+     */
+    getProvider(id: string): ResolvedProvider | undefined;
+    /**
+     * Get all providers
+     */
+    getAllProviders(): ResolvedProvider[];
+    /**
+     * Get providers for a specific network
+     */
+    getProvidersForNetwork(network: Network): ResolvedProvider[];
+    /**
+     * Get providers in default order for a network
+     */
+    getDefaultOrderForNetwork(network: Network): ResolvedProvider[];
+    /**
+     * Get providers by type
+     */
+    getProvidersByType(type: ProviderType): ResolvedProvider[];
+    /**
+     * Get providers that have v2 API endpoints
+     */
+    getV2Providers(): ResolvedProvider[];
+    /**
+     * Get v2 providers for a specific network
+     */
+    getV2ProvidersForNetwork(network: Network): ResolvedProvider[];
+    /**
+     * Check if a provider exists
+     */
+    hasProvider(id: string): boolean;
+    /**
+     * Get provider count
+     */
+    get size(): number;
+    /**
+     * Get the underlying config
+     */
+    getConfig(): RpcConfig;
+    /**
+     * Update config and reload providers
+     */
+    updateConfig(config: RpcConfig): void;
+    /**
+     * Add or update a provider at runtime
+     */
+    setProvider(id: string, provider: ResolvedProvider): void;
+    /**
+     * Remove a provider
+     */
+    removeProvider(id: string): boolean;
+    /**
+     * Get provider IDs
+     */
+    getProviderIds(): string[];
+    /**
+     * Get network default provider IDs
+     */
+    getDefaultProviderIds(network: Network): string[];
+    /**
+     * Find provider by endpoint URL (useful for error reporting)
+     */
+    findProviderByEndpoint(endpoint: string): ResolvedProvider | undefined;
+}
+/**
+ * Create a registry by loading from provider_system/rpc.json
+ */
+declare function createRegistry(logger?: Logger): Promise<ProviderRegistry>;
+/**
+ * @deprecated Use createRegistry() instead
+ */
+declare function createRegistryFromFile(_filePath?: string, logger?: Logger): Promise<ProviderRegistry>;
+/**
+ * Create a registry with default providers only
+ */
+declare function createDefaultRegistry(logger?: Logger): ProviderRegistry;
+/**
+ * Create a registry from raw config data
+ */
+declare function createRegistryFromData(data: RpcConfig, logger?: Logger): ProviderRegistry;
+
+/**
+ * Unified Provider System - Health Checker
+ *
+ * Tests provider connectivity, measures latency, and compares block heights.
+ * Identifies stale, degraded, or offline providers.
+ */
+
+interface HealthCheckConfig {
+    /** Request timeout in milliseconds */
+    timeoutMs: number;
+    /** Maximum blocks behind before marking as stale */
+    maxBlocksBehind: number;
+    /** Latency threshold (ms) for degraded status */
+    degradedLatencyMs: number;
+}
+/**
+ * Health Checker
+ *
+ * Tests provider health by calling getMasterchainInfo and measuring
+ * latency and block height.
+ */
+declare class HealthChecker {
+    private config;
+    private logger;
+    private results;
+    private highestSeqno;
+    constructor(config?: Partial<HealthCheckConfig>, logger?: Logger);
+    /**
+     * Test a single provider's health
+     */
+    testProvider(provider: ResolvedProvider): Promise<ProviderHealthResult>;
+    /**
+     * Test multiple providers in parallel with staggered batches
+     */
+    testProviders(providers: ResolvedProvider[], batchSize?: number, batchDelayMs?: number): Promise<ProviderHealthResult[]>;
+    /**
+     * Get the last health result for a provider
+     */
+    getResult(providerId: string, network: Network): ProviderHealthResult | undefined;
+    /**
+     * Get all results for a network
+     */
+    getResultsForNetwork(network: Network): ProviderHealthResult[];
+    /**
+     * Get available providers for a network (status = available or degraded)
+     */
+    getAvailableProviders(network: Network): ProviderHealthResult[];
+    /**
+     * Get the best provider for a network (lowest latency among available)
+     */
+    getBestProvider(network: Network): ProviderHealthResult | undefined;
+    /**
+     * Get highest known seqno for a network
+     */
+    getHighestSeqno(network: Network): number;
+    /**
+     * Clear all results
+     */
+    clearResults(): void;
+    /**
+     * Mark a provider as degraded (e.g., on 429 error)
+     */
+    markDegraded(providerId: string, network: Network, error?: string): void;
+    /**
+     * Mark a provider as offline
+     */
+    markOffline(providerId: string, network: Network, error?: string): void;
+    private getResultKey;
+    /**
+     * Get endpoint URL for a provider (handles dynamic providers like Orbs)
+     */
+    private getEndpoint;
+    /**
+     * Call getMasterchainInfo API
+     */
+    private callGetMasterchainInfo;
+    private sleep;
+}
+/**
+ * Create a health checker with default configuration
+ */
+declare function createHealthChecker(config?: Partial<HealthCheckConfig>, logger?: Logger): HealthChecker;
+
+/**
+ * Unified Provider System - Rate Limiter
+ *
+ * Token bucket rate limiter with per-provider tracking.
+ * Implements request queuing, serialization, and exponential backoff.
+ */
+
+/**
+ * Default rate limit config (conservative for public endpoints)
+ */
+declare const DEFAULT_RATE_LIMIT: RateLimitConfig;
+/**
+ * Chainstack free plan limits (25 RPS)
+ */
+declare const CHAINSTACK_RATE_LIMIT: RateLimitConfig;
+/**
+ * QuickNode free plan limits (10 RPS)
+ */
+declare const QUICKNODE_RATE_LIMIT: RateLimitConfig;
+/**
+ * Orbs TON Access (decentralized, no hard limit)
+ */
+declare const ORBS_RATE_LIMIT: RateLimitConfig;
+/**
+ * Get rate limit config by provider type
+ */
+declare function getRateLimitForType(type: string): RateLimitConfig;
+/**
+ * Token Bucket Rate Limiter
+ *
+ * Implements a token bucket algorithm with:
+ * - Configurable RPS and burst size
+ * - Request queuing (FIFO)
+ * - Serialized request processing
+ * - Exponential backoff on 429 errors
+ */
+declare class TokenBucketRateLimiter {
+    private config;
+    private tokens;
+    private lastRefill;
+    private currentBackoff;
+    private consecutiveErrors;
+    private requestQueue;
+    private processing;
+    private logger;
+    constructor(config?: Partial<RateLimitConfig>, logger?: Logger);
+    /**
+     * Get current state
+     */
+    getState(): RateLimitState;
+    /**
+     * Acquire a token (wait if necessary)
+     *
+     * @param timeoutMs - Maximum time to wait for a token (default: 60s)
+     * @returns true if token acquired, false if timeout
+     */
+    acquire(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Release a token (call on request completion)
+     */
+    release(): void;
+    /**
+     * Report a successful request (resets backoff)
+     */
+    reportSuccess(): void;
+    /**
+     * Report a rate limit error (applies backoff)
+     */
+    reportRateLimitError(): void;
+    /**
+     * Report a general error
+     */
+    reportError(): void;
+    /**
+     * Reset rate limiter state
+     */
+    reset(): void;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<RateLimitConfig>): void;
+    /**
+     * Refill tokens based on time elapsed
+     */
+    private refill;
+}
+/**
+ * Provider Rate Limiter Manager
+ *
+ * Manages rate limiters for multiple providers.
+ */
+declare class RateLimiterManager {
+    private limiters;
+    private configs;
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Get or create rate limiter for a provider
+     */
+    getLimiter(providerId: string, config?: Partial<RateLimitConfig>): TokenBucketRateLimiter;
+    /**
+     * Set rate limit config for a provider
+     */
+    setConfig(providerId: string, config: RateLimitConfig): void;
+    /**
+     * Get rate limit state for a provider
+     */
+    getState(providerId: string): RateLimitState | null;
+    /**
+     * Acquire token for a provider
+     */
+    acquire(providerId: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Report success for a provider
+     */
+    reportSuccess(providerId: string): void;
+    /**
+     * Report rate limit error for a provider
+     */
+    reportRateLimitError(providerId: string): void;
+    /**
+     * Report general error for a provider
+     */
+    reportError(providerId: string): void;
+    /**
+     * Reset a provider's rate limiter
+     */
+    reset(providerId: string): void;
+    /**
+     * Reset all rate limiters
+     */
+    resetAll(): void;
+    /**
+     * Remove a provider's rate limiter
+     */
+    remove(providerId: string): void;
+    /**
+     * Clear all limiters
+     */
+    clear(): void;
+}
+/**
+ * Create a rate limiter with RPS-based config
+ */
+declare function createRateLimiter(rps: number, logger?: Logger): TokenBucketRateLimiter;
+/**
+ * Create a rate limiter manager
+ */
+declare function createRateLimiterManager(logger?: Logger): RateLimiterManager;
+
+/**
+ * Unified Provider System - Provider Selector
+ *
+ * Selects the best available provider based on health, latency, and priority.
+ * Supports auto-selection, manual override, and custom endpoint.
+ */
+
+interface SelectionConfig {
+    /** Prefer providers with latency below this threshold (ms) */
+    preferredLatencyMs: number;
+    /** Weight for latency in scoring (0-1) */
+    latencyWeight: number;
+    /** Weight for priority in scoring (0-1) */
+    priorityWeight: number;
+    /** Weight for block freshness in scoring (0-1) */
+    freshnessWeight: number;
+    /** Minimum acceptable provider status */
+    minStatus: ProviderStatus[];
+}
+/**
+ * Provider Selector
+ *
+ * Selects the best provider based on multiple criteria:
+ * - Health status (available > degraded > offline)
+ * - Latency (lower is better)
+ * - Priority (from config, lower is higher priority)
+ * - Block freshness (fewer blocks behind is better)
+ */
+declare class ProviderSelector {
+    private registry;
+    private healthChecker;
+    private config;
+    private logger;
+    private selectedProviderId;
+    private autoSelect;
+    private customEndpoint;
+    private bestProviderByNetwork;
+    constructor(registry: ProviderRegistry, healthChecker: HealthChecker, config?: Partial<SelectionConfig>, logger?: Logger);
+    /**
+     * Get the best provider for a network
+     */
+    getBestProvider(network: Network): ResolvedProvider | null;
+    /**
+     * Find the best provider for a network (recalculates)
+     */
+    findBestProvider(network: Network): ResolvedProvider | null;
+    /**
+     * Get all available providers for a network, sorted by score
+     */
+    getAvailableProviders(network: Network): ResolvedProvider[];
+    /**
+     * Get the next best provider (for failover)
+     */
+    getNextProvider(network: Network, excludeIds: string[]): ResolvedProvider | null;
+    /**
+     * Calculate a score for a provider (higher is better)
+     */
+    private scoreProvider;
+    private getStatusScore;
+    private getLatencyScore;
+    private getPriorityScore;
+    private getFreshnessScore;
+    /**
+     * Set manual provider selection
+     */
+    setSelectedProvider(providerId: string | null): void;
+    /**
+     * Get currently selected provider ID
+     */
+    getSelectedProviderId(): string | null;
+    /**
+     * Enable/disable auto-selection
+     */
+    setAutoSelect(enabled: boolean): void;
+    /**
+     * Check if auto-selection is enabled
+     */
+    isAutoSelectEnabled(): boolean;
+    /**
+     * Set custom endpoint override
+     */
+    setCustomEndpoint(endpoint: string | null): void;
+    /**
+     * Get custom endpoint
+     */
+    getCustomEndpoint(): string | null;
+    /**
+     * Check if using custom endpoint
+     */
+    isUsingCustomEndpoint(): boolean;
+    /**
+     * Clear cached best providers (forces recalculation)
+     */
+    clearCache(): void;
+    /**
+     * Update best provider after health check
+     */
+    updateBestProvider(network: Network): void;
+    /**
+     * Handle provider failure (switch to next best)
+     */
+    handleProviderFailure(providerId: string, network: Network): ResolvedProvider | null;
+    /**
+     * Get active provider info
+     */
+    getActiveProviderInfo(network: Network): {
+        id: string;
+        name: string;
+        isCustom: boolean;
+    } | null;
+    /**
+     * Create a pseudo-provider for custom endpoint
+     */
+    private createCustomProvider;
+}
+/**
+ * Create a provider selector
+ */
+declare function createSelector(registry: ProviderRegistry, healthChecker: HealthChecker, config?: Partial<SelectionConfig>, logger?: Logger): ProviderSelector;
+
+/**
+ * Unified Provider System - Provider Manager
+ *
+ * Main entry point for the provider system.
+ * Coordinates registry, health checker, rate limiter, and selector.
+ */
+
+/**
+ * Provider Manager
+ *
+ * Main entry point for the unified provider system.
+ * Manages providers, health checks, rate limiting, and selection.
+ *
+ * Usage:
+ * ```typescript
+ * // Singleton pattern (Node.js)
+ * const pm = ProviderManager.getInstance();
+ * await pm.init('testnet');
+ * const endpoint = await pm.getEndpoint();
+ *
+ * // Instance pattern (Browser/React)
+ * const pm = new ProviderManager({ adapter: 'browser' });
+ * await pm.init(network);
+ * ```
+ */
+declare class ProviderManager {
+    private static instance;
+    private registry;
+    private healthChecker;
+    private rateLimiter;
+    private selector;
+    private options;
+    private network;
+    private initialized;
+    private isTesting;
+    private healthCheckInterval;
+    private listeners;
+    constructor(options?: ProviderManagerOptions);
+    /**
+     * Get singleton instance (recommended for Node.js)
+     */
+    static getInstance(options?: ProviderManagerOptions): ProviderManager;
+    /**
+     * Reset singleton instance (for testing)
+     */
+    static resetInstance(): void;
+    /**
+     * Initialize the provider manager
+     *
+     * @param network - Network to initialize for
+     * @param testProviders - Whether to test providers immediately (default: true)
+     */
+    init(network: Network, testProviders?: boolean): Promise<void>;
+    /**
+     * Check if manager is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Destroy the manager (cleanup)
+     */
+    destroy(): void;
+    /**
+     * Test all providers for current network
+     */
+    testAllProviders(): Promise<ProviderHealthResult[]>;
+    /**
+     * Test a specific provider
+     */
+    testProvider(providerId: string): Promise<ProviderHealthResult | null>;
+    /**
+     * Check if testing is in progress
+     */
+    isTestingProviders(): boolean;
+    /**
+     * Get endpoint URL for current network
+     *
+     * Handles: custom endpoint > manual selection > auto-selection > fallback
+     */
+    getEndpoint(): Promise<string>;
+    /**
+     * Get endpoint with rate limiting
+     *
+     * Waits for rate limit token before returning endpoint.
+     */
+    getEndpointWithRateLimit(timeoutMs?: number): Promise<string>;
+    /**
+     * Get current active provider
+     */
+    getActiveProvider(): ResolvedProvider | null;
+    /**
+     * Get active provider info
+     */
+    getActiveProviderInfo(): {
+        id: string;
+        name: string;
+        isCustom: boolean;
+    } | null;
+    /**
+     * Report a successful request
+     */
+    reportSuccess(): void;
+    /**
+     * Report an error (triggers provider switch if needed)
+     */
+    reportError(error: Error | string): void;
+    /**
+     * Set manual provider selection
+     */
+    setSelectedProvider(providerId: string | null): void;
+    /**
+     * Get selected provider ID
+     */
+    getSelectedProviderId(): string | null;
+    /**
+     * Set auto-select mode
+     */
+    setAutoSelect(enabled: boolean): void;
+    /**
+     * Check if auto-select is enabled
+     */
+    isAutoSelectEnabled(): boolean;
+    /**
+     * Set custom endpoint override
+     */
+    setCustomEndpoint(endpoint: string | null): void;
+    /**
+     * Get custom endpoint
+     */
+    getCustomEndpoint(): string | null;
+    /**
+     * Check if using custom endpoint
+     */
+    isUsingCustomEndpoint(): boolean;
+    /**
+     * Get current network
+     */
+    getNetwork(): Network | null;
+    /**
+     * Get all providers for current network
+     */
+    getProviders(): ResolvedProvider[];
+    /**
+     * Get provider health results for current network
+     */
+    getProviderHealthResults(): ProviderHealthResult[];
+    /**
+     * Get registry (for advanced usage)
+     */
+    getRegistry(): ProviderRegistry | null;
+    /**
+     * Get health checker (for advanced usage)
+     */
+    getHealthChecker(): HealthChecker | null;
+    /**
+     * Get rate limiter manager (for advanced usage)
+     */
+    getRateLimiter(): RateLimiterManager | null;
+    /**
+     * Get current state (for UI)
+     */
+    getState(): ProviderManagerState;
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(listener: StateListener): () => void;
+    /**
+     * Notify all listeners
+     */
+    private notifyListeners;
+    private ensureInitialized;
+    private getFallbackEndpoint;
+    private startHealthCheckInterval;
+    private stopHealthCheckInterval;
+}
+/**
+ * Create a new ProviderManager instance
+ */
+declare function createProviderManager(options?: ProviderManagerOptions): ProviderManager;
+/**
+ * Get singleton ProviderManager instance
+ */
+declare function getProviderManager(options?: ProviderManagerOptions): ProviderManager;
+
+/**
+ * Unified Provider System - Node.js Adapter
+ *
+ * Provides TonClient integration for Node.js environments.
+ * Handles client caching and endpoint changes.
+ */
+
+/**
+ * Node.js Adapter for Provider System
+ *
+ * Provides TonClient and direct REST API access for Node.js environments.
+ */
+declare class NodeAdapter {
+    private manager;
+    private logger;
+    constructor(manager: ProviderManager, logger?: Logger);
+    /**
+     * Get TonClient instance
+     *
+     * Creates a new client if endpoint changed, otherwise returns cached.
+     */
+    getClient(): Promise<TonClient>;
+    /**
+     * Reset client cache (forces new client creation)
+     */
+    resetClient(): void;
+    /**
+     * Get cached client info (for debugging)
+     */
+    getClientInfo(): {
+        endpoint: string;
+        network: Network;
+        age: number;
+    } | null;
+    /**
+     * Get address state via REST API
+     */
+    getAddressState(address: Address | string, timeoutMs?: number): Promise<'uninit' | 'active' | 'frozen'>;
+    /**
+     * Get address balance via REST API
+     */
+    getAddressBalance(address: Address | string, timeoutMs?: number): Promise<bigint>;
+    /**
+     * Run a get method via REST API
+     */
+    runGetMethod(address: Address | string, method: string, stack?: unknown[], timeoutMs?: number): Promise<{
+        exit_code: number;
+        stack: unknown[];
+    }>;
+    /**
+     * Send BOC via REST API
+     */
+    sendBoc(boc: Buffer | string, timeoutMs?: number): Promise<void>;
+    /**
+     * Check if contract is deployed
+     */
+    isContractDeployed(address: Address | string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Unwrap TON API response
+     */
+    private unwrapResponse;
+}
+/**
+ * Create a Node adapter
+ */
+declare function createNodeAdapter(manager: ProviderManager, logger?: Logger): NodeAdapter;
+/**
+ * Get TonClient from ProviderManager (convenience function)
+ */
+declare function getTonClient(manager: ProviderManager): Promise<TonClient>;
+/**
+ * Get TonClient for network (one-shot convenience)
+ */
+declare function getTonClientForNetwork(network: Network, configPath?: string): Promise<TonClient>;
+/**
+ * Reset all cached state
+ */
+declare function resetNodeAdapter(): void;
+
+/**
+ * Unified Provider System - Browser Adapter
+ *
+ * Provides browser-compatible TON client functionality.
+ * Designed for use in React/Next.js applications.
+ */
+
+/**
+ * Browser Adapter for Provider System
+ *
+ * Provides fetch-based TON API access for browser environments.
+ * Compatible with React, Next.js, and other browser frameworks.
+ *
+ * Note: TonClient from @ton/ton works in browser but requires polyfills.
+ * This adapter provides a lighter alternative using fetch directly.
+ */
+declare class BrowserAdapter {
+    private manager;
+    private logger;
+    constructor(manager: ProviderManager, logger?: Logger);
+    /**
+     * Get current endpoint URL
+     */
+    getEndpoint(): Promise<string>;
+    /**
+     * Get endpoint with rate limiting
+     */
+    getEndpointWithRateLimit(timeoutMs?: number): Promise<string>;
+    /**
+     * Make a JSON-RPC call to the TON API
+     */
+    jsonRpc<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /**
+     * Get address state
+     */
+    getAddressState(address: string, timeoutMs?: number): Promise<'uninit' | 'active' | 'frozen'>;
+    /**
+     * Get address balance
+     */
+    getAddressBalance(address: string, timeoutMs?: number): Promise<bigint>;
+    /**
+     * Get address information
+     */
+    getAddressInfo(address: string, timeoutMs?: number): Promise<{
+        state: 'uninit' | 'active' | 'frozen';
+        balance: bigint;
+        lastTransactionLt?: string;
+        lastTransactionHash?: string;
+    }>;
+    /**
+     * Run get method
+     */
+    runGetMethod(address: string, method: string, stack?: unknown[], timeoutMs?: number): Promise<{
+        exit_code: number;
+        stack: unknown[];
+    }>;
+    /**
+     * Get masterchain info
+     */
+    getMasterchainInfo(timeoutMs?: number): Promise<{
+        seqno: number;
+        stateRootHash: string;
+    }>;
+    /**
+     * Get provider manager
+     */
+    getManager(): ProviderManager;
+    /**
+     * Get active provider info
+     */
+    getActiveProviderInfo(): {
+        id: string;
+        name: string;
+        isCustom: boolean;
+    } | null;
+    /**
+     * Get provider health results
+     */
+    getProviderHealthResults(): ProviderHealthResult[];
+    /**
+     * Test all providers
+     */
+    testAllProviders(): Promise<ProviderHealthResult[]>;
+    /**
+     * Unwrap TON API response
+     */
+    private unwrapResponse;
+}
+/**
+ * Create a Browser adapter
+ */
+declare function createBrowserAdapter(manager: ProviderManager, logger?: Logger): BrowserAdapter;
+/**
+ * Create a Browser adapter with auto-initialized manager
+ */
+declare function createBrowserAdapterForNetwork(network: Network, configPath?: string, logger?: Logger): Promise<BrowserAdapter>;
+
+/**
+ * Unified Provider System - Endpoint Utilities
+ *
+ * URL normalization and manipulation for TON RPC endpoints.
+ */
+/**
+ * Normalize endpoint URL for TonClient v2 API.
+ * Ensures the endpoint has /jsonRPC suffix for JSON-RPC POST requests.
+ *
+ * Different providers have different endpoint formats:
+ * - toncenter.com: POST to /api/v2/jsonRPC
+ * - Chainstack: POST to /api/v2/jsonRPC (needs /jsonRPC suffix!)
+ * - TON Access (orbs): Already returns correct JSON-RPC endpoint
+ * - QuickNode: Usually needs /jsonRPC appended
+ */
+declare function normalizeV2Endpoint(endpoint: string): string;
+/**
+ * Convert any endpoint to v2 base URL (without /jsonRPC suffix).
+ */
+declare function toV2Base(endpoint: string): string;
+/**
+ * Convert any endpoint to v3 base URL.
+ */
+declare function toV3Base(endpoint: string): string;
+/**
+ * Extract the base URL (protocol + host) from an endpoint.
+ */
+declare function getBaseUrl(endpoint: string): string;
+/**
+ * Check if an endpoint is a Chainstack URL.
+ */
+declare function isChainstackUrl(url: string): boolean;
+/**
+ * Check if an endpoint is a QuickNode URL.
+ */
+declare function isQuickNodeUrl(url: string): boolean;
+/**
+ * Check if an endpoint is a TonCenter URL.
+ */
+declare function isTonCenterUrl(url: string): boolean;
+/**
+ * Check if an endpoint is an Orbs URL.
+ */
+declare function isOrbsUrl(url: string): boolean;
+/**
+ * Build a full endpoint URL for a specific API method (REST style).
+ */
+declare function buildRestUrl(baseEndpoint: string, method: string): string;
+/**
+ * Build URL for getAddressState call.
+ */
+declare function buildGetAddressStateUrl(baseEndpoint: string, address: string): string;
+/**
+ * Build URL for getAddressBalance call.
+ */
+declare function buildGetAddressBalanceUrl(baseEndpoint: string, address: string): string;
+/**
+ * Build URL for getAddressInformation call.
+ */
+declare function buildGetAddressInfoUrl(baseEndpoint: string, address: string): string;
+/**
+ * Detect network from endpoint URL.
+ */
+declare function detectNetworkFromEndpoint(endpoint: string): 'testnet' | 'mainnet' | null;
+/**
+ * Validate that a string is a valid HTTP(S) URL.
+ */
+declare function isValidHttpUrl(str: string): boolean;
+/**
+ * Validate that a string is a valid WebSocket URL.
+ */
+declare function isValidWsUrl(str: string): boolean;
+
+/**
+ * Unified Provider System - Timeout Utilities
+ *
+ * Promise timeout helpers for async operations.
+ */
+
+/** Default timeout for TON provider requests */
+declare const DEFAULT_PROVIDER_TIMEOUT_MS = 30000;
+/** Default timeout for contract calls */
+declare const DEFAULT_CONTRACT_TIMEOUT_MS = 45000;
+/** Default timeout for health checks */
+declare const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 10000;
+/**
+ * Execute a promise with a timeout.
+ *
+ * @param promise - The promise to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param operationName - Name of the operation (for error messages)
+ * @returns The result of the promise
+ * @throws TimeoutError if the operation times out
+ */
+declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, operationName: string): Promise<T>;
+/**
+ * Execute a function with a timeout.
+ *
+ * @param fn - The async function to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param operationName - Name of the operation (for error messages)
+ * @returns The result of the function
+ * @throws TimeoutError if the operation times out
+ */
+declare function withTimeoutFn<T>(fn: () => Promise<T>, timeoutMs: number, operationName: string): Promise<T>;
+/**
+ * Create an AbortController with automatic timeout.
+ *
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns AbortController that will abort after timeout
+ */
+declare function createTimeoutController(timeoutMs: number): {
+    controller: AbortController;
+    clear: () => void;
+};
+/**
+ * Execute a fetch request with timeout.
+ *
+ * @param url - The URL to fetch
+ * @param options - Fetch options (excluding signal)
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Fetch response
+ * @throws TimeoutError if the request times out
+ */
+declare function fetchWithTimeout(url: string, options: Omit<RequestInit, 'signal'>, timeoutMs: number): Promise<Response>;
+/**
+ * Retry options for async operations.
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Base delay between retries in ms */
+    baseDelayMs: number;
+    /** Maximum delay between retries in ms */
+    maxDelayMs: number;
+    /** Backoff multiplier for exponential backoff */
+    backoffMultiplier: number;
+    /** Function to determine if error is retryable */
+    isRetryable?: (error: Error) => boolean;
+}
+/**
+ * Execute a function with automatic retries on failure.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry options
+ * @returns The result of the function
+ * @throws The last error if all retries fail
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T>;
+/**
+ * Execute a function with both timeout and retry.
+ *
+ * @param fn - The async function to execute
+ * @param timeoutMs - Timeout per attempt in milliseconds
+ * @param operationName - Name of the operation
+ * @param retryOptions - Retry options
+ * @returns The result of the function
+ */
+declare function withTimeoutAndRetry<T>(fn: () => Promise<T>, timeoutMs: number, operationName: string, retryOptions?: Partial<RetryOptions>): Promise<T>;
+/**
+ * Sleep for a specified duration.
+ *
+ * @param ms - Duration in milliseconds
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Check if an error is a timeout error.
+ */
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+/**
+ * Check if an error appears to be a rate limit error.
+ */
+declare function isRateLimitError(error: unknown): boolean;
+
+export { type ApiVersion, ApiVersionSchema, BrowserAdapter, CHAINSTACK_RATE_LIMIT, ConfigError, DEFAULT_CONTRACT_TIMEOUT_MS, DEFAULT_HEALTH_CHECK_TIMEOUT_MS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_TIMEOUT_MS, DEFAULT_RATE_LIMIT, type HealthCheckConfig, HealthChecker, type Logger, type MasterchainInfo, type Network, type NetworkDefaults, NetworkSchema, NodeAdapter, ORBS_RATE_LIMIT, type ProviderConfig, ProviderConfigSchema, type ProviderEndpoints, ProviderError, type ProviderHealthResult, ProviderManager, type ProviderManagerOptions, type ProviderManagerState, ProviderRegistry, ProviderSelector, type ProviderState, type ProviderStatus, type ProviderType, ProviderTypeSchema, QUICKNODE_RATE_LIMIT, type RateLimitConfig, RateLimitError, type RateLimitState, RateLimiterManager, type ResolvedProvider, type RetryOptions, type RpcConfig, RpcConfigSchema, type SelectionConfig, type StateListener, TimeoutError, TokenBucketRateLimiter, type TonApiResponse, buildGetAddressBalanceUrl, buildGetAddressInfoUrl, buildGetAddressStateUrl, buildRestUrl, createBrowserAdapter, createBrowserAdapterForNetwork, createDefaultConfig, createDefaultRegistry, createEmptyConfig, createHealthChecker, createNodeAdapter, createProviderManager, createRateLimiter, createRateLimiterManager, createRegistry, createRegistryFromData, createRegistryFromFile, createSelector, createTimeoutController, detectNetworkFromEndpoint, fetchWithTimeout, getBaseUrl, getDefaultProvidersForNetwork, getEnvVar, getProviderManager, getProvidersForNetwork, getRateLimitForType, getTonClient, getTonClientForNetwork, isApiVersion, isChainstackUrl, isNetwork, isOrbsUrl, isProviderType, isQuickNodeUrl, isRateLimitError, isTimeoutError, isTonCenterUrl, isValidHttpUrl, isValidWsUrl, loadBuiltinConfig, loadConfig, loadConfigFromData, loadConfigFromUrl, mergeConfigs, mergeWithDefaults, normalizeV2Endpoint, parseProviderConfig, parseRpcConfig, resetNodeAdapter, resolveAllProviders, resolveEndpoints, resolveKeyPlaceholder, resolveProvider, sleep, toV2Base, toV3Base, withRetry, withTimeout, withTimeoutAndRetry, withTimeoutFn };