ton-provider-system 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -875,7 +875,10 @@ declare class TokenBucketRateLimiter {
      */
     release(): void;
     /**
-     * Report a successful request (resets backoff)
+     * Report a successful request (gradually reduces backoff)
+     *
+     * Instead of immediately clearing backoff, we gradually reduce it to prevent
+     * immediately hitting the rate limit again after a single success.
      */
     reportSuccess(): void;
     /**
@@ -989,6 +992,8 @@ declare class HealthChecker {
     private logger;
     private results;
     private highestSeqno;
+    /** Rolling window of recent valid seqnos per network (for outlier-robust blocksBehind). */
+    private seqnoSamples;
     private rateLimiter;
     constructor(config?: Partial<HealthCheckConfig>, logger?: Logger, rateLimiter?: RateLimiterManager);
     /**
@@ -1004,6 +1009,7 @@ declare class HealthChecker {
      *
      * @param batchSize - Number of providers to test in parallel (default: 2)
      * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
+     *                       If not provided, calculates delay based on lowest RPS in batch
      */
     testProviders(providers: ResolvedProvider[], batchSize?: number, batchDelayMs?: number): Promise<ProviderHealthResult[]>;
     /**
@@ -1042,6 +1048,18 @@ declare class HealthChecker {
      */
     markOffline(providerId: string, network: Network, error?: string): void;
     private getResultKey;
+    /**
+     * Record a valid seqno sample and return an outlier-robust freshness baseline
+     * (median of recent samples for the network). Using the median instead of the
+     * raw maximum prevents a single provider that reports an inflated seqno from
+     * poisoning `blocksBehind` for every other (healthy) provider. See P2-2.
+     */
+    private recordSeqnoAndGetBaseline;
+    /**
+     * Detect a "non-JSON response" error (e.g. an HTML error page returned by a
+     * misbehaving gateway), used to decide whether to re-discover an Orbs endpoint.
+     */
+    private isNonJsonResponseError;
     /**
      * Get endpoint URL for a provider (handles dynamic providers like Orbs)
      */
@@ -1084,6 +1102,8 @@ interface SelectionConfig {
     freshnessWeight: number;
     /** Minimum acceptable provider status */
     minStatus: ProviderStatus[];
+    /** Cooldown period (ms) before retrying failed providers (default: 30000) */
+    retryCooldownMs: number;
 }
 /**
  * Provider Selector
@@ -1196,6 +1216,22 @@ declare class ProviderSelector {
      * 2. Health check result browserCompatible flag (if health check was performed)
      */
     private filterBrowserCompatible;
+    /**
+     * Check if an error is retryable (temporary) or permanent
+     *
+     * Permanent errors (never retry):
+     * - 404 (Not Found) - endpoint doesn't exist
+     * - 401 (Unauthorized) - invalid API key
+     * - Invalid API key errors
+     *
+     * Retryable errors (can retry after cooldown):
+     * - 503 (Service Unavailable) - temporary server issue
+     * - 502 (Bad Gateway) - temporary gateway issue
+     * - Timeout errors - network issues
+     * - Network errors - connection issues
+     * - 429 (Rate Limit) - temporary rate limit (handled separately)
+     */
+    private isRetryableError;
 }
 /**
  * Create a provider selector
@@ -1554,18 +1590,26 @@ declare class BrowserAdapter {
     getEndpointWithRateLimit(timeoutMs?: number): Promise<string>;
     /**
      * Make a JSON-RPC call to the TON API
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     jsonRpc<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
     /**
      * Get address state
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressState(address: string, timeoutMs?: number): Promise<'uninit' | 'active' | 'frozen'>;
     /**
      * Get address balance
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressBalance(address: string, timeoutMs?: number): Promise<bigint>;
     /**
      * Get address information
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressInfo(address: string, timeoutMs?: number): Promise<{
         state: 'uninit' | 'active' | 'frozen';
@@ -1575,6 +1619,8 @@ declare class BrowserAdapter {
     }>;
     /**
      * Run get method
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     runGetMethod(address: string, method: string, stack?: unknown[], timeoutMs?: number): Promise<{
         exit_code: number;
@@ -1692,6 +1738,17 @@ declare function isValidHttpUrl(str: string): boolean;
  * Validate that a string is a valid WebSocket URL.
  */
 declare function isValidWsUrl(str: string): boolean;
+/**
+ * Redact credentials from an endpoint URL so it is safe to log.
+ *
+ * Masks (a) sensitive query-param values (`apikey`, `api_key`, `key`, `token`,
+ * `secret`, `password`), (b) credential-like path segments while preserving
+ * structural ones (`api`, `v2`, `v3`, `jsonRPC`, `rpc`, `public`, …), and
+ * (c) a credential-like leading host label (e.g. a QuickNode subdomain key).
+ *
+ * For logging only — never use the result to make requests.
+ */
+declare function redactUrl(url: string): string;
 
 /**
  * Unified Provider System - Timeout Utilities
@@ -2027,4 +2084,4 @@ declare class GenericProvider extends BaseProvider {
  */
 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 };
+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, redactUrl, resetNodeAdapter, resolveAllProviders, resolveEndpoints, resolveKeyPlaceholder, resolveProvider, sleep, toV2Base, toV3Base, withRetry, withTimeout, withTimeoutAndRetry, withTimeoutFn };

package/dist/index.d.ts

@@ -875,7 +875,10 @@ declare class TokenBucketRateLimiter {
      */
     release(): void;
     /**
-     * Report a successful request (resets backoff)
+     * Report a successful request (gradually reduces backoff)
+     *
+     * Instead of immediately clearing backoff, we gradually reduce it to prevent
+     * immediately hitting the rate limit again after a single success.
      */
     reportSuccess(): void;
     /**
@@ -989,6 +992,8 @@ declare class HealthChecker {
     private logger;
     private results;
     private highestSeqno;
+    /** Rolling window of recent valid seqnos per network (for outlier-robust blocksBehind). */
+    private seqnoSamples;
     private rateLimiter;
     constructor(config?: Partial<HealthCheckConfig>, logger?: Logger, rateLimiter?: RateLimiterManager);
     /**
@@ -1004,6 +1009,7 @@ declare class HealthChecker {
      *
      * @param batchSize - Number of providers to test in parallel (default: 2)
      * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
+     *                       If not provided, calculates delay based on lowest RPS in batch
      */
     testProviders(providers: ResolvedProvider[], batchSize?: number, batchDelayMs?: number): Promise<ProviderHealthResult[]>;
     /**
@@ -1042,6 +1048,18 @@ declare class HealthChecker {
      */
     markOffline(providerId: string, network: Network, error?: string): void;
     private getResultKey;
+    /**
+     * Record a valid seqno sample and return an outlier-robust freshness baseline
+     * (median of recent samples for the network). Using the median instead of the
+     * raw maximum prevents a single provider that reports an inflated seqno from
+     * poisoning `blocksBehind` for every other (healthy) provider. See P2-2.
+     */
+    private recordSeqnoAndGetBaseline;
+    /**
+     * Detect a "non-JSON response" error (e.g. an HTML error page returned by a
+     * misbehaving gateway), used to decide whether to re-discover an Orbs endpoint.
+     */
+    private isNonJsonResponseError;
     /**
      * Get endpoint URL for a provider (handles dynamic providers like Orbs)
      */
@@ -1084,6 +1102,8 @@ interface SelectionConfig {
     freshnessWeight: number;
     /** Minimum acceptable provider status */
     minStatus: ProviderStatus[];
+    /** Cooldown period (ms) before retrying failed providers (default: 30000) */
+    retryCooldownMs: number;
 }
 /**
  * Provider Selector
@@ -1196,6 +1216,22 @@ declare class ProviderSelector {
      * 2. Health check result browserCompatible flag (if health check was performed)
      */
     private filterBrowserCompatible;
+    /**
+     * Check if an error is retryable (temporary) or permanent
+     *
+     * Permanent errors (never retry):
+     * - 404 (Not Found) - endpoint doesn't exist
+     * - 401 (Unauthorized) - invalid API key
+     * - Invalid API key errors
+     *
+     * Retryable errors (can retry after cooldown):
+     * - 503 (Service Unavailable) - temporary server issue
+     * - 502 (Bad Gateway) - temporary gateway issue
+     * - Timeout errors - network issues
+     * - Network errors - connection issues
+     * - 429 (Rate Limit) - temporary rate limit (handled separately)
+     */
+    private isRetryableError;
 }
 /**
  * Create a provider selector
@@ -1554,18 +1590,26 @@ declare class BrowserAdapter {
     getEndpointWithRateLimit(timeoutMs?: number): Promise<string>;
     /**
      * Make a JSON-RPC call to the TON API
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     jsonRpc<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
     /**
      * Get address state
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressState(address: string, timeoutMs?: number): Promise<'uninit' | 'active' | 'frozen'>;
     /**
      * Get address balance
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressBalance(address: string, timeoutMs?: number): Promise<bigint>;
     /**
      * Get address information
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     getAddressInfo(address: string, timeoutMs?: number): Promise<{
         state: 'uninit' | 'active' | 'frozen';
@@ -1575,6 +1619,8 @@ declare class BrowserAdapter {
     }>;
     /**
      * Run get method
+     *
+     * Note: Uses rate limiting to prevent 429 errors.
      */
     runGetMethod(address: string, method: string, stack?: unknown[], timeoutMs?: number): Promise<{
         exit_code: number;
@@ -1692,6 +1738,17 @@ declare function isValidHttpUrl(str: string): boolean;
  * Validate that a string is a valid WebSocket URL.
  */
 declare function isValidWsUrl(str: string): boolean;
+/**
+ * Redact credentials from an endpoint URL so it is safe to log.
+ *
+ * Masks (a) sensitive query-param values (`apikey`, `api_key`, `key`, `token`,
+ * `secret`, `password`), (b) credential-like path segments while preserving
+ * structural ones (`api`, `v2`, `v3`, `jsonRPC`, `rpc`, `public`, …), and
+ * (c) a credential-like leading host label (e.g. a QuickNode subdomain key).
+ *
+ * For logging only — never use the result to make requests.
+ */
+declare function redactUrl(url: string): string;
 
 /**
  * Unified Provider System - Timeout Utilities
@@ -2027,4 +2084,4 @@ declare class GenericProvider extends BaseProvider {
  */
 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 };
+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, redactUrl, resetNodeAdapter, resolveAllProviders, resolveEndpoints, resolveKeyPlaceholder, resolveProvider, sleep, toV2Base, toV3Base, withRetry, withTimeout, withTimeoutAndRetry, withTimeoutFn };