@lido-nestjs/execution 1.15.0 → 1.17.0

package/dist/error/index.d.ts

@@ -2,3 +2,4 @@ export * from './all-providers-failed.error';
 export * from './fetch.error';
 export * from './no-new-blocks-while-polling.error';
 export * from './request-timeout.error';
+export * from './transaction-wait-timeout.error';

package/dist/error/transaction-wait-timeout.error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Thrown when waitForTransactionWithFallback times out.
+ * lastError distinguishes network issues (present) from slow tx (null).
+ */
+export declare class TransactionWaitTimeoutError extends Error {
+    name: string;
+    txHash: string;
+    timeoutMs: number;
+    lastError: Error | null;
+    constructor(txHash: string, timeoutMs: number, lastError: Error | null);
+}

package/dist/error/transaction-wait-timeout.error.js

@@ -0,0 +1,24 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Thrown when waitForTransactionWithFallback times out.
+ * lastError distinguishes network issues (present) from slow tx (null).
+ */
+class TransactionWaitTimeoutError extends Error {
+    constructor(txHash, timeoutMs, lastError) {
+        const baseMessage = `Transaction ${txHash} not confirmed within ${timeoutMs}ms`;
+        const errorContext = lastError
+            ? `. Last provider error: ${lastError.message}`
+            : ' (no provider errors, transaction may still be pending)';
+        super(baseMessage + errorContext);
+        this.name = 'TransactionWaitTimeoutError';
+        this.txHash = txHash;
+        this.timeoutMs = timeoutMs;
+        this.lastError = lastError;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+exports.TransactionWaitTimeoutError = TransactionWaitTimeoutError;

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './interfaces/fallback-provider';
 export * from './interfaces/simple-fallback-provider-config';
 export * from './interfaces/module.options';
 export * from './interfaces/non-empty-array';
+export * from './interfaces/wait-for-transaction';
 export * from './ethers/fee-history';
 export * from './ethers/block-tag';
 export * from './error';

package/dist/index.js

@@ -12,6 +12,7 @@ var allProvidersFailed_error = require('./error/all-providers-failed.error.js');
 var fetch_error = require('./error/fetch.error.js');
 var noNewBlocksWhilePolling_error = require('./error/no-new-blocks-while-polling.error.js');
 var requestTimeout_error = require('./error/request-timeout.error.js');
+var transactionWaitTimeout_error = require('./error/transaction-wait-timeout.error.js');
 
 
 
@@ -39,3 +40,4 @@ exports.AllProvidersFailedError = allProvidersFailed_error.AllProvidersFailedErr
 exports.FetchError = fetch_error.FetchError;
 exports.NoNewBlocksWhilePollingError = noNewBlocksWhilePolling_error.NoNewBlocksWhilePollingError;
 exports.RequestTimeoutError = requestTimeout_error.RequestTimeoutError;
+exports.TransactionWaitTimeoutError = transactionWaitTimeout_error.TransactionWaitTimeoutError;

package/dist/interfaces/simple-fallback-provider-config.d.ts

@@ -15,4 +15,5 @@ export interface SimpleFallbackProviderConfig {
     fetchMiddlewares?: MiddlewareCallback<Promise<any>>[];
     maxTimeWithoutNewBlocksMs?: number;
     requestTimeoutMs?: number;
+    instanceLabel?: string;
 }

package/dist/interfaces/wait-for-transaction.d.ts

@@ -0,0 +1,14 @@
+import { TransactionReceipt } from '@ethersproject/abstract-provider';
+export interface WaitForTransactionOptions {
+    /** Max wait time in ms. @default 60000 */
+    timeout?: number;
+    /** Polling interval in ms. @default 3000 */
+    pollInterval?: number;
+    /** Required confirmations. @default 1 */
+    confirmations?: number;
+}
+export interface WaitForTransactionResult {
+    receipt: TransactionReceipt;
+    pollCount: number;
+    elapsedMs: number;
+}

package/dist/provider/simple-fallback-json-rpc-batch-provider.d.ts

@@ -10,6 +10,7 @@ import { BigNumber, BigNumberish } from '@ethersproject/bignumber';
 import { Deferrable } from '@ethersproject/properties';
 import { EventType, Listener } from '@ethersproject/abstract-provider';
 import { FeeHistory } from '../ethers/fee-history';
+import { WaitForTransactionOptions, WaitForTransactionResult } from '../interfaces/wait-for-transaction';
 import { TraceConfig, TraceResult } from '../interfaces/debug-traces';
 import { FallbackProviderEvents } from '../events';
 /**
@@ -46,6 +47,7 @@ export declare class SimpleFallbackJsonRpcBatchProvider extends BaseProvider {
     constructor(config: SimpleFallbackProviderConfig, logger: LoggerService);
     static _formatter: Formatter | null;
     static getFormatter(): Formatter;
+    protected formatLog(message: string, providerIndex?: number): string;
     on(eventName: EventType, listener: Listener): this;
     getFeeHistory(blockCount: number, newestBlock?: string | null | number, rewardPercentiles?: number[]): Promise<FeeHistory>;
     getDebugTraceBlockByHash(blockHash: string, traceConfig: Partial<TraceConfig>): Promise<TraceResult[]>;
@@ -61,4 +63,16 @@ export declare class SimpleFallbackJsonRpcBatchProvider extends BaseProvider {
     protected networksEqual(networkA: Network, networkB: Network): boolean;
     get activeProviderIndex(): number;
     get eventEmitter(): SimpleFallbackJsonRpcBatchProviderEventEmitter;
+    /**
+     * Waits for transaction confirmation with fallback provider support.
+     *
+     * Use instead of tx.wait() which hangs forever when providers fail:
+     * - node_modules/@ethersproject/providers/src.ts/base-provider.ts:1055 - polling calls getTransactionReceipt
+     * - node_modules/@ethersproject/providers/src.ts/base-provider.ts:1060 - .catch(e => emit("error", e)) swallows error
+     * - node_modules/@ethersproject/providers/src.ts/base-provider.ts:1313 - waits for event that never comes
+     * - node_modules/@ethersproject/providers/src.ts/base-provider.ts:1412 - timeout=0 by default, no reject
+     *
+     * This method polls via perform() with fallback and always returns/throws.
+     */
+    waitForTransactionWithFallback(txHash: string, options?: WaitForTransactionOptions): Promise<WaitForTransactionResult>;
 }

package/dist/provider/simple-fallback-json-rpc-batch-provider.js

@@ -7,18 +7,21 @@ var providers = require('@ethersproject/providers');
 var extendedJsonRpcBatchProvider = require('./extended-json-rpc-batch-provider.js');
 var common = require('@nestjs/common');
 var retrier = require('../common/retrier.js');
+var sleep = require('../common/sleep.js');
 var formatterWithEip1898 = require('../ethers/formatter-with-eip1898.js');
 var networks = require('../common/networks.js');
 var noNewBlocksWhilePolling_error = require('../error/no-new-blocks-while-polling.error.js');
 var errors = require('../common/errors.js');
 var allProvidersFailed_error = require('../error/all-providers-failed.error.js');
 var requestTimeout_error = require('../error/request-timeout.error.js');
+var transactionWaitTimeout_error = require('../error/transaction-wait-timeout.error.js');
 var feeHistory = require('../ethers/fee-history.js');
 var debugTraceBlockByHash = require('../ethers/debug-trace-block-by-hash.js');
 var events = require('events');
 
 exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchProvider extends providers.BaseProvider {
     constructor(config, logger) {
+        var _a;
         super(config.network);
         this.detectNetworkFirstRun = true;
         this.resetTimer = null;
@@ -55,6 +58,22 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
             };
         });
         this.activeFallbackProviderIndex = 0;
+        // Log initialization info
+        const configInfo = {
+            providers: conns.length,
+            network: this.config.network,
+            requestPolicy: this.config.requestPolicy,
+            maxRetries: this.config.maxRetries,
+            minBackoffMs: this.config.minBackoffMs,
+            maxBackoffMs: this.config.maxBackoffMs,
+            logRetries: this.config.logRetries,
+            resetIntervalMs: this.config.resetIntervalMs,
+            fetchMiddlewares: ((_a = this.config.fetchMiddlewares) === null || _a === void 0 ? void 0 : _a.length) || 0,
+            maxTimeWithoutNewBlocksMs: this.config.maxTimeWithoutNewBlocksMs,
+            requestTimeoutMs: this.config.requestTimeoutMs || 'disabled',
+            instanceLabel: this.config.instanceLabel || 'none',
+        };
+        this.logger.log(this.formatLog(`Initialized SimpleFallbackJsonRpcBatchProvider: ${JSON.stringify(configInfo)}`));
     }
     static getFormatter() {
         if (this._formatter == null) {
@@ -62,6 +81,19 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
         }
         return this._formatter;
     }
+    formatLog(message, providerIndex) {
+        const parts = [];
+        if (this.config.instanceLabel) {
+            parts.push(`[${this.config.instanceLabel}]`);
+        }
+        if (providerIndex !== undefined) {
+            parts.push(`[provider:${providerIndex}]`);
+        }
+        if (parts.length > 0) {
+            return `${parts.join('')} ${message}`;
+        }
+        return message;
+    }
     on(eventName, listener) {
         let dieTimer = null;
         const startDieTimer = (latestObservedBlockNumber) => {
@@ -110,11 +142,13 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
     }
     switchToNextProvider() {
         if (this.fallbackProviders.length === 1) {
-            this.logger.warn('Will not switch to next provider. No valid backup provider provided.');
+            this.logger.warn(this.formatLog('Will not switch to next provider. No valid backup provider provided.'));
             return;
         }
-        this.activeFallbackProviderIndex++;
-        this.logger.log(`Switched to next provider for execution layer`);
+        const oldIndex = this.activeFallbackProviderIndex;
+        this.activeFallbackProviderIndex =
+            (this.activeFallbackProviderIndex + 1) % this.fallbackProviders.length;
+        this.logger.log(this.formatLog(`Switched provider: [${oldIndex}] -> [${this.activeFallbackProviderIndex}] (total: ${this.fallbackProviders.length})`));
     }
     isNonRetryableError(error) {
         return (!errors.isEthersServerError(error) &&
@@ -141,9 +175,11 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
             try {
                 let performRetryAttempt = 0;
                 attempt++;
+                // Log which provider we're attempting to use
+                this.logger.log(this.formatLog(`Attempting request (attempt ${attempt}/${this.fallbackProviders.length})`, this.activeFallbackProviderIndex));
                 // awaiting is extremely important here
                 // without it, the error will not be caught in current try-catch scope
-                return await retry(() => {
+                const result = await retry(() => {
                     const provider = this.provider;
                     const event = {
                         action: 'fallback-provider:request',
@@ -162,6 +198,9 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
                     }
                     return performPromise;
                 });
+                // Log successful request
+                this.logger.log(this.formatLog(`Request successful after ${performRetryAttempt} retry attempt(s)`, this.activeFallbackProviderIndex));
+                return result;
             }
             catch (e) {
                 this.lastError = e;
@@ -173,10 +212,22 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
                         error: e,
                     };
                     this._eventEmitter.emit('rpc', event);
+                    // Log context (label + provider index) synchronously before error object
+                    // to ensure proper ordering in async logging systems
+                    this.logger.error(this.formatLog(`Non-retryable error occurred`, this.activeFallbackProviderIndex));
+                    this.logger.error(e);
                     throw e;
                 }
-                this.logger.error('Error while doing ETH1 RPC request. Will try to switch to another provider');
-                this.logger.error(e);
+                // Log context (label + provider index) synchronously before error object
+                // to ensure proper ordering in async logging systems
+                if (e instanceof requestTimeout_error.RequestTimeoutError) {
+                    this.logger.error(this.formatLog(`Request timeout after ${e.timeoutMs}ms. Will switch to next provider.`, this.activeFallbackProviderIndex));
+                    this.logger.error(e);
+                }
+                else {
+                    this.logger.error(this.formatLog(`Error occurred. Will switch to next provider.`, this.activeFallbackProviderIndex));
+                    this.logger.error(e);
+                }
                 // This check is needed to avoid multiple `switchToNextProvider` calls when doing one JSON-RPC batch.
                 // This can happen when multiple N calls to `perform` are batched in one JSON-RPC request and
                 // that request fails and throws `Error`. This `Error` is bubbled N times to corresponding `perform` calls.
@@ -234,7 +285,7 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
                     if (this.detectNetworkFirstRun) {
                         throw new Error(`Fallback provider [${index}] network is different to other provider's networks`);
                     }
-                    this.logger.warn(`Fallback provider [${index}] network is different to other provider's networks`);
+                    this.logger.warn(this.formatLog(`Fallback provider [${index}] network is different to other provider's networks`));
                 }
             }
             else {
@@ -261,7 +312,7 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
         if (this.resetTimer) {
             clearTimeout(this.resetTimer);
         }
-        this.fallbackProviders.forEach((fallbackProvider, index) => {
+        this.fallbackProviders.forEach((_, index) => {
             var _a;
             if (!((_a = this.fallbackProviders[index].network) === null || _a === void 0 ? void 0 : _a.chainId)) {
                 this.fallbackProviders[index].unreachable = false;
@@ -278,6 +329,49 @@ exports.SimpleFallbackJsonRpcBatchProvider = class SimpleFallbackJsonRpcBatchPro
     get eventEmitter() {
         return this._eventEmitter;
     }
+    /**
+     * Waits for transaction confirmation with fallback provider support.
+     *
+     * Use instead of tx.wait() which hangs forever when providers fail:
+     * - node_modules/@ethersproject/providers/src.ts/base-provider.ts:1055 - polling calls getTransactionReceipt
+     * - node_modules/@ethersproject/providers/src.ts/base-provider.ts:1060 - .catch(e => emit("error", e)) swallows error
+     * - node_modules/@ethersproject/providers/src.ts/base-provider.ts:1313 - waits for event that never comes
+     * - node_modules/@ethersproject/providers/src.ts/base-provider.ts:1412 - timeout=0 by default, no reject
+     *
+     * This method polls via perform() with fallback and always returns/throws.
+     */
+    async waitForTransactionWithFallback(txHash, options = {}) {
+        const { timeout = 60000, pollInterval = 3000, confirmations = 1, } = options;
+        const startTime = Date.now();
+        let lastError = null;
+        let pollCount = 0;
+        this.logger.log(this.formatLog(`Starting waitForTransactionWithFallback for ${txHash} (timeout: ${timeout}ms, pollInterval: ${pollInterval}ms, confirmations: ${confirmations})`));
+        while (Date.now() - startTime < timeout) {
+            pollCount++;
+            try {
+                // Uses perform() which handles fallback switching automatically
+                const receipt = await this.getTransactionReceipt(txHash);
+                if (receipt && receipt.confirmations >= confirmations) {
+                    const elapsedMs = Date.now() - startTime;
+                    this.logger.log(this.formatLog(`Transaction ${txHash} confirmed after ${pollCount} polls (${elapsedMs}ms, ${receipt.confirmations} confirmations)`));
+                    return { receipt, pollCount, elapsedMs };
+                }
+                lastError = null;
+            }
+            catch (error) {
+                // All providers failed - log and retry until timeout
+                lastError = error;
+                this.logger.warn(this.formatLog(`waitForTransactionWithFallback poll #${pollCount} failed for ${txHash}: ${error}`));
+            }
+            await sleep.sleep(pollInterval);
+        }
+        const elapsedMs = Date.now() - startTime;
+        const errorContext = lastError
+            ? `All providers failed on last poll: ${lastError.message}`
+            : 'Transaction not found in any block';
+        this.logger.error(this.formatLog(`waitForTransactionWithFallback timeout for ${txHash} after ${pollCount} polls (${elapsedMs}ms). ${errorContext}`));
+        throw new transactionWaitTimeout_error.TransactionWaitTimeoutError(txHash, timeout, lastError);
+    }
 };
 exports.SimpleFallbackJsonRpcBatchProvider._formatter = null;
 exports.SimpleFallbackJsonRpcBatchProvider = tslib.__decorate([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lido-nestjs/execution",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "MIT",