@atomiqlabs/chain-evm 2.1.12 → 2.1.14

package/src/evm/contract/EVMContractBase.ts

@@ -13,23 +13,39 @@ type KeysOfType<T, ValueType> = keyof {
     [K in keyof T]: T[K] extends ValueType ? K : never;
 };
 
+/**
+ * Typed transaction call decoded from calldata for a specific contract method.
+ *
+ * @category Internal/Contracts
+ */
 export interface TypedFunctionCall<TCMethod extends TypedContractMethod>
     extends Omit<TransactionDescription, "args"> {
     args: __TypechainOutputObject<TCMethod>;
 }
 
 /**
- * Base class providing program specific utilities
+ * Base contract wrapper providing typed event and calldata parsing helpers.
+ *
+ * @category Internal/Contracts
  */
 export class EVMContractBase<T extends BaseContract> {
 
-    contract: T;
+    readonly contract: T;
 
-    public readonly Events: EVMContractEvents<T>;
-    public readonly Chain: EVMChainInterface<any>;
+    /**
+     * @internal
+     */
+    readonly _Events: EVMContractEvents<T>;
+    protected readonly Chain: EVMChainInterface<any>;
 
-    public readonly contractAddress: string;
-    public readonly contractDeploymentHeight?: number;
+    /**
+     * @internal
+     */
+    readonly _contractAddress: string;
+    /**
+     * @internal
+     */
+    readonly _contractDeploymentHeight?: number;
 
     constructor(
         chainInterface: EVMChainInterface<any>,
@@ -39,26 +55,15 @@ export class EVMContractBase<T extends BaseContract> {
     ) {
         this.Chain = chainInterface;
         this.contract = new Contract(contractAddress, contractAbi, chainInterface.provider) as unknown as T;
-        this.Events = new EVMContractEvents<T>(chainInterface, this);
-        this.contractAddress = contractAddress;
-        this.contractDeploymentHeight = contractDeploymentHeight;
-    }
-
-    toTypedEvent<TEventName extends keyof T["filters"] = keyof T["filters"]>(log: Log): TypedEventLog<T["filters"][TEventName]> | null {
-        let foundFragment: EventFragment | null = null;
-        try {
-            foundFragment = this.contract.interface.getEvent(log.topics[0]);
-        } catch (error) { }
-        if(!foundFragment) return null;
-
-        try {
-            return new EventLog(log, this.contract.interface, foundFragment) as unknown as TypedEventLog<T["filters"][TEventName]>;
-        } catch (error: any) { }
-
-        return null;
+        this._Events = new EVMContractEvents<T>(chainInterface, this);
+        this._contractAddress = contractAddress;
+        this._contractDeploymentHeight = contractDeploymentHeight;
     }
 
-    parseCalldata<TMethod extends TypedContractMethod>(calldata: string): TypedFunctionCall<TMethod> {
+    /**
+     * @internal
+     */
+    protected parseCalldata<TMethod extends TypedContractMethod>(calldata: string): TypedFunctionCall<TMethod> {
         return this.contract.interface.parseTransaction({data: calldata}) as unknown as TypedFunctionCall<TMethod>;
     }
 

package/src/evm/contract/EVMContractModule.ts

@@ -4,6 +4,11 @@ import {EVMChainInterface} from "../chain/EVMChainInterface";
 import {EVMContractBase} from "./EVMContractBase";
 
 
+/**
+ * Base module class for EVM components tied to a specific contract wrapper.
+ *
+ * @category Internal/Contracts
+ */
 export class EVMContractModule<T extends BaseContract, C extends EVMContractBase<T> = EVMContractBase<T>> extends EVMModule<any> {
 
     readonly contract: C;

package/src/evm/contract/modules/EVMContractEvents.ts

@@ -1,8 +1,8 @@
-import {BaseContract, Log} from "ethers";
+import {BaseContract, EventFragment, EventLog, Log} from "ethers";
 import {EVMEvents} from "../../chain/modules/EVMEvents";
-import {EVMContractBase} from "../EVMContractBase";
+import {EVMContractBase, TypedFunctionCall} from "../EVMContractBase";
 import {EVMChainInterface} from "../../chain/EVMChainInterface";
-import {TypedEventLog} from "../../typechain/common";
+import {TypedContractMethod, TypedEventLog} from "../../typechain/common";
 
 function normalizeTopic(topic: string) {
     if(topic.length!==66) {
@@ -12,9 +12,14 @@ function normalizeTopic(topic: string) {
 }
 
 
+/**
+ * Typed contract event utilities built on top of generic EVM log querying helpers.
+ *
+ * @category Internal/Contracts
+ */
 export class EVMContractEvents<T extends BaseContract> extends EVMEvents {
 
-    readonly contract: EVMContractBase<T>;
+    private readonly contract: EVMContractBase<T>;
     readonly baseContract: T;
 
     constructor(chainInterface: EVMChainInterface<any>, contract: EVMContractBase<T>) {
@@ -23,8 +28,22 @@ export class EVMContractEvents<T extends BaseContract> extends EVMEvents {
         this.baseContract = contract.contract;
     }
 
-    public toTypedEvents<TEventName extends keyof T["filters"]>(blockEvents: Log[]): (TypedEventLog<T["filters"][TEventName]> | null)[] {
-        return blockEvents.map(log => this.contract.toTypedEvent<TEventName>(log));
+    private toTypedEvent<TEventName extends keyof T["filters"] = keyof T["filters"]>(log: Log): TypedEventLog<T["filters"][TEventName]> | null {
+        let foundFragment: EventFragment | null = null;
+        try {
+            foundFragment = this.baseContract.interface.getEvent(log.topics[0]);
+        } catch (error) { }
+        if(!foundFragment) return null;
+
+        try {
+            return new EventLog(log, this.baseContract.interface, foundFragment) as unknown as TypedEventLog<T["filters"][TEventName]>;
+        } catch (error: any) { }
+
+        return null;
+    }
+
+    toTypedEvents<TEventName extends keyof T["filters"]>(blockEvents: Log[]): (TypedEventLog<T["filters"][TEventName]> | null)[] {
+        return blockEvents.map(log => this.toTypedEvent<TEventName>(log));
     }
 
     private toFilter<TEventName extends keyof T["filters"]>(
@@ -83,7 +102,7 @@ export class EVMContractEvents<T extends BaseContract> extends EVMEvents {
                 if(result!=null) return result;
             }
             return null;
-        }, abortSignal, this.contract.contractDeploymentHeight);
+        }, abortSignal, this.contract._contractDeploymentHeight);
     }
 
     /**
@@ -111,7 +130,7 @@ export class EVMContractEvents<T extends BaseContract> extends EVMEvents {
                 if(result!=null) return result;
             }
             return null;
-        }, abortSignal, Math.max(this.contract.contractDeploymentHeight ?? 0, startHeight ?? 0));
+        }, abortSignal, Math.max(this.contract._contractDeploymentHeight ?? 0, startHeight ?? 0));
     }
 
 }

package/src/evm/events/EVMChainEvents.ts

@@ -6,6 +6,11 @@ import {EVMSwapContract} from "../swaps/EVMSwapContract";
 import {EVMSpvVaultContract} from "../spv_swap/EVMSpvVaultContract";
 
 
+/**
+ * Backend event listener with persisted polling cursor stored on filesystem.
+ *
+ * @category Events
+ */
 export class EVMChainEvents extends EVMChainEventsBrowser {
 
     private readonly directory: string;
@@ -77,6 +82,9 @@ export class EVMChainEvents extends EVMChainEventsBrowser {
         }).join(";"));
     }
 
+    /**
+     * @inheritDoc
+     */
     async init(noAutomaticPoll?: boolean): Promise<void> {
         if(noAutomaticPoll) return Promise.resolve();
         this.stopped = false;

package/src/evm/events/EVMChainEventsBrowser.ts

@@ -24,6 +24,12 @@ const LOGS_SLIDING_WINDOW_LENGTH = 60;
 
 const PROCESSED_EVENTS_BACKLOG = 1000;
 
+/**
+ * Current state of the EVM event listener, containing the last processed block number
+ *  and event position.
+ *
+ * @category Events
+ */
 export type EVMEventListenerState = {lastBlockNumber: number, lastEvent?: {blockHash: string, logIndex: number}} | null;
 
 type AtomiqTypedEvent = (
@@ -35,6 +41,8 @@ type AtomiqTypedEvent = (
  * EVM on-chain event handler for front-end systems without access to fs, uses WS or long-polling to subscribe, might lose
  *  out on some events if the network is unreliable, front-end systems should take this into consideration and not
  *  rely purely on events
+ *
+ * @category Events
  */
 export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventListenerState[]> {
 
@@ -44,23 +52,59 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
     private processedEvents: string[] = [];
     private processedEventsIndex: number = 0;
 
+    /**
+     * @internal
+     */
     protected readonly listeners: EventListener<EVMSwapData>[] = [];
+    /**
+     * @internal
+     */
     protected readonly provider: JsonRpcApiProvider;
+    /**
+     * @internal
+     */
     protected readonly chainInterface: EVMChainInterface;
+    /**
+     * @internal
+     */
     protected readonly evmSwapContract: EVMSwapContract;
+    /**
+     * @internal
+     */
     protected readonly evmSpvVaultContract: EVMSpvVaultContract<any>;
+    /**
+     * @internal
+     */
     protected readonly logger = getLogger("EVMChainEventsBrowser: ");
 
+    /**
+     * @internal
+     */
     protected stopped: boolean = true;
+    /**
+     * @internal
+     */
     protected pollIntervalSeconds: number;
 
     private timeout?: any;
 
     //Websocket
+    /**
+     * @internal
+     */
     protected readonly spvVaultContractLogFilter: EventFilter;
+    /**
+     * @internal
+     */
     protected readonly swapContractLogFilter: EventFilter;
 
+    /**
+     * @internal
+     */
     protected unconfirmedEventQueue: AtomiqTypedEvent[] = [];
+    /**
+     * @internal
+     */
     protected confirmedEventQueue: {event: AtomiqTypedEvent, block: Block}[] = [];
 
     constructor(
@@ -76,10 +120,10 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         this.pollIntervalSeconds = pollIntervalSeconds;
 
         this.spvVaultContractLogFilter = {
-            address: this.evmSpvVaultContract.contractAddress
+            address: this.evmSpvVaultContract._contractAddress
         };
         this.swapContractLogFilter = {
-            address: this.evmSwapContract.contractAddress
+            address: this.evmSwapContract._contractAddress
         };
     }
 
@@ -112,12 +156,12 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         }
     }
 
-    protected parseInitializeEvent(
+    private parseInitializeEvent(
         event: TypedEventLog<EscrowManager["filters"]["Initialize"]>
     ): InitializeEvent<EVMSwapData> | null {
         const escrowHash = event.args.escrowHash.substring(2);
         const claimHandlerHex = event.args.claimHandler;
-        const claimHandler = this.evmSwapContract.claimHandlersByAddress[claimHandlerHex.toLowerCase()];
+        const claimHandler = this.evmSwapContract._claimHandlersByAddress[claimHandlerHex.toLowerCase()];
         if(claimHandler==null) {
             this.logger.warn("parseInitializeEvent("+escrowHash+"): Unknown claim handler with claim: "+claimHandlerHex);
             return null;
@@ -132,7 +176,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         );
     }
 
-    protected parseRefundEvent(
+    private parseRefundEvent(
         event: TypedEventLog<EscrowManager["filters"]["Refund"]>
     ): RefundEvent<EVMSwapData> {
         const escrowHash = event.args.escrowHash.substring(2);
@@ -140,12 +184,12 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         return new RefundEvent<EVMSwapData>(escrowHash);
     }
 
-    protected parseClaimEvent(
+    private parseClaimEvent(
         event: TypedEventLog<EscrowManager["filters"]["Claim"]>
     ): ClaimEvent<EVMSwapData> | null {
         const escrowHash = event.args.escrowHash.substring(2);
         const claimHandlerHex = event.args.claimHandler;
-        const claimHandler = this.evmSwapContract.claimHandlersByAddress[claimHandlerHex.toLowerCase()];
+        const claimHandler = this.evmSwapContract._claimHandlersByAddress[claimHandlerHex.toLowerCase()];
         if(claimHandler==null) {
             this.logger.warn("parseClaimEvent("+escrowHash+"): Unknown claim handler with claim: "+claimHandlerHex);
             return null;
@@ -155,7 +199,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         return new ClaimEvent<EVMSwapData>(escrowHash, witnessResult);
     }
 
-    protected parseSpvOpenEvent(
+    private parseSpvOpenEvent(
         event: TypedEventLog<SpvVaultManager["filters"]["Opened"]>
     ): SpvVaultOpenEvent {
         const owner = event.args.owner;
@@ -167,7 +211,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         return new SpvVaultOpenEvent(owner, vaultId, btcTxId, vout);
     }
 
-    protected parseSpvDepositEvent(
+    private parseSpvDepositEvent(
         event: TypedEventLog<SpvVaultManager["filters"]["Deposited"]>
     ): SpvVaultDepositEvent {
         const [owner, vaultId] = unpackOwnerAndVaultId(event.args.ownerAndVaultId);
@@ -178,7 +222,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         return new SpvVaultDepositEvent(owner, vaultId, amounts, depositCount);
     }
 
-    protected parseSpvFrontEvent(
+    private parseSpvFrontEvent(
         event: TypedEventLog<SpvVaultManager["filters"]["Fronted"]>
     ): SpvVaultFrontEvent {
         const [owner, vaultId] = unpackOwnerAndVaultId(event.args.ownerAndVaultId);
@@ -193,7 +237,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         return new SpvVaultFrontEvent(owner, vaultId, btcTxId, recipient, executionHash, amounts, frontingAddress);
     }
 
-    protected parseSpvClaimEvent(
+    private parseSpvClaimEvent(
         event: TypedEventLog<SpvVaultManager["filters"]["Claimed"]>
     ): SpvVaultClaimEvent {
         const [owner, vaultId] = unpackOwnerAndVaultId(event.args.ownerAndVaultId);
@@ -211,7 +255,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         return new SpvVaultClaimEvent(owner, vaultId, btcTxId, recipient, executionHash, amounts, caller, frontingAddress, withdrawCount);
     }
 
-    protected parseSpvCloseEvent(
+    private parseSpvCloseEvent(
         event: TypedEventLog<SpvVaultManager["filters"]["Closed"]>
     ): SpvVaultCloseEvent {
         const btcTxId = Buffer.from(event.args.btcTxHash.substring(2), "hex").reverse().toString("hex");
@@ -226,7 +270,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
      * @param currentBlock
      * @protected
      */
-    protected async processEvents(
+    private async processEvents(
         events : (
             TypedEventLog<EscrowManager["filters"]["Initialize" | "Refund" | "Claim"]> |
             TypedEventLog<SpvVaultManager["filters"]["Opened" | "Deposited" | "Fronted" | "Claimed" | "Closed"]>
@@ -300,7 +344,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         }
     }
 
-    protected async checkEventsEcrowManager(
+    private async checkEventsEcrowManager(
         currentBlock: Block,
         lastEvent?: {blockHash: string, logIndex: number},
         lastBlockNumber?: number
@@ -311,7 +355,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
             return {lastEvent, lastBlockNumber};
         }
         // this.logger.debug(`checkEvents(EscrowManager): Requesting logs: ${lastBlockNumber}...${currentBlock.number}`);
-        let events = await this.evmSwapContract.Events.getContractBlockEvents(
+        let events = await this.evmSwapContract._Events.getContractBlockEvents(
             ["Initialize", "Claim", "Refund"],
             [],
             lastBlockNumber,
@@ -341,7 +385,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         return {lastEvent, lastBlockNumber};
     }
 
-    protected async checkEventsSpvVaults(
+    private async checkEventsSpvVaults(
         currentBlock: Block,
         lastEvent?: {blockHash: string, logIndex: number},
         lastBlockNumber?: number
@@ -352,7 +396,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
             return {lastEvent, lastBlockNumber};
         }
         // this.logger.debug(`checkEvents(SpvVaults): Requesting logs: ${lastBlockNumber}...${currentBlock.number}`);
-        let events = await this.evmSpvVaultContract.Events.getContractBlockEvents(
+        let events = await this.evmSpvVaultContract._Events.getContractBlockEvents(
             ["Opened", "Deposited", "Closed", "Fronted", "Claimed"],
             [],
             lastBlockNumber,
@@ -388,8 +432,8 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
     async poll(lastState?: EVMEventListenerState[]): Promise<EVMEventListenerState[]> {
         lastState ??= [];
 
-        const currentBlock = await this.provider.getBlock(this.chainInterface.config.safeBlockTag, false);
-        if(currentBlock==null) throw new Error(`Cannot fetch '${this.chainInterface.config.safeBlockTag}' block!`);
+        const currentBlock = await this.provider.getBlock(this.chainInterface._config.safeBlockTag, false);
+        if(currentBlock==null) throw new Error(`Cannot fetch '${this.chainInterface._config.safeBlockTag}' block!`);
 
         const resultEscrow = await this.checkEventsEcrowManager(currentBlock, lastState?.[0]?.lastEvent, lastState?.[0]?.lastBlockNumber);
         const resultSpvVault = await this.checkEventsSpvVaults(currentBlock, lastState?.[1]?.lastEvent, lastState?.[1]?.lastBlockNumber);
@@ -405,7 +449,7 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
     /**
      * Sets up event handlers listening for swap events over websocket
      *
-     * @protected
+     * @internal
      */
     protected async setupPoll(
         lastState?: EVMEventListenerState[],
@@ -428,26 +472,47 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
 
     //Websocket
 
+    /**
+     * @internal
+     */
     protected handleWsEvent(
         event: AtomiqTypedEvent
     ): Promise<void> {
-        if(this.chainInterface.config.safeBlockTag==="latest" || this.chainInterface.config.safeBlockTag==="pending") {
+        if(this.chainInterface._config.safeBlockTag==="latest" || this.chainInterface._config.safeBlockTag==="pending") {
             return this.processEvents([event]);
         }
         this.unconfirmedEventQueue.push(event);
         return this.addOrRemoveBlockListener();
     }
 
+    /**
+     * @internal
+     */
     protected spvVaultContractListener?: (log: Log) => void;
+    /**
+     * @internal
+     */
     protected swapContractListener?: (log: Log) => void;
+    /**
+     * @internal
+     */
     protected blockListener?: (blockNumber: number) => Promise<void>;
+    /**
+     * @internal
+     */
     protected finalityCheckTimer: any;
+    /**
+     * @internal
+     */
     protected wsStarted: boolean = false;
 
+    /**
+     * @internal
+     */
     protected async checkUnconfirmedEventsFinality() {
         if(this.unconfirmedEventQueue.length>0) {
-            const latestSafeBlock = await this.provider.getBlock(this.chainInterface.config.safeBlockTag);
-            if(latestSafeBlock==null) throw new Error(`Failed to fetch '${this.chainInterface.config.safeBlockTag}' block!`);
+            const latestSafeBlock = await this.provider.getBlock(this.chainInterface._config.safeBlockTag);
+            if(latestSafeBlock==null) throw new Error(`Failed to fetch '${this.chainInterface._config.safeBlockTag}' block!`);
 
             const events = this.unconfirmedEventQueue.filter(event => {
                 return event.blockNumber <= latestSafeBlock.number;
@@ -473,8 +538,11 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         }
     }
 
+    /**
+     * @internal
+     */
     protected async addOrRemoveBlockListener() {
-        if(this.chainInterface.config.finalityCheckStrategy?.type!=="blocks") return;
+        if(this.chainInterface._config.finalityCheckStrategy?.type!=="blocks") return;
         if(this.unconfirmedEventQueue.length>0 || this.confirmedEventQueue.length>0) {
             this.logger.debug(`addOrRemoveBlockListener(): Adding block listener, unconfirmed/confirmed event count: ${this.unconfirmedEventQueue.length + this.confirmedEventQueue.length}`);
             await this.provider.on("block", this.blockListener!);
@@ -484,6 +552,9 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
         }
     }
 
+    /**
+     * @internal
+     */
     protected async startFinalityCheckTimer() {
         let check: () => Promise<void>;
         check = async () => {
@@ -496,11 +567,14 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
                 }
             }
             if(!this.wsStarted) return;
-            this.finalityCheckTimer = setTimeout(check, this.chainInterface.config.finalityCheckStrategy?.delayMs ?? 5*1000);
+            this.finalityCheckTimer = setTimeout(check, this.chainInterface._config.finalityCheckStrategy?.delayMs ?? 5*1000);
         };
         await check();
     }
 
+    /**
+     * @internal
+     */
     protected async setupWebsocket() {
         this.wsStarted = true;
 
@@ -518,18 +592,18 @@ export class EVMChainEventsBrowser implements ChainEvents<EVMSwapData, EVMEventL
             await this.addOrRemoveBlockListener();
         }
 
-        if(this.chainInterface.config.safeBlockTag==="safe" || this.chainInterface.config.safeBlockTag==="finalized") {
-            if(this.chainInterface.config.finalityCheckStrategy?.type==="timer") this.startFinalityCheckTimer();
+        if(this.chainInterface._config.safeBlockTag==="safe" || this.chainInterface._config.safeBlockTag==="finalized") {
+            if(this.chainInterface._config.finalityCheckStrategy?.type==="timer") this.startFinalityCheckTimer();
         }
 
         await this.provider.on(this.spvVaultContractLogFilter, this.spvVaultContractListener = (log) => {
-            let [event] = this.evmSpvVaultContract.Events.toTypedEvents([log]);
+            let [event] = this.evmSpvVaultContract._Events.toTypedEvents([log]);
             if(event==null || event.removed) return;
             this.handleWsEvent(event);
         });
 
         await this.provider.on(this.swapContractLogFilter, this.swapContractListener = (log) => {
-            let [event] = this.evmSwapContract.Events.toTypedEvents([log]);
+            let [event] = this.evmSwapContract._Events.toTypedEvents([log]);
             if(event==null || event.removed) return;
             if(event.eventName!=="Initialize" && event.eventName!=="Refund" && event.eventName!=="Claim") return;
             this.handleWsEvent(event);

package/src/evm/providers/JsonRpcProviderWithRetries.ts

@@ -8,6 +8,8 @@ import {
 } from "../../utils/Utils";
 
 /**
+ * JSON-RPC provider with built-in retry functionality for transient RPC failures.
+ *
  * @category Providers
  */
 export class JsonRpcProviderWithRetries extends JsonRpcProvider {
@@ -16,6 +18,13 @@ export class JsonRpcProviderWithRetries extends JsonRpcProvider {
         maxRetries?: number, delay?: number, exponential?: boolean
     };
 
+    /**
+     * Creates a new JSON-RPC provider which retries RPC calls based on the provided policy.
+     *
+     * @param url
+     * @param network
+     * @param options
+     */
     constructor(url: string | FetchRequest, network?: Networkish, options?: JsonRpcApiProviderOptions & {
         maxRetries?: number, delay?: number, exponential?: boolean, timeout?: number
     }) {
@@ -34,4 +43,4 @@ export class JsonRpcProviderWithRetries extends JsonRpcProvider {
         });
     }
 
-}
+}

package/src/evm/providers/ReconnectingWebSocketProvider.ts

@@ -5,6 +5,11 @@ import {getLogger} from "../../utils/Utils";
 
 const logger = getLogger("ReconnectingWebSocketProvider: ");
 
+/**
+ * WebSocket RPC provider with automatic reconnect, heartbeat ping and connection timeout handling.
+ *
+ * @category Providers
+ */
 export class ReconnectingWebSocketProvider extends SocketProvider {
 
     requestTimeoutSeconds: number = 10;
@@ -105,4 +110,4 @@ export class ReconnectingWebSocketProvider extends SocketProvider {
         super.destroy();
     }
 
-}
+}

package/src/evm/providers/WebSocketProviderWithRetries.ts

@@ -10,6 +10,8 @@ import {ReconnectingWebSocketProvider} from "./ReconnectingWebSocketProvider";
 import type {WebSocketLike} from "ethers/lib.esm";
 
 /**
+ * WebSocket RPC provider with reconnect support and retry logic for transient RPC failures.
+ *
  * @category Providers
  */
 export class WebSocketProviderWithRetries extends ReconnectingWebSocketProvider {
@@ -18,6 +20,13 @@ export class WebSocketProviderWithRetries extends ReconnectingWebSocketProvider
         maxRetries?: number, delay?: number, exponential?: boolean
     };
 
+    /**
+     * Creates a new WebSocket provider which retries RPC calls based on the provided policy.
+     *
+     * @param url
+     * @param network
+     * @param options
+     */
     constructor(url: string | (() => WebSocketLike), network?: Networkish, options?: JsonRpcApiProviderOptions & {
         maxRetries?: number, delay?: number, exponential?: boolean
     }) {
@@ -34,4 +43,4 @@ export class WebSocketProviderWithRetries extends ReconnectingWebSocketProvider
         });
     }
 
-}
+}