@woof-software/contracts-tools-sdk-ethers 0.0.21 → 0.0.23

package/README.md

@@ -1,8 +1,561 @@
 # @woof-software/contracts-tools-sdk-ethers
 
-Provides logic for ethers interactions.
+## Description
 
+**contracts-tools-sdk-ethers** is a lightweight zero-dependency TypeScript library built on top of [ethers.js](https://github.com/ethers-io/ethers.js) designed to simplify **smart contract** interactions and [multicall3](https://www.multicall3.com/) aggregation on the Ethereum blockchain and other EVM-compatible networks.\
+All of these tools are compatible with TypeScript.\
+JSDoc is provided.
 ---
 
+## Installation
 
-### See original [README](https://github.com/neuroborus/ethers-tools/blob/main/README.md)
+```bash
+npm install @woof-software/contracts-tools-sdk-ethers ethers
+```
+
+> **Note:** Requires `ethers@^6.0.0` as a peer dependency.
+
+---
+
+## Quickstart
+
+### **MulticallProvider**
+
+```typescript
+import { ethers } from 'ethers';
+
+export const PROVIDER = new ethers.WebSocketProvider(RPC_URL);
+// !: Here is an extra step
+export const MULTICALL_PROVIDER = new MulticallProvider(PROVIDER); 
+export const WALLET = new ethers.Wallet(
+  '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+  MULTICALL_PROVIDER
+);
+
+export const contract = new ethers.Contract(
+  '0xa513E6E4b8f2a923D98304ec87F64353C4D5C853',
+  StorageAbi,
+  WALLET
+);
+
+const [first, second, both, writeCount, setFirstTx, setSecondTx] =
+  await Promise.all([
+    contract['getFirst'](),
+    contract['getSecond'](),
+    contract['getBoth'](),
+    contract['getWriteCount'](),
+    contract['setFirst'](42),
+  ]); // All calls for that event loop iteration will execute as a multicall batch.
+
+/*
+ * Since transactions are managed by the Signer, unlike with a pure MulticallUnit,
+ * view calls are typically executed before write transactions.
+ * */
+
+expect(typeof first).to.be.eq('bigint');
+```
+
+### **MulticallUnit and BaseContract usage**
+
+```typescript
+import { ethers } from 'ethers';
+import { BaseContract, ContractCall, MulticallUnit } from '@woof-software/contracts-tools-sdk-ethers';
+
+/**
+ * --- Setup ---
+ */
+
+const RPC_URL = 'https://eth.llamarpc.com';
+const ADDRESS = '0xbaA999AC55EAce41CcAE355c77809e68Bb345170';
+const PROVIDER = new ethers.WebSocketProvider(RPC_URL);
+
+/**
+ * --- BaseContract Definition ---
+ */
+
+const RegistryAbi = '<abi>';
+class RegistryContract extends BaseContract {
+  constructor(address: string, provider: Provider) {
+    super(RegistryAbi, address, provider);
+  }
+
+  getAddressesProvidersListCall(): ContractCall {
+    return this.getCall('getAddressesProvidersList');
+  }
+
+  owner(): Promise<string> {
+    return this.call<string>('owner');
+  }
+  getOwnerCall(): ContractCall {
+    return this.getCall('owner');
+  }
+}
+
+/*
+ * Alternatively, it can be created dynamically based on the ABI:
+ *
+ * const Registry = BaseContract.createAutoClass(RegistryAbi, ADDRESS, PROVIDER);
+ * const registry = new Registry(); // Or args can be bypassed for override
+ *
+ * Or just:
+ *
+ * const registry = BaseContract.createAutoInstance(RegistryAbi, ADDRESS, PROVIDER);
+ * */
+
+/**
+ * --- Using Multicall ---
+ */
+
+const registry = new RegistryContract(ADDRESS, PROVIDER);
+const unit = new MulticallUnit(PROVIDER);
+
+const addressesProvidersListTag = 'getAddressesProvidersList';
+const ownerTag = 'owner';
+
+// Add calls to unit
+unit.add(registry.getAddressesProvidersListCall(), addressesProvidersListTag);
+unit.add(registry.getOwnerCall(), ownerTag);
+
+// Execute multicall
+const isSuccess: boolean = await unit.run();
+
+// Retrieve results
+const list = unit.getArray<string[]>(addressesProvidersListTag);
+const owner = unit.getSingle<string>(ownerTag);
+
+expect(isSuccess).toBe(true);
+const directOwner = await registry.owner();
+expect(owner).toBe(directOwner);
+expect(JSON.stringify(list)).toBe();
+expect(JSON.stringify(list)).toBe(
+  "['0x2f39d218133AFaB8F2B819B1066c7E434Ad94E9e''0xcfBf336fe147D643B9Cb705648500e101504B16d','0xeBa440B438Ad808101d1c451C1C5322c90BEFCdA']"
+);
+```
+
+### **Events listening**
+
+```typescript
+import { ContractEventPayload } from 'ethers';
+
+/**
+ * --- Listening to Events ---
+ */
+const data: Map<string, { address: string; id: bigint }> = new Map();
+// Realtime listening
+registry.listenEvent(
+  'AddressesProviderRegistered',
+  (addressesProvider: string, id: bigint, payload: ContractEventPayload) => {
+    data.set(payload.log.transactionHash, {
+      addressesProvider,
+      id,
+    });
+  }
+);
+// Historical logs from last 30,000 blocks
+for await (const cLog of registry.getLogsStream(-30000, [
+  'AddressesProviderRegistered',
+])) {
+  data.set(cLog.log.transactionHash, cLog.description);
+}
+```
+
+## BaseContract
+
+### Description
+
+**BaseContract** is a parent class for contract classes that includes basic state getters and methods for calling the contract directly or obtaining a `ContractCall` for use in **MulticallUnit**. These methods can be parameterized.
+
+### Driver
+
+The driver is either a `Signer` or a `Provider`. The contract's ability to make calls depends on it. An error will occur if you try to call the contract without it, especially when making a mutable call without providing an ethers `Signer` (e.g, `Wallet`) as the driver.
+
+### Fields
+
+* `.address` // Address of contract.
+* `.isCallable` // Flag that indicates whether calls (static or mutable) can be made.
+* `.isReadonly` // Flag that indicates whether only static calls are allowed (false if mutable calls are possible).
+* `.interface` // Ethers contract interface.
+* `.contract` // 'Bare' ethers Contract.
+* `.provider` // Ethers Provider.
+* `.signer` // Ethers Signer.
+
+### Methods
+
+```typescript
+constructor(
+    abi: Interface | InterfaceAbi,
+    address?: string,
+    driver?: Signer | Provider,
+    options?: ContractOptions
+  );
+```
+
+* `static createAutoClass( abi: Interface | InterfaceAbi, address?: string, driver?: Provider | Signer, options?: ContractOptions ): DynamicContractConstructor` // Creates a subclass of the BaseContract with dynamically generated methods based on the functions defined in the provided ABI.
+* `static createAutoInstance( abi: Interface | InterfaceAbi, address?: string, driver?: Provider | Signer, options?: ContractOptions ): DynamicContract` // Instantiates a DynamicContract with methods automatically generated from the provided ABI.
+* `call<T = unknown>(methodName: string, args?: any[], options?: CallOptions): Promise<T>` // Performs a single on-chain call for the contract. Throws an error if unable to execute.
+* `estimate(method: string, args?: any[], options?: ContractCallOptions): Promise<bigint>;` // Estimates gas required to execute a contract method.
+* `getCall(methodName: string, args?: any[], callData?: Partial<ContractCall>): ContractCall` // Creates a `ContractCall` for `MulticallUnit`. Throws an error if unable to create. You can do force replacement with a `callData` parameter.
+* `listenEvent(eventName: string, listener: Listener): Promise<Contract>` // Creates event listener on the contract. WebsocketProvider is required.
+* `getLogs(fromBlock: number, eventsNames?: string[], toBlock?: number, options?: ContractGetLogsOptions): Promise<ContractLog[]>` // Synchronous log retrieval. 'fromBlocks' can have a minus sign, which means 'n blocks ago'.
+* `getLogsStream(fromBlock: number, eventsNames?: string[], toBlock?: number, options?: ContractGetLogsOptions): AsyncGenerator<ContractLog, void>` // Asynchronous way to getting logs.
+
+**ContractOptions**
+
+```typescript
+export interface ContractOptions {
+  forceMutability?: CallMutability; // By default, BaseContract/MulticallUnit automatically detects the mutability of the method(s). You can force it.
+  highPriorityTxs?: boolean; // If activated, calls as "high priority tx": multiply gasPrice and gasLimit by multiplier. It takes additional requests to get them.
+  priorityOptions?: PriorityCallOptions; // Only matters if `highPriorityTx` is activated.
+  logsBlocksStep?: number; // Quantity of processed blocks per iteration during log parsing.
+  logsDelayMs?: number; // Delay between log parsing iterations.
+  signals?: AbortSignal[]; // Can be passed for abort signal control
+  staticCallsTimeoutMs?: number; // Timeout for static calls in ms. DEFAULT: 10000
+  mutableCallsTimeoutMs?: number; // Timeout for mutable calls in ms. DEFAULT: 20000
+}
+export interface PriorityCallOptions {
+  asynchronous?: boolean; // Can be a little faster if provider allows (simultaneously getting gasPrice & gasLimit).
+  chainId?: bigint; // Manually set. (Prevents replay attacks by ensuring the transaction is valid only for the intended blockchain network)
+  provideChainId?: boolean; // Automatic - additional async request. (Prevents replay attacks by ensuring the transaction is valid only for the intended blockchain network)
+  multiplier?: number; // Multiplier for gasPrise and gasLimit values.
+  signals?: AbortSignal[]; // Can be passed for abort signal control
+  timeoutMs?: number; // Timeout in milliseconds. If not provided, there is no default option.
+}
+```
+
+**ContractCall**
+
+```typescript
+export type ContractCall = {
+  // Optional params are using for the result parsing
+  method?: string; // Name of the method.
+  contractInterface?: ethers.Interface; // Interface of the callable contract. Uses for answer decoding.
+  target: string; // Address of contract.
+  allowFailure: boolean; // Failure allowance - false by default (*). DEFAULT: false
+  callData: string; // Encoded function data - uses in multicall.
+  stateMutability: StateMutability; // Shows mutability of the method.
+};
+export declare enum StateMutability {
+  View = 'view',
+  Pure = 'pure',
+  NonPayable = 'nonpayable',
+  Payable = 'payable',
+}
+```
+
+**ContractGetLogsOptions**
+
+```typescript
+export interface ContractGetLogsOptions {
+  blocksStep?: number; // Quantity of processed blocks per iteration during log parsing
+  delayMs?: number; // Delay between log parsing iterations.
+  signals?: AbortSignal[]; // Can be passed for abort signal control
+}
+```
+
+**ContractLog**
+
+```typescript
+export interface ContractLog {
+  log: Log; // Info about log
+  description: LogDescription; // Parsed data
+}
+```
+
+## MulticallUnit
+
+### Description
+
+**MulticallUnit** is a tool that takes a calls (`ContractCall`). When the `run()` method is invoked, it splits the stored calls into mutable and static, prioritizing mutable calls. It then processes them by stacks. The size of the concurrently processed call stack for mutable and static calls can be adjusted separately via `MulticallOptions`, along with other parameters.
+
+### Tags
+
+Tags serve as unique references for your specific calls. They support **single values, arrays, and records**.\
+This can be useful for complex calls.
+
+```typescript
+export type Keyable = string | number | symbol;
+export type Tagable = Keyable | bigint;
+
+export type MulticallTags = Tagable | Tagable[] | Record<Keyable, Tagable>;
+```
+
+### Fields
+
+* `.tags` // Array of provided tags.
+* `.calls` // Array of provided calls.
+* `.response` // Array of the whole response.
+* `.success` // Flag that indicates whether all calls were successful.
+* `.static` // Flag that indicates whether all calls are static (not mutable).
+* `.executing` // Flag that indicates if `run()` executing at the moment.
+
+### Methods
+
+```typescript
+constructor(
+  driver: Signer | Provider,
+  options?: MulticallOptions, // Default options for the each run.
+  multicallAddress?: string, // You can use any address. Useful for less popular networks.
+);
+```
+* `add(contractCall: ContractCall, tags?: MulticallTags): MulticallTags` // Add new call. Returns Tags as reference.
+* `run(options?: MulticallOptions): Promise<boolean>` // Executes the multicall operation.
+* `estimateRun(options?: MulticallOptions): Promise<bigint[]>` // Estimates gas for each batch of mutable calls (estimates .run() method).
+
+
+* `get<T>(tags: MulticallTags): T | null` // Returns the decoded result for the specified tag.
+* `getOrThrow<T>(tags: MulticallTags): T` // Same as get(), but throws an error if the result is missing or cannot be decoded.
+* `getSingle<T>(tags: MulticallTags): T | undefined` // Get single primitive value as result.
+* `getSingleOrThrow<T>(tags: MulticallTags): T;` // The same but throws an error if not found.
+* `getArray<T>(tags: MulticallTags, deep?: boolean): T | undefined` // Get array as result.
+* `getArrayOrThrow<T>(tags: MulticallTags, deep?: boolean): T` // The same but throws an error if not found.
+* `getObject<T>(tags: MulticallTags, deep?: boolean): T | undefined` // Get object as result. Works with named fields in ABI.
+* `getObjectOrThrow<T>(tags: MulticallTags, deep?: boolean): T` // The same but throws an error if not found.
+* `getRaw(tags: MulticallTags): string | null` // Get the raw call result.
+* `getTxResponse(tags: MulticallTags): TransactionResponse | null` // Returns TransactionResponse for the mutable call.
+* `getTxResponseOrThrow(tags: MulticallTags): TransactionResponse` // Returns TransactionResponse for the mutable call or throws if not found.
+* `getTxReceipt(tags: MulticallTags): TransactionReceipt | null` // Returns TransactionReceipt for the mutable call.
+
+
+* `wait<T>(tags: MulticallTags, options?: MulticallWaitOptions): Promise<void>` // Waiting for the call execution.
+* `waitFor<T>(tags: MulticallTags, options?: MulticallWaitOptions): Promise<T>` // Waiting for the parsed call result.
+* `waitRaw(tags: MulticallTags, options?: MulticallWaitOptions): Promise<string | null>;` // Waiting for the specific raw data.
+* `waitRawOrThrow(tags: MulticallTags, options?: MulticallWaitOptions): Promise<string>;` // Same as waitRaw, but throws if not found.
+* `waitTx(tags: MulticallTags, options?: MulticallWaitOptions): Promise<string | null>;` // Waiting for the TransactionResponse for the specific call.
+* `waitTxOrThrow(tags: MulticallTags, options?: MulticallWaitOptions): Promise<string>;` // Same as waitTx, but throws if not found.
+
+
+* `isSuccess(tags: MulticallTags): boolean | undefined` // Check if call finished successfully.
+* `clear(): void` // Completely clears the Unit for reuse.
+
+### **MulticallOptions**
+
+```typescript
+export interface MulticallOptions {
+  forceMutability?: CallMutability; // Allows to force mutability. It will try to call as static or mutable if you want to.
+  waitForTxs?: boolean; // Wait for every transaction. Turned on by default for nonce safety. DEFAULT: true
+  highPriorityTxs?: boolean; // You can make priority transaction when it is necessary. Requires more calls, but will be processed more quickly.
+  priorityOptions?: PriorityCallOptions; // Only matters if `highPriorityTxs` is turned on.
+  maxStaticCallsStack?: number; // The maximum size of one static execution. If it overfills, the multicall performs additional executions. DEFAULT: 50
+  maxMutableCallsStack?: number; // The maximum size of one mutable execution. If it overfills, the multicall performs additional executions. DEFAULT: 10
+  signals?: AbortSignal[]; // Can be passed for abort signal control
+  staticCallsTimeoutMs?: number; // Timeout for static calls in ms. DEFAULT: 10000
+  mutableCallsTimeoutMs?: number; // Timeout for mutable calls in ms. DEFAULT: 20000
+  waitCallsTimeoutMs?: number; // Timeout for waiting in ms. DEFAULT: 30000
+  batchDelayMs?: number; // Delay between batch calls. DEFAULT: 0
+  maxAsyncReadBatches?: number; // Maximum number of read batches to be executed concurrently. DEFAULT: 1
+}
+export enum CallMutability {
+  Static = 'STATIC',
+  Mutable = 'MUTABLE',
+} 
+```
+
+### MulticallDecodableData
+
+```typescript
+export interface MulticallDecodableData {
+  call: ContractCall;
+  tags?: Tagable;
+}
+```
+
+**Warning (\*)**
+
+Since in the case of a **mutable call**, the result is not returned but rather **a transaction or a receipt**, `getRaw` for a single **calls batch** will provide the same information. As a result, using `allowFailure` will lead to inconsistent results. When using `allowFailure`, _make sure that you do not need to track the outcome of a specific execution_.
+
+## Config
+
+Configuration can be set globally or at specific points, such as when creating objects or making calls.
+
+```typescript
+import { config } from '@woof-software/contracts-tools-sdk-ethers';
+
+config.multicallUnit.mutableCalls.batchLimit = 3;
+```
+
+```typescript
+export type Config = {
+  multicallUnit: {
+    /** Multicall contract address */
+    address: string;
+
+    /** If true, allows individual call failures without failing the entire batch */
+    allowFailure: boolean;
+
+    /** If true, waits for transaction confirmations in mutable calls */
+    waitForTxs: boolean;
+
+    /** Settings for read-only (eth_call) operations */
+    staticCalls: {
+      /** Maximum number of static calls per batch */
+      batchLimit: number;
+
+      /** Timeout for each static call in milliseconds */
+      timeoutMs: number;
+    };
+
+    /** Settings for state-changing (eth_sendTransaction) operations */
+    mutableCalls: {
+      /** Maximum number of mutable calls per batch */
+      batchLimit: number;
+
+      /** Timeout for each mutable call in milliseconds */
+      timeoutMs: number;
+    };
+
+    /** Settings for waiting on call results */
+    waitCalls: {
+      /** Timeout for awaiting results of batched calls */
+      timeoutMs: number;
+    };
+
+    /** Settings for prioritizing certain calls */
+    priorityCalls: {
+      /** Priority multiplier to determine weight/importance of selected calls */
+      multiplier: number;
+    };
+    
+      /** Delay between batch calls */
+    batchDelayMs: number;
+    
+      /** Maximum number of read batches to be executed concurrently */
+    maxAsyncReadBatches: number;
+  };
+
+  contract: {
+    /** Global static call timeout for individual contract methods */
+    staticCalls: {
+      /** Timeout for static contract calls in milliseconds */
+      timeoutMs: number;
+    };
+
+    /** Global mutable call timeout for individual contract methods */
+    mutableCalls: {
+      /** Timeout for mutable contract calls in milliseconds */
+      timeoutMs: number;
+    };
+
+    /** Parameters for event log fetching and listening */
+    logsGathering: {
+      /** Number of blocks to query per log fetch request */
+      blocksStep: number;
+
+      /** Delay between log fetch requests in milliseconds */
+      delayMs: number;
+    };
+  };
+
+  /** Default priority settings for individual call execution */
+  priorityCalls: {
+    /** Default multiplier for priority call handling */
+    multiplier: number;
+  };
+};
+```
+
+## Other
+
+**Helpers**
+
+```typescript
+export declare const priorityCall: (
+  // Function that allows making custom priority calls
+  provider: Provider,
+  signer: Signer,
+  contract: Contract,
+  method: string,
+  args: any[],
+  options: PriorityCallOptions
+) => Promise<TransactionResponse>;
+```
+
+```typescript
+export declare const priorityCallEstimate: (
+  // Function that allows you to estimate gas for your custom priority calls
+  provider: Provider,
+  signer: Signer,
+  contract: Contract,
+  method: string,
+  args: any[],
+  options: PriorityCallOptions
+) => Promise<bigint>;
+```
+
+```typescript
+export declare const waitForAddressTxs: (
+  // Function that waits for the end of all users transactions
+  address: string,
+  provider: Provider,
+  delayMs?: number
+) => Promise<void>;
+```
+
+```typescript
+// Indicates whether the call has all the necessary parameters for parsing
+export declare const isParsable: (call: ContractCall) => boolean;
+```
+
+```typescript
+// Accepts mutability and says if method is static
+export declare const isStaticMethod: (
+  state: StateMutability | string
+) => boolean;
+```
+
+```typescript
+// Accepts array of ContractCalls and says if all methods are static
+export declare const isStaticArray: (calls: ContractCall[]) => boolean;
+```
+
+```typescript
+// Generates Tag for Multicall Unit
+export declare const multicallGenerateTag: () => string;
+```
+
+**Entities**
+
+```typescript
+// Contains more than 250 different chains.
+// Supports JS as struct. All of these chains right now supports multicall3.
+export enum Chain {
+  Mainnet = 1,
+  Kovan = 42,
+  Rinkeby = 4,
+  // And other 250+ chains...
+}
+```
+
+**Utilities**
+
+```typescript
+// Check AbortSignal[] and throw if any signal is aborted.
+export declare const checkSignals: (signals: AbortSignal[]) => void;
+```
+
+```typescript
+// Create a promise for signals to use in race conditions
+export declare const createSignalsPromise: (
+  signals: AbortSignal[]
+) => Promise<never>;
+```
+
+```typescript
+// Create a signal from a timeout in milliseconds.
+export declare const createTimeoutSignal: (ms: number) => AbortSignal;
+```
+
+```typescript
+// Race the provided function (racer) with the given signals.
+export declare const raceWithSignals: <T>(
+  racer: () => Promise<T>,
+  signals?: AbortSignal[]
+) => Promise<T>;
+```
+
+```typescript
+// Wait while listening to signals
+export declare const waitWithSignals: (
+  ms: number,
+  signals?: AbortSignal[]
+) => Promise<void>;
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@woof-software/contracts-tools-sdk-ethers",
   "description": "Module simplify smart contract interactions and multicall3 aggregation on the Ethereum blockchain and other EVM-compatible networks.",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/woof-compound/sandbox-sdks.git"