ton-provider-system 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -1368,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)
      */
@@ -1416,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)
  */
@@ -1701,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

@@ -1368,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)
      */
@@ -1416,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)
  */
@@ -1701,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.js

@@ -1895,10 +1895,20 @@ var _ProviderManager = class _ProviderManager {
     this.rateLimiter = createRateLimiterManager(this.options.logger);
     for (const provider of this.registry.getAllProviders()) {
       const config2 = getRateLimitForType(provider.type);
+      const minDelayMs = Math.ceil(1e3 / provider.rps * 1.1);
+      let burstSize;
+      if (provider.rps <= 3) {
+        burstSize = 1;
+      } else if (provider.rps <= 5) {
+        burstSize = 2;
+      } else {
+        burstSize = Math.max(3, Math.ceil(provider.rps * 1.5));
+      }
       this.rateLimiter.setConfig(provider.id, {
         ...config2,
         rps: provider.rps,
-        minDelayMs: Math.ceil(1e3 / provider.rps)
+        minDelayMs,
+        burstSize
       });
     }
     this.healthChecker = createHealthChecker(
@@ -2304,6 +2314,17 @@ var NodeAdapter = class {
    * 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
+   * ```
    */
   async getClient() {
     const endpoint = await this.manager.getEndpoint();
@@ -2329,6 +2350,19 @@ var NodeAdapter = class {
     this.logger.debug(`Created TonClient for ${network}`, { endpoint });
     return client;
   }
+  /**
+   * 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.
+   */
+  async getClientWithRateLimit(timeoutMs) {
+    await this.manager.getEndpointWithRateLimit(timeoutMs);
+    return this.getClient();
+  }
   /**
    * Reset client cache (forces new client creation)
    */
@@ -2514,6 +2548,22 @@ async function getTonClient(manager) {
   const adapter = new NodeAdapter(manager);
   return adapter.getClient();
 }
+async function getTonClientWithRateLimit(manager) {
+  const adapter = new NodeAdapter(manager);
+  const client = await adapter.getClient();
+  const withRateLimit = async (fn) => {
+    await manager.getEndpointWithRateLimit();
+    try {
+      const result = await fn();
+      manager.reportSuccess();
+      return result;
+    } catch (error) {
+      manager.reportError(error);
+      throw error;
+    }
+  };
+  return { client, withRateLimit };
+}
 async function getTonClientForNetwork(network, configPath) {
   const manager = ProviderManager.getInstance({ configPath });
   if (!manager.isInitialized() || manager.getNetwork() !== network) {
@@ -2798,6 +2848,6 @@ async function createBrowserAdapterForNetwork(network, configPath, logger) {
   return new BrowserAdapter(manager, logger);
 }
 
-export { ApiVersionSchema, BrowserAdapter, CHAINSTACK_RATE_LIMIT, ConfigError, DEFAULT_CONTRACT_TIMEOUT_MS, DEFAULT_HEALTH_CHECK_TIMEOUT_MS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_TIMEOUT_MS, DEFAULT_RATE_LIMIT, HealthChecker, NetworkSchema, NodeAdapter, ORBS_RATE_LIMIT, ProviderConfigSchema, ProviderError, ProviderManager, ProviderRegistry, ProviderSelector, ProviderTypeSchema, QUICKNODE_RATE_LIMIT, RateLimitError, RateLimiterManager, RpcConfigSchema, TimeoutError, TokenBucketRateLimiter, 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 { ApiVersionSchema, BrowserAdapter, CHAINSTACK_RATE_LIMIT, ConfigError, DEFAULT_CONTRACT_TIMEOUT_MS, DEFAULT_HEALTH_CHECK_TIMEOUT_MS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_TIMEOUT_MS, DEFAULT_RATE_LIMIT, HealthChecker, NetworkSchema, NodeAdapter, ORBS_RATE_LIMIT, ProviderConfigSchema, ProviderError, ProviderManager, ProviderRegistry, ProviderSelector, ProviderTypeSchema, QUICKNODE_RATE_LIMIT, RateLimitError, RateLimiterManager, RpcConfigSchema, TimeoutError, TokenBucketRateLimiter, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map