fix: fix waitfortransaction for rotating nodes services with lifeCycleRetries default 3

Author: tabaktoni

src/channel/rpc_0_8_1.ts

@@ -396,21 +396,22 @@ export class RpcChannel {
 
   public async waitForTransaction(txHash: BigNumberish, options?: waitForTransactionOptions) {
     const transactionHash = toHex(txHash);
-    let { retries } = this;
+    let retries = options?.retries ?? this.retries;
+    let lifeCycleRetries = options?.lifeCycleRetries ?? 3;
     let onchain = false;
     let isErrorState = false;
     const retryInterval = options?.retryInterval ?? this.transactionRetryIntervalDefault;
-    const errorStates: any = options?.errorStates ?? [
-      RPC.ETransactionStatus.REJECTED,
-      // TODO: commented out to preserve the long-standing behavior of "reverted" not being treated as an error by default
-      // should decide which behavior to keep in the future
-      // RPC.ETransactionExecutionStatus.REVERTED,
-    ];
+    const errorStates: any = options?.errorStates ?? [RPC.ETransactionStatus.REJECTED];
     const successStates: any = options?.successStates ?? [
       // RPC.ETransactionExecutionStatus.SUCCEEDED, Starknet 0.14.0 this one can have incomplete events
       RPC.ETransactionStatus.ACCEPTED_ON_L2,
       RPC.ETransactionStatus.ACCEPTED_ON_L1,
     ];
+    const LifeCycleErrorMessages: Record<string, string> = {
+      [RPCSPEC09.ETransactionStatus.RECEIVED]: SYSTEM_MESSAGES.txEvictedFromMempool,
+      [RPCSPEC09.ETransactionStatus.PRE_CONFIRMED]: SYSTEM_MESSAGES.consensusFailed,
+      [RPCSPEC09.ETransactionStatus.CANDIDATE]: SYSTEM_MESSAGES.txFailsBlockBuildingValidation,
+    };
 
     const txLife: string[] = [];
     let txStatus: RPC.TransactionStatus;
@@ -451,16 +452,11 @@ export class RpcChannel {
 
         if (error instanceof RpcError && error.isType('TXN_HASH_NOT_FOUND')) {
           logger.info('txLife: ', txLife);
-          const errorMessages: Record<string, string> = {
-            [RPCSPEC09.ETransactionStatus.RECEIVED]: SYSTEM_MESSAGES.txEvictedFromMempool,
-            [RPCSPEC09.ETransactionStatus.PRE_CONFIRMED]: SYSTEM_MESSAGES.consensusFailed,
-            [RPCSPEC09.ETransactionStatus.CANDIDATE]:
-              SYSTEM_MESSAGES.txFailsBlockBuildingValidation,
-          };
-          const errorMessage = errorMessages[txLife.at(-1) as string];
-          if (errorMessage) {
+          const errorMessage = LifeCycleErrorMessages[txLife.at(-1) as string];
+          if (errorMessage && lifeCycleRetries <= 0) {
             throw new Error(errorMessage);
           }
+          lifeCycleRetries -= 1;
         }
 
         if (retries <= 0) {

src/channel/rpc_0_9_0.ts

@@ -403,7 +403,8 @@ export class RpcChannel {
 
   public async waitForTransaction(txHash: BigNumberish, options?: waitForTransactionOptions) {
     const transactionHash = toHex(txHash);
-    let { retries } = this;
+    let retries = options?.retries ?? this.retries;
+    let lifeCycleRetries = options?.lifeCycleRetries ?? 3;
     let onchain = false;
     let isErrorState = false;
     const retryInterval = options?.retryInterval ?? this.transactionRetryIntervalDefault;
@@ -413,6 +414,11 @@ export class RpcChannel {
       RPC.ETransactionFinalityStatus.ACCEPTED_ON_L2,
       RPC.ETransactionFinalityStatus.ACCEPTED_ON_L1,
     ];
+    const errorMessages: Record<string, string> = {
+      [RPC.ETransactionStatus.RECEIVED]: SYSTEM_MESSAGES.txEvictedFromMempool,
+      [RPC.ETransactionStatus.PRE_CONFIRMED]: SYSTEM_MESSAGES.consensusFailed,
+      [RPC.ETransactionStatus.CANDIDATE]: SYSTEM_MESSAGES.txFailsBlockBuildingValidation,
+    };
 
     const txLife: string[] = [];
     let txStatus: RPC.TransactionStatus;
@@ -453,15 +459,11 @@ export class RpcChannel {
 
         if (error instanceof RpcError && error.isType('TXN_HASH_NOT_FOUND')) {
           logger.info('txLife: ', txLife);
-          const errorMessages: Record<string, string> = {
-            [RPC.ETransactionStatus.RECEIVED]: SYSTEM_MESSAGES.txEvictedFromMempool,
-            [RPC.ETransactionStatus.PRE_CONFIRMED]: SYSTEM_MESSAGES.consensusFailed,
-            [RPC.ETransactionStatus.CANDIDATE]: SYSTEM_MESSAGES.txFailsBlockBuildingValidation,
-          };
           const errorMessage = errorMessages[txLife.at(-1) as string];
-          if (errorMessage) {
+          if (errorMessage && lifeCycleRetries <= 0) {
             throw new Error(errorMessage);
           }
+          lifeCycleRetries -= 1;
         }
 
         if (retries <= 0) {

src/provider/types/configuration.type.ts

@@ -1,13 +1,22 @@
 import { NetworkName, StarknetChainId, SupportedRpcVersion } from '../../global/constants';
-import { BlockIdentifier } from '../../types/lib';
+import { BlockIdentifier, waitForTransactionOptions } from '../../types/lib';
 import { ResourceBoundsOverhead } from './spec.type';
 
 export interface ProviderOptions extends RpcProviderOptions {}
 
 export type RpcProviderOptions = {
   nodeUrl?: string | NetworkName;
-  retries?: number;
+  /**
+   * Define the number of retries for waitForTransaction
+   */
+  retries?: waitForTransactionOptions['retries'];
+  /**
+   * Define the time interval between retries in milliseconds
+   */
   transactionRetryIntervalFallback?: number;
+  /**
+   * Define the headers
+   */
   headers?: object;
   blockIdentifier?: BlockIdentifier;
   chainId?: StarknetChainId;

src/types/lib/index.ts

@@ -313,8 +313,26 @@ export type ParsedStruct = {
 };
 
 export type waitForTransactionOptions = {
+  /**
+   * Define the number of retries before throwing an error for the transaction life cycle when the transaction is not found after it had a valid status.
+   * This is useful for nodes that are not fully synced yet when connecting to service that rotate nodes.
+   */
+  lifeCycleRetries?: number;
+  /**
+   * Define the number of retries before throwing an error
+   */
+  retries?: number;
+  /**
+   * Define the time interval between retries in milliseconds
+   */
   retryInterval?: number;
+  /**
+   * Define which states are considered as successful
+   */
   successStates?: Array<TransactionFinalityStatus | TransactionExecutionStatus>;
+  /**
+   * Define which states are considered as errors
+   */
   errorStates?: Array<TransactionFinalityStatus | TransactionExecutionStatus>;
 };