ton-provider-system 0.2.4 → 0.3.0

package/dist/index.d.cts

@@ -992,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);
     /**
@@ -1046,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)
      */
@@ -1724,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
@@ -2059,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

@@ -992,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);
     /**
@@ -1046,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)
      */
@@ -1724,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
@@ -2059,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 };