@augustdigital/sdk 8.11.0 → 8.13.0

package/lib/core/helpers/revert-decode.js

@@ -0,0 +1,515 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeRevertData = decodeRevertData;
+exports.extractRevertFromErrorText = extractRevertFromErrorText;
+exports.lookupSelector = lookupSelector;
+exports.simulateCall = simulateCall;
+exports.readTokenState = readTokenState;
+const ethers_1 = require("ethers");
+const abis_1 = require("../../abis");
+/**
+ * Revert-data decoding helpers.
+ *
+ * Leaf module (depends only on `ethers` and `abis/`) that turns raw EVM revert
+ * blobs — the `data="0x…"` payload an ethers v6 `CALL_EXCEPTION` carries — into
+ * named errors with decoded arguments. The core decode path
+ * ({@link decodeRevertData}, {@link extractRevertFromErrorText}) is pure and
+ * offline: no RPC, no network, safe in both browser and Node. The network
+ * helpers ({@link lookupSelector}, {@link simulateCall},
+ * {@link readTokenState}) are exported separately so tree-shaken offline
+ * consumers never pull them in.
+ *
+ * @module
+ */
+/** ABI selector for the standard `Error(string)` revert (`require` with a message). */
+const ERROR_STRING_SELECTOR = '0x08c379a0';
+/** ABI selector for the compiler-inserted `Panic(uint256)` revert. */
+const PANIC_SELECTOR = '0x4e487b71';
+/**
+ * Human-readable names for the Solidity `Panic(uint256)` codes, as defined in
+ * the Solidity documentation ("Panic via assert and Error via require").
+ */
+const PANIC_CODE_NAMES = {
+    0: 'generic compiler-inserted panic',
+    1: 'assertion failed (assert)',
+    17: 'arithmetic overflow or underflow',
+    18: 'division or modulo by zero',
+    33: 'value invalid for enum type',
+    34: 'incorrectly encoded storage byte array',
+    49: 'pop() on an empty array',
+    50: 'array index out of bounds',
+    65: 'allocation of too much memory or array too large',
+    81: 'call to a zero-initialized variable of internal function type',
+};
+/**
+ * Well-known custom-error signatures included in the built-in decode corpus,
+ * declared as human-readable fragments:
+ *
+ * - OpenZeppelin ERC-6093 error sets for ERC-20 / ERC-721 / ERC-1155
+ *   (`draft-IERC6093.sol`, OpenZeppelin Contracts 5.x).
+ * - OpenZeppelin `SafeERC20`, `ERC4626`, `Ownable`, `Pausable`, and
+ *   `ReentrancyGuard` errors (OpenZeppelin Contracts 5.x).
+ * - LayerZero V2 `OApp`/`OFT` errors (`IOAppCore.sol`, `OFTCore.sol`) — the
+ *   error surface of the SDK's cross-chain OVault flows.
+ */
+const STANDARD_ERROR_SIGNATURES = [
+    'error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed)',
+    'error ERC20InvalidSender(address sender)',
+    'error ERC20InvalidReceiver(address receiver)',
+    'error ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed)',
+    'error ERC20InvalidApprover(address approver)',
+    'error ERC20InvalidSpender(address spender)',
+    'error ERC721InvalidOwner(address owner)',
+    'error ERC721NonexistentToken(uint256 tokenId)',
+    'error ERC721IncorrectOwner(address sender, uint256 tokenId, address owner)',
+    'error ERC721InvalidSender(address sender)',
+    'error ERC721InvalidReceiver(address receiver)',
+    'error ERC721InsufficientApproval(address operator, uint256 tokenId)',
+    'error ERC721InvalidApprover(address approver)',
+    'error ERC721InvalidOperator(address operator)',
+    'error ERC1155InsufficientBalance(address sender, uint256 balance, uint256 needed, uint256 tokenId)',
+    'error ERC1155InvalidSender(address sender)',
+    'error ERC1155InvalidReceiver(address receiver)',
+    'error ERC1155MissingApprovalForAll(address operator, address owner)',
+    'error ERC1155InvalidApprover(address approver)',
+    'error ERC1155InvalidOperator(address operator)',
+    'error ERC1155InvalidArrayLength(uint256 idsLength, uint256 valuesLength)',
+    'error SafeERC20FailedOperation(address token)',
+    'error SafeERC20FailedDecreaseAllowance(address spender, uint256 currentAllowance, uint256 requestedDecrease)',
+    'error ERC4626ExceededMaxDeposit(address receiver, uint256 assets, uint256 max)',
+    'error ERC4626ExceededMaxMint(address receiver, uint256 shares, uint256 max)',
+    'error ERC4626ExceededMaxWithdraw(address owner, uint256 assets, uint256 max)',
+    'error ERC4626ExceededMaxRedeem(address owner, uint256 shares, uint256 max)',
+    'error OwnableUnauthorizedAccount(address account)',
+    'error OwnableInvalidOwner(address owner)',
+    'error EnforcedPause()',
+    'error ExpectedPause()',
+    'error ReentrancyGuardReentrantCall()',
+    'error NoPeer(uint32 eid)',
+    'error OnlyPeer(uint32 eid, bytes32 sender)',
+    'error OnlyEndpoint(address addr)',
+    'error InvalidDelegate()',
+    'error InvalidEndpointCall()',
+    'error LzTokenUnavailable()',
+    'error NotEnoughNative(uint256 msgValue)',
+    'error SlippageExceeded(uint256 amountLD, uint256 minAmountLD)',
+    'error InvalidLocalDecimals()',
+];
+/**
+ * ABIs already shipped by the SDK whose `error` fragments join the corpus.
+ * Covers the August/Upshift vault estate: tokenized vaults (plus their
+ * receipt / permit / whitelist companions), the SwapRouter, lending pools,
+ * the fee oracle, the native-deposit wrapper, Multicall3, and the RWA redeem
+ * subaccount.
+ */
+const CORPUS_ABIS = [
+    STANDARD_ERROR_SIGNATURES,
+    abis_1.ABI_TOKENIZED_VAULT_V2,
+    abis_1.ABI_TOKENIZED_VAULT_V2_RECEIPT,
+    abis_1.ABI_TOKENIZED_VAULT_V2_DEPOSIT_WITH_PERMIT,
+    abis_1.ABI_TOKENIZED_VAULT_V2_WHITELISTED_ASSETS,
+    abis_1.ABI_TOKENIZED_VAULT_V2_WHITELISTED_ALLOCATION,
+    abis_1.ABI_TOKENIZED_VAULT_V2_SENDER_ALLOCATION_WHITELIST,
+    abis_1.ABI_MULTI_ASSET_NATIVE_DEPOSIT_WRAPPER,
+    abis_1.ABI_SWAP_ROUTER,
+    abis_1.ABI_LENDING_POOL_V3,
+    abis_1.ABI_FEE_ORACLE,
+    abis_1.ABI_MULTICALL3,
+    abis_1.RWA_REDEEM_SUBACCOUNT,
+];
+let corpusInterface;
+function getCorpusInterface() {
+    if (corpusInterface)
+        return corpusInterface;
+    const bySelector = new Map();
+    for (const abi of CORPUS_ABIS) {
+        const iface = new ethers_1.Interface(abi);
+        iface.forEachError((fragment) => {
+            if (!bySelector.has(fragment.selector)) {
+                bySelector.set(fragment.selector, fragment);
+            }
+        });
+    }
+    corpusInterface = new ethers_1.Interface([...bySelector.values()]);
+    return corpusInterface;
+}
+function decodeWithFragment(iface, fragment, data, selector) {
+    const base = {
+        kind: 'custom',
+        selector,
+        name: fragment.name,
+        signature: fragment.format('sighash'),
+    };
+    try {
+        const args = iface.decodeErrorResult(fragment, data);
+        return { ...base, args: Array.from(args) };
+    }
+    catch {
+        return {
+            ...base,
+            reason: `matched ${fragment.format('sighash')} but the argument data is truncated or malformed`,
+        };
+    }
+}
+/**
+ * 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],
+ * // }
+ * ```
+ */
+function decodeRevertData(data, opts) {
+    const hex = typeof data === 'string' ? data.trim() : '';
+    if (!/^0x[0-9a-fA-F]*$/.test(hex) || hex.length < 10) {
+        return { kind: 'unknown', selector: hex.slice(0, 10).toLowerCase() };
+    }
+    const selector = hex.slice(0, 10).toLowerCase();
+    if (selector === ERROR_STRING_SELECTOR) {
+        try {
+            const [message] = ethers_1.AbiCoder.defaultAbiCoder().decode(['string'], `0x${hex.slice(10)}`);
+            return {
+                kind: 'error-string',
+                selector,
+                name: 'Error',
+                signature: 'Error(string)',
+                args: [message],
+                reason: message,
+            };
+        }
+        catch {
+            return {
+                kind: 'error-string',
+                selector,
+                name: 'Error',
+                signature: 'Error(string)',
+                reason: 'Error(string) revert with truncated or malformed message data',
+            };
+        }
+    }
+    if (selector === PANIC_SELECTOR) {
+        try {
+            const [code] = ethers_1.AbiCoder.defaultAbiCoder().decode(['uint256'], `0x${hex.slice(10)}`);
+            const named = PANIC_CODE_NAMES[Number(code)];
+            return {
+                kind: 'panic',
+                selector,
+                name: 'Panic',
+                signature: 'Panic(uint256)',
+                args: [code],
+                reason: named
+                    ? `panic 0x${code.toString(16).padStart(2, '0')}: ${named}`
+                    : `panic 0x${code.toString(16)}: unrecognized panic code`,
+            };
+        }
+        catch {
+            return {
+                kind: 'panic',
+                selector,
+                name: 'Panic',
+                signature: 'Panic(uint256)',
+                reason: 'Panic(uint256) revert with truncated or malformed code data',
+            };
+        }
+    }
+    for (const abi of opts?.extraAbis ?? []) {
+        try {
+            const iface = new ethers_1.Interface(abi);
+            const fragment = iface.getError(selector);
+            if (fragment)
+                return decodeWithFragment(iface, fragment, hex, selector);
+        }
+        catch { }
+    }
+    const corpus = getCorpusInterface();
+    const fragment = corpus.getError(selector);
+    if (fragment)
+        return decodeWithFragment(corpus, fragment, hex, selector);
+    return { kind: 'unknown', selector };
+}
+/**
+ * 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));
+ * ```
+ */
+function extractRevertFromErrorText(text) {
+    const out = {};
+    if (typeof text !== 'string' || text.length === 0)
+        return out;
+    const action = text.match(/\baction="([^"]+)"/);
+    if (action)
+        out.action = action[1];
+    const code = text.match(/\bcode=([A-Z_]+)/);
+    if (code)
+        out.code = code[1];
+    const revertData = text.match(/[(,]\s*data="(0x[0-9a-fA-F]*)/);
+    if (revertData)
+        out.revertData = revertData[1];
+    const txData = text.match(/"data"\s*:\s*"(0x[0-9a-fA-F]*)/);
+    const txFrom = text.match(/"from"\s*:\s*"(0x[0-9a-fA-F]*)/);
+    const txTo = text.match(/"to"\s*:\s*"(0x[0-9a-fA-F]*)/);
+    if (txData || txFrom || txTo) {
+        out.tx = {};
+        if (txFrom)
+            out.tx.from = txFrom[1];
+        if (txTo)
+            out.tx.to = txTo[1];
+        if (txData)
+            out.tx.data = txData[1];
+    }
+    return out;
+}
+/**
+ * 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');
+ * ```
+ */
+async function lookupSelector(selector) {
+    const hex = typeof selector === 'string' ? selector.trim() : '';
+    if (!/^0x[0-9a-fA-F]{8,}$/.test(hex))
+        return [];
+    const sel = hex.slice(0, 10).toLowerCase();
+    try {
+        const res = await fetch(`https://api.openchain.xyz/signature-database/v1/lookup?function=${sel}&filter=true`);
+        if (res.ok) {
+            const body = (await res.json());
+            const entries = body.result?.function?.[sel];
+            const names = (entries ?? [])
+                .map((e) => e.name)
+                .filter((n) => typeof n === 'string' && n.length > 0);
+            if (names.length > 0)
+                return [...new Set(names)];
+        }
+    }
+    catch {
+        /* fall through to 4byte */
+    }
+    try {
+        const res = await fetch(`https://www.4byte.directory/api/v1/signatures/?hex_signature=${sel}&ordering=created_at`);
+        if (res.ok) {
+            const body = (await res.json());
+            const names = (body.results ?? [])
+                .map((r) => r.text_signature)
+                .filter((n) => typeof n === 'string' && n.length > 0);
+            return [...new Set(names)];
+        }
+    }
+    catch {
+        /* both sources unreachable */
+    }
+    return [];
+}
+function extractRevertDataFromError(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const e = error;
+    const candidates = [e.data, e.error?.data, e.info?.error?.data];
+    for (const c of candidates) {
+        if (typeof c === 'string' && /^0x[0-9a-fA-F]*$/.test(c) && c.length >= 10) {
+            return c;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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);
+ * ```
+ */
+async function simulateCall(provider, tx, blockTag, opts) {
+    try {
+        const returnData = await provider.call({
+            from: tx.from,
+            to: tx.to,
+            data: tx.data,
+            blockTag,
+        });
+        return { ok: true, returnData };
+    }
+    catch (error) {
+        const revertData = extractRevertDataFromError(error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (!revertData)
+            return { ok: false, errorMessage };
+        return {
+            ok: false,
+            revertData,
+            decoded: decodeRevertData(revertData, opts),
+            errorMessage,
+        };
+    }
+}
+const TOKEN_STATE_ABI = [
+    'function symbol() view returns (string)',
+    'function decimals() view returns (uint8)',
+    'function balanceOf(address account) view returns (uint256)',
+    'function allowance(address owner, address spender) view returns (uint256)',
+    'function isAccountFrozen(address account) view returns (bool)',
+    'function isBlacklisted(address account) view returns (bool)',
+    'function isFrozen(address account) view returns (bool)',
+];
+/**
+ * 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 }
+ * ```
+ */
+async function readTokenState(provider, token, holder, spender) {
+    const contract = new ethers_1.Contract(token, TOKEN_STATE_ABI, provider);
+    const out = {};
+    const [symbol, decimals, balance, allowance] = await Promise.allSettled([
+        contract.symbol(),
+        contract.decimals(),
+        contract.balanceOf(holder),
+        spender
+            ? contract.allowance(holder, spender)
+            : Promise.reject(new Error('no spender')),
+    ]);
+    if (symbol.status === 'fulfilled')
+        out.symbol = symbol.value;
+    if (decimals.status === 'fulfilled')
+        out.decimals = Number(decimals.value);
+    if (balance.status === 'fulfilled')
+        out.balance = balance.value;
+    if (spender && allowance.status === 'fulfilled') {
+        out.allowance = allowance.value;
+    }
+    const complianceProbes = ['isAccountFrozen', 'isBlacklisted', 'isFrozen'];
+    for (const probe of complianceProbes) {
+        try {
+            const frozen = (await contract[probe](holder));
+            out.frozen = Boolean(frozen);
+            break;
+        }
+        catch { }
+    }
+    return out;
+}
+//# sourceMappingURL=revert-decode.js.map