ton-provider-system 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -797,89 +797,6 @@ declare function createDefaultRegistry(logger?: Logger): ProviderRegistry;
  */
 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
  *
@@ -1030,6 +947,104 @@ declare function createRateLimiter(rps: number, logger?: Logger): TokenBucketRat
  */
 declare function createRateLimiterManager(logger?: Logger): RateLimiterManager;
 
+/**
+ * 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;
+    private rateLimiter;
+    constructor(config?: Partial<HealthCheckConfig>, logger?: Logger, rateLimiter?: RateLimiterManager);
+    /**
+     * Set rate limiter (can be set after construction)
+     */
+    setRateLimiter(rateLimiter: RateLimiterManager | null): void;
+    /**
+     * Test a single provider's health
+     */
+    testProvider(provider: ResolvedProvider): Promise<ProviderHealthResult>;
+    /**
+     * Test multiple providers in parallel with staggered batches
+     *
+     * @param batchSize - Number of providers to test in parallel (default: 2)
+     * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
+     */
+    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;
+    /**
+     * 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
+     */
+    private callGetMasterchainInfo;
+    private sleep;
+}
+/**
+ * Create a health checker with default configuration
+ */
+declare function createHealthChecker(config?: Partial<HealthCheckConfig>, logger?: Logger, rateLimiter?: RateLimiterManager): HealthChecker;
+
 /**
  * Unified Provider System - Provider Selector
  *
@@ -1353,8 +1368,29 @@ declare class NodeAdapter {
      * Get TonClient instance
      *
      * Creates a new client if endpoint changed, otherwise returns cached.
+     *
+     * NOTE: Direct TonClient calls bypass rate limiting. For rate-limited operations,
+     * use adapter methods (getAddressState, runGetMethod, etc.) or wrap your calls
+     * with rate limit token acquisition.
+     *
+     * Example with rate limiting:
+     * ```typescript
+     * const endpoint = await adapter.manager.getEndpointWithRateLimit();
+     * // Make your TonClient call
+     * adapter.manager.reportSuccess(); // or reportError() on failure
+     * ```
      */
     getClient(): Promise<TonClient>;
+    /**
+     * Get TonClient with rate limiting applied
+     *
+     * Acquires a rate limit token before returning the client.
+     * Use this when you need to ensure rate limiting is respected.
+     *
+     * Note: This only acquires ONE token. For multiple operations,
+     * you should acquire tokens before each operation or use adapter methods.
+     */
+    getClientWithRateLimit(timeoutMs?: number): Promise<TonClient>;
     /**
      * Reset client cache (forces new client creation)
      */
@@ -1401,8 +1437,45 @@ declare class NodeAdapter {
 declare function createNodeAdapter(manager: ProviderManager, logger?: Logger): NodeAdapter;
 /**
  * Get TonClient from ProviderManager (convenience function)
+ *
+ * WARNING: Direct TonClient API calls bypass rate limiting!
+ * For rate-limited operations, use one of these approaches:
+ *
+ * 1. Use adapter methods (recommended):
+ *    ```typescript
+ *    const adapter = new NodeAdapter(manager);
+ *    const state = await adapter.getAddressState(address);
+ *    ```
+ *
+ * 2. Acquire rate limit tokens before operations:
+ *    ```typescript
+ *    await manager.getEndpointWithRateLimit(); // Acquire token
+ *    const result = await client.someMethod();
+ *    manager.reportSuccess(); // or reportError() on failure
+ *    ```
+ *
+ * 3. Use getTonClientWithRateLimit() for operations that need rate limiting
  */
 declare function getTonClient(manager: ProviderManager): Promise<TonClient>;
+/**
+ * Get TonClient with rate limiting wrapper
+ *
+ * Returns a TonClient along with helper methods to ensure rate limiting.
+ * Use this when you need to make multiple TonClient calls with rate limiting.
+ *
+ * Example:
+ * ```typescript
+ * const { client, withRateLimit } = await getTonClientWithRateLimit(manager);
+ *
+ * // Wrap your operations
+ * const balance = await withRateLimit(() => client.getBalance(address));
+ * const state = await withRateLimit(() => client.getContractState(address));
+ * ```
+ */
+declare function getTonClientWithRateLimit(manager: ProviderManager): Promise<{
+    client: TonClient;
+    withRateLimit: <T>(fn: () => Promise<T>) => Promise<T>;
+}>;
 /**
  * Get TonClient for network (one-shot convenience)
  */
@@ -1522,7 +1595,10 @@ declare function createBrowserAdapterForNetwork(network: Network, configPath?: s
  * - 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
+ * - 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
  */
 declare function normalizeV2Endpoint(endpoint: string): string;
 /**
@@ -1683,4 +1759,4 @@ 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, 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 };
+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 };

package/dist/index.d.ts

@@ -797,89 +797,6 @@ declare function createDefaultRegistry(logger?: Logger): ProviderRegistry;
  */
 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
  *
@@ -1030,6 +947,104 @@ declare function createRateLimiter(rps: number, logger?: Logger): TokenBucketRat
  */
 declare function createRateLimiterManager(logger?: Logger): RateLimiterManager;
 
+/**
+ * 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;
+    private rateLimiter;
+    constructor(config?: Partial<HealthCheckConfig>, logger?: Logger, rateLimiter?: RateLimiterManager);
+    /**
+     * Set rate limiter (can be set after construction)
+     */
+    setRateLimiter(rateLimiter: RateLimiterManager | null): void;
+    /**
+     * Test a single provider's health
+     */
+    testProvider(provider: ResolvedProvider): Promise<ProviderHealthResult>;
+    /**
+     * Test multiple providers in parallel with staggered batches
+     *
+     * @param batchSize - Number of providers to test in parallel (default: 2)
+     * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
+     */
+    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;
+    /**
+     * 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
+     */
+    private callGetMasterchainInfo;
+    private sleep;
+}
+/**
+ * Create a health checker with default configuration
+ */
+declare function createHealthChecker(config?: Partial<HealthCheckConfig>, logger?: Logger, rateLimiter?: RateLimiterManager): HealthChecker;
+
 /**
  * Unified Provider System - Provider Selector
  *
@@ -1353,8 +1368,29 @@ declare class NodeAdapter {
      * Get TonClient instance
      *
      * Creates a new client if endpoint changed, otherwise returns cached.
+     *
+     * NOTE: Direct TonClient calls bypass rate limiting. For rate-limited operations,
+     * use adapter methods (getAddressState, runGetMethod, etc.) or wrap your calls
+     * with rate limit token acquisition.
+     *
+     * Example with rate limiting:
+     * ```typescript
+     * const endpoint = await adapter.manager.getEndpointWithRateLimit();
+     * // Make your TonClient call
+     * adapter.manager.reportSuccess(); // or reportError() on failure
+     * ```
      */
     getClient(): Promise<TonClient>;
+    /**
+     * Get TonClient with rate limiting applied
+     *
+     * Acquires a rate limit token before returning the client.
+     * Use this when you need to ensure rate limiting is respected.
+     *
+     * Note: This only acquires ONE token. For multiple operations,
+     * you should acquire tokens before each operation or use adapter methods.
+     */
+    getClientWithRateLimit(timeoutMs?: number): Promise<TonClient>;
     /**
      * Reset client cache (forces new client creation)
      */
@@ -1401,8 +1437,45 @@ declare class NodeAdapter {
 declare function createNodeAdapter(manager: ProviderManager, logger?: Logger): NodeAdapter;
 /**
  * Get TonClient from ProviderManager (convenience function)
+ *
+ * WARNING: Direct TonClient API calls bypass rate limiting!
+ * For rate-limited operations, use one of these approaches:
+ *
+ * 1. Use adapter methods (recommended):
+ *    ```typescript
+ *    const adapter = new NodeAdapter(manager);
+ *    const state = await adapter.getAddressState(address);
+ *    ```
+ *
+ * 2. Acquire rate limit tokens before operations:
+ *    ```typescript
+ *    await manager.getEndpointWithRateLimit(); // Acquire token
+ *    const result = await client.someMethod();
+ *    manager.reportSuccess(); // or reportError() on failure
+ *    ```
+ *
+ * 3. Use getTonClientWithRateLimit() for operations that need rate limiting
  */
 declare function getTonClient(manager: ProviderManager): Promise<TonClient>;
+/**
+ * Get TonClient with rate limiting wrapper
+ *
+ * Returns a TonClient along with helper methods to ensure rate limiting.
+ * Use this when you need to make multiple TonClient calls with rate limiting.
+ *
+ * Example:
+ * ```typescript
+ * const { client, withRateLimit } = await getTonClientWithRateLimit(manager);
+ *
+ * // Wrap your operations
+ * const balance = await withRateLimit(() => client.getBalance(address));
+ * const state = await withRateLimit(() => client.getContractState(address));
+ * ```
+ */
+declare function getTonClientWithRateLimit(manager: ProviderManager): Promise<{
+    client: TonClient;
+    withRateLimit: <T>(fn: () => Promise<T>) => Promise<T>;
+}>;
 /**
  * Get TonClient for network (one-shot convenience)
  */
@@ -1522,7 +1595,10 @@ declare function createBrowserAdapterForNetwork(network: Network, configPath?: s
  * - 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
+ * - 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
  */
 declare function normalizeV2Endpoint(endpoint: string): string;
 /**
@@ -1683,4 +1759,4 @@ 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, 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 };
+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 };