@augustdigital/sdk 8.12.0 → 8.13.0

package/lib/core/analytics/method-taxonomy.js

@@ -40,6 +40,8 @@ exports.METHOD_CATEGORIES = {
     getYieldLastRealizedOn: 'read.vault',
     getVaultActivity: 'read.vault',
     getSwapRouterDepositResult: 'read.vault',
+    getSwapRouterWhitelistedTokens: 'read.vault',
+    getSwapRouterEligibleVaults: 'read.vault',
     getVaultPositions: 'read.position',
     getVaultUserHistory: 'read.position',
     getUserHistory: 'read.position',

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "8.12.0";
+export declare const SDK_VERSION = "8.13.0";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '8.12.0';
+exports.SDK_VERSION = '8.13.0';
 //# sourceMappingURL=version.js.map

package/lib/core/constants/swap-router.d.ts

@@ -8,6 +8,20 @@ import type { IAddress } from '../../types';
  * @see {@link getSwapRouterAddress} for the typed lookup helper.
  */
 export declare const SWAP_ROUTER_ADDRESSES: Readonly<Record<number, IAddress>>;
+/**
+ * Human-readable display name of the `SwapRouter` periphery contract on each
+ * supported chain.
+ *
+ * The contract exposes no on-chain name (no `@title` accessor), so UIs that
+ * want to show *which contract* performed the swap-and-deposit — rather than a
+ * bare address — read it from here. Display metadata only: never derive
+ * routing or eligibility logic from it.
+ *
+ * Missing keys mean no SwapRouter is deployed on that chain.
+ *
+ * @see {@link getSwapRouterName} for the typed lookup helper.
+ */
+export declare const SWAP_ROUTER_NAMES: Readonly<Record<number, string>>;
 /**
  * Vaults whose UI **may offer the any-token SwapRouter deposit surface** —
  * i.e. the SwapRouter is `enableVault`-ed for them on-chain.
@@ -31,15 +45,41 @@ export declare const SWAP_ROUTER_ADDRESSES: Readonly<Record<number, IAddress>>;
  *
  * Lowercase comparison is required when checking — use
  * {@link isSwapRouterEligible} rather than reading this set directly.
+ *
+ * @deprecated Superseded by {@link getSwapRouterEligibleVaults}, which derives
+ * the eligible set from the router's on-chain `VaultEnabled` history and
+ * verifies each vault's current registration (`vaultInfo.referenceAsset != 0`)
+ * — so new enablements surface without an SDK release. This static set stays
+ * functional as the zero-RPC fallback seed (e.g. TanStack Query `initialData`)
+ * and for SDK-internal sync consumers.
  */
 export declare const SWAP_ROUTER_ELIGIBLE_VAULTS: ReadonlySet<string>;
 /**
- * @deprecated Renamed to {@link SWAP_ROUTER_ELIGIBLE_VAULTS}, and the semantics
- * changed: this set no longer drives `vaultDeposit` auto-routing (that branch
- * was removed) — it now only marks vaults whose UI may offer the swap-router
- * deposit surface. Kept as an alias for one release; migrate to the new name.
+ * @deprecated Renamed to {@link SWAP_ROUTER_ELIGIBLE_VAULTS} (itself now
+ * superseded by {@link getSwapRouterEligibleVaults}, the on-chain-derived
+ * resolver), and the semantics changed: this set no longer drives
+ * `vaultDeposit` auto-routing (that branch was removed) — it only marks vaults
+ * whose UI may offer the swap-router deposit surface. Kept as an alias for one
+ * release; migrate to the async resolver.
  */
 export declare const VAULTS_USING_SWAP_ROUTER: ReadonlySet<string>;
+/**
+ * Block at which each chain's `SwapRouter` was deployed/configured — the safe
+ * lower bound for scanning its `TokenEnabled` / `VaultEnabled` log history.
+ *
+ * The router stores its allowlist as `mapping(address => bool) whitelistedTokens`
+ * with no on-chain enumeration, so {@link getSwapRouterWhitelistedTokens} must
+ * reconstruct the candidate set from `TokenEnabled` events before verifying each
+ * against the current mapping. Starting the `eth_getLogs` scan here (rather than
+ * from genesis) bounds it to the router's own lifetime — a few chunks — instead
+ * of the whole chain.
+ *
+ * Mainnet value is the router's deployment block (its first emitted event, the
+ * constructor `OwnershipTransferred`). A too-low value only costs extra empty
+ * log ranges; a value ABOVE the first `TokenEnabled` would silently miss tokens,
+ * so err on the side of earlier.
+ */
+export declare const SWAP_ROUTER_DEPLOY_BLOCKS: Readonly<Record<number, number>>;
 /**
  * 32-byte origin codes registered on the `SwapRouter` via `addOrigin`.
  * Drives origin/referral-fee accrual. The on-chain admin must register a

package/lib/core/constants/swap-router.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_CODES = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS = exports.SWAP_ROUTER_ADDRESSES = void 0;
+exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_CODES = exports.SWAP_ROUTER_DEPLOY_BLOCKS = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS = exports.SWAP_ROUTER_NAMES = exports.SWAP_ROUTER_ADDRESSES = void 0;
 /**
  * Address of the `SwapRouter` periphery contract on each supported chain.
  *
@@ -12,6 +12,22 @@ exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = export
 exports.SWAP_ROUTER_ADDRESSES = {
     1: '0xAC771209FF2b71EECfF6E85a9AD01db8Ff2618B0',
 };
+/**
+ * Human-readable display name of the `SwapRouter` periphery contract on each
+ * supported chain.
+ *
+ * The contract exposes no on-chain name (no `@title` accessor), so UIs that
+ * want to show *which contract* performed the swap-and-deposit — rather than a
+ * bare address — read it from here. Display metadata only: never derive
+ * routing or eligibility logic from it.
+ *
+ * Missing keys mean no SwapRouter is deployed on that chain.
+ *
+ * @see {@link getSwapRouterName} for the typed lookup helper.
+ */
+exports.SWAP_ROUTER_NAMES = {
+    1: 'Upshift Swap Router',
+};
 /**
  * Vaults whose UI **may offer the any-token SwapRouter deposit surface** —
  * i.e. the SwapRouter is `enableVault`-ed for them on-chain.
@@ -35,6 +51,13 @@ exports.SWAP_ROUTER_ADDRESSES = {
  *
  * Lowercase comparison is required when checking — use
  * {@link isSwapRouterEligible} rather than reading this set directly.
+ *
+ * @deprecated Superseded by {@link getSwapRouterEligibleVaults}, which derives
+ * the eligible set from the router's on-chain `VaultEnabled` history and
+ * verifies each vault's current registration (`vaultInfo.referenceAsset != 0`)
+ * — so new enablements surface without an SDK release. This static set stays
+ * functional as the zero-RPC fallback seed (e.g. TanStack Query `initialData`)
+ * and for SDK-internal sync consumers.
  */
 exports.SWAP_ROUTER_ELIGIBLE_VAULTS = new Set([
     // Sentora USD — native multi-asset Tokenized Vault V2 (reference asset
@@ -43,12 +66,33 @@ exports.SWAP_ROUTER_ELIGIBLE_VAULTS = new Set([
     '0x74ad2f789ed583dbd141bbdafc673fe1f033718b',
 ]);
 /**
- * @deprecated Renamed to {@link SWAP_ROUTER_ELIGIBLE_VAULTS}, and the semantics
- * changed: this set no longer drives `vaultDeposit` auto-routing (that branch
- * was removed) — it now only marks vaults whose UI may offer the swap-router
- * deposit surface. Kept as an alias for one release; migrate to the new name.
+ * @deprecated Renamed to {@link SWAP_ROUTER_ELIGIBLE_VAULTS} (itself now
+ * superseded by {@link getSwapRouterEligibleVaults}, the on-chain-derived
+ * resolver), and the semantics changed: this set no longer drives
+ * `vaultDeposit` auto-routing (that branch was removed) — it only marks vaults
+ * whose UI may offer the swap-router deposit surface. Kept as an alias for one
+ * release; migrate to the async resolver.
  */
 exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS;
+/**
+ * Block at which each chain's `SwapRouter` was deployed/configured — the safe
+ * lower bound for scanning its `TokenEnabled` / `VaultEnabled` log history.
+ *
+ * The router stores its allowlist as `mapping(address => bool) whitelistedTokens`
+ * with no on-chain enumeration, so {@link getSwapRouterWhitelistedTokens} must
+ * reconstruct the candidate set from `TokenEnabled` events before verifying each
+ * against the current mapping. Starting the `eth_getLogs` scan here (rather than
+ * from genesis) bounds it to the router's own lifetime — a few chunks — instead
+ * of the whole chain.
+ *
+ * Mainnet value is the router's deployment block (its first emitted event, the
+ * constructor `OwnershipTransferred`). A too-low value only costs extra empty
+ * log ranges; a value ABOVE the first `TokenEnabled` would silently miss tokens,
+ * so err on the side of earlier.
+ */
+exports.SWAP_ROUTER_DEPLOY_BLOCKS = {
+    1: 25237804,
+};
 /**
  * 32-byte origin codes registered on the `SwapRouter` via `addOrigin`.
  * Drives origin/referral-fee accrual. The on-chain admin must register a

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>;