@woof-software/contracts-tools-sdk-ethers 0.0.1

package/lib/multicall/multicall-unit.js

@@ -0,0 +1,367 @@
+import { EventEmitter } from "node:events";
+import { MulticallAbi } from "../abis";
+import { config } from "../config";
+import { MULTICALL_ADDRESS } from "../constant";
+import { BaseContract } from "../contract";
+import { MULTICALL_ERRORS } from "../errors";
+import { isParsable, isStaticArray } from "../helpers";
+import { CallMutability, } from "../types";
+import { checkSignals, createTimeoutSignal, raceWithSignals, waitWithSignals, } from "../utils";
+import { multicallErrorEventName } from "./multicall-error-event-name";
+import { multicallNormalizeTags } from "./multicall-normalize-tags";
+import { multicallResultEventName } from "./multicall-result-event-name";
+import { multicallSplitCalls } from "./multicall-split-calls";
+const aggregate3 = "aggregate3";
+export class MulticallUnit extends BaseContract {
+    constructor(driver, options = {}, multicallAddress = MULTICALL_ADDRESS) {
+        const contractOptions = {
+            forceMutability: options.forceMutability,
+            highPriorityTxs: options.highPriorityTxs,
+            priorityOptions: options.priorityOptions,
+            signals: options.signals,
+            staticCallsTimeoutMs: options.staticCallsTimeoutMs,
+            mutableCallsTimeoutMs: options.mutableCallsTimeoutMs,
+        };
+        super(MulticallAbi, multicallAddress, driver, contractOptions);
+        this._units = new Map();
+        this._response = [];
+        this._rawData = new Map();
+        this._callsSuccess = new Map();
+        this._isExecuting = false;
+        this._emitter = new EventEmitter();
+        this._multicallOptions = {};
+        this._txResponses = new Map();
+        this._txReceipts = new Map();
+        this._multicallOptions = {
+            maxStaticCallsStack: config.multicallUnit.staticCalls.batchLimit,
+            maxMutableCallsStack: config.multicallUnit.mutableCalls.batchLimit,
+            waitForTxs: config.multicallUnit.waitForTxs,
+            waitCallsTimeoutMs: config.multicallUnit.waitCalls.timeoutMs,
+            batchDelayMs: config.multicallUnit.batchDelayMs,
+            ...options,
+        };
+    }
+    clear() {
+        this._units = new Map();
+        this._response = [];
+        this._rawData = new Map();
+        this._callsSuccess = new Map();
+        this._lastSuccess = undefined;
+    }
+    add(contractCall, tags) {
+        this._units.set(multicallNormalizeTags(tags), contractCall);
+        return tags;
+    }
+    get tags() {
+        return Array.from(this._units.keys()); // The order is guaranteed
+    }
+    get calls() {
+        return Array.from(this._units.values()); // The order is guaranteed
+    }
+    get response() {
+        return this._response;
+    }
+    get success() {
+        return this._lastSuccess;
+    }
+    get static() {
+        if (!this._units.size)
+            return true;
+        return isStaticArray(this.calls);
+    }
+    get executing() {
+        return this._isExecuting;
+    }
+    isSuccess(tags) {
+        return this._callsSuccess.get(multicallNormalizeTags(tags));
+    }
+    getRaw(tags) {
+        return this._rawData.get(multicallNormalizeTags(tags)) ?? null;
+    }
+    getSingle(tags) {
+        const data = this.getDecodableData(tags);
+        if (!data)
+            return null;
+        const [value] = data.call.contractInterface.decodeFunctionResult(data.call.method, data.rawData);
+        return value;
+    }
+    getArray(tags, deep = false) {
+        const data = this.getDecodableData(tags);
+        if (data === null)
+            return null;
+        return data.call
+            .contractInterface.decodeFunctionResult(data.call.method, data.rawData)
+            .toArray(deep);
+    }
+    async run(options = {}) {
+        const runOptions = {
+            ...this._multicallOptions,
+            ...options,
+        };
+        if (this._isExecuting)
+            throw MULTICALL_ERRORS.SIMULTANEOUS_INVOCATIONS;
+        this._isExecuting = true;
+        this._lastSuccess = undefined;
+        const tags = this.tags;
+        const calls = this.calls;
+        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;
+            }
+            // 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 iterationIndexes = mutableIndexes.slice(i, border); // half-opened interval
+                const iterationResponse = await this.processMutableCalls(iterationCalls, iterationTags, runOptions);
+                this.saveResponse(iterationResponse, iterationIndexes, tags);
+                await waitWithSignals(runOptions.batchDelayMs, runOptions.signals);
+            }
+            // Process static
+            for (let i = 0; i < staticCalls.length; i += runOptions.maxStaticCallsStack) {
+                checkSignals(runOptions.signals);
+                const border = Math.min(i + runOptions.maxStaticCallsStack, staticCalls.length);
+                const iterationCalls = staticCalls.slice(i, border); // half-opened interval
+                const iterationIndexes = staticIndexes.slice(i, border); // half-opened interval
+                const iterationResponse = await this.processStaticCalls(iterationCalls, runOptions);
+                this.saveResponse(iterationResponse, iterationIndexes, tags);
+                await waitWithSignals(runOptions.batchDelayMs, runOptions.signals);
+            }
+        }
+        catch (error) {
+            this._lastSuccess = false;
+            tags.forEach((tag) => this._emitter.emit(multicallErrorEventName(tag), error)); // For unlock all the waiters
+            throw error;
+        }
+        finally {
+            this._isExecuting = false;
+        }
+        return this._lastSuccess ?? false;
+    }
+    async processStaticCalls(iterationCalls, runOptions) {
+        const result = await this.call(aggregate3, [iterationCalls], {
+            forceMutability: CallMutability.Static,
+            signals: runOptions.signals,
+            timeoutMs: runOptions.staticCallsTimeoutMs,
+        });
+        this._lastSuccess = !(this._lastSuccess === false);
+        return result;
+    }
+    async processMutableCalls(iterationCalls, iterationTags, runOptions) {
+        let result;
+        const tx = (await this.call(aggregate3, [iterationCalls], {
+            forceMutability: CallMutability.Mutable,
+            highPriorityTx: runOptions.highPriorityTxs,
+            priorityOptions: runOptions.priorityOptions,
+            signals: runOptions.signals,
+            timeoutMs: runOptions.mutableCallsTimeoutMs,
+        }));
+        iterationTags.forEach((tag) => this._txResponses.set(tag, tx));
+        if (runOptions.waitForTxs) {
+            const receipt = await raceWithSignals(() => tx.wait(), runOptions.signals);
+            if (!receipt) {
+                result = Array(iterationCalls.length).fill([false, null]);
+                this._lastSuccess = false;
+            }
+            else {
+                result = Array(iterationCalls.length).fill([true, receipt]);
+                this._lastSuccess = !(this._lastSuccess === false);
+                iterationTags.forEach((tag) => this._txReceipts.set(tag, receipt));
+            }
+        }
+        else {
+            result = Array(iterationCalls.length).fill([true, tx]);
+            this._lastSuccess = !(this._lastSuccess === false);
+        }
+        return result;
+    }
+    saveResponse(iterationResponse, iterationIndexes, globalTags) {
+        iterationResponse.forEach((el, index) => {
+            const [success, data] = el;
+            const globalIndex = iterationIndexes[index];
+            const tag = globalTags[globalIndex]; // Normalized
+            if (!success)
+                this._lastSuccess = false;
+            if (typeof data === "string")
+                this._rawData.set(tag, data);
+            this._callsSuccess.set(tag, success);
+            this._response[globalIndex] = el;
+            this._emitter.emit(multicallResultEventName(tag));
+        });
+    }
+    getOrThrow(tags, deep = false) {
+        const value = this.get(tags, deep);
+        if (value === null)
+            throw MULTICALL_ERRORS.RESULT_NOT_FOUND;
+        return value;
+    }
+    get(tags, deep = false) {
+        const raw = this.getRaw(tags);
+        if (raw === null)
+            return null;
+        // if (typeof raw !== 'string') return raw; // Transaction or Receipt for mutable call
+        const data = this.getDecodableData(tags);
+        if (!data)
+            return null;
+        const decoded = data.call.contractInterface.decodeFunctionResult(data.call.method, data.rawData);
+        const outputs = data.call.contractInterface.getFunction(data.call.method).outputs;
+        if (!outputs || outputs.length === 0) {
+            return null;
+        }
+        // Only one output - returns just single (sometimes can work with arrays (like [address[]]))
+        if (outputs.length === 1) {
+            return decoded[0];
+        }
+        // Outputs are named in ABI - object can be formed
+        // If output is named - object is preferable
+        if (outputs.every((param) => !!param.name)) {
+            return decoded.toObject(deep);
+        }
+        // In other case - return array
+        return decoded.toArray(deep);
+    }
+    getDecodableData(tags) {
+        const nTags = multicallNormalizeTags(tags);
+        const rawData = this._rawData.get(nTags);
+        const call = this._units.get(nTags);
+        if (rawData === undefined ||
+            !call ||
+            !isParsable(call) ||
+            !this.isSuccess(nTags)) {
+            return null;
+        }
+        return {
+            call,
+            rawData,
+        };
+    }
+    async waitRawOrThrow(tags, options) {
+        const raw = await this.waitRaw(tags, options);
+        if (raw === null)
+            throw MULTICALL_ERRORS.RESULT_NOT_FOUND;
+        return raw;
+    }
+    async waitRaw(tags, options) {
+        const nTags = multicallNormalizeTags(tags);
+        // 1. If result exists - just return
+        {
+            const result = this._rawData.get(nTags);
+            if (result)
+                return result;
+        }
+        if (this._txResponses.has(nTags)) {
+            return null;
+        }
+        // 2. Or wait for event
+        await this.wait(tags, options);
+        return this.getRaw(nTags);
+    }
+    wait(tags, options) {
+        const signals = options?.signals ?? [];
+        if (options?.timeoutMs)
+            signals.push(createTimeoutSignal(options.timeoutMs));
+        const nTags = multicallNormalizeTags(tags);
+        return raceWithSignals(() => new Promise((resolve, reject) => {
+            const resultEvent = multicallResultEventName(nTags);
+            const errorEvent = multicallErrorEventName(nTags);
+            const onResult = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const cleanup = () => {
+                this._emitter.removeListener(resultEvent, onResult);
+                this._emitter.removeListener(errorEvent, onError);
+            };
+            this._emitter.once(resultEvent, onResult);
+            this._emitter.once(errorEvent, onError);
+        }), signals);
+    }
+    async waitTxOrThrow(tags, options) {
+        const tx = await this.waitTx(tags, options);
+        if (tx === null)
+            throw MULTICALL_ERRORS.RESULT_NOT_FOUND;
+        return tx;
+    }
+    async waitTx(tags, options) {
+        const nTags = multicallNormalizeTags(tags);
+        // 1. If result exists - just return
+        {
+            const result = this._txResponses.get(nTags);
+            if (result)
+                return result;
+        }
+        if (this._rawData.has(nTags)) {
+            return null;
+        }
+        // 2. Or wait for event
+        await this.wait(tags, options);
+        return this.getTxResponse(nTags);
+    }
+    getTxResponse(tags) {
+        return this._txResponses.get(multicallNormalizeTags(tags)) ?? null;
+    }
+    getTxResponseOrThrow(tags) {
+        const response = this.getTxResponse(tags);
+        if (response === null)
+            throw MULTICALL_ERRORS.RESPONSE_NOT_FOUND;
+        return response;
+    }
+    getTxReceipt(tags) {
+        return this._txReceipts.get(multicallNormalizeTags(tags)) ?? null;
+    }
+    getObjectOrThrow(tags, deep = false) {
+        const obj = this.getObject(tags, deep);
+        if (obj === null)
+            throw MULTICALL_ERRORS.RESULT_NOT_FOUND;
+        return obj;
+    }
+    getObject(tags, deep = false) {
+        const data = this.getDecodableData(tags);
+        if (data === null)
+            return null;
+        const decoded = data.call.contractInterface.decodeFunctionResult(data.call.method, data.rawData);
+        return decoded.toObject(deep);
+    }
+    async waitFor(tags, options) {
+        const nTags = multicallNormalizeTags(tags);
+        if (this._rawData.has(nTags)) {
+            return this.get(tags, options?.deep);
+        }
+        await this.wait(tags, options);
+        return this.get(tags, options?.deep);
+    }
+}

package/lib/types/call-mutability.d.ts

@@ -0,0 +1,4 @@
+export declare enum CallMutability {
+    Static = "STATIC",
+    Mutable = "MUTABLE"
+}

package/lib/types/call-mutability.js

@@ -0,0 +1,5 @@
+export var CallMutability;
+(function (CallMutability) {
+    CallMutability["Static"] = "STATIC";
+    CallMutability["Mutable"] = "MUTABLE";
+})(CallMutability || (CallMutability = {}));

package/lib/types/contract/contract-auto-methods.d.ts

@@ -0,0 +1,13 @@
+export interface ContractAutoMethods {
+    /**
+     * Dynamically generated contract method calls.
+     * E.g., `balanceOf(...)`, `name()`, etc.
+     * OR
+     * Dynamically generated call object getters.
+     * E.g., `getBalanceOfCall`, `getNameCall`, etc.
+     *
+     * @param args - Arguments for the contract method + options/callData.
+     * @returns ContractCall OR Promise of the method result.
+     */
+    [method: string]: <T = unknown>(...args: any[]) => T;
+}

package/lib/types/contract/contract-auto-methods.js

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

package/lib/types/contract/contract-call-options.d.ts

@@ -0,0 +1,9 @@
+import type { CallMutability } from "../call-mutability";
+import type { PriorityCallOptions } from "../priority-call-options";
+export interface ContractCallOptions {
+    forceMutability?: CallMutability;
+    highPriorityTx?: boolean;
+    priorityOptions?: PriorityCallOptions;
+    signals?: AbortSignal[];
+    timeoutMs?: number;
+}

package/lib/types/contract/contract-call-options.js

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

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

@@ -0,0 +1,10 @@
+import type { Interface } from "ethers";
+import type { StateMutability } from "../state-mutabiity";
+export interface ContractCall {
+    method?: string;
+    contractInterface?: Interface;
+    target: string;
+    allowFailure: boolean;
+    callData: string;
+    stateMutability: StateMutability;
+}

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

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

package/lib/types/contract/contract-get-logs-options.d.ts

@@ -0,0 +1,5 @@
+export interface ContractGetLogsOptions {
+    blocksStep?: number;
+    delayMs?: number;
+    signals?: AbortSignal[];
+}

package/lib/types/contract/contract-get-logs-options.js

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

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

@@ -0,0 +1,12 @@
+import type { CallMutability } from "../call-mutability";
+import type { PriorityCallOptions } from "../priority-call-options";
+export interface ContractOptions {
+    forceMutability?: CallMutability;
+    highPriorityTxs?: boolean;
+    priorityOptions?: PriorityCallOptions;
+    logsBlocksStep?: number;
+    logsDelayMs?: number;
+    signals?: AbortSignal[];
+    staticCallsTimeoutMs?: number;
+    mutableCallsTimeoutMs?: number;
+}

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

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

package/lib/types/contract/dynamic-contract-constructor-args.d.ts

@@ -0,0 +1,8 @@
+import type { Interface, InterfaceAbi, Provider, Signer } from "ethers";
+import type { ContractOptions } from "./contract-options";
+export interface DynamicContractConstructorArgs {
+    abi?: Interface | InterfaceAbi;
+    address?: string;
+    driver?: Provider | Signer;
+    options?: ContractOptions;
+}

package/lib/types/contract/dynamic-contract-constructor-args.js

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

package/lib/types/contract/dynamic-contract-constructor.d.ts

@@ -0,0 +1,3 @@
+import type { DynamicContract } from "./dynamic-contract";
+import type { DynamicContractConstructorArgs } from "./dynamic-contract-constructor-args";
+export type DynamicContractConstructor = new (args?: DynamicContractConstructorArgs) => DynamicContract;

package/lib/types/contract/dynamic-contract-constructor.js

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

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

@@ -0,0 +1,3 @@
+import type { BaseContract } from "../../contract";
+import type { ContractAutoMethods } from "./contract-auto-methods";
+export type DynamicContract = BaseContract & ContractAutoMethods;

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

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

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

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

package/lib/types/contract/index.js

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

package/lib/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./contract";
+export * from "./multicall";
+export * from "./split-calls";
+export * from "./state-mutabiity";
+export * from "./call-mutability";
+export * from "./priority-call-options";

package/lib/types/index.js

@@ -0,0 +1,6 @@
+export * from "./contract";
+export * from "./multicall";
+export * from "./split-calls";
+export * from "./state-mutabiity";
+export * from "./call-mutability";
+export * from "./priority-call-options";

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

@@ -0,0 +1,5 @@
+export * from "./multicall-tags";
+export * from "./multicall-response";
+export * from "./multicall-options";
+export * from "./multicall-decodable-data";
+export * from "./multicall-wait-options";

package/lib/types/multicall/index.js

@@ -0,0 +1,5 @@
+export * from "./multicall-tags";
+export * from "./multicall-response";
+export * from "./multicall-options";
+export * from "./multicall-decodable-data";
+export * from "./multicall-wait-options";

package/lib/types/multicall/multicall-decodable-data.d.ts

@@ -0,0 +1,5 @@
+import type { ContractCall } from "../contract";
+export interface MulticallDecodableData {
+    call: ContractCall;
+    rawData: string;
+}

package/lib/types/multicall/multicall-decodable-data.js

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

package/lib/types/multicall/multicall-options.d.ts

@@ -0,0 +1,15 @@
+import type { CallMutability } from "../call-mutability";
+import type { PriorityCallOptions } from "../priority-call-options";
+export interface MulticallOptions {
+    forceMutability?: CallMutability;
+    waitForTxs?: boolean;
+    highPriorityTxs?: boolean;
+    priorityOptions?: PriorityCallOptions;
+    maxStaticCallsStack?: number;
+    maxMutableCallsStack?: number;
+    signals?: AbortSignal[];
+    staticCallsTimeoutMs?: number;
+    mutableCallsTimeoutMs?: number;
+    waitCallsTimeoutMs?: number;
+    batchDelayMs?: number;
+}

package/lib/types/multicall/multicall-options.js

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

package/lib/types/multicall/multicall-response.d.ts

@@ -0,0 +1,5 @@
+import type { TransactionReceipt, TransactionResponse } from "ethers";
+export type MulticallResponse = [
+    success: boolean | undefined,
+    rawData: string | TransactionResponse | TransactionReceipt | null
+];

package/lib/types/multicall/multicall-response.js

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

package/lib/types/multicall/multicall-tags.d.ts

@@ -0,0 +1,4 @@
+type Keyable = string | number | symbol;
+export type Tagable = Keyable | bigint;
+export type MulticallTags = Tagable | Tagable[] | Record<Keyable, Tagable>;
+export {};

package/lib/types/multicall/multicall-tags.js

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

package/lib/types/multicall/multicall-wait-options.d.ts

@@ -0,0 +1,5 @@
+export interface MulticallWaitOptions {
+    timeoutMs?: number;
+    deep?: boolean;
+    signals?: AbortSignal[];
+}

package/lib/types/multicall/multicall-wait-options.js

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

package/lib/types/priority-call-options.d.ts

@@ -0,0 +1,8 @@
+export interface PriorityCallOptions {
+    asynchronous?: boolean;
+    chainId?: bigint;
+    provideChainId?: boolean;
+    multiplier?: number;
+    signals?: AbortSignal[];
+    timeoutMs?: number;
+}

package/lib/types/priority-call-options.js

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

package/lib/types/split-calls.d.ts

@@ -0,0 +1,9 @@
+import type { ContractCall } from "./contract";
+import type { Tagable } from "./multicall";
+export interface SplitCalls {
+    staticCalls: ContractCall[];
+    staticIndexes: number[];
+    mutableCalls: ContractCall[];
+    mutableTags: Tagable[];
+    mutableIndexes: number[];
+}

package/lib/types/split-calls.js

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

package/lib/types/state-mutabiity.d.ts

@@ -0,0 +1,6 @@
+export declare enum StateMutability {
+    View = "view",
+    Pure = "pure",
+    NonPayable = "nonpayable",
+    Payable = "payable"
+}

package/lib/types/state-mutabiity.js

@@ -0,0 +1,7 @@
+export var StateMutability;
+(function (StateMutability) {
+    StateMutability["View"] = "view";
+    StateMutability["Pure"] = "pure";
+    StateMutability["NonPayable"] = "nonpayable";
+    StateMutability["Payable"] = "payable";
+})(StateMutability || (StateMutability = {}));

package/lib/utils/check-signals.d.ts

@@ -0,0 +1 @@
+export declare function checkSignals(signals: AbortSignal[] | undefined): void;

package/lib/utils/check-signals.js

@@ -0,0 +1,4 @@
+export function checkSignals(signals) {
+    if (signals)
+        signals.forEach((signal) => signal.throwIfAborted());
+}

package/lib/utils/create-signals-promise.d.ts

@@ -0,0 +1 @@
+export declare function createSignalsPromise(signals?: AbortSignal[]): Promise<never>;

package/lib/utils/create-signals-promise.js

@@ -0,0 +1,8 @@
+export function createSignalsPromise(signals = []) {
+    return new Promise((_, reject) => {
+        const onAbort = (signal) => reject(signal.reason || new Error("Operation aborted"));
+        for (const signal of signals) {
+            signal.addEventListener("abort", () => onAbort(signal), { once: true });
+        }
+    });
+}

package/lib/utils/create-timeout-signal.d.ts

@@ -0,0 +1 @@
+export declare function createTimeoutSignal(ms: number): AbortSignal;