@augustdigital/sdk 8.11.0 → 8.13.0

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

@@ -1,4 +1,5 @@
-import type { IAddress } from '../../types';
+import { type Signer, type Wallet } from 'ethers';
+import type { IAddress, ISwapRouterDepositResult, ISwapRouterDepositResultOptions } from '../../types';
 /**
  * Resolve the `SwapRouter` address for a chain.
  *
@@ -11,6 +12,26 @@ import type { IAddress } from '../../types';
  * ```
  */
 export declare function getSwapRouterAddress(chainId: number): IAddress | undefined;
+/**
+ * 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'
+ * ```
+ */
+export declare function getSwapRouterName(chainId: number): string | undefined;
 /**
  * Whether a vault is eligible for the any-token `SwapRouter` deposit surface
  * (the SwapRouter is `enableVault`-ed for it on-chain). Address comparison is
@@ -22,13 +43,20 @@ export declare function getSwapRouterAddress(chainId: number): IAddress | undefi
  *
  * @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.
  */
 export declare function isSwapRouterEligible(vaultAddress: IAddress): boolean;
 /**
- * @deprecated Renamed to {@link isSwapRouterEligible}. 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.
+ * @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.
  */
 export declare const vaultUsesSwapRouter: typeof isSwapRouterEligible;
 /**
@@ -46,3 +74,138 @@ export declare const vaultUsesSwapRouter: typeof isSwapRouterEligible;
  * @throws {@link AugustValidationError} when `provided` is not a 32-byte hex string.
  */
 export declare function resolveOriginCode(provided?: `0x${string}`): `0x${string}`;
+/**
+ * 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
+ * ```
+ */
+export declare function getSwapRouterDepositResult(signer: Signer | Wallet, { txHash, vault }: ISwapRouterDepositResultOptions): Promise<ISwapRouterDepositResult | null>;
+/**
+ * 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)
+ * ```
+ */
+export declare function getSwapRouterWhitelistedTokens(chainId: number, options: {
+    rpcUrl: string;
+    fromBlock?: number;
+}): Promise<IAddress[]>;
+/**
+ * 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)
+ * ```
+ */
+export declare function getSwapRouterEligibleVaults(chainId: number, options: {
+    rpcUrl: string;
+    fromBlock?: number;
+}): Promise<IAddress[]>;

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

@@ -2,10 +2,20 @@
 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.
  *
@@ -20,6 +30,28 @@ const errors_1 = require("../errors");
 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
@@ -31,15 +63,22 @@ function getSwapRouterAddress(chainId) {
  *
  * @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}. 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.
+ * @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;
 /**
@@ -64,4 +103,378 @@ function resolveOriginCode(provided) {
     }
     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

@@ -1,5 +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: ITokenizedVault): IVaultVersion | undefined;
+export declare function getVaultVersionV2(vault: (Pick<ITokenizedVault, 'address'> & {
+    chain_type?: string;
+    internal_type?: string;
+}) | undefined | null): IVaultVersion | undefined;