@upshiftfinance/sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,542 @@
+"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.getOriginInfo = getOriginInfo;
+exports.readOriginInfo = readOriginInfo;
+exports.readVaultHasSendersWhitelist = readVaultHasSendersWhitelist;
+exports.readSwapRouterPaused = readSwapRouterPaused;
+exports.getSwapRouterWhitelistedTokens = getSwapRouterWhitelistedTokens;
+exports.getSwapRouterEligibleVaults = getSwapRouterEligibleVaults;
+const ethers_1 = require("ethers");
+const swap_router_1 = require("../constants/swap-router");
+const attribution_1 = require("../attribution");
+const abis_1 = require("../../abis");
+const errors_1 = require("../errors");
+const cache_1 = require("../cache");
+const concurrency_1 = require("./concurrency");
+const fetcher_1 = require("../fetcher");
+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);
+ * // '0xC11c6d8fD8FfFB2045d57b149125C44414d8160B'
+ * ```
+ */
+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
+ * (swap tokens). 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 never swaps (see `getDepositRoute` for when it uses the router).
+ *
+ * @param vaultAddress - Upshift vault address.
+ * @returns `true` when the vault is in {@link SWAP_ROUTER_ELIGIBLE_VAULTS}.
+ * @deprecated Superseded by {@link getSwapRouterEligibleVaults}, which resolves
+ * eligibility from the backend `swaps_enabled` flag 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 `swaps_enabled` 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 (an explicit all-zero
+ * sentinel opts one call out), otherwise the SDK instance's
+ * `attribution.originCode` when `chainId` is in
+ * {@link ORIGIN_ATTRIBUTION_CHAINS} (Ethereum mainnet only), 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.
+ * @param chainId - Chain the deposit is sent on. The instance code is never
+ *   returned without it, or on a chain outside
+ *   {@link ORIGIN_ATTRIBUTION_CHAINS}.
+ * @returns The 32-byte origin code to pass to the router.
+ * @throws {@link UpshiftValidationError} when `provided` is not a 32-byte hex string.
+ */
+function resolveOriginCode(provided, chainId) {
+    if (provided === undefined) {
+        const instanceCode = (0, attribution_1.getOriginCode)();
+        return instanceCode &&
+            chainId !== undefined &&
+            swap_router_1.ORIGIN_ATTRIBUTION_CHAINS.includes(chainId)
+            ? instanceCode
+            : swap_router_1.ORIGIN_CODES.default;
+    }
+    if (!swap_router_1.ORIGIN_CODE_PATTERN.test(provided)) {
+        throw new errors_1.UpshiftValidationError('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 UpshiftValidationError} if `signer` has no connected provider.
+ * @worstCaseRpcCalls 1 — a single `getTransactionReceipt` call; decoding is
+ *   local.
+ * @example
+ * ```ts
+ * const hash = await upshiftSdk.evm.swapRouterDeposit({ ... });
+ * const result = await upshiftSdk.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.UpshiftValidationError('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 resolved origin-code, vault and token registrations (5 minutes). */
+const SWAP_ROUTER_ORIGIN_INFO_TTL_MS = 5 * 60 * 1000;
+/**
+ * Read how an origin code is registered on a chain's `SwapRouter`: whether it
+ * exists, its origin fee, and its fee collector.
+ *
+ * Check a partner code with this before configuring it as
+ * `attribution.originCode` — the router reverts every deposit carrying an
+ * unregistered code with `InvalidOrigin`. A code is registered when its
+ * collector is non-zero (`addOrigin` always sets one); a zero-fee code is
+ * still registered but never emits `OriginFeeApplied`. Cached per (chain,
+ * router, code) for 5 minutes.
+ *
+ * @param options - {@link IGetOriginInfoOptions}.
+ * @returns {@link IOriginInfo}; `registered: false` with a zero fee and
+ *   collector, and no RPC, on a chain with no SwapRouter deployment.
+ * @throws {@link UpshiftValidationError} when `originCode` is not a 32-byte hex
+ *   string.
+ * @throws {@link UpshiftSDKError} when the `origins(bytes32)` read fails.
+ * @worstCaseRpcCalls 1 — one `origins(bytes32)` call; none on a cache hit.
+ * @example
+ * ```ts
+ * const info = await getOriginInfo({ chainId: 1, originCode, rpcUrl });
+ * if (!info.registered) throw new Error('origin code is not registered');
+ * ```
+ */
+async function getOriginInfo({ chainId, originCode, rpcUrl, }) {
+    if (!swap_router_1.ORIGIN_CODE_PATTERN.test(originCode)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `getOriginInfo: originCode must be a 32-byte hex string (66 chars incl. 0x), got ${String(originCode).length} chars`, { context: { chainId, expectedLength: 66 } });
+    }
+    try {
+        return await readOriginInfo(chainId, originCode, () => (0, web3_1.createProvider)(rpcUrl, chainId));
+    }
+    catch (e) {
+        if (e instanceof errors_1.UpshiftSDKError)
+            throw e;
+        throw new errors_1.UpshiftSDKError('UNKNOWN', `getOriginInfo failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { chainId } });
+    }
+}
+/**
+ * {@link getOriginInfo} without input validation, reading through a caller
+ * runner (created lazily, only on a cache miss). Shared with the deposit-route
+ * resolver so both hit the same cache entry.
+ * @internal
+ */
+async function readOriginInfo(chainId, originCode, runner) {
+    const unregistered = {
+        registered: false,
+        originFeeBps: 0,
+        collector: ethers_1.ethers.ZeroAddress,
+    };
+    const router = getSwapRouterAddress(chainId);
+    if (!router)
+        return unregistered;
+    const cacheKey = `swap-router-origin-${chainId}-${router.toLowerCase()}-${originCode.toLowerCase()}`;
+    const cached = await (0, cache_1.getSafeCache)(cacheKey);
+    if (cached)
+        return cached;
+    const contract = (0, web3_1.createContract)({
+        address: router,
+        provider: runner(),
+        abi: abis_1.ABI_SWAP_ROUTER,
+    });
+    if (!contract)
+        return unregistered;
+    const [originFee, originFeeCollector] = await contract.origins(originCode);
+    const info = {
+        registered: originFeeCollector !== ethers_1.ethers.ZeroAddress,
+        originFeeBps: Number(originFee),
+        collector: originFeeCollector,
+    };
+    cache_1.CACHE.set(cacheKey, info, { ttl: SWAP_ROUTER_ORIGIN_INFO_TTL_MS });
+    return info;
+}
+/**
+ * Read whether a Tokenized Vault V2 restricts depositors with a senders
+ * whitelist (KYC), cached for 5 minutes like the router reads.
+ *
+ * The v2 SwapRouter accepts any vault, so this is the check that keeps KYC
+ * vaults off the router: such a vault only accepts deposits from whitelisted
+ * senders, so a router deposit either reverts `SenderNotWhitelisted` or, on an
+ * implementation that checks only `msg.sender`, would let any wallet deposit
+ * through a whitelisted router.
+ *
+ * @param runner - Provider or signer used for the read.
+ * @param chainId - Chain the vault is on (part of the cache key).
+ * @param vault - Tokenized Vault V2 address.
+ * @returns `true` when `sendersWhitelistAddress()` is non-zero.
+ * @throws When the `sendersWhitelistAddress()` read fails. Callers wrap it in
+ *   their own error handling.
+ * @worstCaseRpcCalls 1 — one `sendersWhitelistAddress()` call; none on a cache hit.
+ * @internal
+ */
+async function readVaultHasSendersWhitelist(runner, chainId, vault) {
+    const cacheKey = `vault-senders-whitelist-${chainId}-${vault.toLowerCase()}`;
+    const cached = await (0, cache_1.getSafeCache)(cacheKey);
+    if (cached !== null)
+        return cached;
+    const contract = (0, web3_1.createContract)({
+        address: vault,
+        provider: runner,
+        abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+    });
+    const whitelist = (await contract.sendersWhitelistAddress());
+    const hasWhitelist = whitelist !== ethers_1.ethers.ZeroAddress;
+    cache_1.CACHE.set(cacheKey, hasWhitelist, { ttl: SWAP_ROUTER_ORIGIN_INFO_TTL_MS });
+    return hasWhitelist;
+}
+/**
+ * Cache TTL for a SwapRouter's pause state (15 seconds). Far shorter than the
+ * 5-minute TTL of the other router reads: the owner pauses the router to stop
+ * deposits during an incident, so a pause must reach the deposit-route
+ * resolver within seconds. Long enough that the resolver and the router write
+ * it hands off to share one `isPaused()` read.
+ */
+const SWAP_ROUTER_PAUSED_TTL_MS = 15 * 1000;
+/**
+ * Read whether a chain's `SwapRouter` is paused (`isPaused()`), cached for 15
+ * seconds. Every router entry point (`deposit`, `swapAndDeposit`,
+ * `depositNativeToken`) reverts with `ContractIsPaused` while the router is
+ * paused, so callers check this before routing a deposit or sending an
+ * approval to the router.
+ *
+ * @param runner - Contract runner (provider or signer) used for the read.
+ * @param chainId - EVM chain ID.
+ * @returns `true` while the router is paused; `false` when it is not, or on a
+ *   chain with no SwapRouter (no RPC).
+ * @throws When the `isPaused()` read fails. Callers wrap it in
+ *   {@link UpshiftSDKError}.
+ * @worstCaseRpcCalls 1 — one `isPaused()` call; none on a cache hit.
+ * @internal
+ */
+async function readSwapRouterPaused(runner, chainId) {
+    const router = getSwapRouterAddress(chainId);
+    if (!router)
+        return false;
+    const cacheKey = `swap-router-paused-${chainId}-${router.toLowerCase()}`;
+    const cached = await (0, cache_1.getSafeCache)(cacheKey);
+    if (cached !== null)
+        return cached;
+    const contract = (0, web3_1.createContract)({
+        address: router,
+        provider: runner,
+        abi: abis_1.ABI_SWAP_ROUTER,
+    });
+    if (!contract)
+        return false;
+    const paused = (await contract.isPaused()) === true;
+    cache_1.CACHE.set(cacheKey, paused, { ttl: SWAP_ROUTER_PAUSED_TTL_MS });
+    return paused;
+}
+/**
+ * Upper bound on simultaneous `eth_getLogs` chunks during a router log scan.
+ *
+ * The scan covers the router's whole on-chain lifetime in
+ * `determineBlockSkipInternal`-sized windows (10k blocks on mainnet), and the
+ * chunk count grows by one every ~1.4 days of mainnet history. Firing every
+ * chunk at once (`Promise.allSettled` over the full range list) opened an
+ * unbounded number of concurrent requests against a single RPC origin, which
+ * is exactly what triggers provider rate limiting. 8 keeps a cold scan close
+ * to the fully-parallel latency while bounding the burst.
+ */
+const SWAP_ROUTER_LOG_SCAN_CONCURRENCY = 8;
+/** 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 UpshiftValidationError when `rpcUrl` is missing/empty.
+ * @throws UpshiftSDKError when an `eth_getLogs` chunk fails — surfaced (not
+ *   swallowed) so a partial scan never masquerades as a complete allowlist.
+ * @worstCaseRpcCalls 1 `eth_blockNumber` + ⌈(head − deploy block) ÷ window⌉
+ *   `eth_getLogs` chunks + 1 Multicall3 `eth_call`, where `window` is
+ *   {@link determineBlockSkipInternal} (10k blocks on mainnet, 1k on
+ *   HyperEVM). The chunk count grows with the router's on-chain age (on
+ *   mainnet roughly one more chunk every ~1.4 days since the deploy block,
+ *   already in the tens), not with candidate count. Chunks run at most 8 at a
+ *   time, so a cold scan never opens more than 8 concurrent requests.
+ * @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 });
+    }
+    // Bounded fan-out (see SWAP_ROUTER_LOG_SCAN_CONCURRENCY). Each chunk is
+    // settled individually so the result shape matches `Promise.allSettled`;
+    // once one chunk has failed the remaining chunks are skipped rather than
+    // spent, since the scan is thrown away below anyway.
+    let scanFailure;
+    const settled = await (0, concurrency_1.mapWithConcurrency)(ranges, SWAP_ROUTER_LOG_SCAN_CONCURRENCY, async (r) => {
+        if (scanFailure)
+            return scanFailure;
+        const [result] = await Promise.allSettled([
+            contract.queryFilter('TokenEnabled', BigInt(r.from), BigInt(r.to)),
+        ]);
+        if (result.status === 'rejected')
+            scanFailure = result;
+        return result;
+    });
+    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.UpshiftSDKError('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;
+}
+/**
+ * Resolve the vaults that offer the any-token `SwapRouter` deposit surface
+ * (swap tokens) on a chain: every vault the Upshift API marks `swaps_enabled`,
+ * on a chain with a SwapRouter.
+ *
+ * SwapRouter v2 has no on-chain vault registry, so the backend `swaps_enabled`
+ * flag is the source of truth. It fails closed: a vault without the flag, or
+ * with it `false`, is excluded. It only gates swap tokens — a normal deposit
+ * of an asset the vault accepts routes through the router whatever the flag
+ * (see {@link getDepositRoute}).
+ *
+ * App-level policy (e.g. excluding vaults with their own OVault deposit flow)
+ * remains the caller's responsibility.
+ *
+ * @param chainId - EVM chain ID. Chains without a {@link SWAP_ROUTER_ADDRESSES}
+ *   entry resolve to `[]` with no request.
+ * @param _options - Kept for compatibility; `rpcUrl` and `fromBlock` are no
+ *   longer read.
+ * @returns Checksummed addresses of the chain's `swaps_enabled` vaults. Empty
+ *   when no router is deployed or no vault has the flag.
+ * @throws When the Upshift API vault-list request fails.
+ * @worstCaseRpcCalls 0 — one Upshift API request (the vault list, cached for
+ *   15 minutes), no RPC.
+ * @example
+ * ```ts
+ * const vaults = await getSwapRouterEligibleVaults(1);
+ * // ['0x74aD…718b', '0xE9B7…9D32']
+ * ```
+ */
+async function getSwapRouterEligibleVaults(chainId, _options) {
+    if (!getSwapRouterAddress(chainId))
+        return [];
+    const vaults = await (0, fetcher_1.fetchTokenizedVaults)(undefined, undefined, false, false);
+    return vaults
+        .filter((v) => v.chain === chainId && v.swaps_enabled === true && (0, ethers_1.isAddress)(v.address))
+        .map((v) => (0, ethers_1.getAddress)(v.address));
+}
+//# sourceMappingURL=swap-router.js.map

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

@@ -0,0 +1,24 @@
+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, Stellar, or a
+ *   Sui Vault object ID — `0x` + 64 hex chars).
+ * @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,83 @@
+"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, Stellar, or a
+ *   Sui Vault object ID — `0x` + 64 hex chars).
+ * @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 (chainType === 'sui')
+        return 'sui-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 (vault.chain_type === 'sui' || chainType === 'sui')
+        return 'sui-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' ||
+        // Checksum-normalize before the lookup: the list holds checksummed
+        // addresses, and the backend / callers may supply lowercase. `isAddress`
+        // above already guarantees `getAddress` cannot throw here.
+        vaults_1.MULTI_ASSET_VAULTS.includes((0, ethers_1.getAddress)(vault.address))) {
+        return 'evm-2';
+    }
+    else {
+        return 'evm-1';
+    }
+}
+//# sourceMappingURL=vault-version.js.map