augustdigital-sdk 8.20.1

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

@@ -0,0 +1,480 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vaultUsesSwapRouter = void 0;
+exports.getSwapRouterAddress = getSwapRouterAddress;
+exports.getSwapRouterName = getSwapRouterName;
+exports.isSwapRouterEligible = isSwapRouterEligible;
+exports.resolveOriginCode = resolveOriginCode;
+exports.getSwapRouterDepositResult = getSwapRouterDepositResult;
+exports.getSwapRouterWhitelistedTokens = getSwapRouterWhitelistedTokens;
+exports.getSwapRouterEligibleVaults = getSwapRouterEligibleVaults;
+const ethers_1 = require("ethers");
+const swap_router_1 = require("../constants/swap-router");
+const abis_1 = require("../../abis");
+const errors_1 = require("../errors");
+const cache_1 = require("../cache");
+const logger_1 = require("../logger");
+const web3_1 = require("./web3");
+const multicall_1 = require("./multicall");
+/**
+ * Resolve the `SwapRouter` address for a chain.
+ *
+ * @param chainId - EVM chain ID.
+ * @returns The router address, or `undefined` if no SwapRouter is deployed.
+ * @example
+ * ```ts
+ * const router = getSwapRouterAddress(1);
+ * // '0xAC771209FF2b71EECfF6E85a9AD01db8Ff2618B0'
+ * ```
+ */
+function getSwapRouterAddress(chainId) {
+    return swap_router_1.SWAP_ROUTER_ADDRESSES[chainId];
+}
+/**
+ * Resolve the human-readable display name of the `SwapRouter` periphery
+ * contract for a chain.
+ *
+ * The contract exposes no name on-chain, so this reads the SDK-maintained
+ * {@link SWAP_ROUTER_NAMES} registry. Intended for UI surfaces that label the
+ * contract a swap-and-deposit routes through (e.g. a "Router" row in a
+ * transaction overview) — display metadata only, never routing logic.
+ *
+ * @param chainId - EVM chain ID.
+ * @returns The display name (e.g. `'Upshift Swap Router'`), or `undefined`
+ *   when no SwapRouter is deployed on the chain — callers should omit the
+ *   label rather than show an address.
+ * @example
+ * ```ts
+ * const name = getSwapRouterName(1);
+ * // 'Upshift Swap Router'
+ * ```
+ */
+function getSwapRouterName(chainId) {
+    return swap_router_1.SWAP_ROUTER_NAMES[chainId];
+}
+/**
+ * Whether a vault is eligible for the any-token `SwapRouter` deposit surface
+ * (the SwapRouter is `enableVault`-ed for it on-chain). Address comparison is
+ * case-insensitive.
+ *
+ * This gates the (flag-controlled) swap-router deposit UI and can fail-fast a
+ * {@link swapRouterDeposit} call. It does **not** affect {@link vaultDeposit},
+ * which is always the native/multiasset/adapter path.
+ *
+ * @param vaultAddress - August vault address.
+ * @returns `true` when the vault is in {@link SWAP_ROUTER_ELIGIBLE_VAULTS}.
+ * @deprecated Superseded by {@link getSwapRouterEligibleVaults}, which resolves
+ * eligibility from the router's on-chain `VaultEnabled` history + current
+ * `vaultInfo` registration instead of this static snapshot. Kept functional as
+ * the zero-RPC sync fallback (seed data, fail-fast checks); migrate UI gates
+ * to the async resolver.
+ */
+function isSwapRouterEligible(vaultAddress) {
+    return swap_router_1.SWAP_ROUTER_ELIGIBLE_VAULTS.has(vaultAddress.toLowerCase());
+}
+/**
+ * @deprecated Renamed to {@link isSwapRouterEligible} (itself now superseded by
+ * {@link getSwapRouterEligibleVaults}, the on-chain-derived resolver). The
+ * meaning also changed: it no longer implies `vaultDeposit` routes the vault
+ * through the SwapRouter (that behavior was removed) — it only reports
+ * swap-router *eligibility* for the opt-in deposit surface. Kept as an alias
+ * for one release; migrate to the async resolver.
+ */
+exports.vaultUsesSwapRouter = isSwapRouterEligible;
+/**
+ * Normalize an optional origin code to the value to send on-chain.
+ *
+ * Returns the caller-supplied code when present, otherwise the default
+ * (all-zero) sentinel from {@link ORIGIN_CODES}. Validates that any
+ * supplied code is exactly 32 bytes (66 chars including the `0x` prefix);
+ * the on-chain SwapRouter reverts with `InvalidOrigin` otherwise, but
+ * surfacing the failure here as a typed SDK error gives partners a
+ * grepable Sentry event instead of a generic `execution reverted`.
+ *
+ * @param provided - Optional caller-supplied origin code.
+ * @returns The 32-byte origin code to pass to the router.
+ * @throws {@link AugustValidationError} when `provided` is not a 32-byte hex string.
+ */
+function resolveOriginCode(provided) {
+    if (provided === undefined)
+        return swap_router_1.ORIGIN_CODES.default;
+    if (!/^0x[0-9a-fA-F]{64}$/.test(provided)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `resolveOriginCode: originCode must be a 32-byte hex string (66 chars incl. 0x), got "${provided}" (${provided.length} chars)`, { context: { provided, expectedLength: 66 } });
+    }
+    return provided;
+}
+/**
+ * Resolves the real, post-execution outcome of a SwapRouter deposit from its
+ * mined transaction receipt. The SwapRouter contract itself emits no
+ * deposit/amount-out event — only the vault does, via its own `Deposit` event
+ * — so this decodes that log directly rather than trusting the pre-trade quote
+ * a UI shows before the user submits (the true post-swap amount depends on
+ * execution-time price and can differ from that estimate).
+ *
+ * Works for both vault generations without the caller resolving the version
+ * first: evm-1 (ERC-4626-style `Deposit(sender, owner, assets, shares)`) and
+ * evm-2 (`Deposit(assetIn, amountIn, shares, senderAddr, receiverAddr)`) have
+ * different event signatures (different topic0), so both are registered and
+ * whichever matches the vault's actual log is decoded.
+ *
+ * @param signer - ethers `Signer` or `Wallet` connected to a provider (used
+ *   read-only here — no transaction is sent).
+ * @param options - {@link ISwapRouterDepositResultOptions}.
+ * @returns The decoded {@link ISwapRouterDepositResult}, or `null` if the
+ *   receipt isn't found yet or carries no `Deposit` log from `vault` (e.g. the
+ *   hash is wrong, or the tx hasn't mined).
+ * @throws {@link AugustValidationError} if `signer` has no connected provider.
+ * @worstCaseRpcCalls 1 — a single `getTransactionReceipt` call; decoding is
+ *   local.
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.swapRouterDeposit({ ... });
+ * const result = await augustSdk.evm.getSwapRouterDepositResult({
+ *   txHash: hash,
+ *   vault: '0x74ad2f789ed583dbd141bbdafc673fe1f033718b',
+ * });
+ * // result?.amountOut — actual reference-asset amount received after the swap
+ * ```
+ */
+async function getSwapRouterDepositResult(signer, { txHash, vault }) {
+    const provider = signer.provider;
+    if (!provider) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', 'getSwapRouterDepositResult: signer has no connected provider');
+    }
+    const receipt = await provider.getTransactionReceipt(txHash);
+    if (!receipt)
+        return null;
+    const iface = new ethers_1.ethers.Interface([
+        'event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares)',
+        'event Deposit(address assetIn, uint256 amountIn, uint256 shares, address indexed senderAddr, address indexed receiverAddr)',
+    ]);
+    for (const log of receipt.logs) {
+        if (log.address.toLowerCase() !== vault.toLowerCase())
+            continue;
+        let parsed;
+        try {
+            parsed = iface.parseLog(log);
+        }
+        catch {
+            continue;
+        }
+        if (parsed?.name !== 'Deposit')
+            continue;
+        // Discriminate on the matched event fragment, not on probing a
+        // possibly-absent named arg. Only the evm-2 signature declares `assetIn`,
+        // so its presence in the fragment inputs uniquely identifies the version.
+        // (Reading `parsed.args.assetIn` on the evm-1 log would couple correctness
+        // to ethers' `Result`-proxy behavior for unknown names.)
+        const isEvm2 = parsed.fragment.inputs.some((i) => i.name === 'assetIn');
+        if (isEvm2) {
+            // evm-2 TokenizedVault: Deposit(assetIn, amountIn, shares, sender, receiver)
+            return {
+                amountOut: BigInt(parsed.args.amountIn),
+                sharesOut: BigInt(parsed.args.shares),
+            };
+        }
+        // evm-1 ERC-4626-style: Deposit(sender, owner, assets, shares)
+        return {
+            amountOut: BigInt(parsed.args.assets),
+            sharesOut: BigInt(parsed.args.shares),
+        };
+    }
+    return null;
+}
+/** Cache TTL for a chain's resolved SwapRouter token allowlist (5 minutes). */
+const SWAP_ROUTER_WHITELIST_TTL_MS = 5 * 60 * 1000;
+/**
+ * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
+ * chain — the any-token set a UI can offer as swap-and-deposit inputs.
+ *
+ * The router exposes its allowlist only as `mapping(address => bool)
+ * whitelistedTokens` with **no on-chain enumeration**, so this cannot be a
+ * single view call. It runs in two stages:
+ *  1. Scan the router's `TokenEnabled(address)` event history (from the chain's
+ *     {@link SWAP_ROUTER_DEPLOY_BLOCKS} floor, in `eth_getLogs` chunks sized by
+ *     {@link determineBlockSkipInternal}) to reconstruct the candidate set of
+ *     every token ever enabled.
+ *  2. Re-read `whitelistedTokens(token)` for each candidate — batched via
+ *     Multicall3 where verified, else per-call — and keep only those the
+ *     mapping currently returns `true` for. This step makes later disables (and
+ *     disable-then-re-enable) correct without replaying `TokenDisabled`, and is
+ *     the fail-closed source of truth: a token surfaces only on a definite
+ *     on-chain `true`.
+ *
+ * The resolved list is cached per chain for 5 minutes — the allowlist changes
+ * only via an admin `enableToken`/`disableToken` transaction, so a short TTL
+ * keeps the (multi-RPC) scan off the hot path without going stale for long.
+ *
+ * @param chainId - EVM chain ID. Chains without a {@link SWAP_ROUTER_ADDRESSES}
+ *   entry resolve to `[]` with no RPC.
+ * @param options - `rpcUrl` (required) must point at `chainId`'s network;
+ *   `fromBlock` overrides the default deploy-block scan floor (e.g. to widen a
+ *   scan on a chain missing from {@link SWAP_ROUTER_DEPLOY_BLOCKS}).
+ * @returns Checksummed addresses of the currently-whitelisted tokens, deduped.
+ *   Empty when no router is deployed or none are enabled. Callers still filter
+ *   out a given vault's natively-accepted assets (those deposit without a swap).
+ * @throws AugustValidationError when `rpcUrl` is missing/empty.
+ * @throws AugustSDKError when an `eth_getLogs` chunk fails — surfaced (not
+ *   swallowed) so a partial scan never masquerades as a complete allowlist.
+ * @worstCaseRpcCalls On mainnet, 1 `eth_blockNumber` + ~4 `eth_getLogs` chunks
+ *   (router-lifetime ÷ 50k-block window) + 1 Multicall3 `eth_call` ≈ 6; scales
+ *   with the router's on-chain age, not with candidate count.
+ * @example
+ * ```ts
+ * const tokens = await getSwapRouterWhitelistedTokens(1, {
+ *   rpcUrl: 'https://eth-mainnet.example/v2/KEY',
+ * });
+ * // ['0xA0b8…', '0xdAC1…', '0xC02a…', '0x2260…']  (USDC, USDT, WETH, WBTC)
+ * ```
+ */
+async function getSwapRouterWhitelistedTokens(chainId, options) {
+    const router = getSwapRouterAddress(chainId);
+    if (!router)
+        return [];
+    const cacheKey = `swap-router-whitelisted-tokens-${chainId}-${router.toLowerCase()}`;
+    const cached = await (0, cache_1.getSafeCache)(cacheKey);
+    if (cached)
+        return cached;
+    const provider = (0, web3_1.createProvider)(options.rpcUrl, chainId);
+    const contract = (0, web3_1.createContract)({
+        address: router,
+        provider,
+        abi: abis_1.ABI_SWAP_ROUTER,
+    });
+    if (!contract)
+        return [];
+    // Stage 1 — reconstruct the candidate set from TokenEnabled logs, scanning
+    // the router's lifetime in chunks to respect per-request eth_getLogs limits.
+    const currentBlock = await provider.getBlockNumber();
+    const fromBlock = Math.max(0, options.fromBlock ?? swap_router_1.SWAP_ROUTER_DEPLOY_BLOCKS[chainId] ?? 0);
+    const blockSkip = (0, web3_1.determineBlockSkipInternal)(chainId);
+    const ranges = [];
+    for (let end = currentBlock; end >= fromBlock; end -= blockSkip + 1) {
+        ranges.push({ from: Math.max(end - blockSkip, fromBlock), to: end });
+    }
+    const settled = await Promise.allSettled(ranges.map((r) => contract.queryFilter('TokenEnabled', BigInt(r.from), BigInt(r.to))));
+    const failed = settled.find((s) => s.status === 'rejected');
+    if (failed) {
+        const reason = failed.reason instanceof Error
+            ? failed.reason.message
+            : String(failed.reason);
+        throw new errors_1.AugustSDKError('NETWORK_ERROR', `getSwapRouterWhitelistedTokens: TokenEnabled log scan failed on chain ${chainId}: ${reason}`);
+    }
+    const candidates = new Set();
+    for (const s of settled) {
+        if (s.status !== 'fulfilled')
+            continue;
+        for (const log of s.value) {
+            const raw = log.args?.tokenAddr;
+            if (typeof raw === 'string' && (0, ethers_1.isAddress)(raw)) {
+                candidates.add((0, ethers_1.getAddress)(raw));
+            }
+        }
+    }
+    if (candidates.size === 0) {
+        cache_1.CACHE.set(cacheKey, [], { ttl: SWAP_ROUTER_WHITELIST_TTL_MS });
+        return [];
+    }
+    // Stage 2 — keep only tokens the mapping currently reports as whitelisted.
+    const list = [...candidates];
+    let enabled;
+    if ((0, multicall_1.isMulticall3Supported)(chainId)) {
+        const calls = list.map((token) => ({
+            target: router,
+            abi: abis_1.ABI_SWAP_ROUTER,
+            functionName: 'whitelistedTokens',
+            args: [token],
+        }));
+        const results = await (0, multicall_1.multicall3Aggregate)(provider, chainId, calls);
+        enabled = list.filter((_, i) => results[i]?.success && results[i]?.value === true);
+    }
+    else {
+        const bools = await Promise.all(list.map(async (token) => {
+            try {
+                return (await contract.whitelistedTokens(token));
+            }
+            catch (e) {
+                logger_1.Logger.log.warn('getSwapRouterWhitelistedTokens', `whitelistedTokens(${token}) read failed — omitting`, e);
+                return false;
+            }
+        }));
+        enabled = list.filter((_, i) => bools[i] === true);
+    }
+    cache_1.CACHE.set(cacheKey, enabled, { ttl: SWAP_ROUTER_WHITELIST_TTL_MS });
+    return enabled;
+}
+/** Cache TTL for a chain's resolved SwapRouter eligible-vault set (5 minutes). */
+const SWAP_ROUTER_ELIGIBLE_VAULTS_TTL_MS = 5 * 60 * 1000;
+/**
+ * Minimal `vaultInfo` fragment declaring the four static outputs as a single
+ * named tuple. The ABI encoding of `(uint256,uint8,address,address)` returned
+ * as four values is byte-identical to the same four static types returned as
+ * one tuple, and {@link multicall3Aggregate} surfaces only the FIRST decoded
+ * output — so decoding against this fragment makes that first output the whole
+ * struct, giving batched access to `referenceAsset` (the registration marker)
+ * without changing the shared multicall helper.
+ */
+const ABI_SWAP_ROUTER_VAULT_INFO_TUPLE = [
+    {
+        inputs: [{ internalType: 'address', name: '', type: 'address' }],
+        name: 'vaultInfo',
+        outputs: [
+            {
+                components: [
+                    { internalType: 'uint256', name: 'swapFee', type: 'uint256' },
+                    { internalType: 'uint8', name: 'vaultType', type: 'uint8' },
+                    { internalType: 'address', name: 'referenceAsset', type: 'address' },
+                    { internalType: 'address', name: 'lpTokenAddress', type: 'address' },
+                ],
+                internalType: 'struct SwapRouter.VaultInfo',
+                name: 'info',
+                type: 'tuple',
+            },
+        ],
+        stateMutability: 'view',
+        type: 'function',
+    },
+];
+/**
+ * Extract `referenceAsset` from a decoded `vaultInfo` result (ethers `Result`
+ * proxies expose named tuple components as properties). Returns `undefined`
+ * for anything that doesn't carry a string `referenceAsset` — treated as
+ * unregistered by the caller (fail-closed).
+ */
+function referenceAssetOf(value) {
+    const ref = value
+        ?.referenceAsset;
+    return typeof ref === 'string' ? ref : undefined;
+}
+/**
+ * Resolve the vaults currently eligible for the any-token `SwapRouter` deposit
+ * surface on a chain — i.e. every vault the router has `enableVault`-ed that is
+ * still registered on-chain.
+ *
+ * The router stores registrations as `mapping(address => VaultInfo) vaultInfo`
+ * with **no on-chain enumeration**, so (exactly like
+ * {@link getSwapRouterWhitelistedTokens}) this runs in two stages:
+ *  1. Scan the router's `VaultEnabled(address)` event history (from the chain's
+ *     {@link SWAP_ROUTER_DEPLOY_BLOCKS} floor, in `eth_getLogs` chunks sized by
+ *     {@link determineBlockSkipInternal}) to reconstruct the candidate set of
+ *     every vault ever enabled.
+ *  2. Re-read `vaultInfo(vault)` for each candidate — batched via Multicall3
+ *     where verified, else per-call — and keep only those whose
+ *     `referenceAsset != address(0)` (an unregistered vault reverts with
+ *     `InvalidVault` at deposit time). This makes later disables correct
+ *     without replaying `VaultDisabled`, and is the fail-closed source of
+ *     truth: a vault surfaces only on a definite on-chain registration.
+ *
+ * This is the dynamic successor to the static
+ * {@link SWAP_ROUTER_ELIGIBLE_VAULTS} snapshot / {@link isSwapRouterEligible}.
+ * It reports **on-chain eligibility only** — app-level policy (e.g. excluding
+ * OVault-enabled vaults that have their own deposit flow) remains the caller's
+ * responsibility, as does the flag gating of the UI surface.
+ *
+ * The resolved list is cached per chain for 5 minutes — registrations change
+ * only via an admin `enableVault`/`disableVault` transaction, so a short TTL
+ * keeps the (multi-RPC) scan off the hot path without going stale for long.
+ *
+ * @param chainId - EVM chain ID. Chains without a {@link SWAP_ROUTER_ADDRESSES}
+ *   entry resolve to `[]` with no RPC.
+ * @param options - `rpcUrl` (required) must point at `chainId`'s network;
+ *   `fromBlock` overrides the default deploy-block scan floor.
+ * @returns Checksummed addresses of the currently-registered eligible vaults,
+ *   deduped. Empty when no router is deployed or none are registered.
+ * @throws AugustValidationError when `rpcUrl` is missing/empty.
+ * @throws AugustSDKError when an `eth_getLogs` chunk fails — surfaced (not
+ *   swallowed) so a partial scan never masquerades as the complete set.
+ * @worstCaseRpcCalls On mainnet, 1 `eth_blockNumber` + ~4 `eth_getLogs` chunks
+ *   (router-lifetime ÷ 50k-block window) + 1 Multicall3 `eth_call` ≈ 6; scales
+ *   with the router's on-chain age, not with candidate count.
+ * @example
+ * ```ts
+ * const vaults = await getSwapRouterEligibleVaults(1, {
+ *   rpcUrl: 'https://eth-mainnet.example/v2/KEY',
+ * });
+ * // ['0x74aD…718b', '0xE9B7…9D32']  (Sentora USD, Upshift Core USDC)
+ * ```
+ */
+async function getSwapRouterEligibleVaults(chainId, options) {
+    const router = getSwapRouterAddress(chainId);
+    if (!router)
+        return [];
+    const cacheKey = `swap-router-eligible-vaults-${chainId}-${router.toLowerCase()}`;
+    const cached = await (0, cache_1.getSafeCache)(cacheKey);
+    if (cached)
+        return cached;
+    const provider = (0, web3_1.createProvider)(options.rpcUrl, chainId);
+    const contract = (0, web3_1.createContract)({
+        address: router,
+        provider,
+        abi: abis_1.ABI_SWAP_ROUTER,
+    });
+    if (!contract)
+        return [];
+    // Stage 1 — reconstruct the candidate set from VaultEnabled logs, scanning
+    // the router's lifetime in chunks to respect per-request eth_getLogs limits.
+    const currentBlock = await provider.getBlockNumber();
+    const fromBlock = Math.max(0, options.fromBlock ?? swap_router_1.SWAP_ROUTER_DEPLOY_BLOCKS[chainId] ?? 0);
+    const blockSkip = (0, web3_1.determineBlockSkipInternal)(chainId);
+    const ranges = [];
+    for (let end = currentBlock; end >= fromBlock; end -= blockSkip + 1) {
+        ranges.push({ from: Math.max(end - blockSkip, fromBlock), to: end });
+    }
+    const settled = await Promise.allSettled(ranges.map((r) => contract.queryFilter('VaultEnabled', BigInt(r.from), BigInt(r.to))));
+    const failed = settled.find((s) => s.status === 'rejected');
+    if (failed) {
+        const reason = failed.reason instanceof Error
+            ? failed.reason.message
+            : String(failed.reason);
+        throw new errors_1.AugustSDKError('NETWORK_ERROR', `getSwapRouterEligibleVaults: VaultEnabled log scan failed on chain ${chainId}: ${reason}`);
+    }
+    const candidates = new Set();
+    for (const s of settled) {
+        if (s.status !== 'fulfilled')
+            continue;
+        for (const log of s.value) {
+            const raw = log.args?.vaultAddr;
+            if (typeof raw === 'string' && (0, ethers_1.isAddress)(raw)) {
+                candidates.add((0, ethers_1.getAddress)(raw));
+            }
+        }
+    }
+    if (candidates.size === 0) {
+        cache_1.CACHE.set(cacheKey, [], { ttl: SWAP_ROUTER_ELIGIBLE_VAULTS_TTL_MS });
+        return [];
+    }
+    // Stage 2 — keep only vaults whose current on-chain registration is live
+    // (referenceAsset set). Fail-closed: unreadable/zero → excluded.
+    const list = [...candidates];
+    let registered;
+    if ((0, multicall_1.isMulticall3Supported)(chainId)) {
+        const calls = list.map((vault) => ({
+            target: router,
+            abi: ABI_SWAP_ROUTER_VAULT_INFO_TUPLE,
+            functionName: 'vaultInfo',
+            args: [vault],
+        }));
+        const results = await (0, multicall_1.multicall3Aggregate)(provider, chainId, calls);
+        registered = list.filter((_, i) => {
+            if (!results[i]?.success)
+                return false;
+            const ref = referenceAssetOf(results[i]?.value);
+            return !!ref && ref !== ethers_1.ethers.ZeroAddress;
+        });
+    }
+    else {
+        const refs = await Promise.all(list.map(async (vault) => {
+            try {
+                return referenceAssetOf(await contract.vaultInfo(vault));
+            }
+            catch (e) {
+                logger_1.Logger.log.warn('getSwapRouterEligibleVaults', `vaultInfo(${vault}) read failed — omitting`, e);
+                return undefined;
+            }
+        }));
+        registered = list.filter((_, i) => !!refs[i] && refs[i] !== ethers_1.ethers.ZeroAddress);
+    }
+    cache_1.CACHE.set(cacheKey, registered, { ttl: SWAP_ROUTER_ELIGIBLE_VAULTS_TTL_MS });
+    return registered;
+}
+//# sourceMappingURL=swap-router.js.map

package/lib/core/helpers/vault-version.d.ts

@@ -0,0 +1,23 @@
+import type { ITokenizedVault, IVaultVersion, ChainType } from '../../types';
+/** Classify an address by chain family (evm / solana / stellar / sui). */
+export declare function getAddressChainType(address: string): ChainType;
+/**
+ * Classify a vault's protocol version from its address alone.
+ *
+ * @deprecated Use {@link getVaultVersionV2} instead. This V1 classifier can only
+ * recognise a multi-asset vault (`evm-2`) if its address is hard-coded in the
+ * static `MULTI_ASSET_VAULTS` list. Any multi-asset vault missing from that list
+ * is silently misclassified as `evm-1`, which broke deposit preview/simulation in
+ * the 2026-07-06 Sentora incident. `getVaultVersionV2` reads the backend
+ * `internal_type` (falling back to the static list only as a safety net), so new
+ * vaults classify correctly without a code change. Retained as a non-breaking
+ * shim; scheduled for removal in the next major.
+ *
+ * @param vault - The vault contract address (EVM `0x…`, Solana, or Stellar).
+ * @returns The vault version slug, or `undefined` for empty/invalid input.
+ */
+export declare function getVaultVersion(vault: string): IVaultVersion | undefined;
+export declare function getVaultVersionV2(vault: (Pick<ITokenizedVault, 'address'> & {
+    chain_type?: string;
+    internal_type?: string;
+}) | undefined | null): IVaultVersion | undefined;

package/lib/core/helpers/vault-version.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAddressChainType = getAddressChainType;
+exports.getVaultVersion = getVaultVersion;
+exports.getVaultVersionV2 = getVaultVersionV2;
+const ethers_1 = require("ethers");
+const vaults_1 = require("../constants/vaults");
+const chain_address_1 = require("./chain-address");
+/** Classify an address by chain family (evm / solana / stellar / sui). */
+function getAddressChainType(address) {
+    if ((0, chain_address_1.isStellarAddress)(address))
+        return 'stellar';
+    if ((0, chain_address_1.isSolanaAddress)(address))
+        return 'solana';
+    if ((0, chain_address_1.isSuiAddress)(address))
+        return 'sui';
+    return 'evm';
+}
+/**
+ * Classify a vault's protocol version from its address alone.
+ *
+ * @deprecated Use {@link getVaultVersionV2} instead. This V1 classifier can only
+ * recognise a multi-asset vault (`evm-2`) if its address is hard-coded in the
+ * static `MULTI_ASSET_VAULTS` list. Any multi-asset vault missing from that list
+ * is silently misclassified as `evm-1`, which broke deposit preview/simulation in
+ * the 2026-07-06 Sentora incident. `getVaultVersionV2` reads the backend
+ * `internal_type` (falling back to the static list only as a safety net), so new
+ * vaults classify correctly without a code change. Retained as a non-breaking
+ * shim; scheduled for removal in the next major.
+ *
+ * @param vault - The vault contract address (EVM `0x…`, Solana, or Stellar).
+ * @returns The vault version slug, or `undefined` for empty/invalid input.
+ */
+function getVaultVersion(vault) {
+    if (!vault)
+        return;
+    const chainType = getAddressChainType(vault);
+    if (chainType === 'stellar')
+        return 'stellar-0';
+    if (chainType === 'solana')
+        return 'sol-0';
+    if (!(0, ethers_1.isAddress)(vault))
+        return;
+    if (vaults_1.OLD_LENDING_POOLS.includes((0, ethers_1.getAddress)(vault))) {
+        return 'evm-0';
+    }
+    else if (vaults_1.MULTI_ASSET_VAULTS.includes((0, ethers_1.getAddress)(vault))) {
+        return 'evm-2';
+    }
+    else {
+        return 'evm-1';
+    }
+}
+function getVaultVersionV2(vault) {
+    if (!vault)
+        return;
+    const chainType = getAddressChainType(vault.address);
+    if (vault.chain_type === 'stellar' || chainType === 'stellar')
+        return 'stellar-0';
+    if (vault.chain_type === 'solana' || chainType === 'solana')
+        return 'sol-0';
+    if (!(0, ethers_1.isAddress)(vault.address))
+        return;
+    if (vaults_1.OLD_LENDING_POOLS.includes((0, ethers_1.getAddress)(vault.address))) {
+        return 'evm-0';
+    }
+    else if (vault.internal_type === 'multiAssetVault' ||
+        vaults_1.MULTI_ASSET_VAULTS.includes(vault.address)) {
+        return 'evm-2';
+    }
+    else {
+        return 'evm-1';
+    }
+}
+//# sourceMappingURL=vault-version.js.map

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

@@ -0,0 +1,89 @@
+import type { IAddress, IContractRunner } from '../../types';
+/**
+ * Bad transactions that should be ignored
+ * these transactions are usually from tests and can skew data
+ */
+export declare const isBadTransaction: (hash: string, chainId: number) => boolean;
+export declare const isBadVault: (address?: string) => boolean;
+import { getAddressChainType, getVaultVersion, getVaultVersionV2 } from './vault-version';
+export { getAddressChainType, getVaultVersion, getVaultVersionV2 };
+export declare const REWARD_DISTRIBUTOR_ADDRESS: (chainId: number) => string[];
+export declare const AVAX_PRICE_FEED_ADDRESS: (chainId: number) => "0x" | "0xFF3EEb22B5E3dE6e705b44749C2559d704923FD7";
+export declare function getVaultSymbol(vault: IAddress, provider: IContractRunner): Promise<string | undefined>;
+/**
+ * @deprecated
+ * Replaced by SUBGRAPH_VAULT_URLS which are subgraphs deployed on Goldsky.
+ */
+export declare const SUBGRAPH_POOL_URLS: (apiKey: string, chainId?: number, pool?: IAddress) => {
+    1: string;
+    8453: string;
+    43114: string;
+    42161: string;
+    56: string;
+} | {
+    999: string;
+};
+/**
+ * Previously fabricated a Goldsky subgraph URL from the chain name and vault
+ * symbol. That guess is unreliable and produced dead endpoints:
+ * - The path segment `/v1/subgraphs/name/goldsky/` is legacy hosted-service
+ *   syntax, not Goldsky's current scheme (cf. {@link SUBGRAPH_VAULT_URLS}).
+ * - The chain name isn't the subgraph slug — ethers reports Citrea's network as
+ *   `unknown`, and mainnet as `mainnet` where the subgraph uses `eth`.
+ * - A vault's symbol isn't its subgraph name — e.g. on-chain `EctUSD` vs the
+ *   deployed `earn-ctusd`.
+ *
+ * A fabricated URL 404s silently, so a missing subgraph reads as "no data"
+ * rather than an error (this masked the Citrea Earn ctUSD outage). Subgraph URLs
+ * must now come from backend vault metadata (`fetchVaultMetadata → subgraph`).
+ * This returns `undefined` so callers hit their existing "Missing Subgraph"
+ * branch (warn + Slack alert) instead of querying a dead endpoint.
+ *
+ * @param _network - Unused. Kept for call-site compatibility.
+ * @param _symbol - Unused. Kept for call-site compatibility.
+ * @returns `undefined` — the SDK no longer guesses subgraph URLs.
+ * @deprecated Resolve subgraph URLs from `fetchVaultMetadata`; do not rely on a
+ *   generated fallback.
+ */
+export declare const getDefaultSubgraphUrl: (_network: string, _symbol: string) => string | undefined;
+/**
+ * Resolve whether a single fee (management or performance) is currently waived.
+ *
+ * Backend-driven, per AUGUST-5584. This centralizes logic that previously lived —
+ * and diverged — across two upshift-app components. The resolution is deliberately
+ * split between the backend and the SDK:
+ *
+ * - The backend `isFeeWaivedToggle` (`platform_fee_override.is_fee_waived`) is both
+ *   the master enable AND the TVL latch. Retool config takes precedence over live
+ *   TVL, and the backend flips this flag `false` once live TVL crosses the
+ *   configured threshold. That flip is one-way: if TVL later falls back below the
+ *   threshold the waiver does NOT re-apply. The SDK therefore does no TVL math and
+ *   never reads `latest_reported_tvl` here — trusting the flag preserves the latch.
+ * - The **date** window is time-dependent, so it cannot be a static DB flag; the SDK
+ *   evaluates it live against the clock.
+ *
+ * Resolution:
+ * - Toggle off  → never waived (also the only "hide" path once TVL trips the latch).
+ * - Toggle on, both date and TVL blank → indefinite manual waiver → waived.
+ * - Toggle on with a date window → waived while `now < waivedUntilDate`.
+ * - Toggle on with a TVL threshold configured → waived (the backend keeps the toggle
+ *   on only while live TVL is under the threshold).
+ *
+ * @param isFeeWaivedToggle - Backend master/TVL-latch flag. `false` ⇒ never waived.
+ * @param waivedUntilDate - ISO datetime string the waiver runs until, or `null` for
+ *   no date window. An unparseable string yields `NaN`, which is never `> now`, so
+ *   it correctly contributes no date-based waiver.
+ * @param waivedUntilTvl - Configured TVL threshold in whole USD, or `null`. Used only
+ *   to detect that a TVL-based waiver was set (values `<= 0` are treated as unset);
+ *   the threshold comparison itself is owned by the backend.
+ * @param now - Clock, injected for deterministic testing. Defaults to `new Date()`.
+ * @returns `true` if the UI should present this fee as "Fee Waived" right now.
+ * @example
+ * ```ts
+ * // Toggle on, 30-day window still open → waived.
+ * resolveFeeWaived(true, '2099-01-01T00:00:00Z', null); // true
+ * // Toggle off overrides everything → not waived.
+ * resolveFeeWaived(false, '2099-01-01T00:00:00Z', 10_000_000); // false
+ * ```
+ */
+export declare function resolveFeeWaived(isFeeWaivedToggle: boolean, waivedUntilDate: string | null, waivedUntilTvl: number | null, now?: Date): boolean;