upshift-finance 1.0.0

package/lib/core/helpers/chain-support.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Chain-ID validation for public SDK entry points.
+ *
+ * Two distinct failure modes are covered here, and they are deliberately kept
+ * separate because they have different remediations:
+ *
+ * 1. **Unknown chain ID** — the caller passed an ID the SDK has no concept of
+ *    (a typo, a stale constant, an off-by-one on a non-EVM synthetic ID). No
+ *    configuration can make this work; the call site is wrong.
+ * 2. **Known EVM chain, no RPC configured** — the ID is valid but the SDK was
+ *    constructed without a provider for it. Remediated by passing an RPC URL.
+ *
+ * Both used to be logged-and-ignored, letting execution continue with an
+ * `undefined` RPC URL. That produced a cascade of misleading downstream
+ * failures (`connect ECONNREFUSED 127.0.0.1:8545` from ethers' localhost
+ * default, `missing revert data` from `decimals()` reads issued against the
+ * wrong chain, and `TypeError: Cannot read properties of undefined`). Failing
+ * fast at the boundary replaces that cascade with one actionable error.
+ *
+ * @module core/helpers/chain-support
+ */
+/**
+ * Whether `chainId` is an EVM chain the SDK knows about (i.e. has an entry in
+ * {@link NETWORKS}).
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` for supported EVM chains, `false` for non-EVM synthetic IDs
+ *   (Solana, Stellar, Sui) and for anything unrecognised.
+ */
+export declare function isEvmChainId(chainId: number): boolean;
+/**
+ * Whether `chainId` is recognised by the SDK at all — either a supported EVM
+ * chain or one of the non-EVM chain IDs in {@link NON_EVM_CHAIN_IDS}.
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` when the ID maps to a chain the SDK can route to.
+ */
+export declare function isKnownChainId(chainId: number): boolean;
+/**
+ * Throw when `chainId` is not a chain the SDK recognises.
+ *
+ * Called at public vault entry points so an unroutable ID surfaces as one
+ * typed error instead of an opaque downstream RPC failure.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op —
+ *   omitting the chain is valid and falls back to the SDK's active network.
+ * @param providers - The SDK's configured `chainId → RPC URL` map. A chain
+ *   with a caller-configured provider is routable even if it is missing from
+ *   {@link NETWORKS} (the SDK ships fallback RPCs/oracles for some EVM chains
+ *   ahead of adding them to `NETWORKS`), so it is accepted here too.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link AugustValidationError} with code `INVALID_CHAIN` when the ID
+ *   is not in {@link NETWORKS} or {@link NON_EVM_CHAIN_IDS}, and has no
+ *   caller-configured provider.
+ * @example
+ * ```ts
+ * assertKnownChainId(-2, undefined, 'getVault');
+ * // AugustValidationError: getVault: unknown chainId -2.
+ * ```
+ */
+export declare function assertKnownChainId(chainId: number | undefined, providers: Partial<Record<number, string>> | undefined, method: string): void;
+/**
+ * Throw when a known EVM `chainId` has no RPC URL configured on the SDK.
+ *
+ * Non-EVM chain IDs are exempt: Solana, Stellar and Sui vaults route through
+ * their adapters and never read from the `providers` map, so a missing entry
+ * is expected rather than a misconfiguration.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op.
+ * @param providers - The SDK's configured `chainId → RPC URL` map.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link AugustValidationError} with code `INVALID_CHAIN` when
+ *   `chainId` is an EVM chain with no configured provider.
+ * @example
+ * ```ts
+ * assertEvmProviderConfigured(143, {}, 'getVault');
+ * // AugustValidationError: getVault: no RPC URL configured for chainId 143 (Monad).
+ * ```
+ */
+export declare function assertEvmProviderConfigured(chainId: number | undefined, providers: Partial<Record<number, string>> | undefined, method: string): void;

package/lib/core/helpers/chain-support.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Chain-ID validation for public SDK entry points.
+ *
+ * Two distinct failure modes are covered here, and they are deliberately kept
+ * separate because they have different remediations:
+ *
+ * 1. **Unknown chain ID** — the caller passed an ID the SDK has no concept of
+ *    (a typo, a stale constant, an off-by-one on a non-EVM synthetic ID). No
+ *    configuration can make this work; the call site is wrong.
+ * 2. **Known EVM chain, no RPC configured** — the ID is valid but the SDK was
+ *    constructed without a provider for it. Remediated by passing an RPC URL.
+ *
+ * Both used to be logged-and-ignored, letting execution continue with an
+ * `undefined` RPC URL. That produced a cascade of misleading downstream
+ * failures (`connect ECONNREFUSED 127.0.0.1:8545` from ethers' localhost
+ * default, `missing revert data` from `decimals()` reads issued against the
+ * wrong chain, and `TypeError: Cannot read properties of undefined`). Failing
+ * fast at the boundary replaces that cascade with one actionable error.
+ *
+ * @module core/helpers/chain-support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEvmChainId = isEvmChainId;
+exports.isKnownChainId = isKnownChainId;
+exports.assertKnownChainId = assertKnownChainId;
+exports.assertEvmProviderConfigured = assertEvmProviderConfigured;
+const web3_1 = require("../constants/web3");
+const errors_1 = require("../errors");
+/**
+ * Whether `chainId` is an EVM chain the SDK knows about (i.e. has an entry in
+ * {@link NETWORKS}).
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` for supported EVM chains, `false` for non-EVM synthetic IDs
+ *   (Solana, Stellar, Sui) and for anything unrecognised.
+ */
+function isEvmChainId(chainId) {
+    return Object.hasOwn(web3_1.NETWORKS, chainId);
+}
+/**
+ * Whether `chainId` is recognised by the SDK at all — either a supported EVM
+ * chain or one of the non-EVM chain IDs in {@link NON_EVM_CHAIN_IDS}.
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` when the ID maps to a chain the SDK can route to.
+ */
+function isKnownChainId(chainId) {
+    return isEvmChainId(chainId) || web3_1.NON_EVM_CHAIN_IDS.has(chainId);
+}
+/**
+ * Throw when `chainId` is not a chain the SDK recognises.
+ *
+ * Called at public vault entry points so an unroutable ID surfaces as one
+ * typed error instead of an opaque downstream RPC failure.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op —
+ *   omitting the chain is valid and falls back to the SDK's active network.
+ * @param providers - The SDK's configured `chainId → RPC URL` map. A chain
+ *   with a caller-configured provider is routable even if it is missing from
+ *   {@link NETWORKS} (the SDK ships fallback RPCs/oracles for some EVM chains
+ *   ahead of adding them to `NETWORKS`), so it is accepted here too.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link AugustValidationError} with code `INVALID_CHAIN` when the ID
+ *   is not in {@link NETWORKS} or {@link NON_EVM_CHAIN_IDS}, and has no
+ *   caller-configured provider.
+ * @example
+ * ```ts
+ * assertKnownChainId(-2, undefined, 'getVault');
+ * // AugustValidationError: getVault: unknown chainId -2.
+ * ```
+ */
+function assertKnownChainId(chainId, providers, method) {
+    if (typeof chainId === 'undefined')
+        return;
+    if (isKnownChainId(chainId))
+        return;
+    if (providers?.[chainId])
+        return;
+    throw new errors_1.AugustValidationError('INVALID_CHAIN', `${method}: unknown chainId ${chainId}. ` +
+        'Pass a supported EVM chain ID (see NETWORKS) or a non-EVM chain ID ' +
+        '(-1 Solana, -3 Stellar, 101 Sui).', { context: { method, chainId } });
+}
+/**
+ * Throw when a known EVM `chainId` has no RPC URL configured on the SDK.
+ *
+ * Non-EVM chain IDs are exempt: Solana, Stellar and Sui vaults route through
+ * their adapters and never read from the `providers` map, so a missing entry
+ * is expected rather than a misconfiguration.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op.
+ * @param providers - The SDK's configured `chainId → RPC URL` map.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link AugustValidationError} with code `INVALID_CHAIN` when
+ *   `chainId` is an EVM chain with no configured provider.
+ * @example
+ * ```ts
+ * assertEvmProviderConfigured(143, {}, 'getVault');
+ * // AugustValidationError: getVault: no RPC URL configured for chainId 143 (Monad).
+ * ```
+ */
+function assertEvmProviderConfigured(chainId, providers, method) {
+    if (typeof chainId === 'undefined')
+        return;
+    if (!isEvmChainId(chainId))
+        return;
+    if (providers?.[chainId])
+        return;
+    const name = web3_1.NETWORKS[chainId]?.name;
+    throw new errors_1.AugustValidationError('INVALID_CHAIN', `${method}: no RPC URL configured for chainId ${chainId}` +
+        `${name ? ` (${name})` : ''}. ` +
+        'Pass one when constructing AugustSDK: ' +
+        `new AugustSDK({ providers: { ${chainId}: '<rpc-url>' } }).`, { context: { method, chainId } });
+}
+//# sourceMappingURL=chain-support.js.map

package/lib/core/helpers/core.d.ts

@@ -0,0 +1,68 @@
+import type { INormalizedNumber } from '../../types';
+/**
+ * Table of Contents
+ * - Formatters
+ * - Datetime
+ * - Arrays
+ * - Caching
+ */
+export declare function toNormalizedBn(value: string | bigint | number, decimals?: number | bigint): INormalizedNumber;
+/**
+ * Get fallback RPC URLs for a specific chain
+ */
+export declare function getFallbackRpcUrls(chainId: number): string[];
+export declare const filterOutBySize: (usdAmount: number) => boolean;
+/**
+ * Formatters
+ */
+export declare function toTitleCase(str: string, type?: 'camel'): string;
+export declare function truncate(s: string, amount?: number): string;
+/**
+ * Formats any numeric value (number, string, or bigint) to a standardized string.
+ *
+ * @param value - amount to be formatted
+ * @param options - formatting options:
+ *   `showing` is the number of decimals to cut off at (or `'all'`);
+ *   `usd` toggles USD-value display;
+ *   `decimals` is how many decimals to parse to when `value` is a bigint.
+ *
+ * @returns standardized string type value
+ */
+export declare function round(value: number | string | bigint, options?: {
+    showing?: number | 'all';
+    usd?: boolean;
+    decimals?: number;
+}): string;
+export declare function loanStateToReadable(loanState: number | bigint): "PREAPPROVED" | "FUNDING_REQUIRED" | "FUNDED" | "ACTIVE" | "CANCELLED" | "MATURED" | "CLOSED";
+/**
+ * Datetime
+ */
+export declare function dateToUnix(date: Date): number;
+export declare function unixToDate(epoch: number): Date;
+export declare function isEarlierThanNow(startTime: Date): boolean;
+export declare function daysAgo(days: number): Date;
+export declare function prepareDateForDb(date: string | Date): string;
+/**
+ * Arrays
+ */
+export declare function orderObjArrByDate<T extends Record<string, unknown>>(objectArray: T[], options?: {
+    key?: string;
+    order?: 'asc' | 'desc';
+}): T[];
+/**
+ * Calculate weights based on a specific property in array of objects.
+ * @param data - Array of objects to calculate weights for
+ * @param weightProperty - Property name to base weights on
+ * @returns Original data with each item's `weight` added
+ */
+export declare function calculateWeights<T extends Record<string, unknown>>(data?: T[], weightProperty?: string): Array<T & {
+    weight: number;
+}>;
+/**
+ * Calculate weighted average for array of objects.
+ * @param data - Array of objects with values
+ * @param valueProperty - Property name containing the value to average
+ * @param weightProperty - Optional property to base weights on
+ * @returns Weighted average
+ */
+export declare function calculateWeightedAverage<T extends Record<string, unknown>>(data?: T[], valueProperty?: string, weightProperty?: string): number;

package/lib/core/helpers/core.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterOutBySize = void 0;
+exports.toNormalizedBn = toNormalizedBn;
+exports.getFallbackRpcUrls = getFallbackRpcUrls;
+exports.toTitleCase = toTitleCase;
+exports.truncate = truncate;
+exports.round = round;
+exports.loanStateToReadable = loanStateToReadable;
+exports.dateToUnix = dateToUnix;
+exports.unixToDate = unixToDate;
+exports.isEarlierThanNow = isEarlierThanNow;
+exports.daysAgo = daysAgo;
+exports.prepareDateForDb = prepareDateForDb;
+exports.orderObjArrByDate = orderObjArrByDate;
+exports.calculateWeights = calculateWeights;
+exports.calculateWeightedAverage = calculateWeightedAverage;
+const web3_1 = require("../constants/web3");
+const ethers_1 = require("ethers");
+/**
+ * Table of Contents
+ * - Formatters
+ * - Datetime
+ * - Arrays
+ * - Caching
+ */
+function toNormalizedBn(value, decimals = 18) {
+    if (!value)
+        return { normalized: '0', raw: BigInt(0).toString() };
+    const sanitize = (val, decimals) => {
+        const [whole, frac = ''] = val.split('.');
+        const trimmedFrac = frac.slice(0, decimals); // trim to allowed precision
+        return trimmedFrac ? `${whole}.${trimmedFrac}` : whole;
+    };
+    // Convert number or exponential string to fixed decimal string
+    const toFixedDecimalString = (val) => {
+        const strRep = typeof val === 'number' ? String(val) : val;
+        // Check if the string representation contains exponential notation
+        if (strRep.includes('e') || strRep.includes('E')) {
+            // Parse as number and use toFixed with high precision to convert exponential to fixed decimal
+            // 100 decimals should handle even extremely small numbers like 1e-20
+            const num = typeof val === 'number' ? val : parseFloat(strRep);
+            return num.toFixed(100).replace(/\.?0+$/, '');
+        }
+        // For regular numbers/strings, return as is
+        return strRep;
+    };
+    if (typeof value === 'string' || typeof value === 'number') {
+        // Convert to fixed decimal string to avoid exponential notation
+        const strVal = toFixedDecimalString(value);
+        const safeVal = sanitize(strVal, Number(decimals));
+        return {
+            normalized: safeVal,
+            raw: (0, ethers_1.parseUnits)(safeVal, Number(decimals)).toString(),
+        };
+    }
+    else {
+        return {
+            normalized: (0, ethers_1.formatUnits)(value, Number(decimals)) ?? '0',
+            raw: value.toString(),
+        };
+    }
+}
+/**
+ * Get fallback RPC URLs for a specific chain
+ */
+function getFallbackRpcUrls(chainId) {
+    return web3_1.FALLBACK_RPC_URLS[chainId] || [];
+}
+const filterOutBySize = (usdAmount) => usdAmount > 3_000;
+exports.filterOutBySize = filterOutBySize;
+/**
+ * Formatters
+ */
+function toTitleCase(str, type) {
+    if (!str)
+        return;
+    switch (type) {
+        case 'camel': {
+            const words = Array.from(str)
+                .map((letter) => {
+                // letter is uppercase
+                if (letter === letter.toUpperCase()) {
+                    return ` ${letter}`;
+                }
+                // else
+                return letter;
+            })
+                .join('');
+            const _words = str.split(' ')?.map((w) => w.toLowerCase());
+            for (let i = 0; i < words.length; i++) {
+                _words[i] = _words[i][0].toUpperCase() + _words[i].substr(1);
+            }
+            return _words.join(' ');
+        }
+        default: {
+            const words = str.split(' ')?.map((w) => w.toLowerCase());
+            for (let i = 0; i < words.length; i++) {
+                words[i] = words[i][0].toUpperCase() + words[i].substr(1);
+            }
+            return words.join(' ');
+        }
+    }
+}
+function truncate(s, amount) {
+    if (typeof s !== 'string') {
+        // Leaf string util: importing Logger here would create an import cycle
+        // (helpers/core → logger/index → slack → helpers/core) that the madge CI
+        // check forbids (CLAUDE.md §9). Keep a direct console.error for this
+        // defensive type-guard diagnostic.
+        // biome-ignore lint/suspicious/noConsole: leaf util cannot import Logger without a cycle (CLAUDE.md §9); keep a direct console.error for this defensive type-guard diagnostic.
+        if (s !== undefined)
+            console.error('#truncate: not a string', s);
+        return '';
+    }
+    if (!s)
+        return s;
+    if (s === 'N/A')
+        return s;
+    return `${s.slice(0, amount ? amount : 4)}...${s.slice(amount ? amount * -1 : -4)}`;
+}
+/**
+ * Formats any numeric value (number, string, or bigint) to a standardized string.
+ *
+ * @param value - amount to be formatted
+ * @param options - formatting options:
+ *   `showing` is the number of decimals to cut off at (or `'all'`);
+ *   `usd` toggles USD-value display;
+ *   `decimals` is how many decimals to parse to when `value` is a bigint.
+ *
+ * @returns standardized string type value
+ */
+function round(value, options) {
+    // standardize to string
+    let _value;
+    if (typeof value === 'bigint') {
+        _value = toNormalizedBn(value, options?.decimals ?? web3_1.FALLBACK_DECIMALS).normalized;
+    }
+    else {
+        _value = String(value);
+        // if string passed includes something like a symbol (i.e. 0.1 ETH --> 0.1)
+        if (_value.includes(' '))
+            _value = _value.split(' ')[0];
+    }
+    // if wanting USD value
+    if (options?.usd) {
+        const usdFormatter = new Intl.NumberFormat('en-US', {
+            style: 'currency',
+            currency: 'USD',
+        });
+        const valueNumber = Number(_value);
+        return usdFormatter.format(valueNumber) !== 'NaN'
+            ? usdFormatter.format(valueNumber)
+            : '0';
+    }
+    // else slice if decimal places is more than 6 and display
+    if (_value === '0' || _value === '0.0')
+        return '0.000';
+    if (options?.showing === 'all') {
+        return _value;
+    }
+    else {
+        const _showing = () => {
+            if (options?.showing && typeof options.showing === 'number')
+                return options?.showing;
+            if (options?.usd)
+                return 2;
+            if (_value?.includes('.') && _value.split('.')[0].length > 2)
+                return 3;
+            if (_value?.length && _value?.length > 6)
+                return 6;
+            return 4;
+        };
+        const numberFormatter = new Intl.NumberFormat('en-US', {
+            minimumFractionDigits: _showing(),
+            maximumFractionDigits: _showing(),
+        });
+        return numberFormatter.format(Number(_value)) !== 'NaN'
+            ? numberFormatter.format(Number(_value))
+            : '0';
+    }
+}
+function loanStateToReadable(loanState) {
+    switch (Number(loanState)) {
+        case 1:
+            return 'PREAPPROVED';
+        case 2:
+            return 'FUNDING_REQUIRED';
+        case 3:
+            return 'FUNDED';
+        case 4:
+            return 'ACTIVE';
+        case 5:
+            return 'CANCELLED';
+        case 6:
+            return 'MATURED';
+        case 7:
+            return 'CLOSED';
+    }
+}
+/**
+ * Datetime
+ */
+function dateToUnix(date) {
+    if (!date)
+        return Math.floor(Date.now());
+    return Math.floor(new Date(date).getTime());
+}
+function unixToDate(epoch) {
+    if (!epoch)
+        return new Date();
+    return new Date(new Date(epoch).getTime());
+}
+function isEarlierThanNow(startTime) {
+    if (!startTime)
+        return true;
+    if (startTime <= new Date())
+        return true;
+    return false;
+}
+function daysAgo(days) {
+    const today = new Date();
+    return new Date(new Date().setDate(today.getDate() - days));
+}
+function prepareDateForDb(date) {
+    return new Date(date).toISOString();
+}
+/**
+ * Arrays
+ */
+function orderObjArrByDate(objectArray, options) {
+    const selectedOrder = options?.order ?? 'desc';
+    const selectedKey = options?.key ?? 'date';
+    const toTime = (item) => new Date(item[selectedKey]).valueOf();
+    return objectArray.sort((a, b) => {
+        // Turn your strings into dates, and then subtract them
+        // to get a value that is either negative, positive, or zero.
+        if (selectedOrder === 'asc')
+            return toTime(a) - toTime(b);
+        return toTime(b) - toTime(a);
+    });
+}
+/**
+ * Calculate weights based on a specific property in array of objects.
+ * @param data - Array of objects to calculate weights for
+ * @param weightProperty - Property name to base weights on
+ * @returns Original data with each item's `weight` added
+ */
+function calculateWeights(data, weightProperty) {
+    if (!data || data.length === 0 || !weightProperty)
+        return [];
+    // Get total of the property we're using for weight calculation
+    const total = data.reduce((sum, item) => sum + item[weightProperty], 0);
+    // Add weight property to each item
+    return data.map((item) => ({
+        ...item,
+        weight: item[weightProperty] / total,
+    }));
+}
+/**
+ * Calculate weighted average for array of objects.
+ * @param data - Array of objects with values
+ * @param valueProperty - Property name containing the value to average
+ * @param weightProperty - Optional property to base weights on
+ * @returns Weighted average
+ */
+function calculateWeightedAverage(data, valueProperty, weightProperty) {
+    if (!data || data.length === 0 || !valueProperty)
+        return 0;
+    let weightedData;
+    // If no weightProperty specified, use equal weights
+    if (!weightProperty) {
+        weightedData = data.map((item) => ({
+            ...item,
+            weight: 1 / data.length,
+        }));
+    }
+    else {
+        weightedData = calculateWeights(data, weightProperty);
+    }
+    // Calculate weighted average
+    const weightedAverage = weightedData.reduce((acc, item) => acc + item[valueProperty] * item.weight, 0);
+    return weightedAverage;
+}
+//# sourceMappingURL=core.js.map

package/lib/core/helpers/explorer-link.d.ts

@@ -0,0 +1,16 @@
+import type { IAddress, IChainId, IExplorerType } from '../../types';
+/**
+ * Generate a block-explorer URL for an address or transaction hash.
+ *
+ * Returns an empty string when `chain` is falsy or unknown so the return
+ * type stays assignable to `string` — preserves the historical public
+ * shape from before the file split out of `web3.ts`, where the SDK's
+ * `strictNullChecks: false` masked the implicit `undefined` branch and
+ * consumers pinned to `string` via the emitted `.d.ts`.
+ *
+ * @param hex Address or transaction hash
+ * @param chain Chain ID
+ * @param type Explorer view type (`address`, `tx`, `block`)
+ * @returns Full explorer URL, or `''` when `chain` is falsy / unknown.
+ */
+export declare const explorerLink: (hex: IAddress, chain: IChainId, type: IExplorerType) => string;

package/lib/core/helpers/explorer-link.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explorerLink = void 0;
+const web3_1 = require("../constants/web3");
+/**
+ * Generate a block-explorer URL for an address or transaction hash.
+ *
+ * Returns an empty string when `chain` is falsy or unknown so the return
+ * type stays assignable to `string` — preserves the historical public
+ * shape from before the file split out of `web3.ts`, where the SDK's
+ * `strictNullChecks: false` masked the implicit `undefined` branch and
+ * consumers pinned to `string` via the emitted `.d.ts`.
+ *
+ * @param hex Address or transaction hash
+ * @param chain Chain ID
+ * @param type Explorer view type (`address`, `tx`, `block`)
+ * @returns Full explorer URL, or `''` when `chain` is falsy / unknown.
+ */
+const explorerLink = (hex, chain, type) => {
+    const network = chain ? web3_1.NETWORKS[chain] : undefined;
+    if (!network)
+        return '';
+    return `${network.explorer}/${type}/${hex}`;
+};
+exports.explorerLink = explorerLink;
+//# sourceMappingURL=explorer-link.js.map

package/lib/core/helpers/multicall.d.ts

@@ -0,0 +1,68 @@
+import { type InterfaceAbi } from 'ethers';
+import type { IAddress, IContractRunner } from '../../types';
+/**
+ * One read to fold into a Multicall3 `aggregate3` batch.
+ * @internal
+ */
+export interface IMulticall3Request {
+    /** Contract to call. */
+    target: IAddress;
+    /** ABI containing `functionName` (full or minimal fragment). */
+    abi: InterfaceAbi;
+    /** View function to encode. */
+    functionName: string;
+    /** Positional arguments for the function. */
+    args?: unknown[];
+}
+/**
+ * Per-call result of an `aggregate3` batch. `success: false` means that one
+ * call reverted (or its chunk failed at the transport level) — it never
+ * implies anything about the other calls in the batch.
+ * @internal
+ */
+export interface IMulticall3Result {
+    success: boolean;
+    /** First decoded return value; `undefined` when `success` is `false`. */
+    value?: unknown;
+}
+/**
+ * Calls per `aggregate3` chunk. Mirrors the `batchMaxCount: 10` cap on
+ * `createProvider` — some RPC providers (e.g. rpc.hypurrscan.io) enforce
+ * their own batch/response-size limits, so an unbounded batch for a wallet
+ * with many vaults risks exceeding response-size or `eth_call` gas ceilings.
+ * @internal
+ */
+export declare const MULTICALL3_BATCH_SIZE = 10;
+/**
+ * Whether Multicall3 read-aggregation is enabled for a chain. Only chains in
+ * {@link MULTICALL3_VERIFIED_CHAINS} (deployment verified via `eth_getCode`,
+ * never assumed) qualify — callers must fall back to individual reads for
+ * every other chain.
+ * @internal
+ */
+export declare function isMulticall3Supported(chainId: number | undefined): boolean;
+/**
+ * Aggregate independent view calls into chunked Multicall3 `aggregate3`
+ * batches (`allowFailure: true` per call).
+ *
+ * Failure semantics — the load-bearing detail:
+ * - A reverting inner call (paused/deprecated vault) yields `success: false`
+ *   for that call only; every other call in the batch decodes normally.
+ * - A transport-level failure of one chunk degrades that chunk's calls to
+ *   `success: false` instead of throwing, so a caller can always fall back
+ *   to its per-call path. This function never rejects for RPC reasons.
+ *
+ * RPC cost: `ceil(calls.length / batchSize)` `eth_call`s, versus
+ * `calls.length` without aggregation.
+ *
+ * @param provider Provider for the target chain.
+ * @param chainId Chain the provider is connected to — must be in the
+ *   verified allowlist; gate with {@link isMulticall3Supported} first.
+ * @param calls Reads to aggregate, in order.
+ * @param batchSize Max calls per `aggregate3` chunk.
+ * @returns One {@link IMulticall3Result} per request, index-aligned.
+ * @throws AugustValidationError when `chainId` is not on the verified
+ *   allowlist — programming error, not a runtime condition to swallow.
+ * @internal
+ */
+export declare function multicall3Aggregate(provider: IContractRunner, chainId: number, calls: IMulticall3Request[], batchSize?: number): Promise<IMulticall3Result[]>;