@woof-software/contracts-tools-sdk-ethers 0.0.10 → 0.0.12

package/lib/contract/base-contract.d.ts

@@ -1,5 +1,5 @@
-import { Contract as EthersContract, type Interface, type InterfaceAbi, type Listener, type LogDescription, type Provider, type Signer } from "ethers";
-import { type ContractCall, type ContractCallOptions, type ContractGetLogsOptions, type ContractOptions, type DynamicContractConstructor } from "../types";
+import { Contract as EthersContract, type Interface, type InterfaceAbi, type Listener, type Provider, type Signer } from "ethers";
+import { type ContractCall, type ContractCallOptions, type ContractGetLogsOptions, type ContractLog, type ContractOptions, type DynamicContractConstructor } from "../types";
 export declare class BaseContract {
     readonly address: string;
     readonly driver?: Signer | Provider;
@@ -14,10 +14,11 @@ export declare class BaseContract {
     get signer(): Signer | null;
     get interface(): Interface;
     call<T>(method: string, args?: any[], options?: ContractCallOptions): Promise<Awaited<T>>;
+    estimate(method: string, args?: any[], options?: ContractCallOptions): Promise<bigint>;
     getCall(methodName: string, args?: any[], callData?: {}): ContractCall;
     listenEvent(eventName: string, listener: Listener): Promise<EthersContract>;
-    getLogs(fromBlock: number, eventsNames?: string[], toBlock?: number, options?: ContractGetLogsOptions): Promise<LogDescription[]>;
+    getLogs(fromBlock: number, eventsNames?: string[], toBlock?: number, options?: ContractGetLogsOptions): Promise<ContractLog[]>;
     getLogsStream(fromBlock: number, eventsNames?: string[], toBlock?: number, // Latest by default
-    options?: ContractGetLogsOptions): AsyncGenerator<LogDescription, void>;
+    options?: ContractGetLogsOptions): AsyncGenerator<ContractLog, void>;
     private getTimeoutSignal;
 }

package/lib/contract/base-contract.js

@@ -1,7 +1,7 @@
 import { Contract as EthersContract, WebSocketProvider, } from "ethers";
 import { config } from "../config.js";
 import { CONTRACTS_ERRORS } from "../errors/index.js";
-import { isSigner, isStaticMethod, priorityCall } from "../helpers/index.js";
+import { isSigner, isStaticMethod, priorityCall, priorityCallEstimate, } from "../helpers/index.js";
 import { CallMutability, } from "../types/index.js";
 import { checkSignals, createTimeoutSignal, raceWithSignals, waitWithSignals, } from "../utils/index.js";
 import { contractCreateCallName } from "./contract-create-call-name.js";
@@ -107,6 +107,42 @@ export class BaseContract {
             return tx;
         }
     }
+    async estimate(method, args = [], options = {}) {
+        if (!this.isCallable)
+            throw CONTRACTS_ERRORS.NON_CALLABLE_CONTRACT_INVOCATION;
+        const methodFn = this.contract[method];
+        if (!methodFn)
+            throw CONTRACTS_ERRORS.METHOD_NOT_DEFINED(method);
+        const functionFragment = this.contract.interface.getFunction(method);
+        if (!functionFragment)
+            throw CONTRACTS_ERRORS.FRAGMENT_NOT_DEFINED(method);
+        if (isStaticMethod(functionFragment.stateMutability))
+            throw CONTRACTS_ERRORS.ESTIMATE_STATIC_CALL(method);
+        const callOptions = {
+            highPriorityTx: this.contractOptions.highPriorityTxs,
+            priorityOptions: this.contractOptions.priorityOptions,
+            ...options,
+        };
+        const localSignals = [];
+        if (callOptions.signals)
+            localSignals.push(...callOptions.signals);
+        if (callOptions.timeoutMs)
+            localSignals.push(this.getTimeoutSignal(false, callOptions.timeoutMs));
+        if (this.isReadonly)
+            throw CONTRACTS_ERRORS.READ_ONLY_CONTRACT_MUTATION;
+        let estimate;
+        if (callOptions.highPriorityTx) {
+            const provider = this.driver?.provider;
+            estimate = await raceWithSignals(() => priorityCallEstimate(provider, this.driver, this.contract, method, args, {
+                signals: localSignals,
+                ...options.priorityOptions,
+            }), localSignals);
+        }
+        else {
+            estimate = await raceWithSignals(() => this.contract[method].estimateGas(...args), localSignals);
+        }
+        return estimate;
+    }
     getCall(methodName, args = [], callData = {}) {
         if (!this.address)
             throw CONTRACTS_ERRORS.NON_CALLABLE_CONTRACT_INVOCATION;
@@ -168,7 +204,10 @@ export class BaseContract {
                 const description = this.interface.parseLog(log);
                 if (!description)
                     continue;
-                yield description;
+                yield {
+                    log,
+                    description,
+                };
             }
             await waitWithSignals(streamOptions.delayMs, options.signals);
         }

package/lib/errors/contracts-errors.d.ts

@@ -6,4 +6,5 @@ export declare const CONTRACTS_ERRORS: {
     FRAGMENT_NOT_DEFINED: (methodName: any) => Error;
     MISSING_WEBSOCKET_PROVIDER: Error;
     MISSING_PROVIDER: Error;
+    ESTIMATE_STATIC_CALL: (methodName: any) => Error;
 };

package/lib/errors/contracts-errors.js

@@ -6,4 +6,5 @@ export const CONTRACTS_ERRORS = {
     FRAGMENT_NOT_DEFINED: (methodName) => new Error(`Fragment for method "${methodName}" was not found on the contract!`),
     MISSING_WEBSOCKET_PROVIDER: new Error("Attempted to listen for contract events, but no WebSocketProvider was provided!"),
     MISSING_PROVIDER: new Error("A provider is required, but none was provided!"),
+    ESTIMATE_STATIC_CALL: (methodName) => new Error(`Cannot estimate gas for static (view/pure) method "${methodName}"!`),
 };

package/lib/helpers/priority-call.d.ts

@@ -1,3 +1,4 @@
 import type { Contract, Provider, Signer } from "ethers";
 import type { PriorityCallOptions } from "../types";
 export declare function priorityCall(provider: Provider, signer: Signer, contract: Contract, method: string, args?: any[], options?: PriorityCallOptions): Promise<any>;
+export declare function priorityCallEstimate(provider: Provider, signer: Signer, contract: Contract, method: string, args?: any[], options?: PriorityCallOptions): Promise<bigint>;

package/lib/helpers/priority-call.js

@@ -1,8 +1,16 @@
-import { DEFAULT_PRIORITY_CALL_MULTIPLIER } from "../constant.js";
+import { config } from "../config.js";
 import { checkSignals, createTimeoutSignal } from "../utils/index.js";
 export async function priorityCall(provider, signer, contract, method, args = [], options = {}) {
+    const txn = await formTx(provider, signer, contract, method, args, options);
+    return signer.sendTransaction(txn);
+}
+export async function priorityCallEstimate(provider, signer, contract, method, args = [], options = {}) {
+    const txn = await formTx(provider, signer, contract, method, args, options);
+    return signer.estimateGas(txn);
+}
+async function formTx(provider, signer, contract, method, args = [], options = {}) {
     const localOptions = {
-        multiplier: DEFAULT_PRIORITY_CALL_MULTIPLIER,
+        multiplier: config.priorityCalls.multiplier,
         ...options,
     };
     const localSignals = [];
@@ -16,9 +24,7 @@ export async function priorityCall(provider, signer, contract, method, args = []
     const maxPriorityFeePerGas = Math.ceil(localOptions.multiplier * Number(originalFeeData.maxPriorityFeePerGas));
     const gasLimit = Math.ceil(localOptions.multiplier * Number(originalGasLimit));
     checkSignals(localSignals);
-    const txn = await contract
-        .getFunction(method)
-        .populateTransaction(...args, {
+    const txn = await contract.getFunction(method).populateTransaction(...args, {
         gasLimit,
         maxFeePerGas,
         maxPriorityFeePerGas,
@@ -31,11 +37,11 @@ export async function priorityCall(provider, signer, contract, method, args = []
         const network = await provider.getNetwork();
         txn.chainId = network.chainId;
     }
-    else if (localOptions.chainId) {
-        txn.chainId = localOptions.chainId;
+    else {
+        if (localOptions.chainId)
+            txn.chainId = localOptions.chainId;
     }
-    checkSignals(localSignals);
-    return signer.sendTransaction(txn);
+    return txn;
 }
 async function gatherOriginalData(provider, contract, method, args = [], asynchronous, signals) {
     let originalFeeData;

package/lib/multicall/multicall-unit.d.ts

@@ -30,8 +30,11 @@ export declare class MulticallUnit extends BaseContract {
     getArray<T>(tags: MulticallTags, deep?: boolean): T | null;
     getArrayOrThrow<T>(tags: MulticallTags, deep?: boolean): T;
     run(options?: Partial<MulticallOptions>): Promise<boolean>;
+    estimateRun(options?: MulticallOptions): Promise<bigint[]>;
+    private splitCalls;
     private processStaticCalls;
     private processMutableCalls;
+    private estimateMutableCallsBatch;
     private saveResponse;
     getOrThrow<T>(tags: MulticallTags, deep?: boolean): T;
     get<T>(tags: MulticallTags, deep?: boolean): T | null;

package/lib/multicall/multicall-unit.js

@@ -119,35 +119,7 @@ export class MulticallUnit extends BaseContract {
         this._response = Array(tags.length).fill([undefined, null]);
         try {
             checkSignals(runOptions.signals);
-            let staticCalls;
-            let staticIndexes;
-            let mutableCalls;
-            let mutableTags;
-            let mutableIndexes;
-            if (runOptions.forceMutability) {
-                if (runOptions.forceMutability === CallMutability.Static) {
-                    staticCalls = calls;
-                    staticIndexes = Array.from({ length: calls.length }, (_, i) => i);
-                    mutableCalls = [];
-                    mutableTags = [];
-                    mutableIndexes = [];
-                }
-                else {
-                    staticCalls = [];
-                    staticIndexes = [];
-                    mutableCalls = calls;
-                    mutableTags = tags;
-                    mutableIndexes = Array.from({ length: calls.length }, (_, i) => i);
-                }
-            }
-            else {
-                const split = multicallSplitCalls(calls, tags);
-                staticCalls = split.staticCalls;
-                staticIndexes = split.staticIndexes;
-                mutableCalls = split.mutableCalls;
-                mutableTags = split.mutableTags;
-                mutableIndexes = split.mutableIndexes;
-            }
+            const { staticCalls, staticIndexes, mutableCalls, mutableTags, mutableIndexes, } = this.splitCalls(calls, tags, options.forceMutability);
             // Process mutable
             for (let i = 0; i < mutableCalls.length; i += runOptions.maxMutableCallsStack) {
                 checkSignals(runOptions.signals);
@@ -180,6 +152,65 @@ export class MulticallUnit extends BaseContract {
         }
         return this._lastSuccess ?? false;
     }
+    async estimateRun(options = {}) {
+        const runOptions = {
+            ...this._multicallOptions,
+            ...options,
+        };
+        const tags = this.tags;
+        const calls = this.calls;
+        checkSignals(runOptions.signals);
+        const { mutableCalls, mutableTags } = this.splitCalls(calls, tags, options.forceMutability);
+        const estimates = [];
+        // Process mutable
+        for (let i = 0; i < mutableCalls.length; i += runOptions.maxMutableCallsStack) {
+            checkSignals(runOptions.signals);
+            const border = Math.min(i + runOptions.maxMutableCallsStack, mutableCalls.length);
+            const iterationCalls = mutableCalls.slice(i, border); // half-opened interval
+            const iterationTags = mutableTags.slice(i, border);
+            const estimation = await this.estimateMutableCallsBatch(iterationCalls, iterationTags, runOptions);
+            estimates.push(estimation);
+        }
+        return estimates;
+    }
+    splitCalls(calls, tags, forceMutability) {
+        let staticCalls;
+        let staticIndexes;
+        let mutableCalls;
+        let mutableTags;
+        let mutableIndexes;
+        if (forceMutability) {
+            if (forceMutability === CallMutability.Static) {
+                staticCalls = calls;
+                staticIndexes = Array.from({ length: calls.length }, (_, i) => i);
+                mutableCalls = [];
+                mutableTags = [];
+                mutableIndexes = [];
+            }
+            else {
+                staticCalls = [];
+                staticIndexes = [];
+                mutableCalls = calls;
+                mutableTags = tags;
+                mutableIndexes = Array.from({ length: calls.length }, (_, i) => i);
+            }
+        }
+        else {
+            const split = multicallSplitCalls(calls, tags);
+            staticCalls = split.staticCalls;
+            staticIndexes = split.staticIndexes;
+            mutableCalls = split.mutableCalls;
+            mutableTags = split.mutableTags;
+            mutableIndexes = split.mutableIndexes;
+        }
+        return {
+            staticCalls,
+            staticIndexes,
+            mutableCalls,
+            mutableTags,
+            mutableIndexes,
+        };
+    }
     async processStaticCalls(iterationCalls, runOptions) {
         const result = await this.call(aggregate3, [iterationCalls], {
             forceMutability: CallMutability.Static,
@@ -217,6 +248,15 @@ export class MulticallUnit extends BaseContract {
         }
         return result;
     }
+    async estimateMutableCallsBatch(iterationCalls, iterationTags, runOptions) {
+        return this.estimate(aggregate3, [iterationCalls], {
+            forceMutability: CallMutability.Mutable,
+            highPriorityTx: runOptions.highPriorityTxs,
+            priorityOptions: runOptions.priorityOptions,
+            signals: runOptions.signals,
+            timeoutMs: runOptions.mutableCallsTimeoutMs,
+        });
+    }
     saveResponse(iterationResponse, iterationIndexes, globalTags) {
         iterationResponse.forEach((el, index) => {
             const [success, data] = el;

package/lib/types/contract/contract-log.d.ts

@@ -0,0 +1,5 @@
+import type { Log, LogDescription } from "ethers";
+export interface ContractLog {
+    log: Log;
+    description: LogDescription;
+}

package/lib/types/contract/contract-log.js

@@ -0,0 +1 @@
+export {};

package/lib/types/contract/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./contract-call";
 export * from "./contract-call-options";
 export * from "./contract-get-logs-options";
+export * from "./contract-log";
 export * from "./contract-options";
 export * from "./dynamic-contract";
 export * from "./dynamic-contract-constructor";

package/lib/types/contract/index.js

@@ -1,6 +1,7 @@
 export * from "./contract-call.js";
 export * from "./contract-call-options.js";
 export * from "./contract-get-logs-options.js";
+export * from "./contract-log.js";
 export * from "./contract-options.js";
 export * from "./dynamic-contract.js";
 export * from "./dynamic-contract-constructor.js";

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.10",
+  "version": "0.0.12",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/woof-compound/sandbox-sdks.git"

package/lib/abis/multicall.abi.json

@@ -1,440 +0,0 @@
-[
-    {
-        "inputs": [
-            {
-                "components": [
-                    {
-                        "internalType": "address",
-                        "name": "target",
-                        "type": "address"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "callData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Call[]",
-                "name": "calls",
-                "type": "tuple[]"
-            }
-        ],
-        "name": "aggregate",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "blockNumber",
-                "type": "uint256"
-            },
-            {
-                "internalType": "bytes[]",
-                "name": "returnData",
-                "type": "bytes[]"
-            }
-        ],
-        "stateMutability": "payable",
-        "type": "function"
-    },
-    {
-        "inputs": [
-            {
-                "components": [
-                    {
-                        "internalType": "address",
-                        "name": "target",
-                        "type": "address"
-                    },
-                    {
-                        "internalType": "bool",
-                        "name": "allowFailure",
-                        "type": "bool"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "callData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Call3[]",
-                "name": "calls",
-                "type": "tuple[]"
-            }
-        ],
-        "name": "aggregate3",
-        "outputs": [
-            {
-                "components": [
-                    {
-                        "internalType": "bool",
-                        "name": "success",
-                        "type": "bool"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "returnData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Result[]",
-                "name": "returnData",
-                "type": "tuple[]"
-            }
-        ],
-        "stateMutability": "payable",
-        "type": "function"
-    },
-    {
-        "inputs": [
-            {
-                "components": [
-                    {
-                        "internalType": "address",
-                        "name": "target",
-                        "type": "address"
-                    },
-                    {
-                        "internalType": "bool",
-                        "name": "allowFailure",
-                        "type": "bool"
-                    },
-                    {
-                        "internalType": "uint256",
-                        "name": "value",
-                        "type": "uint256"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "callData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Call3Value[]",
-                "name": "calls",
-                "type": "tuple[]"
-            }
-        ],
-        "name": "aggregate3Value",
-        "outputs": [
-            {
-                "components": [
-                    {
-                        "internalType": "bool",
-                        "name": "success",
-                        "type": "bool"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "returnData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Result[]",
-                "name": "returnData",
-                "type": "tuple[]"
-            }
-        ],
-        "stateMutability": "payable",
-        "type": "function"
-    },
-    {
-        "inputs": [
-            {
-                "components": [
-                    {
-                        "internalType": "address",
-                        "name": "target",
-                        "type": "address"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "callData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Call[]",
-                "name": "calls",
-                "type": "tuple[]"
-            }
-        ],
-        "name": "blockAndAggregate",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "blockNumber",
-                "type": "uint256"
-            },
-            {
-                "internalType": "bytes32",
-                "name": "blockHash",
-                "type": "bytes32"
-            },
-            {
-                "components": [
-                    {
-                        "internalType": "bool",
-                        "name": "success",
-                        "type": "bool"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "returnData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Result[]",
-                "name": "returnData",
-                "type": "tuple[]"
-            }
-        ],
-        "stateMutability": "payable",
-        "type": "function"
-    },
-    {
-        "inputs": [],
-        "name": "getBasefee",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "basefee",
-                "type": "uint256"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [
-            {
-                "internalType": "uint256",
-                "name": "blockNumber",
-                "type": "uint256"
-            }
-        ],
-        "name": "getBlockHash",
-        "outputs": [
-            {
-                "internalType": "bytes32",
-                "name": "blockHash",
-                "type": "bytes32"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [],
-        "name": "getBlockNumber",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "blockNumber",
-                "type": "uint256"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [],
-        "name": "getChainId",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "chainid",
-                "type": "uint256"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [],
-        "name": "getCurrentBlockCoinbase",
-        "outputs": [
-            {
-                "internalType": "address",
-                "name": "coinbase",
-                "type": "address"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [],
-        "name": "getCurrentBlockDifficulty",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "difficulty",
-                "type": "uint256"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [],
-        "name": "getCurrentBlockGasLimit",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "gaslimit",
-                "type": "uint256"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [],
-        "name": "getCurrentBlockTimestamp",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "timestamp",
-                "type": "uint256"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [
-            {
-                "internalType": "address",
-                "name": "addr",
-                "type": "address"
-            }
-        ],
-        "name": "getEthBalance",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "balance",
-                "type": "uint256"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [],
-        "name": "getLastBlockHash",
-        "outputs": [
-            {
-                "internalType": "bytes32",
-                "name": "blockHash",
-                "type": "bytes32"
-            }
-        ],
-        "stateMutability": "view",
-        "type": "function"
-    },
-    {
-        "inputs": [
-            {
-                "internalType": "bool",
-                "name": "requireSuccess",
-                "type": "bool"
-            },
-            {
-                "components": [
-                    {
-                        "internalType": "address",
-                        "name": "target",
-                        "type": "address"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "callData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Call[]",
-                "name": "calls",
-                "type": "tuple[]"
-            }
-        ],
-        "name": "tryAggregate",
-        "outputs": [
-            {
-                "components": [
-                    {
-                        "internalType": "bool",
-                        "name": "success",
-                        "type": "bool"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "returnData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Result[]",
-                "name": "returnData",
-                "type": "tuple[]"
-            }
-        ],
-        "stateMutability": "payable",
-        "type": "function"
-    },
-    {
-        "inputs": [
-            {
-                "internalType": "bool",
-                "name": "requireSuccess",
-                "type": "bool"
-            },
-            {
-                "components": [
-                    {
-                        "internalType": "address",
-                        "name": "target",
-                        "type": "address"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "callData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Call[]",
-                "name": "calls",
-                "type": "tuple[]"
-            }
-        ],
-        "name": "tryBlockAndAggregate",
-        "outputs": [
-            {
-                "internalType": "uint256",
-                "name": "blockNumber",
-                "type": "uint256"
-            },
-            {
-                "internalType": "bytes32",
-                "name": "blockHash",
-                "type": "bytes32"
-            },
-            {
-                "components": [
-                    {
-                        "internalType": "bool",
-                        "name": "success",
-                        "type": "bool"
-                    },
-                    {
-                        "internalType": "bytes",
-                        "name": "returnData",
-                        "type": "bytes"
-                    }
-                ],
-                "internalType": "struct Multicall3.Result[]",
-                "name": "returnData",
-                "type": "tuple[]"
-            }
-        ],
-        "stateMutability": "payable",
-        "type": "function"
-    }
-]