upshift-finance 1.0.0

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 AugustValidationError 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.AugustValidationError('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

package/lib/core/helpers/revert-decode.d.ts

@@ -0,0 +1,248 @@
+import { type InterfaceAbi, type JsonRpcProvider } from 'ethers';
+/** The revert shapes {@link decodeRevertData} distinguishes. */
+export type IRevertKind = 'error-string' | 'panic' | 'custom' | 'unknown';
+/** Result of decoding a raw revert blob with {@link decodeRevertData}. */
+export interface IDecodedRevert {
+    /**
+     * `'error-string'` for `Error(string)` (a `require` message), `'panic'` for
+     * compiler-inserted `Panic(uint256)`, `'custom'` when the selector matched a
+     * corpus (or caller-supplied) custom error, `'unknown'` when nothing matched.
+     */
+    kind: IRevertKind;
+    /** The 4-byte selector (`0x` + 8 hex chars), always present — even for `'unknown'` so callers can 4byte-lookup it. */
+    selector: string;
+    /** Error name (e.g. `'ERC20InsufficientBalance'`, `'Error'`, `'Panic'`). Absent for `'unknown'`. */
+    name?: string;
+    /** Full error signature (e.g. `'ERC20InsufficientBalance(address,uint256,uint256)'`). Absent for `'unknown'`. */
+    signature?: string;
+    /**
+     * Decoded arguments in declaration order (`bigint` for integers, checksummed
+     * strings for addresses). Absent when the selector matched but the argument
+     * bytes were truncated or malformed — see {@link IDecodedRevert.reason}.
+     */
+    args?: unknown[];
+    /**
+     * Human-readable summary when one exists: the `Error(string)` message, the
+     * named `Panic` code, or a note that the argument data was truncated.
+     */
+    reason?: string;
+}
+/**
+ * Decode a raw EVM revert blob into a named error with arguments.
+ *
+ * Pure and offline — no RPC calls, no network. Handles the three revert
+ * shapes the EVM produces:
+ *
+ * 1. `Error(string)` (`0x08c379a0`) — a `require`/`revert` with a message.
+ * 2. `Panic(uint256)` (`0x4e487b71`) — compiler-inserted checks, with the
+ *    numeric code translated to its documented meaning (overflow, division by
+ *    zero, …).
+ * 3. Custom errors — matched against a built-in corpus of OpenZeppelin
+ *    ERC-6093 / SafeERC20 / ERC4626 / Ownable / Pausable errors, LayerZero V2
+ *    OApp/OFT errors, and every `error` fragment in the vault ABIs the SDK
+ *    ships (tokenized vaults, SwapRouter, lending pools, …). Callers can
+ *    extend the corpus per call via `opts.extraAbis`, which take precedence.
+ *
+ * Truncated input degrades gracefully: when the 4-byte selector matches a
+ * known error but the argument bytes are incomplete (e.g. an alert pipeline
+ * clipped the hex), the result still carries `kind: 'custom'`, `name`, and
+ * `signature`, with `args` omitted and `reason` explaining the truncation.
+ *
+ * @param data - The revert blob as a `0x`-prefixed hex string (the `data`
+ *   field of an ethers v6 `CALL_EXCEPTION`). Anything shorter than a 4-byte
+ *   selector, or not hex at all, yields `kind: 'unknown'`.
+ * @param opts - Optional settings.
+ * @param opts.extraAbis - Additional ABIs whose `error` fragments are checked
+ *   before the built-in corpus.
+ * @returns The decoded revert. Never throws; unrecognized selectors return
+ *   `kind: 'unknown'` with the selector preserved so callers can look it up
+ *   via {@link lookupSelector}.
+ *
+ * @example
+ * ```ts
+ * const decoded = decodeRevertData('0xe450d38c…');
+ * // {
+ * //   kind: 'custom',
+ * //   selector: '0xe450d38c',
+ * //   name: 'ERC20InsufficientBalance',
+ * //   signature: 'ERC20InsufficientBalance(address,uint256,uint256)',
+ * //   args: ['0x9281…', 487711967n, 1261711967n],
+ * // }
+ * ```
+ */
+export declare function decodeRevertData(data: string, opts?: {
+    extraAbis?: InterfaceAbi[];
+}): IDecodedRevert;
+/** Fields recovered from an ethers v6 error string by {@link extractRevertFromErrorText}. */
+export interface IExtractedRevertContext {
+    /** The revert blob from the top-level `data="0x…"` field, when present. */
+    revertData?: string;
+    /** The failed operation from `action="…"` (e.g. `'estimateGas'`, `'call'`). */
+    action?: string;
+    /** The ethers error code from `code=…` (e.g. `'CALL_EXCEPTION'`). */
+    code?: string;
+    /** The embedded `transaction={ … }` fields that survived, when any did. */
+    tx?: {
+        from?: string;
+        to?: string;
+        data?: string;
+    };
+}
+/**
+ * Parse an ethers v6 error *string* and recover the machine-readable fields
+ * embedded in it.
+ *
+ * ethers v6 serializes rich error objects into a single message of the shape
+ * `… (action="estimateGas", data="0x…", reason=…, transaction={ "data":
+ * "0x…", "from": "0x…", "to": "0x…" }, …, code=CALL_EXCEPTION, version=…)` —
+ * exactly what error-alert pipelines end up carrying once the original error
+ * object is stringified. This helper regex-extracts the revert `data`, the
+ * `action`, the `code`, and the embedded transaction fields.
+ *
+ * Pure and offline. Tolerant of truncation: alert transports often cap
+ * message length mid-hex, so every field is matched without requiring its
+ * closing quote and the result simply omits whatever did not survive.
+ *
+ * @param text - The error text to parse (an ethers v6 `error.message`, or a
+ *   log/alert line that embeds one).
+ * @returns The recovered fields; an empty object when nothing matched. Never
+ *   throws.
+ *
+ * @example
+ * ```ts
+ * const ctx = extractRevertFromErrorText(alertErrorLine);
+ * if (ctx.revertData) console.log(decodeRevertData(ctx.revertData));
+ * ```
+ */
+export declare function extractRevertFromErrorText(text: string): IExtractedRevertContext;
+/**
+ * Look up candidate signatures for an unknown 4-byte selector against public
+ * signature databases.
+ *
+ * Network helper — queries [openchain.xyz](https://openchain.xyz) first and
+ * falls back to [4byte.directory](https://www.4byte.directory). Kept separate
+ * from {@link decodeRevertData} so the core decode path stays offline.
+ * Worst case 2 HTTPS requests.
+ *
+ * @param selector - The selector to look up. Longer hex (a full revert blob)
+ *   is accepted; only the first 4 bytes are used.
+ * @returns Candidate signatures (e.g. `['ERC20InsufficientBalance(address,uint256,uint256)']`),
+ *   most-likely first. Empty when the input is not hex, no database knows the
+ *   selector, or both databases were unreachable. Never throws.
+ *
+ * @example
+ * ```ts
+ * const candidates = await lookupSelector('0xe450d38c');
+ * ```
+ */
+export declare function lookupSelector(selector: string): Promise<string[]>;
+/** Result of an {@link simulateCall} `eth_call` replay. */
+export type ISimulateCallResult = {
+    /** The call succeeded. */
+    ok: true;
+    /** The raw return data of the call, `0x`-prefixed. */
+    returnData: string;
+} | {
+    /** The call reverted or the node rejected it. */
+    ok: false;
+    /** Fresh, untruncated revert blob when the node returned one. */
+    revertData?: string;
+    /** {@link decodeRevertData} applied to `revertData`, when present. */
+    decoded?: IDecodedRevert;
+    /** The underlying error message, for failures without revert data. */
+    errorMessage: string;
+};
+/**
+ * Replay a call via `eth_call` and decode the revert when it fails.
+ *
+ * The primary use is re-executing a transaction that failed at `estimateGas`
+ * (so no transaction hash ever existed): the node returns the *full* revert
+ * blob, which both confirms the failure still reproduces and recovers
+ * untruncated revert data even when the original error text was clipped in
+ * transit. Passing a historical `blockTag` replays against archival state
+ * (requires an archive-capable RPC).
+ *
+ * Exactly 1 RPC call (`eth_call`).
+ *
+ * @param provider - A connected `JsonRpcProvider` for the target chain, e.g.
+ *   from `createProvider(rpcUrl, chainId)`. Note that some listed public RPCs
+ *   reject keyless `eth_call` — supply a working endpoint via the SDK's RPC
+ *   precedence (constructor `providers` map / `AUGUST_RPC_<chainId>` env).
+ * @param tx - The call to replay: `to` and `data` are required, `from`
+ *   matters whenever the target checks `msg.sender`.
+ * @param blockTag - Optional block to execute against (`'latest'` by
+ *   default; a number or hex tag replays historical state).
+ * @param opts - Optional settings forwarded to {@link decodeRevertData}.
+ * @param opts.extraAbis - Additional ABIs checked before the built-in corpus
+ *   when decoding a revert.
+ * @returns `{ ok: true, returnData }` on success; on failure `{ ok: false }`
+ *   with the fresh `revertData` and its decode when the node supplied one.
+ *   Never throws on revert — only on programmer error (e.g. no provider).
+ *
+ * @example
+ * ```ts
+ * const result = await simulateCall(provider, {
+ *   from: eoa,
+ *   to: vault,
+ *   data: calldata,
+ * });
+ * if (!result.ok && result.decoded) console.log(result.decoded.signature);
+ * ```
+ */
+export declare function simulateCall(provider: JsonRpcProvider, tx: {
+    from?: string;
+    to: string;
+    data: string;
+}, blockTag?: string | number, opts?: {
+    extraAbis?: InterfaceAbi[];
+}): Promise<ISimulateCallResult>;
+/** Snapshot of a holder's token state returned by {@link readTokenState}. */
+export interface ITokenState {
+    /** Token symbol, when the contract implements `symbol()`. */
+    symbol?: string;
+    /** Token decimals, when the contract implements `decimals()`. */
+    decimals?: number;
+    /** The holder's raw balance in base units, when `balanceOf` resolved. */
+    balance?: bigint;
+    /** Raw allowance from holder to `spender`, only probed when `spender` was given. */
+    allowance?: bigint;
+    /**
+     * Whether the holder is frozen/blacklisted by the token issuer, from the
+     * first compliance getter the token implements (`isAccountFrozen` — Agora
+     * AUSD, `isBlacklisted` — USDC-style, `isFrozen`). `undefined` when the
+     * token exposes none of them — which is NOT evidence the holder is clear,
+     * only that the token has no recognized compliance getter.
+     */
+    frozen?: boolean;
+}
+/**
+ * Read a bounded, fixed set of token-state probes for a holder — the exact
+ * facts needed to explain a failed deposit/transfer: what the token is, what
+ * the holder has, what the spender may pull, and whether the issuer froze the
+ * holder.
+ *
+ * The probe set is deliberately fixed (no arbitrary calldata): `symbol()`,
+ * `decimals()`, `balanceOf(holder)`, `allowance(holder, spender)` when a
+ * spender is given, and the compliance getters tried in order —
+ * `isAccountFrozen(address)` (Agora AUSD, selector `0xe816d97f`),
+ * `isBlacklisted(address)` (USDC-style), `isFrozen(address)`. Probes the
+ * token does not implement resolve to `undefined`; this function never
+ * throws.
+ *
+ * Worst case 7 RPC calls (4 base probes + 3 compliance getters), batched by
+ * the provider where supported.
+ *
+ * @param provider - A connected `JsonRpcProvider` for the token's chain.
+ * @param token - The ERC-20 token contract address.
+ * @param holder - The account whose balance/compliance state to read.
+ * @param spender - Optional spender for the `allowance(holder, spender)`
+ *   probe (e.g. the vault a deposit approves).
+ * @returns The token state with every unresolvable probe as `undefined`.
+ *
+ * @example
+ * ```ts
+ * const state = await readTokenState(provider, ausd, eoa, vault);
+ * // { symbol: 'AUSD', decimals: 6, balance: 487711967n, allowance: 0n, frozen: false }
+ * ```
+ */
+export declare function readTokenState(provider: JsonRpcProvider, token: string, holder: string, spender?: string): Promise<ITokenState>;