dequanto 0.2.27 → 0.2.29

package/src/class/PackedRanges.ts

@@ -19,7 +19,7 @@ export class PackedRanges {
     constructor(opts?: {
         from?: number
         to?: number
-        ranges?: [ number, number ][]
+        ranges?: [number, number][]
     }) {
 
         if (opts != null) {
@@ -29,7 +29,8 @@ export class PackedRanges {
         }
     }
 
-    total () {
+    // Get the outer range [from..to] total capacity (regardless of tracked ranges)
+    total() {
         let min = this.from;
         let max = this.to ?? this.getMax();
         if (min == null || max == null) {
@@ -37,7 +38,8 @@ export class PackedRanges {
         }
         return max - min;
     }
-    totalAdded () {
+    // Get the sum of all tracked range lengths (total numbers visited/added)
+    totalAdded() {
         let count = 0;
         for (let i = 0; i < this.ranges.length; i++) {
             let [min, max] = this.ranges[i];
@@ -45,11 +47,32 @@ export class PackedRanges {
         }
         return count;
     }
-    totalLeft () {
+
+    /**
+     * Calculates the number of elements remaining to be visited/added in the range.
+     * This is the difference between the total capacity and the number of elements already tracked.
+     */
+    totalLeft() {
         return this.total() - this.totalAdded();
     }
 
 
+    /**
+     * Gets the next unvisited number in the range and marks it as visited.
+     *
+     * This method finds the next number that hasn't been added to the tracked ranges yet,
+     * automatically adds it to the ranges, and returns it. It respects the boundaries
+     * defined by `from` and `to` properties.
+     *
+     * The method works by:
+     * - Starting from `this.from` if no ranges exist
+     * - Filling gaps between existing ranges
+     * - Extending the last range if no gaps exist
+     * - Merging adjacent ranges when they become contiguous
+     *
+     * @returns The next unvisited number in the range, or `null` if all numbers up to `this.to` have been visited
+     * @throws {Error} If the internal ranges array is in an invalid state (unsorted or overlapping)
+     */
     next(): number {
         let min = this.from;
         if (this.ranges.length === 0) {
@@ -88,6 +111,14 @@ export class PackedRanges {
         return r0Max;
     }
 
+    /**
+     * Gets the maximum (upper bound) value from all tracked ranges.
+     *
+     * This method returns the highest number that has been visited/added to the ranges.
+     * It retrieves the upper bound of the last range in the sorted ranges array.
+     *
+     * @returns The maximum value in the tracked ranges, or `null` if no ranges have been added yet
+     */
     getMax() {
         if (this.ranges.length === 0) {
             return null;
@@ -96,6 +127,16 @@ export class PackedRanges {
         return r[1];
     }
 
+    /**
+     * Checks if a specific number has been visited/added to the tracked ranges.
+     *
+     * This method searches through all tracked ranges to determine if the given number
+     * falls within any of them. It performs a linear search through the ranges array,
+     * checking if the number is within the bounds (inclusive) of any range.
+     *
+     * @param nr - The number to check for inclusion in the tracked ranges
+     * @returns `true` if the number exists within any of the tracked ranges, `false` otherwise
+     */
     includes(nr: number) {
         for (let i = 0; i < this.ranges.length; i++) {
             let [a, b] = this.ranges[i];
@@ -106,6 +147,21 @@ export class PackedRanges {
         return false;
     }
 
+    /**
+     * Adds a number to the tracked ranges, marking it as visited.
+     *
+     * This method intelligently adds a number to the ranges by either:
+     * - Extending an existing range if the number is adjacent to it
+     * - Creating a new range if the number is isolated
+     * - Doing nothing if the number is already included in an existing range
+     *
+     * The method maintains the sorted order of ranges and automatically merges
+     * adjacent numbers into contiguous ranges for efficient storage.
+     *
+     * @param nr - The number to add to the tracked ranges
+     * @returns `true` if the number was successfully added (new or extended a range),
+     *          `false` if the number was already present in the ranges
+     */
     add(nr: number) {
         let modified = false;
         for (let i = 0; i < this.ranges.length; i++) {
@@ -142,7 +198,43 @@ export class PackedRanges {
         }
         return true;
     }
-    remove (nr: number) {
+
+    /**
+     * Adds a complete range to the tracked ranges and compacts the result.
+     *
+     * This method adds an entire range [min, max] to the tracked ranges array,
+     * then automatically compacts the ranges to merge any overlapping or adjacent
+     * ranges. This is useful for bulk operations where you want to mark multiple
+     * consecutive numbers as visited at once.
+     *
+     * Unlike the `add()` method which adds individual numbers, this method adds
+     * a complete range tuple and ensures the internal ranges array remains optimized
+     * by calling `compact()` after insertion.
+     *
+     * @param range - A tuple [min, max] representing the range to add, where both bounds are inclusive
+     */
+    addRange(range: [number, number]) {
+        this.ranges.push(range);
+        this.compact();
+    }
+
+    /**
+     * Removes a specific number from the tracked ranges, marking it as unvisited.
+     *
+     * This method searches for the number within the tracked ranges and removes it by either:
+     * - Removing the entire range if it contains only the target number
+     * - Shrinking the range by adjusting its lower bound if the number is at the start
+     * - Shrinking the range by adjusting its upper bound if the number is at the end
+     * - Splitting the range into two separate ranges if the number is in the middle
+     *
+     * The method maintains the sorted order of ranges and ensures efficient storage
+     * by handling all edge cases appropriately.
+     *
+     * @param nr - The number to remove from the tracked ranges
+     * @returns `true` if the number was found and successfully removed from the ranges,
+     *          `false` if the number was not present in any of the tracked ranges
+     */
+    remove(nr: number) {
         for (let i = 0; i < this.ranges.length; i++) {
             let [min, max] = this.ranges[i];
             if (min <= nr && nr <= max) {
@@ -160,8 +252,8 @@ export class PackedRanges {
                     return true;
                 }
 
-                let arr1 = [min, nr - 1] as [ number, number];
-                let arr2 = [nr + 1, max] as [ number, number];
+                let arr1 = [min, nr - 1] as [number, number];
+                let arr2 = [nr + 1, max] as [number, number];
                 this.ranges.splice(i, 1, arr1, arr2);
                 return true;
             }
@@ -169,45 +261,373 @@ export class PackedRanges {
         return false;
     }
 
+    /**
+     * Removes a range of numbers from the tracked ranges, marking them as unvisited.
+     *
+     * This method subtracts the specified range from all tracked ranges, effectively
+     * removing all numbers within the given range from the visited/added set. It handles
+     * overlapping ranges by splitting or trimming existing ranges as needed.
+     *
+     * The method maintains the sorted order of ranges and ensures efficient storage
+     * by delegating to the `Ranges.subtract()` utility function.
+     *
+     * @param range - A tuple [min, max] representing the range to remove, where both bounds are inclusive
+     * @returns The current `PackedRanges` instance for method chaining
+     */
+    subtractRange(range: [number, number]) {
+        this.ranges = Ranges.subtract(this.ranges, range);
+        return this;
+    }
+
+    /**
+     * Removes multiple ranges of numbers from the tracked ranges, marking them as unvisited.
+     *
+     * This method subtracts all specified ranges from the tracked ranges, effectively
+     * removing all numbers within the given ranges from the visited/added set. It handles
+     * overlapping ranges by splitting or trimming existing ranges as needed for each
+     * range in the input array.
+     *
+     * The method maintains the sorted order of ranges and ensures efficient storage
+     * by delegating to the `Ranges.subtractMany()` utility function.
+     *
+     * @param ranges - An array of tuples [min, max] representing the ranges to remove, where both bounds are inclusive
+     * @returns The current `PackedRanges` instance for method chaining
+     */
+    subtractRanges(ranges: [number, number][]) {
+        this.ranges = Ranges.subtractMany(this.ranges, ranges);
+        return this;
+    }
+
+    /**
+     * Compacts the tracked ranges by merging overlapping and adjacent ranges.
+     *
+     * This method optimizes the internal ranges array by:
+     * - Merging overlapping ranges into single contiguous ranges
+     * - Joining adjacent ranges (e.g., [1,4] and [5,6] become [1,6])
+     * - Sorting ranges by their starting values
+     * - Removing redundant range entries
+     *
+     * This operation is useful after bulk modifications to ensure the ranges
+     * array remains in its most efficient form for storage and querying.
+     */
     compact() {
-        for (let i = 0; i < this.ranges.length; i++) {
-            let rangeA = this.ranges[i];
-            for (let j = i + 1; j < this.ranges.length; j++) {
-                let rangeB = this.ranges[j];
-                if (Ranges.overlaps(rangeA, rangeB)) {
+        this.ranges = Ranges.compact(this.ranges);
+    }
+
+    /**
+     * Sets the tracked ranges to a new array of ranges and compacts them.
+     *
+     * This method replaces the entire internal ranges array with the provided ranges,
+     * then automatically compacts them to merge any overlapping or adjacent ranges.
+     * This is useful for bulk initialization or restoration of ranges from a saved state.
+     *
+     * After setting the ranges, the method ensures the internal ranges array is optimized
+     * by calling `compact()`, which merges overlapping ranges and joins adjacent ones.
+     *
+     * @param ranges - An array of tuples [min, max] representing the ranges to set, where both bounds are inclusive
+     */
+    set(ranges: [number, number][]) {
+        this.ranges = ranges;
+        this.compact();
+    }
+
+    /**
+     * Serializes the tracked ranges to a JSON string representation.
+     *
+     * This method converts the internal ranges array into a JSON string format,
+     * which can be used for persistence, transmission, or storage purposes.
+     * The serialized string can later be parsed and used to restore the ranges
+     * via the constructor's `ranges` option.
+     *
+     * @returns A JSON string representation of the tracked ranges array
+     */
+    serialize() {
+        return JSON.stringify(this.ranges);
+    }
+
+    /**
+     * Creates a new PackedRanges instance containing only the ranges starting from a specified number.
+     *
+     * This method filters the tracked ranges to include only those that contain or come after
+     * the specified `from` value. If a range overlaps with the `from` value, it is trimmed
+     * to start at `from`. All ranges before `from` are excluded from the result.
+     *
+     * The original PackedRanges instance remains unchanged; a new instance is returned with
+     * the filtered ranges.
+     *
+     * @param from - The starting number from which to pick ranges (inclusive)
+     * @returns A new PackedRanges instance containing only the ranges from the specified number onwards
+     */
+    pickFrom(from: number): PackedRanges {
+        let arr = Ranges.pickFrom(this.ranges, from);
+        return new PackedRanges({ ranges: arr });
+    }
+
+    /**
+     * Creates a new PackedRanges instance containing only the ranges up to a specified number.
+     *
+     * This method filters the tracked ranges to include only those that contain or come before
+     * the specified `to` value. If a range overlaps with the `to` value, it is trimmed
+     * to end at `to`. All ranges after `to` are excluded from the result.
+     *
+     * The original PackedRanges instance remains unchanged; a new instance is returned with
+     * the filtered ranges.
+     *
+     * @param to - The ending number up to which to pick ranges (inclusive)
+     * @returns A new PackedRanges instance containing only the ranges up to the specified number
+     */
+    pickTo(to: number): PackedRanges {
+        let arr = Ranges.pickTo(this.ranges, to);
+        return new PackedRanges({ ranges: arr });
+    }
+
+
+    /**
+     * Computes the intersection of multiple range arrays, returning only the ranges that are common to all inputs.
+     *
+     * This method performs a set intersection operation across multiple arrays of ranges,
+     * finding only those number ranges that appear in every input array. The result is
+     * compacted to merge any overlapping or adjacent ranges for efficient storage.
+     *
+     * For example:
+     * - Input: [[[1,5], [10,15]], [[3,7], [12,20]]]
+     * - Output: [[3,5], [12,15]] (ranges common to both arrays)
+     *
+     * @param rangesArr - An array of range arrays, where each range array contains tuples [min, max] representing inclusive number ranges
+     * @returns A compacted array of ranges representing the intersection of all input range arrays, or an empty array if no common ranges exist or if the input is empty
+     */
+    static intersection(rangesArr: ([number, number][])[]): [number, number][] {
+        if (rangesArr.length === 0) {
+            return [];
+        }
+        let arr = Ranges.clone(rangesArr[0]);
+        for (let i = 1; i < rangesArr.length; i++) {
+            arr = Ranges.intersection(arr, rangesArr[i]);
+        }
+        return Ranges.compact(arr);
+    }
+
+    /**
+     * Computes the union of multiple range arrays, returning all ranges that appear in any of the inputs.
+     *
+     * This method performs a set union operation across multiple arrays of ranges,
+     * combining all number ranges from every input array. The result is compacted to
+     * merge any overlapping or adjacent ranges for efficient storage.
+     *
+     * For example:
+     * - Input: [[[1,5], [10,15]], [[3,7], [12,20]]]
+     * - Output: [[1,7], [10,20]] (all ranges merged and compacted)
+     *
+     * @param rangesArr - An array of range arrays, where each range array contains tuples [min, max] representing inclusive number ranges
+     * @returns A compacted array of ranges representing the union of all input range arrays, or an empty array if the input is empty
+     */
+    static union(rangesArr: ([number, number][])[]): [number, number][] {
+        let arr = alot(rangesArr)
+            .mapMany(x => x)
+            .toArray();
+        return Ranges.compact(arr);
+    }
+
+    /**
+     * Computes the difference between two range arrays, removing all ranges in B from ranges in A.
+     *
+     * This method performs a set difference operation (A − B), subtracting all number ranges
+     * in `rangesB` from `rangesA`. The result contains only those portions of `rangesA` that
+     * do not overlap with any range in `rangesB`. The result is compacted to merge any
+     * overlapping or adjacent ranges for efficient storage.
+     *
+     * For example:
+     * - Input: rangesA = [[1,10], [20,30]], rangesB = [[5,15], [25,35]]
+     * - Output: [[1,4], [20,24]] (parts of A not covered by B)
+     *
+     * @param rangesA - The array of ranges to subtract from, where each range is a tuple [min, max] representing inclusive number ranges
+     * @param rangesB - The array of ranges to subtract, where each range is a tuple [min, max] representing inclusive number ranges
+     * @returns A compacted array of ranges representing the difference (A − B), or an empty array if all of A is covered by B
+     */
+    static subtract(rangesA: [number, number][], rangesB: [number, number][]): [number, number][] {
+        let arr = Ranges.subtractMany(rangesA, rangesB);
+        return Ranges.compact(arr);
+    }
+
+
+    static pickFrom(ranges: [number, number][], from: number): [number, number][] {
+        let arr = Ranges.pickFrom(ranges, from);
+        return arr;
+    }
+
+    static pickTo(ranges: [number, number][], to: number): [number, number][] {
+        let arr = Ranges.pickTo(ranges, to);
+        return arr;
+    }
+}
+
+namespace Range {
+
+    // Check if two ranges overlap
+    export function overlaps(r1: [number, number], r2: [number, number]) {
+        let [x1, y1] = r1;
+        let [x2, y2] = r2;
+        let d = Math.min(y1, y2) - Math.max(x1, x2);
+        return d > -1;
+    }
+
+    // AND: A ∩ B
+    export function intersection(r1: [number, number], r2: [number, number]) {
+        let [x1, y1] = r1;
+        let [x2, y2] = r2;
+        let minY = Math.min(y1, y2);
+        let maxX = Math.max(x1, x2);
+        if (minY >= maxX) {
+            return [maxX, minY] as [number, number];
+        }
+        return null;
+    }
+
+}
+
+
+
+namespace Ranges {
+    export function clone(ranges: [number, number][]) {
+        let arr = [] as [number, number][];
+        for (let [x, y] of ranges) {
+            arr.push([x, y]);
+        }
+        return arr;
+    }
+
+    // AND: A ∩ B
+    export function intersection(rangesA: [number, number][], rangesB: [number, number][]) {
+        let arr = [] as [number, number][];
+        for (let i = 0; i < rangesA.length; i++) {
+            let rA = rangesA[i];
+            for (let j = 0; j < rangesB.length; j++) {
+                let union = Range.intersection(rA, rangesB[j]);
+                if (union) {
+                    arr.push(union);
+                    continue;
+                }
+            }
+        }
+        return arr;
+    }
+
+    export function compact (ranges: [number, number][]): [number, number][] {
+        for (let i = 0; i < ranges.length; i++) {
+            let rangeA = ranges[i];
+            for (let j = i + 1; j < ranges.length; j++) {
+                let rangeB = ranges[j];
+                if (Range.overlaps(rangeA, rangeB)) {
                     let [x1, y1] = rangeA;
                     let [x2, y2] = rangeB;
 
-                    this.ranges[i] = [Math.min(x1, x2), Math.max(y1, y2)];
-                    this.ranges.splice(j, 1);
+                    ranges[i] = [Math.min(x1, x2), Math.max(y1, y2)];
+                    ranges.splice(j, 1);
                     j--;
                     continue;
                 }
             }
         }
 
-        this.ranges = alot(this.ranges)
+        ranges = alot(ranges)
             .sortBy(([x]) => x)
             .toArray();
+
+        // Join non overlapping ranges: [1,4],[5, 6] -> [1,6]
+        for (let i = 0; i < ranges.length - 1; i++) {
+            let A = ranges[i];
+            let B = ranges[i + 1];
+            let aLast = A[A.length - 1];
+            let bFirst = B[0];
+            if (aLast + 1 === bFirst) {
+                let bLast = B[B.length - 1];
+                A[A.length - 1] = bLast;
+                ranges.splice(i + 1, 1);
+            }
+        }
+
+        return ranges;
     }
 
-    set(ranges: [number, number][]) {
-        this.ranges = ranges;
-        this.compact();
+    // Difference: A \ B
+    export function subtract(ranges:[number, number][], range: [number, number]) {
+        let arr = [] as [number, number][];
+        let [rmFrom, rmTo] = range;
+        for (let i = 0; i < ranges.length; i++) {
+            let A = ranges[i];
+            if (Range.overlaps(A, range) === false) {
+                arr.push(A);
+                continue;
+            }
+            let [Amin, Amax] = ranges[i];
+            if (Amin < rmFrom) {
+                arr.push([Amin, rmFrom - 1]);
+            }
+            if (Amax > rmTo) {
+                arr.push([rmTo + 1, Amax]);
+            }
+        }
+        return arr;
     }
-    serialize() {
-        return JSON.stringify(this.ranges);
+
+    // Difference: A \ ∩B
+    export function subtractMany(ranges:[number, number][], rangeArr: [number, number][]) {
+        let arr = ranges;
+        for (let range of rangeArr) {
+            arr = subtract(arr, range);
+        }
+        return arr;
     }
-}
 
+    export function pickFrom(ranges: [number, number][], from: number): [number, number][] {
+        if (ranges == null || ranges.length === 0) {
+            return [];
+        }
+        let arr = [] as [number, number][];
+        for (let i = 0; i < ranges.length; i++) {
+            let A = ranges[i];
+            let aFirst = A[0];
+            let aLast = A[A.length - 1];
+            if (aLast < from) {
+                // This part is fully before from, ignore, search for the next part
+                continue;
+            }
+            if (from < aFirst) {
+                // No overlapping, pick all ranges
+                arr = ranges.slice(i).map(([x, y]) => [x, y]);
+                break;
+            }
+            let overlapped = [from, aLast] as [number, number];
+            arr = ranges.slice(i + 1).map(([x, y]) => [x, y]);
+            arr.unshift(overlapped)
+            break;
+        }
+        return arr
+    }
 
+    export function pickTo(ranges: [number, number][], to: number): [number, number][] {
+        if (ranges == null || ranges.length === 0) {
+            return [];
+        }
+        let arr = [] as [number, number][];
+        for (let i = 0; i < ranges.length; i++) {
+            let A = ranges[i];
+            let aFirst = A[0];
+            let aLast = A[A.length - 1];
 
-namespace Ranges {
-    export function overlaps (r1: [number, number], r2: [number, number]) {
-        let [x1, y1] = r1;
-        let [x2, y2] = r2;
-        let d = Math.min(y1, y2) - Math.max(x1, x2);
+            if (aFirst > to) {
+                // This part starts after 'to' => break (as sorted, next parts also start after 'to')
+                break;
+            }
 
-        return d > -1;
+            if (aLast < to) {
+                // No overlapping, pick full range
+                arr.push([aFirst, aLast]);
+            } else {
+                // Overlapps
+                arr.push([aFirst, to]);
+            }
+        }
+        return arr;
     }
 }

package/src/clients/Web3Client.ts

@@ -586,6 +586,10 @@ export type TLogsRangeProgress<TLogParsed> = {
     blocksPerSecond: number
     timeLeftSeconds: number
     completed: boolean
+    infos: {
+        fetched: number
+        cached: number
+    }
 }
 
 namespace RangeWorker {
@@ -658,7 +662,8 @@ namespace RangeWorker {
                 blocks: perf.blocks,
                 blocksPerSecond: Number(blocksPerSecFormatted),
                 timeLeftSeconds: leftSeconds,
-                completed: cursor >= toBlock
+                completed: cursor >= toBlock,
+                infos: { fetched: perf.blocks.loaded, cached: 0 }
             });
 
             let lastNodeStats = Date.now() - nodeStats;

package/src/contracts/ContractReader.ts

@@ -19,8 +19,10 @@ import { $require } from '@dequanto/utils/$require';
 import { $array } from '@dequanto/utils/$array';
 import { RpcTypes } from '@dequanto/rpc/Rpc';
 import { TEth } from '@dequanto/models/TEth';
-import { TRpcContractCall } from '@dequanto/rpc/RpcContract';
+import { RpcContract, TRpcContractCall } from '@dequanto/rpc/RpcContract';
 import { WClient } from '@dequanto/clients/ClientPool';
+import { $traces } from '@dequanto/utils/$traces';
+import { $abiProvider } from '@dequanto/utils/$abiProvider';
 
 
 
@@ -35,7 +37,10 @@ export class ContractReader implements IContractReader {
     private blockNumberTask: Promise<number>;
     private options: TRpcContractCall = {};
 
-    constructor(public client: Web3Client = di.resolve(EthWeb3Client), private ctx?: { name?: string }) {
+    constructor(public client: Web3Client = di.resolve(EthWeb3Client), private ctx?: {
+        name?: string
+        color?: boolean
+    }) {
 
     }
     forBlock (mix: number | Date | undefined) {
@@ -107,7 +112,29 @@ export class ContractReader implements IContractReader {
             return result as TResult;
         } catch (error) {
             let args = params.map((x, i) => `[${i}] ${x}`).join('\n');
-            let err = new Error(`Read ${this.ctx?.name ?? ''} ${address}.${method}(${args}) failed with ${error.message}`);
+
+            let { client } = this;
+            let { tx: txData } = await RpcContract.createCalldata({
+                address,
+                abi: abiArr,
+                method: method,
+                params: params,
+                blockNumber: blockNumber,
+                from: this.options.from,
+            });
+            let traces = await client.debug.traceCall(txData);
+            let output = await $traces.format({
+                tx: txData,
+                traces,
+                color: this.ctx?.color ?? false,
+                shortAddress: false,
+                async getABI(address) {
+                    return $abiProvider.getAbi(address, client.network);
+                }
+            });
+            let tracesF = `\nTraces: \n` + output;
+
+            let err = new Error(`Read ${this.ctx?.name ?? ''} ${address}.${method}(${args}) failed with ${error.message}\n${tracesF}`);
             err.stack = error.stack;
             throw err;
         }

package/src/contracts/ContractWriter.ts

@@ -131,7 +131,7 @@ export class ContractWriter implements IContractWriter {
         let silentTxWriter = writerConfig?.silent ?? ContractWriter.SILENT;
         if (silentTxWriter === false) {
             writer.on('log', message => {
-                $logger.log(`TxContract ${abi.name}; ${message}`);
+                $logger.log(`${abi.name}; ${message}`);
             });
         }
         return writer;

package/src/hardhat/HardhatProvider.ts

@@ -419,6 +419,15 @@ export class HardhatProvider {
     }
 
     private async createTmpFile(solidityCode: string, options: Parameters<HardhatProvider['deploySol']>[1] = {}) {
+
+        // Ensure the code includes the necessary pragmas and license header.
+        if (solidityCode.includes('pragma solidity') === false) {
+            solidityCode = `pragma solidity ^0.8.0;\n${solidityCode}`;
+        }
+        if (solidityCode.includes('SPDX-License-Identifier') === false) {
+            solidityCode = `// SPDX-License-Identifier: MIT\n${solidityCode}`;
+        }
+
         let contractName = options.contractName;
         if (contractName == null) {
             let matches = Array.from(solidityCode.matchAll(/contract\s+(?<name>[\w]+)/g));