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

package/lib/contract/base-contract.js

@@ -0,0 +1,191 @@
+import { Contract as EthersContract, Wallet, WebSocketProvider, } from "ethers";
+import { config } from "../config";
+import { CONTRACTS_ERRORS } from "../errors";
+import { isSigner, isStaticMethod } from "../helpers";
+import { CallMutability, } from "../types";
+import { checkSignals, createTimeoutSignal, priorityCall, raceWithSignals, waitWithSignals, } from "../utils";
+import { contractCreateCallName } from "./contract-create-call-name";
+export class BaseContract {
+    static createAutoClass(abi, address, driver, options) {
+        return class extends this {
+            constructor(args) {
+                super(args?.abi || abi, args?.address || address, args?.driver || driver, args?.options || options);
+                for (const fragment of Object.values(this.interface.fragments)) {
+                    if (fragment.type === "function") {
+                        const funcFragment = fragment;
+                        const name = funcFragment.name;
+                        if (!(name in this)) {
+                            Object.defineProperty(this, name, {
+                                value: async (args = [], options) => this.call(name, args, options),
+                                writable: true,
+                                enumerable: true,
+                            });
+                        }
+                        const getCallName = contractCreateCallName(name);
+                        if (!(getCallName in this)) {
+                            Object.defineProperty(this, getCallName, {
+                                value: (args = [], callData = {}) => this.getCall(name, args, callData),
+                                writable: true,
+                                enumerable: true,
+                            });
+                        }
+                    }
+                }
+            }
+        };
+    }
+    static createAutoInstance(abi, address, driver, options) {
+        const AutoClass = this.createAutoClass(abi, address, driver, options);
+        return new AutoClass({ abi, address, driver, options });
+    }
+    constructor(abi, address = "0x0000000000000000000000000000000000000000", driver, options = {}) {
+        this.contractOptions = {};
+        this.address = address;
+        this.driver = driver;
+        this.isCallable = !!address && !!driver;
+        this.isReadonly = !this.isCallable || !(driver instanceof Wallet);
+        this.contract = new EthersContract(address, abi, driver);
+        this.contractOptions = {
+            staticCallsTimeoutMs: config.contract.staticCalls.timeoutMs,
+            mutableCallsTimeoutMs: config.contract.mutableCalls.timeoutMs,
+            ...options,
+        };
+    }
+    get provider() {
+        if (!this.driver)
+            return null;
+        return this.driver.provider;
+    }
+    get signer() {
+        if (isSigner(this.driver))
+            return this.driver;
+        return null;
+    }
+    get interface() {
+        return this.contract.interface;
+    }
+    async call(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);
+        const callOptions = {
+            forceMutability: this.contractOptions.forceMutability,
+            highPriorityTx: this.contractOptions.highPriorityTxs,
+            priorityOptions: this.contractOptions.priorityOptions,
+            ...options,
+        };
+        const isStatic = callOptions.forceMutability
+            ? callOptions.forceMutability === CallMutability.Static
+            : isStaticMethod(functionFragment.stateMutability);
+        const localSignals = [];
+        if (callOptions.signals)
+            localSignals.push(...callOptions.signals);
+        if (callOptions.timeoutMs)
+            localSignals.push(this.getTimeoutSignal(isStatic, callOptions.timeoutMs));
+        if (isStatic) {
+            return raceWithSignals(() => methodFn.staticCall(...args), localSignals);
+        }
+        else {
+            if (this.isReadonly)
+                throw CONTRACTS_ERRORS.READ_ONLY_CONTRACT_MUTATION;
+            let tx;
+            if (callOptions.highPriorityTx) {
+                const provider = this.driver?.provider;
+                tx = await raceWithSignals(() => priorityCall(provider, this.driver, this.contract, method, args, {
+                    signals: localSignals,
+                    ...options.priorityOptions,
+                }), localSignals);
+            }
+            else {
+                tx = await raceWithSignals(() => methodFn(...args), localSignals);
+            }
+            return tx;
+        }
+    }
+    getCall(methodName, args = [], callData = {}) {
+        if (!this.address)
+            throw CONTRACTS_ERRORS.NON_CALLABLE_CONTRACT_INVOCATION;
+        const functionFragment = this.interface.getFunction(methodName);
+        if (!functionFragment)
+            throw CONTRACTS_ERRORS.FRAGMENT_NOT_DEFINED(methodName);
+        return {
+            method: methodName,
+            target: this.address,
+            allowFailure: config.multicallUnit.allowFailure,
+            callData: this.interface.encodeFunctionData(methodName, args),
+            stateMutability: functionFragment.stateMutability,
+            contractInterface: this.interface,
+            ...callData,
+        };
+    }
+    async listenEvent(eventName, listener) {
+        if (!this.isCallable)
+            throw CONTRACTS_ERRORS.NON_CALLABLE_CONTRACT_INVOCATION;
+        if (!(this.provider instanceof WebSocketProvider))
+            throw CONTRACTS_ERRORS.MISSING_WEBSOCKET_PROVIDER;
+        return this.contract.on(eventName, listener);
+    }
+    async getLogs(fromBlock, eventsNames = [], toBlock = 0, options = {}) {
+        const descriptions = [];
+        for await (const description of this.getLogsStream(fromBlock, eventsNames, toBlock, options)) {
+            descriptions.push(description);
+        }
+        return descriptions;
+    }
+    async *getLogsStream(fromBlock, eventsNames = [], toBlock = 0, // Latest by default
+    options = {}) {
+        if (!this.isCallable)
+            throw CONTRACTS_ERRORS.NON_CALLABLE_CONTRACT_INVOCATION;
+        const streamOptions = {
+            blocksStep: this.contractOptions.logsBlocksStep ||
+                config.contract.logsGathering.blocksStep,
+            delayMs: this.contractOptions.logsDelayMs ||
+                config.contract.logsGathering.delayMs,
+            ...options,
+        };
+        const topics = eventsNames.map((event) => this.contract.getEvent(event).fragment.topicHash);
+        checkSignals(options.signals);
+        const finToBlock = toBlock
+            ? toBlock
+            : await this.provider.getBlockNumber();
+        const finFromBlock = fromBlock < 0 ? finToBlock + fromBlock : fromBlock;
+        for (let from = finFromBlock; from < finToBlock; from += streamOptions.blocksStep) {
+            checkSignals(options.signals);
+            const to = Math.min(from + streamOptions.blocksStep, finToBlock);
+            const localLogs = await this.provider.getLogs({
+                fromBlock: from,
+                toBlock: to,
+                address: this.address,
+                topics: topics.length ? [topics] : undefined,
+            });
+            for (const log of localLogs) {
+                checkSignals(options.signals);
+                const description = this.interface.parseLog(log);
+                if (!description)
+                    continue;
+                yield description;
+            }
+            await waitWithSignals(streamOptions.delayMs, options.signals);
+        }
+    }
+    getTimeoutSignal(isStatic, timeoutMs) {
+        let timeout;
+        if (timeoutMs) {
+            timeout = timeoutMs;
+        }
+        else {
+            if (isStatic) {
+                timeout = this.contractOptions.staticCallsTimeoutMs;
+            }
+            else {
+                timeout = this.contractOptions.mutableCallsTimeoutMs;
+            }
+        }
+        return createTimeoutSignal(timeout);
+    }
+}

package/lib/contract/contract-create-call-name.d.ts

@@ -0,0 +1 @@
+export declare const contractCreateCallName: (name: string) => string;

package/lib/contract/contract-create-call-name.js

@@ -0,0 +1 @@
+export const contractCreateCallName = (name) => `${name.startsWith("get") ? name : `get${name[0].toUpperCase()}${name.slice(1)}`}Call`;

package/lib/contract/index.d.ts

@@ -0,0 +1 @@
+export * from "./base-contract";

package/lib/contract/index.js

@@ -0,0 +1 @@
+export * from "./base-contract";

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

@@ -0,0 +1,9 @@
+export declare const CONTRACTS_ERRORS: {
+    NON_CALLABLE_CONTRACT_INVOCATION: Error;
+    READ_ONLY_CONTRACT_MUTATION: Error;
+    MISSING_CONTRACT_ADDRESS: Error;
+    METHOD_NOT_DEFINED: (methodName: any) => Error;
+    FRAGMENT_NOT_DEFINED: (methodName: any) => Error;
+    MISSING_WEBSOCKET_PROVIDER: Error;
+    MISSING_PROVIDER: Error;
+};

package/lib/errors/contracts-errors.js

@@ -0,0 +1,9 @@
+export const CONTRACTS_ERRORS = {
+    NON_CALLABLE_CONTRACT_INVOCATION: new Error("The contract was created as non-callable, but an attempt was made to call it!"),
+    READ_ONLY_CONTRACT_MUTATION: new Error("The contract was created as read-only, but an attempt was made to call mutable method!"),
+    MISSING_CONTRACT_ADDRESS: new Error("A contract address was not provided!"),
+    METHOD_NOT_DEFINED: (methodName) => new Error(`Method "${methodName}" was not found on the contract!`),
+    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!"),
+};

package/lib/errors/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./multicall-errors";
+export * from "./contracts-errors";

package/lib/errors/index.js

@@ -0,0 +1,2 @@
+export * from "./multicall-errors";
+export * from "./contracts-errors";

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

@@ -0,0 +1,8 @@
+export declare const MULTICALL_ERRORS: {
+    SIMULTANEOUS_INVOCATIONS: Error;
+    RESULT_NOT_FOUND: Error;
+    RESPONSE_NOT_FOUND: Error;
+    RECEIPT_NOT_FOUND: Error;
+    MISSING_PROVIDER_INTERFACE: Error;
+    MISSING_PROVIDER_CALL_DATA: Error;
+};

package/lib/errors/multicall-errors.js

@@ -0,0 +1,8 @@
+export const MULTICALL_ERRORS = {
+    SIMULTANEOUS_INVOCATIONS: new Error("Multicall -> Another execution was triggered during processing."),
+    RESULT_NOT_FOUND: new Error("Multicall result not found."),
+    RESPONSE_NOT_FOUND: new Error("Multicall response not found."),
+    RECEIPT_NOT_FOUND: new Error("Multicall receipt not received."),
+    MISSING_PROVIDER_INTERFACE: new Error("MulticallProvider -> Missing contractInterface in customData."),
+    MISSING_PROVIDER_CALL_DATA: new Error('MulticallProvider -> Missing "to" or "data".'),
+};

package/lib/helpers/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./is-static-array";
+export * from "./is-static-method";
+export * from "./wait-for-address-txs";
+export * from "./is-signer";
+export * from "./is-parsable";
+export * from "./priority-call";

package/lib/helpers/index.js

@@ -0,0 +1,6 @@
+export * from "./is-static-array";
+export * from "./is-static-method";
+export * from "./wait-for-address-txs";
+export * from "./is-signer";
+export * from "./is-parsable";
+export * from "./priority-call";

package/lib/helpers/is-parsable.d.ts

@@ -0,0 +1,2 @@
+import type { ContractCall } from "../types";
+export declare const isParsable: (call: ContractCall) => boolean;

package/lib/helpers/is-parsable.js

@@ -0,0 +1 @@
+export const isParsable = (call) => call.method !== undefined && call.contractInterface !== undefined;

package/lib/helpers/is-signer.d.ts

@@ -0,0 +1,2 @@
+import type { Signer } from "ethers";
+export declare const isSigner: (driver: Signer) => boolean;

package/lib/helpers/is-signer.js

@@ -0,0 +1,3 @@
+export const isSigner = (driver) => {
+    return typeof driver?.getAddress === "function";
+};

package/lib/helpers/is-static-array.d.ts

@@ -0,0 +1,2 @@
+import type { ContractCall } from "../types";
+export declare const isStaticArray: (calls: ContractCall[]) => boolean;

package/lib/helpers/is-static-array.js

@@ -0,0 +1,2 @@
+import { isStaticMethod } from "./is-static-method";
+export const isStaticArray = (calls) => !calls.some((call) => !isStaticMethod(call.stateMutability));

package/lib/helpers/is-static-method.d.ts

@@ -0,0 +1,2 @@
+import { StateMutability } from "../types";
+export declare const isStaticMethod: (state: StateMutability | string) => boolean;

package/lib/helpers/is-static-method.js

@@ -0,0 +1,4 @@
+import { StateMutability } from "../types";
+export const isStaticMethod = (state) => {
+    return state === StateMutability.View || state === StateMutability.Pure;
+};

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

@@ -0,0 +1,5 @@
+import type { Contract, Provider, TransactionRequest } from "ethers";
+import type { PriorityCallOptions } from "../types";
+export declare function priorityCall(provider: Provider, signer: {
+    sendTransaction: (txn: TransactionRequest) => Promise<any>;
+}, contract: Contract, method: string, args?: any[], options?: PriorityCallOptions): Promise<any>;

package/lib/helpers/priority-call.js

@@ -0,0 +1,55 @@
+import { DEFAULT_PRIORITY_CALL_MULTIPLIER } from "../constant";
+import { checkSignals, createTimeoutSignal } from "../utils";
+export async function priorityCall(provider, signer, contract, method, args = [], options = {}) {
+    const localOptions = {
+        multiplier: DEFAULT_PRIORITY_CALL_MULTIPLIER,
+        ...options,
+    };
+    const localSignals = [];
+    if (localOptions.signals)
+        localSignals.push(...localOptions.signals);
+    if (localOptions.timeoutMs)
+        localSignals.push(createTimeoutSignal(localOptions.timeoutMs));
+    checkSignals(localSignals);
+    const [originalFeeData, originalGasLimit] = await gatherOriginalData(provider, contract, method, args, localOptions.asynchronous ?? false, localSignals);
+    const maxFeePerGas = Math.ceil(localOptions.multiplier * Number(originalFeeData.maxFeePerGas));
+    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, {
+        gasLimit,
+        maxFeePerGas,
+        maxPriorityFeePerGas,
+    });
+    // Prevents conflicts when using signer.sendTransaction(txn), as the signer should determine the from address.
+    // Avoids potential issues if from is incorrectly set or differs from the signer's address.
+    delete txn.from;
+    if (localOptions.provideChainId) {
+        checkSignals(localSignals);
+        const network = await provider.getNetwork();
+        txn.chainId = network.chainId;
+    }
+    else if (localOptions.chainId) {
+        txn.chainId = localOptions.chainId;
+    }
+    checkSignals(localSignals);
+    return signer.sendTransaction(txn);
+}
+async function gatherOriginalData(provider, contract, method, args = [], asynchronous, signals) {
+    let originalFeeData;
+    let originalGasLimit;
+    checkSignals(signals);
+    if (asynchronous) {
+        [originalFeeData, originalGasLimit] = await Promise.all([
+            provider.getFeeData(),
+            contract.getFunction(method).estimateGas(...args),
+        ]);
+        return [originalFeeData, originalGasLimit];
+    }
+    originalFeeData = await provider.getFeeData();
+    checkSignals(signals);
+    originalGasLimit = await contract.getFunction(method).estimateGas(...args);
+    return [originalFeeData, originalGasLimit];
+}

package/lib/helpers/wait-for-address-txs.d.ts

@@ -0,0 +1,2 @@
+import type { Provider } from "ethers";
+export declare const waitForAddressTxs: (address: string, provider: Provider, delayMs?: number) => Promise<void>;

package/lib/helpers/wait-for-address-txs.js

@@ -0,0 +1,9 @@
+export const waitForAddressTxs = async (address, provider, delayMs = 1000) => {
+    let flag = true;
+    while (flag) {
+        const pendingNonce = await provider.getTransactionCount(address, "pending");
+        const latestNonce = await provider.getTransactionCount(address, "latest");
+        flag = pendingNonce > latestNonce;
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+};

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./contract";
+export * from "./multicall";
+export * from "./config";
+export * from "./helpers";
+export * from "./types";

package/lib/index.js

@@ -0,0 +1,5 @@
+export * from "./contract";
+export * from "./multicall";
+export * from "./config";
+export * from "./helpers";
+export * from "./types";

package/lib/multicall/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./multicall-normalize-tags";
+export * from "./multicall-split-calls";
+export * from "./multicall-unit";
+export * from "./multicall-normalize-tags";
+export * from "./multicall-split-calls";

package/lib/multicall/index.js

@@ -0,0 +1,5 @@
+export * from "./multicall-normalize-tags";
+export * from "./multicall-split-calls";
+export * from "./multicall-unit";
+export * from "./multicall-normalize-tags";
+export * from "./multicall-split-calls";

package/lib/multicall/multicall-error-event-name.d.ts

@@ -0,0 +1,2 @@
+import type { Tagable } from "../types";
+export declare const multicallErrorEventName: (normalizedTags: Tagable) => string;

package/lib/multicall/multicall-error-event-name.js

@@ -0,0 +1 @@
+export const multicallErrorEventName = (normalizedTags) => `error:${String(normalizedTags)}`;

package/lib/multicall/multicall-generate-tag.d.ts

@@ -0,0 +1 @@
+export declare const multicallGenerateTag: () => string;

package/lib/multicall/multicall-generate-tag.js

@@ -0,0 +1 @@
+export const multicallGenerateTag = () => `tag:${Date.now()}:${crypto.randomUUID()}`;

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

@@ -0,0 +1,2 @@
+import type { MulticallTags, Tagable } from "../types";
+export declare const multicallNormalizeTags: (tags: MulticallTags) => Tagable;

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

@@ -0,0 +1,6 @@
+export const multicallNormalizeTags = (tags) => {
+    if (typeof tags === "object" || Array.isArray(tags)) {
+        return JSON.stringify(tags, (_, value) => typeof value === "bigint" ? value.toString() : value);
+    }
+    return tags;
+};

package/lib/multicall/multicall-result-event-name.d.ts

@@ -0,0 +1,2 @@
+import type { Tagable } from "../types";
+export declare const multicallResultEventName: (normalizedTags: Tagable) => string;

package/lib/multicall/multicall-result-event-name.js

@@ -0,0 +1 @@
+export const multicallResultEventName = (normalizedTags) => `result:${String(normalizedTags)}`;

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

@@ -0,0 +1,2 @@
+import type { ContractCall, SplitCalls, Tagable } from "../types";
+export declare const multicallSplitCalls: (calls: ContractCall[], tags: Tagable[]) => SplitCalls;

package/lib/multicall/multicall-split-calls.js

@@ -0,0 +1,19 @@
+import { isStaticMethod } from "../helpers";
+export const multicallSplitCalls = (calls, tags) => calls.reduce((acc, call, index) => {
+    if (isStaticMethod(call.stateMutability)) {
+        acc.staticCalls.push(call);
+        acc.staticIndexes.push(index);
+    }
+    else {
+        acc.mutableCalls.push(call);
+        acc.mutableTags.push(tags[index]);
+        acc.mutableIndexes.push(index);
+    }
+    return acc;
+}, {
+    staticCalls: [],
+    staticIndexes: [],
+    mutableCalls: [],
+    mutableTags: [],
+    mutableIndexes: [],
+});

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

@@ -0,0 +1,48 @@
+import { EventEmitter } from "node:events";
+import type { Provider, Signer, TransactionReceipt, TransactionResponse } from "ethers";
+import { BaseContract } from "../contract";
+import { type ContractCall, type MulticallOptions, type MulticallTags, type MulticallWaitOptions, type Tagable } from "../types";
+export type Response = [success: boolean, rawData: string];
+export declare class MulticallUnit extends BaseContract {
+    protected _units: Map<Tagable, ContractCall>;
+    protected _response: Response[];
+    protected _rawData: Map<Tagable, string>;
+    protected _callsSuccess: Map<Tagable, boolean>;
+    protected _lastSuccess: boolean | undefined;
+    protected _isExecuting: boolean;
+    protected _emitter: EventEmitter<[never]>;
+    protected _multicallOptions: MulticallOptions;
+    protected _txResponses: Map<any, any>;
+    protected _txReceipts: Map<any, any>;
+    constructor(driver: Signer | Provider, options?: MulticallOptions, multicallAddress?: string);
+    clear(): void;
+    add(contractCall: ContractCall, tags: MulticallTags): MulticallTags;
+    get tags(): Tagable[];
+    get calls(): ContractCall[];
+    get response(): Response[];
+    get success(): boolean | undefined;
+    get static(): boolean;
+    get executing(): boolean;
+    isSuccess(tags: MulticallTags): boolean | undefined;
+    getRaw(tags: MulticallTags): string | null;
+    getSingle<T>(tags: MulticallTags): T | null;
+    getArray<T>(tags: MulticallTags, deep?: boolean): T | null;
+    run(options?: Partial<MulticallOptions>): Promise<boolean>;
+    private processStaticCalls;
+    private processMutableCalls;
+    private saveResponse;
+    getOrThrow<T>(tags: MulticallTags, deep?: boolean): T;
+    get<T>(tags: MulticallTags, deep?: boolean): T | null;
+    private getDecodableData;
+    waitRawOrThrow(tags: MulticallTags, options?: MulticallWaitOptions): Promise<string>;
+    waitRaw(tags: MulticallTags, options?: MulticallWaitOptions): Promise<string | null>;
+    wait(tags: MulticallTags, options?: MulticallWaitOptions): Promise<void>;
+    waitTxOrThrow(tags: MulticallTags, options?: MulticallWaitOptions): Promise<TransactionResponse>;
+    waitTx(tags: MulticallTags, options?: MulticallWaitOptions): Promise<TransactionResponse | null>;
+    getTxResponse(tags: MulticallTags): TransactionResponse | null;
+    getTxResponseOrThrow(tags: MulticallTags): TransactionResponse;
+    getTxReceipt(tags: MulticallTags): TransactionReceipt | null;
+    getObjectOrThrow<T>(tags: MulticallTags, deep?: boolean): T;
+    getObject<T>(tags: MulticallTags, deep?: boolean): T | null;
+    waitFor<T>(tags: MulticallTags, options?: MulticallWaitOptions): Promise<T>;
+}