@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/core/constants/core.js

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * Upshift
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FETCH_OPTIONS = exports.WEBSERVER_ENDPOINTS = exports.WEBSERVER_URL = exports.PRICE_SERVER_URL = exports.REQUEST_TIMEOUT_MS = void 0;
+const ethers_1 = require("ethers");
+/**
+ * Build the path segment for a subaccount identifier.
+ *
+ * Why this exists: subaccounts are not EVM-only. Vault operators and loan
+ * borrowers can be Solana base58 keys or Stellar `G…`/`C…` addresses, and the
+ * backend keys those records by their native string form. Calling ethers'
+ * `getAddress()` on them throws `INVALID_ARGUMENT` before the request is ever
+ * made — which is how a Solana borrower turned every
+ * `getVaultAllocations` call for a mixed-chain vault into a
+ * `TypeError: invalid address` (see `getVaultAllocations:cefi` /
+ * `:otc` in Sentry).
+ *
+ * EVM addresses are still checksummed, because the backend expects the
+ * checksummed form for those and case-normalising avoids cache misses.
+ * Everything else is passed through URL-encoded so a malformed value can never
+ * inject extra path segments.
+ *
+ * @param subaccount - Subaccount identifier: EVM hex address, Solana base58
+ *   public key, or Stellar strkey. Not validated beyond the EVM branch — the
+ *   backend is the authority on whether a non-EVM identifier exists.
+ * @returns A single URL path segment safe to interpolate into an endpoint.
+ */
+function subaccountSegment(subaccount) {
+    return (0, ethers_1.isAddress)(subaccount)
+        ? (0, ethers_1.getAddress)(subaccount)
+        : encodeURIComponent(subaccount);
+}
+/**
+ * Default per-request timeout, in milliseconds, for every Upshift HTTP fetcher
+ * (`fetchUpshiftPublic`, `fetchUpshiftWithKey`, `fetchUpshiftWithBearer`).
+ *
+ * Previously 90s. That was longer than any realistic caller was willing to
+ * wait: server-rendered integrations run inside serverless functions whose own
+ * execution budget is well under 90s, so the request had already been abandoned
+ * upstream by the time the abort fired — the timeout only ever garbage-collected
+ * a dead request, while the socket stayed open holding backend capacity and
+ * amplifying the stall for every concurrent caller.
+ *
+ * 15s is above the p99 of a healthy Upshift API response and below every common
+ * upstream budget (Vercel/Lambda defaults, browser patience, upstream gateway
+ * timeouts), so a stalled request now fails fast and frees its connection.
+ *
+ * Callers that genuinely need longer override per-request via
+ * `IFetchUpshiftOptions.timeoutMs`, or process-wide via `setSdkRequestTimeout`.
+ */
+exports.REQUEST_TIMEOUT_MS = 15000;
+exports.PRICE_SERVER_URL = 'https://prices.augustdigital.io';
+exports.WEBSERVER_URL = {
+    production: 'https://backend.fractalprotocol.org',
+    staging: 'https://backend.staging.fractalprotocol.org',
+    development: 'https://backend-dev.augustdigital.io',
+    localhost: 'http://127.0.0.1:8000',
+    qa: 'https://backend-qa.augustdigital.io',
+    public: 'https://api.augustdigital.io/api/v1',
+    upshift: 'https://app.upshift.finance',
+};
+exports.WEBSERVER_ENDPOINTS = {
+    default: {
+        /** @deprecated No backend route. Removed in the next major release. */
+        hello: '/hello',
+        protected: '/protected',
+    },
+    auth: {
+        verify: '/auth/secret',
+        sign: '/auth/sign',
+        login: '/auth/login',
+        nonce: '/auth/nonce',
+        refresh: '/auth/refresh',
+    },
+    subaccount: {
+        list: (offset = 0, limit = 100) => `/subaccount?offset=${offset}&limit=${limit}`,
+        /** @deprecated No backend route. Removed in the next major release. */
+        rewards: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/rewards`,
+        tokens: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/tokens`,
+        twap: {
+            create: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/twap`,
+            stop: (subaccount, id) => `/subaccount/${subaccountSegment(subaccount)}/twap/${id}/stop`,
+            fills: (subaccount, id) => `/subaccount/${subaccountSegment(subaccount)}/twap/${id}/fills`,
+        },
+        debank: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/debank`,
+        health_factor: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/health_factor`,
+        summary: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/summary`,
+        /** @deprecated No backend route. Removed in the next major release. */
+        batch: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/tx_batcher_integrations`,
+        loans: (subaccount, side = 'BOTH', active = true) => `/subaccount/${subaccountSegment(subaccount)}/loans?side=${side}&active=${active}`,
+        cefi: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/cefi_position`,
+        otc_positions: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/otc_positions`,
+        loanByAddress: (loanAddress, chainId) => `/subaccount/loans/${encodeURIComponent(loanAddress)}?chain_id=${chainId}`,
+        _: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}`,
+    },
+    transactions: {
+        v2: (subaccount, startTime, endTime) => {
+            const params = new URLSearchParams({ address: subaccount });
+            if (startTime !== undefined)
+                params.set('start_time', startTime);
+            if (endTime !== undefined)
+                params.set('end_time', endTime);
+            return `/transactions/v2?${params.toString()}`;
+        },
+    },
+    otc: {
+        positions: '/otc/position',
+        marginRequirements: (otcCounterpartyId, payer) => {
+            const params = new URLSearchParams();
+            if (otcCounterpartyId !== undefined)
+                params.set('otc_counter_party_id', otcCounterpartyId);
+            if (payer !== undefined)
+                params.set('payer', payer);
+            const query = params.toString();
+            return `/otc/margin_requirement${query ? `?${query}` : ''}`;
+        },
+    },
+    curator: {
+        vaultSubaccounts: (vaultAddress) => `/curator/vaults/${encodeURIComponent(vaultAddress)}/subaccounts`,
+        vaultWhitelist: (vaultAddress) => `/curator/vaults/${encodeURIComponent(vaultAddress)}/whitelist`,
+    },
+    timelockRequests: (vaultAddress, chainId, status) => {
+        const params = new URLSearchParams({
+            vaultAddress,
+            chainId: String(chainId),
+        });
+        if (status !== undefined)
+            params.set('status', status);
+        return `/timelock-requests?${params.toString()}`;
+    },
+    users: {
+        get: '/users',
+    },
+    dashboard: {
+        loans: '/dashboard/loans',
+    },
+    risk: {
+        discountFactors: '/risk/discount_factors',
+        collateralExcessOrDeficit: (subaccount, tokenAddress, tokenChain, targetHealthFactor) => {
+            const params = new URLSearchParams({
+                address: subaccount,
+                token_address: tokenAddress,
+                token_chain: String(tokenChain),
+            });
+            if (targetHealthFactor !== undefined)
+                params.set('target_health_factor', String(targetHealthFactor));
+            return `/risk/collateral_excess_or_deficit?${params.toString()}`;
+        },
+        collateralSimulation: '/risk/collateral_simulation',
+    },
+    prices: (symbol) => `/prices/${symbol}`,
+    metrics: {
+        pnl: (subaccount, startTime, endTime) => `/metrics/pnl?subaccount_address=${subaccountSegment(subaccount)}${startTime && endTime ? `&start=${startTime}&end=${endTime}` : ''}`,
+        vaultPerformanceFees: (params) => {
+            const q = new URLSearchParams({
+                vault_address: params.vaultAddress,
+                annualized_fees_pct: String(params.annualizedFeesPct),
+                native_denominated: String(params.nativeDenominated),
+                calculation_period: params.calculationPeriod,
+            });
+            if (params.startDate !== undefined)
+                q.set('start_date', params.startDate);
+            if (params.endDate !== undefined)
+                q.set('end_date', params.endDate);
+            return `/metrics/vault_performance_fees?${q.toString()}`;
+        },
+    },
+    public: {
+        integrations: {
+            morpho: {
+                apy: (subaccount, vaultAddress) => `/integrations/morpho/apy?subaccount_address=${subaccountSegment(subaccount)}&vault_address=${(0, ethers_1.getAddress)(vaultAddress)}`,
+            },
+        },
+        tokenizedVault: {
+            loans: (vaultAddress, chainId, active) => `/upshift/lending_pool/loanbook?address=${vaultAddress}&chain=${chainId}&active=${active}`,
+            subaccountLoans: (vaultAddress, chainId, active) => `/upshift/lending_pool/subaccounts_loanbook?address=${vaultAddress}&chain=${chainId}&active=${active}`,
+            list: '/tokenized_vault',
+            byVaultAddress: (vaultAddress) => `/tokenized_vault/${vaultAddress}`,
+            historicalApy: (vaultAddress) => `/upshift/historical_apy/chart?vault_address=${vaultAddress}`,
+            historicalTimeseries: (vaultAddress, nDays) => `/tokenized_vault/${vaultAddress}/historical-timeseries${nDays ? `?n_days=${nDays}` : ''}`,
+            annualizedApy: (vaultAddress) => `/tokenized_vault/annualized_apy/${(0, ethers_1.getAddress)(vaultAddress)}`,
+            summary: (vaultAddress) => `/tokenized_vault/vault_summary/${(0, ethers_1.getAddress)(vaultAddress)}`,
+            withdrawals: (chain, vaultAddress) => `/withdrawals/${chain}/${(0, ethers_1.getAddress)(vaultAddress)}`,
+            debank: (vaultAddress) => `/tokenized_vault/${(0, ethers_1.getAddress)(vaultAddress)}/debank`,
+            octav: (vaultAddress) => `/tokenized_vault/${subaccountSegment(vaultAddress)}/octav`,
+            // Mongo-backed deposit/withdraw history for archived vaults whose
+            // subgraph has been (or will be) retired. See fetchArchivedVaults.
+            userHistory: (vaultAddress, wallet) => `/upshift/vault_history/${(0, ethers_1.getAddress)(vaultAddress)}?wallet=${(0, ethers_1.getAddress)(wallet)}`,
+            // Vaults whose history is served from the snapshot (source of truth for
+            // routing — a vault appears only after its backfill completes).
+            archivedVaults: '/upshift/vault_history/archived',
+        },
+        points: {
+            byUserAddress: (userAddress) => `/upshift/points/${(0, ethers_1.getAddress)(userAddress)}`,
+            register: '/upshift/points/register',
+            leaderboard: '/upshift/points/leaderboard',
+        },
+        vaults: {
+            pendingRedemptions: (vaultAddress) => `/vaults/${vaultAddress}/pending-redemptions`,
+        },
+        pnl: {
+            unrealizedHistory: (vaultAddress, limit) => `/upshift/unrealized_pnl?vault_address=${vaultAddress}${limit !== undefined ? `&limit=${limit}` : ''}`,
+            unrealizedLatest: '/upshift/unrealized_pnl/latest',
+        },
+        revertReason: (txHash, chain) => `/revert_reason?${new URLSearchParams({
+            tx_hash: txHash,
+            chain: String(chain),
+        }).toString()}`,
+        oracleClassification: (vaultAddress, chainId) => `/upshift/oracle_classification/${encodeURIComponent(vaultAddress)}?chain_id=${chainId}`,
+        // Transparency dashboard endpoints (all public, snapshot-backed).
+        transparency: {
+            positions: (vaultAddress, chainId) => `/upshift/positions/${encodeURIComponent(vaultAddress)}?chain_id=${chainId}`,
+            historicalAllocations: (vaultAddress, chainId, startDate, endDate) => {
+                const q = new URLSearchParams({ chain_id: String(chainId) });
+                if (startDate)
+                    q.set('start_date', startDate);
+                // The backend compares `<= end_date` as a datetime, so a bare date
+                // would exclude the whole last day; widen to end-of-day for the
+                // documented inclusive semantics.
+                if (endDate)
+                    q.set('end_date', `${endDate}T23:59:59.999`);
+                return `/upshift/historical_allocations/${encodeURIComponent(vaultAddress)}?${q.toString()}`;
+            },
+            fees: (vaultAddress, chainId) => `/upshift/fees/${encodeURIComponent(vaultAddress)}?chain_id=${chainId}`,
+            ratioSeries: (vaultAddress, startDate, endDate, limit) => {
+                const q = new URLSearchParams({
+                    vault_address: vaultAddress,
+                    fields: 'ratio',
+                });
+                if (startDate)
+                    q.set('start_date', startDate);
+                // See historicalAllocations: widen to end-of-day for inclusive semantics.
+                if (endDate)
+                    q.set('end_date', `${endDate}T23:59:59.999`);
+                if (limit !== undefined)
+                    q.set('limit', String(limit));
+                return `/upshift/unrealized_pnl?${q.toString()}`;
+            },
+            smoothedApy: (vaultAddress, daysAgo, averagingPeriodDays, applySmoothing) => `/upshift/historical_apy/chart?${new URLSearchParams({
+                vault_address: vaultAddress,
+                days_ago: String(daysAgo),
+                averaging_period_in_days: String(averagingPeriodDays),
+                apply_smoothing: String(applySmoothing),
+            }).toString()}`,
+            governanceRoles: (vaultAddress, chainId) => `/upshift/governance/${encodeURIComponent(vaultAddress)}/roles?chain_id=${chainId}`,
+            governancePermissions: (vaultAddress, chainId) => `/upshift/governance/${encodeURIComponent(vaultAddress)}/permissions?chain_id=${chainId}`,
+            governanceTimelocks: (vaultAddress, chainId, status) => {
+                const q = new URLSearchParams({ chain_id: String(chainId) });
+                if (status)
+                    q.set('status', status);
+                return `/upshift/governance/${encodeURIComponent(vaultAddress)}/timelocks?${q.toString()}`;
+            },
+            governanceAuditLog: (vaultAddress, chainId, category, before, limit) => {
+                const q = new URLSearchParams({ chain_id: String(chainId) });
+                if (category)
+                    q.set('category', category);
+                if (before)
+                    q.set('before', before);
+                if (limit !== undefined)
+                    q.set('limit', String(limit));
+                return `/upshift/governance/${encodeURIComponent(vaultAddress)}/audit_log?${q.toString()}`;
+            },
+        },
+    },
+    upshift: {
+        vaults: {
+            metadata: `/api/sdk/vaults-metadata`,
+        },
+    },
+    // TODO: add remaining endpoints
+};
+exports.DEFAULT_FETCH_OPTIONS = {
+    method: 'GET',
+    headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+    },
+};
+//# sourceMappingURL=core.js.map

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

@@ -0,0 +1,180 @@
+import type { IAddress } from '../../types';
+/**
+ * Address of the `SwapRouter` periphery contract on each supported chain.
+ *
+ * Missing keys mean no SwapRouter is deployed on that chain — callers
+ * should fall back to legacy adapter paths.
+ *
+ * @see {@link getSwapRouterAddress} for the typed lookup helper.
+ */
+export declare const SWAP_ROUTER_ADDRESSES: Readonly<Record<number, IAddress>>;
+/**
+ * Human-readable display name of the `SwapRouter` periphery contract on each
+ * supported chain.
+ *
+ * The contract exposes no on-chain name (no `@title` accessor), so UIs that
+ * want to show *which contract* performed the swap-and-deposit — rather than a
+ * bare address — read it from here. Display metadata only: never derive
+ * routing or eligibility logic from it.
+ *
+ * Missing keys mean no SwapRouter is deployed on that chain.
+ *
+ * @see {@link getSwapRouterName} for the typed lookup helper.
+ */
+export declare const SWAP_ROUTER_NAMES: Readonly<Record<number, string>>;
+/**
+ * Vaults whose UI **may offer the any-token SwapRouter deposit surface**
+ * (swap tokens).
+ *
+ * This is *eligibility metadata only*. It is consumed by:
+ *  - the app UI, to decide whether to render the (flag-gated) swap-router
+ *    deposit surface for a vault; and
+ *  - {@link swapRouterDeposit}, optionally, as a fail-fast eligibility check.
+ *
+ * It is deliberately **NOT** read by {@link vaultDeposit}: `vaultDeposit` never
+ * swaps, and uses the SwapRouter only for a direct deposit of an asset the
+ * vault accepts (see `getDepositRoute`). That separation is what
+ * stops a natively-accepted asset from being silently swapped — the
+ * regression that implicit auto-routing caused. Any-token swap
+ * deposits are the explicit, opt-in job of {@link swapRouterDeposit}.
+ *
+ * A listed vault's natively-accepted assets
+ * (for a multi-asset vault, its whole deposit-asset set) still deposit via
+ * `vaultDeposit`; only tokens OUTSIDE that set go through `swapRouterDeposit`.
+ *
+ * Lowercase comparison is required when checking — use
+ * {@link isSwapRouterEligible} rather than reading this set directly.
+ *
+ * @deprecated Superseded by {@link getSwapRouterEligibleVaults}, which reads
+ * the backend `swaps_enabled` flag — so new vaults surface without an SDK
+ * release. This static set stays
+ * functional as the zero-RPC fallback seed (e.g. TanStack Query `initialData`)
+ * and for SDK-internal sync consumers.
+ */
+export declare const SWAP_ROUTER_ELIGIBLE_VAULTS: ReadonlySet<string>;
+/**
+ * @deprecated Renamed to {@link SWAP_ROUTER_ELIGIBLE_VAULTS} (itself now
+ * superseded by {@link getSwapRouterEligibleVaults}, the `swaps_enabled`
+ * resolver), and the semantics changed: this set no longer drives
+ * `vaultDeposit` auto-routing (that branch was removed) — it only marks vaults
+ * whose UI may offer the swap-router deposit surface. Kept as an alias for one
+ * release; migrate to the async resolver.
+ */
+export declare const VAULTS_USING_SWAP_ROUTER: ReadonlySet<string>;
+/**
+ * Block at which each chain's `SwapRouter` was deployed/configured — the safe
+ * lower bound for scanning its `TokenEnabled` log history.
+ *
+ * The router stores its allowlist as `mapping(address => bool) whitelistedTokens`
+ * with no on-chain enumeration, so {@link getSwapRouterWhitelistedTokens} must
+ * reconstruct the candidate set from `TokenEnabled` events before verifying each
+ * against the current mapping. Starting the `eth_getLogs` scan here (rather than
+ * from genesis) bounds it to the router's own lifetime — a few chunks — instead
+ * of the whole chain.
+ *
+ * Each value is the router's deployment block (its first emitted event, the
+ * constructor `OwnershipTransferred`). A too-low value only costs extra empty
+ * log ranges; a value ABOVE the first `TokenEnabled` would silently miss tokens,
+ * so err on the side of earlier.
+ */
+export declare const SWAP_ROUTER_DEPLOY_BLOCKS: Readonly<Record<number, number>>;
+/**
+ * 32-byte origin codes registered on the `SwapRouter` via `addOrigin`.
+ * Drives origin/referral-fee accrual. The on-chain admin must register a
+ * code before it can be used — calls with an unknown code revert with
+ * `InvalidOrigin`.
+ *
+ * `default` is the all-zero sentinel — the SwapRouter treats it as "no
+ * origin fee" and skips the origin-fee transfer.
+ */
+export declare const ORIGIN_CODES: {
+    /** All-zero sentinel — no origin fee. */
+    readonly default: `0x${string}`;
+};
+/**
+ * Shape of a SwapRouter origin code: `0x` followed by exactly 64 hex chars
+ * (a `bytes32`). Shared by every origin-code entry point so the constructor
+ * option, the per-call override and the registration read validate the same
+ * way.
+ * @internal
+ */
+export declare const ORIGIN_CODE_PATTERN: RegExp;
+/**
+ * Chains on which the SDK sends the instance origin code
+ * (`attribution.originCode`). Ethereum mainnet only: it is the one SwapRouter
+ * deployment whose origin registry has been verified. On any other chain the
+ * instance code is never sent, even where a SwapRouter is configured; an
+ * `originCode` passed to a call is still sent.
+ */
+export declare const ORIGIN_ATTRIBUTION_CHAINS: readonly number[];
+/**
+ * Maximum number of swap legs the contract accepts in a single
+ * `swapAndDeposit` call. Mirrors the on-chain `MAX_SWAPS` constant; reading
+ * the on-chain value at call time would add an RPC for no gain.
+ *
+ * Kept here so the SDK can reject oversize inputs at the boundary rather
+ * than wait for the on-chain `TooManySwaps` revert.
+ */
+export declare const SWAP_ROUTER_MAX_SWAPS = 9;
+/**
+ * Wrapped-native ERC-20 per chain that has a SwapRouter deployment. Mirrors
+ * the on-chain `wrappedNativeTokenAddress()` view to avoid an extra RPC on
+ * every dispatch. Used to validate that native-token deposits target a
+ * vault whose reference asset is the wrapped native — the only configuration
+ * the contract's `depositNativeToken` / `swapAndDepositNativeToken` accept.
+ *
+ * **Wrap-only, WETH-vaults-only limitation.** Both payable entry points on the
+ * deployed router (`depositNativeToken` and `swapAndDepositNativeToken`) only
+ * wrap native ETH to this address and deposit — neither has an ETH→other-asset
+ * swap leg. `swapAndDepositNativeToken`'s ABI takes no swap payload, so a DEX
+ * swap is structurally impossible on that path too; its only difference from
+ * `depositNativeToken` is applying the vault swap fee on the pure wrap. The
+ * practical consequence: **native ETH can only be deposited into a vault whose
+ * reference asset is this wrapped-native token** (e.g. a WETH-reference
+ * vault). There is no atomic native-ETH deposit into a non-WETH-reference
+ * vault (e.g. a USDC vault) — deposit the wrapped native token instead
+ * (already whitelisted, and it routes through the swap leg for a vault whose
+ * reference asset differs). True atomic ETH→any-asset support would require a
+ * contract change (a payable `swapAndDeposit` variant), which is out of scope
+ * for this SDK. Use {@link isNativeSwapRouterDepositSupported} to check a
+ * vault's eligibility for the native path before offering it in a UI.
+ */
+export declare const SWAP_ROUTER_WRAPPED_NATIVE: Readonly<Record<number, IAddress>>;
+/**
+ * The DEX aggregator whitelisted on each chain's `SwapRouter` via
+ * `enableRouter`, plus the single aggregator contract method every swap leg is
+ * pinned to and that method's 4-byte selector.
+ *
+ * This is the single source of truth tying the off-chain swap-leg builder to
+ * the on-chain router whitelist. The two MUST agree or `swapAndDeposit` reverts
+ * with `InvalidRouter()` (router not whitelisted) or `InvalidNotWhitelisted()`
+ * (selector not authorized). It is consumed in three places:
+ *
+ * - `dispatchViaSwapRouter` asks {@link fetchSwapQuote} to pin the aggregator to
+ *   `contractMethod`, then asserts the returned quote's `router` and payload
+ *   selector match this entry before broadcasting — failing closed rather than
+ *   letting the user pay gas for a transaction the contract will reject.
+ * - The CI check `scripts/verify-swap-router-aggregator.mjs` asserts the
+ *   deployed `SwapRouter` actually has `tokenTransferProxies[router] != 0` and
+ *   `isAuthorizedSelector(router, selector) == true` for every entry here, so
+ *   config drift is caught at release time, not by a user's failed deposit.
+ *
+ * Pinning to one generic method matters: the aggregator otherwise picks a route
+ * method per quote (e.g. a direct `swapExactAmountInOnUniswapV3`) that varies
+ * with market conditions, producing a different selector each time. Pinning
+ * collapses that to one stable selector so the on-chain whitelist needs only
+ * that selector and never drifts as routing changes.
+ *
+ * `router` is the address the aggregator's calldata targets (ParaSwap v6.2
+ * pulls tokens to the Augustus contract itself, so the SwapRouter's
+ * `tokenTransferProxies[router]` is the router address). `selector` is
+ * `bytes4(keccak256("<contractMethod>(...)"))`. Verify both against the
+ * deployed router before adding a chain — a wrong value reverts at deposit time.
+ */
+export declare const SWAP_ROUTER_DEX_AGGREGATOR: Readonly<Record<number, {
+    router: IAddress;
+    contractMethod: string;
+    selector: `0x${string}`;
+    /** Human-readable aggregator name — for display; never derive routing logic from it. */
+    name: string;
+}>>;

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

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_ATTRIBUTION_CHAINS = exports.ORIGIN_CODE_PATTERN = exports.ORIGIN_CODES = exports.SWAP_ROUTER_DEPLOY_BLOCKS = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS = exports.SWAP_ROUTER_NAMES = exports.SWAP_ROUTER_ADDRESSES = void 0;
+/**
+ * Address of the `SwapRouter` periphery contract on each supported chain.
+ *
+ * Missing keys mean no SwapRouter is deployed on that chain — callers
+ * should fall back to legacy adapter paths.
+ *
+ * @see {@link getSwapRouterAddress} for the typed lookup helper.
+ */
+exports.SWAP_ROUTER_ADDRESSES = {
+    1: '0xC11c6d8fD8FfFB2045d57b149125C44414d8160B',
+    999: '0x1766f1F4C80756c0985ae93E3cf5cA5024bdAE6F',
+};
+/**
+ * Human-readable display name of the `SwapRouter` periphery contract on each
+ * supported chain.
+ *
+ * The contract exposes no on-chain name (no `@title` accessor), so UIs that
+ * want to show *which contract* performed the swap-and-deposit — rather than a
+ * bare address — read it from here. Display metadata only: never derive
+ * routing or eligibility logic from it.
+ *
+ * Missing keys mean no SwapRouter is deployed on that chain.
+ *
+ * @see {@link getSwapRouterName} for the typed lookup helper.
+ */
+exports.SWAP_ROUTER_NAMES = {
+    1: 'Upshift Swap Router',
+    999: 'Upshift Swap Router',
+};
+/**
+ * Vaults whose UI **may offer the any-token SwapRouter deposit surface**
+ * (swap tokens).
+ *
+ * This is *eligibility metadata only*. It is consumed by:
+ *  - the app UI, to decide whether to render the (flag-gated) swap-router
+ *    deposit surface for a vault; and
+ *  - {@link swapRouterDeposit}, optionally, as a fail-fast eligibility check.
+ *
+ * It is deliberately **NOT** read by {@link vaultDeposit}: `vaultDeposit` never
+ * swaps, and uses the SwapRouter only for a direct deposit of an asset the
+ * vault accepts (see `getDepositRoute`). That separation is what
+ * stops a natively-accepted asset from being silently swapped — the
+ * regression that implicit auto-routing caused. Any-token swap
+ * deposits are the explicit, opt-in job of {@link swapRouterDeposit}.
+ *
+ * A listed vault's natively-accepted assets
+ * (for a multi-asset vault, its whole deposit-asset set) still deposit via
+ * `vaultDeposit`; only tokens OUTSIDE that set go through `swapRouterDeposit`.
+ *
+ * Lowercase comparison is required when checking — use
+ * {@link isSwapRouterEligible} rather than reading this set directly.
+ *
+ * @deprecated Superseded by {@link getSwapRouterEligibleVaults}, which reads
+ * the backend `swaps_enabled` flag — so new vaults surface without an SDK
+ * release. This static set stays
+ * functional as the zero-RPC fallback seed (e.g. TanStack Query `initialData`)
+ * and for SDK-internal sync consumers.
+ */
+exports.SWAP_ROUTER_ELIGIBLE_VAULTS = new Set([
+    // Sentora USD — native multi-asset Tokenized Vault V2 (reference asset
+    // USDC). Its native assets (USDC/RLUSD/PYUSD/USDT) deposit via vaultDeposit;
+    // the swap-router surface adds deposits of tokens outside that set.
+    '0x74ad2f789ed583dbd141bbdafc673fe1f033718b',
+]);
+/**
+ * @deprecated Renamed to {@link SWAP_ROUTER_ELIGIBLE_VAULTS} (itself now
+ * superseded by {@link getSwapRouterEligibleVaults}, the `swaps_enabled`
+ * resolver), and the semantics changed: this set no longer drives
+ * `vaultDeposit` auto-routing (that branch was removed) — it only marks vaults
+ * whose UI may offer the swap-router deposit surface. Kept as an alias for one
+ * release; migrate to the async resolver.
+ */
+exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS;
+/**
+ * Block at which each chain's `SwapRouter` was deployed/configured — the safe
+ * lower bound for scanning its `TokenEnabled` log history.
+ *
+ * The router stores its allowlist as `mapping(address => bool) whitelistedTokens`
+ * with no on-chain enumeration, so {@link getSwapRouterWhitelistedTokens} must
+ * reconstruct the candidate set from `TokenEnabled` events before verifying each
+ * against the current mapping. Starting the `eth_getLogs` scan here (rather than
+ * from genesis) bounds it to the router's own lifetime — a few chunks — instead
+ * of the whole chain.
+ *
+ * Each value is the router's deployment block (its first emitted event, the
+ * constructor `OwnershipTransferred`). A too-low value only costs extra empty
+ * log ranges; a value ABOVE the first `TokenEnabled` would silently miss tokens,
+ * so err on the side of earlier.
+ */
+exports.SWAP_ROUTER_DEPLOY_BLOCKS = {
+    1: 26248966,
+    999: 49232457,
+};
+/**
+ * 32-byte origin codes registered on the `SwapRouter` via `addOrigin`.
+ * Drives origin/referral-fee accrual. The on-chain admin must register a
+ * code before it can be used — calls with an unknown code revert with
+ * `InvalidOrigin`.
+ *
+ * `default` is the all-zero sentinel — the SwapRouter treats it as "no
+ * origin fee" and skips the origin-fee transfer.
+ */
+exports.ORIGIN_CODES = {
+    /** All-zero sentinel — no origin fee. */
+    default: '0x0000000000000000000000000000000000000000000000000000000000000000',
+};
+/**
+ * Shape of a SwapRouter origin code: `0x` followed by exactly 64 hex chars
+ * (a `bytes32`). Shared by every origin-code entry point so the constructor
+ * option, the per-call override and the registration read validate the same
+ * way.
+ * @internal
+ */
+exports.ORIGIN_CODE_PATTERN = /^0x[0-9a-fA-F]{64}$/;
+/**
+ * Chains on which the SDK sends the instance origin code
+ * (`attribution.originCode`). Ethereum mainnet only: it is the one SwapRouter
+ * deployment whose origin registry has been verified. On any other chain the
+ * instance code is never sent, even where a SwapRouter is configured; an
+ * `originCode` passed to a call is still sent.
+ */
+exports.ORIGIN_ATTRIBUTION_CHAINS = [1];
+/**
+ * Maximum number of swap legs the contract accepts in a single
+ * `swapAndDeposit` call. Mirrors the on-chain `MAX_SWAPS` constant; reading
+ * the on-chain value at call time would add an RPC for no gain.
+ *
+ * Kept here so the SDK can reject oversize inputs at the boundary rather
+ * than wait for the on-chain `TooManySwaps` revert.
+ */
+exports.SWAP_ROUTER_MAX_SWAPS = 9;
+/**
+ * Wrapped-native ERC-20 per chain that has a SwapRouter deployment. Mirrors
+ * the on-chain `wrappedNativeTokenAddress()` view to avoid an extra RPC on
+ * every dispatch. Used to validate that native-token deposits target a
+ * vault whose reference asset is the wrapped native — the only configuration
+ * the contract's `depositNativeToken` / `swapAndDepositNativeToken` accept.
+ *
+ * **Wrap-only, WETH-vaults-only limitation.** Both payable entry points on the
+ * deployed router (`depositNativeToken` and `swapAndDepositNativeToken`) only
+ * wrap native ETH to this address and deposit — neither has an ETH→other-asset
+ * swap leg. `swapAndDepositNativeToken`'s ABI takes no swap payload, so a DEX
+ * swap is structurally impossible on that path too; its only difference from
+ * `depositNativeToken` is applying the vault swap fee on the pure wrap. The
+ * practical consequence: **native ETH can only be deposited into a vault whose
+ * reference asset is this wrapped-native token** (e.g. a WETH-reference
+ * vault). There is no atomic native-ETH deposit into a non-WETH-reference
+ * vault (e.g. a USDC vault) — deposit the wrapped native token instead
+ * (already whitelisted, and it routes through the swap leg for a vault whose
+ * reference asset differs). True atomic ETH→any-asset support would require a
+ * contract change (a payable `swapAndDeposit` variant), which is out of scope
+ * for this SDK. Use {@link isNativeSwapRouterDepositSupported} to check a
+ * vault's eligibility for the native path before offering it in a UI.
+ */
+exports.SWAP_ROUTER_WRAPPED_NATIVE = {
+    1: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+    999: '0x5555555555555555555555555555555555555555',
+};
+/**
+ * The DEX aggregator whitelisted on each chain's `SwapRouter` via
+ * `enableRouter`, plus the single aggregator contract method every swap leg is
+ * pinned to and that method's 4-byte selector.
+ *
+ * This is the single source of truth tying the off-chain swap-leg builder to
+ * the on-chain router whitelist. The two MUST agree or `swapAndDeposit` reverts
+ * with `InvalidRouter()` (router not whitelisted) or `InvalidNotWhitelisted()`
+ * (selector not authorized). It is consumed in three places:
+ *
+ * - `dispatchViaSwapRouter` asks {@link fetchSwapQuote} to pin the aggregator to
+ *   `contractMethod`, then asserts the returned quote's `router` and payload
+ *   selector match this entry before broadcasting — failing closed rather than
+ *   letting the user pay gas for a transaction the contract will reject.
+ * - The CI check `scripts/verify-swap-router-aggregator.mjs` asserts the
+ *   deployed `SwapRouter` actually has `tokenTransferProxies[router] != 0` and
+ *   `isAuthorizedSelector(router, selector) == true` for every entry here, so
+ *   config drift is caught at release time, not by a user's failed deposit.
+ *
+ * Pinning to one generic method matters: the aggregator otherwise picks a route
+ * method per quote (e.g. a direct `swapExactAmountInOnUniswapV3`) that varies
+ * with market conditions, producing a different selector each time. Pinning
+ * collapses that to one stable selector so the on-chain whitelist needs only
+ * that selector and never drifts as routing changes.
+ *
+ * `router` is the address the aggregator's calldata targets (ParaSwap v6.2
+ * pulls tokens to the Augustus contract itself, so the SwapRouter's
+ * `tokenTransferProxies[router]` is the router address). `selector` is
+ * `bytes4(keccak256("<contractMethod>(...)"))`. Verify both against the
+ * deployed router before adding a chain — a wrong value reverts at deposit time.
+ */
+exports.SWAP_ROUTER_DEX_AGGREGATOR = {
+    // ParaSwap AugustusV6.2 (Velora). `swapExactAmountIn` is the generic
+    // executor method; its selector is 0xe3ead59e.
+    1: {
+        router: '0x6A000F20005980200259B80c5102003040001068',
+        contractMethod: 'swapExactAmountIn',
+        selector: '0xe3ead59e',
+        name: 'ParaSwap',
+    },
+};
+//# sourceMappingURL=swap-router.js.map