@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/core/helpers/core.js

@@ -0,0 +1,368 @@
+"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;
+exports.toRawBigInt = toRawBigInt;
+const web3_1 = require("../constants/web3");
+const ethers_1 = require("ethers");
+const errors_1 = require("../errors");
+/**
+ * Table of Contents
+ * - Formatters
+ * - Datetime
+ * - Arrays
+ * - Caching
+ */
+/**
+ * Normalize an amount into both its human-readable and raw (integer) forms.
+ *
+ * @param value - Amount as a decimal string (`"1.5"`), a JS number, or a raw
+ *   `bigint` already scaled by `decimals`. Strings/numbers are treated as
+ *   human-readable values and scaled UP; bigints are treated as raw values
+ *   and scaled DOWN. Exponential notation (`1e-7`, `1e21`) is accepted for
+ *   strings and numbers.
+ * @param decimals - Token decimals used for scaling. Default `18`.
+ * @returns `{ normalized, raw }` where `normalized` is the decimal string
+ *   (fraction trimmed to `decimals` places) and `raw` is the integer string.
+ *   Falsy input yields `{ normalized: '0', raw: '0' }`.
+ * @throws Whatever ethers' `parseUnits` throws for a string that is not a
+ *   decimal number (e.g. `"abc"`).
+ */
+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);
+            // `Number#toFixed` itself falls back to exponential notation for
+            // magnitudes >= 1e21 ("1e+21"), which `parseUnits` rejects. Every IEEE
+            // double of that size is an integer (well past 2^53), so `BigInt` yields
+            // the exact plain-digit string. The digits are those of the IEEE double,
+            // not of the literal input (`"1.5e21"` is parsed to the nearest double
+            // before this point), so precision beyond ~15-17 significant digits was
+            // already lost at `parseFloat`/`Number`.
+            if (Number.isFinite(num) && Math.abs(num) >= 1e21) {
+                return BigInt(num).toString();
+            }
+            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': {
+            // Expand camelCase by inserting a space before each uppercase letter,
+            // then title-case the resulting words. The split must operate on the
+            // EXPANDED string (not the original) and skip empty tokens: a leading
+            // uppercase letter produces a leading space, and the previous version
+            // indexed the original's word list by the expanded string's length,
+            // which threw on any multi-character input.
+            const expanded = Array.from(str)
+                .map((letter) => {
+                // letter is uppercase
+                if (letter === letter.toUpperCase()) {
+                    return ` ${letter}`;
+                }
+                // else
+                return letter;
+            })
+                .join('');
+            return expanded
+                .split(' ')
+                .filter((w) => w.length > 0)
+                .map((w) => w[0].toUpperCase() + w.slice(1).toLowerCase())
+                .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);
+    // A zero (or NaN) total would make every weight NaN; report zero weights
+    // instead so downstream weighted averages collapse to 0 rather than NaN.
+    if (!total) {
+        return data.map((item) => ({ ...item, weight: 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;
+}
+/**
+ * Coerce a caller-supplied integer (`string | bigint | number`) to a `bigint`,
+ * rejecting anything that is not a non-negative safe integer. `label` names the
+ * calling method and `noun` the field being validated, so bad input surfaces as
+ * `UpshiftValidationError('INVALID_INPUT')` at the SDK boundary instead of a
+ * `BigInt()` SyntaxError wrapped as `UNKNOWN`.
+ * @internal
+ */
+function toRawBigInt(value, label, noun = 'amount') {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${label}: ${noun} must be finite, got ${value}`);
+        }
+        if (value < 0) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${label}: ${noun} must be non-negative, got ${value}`);
+        }
+        if (!Number.isInteger(value)) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${label}: ${noun} must be an integer, got ${value}`);
+        }
+        if (!Number.isSafeInteger(value)) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${label}: ${noun} ${value} exceeds Number.MAX_SAFE_INTEGER; pass a string or bigint to preserve precision`);
+        }
+        return BigInt(value);
+    }
+    if (typeof value === 'string') {
+        if (value.trim() === '') {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${label}: ${noun} string must not be empty`);
+        }
+        try {
+            const parsed = BigInt(value);
+            if (parsed < 0n) {
+                throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${label}: ${noun} must be non-negative, got ${value}`);
+            }
+            return parsed;
+        }
+        catch (e) {
+            if (e instanceof errors_1.UpshiftValidationError)
+                throw e;
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${label}: ${noun} "${value}" is not a valid integer`);
+        }
+    }
+    throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${label}: ${noun} must be a string, bigint, or number`);
+}
+//# 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 UpshiftValidationError 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[]>;

package/lib/core/helpers/multicall.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTICALL3_BATCH_SIZE = void 0;
+exports.isMulticall3Supported = isMulticall3Supported;
+exports.multicall3Aggregate = multicall3Aggregate;
+const ethers_1 = require("ethers");
+const Multicall3_1 = require("../../abis/Multicall3");
+const web3_1 = require("../constants/web3");
+const errors_1 = require("../errors");
+const logger_1 = require("../logger");
+/**
+ * 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
+ */
+exports.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
+ */
+function isMulticall3Supported(chainId) {
+    return typeof chainId === 'number' && web3_1.MULTICALL3_VERIFIED_CHAINS.has(chainId);
+}
+/**
+ * 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 UpshiftValidationError when `chainId` is not on the verified
+ *   allowlist — programming error, not a runtime condition to swallow.
+ * @internal
+ */
+async function multicall3Aggregate(provider, chainId, calls, batchSize = exports.MULTICALL3_BATCH_SIZE) {
+    if (!isMulticall3Supported(chainId)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `multicall3Aggregate: Multicall3 deployment is not verified on chain ${chainId} — use the per-call read path instead`);
+    }
+    if (calls.length === 0)
+        return [];
+    const encoded = calls.map((c) => {
+        const iface = new ethers_1.Interface(c.abi);
+        return {
+            target: c.target,
+            allowFailure: true,
+            callData: iface.encodeFunctionData(c.functionName, c.args ?? []),
+            iface,
+            functionName: c.functionName,
+        };
+    });
+    const chunks = [];
+    for (let i = 0; i < encoded.length; i += batchSize) {
+        chunks.push(encoded.slice(i, i + batchSize));
+    }
+    const multicall = new ethers_1.Contract(web3_1.MULTICALL3_ADDRESS, Multicall3_1.ABI_MULTICALL3, provider);
+    const chunkResults = await Promise.all(chunks.map(async (chunk) => {
+        try {
+            const returned = (await multicall.aggregate3(chunk.map((c) => ({
+                target: c.target,
+                allowFailure: c.allowFailure,
+                callData: c.callData,
+            }))));
+            return chunk.map((c, i) => {
+                const r = returned[i];
+                if (!r?.success || !r.returnData || r.returnData === '0x') {
+                    return { success: false, value: undefined };
+                }
+                try {
+                    const decoded = c.iface.decodeFunctionResult(c.functionName, r.returnData);
+                    return { success: true, value: decoded[0] };
+                }
+                catch (decodeError) {
+                    logger_1.Logger.log.warn('multicall3Aggregate', `failed to decode ${c.functionName} result for ${c.target}`, decodeError);
+                    return { success: false, value: undefined };
+                }
+            });
+        }
+        catch (chunkError) {
+            logger_1.Logger.log.warn('multicall3Aggregate', `aggregate3 chunk failed on chain ${chainId} (${chunk.length} calls) — callers fall back to per-call reads`, chunkError);
+            return chunk.map(() => ({ success: false, value: undefined }));
+        }
+    }));
+    return chunkResults.flat();
+}
+//# sourceMappingURL=multicall.js.map