ton-provider-system 0.1.13 → 0.2.1

package/dist/index.d.cts

@@ -1032,6 +1032,9 @@ declare class HealthChecker {
     clearResults(): void;
     /**
      * Mark a provider as degraded (e.g., on 429 error)
+     *
+     * Providers marked as degraded have failed health checks (e.g., rate limit errors)
+     * and should not be selected. The system will failover to the next available provider.
      */
     markDegraded(providerId: string, network: Network, error?: string): void;
     /**
@@ -1043,13 +1046,6 @@ declare class HealthChecker {
      * Get endpoint URL for a provider (handles dynamic providers like Orbs)
      */
     private getEndpoint;
-    /**
-     * Normalize endpoint for provider-specific requirements
-     *
-     * Note: normalizeV2Endpoint now handles all provider-specific cases correctly,
-     * including Tatum (/jsonRPC), OnFinality (/public or /rpc), QuickNode, and GetBlock.
-     */
-    private normalizeEndpointForProvider;
     /**
      * Call getMasterchainInfo API with provider-specific handling
      */
@@ -1630,20 +1626,16 @@ declare function createBrowserAdapterForNetwork(network: Network, configPath?: s
  *
  * 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.
+ * Normalize endpoint URL for TonClient v2 API using provider-specific implementation.
+ * This is the preferred method when a ResolvedProvider is available.
  *
- * 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: Needs /jsonRPC appended to base URL
- * - GetBlock: Needs /jsonRPC appended to base URL
- * - Tatum: Gateway URLs need /jsonRPC appended (gateway.tatum.io/jsonRPC)
- * - OnFinality: Uses /public or /rpc path with query params - preserve query params
+ * @param endpoint - Endpoint URL to normalize
+ * @param provider - Resolved provider configuration (optional)
+ * @returns Normalized endpoint URL
  */
-declare function normalizeV2Endpoint(endpoint: string): string;
+declare function normalizeV2Endpoint(endpoint: string, provider?: ResolvedProvider): string;
 /**
  * Convert any endpoint to v2 base URL (without /jsonRPC suffix).
  */
@@ -1802,4 +1794,234 @@ declare function isTimeoutError(error: unknown): error is TimeoutError;
  */
 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, getTonClientWithRateLimit, 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 };
+/**
+ * Unified Provider System - Base Provider
+ *
+ * Base class for provider-specific implementations.
+ * All provider types extend this class to provide provider-specific behavior.
+ */
+
+/**
+ * Base provider class that all provider-specific implementations extend.
+ * Provides common functionality and defines the interface for provider-specific behavior.
+ */
+declare abstract class BaseProvider {
+    protected provider: ResolvedProvider;
+    constructor(provider: ResolvedProvider);
+    /**
+     * Get the provider instance
+     */
+    getProvider(): ResolvedProvider;
+    /**
+     * Normalize endpoint URL for this provider type.
+     * Each provider may have different endpoint format requirements.
+     */
+    abstract normalizeEndpoint(endpoint: string): string;
+    /**
+     * Build HTTP headers for requests to this provider.
+     * Handles provider-specific authentication (API keys in headers, etc.)
+     */
+    abstract buildHeaders(): Record<string, string>;
+    /**
+     * Build a JSON-RPC request body.
+     * Most providers use standard JSON-RPC 2.0, but some may need modifications.
+     */
+    buildRequest(method: string, params?: Record<string, unknown>): {
+        id: string;
+        jsonrpc: string;
+        method: string;
+        params: Record<string, unknown>;
+    };
+    /**
+     * Parse response from provider.
+     * Handles provider-specific response formats.
+     */
+    parseResponse<T = unknown>(data: unknown): T;
+    /**
+     * Parse masterchain info from response.
+     * Validates the response structure and extracts seqno.
+     */
+    parseMasterchainInfo(data: unknown): MasterchainInfo;
+    /**
+     * Validate provider configuration.
+     * Checks if required API keys are present, etc.
+     */
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Get the normalized endpoint for this provider.
+     */
+    getNormalizedEndpoint(): string;
+    /**
+     * Check if this provider requires an API key.
+     */
+    requiresApiKey(): boolean;
+    /**
+     * Check if API key is present (if required).
+     */
+    hasApiKey(): boolean;
+}
+
+/**
+ * Unified Provider System - Chainstack Provider
+ *
+ * Chainstack-specific implementation.
+ * Documentation: https://docs.chainstack.com/reference/getting-started-ton
+ *
+ * Endpoint format: https://ton-{network}.core.chainstack.com/{key}/api/v2/jsonRPC
+ * API key: In URL path (not header)
+ */
+
+declare class ChainstackProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+}
+
+/**
+ * Unified Provider System - Tatum Provider
+ *
+ * Tatum-specific implementation.
+ * Documentation: https://docs.tatum.io/reference/rpc-ton
+ *
+ * Endpoint format: https://ton-{network}.gateway.tatum.io/jsonRPC
+ * API key: Required in x-api-key header
+ */
+
+declare class TatumProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    requiresApiKey(): boolean;
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+}
+
+/**
+ * Unified Provider System - OnFinality Provider
+ *
+ * OnFinality-specific implementation.
+ * Documentation: https://documentation.onfinality.io/support/ton
+ *
+ * Endpoint format: https://ton-{network}.api.onfinality.io/public or /rpc
+ * API key: Optional, in apikey header (preferred) or query params
+ */
+
+declare class OnFinalityProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    parseResponse<T = unknown>(data: unknown): T;
+}
+
+/**
+ * Unified Provider System - QuickNode Provider
+ *
+ * QuickNode-specific implementation.
+ * Documentation: https://quicknode.com/docs/ton
+ *
+ * Endpoint format: https://{key}.ton-{network}.quiknode.pro/jsonRPC
+ * API key: In subdomain (not header)
+ */
+
+declare class QuickNodeProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+}
+
+/**
+ * Unified Provider System - GetBlock Provider
+ *
+ * GetBlock-specific implementation.
+ * Documentation: https://docs.getblock.io/api-reference/the-open-network-ton
+ *
+ * Endpoint format: https://go.getblock.io/{key}/jsonRPC
+ * API key: Required in x-api-key header
+ */
+
+declare class GetBlockProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    requiresApiKey(): boolean;
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+}
+
+/**
+ * Unified Provider System - TON Center Provider
+ *
+ * TON Center-specific implementation.
+ * Documentation: https://toncenter.com/api/v2/
+ *
+ * Endpoint format: https://{testnet.}toncenter.com/api/v2/jsonRPC
+ * API key: Optional, passed to TonClient (not in header for HTTP requests)
+ */
+
+declare class TonCenterProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    requiresApiKey(): boolean;
+}
+
+/**
+ * Unified Provider System - Orbs Provider
+ *
+ * Orbs (TON Access) specific implementation.
+ * Documentation: https://github.com/orbs-network/ton-access
+ *
+ * Endpoint format: Dynamic discovery via @orbs-network/ton-access
+ * API key: Not required (decentralized gateway)
+ */
+
+declare class OrbsProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    /**
+     * Get dynamic endpoint from Orbs TON Access.
+     * This should be called before making requests.
+     */
+    getDynamicEndpoint(): Promise<string>;
+    requiresApiKey(): boolean;
+}
+
+/**
+ * Unified Provider System - Provider Factory
+ *
+ * Factory for creating provider-specific implementations.
+ */
+
+/**
+ * Generic provider for unknown/custom provider types.
+ * Uses default behavior from BaseProvider.
+ */
+declare class GenericProvider extends BaseProvider {
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+}
+/**
+ * Create a provider-specific implementation for the given provider.
+ *
+ * @param provider - Resolved provider configuration
+ * @returns Provider-specific implementation instance
+ */
+declare function createProvider(provider: ResolvedProvider): BaseProvider;
+
+export { type ApiVersion, ApiVersionSchema, BaseProvider, BrowserAdapter, CHAINSTACK_RATE_LIMIT, ChainstackProvider, ConfigError, DEFAULT_CONTRACT_TIMEOUT_MS, DEFAULT_HEALTH_CHECK_TIMEOUT_MS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_TIMEOUT_MS, DEFAULT_RATE_LIMIT, GenericProvider, GetBlockProvider, type HealthCheckConfig, HealthChecker, type Logger, type MasterchainInfo, type Network, type NetworkDefaults, NetworkSchema, NodeAdapter, ORBS_RATE_LIMIT, OnFinalityProvider, OrbsProvider, 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, QuickNodeProvider, type RateLimitConfig, RateLimitError, type RateLimitState, RateLimiterManager, type ResolvedProvider, type RetryOptions, type RpcConfig, RpcConfigSchema, type SelectionConfig, type StateListener, TatumProvider, TimeoutError, TokenBucketRateLimiter, type TonApiResponse, TonCenterProvider, buildGetAddressBalanceUrl, buildGetAddressInfoUrl, buildGetAddressStateUrl, buildRestUrl, createBrowserAdapter, createBrowserAdapterForNetwork, createDefaultConfig, createDefaultRegistry, createEmptyConfig, createHealthChecker, createNodeAdapter, createProvider, createProviderManager, createRateLimiter, createRateLimiterManager, createRegistry, createRegistryFromData, createRegistryFromFile, createSelector, createTimeoutController, detectNetworkFromEndpoint, fetchWithTimeout, getBaseUrl, getDefaultProvidersForNetwork, getEnvVar, getProviderManager, getProvidersForNetwork, getRateLimitForType, getTonClient, getTonClientForNetwork, getTonClientWithRateLimit, 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 };

package/dist/index.d.ts

@@ -1032,6 +1032,9 @@ declare class HealthChecker {
     clearResults(): void;
     /**
      * Mark a provider as degraded (e.g., on 429 error)
+     *
+     * Providers marked as degraded have failed health checks (e.g., rate limit errors)
+     * and should not be selected. The system will failover to the next available provider.
      */
     markDegraded(providerId: string, network: Network, error?: string): void;
     /**
@@ -1043,13 +1046,6 @@ declare class HealthChecker {
      * Get endpoint URL for a provider (handles dynamic providers like Orbs)
      */
     private getEndpoint;
-    /**
-     * Normalize endpoint for provider-specific requirements
-     *
-     * Note: normalizeV2Endpoint now handles all provider-specific cases correctly,
-     * including Tatum (/jsonRPC), OnFinality (/public or /rpc), QuickNode, and GetBlock.
-     */
-    private normalizeEndpointForProvider;
     /**
      * Call getMasterchainInfo API with provider-specific handling
      */
@@ -1630,20 +1626,16 @@ declare function createBrowserAdapterForNetwork(network: Network, configPath?: s
  *
  * 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.
+ * Normalize endpoint URL for TonClient v2 API using provider-specific implementation.
+ * This is the preferred method when a ResolvedProvider is available.
  *
- * 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: Needs /jsonRPC appended to base URL
- * - GetBlock: Needs /jsonRPC appended to base URL
- * - Tatum: Gateway URLs need /jsonRPC appended (gateway.tatum.io/jsonRPC)
- * - OnFinality: Uses /public or /rpc path with query params - preserve query params
+ * @param endpoint - Endpoint URL to normalize
+ * @param provider - Resolved provider configuration (optional)
+ * @returns Normalized endpoint URL
  */
-declare function normalizeV2Endpoint(endpoint: string): string;
+declare function normalizeV2Endpoint(endpoint: string, provider?: ResolvedProvider): string;
 /**
  * Convert any endpoint to v2 base URL (without /jsonRPC suffix).
  */
@@ -1802,4 +1794,234 @@ declare function isTimeoutError(error: unknown): error is TimeoutError;
  */
 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, getTonClientWithRateLimit, 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 };
+/**
+ * Unified Provider System - Base Provider
+ *
+ * Base class for provider-specific implementations.
+ * All provider types extend this class to provide provider-specific behavior.
+ */
+
+/**
+ * Base provider class that all provider-specific implementations extend.
+ * Provides common functionality and defines the interface for provider-specific behavior.
+ */
+declare abstract class BaseProvider {
+    protected provider: ResolvedProvider;
+    constructor(provider: ResolvedProvider);
+    /**
+     * Get the provider instance
+     */
+    getProvider(): ResolvedProvider;
+    /**
+     * Normalize endpoint URL for this provider type.
+     * Each provider may have different endpoint format requirements.
+     */
+    abstract normalizeEndpoint(endpoint: string): string;
+    /**
+     * Build HTTP headers for requests to this provider.
+     * Handles provider-specific authentication (API keys in headers, etc.)
+     */
+    abstract buildHeaders(): Record<string, string>;
+    /**
+     * Build a JSON-RPC request body.
+     * Most providers use standard JSON-RPC 2.0, but some may need modifications.
+     */
+    buildRequest(method: string, params?: Record<string, unknown>): {
+        id: string;
+        jsonrpc: string;
+        method: string;
+        params: Record<string, unknown>;
+    };
+    /**
+     * Parse response from provider.
+     * Handles provider-specific response formats.
+     */
+    parseResponse<T = unknown>(data: unknown): T;
+    /**
+     * Parse masterchain info from response.
+     * Validates the response structure and extracts seqno.
+     */
+    parseMasterchainInfo(data: unknown): MasterchainInfo;
+    /**
+     * Validate provider configuration.
+     * Checks if required API keys are present, etc.
+     */
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Get the normalized endpoint for this provider.
+     */
+    getNormalizedEndpoint(): string;
+    /**
+     * Check if this provider requires an API key.
+     */
+    requiresApiKey(): boolean;
+    /**
+     * Check if API key is present (if required).
+     */
+    hasApiKey(): boolean;
+}
+
+/**
+ * Unified Provider System - Chainstack Provider
+ *
+ * Chainstack-specific implementation.
+ * Documentation: https://docs.chainstack.com/reference/getting-started-ton
+ *
+ * Endpoint format: https://ton-{network}.core.chainstack.com/{key}/api/v2/jsonRPC
+ * API key: In URL path (not header)
+ */
+
+declare class ChainstackProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+}
+
+/**
+ * Unified Provider System - Tatum Provider
+ *
+ * Tatum-specific implementation.
+ * Documentation: https://docs.tatum.io/reference/rpc-ton
+ *
+ * Endpoint format: https://ton-{network}.gateway.tatum.io/jsonRPC
+ * API key: Required in x-api-key header
+ */
+
+declare class TatumProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    requiresApiKey(): boolean;
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+}
+
+/**
+ * Unified Provider System - OnFinality Provider
+ *
+ * OnFinality-specific implementation.
+ * Documentation: https://documentation.onfinality.io/support/ton
+ *
+ * Endpoint format: https://ton-{network}.api.onfinality.io/public or /rpc
+ * API key: Optional, in apikey header (preferred) or query params
+ */
+
+declare class OnFinalityProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    parseResponse<T = unknown>(data: unknown): T;
+}
+
+/**
+ * Unified Provider System - QuickNode Provider
+ *
+ * QuickNode-specific implementation.
+ * Documentation: https://quicknode.com/docs/ton
+ *
+ * Endpoint format: https://{key}.ton-{network}.quiknode.pro/jsonRPC
+ * API key: In subdomain (not header)
+ */
+
+declare class QuickNodeProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+}
+
+/**
+ * Unified Provider System - GetBlock Provider
+ *
+ * GetBlock-specific implementation.
+ * Documentation: https://docs.getblock.io/api-reference/the-open-network-ton
+ *
+ * Endpoint format: https://go.getblock.io/{key}/jsonRPC
+ * API key: Required in x-api-key header
+ */
+
+declare class GetBlockProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    requiresApiKey(): boolean;
+    validateConfig(): {
+        valid: boolean;
+        error?: string;
+    };
+}
+
+/**
+ * Unified Provider System - TON Center Provider
+ *
+ * TON Center-specific implementation.
+ * Documentation: https://toncenter.com/api/v2/
+ *
+ * Endpoint format: https://{testnet.}toncenter.com/api/v2/jsonRPC
+ * API key: Optional, passed to TonClient (not in header for HTTP requests)
+ */
+
+declare class TonCenterProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    requiresApiKey(): boolean;
+}
+
+/**
+ * Unified Provider System - Orbs Provider
+ *
+ * Orbs (TON Access) specific implementation.
+ * Documentation: https://github.com/orbs-network/ton-access
+ *
+ * Endpoint format: Dynamic discovery via @orbs-network/ton-access
+ * API key: Not required (decentralized gateway)
+ */
+
+declare class OrbsProvider extends BaseProvider {
+    constructor(provider: ResolvedProvider);
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+    /**
+     * Get dynamic endpoint from Orbs TON Access.
+     * This should be called before making requests.
+     */
+    getDynamicEndpoint(): Promise<string>;
+    requiresApiKey(): boolean;
+}
+
+/**
+ * Unified Provider System - Provider Factory
+ *
+ * Factory for creating provider-specific implementations.
+ */
+
+/**
+ * Generic provider for unknown/custom provider types.
+ * Uses default behavior from BaseProvider.
+ */
+declare class GenericProvider extends BaseProvider {
+    normalizeEndpoint(endpoint: string): string;
+    buildHeaders(): Record<string, string>;
+}
+/**
+ * Create a provider-specific implementation for the given provider.
+ *
+ * @param provider - Resolved provider configuration
+ * @returns Provider-specific implementation instance
+ */
+declare function createProvider(provider: ResolvedProvider): BaseProvider;
+
+export { type ApiVersion, ApiVersionSchema, BaseProvider, BrowserAdapter, CHAINSTACK_RATE_LIMIT, ChainstackProvider, ConfigError, DEFAULT_CONTRACT_TIMEOUT_MS, DEFAULT_HEALTH_CHECK_TIMEOUT_MS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_TIMEOUT_MS, DEFAULT_RATE_LIMIT, GenericProvider, GetBlockProvider, type HealthCheckConfig, HealthChecker, type Logger, type MasterchainInfo, type Network, type NetworkDefaults, NetworkSchema, NodeAdapter, ORBS_RATE_LIMIT, OnFinalityProvider, OrbsProvider, 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, QuickNodeProvider, type RateLimitConfig, RateLimitError, type RateLimitState, RateLimiterManager, type ResolvedProvider, type RetryOptions, type RpcConfig, RpcConfigSchema, type SelectionConfig, type StateListener, TatumProvider, TimeoutError, TokenBucketRateLimiter, type TonApiResponse, TonCenterProvider, buildGetAddressBalanceUrl, buildGetAddressInfoUrl, buildGetAddressStateUrl, buildRestUrl, createBrowserAdapter, createBrowserAdapterForNetwork, createDefaultConfig, createDefaultRegistry, createEmptyConfig, createHealthChecker, createNodeAdapter, createProvider, createProviderManager, createRateLimiter, createRateLimiterManager, createRegistry, createRegistryFromData, createRegistryFromFile, createSelector, createTimeoutController, detectNetworkFromEndpoint, fetchWithTimeout, getBaseUrl, getDefaultProvidersForNetwork, getEnvVar, getProviderManager, getProvidersForNetwork, getRateLimitForType, getTonClient, getTonClientForNetwork, getTonClientWithRateLimit, 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 };