upshift-config 0.5.14

package/lib/types/vaults.d.ts

@@ -0,0 +1,714 @@
+import type { IAddress, INormalizedNumber, VaultAddress } from './web3';
+import type { IDebankProtocolExposure, IDebankTokenExposure, IOTCPosition, IWSSubaccountCefi, IWSSubaccountLoan, IWSTokenEntry, ITokenizedVaultOperator, ITokenizedVaultEoaOperator, IHIstoricalSnapshot, IApyOverride } from './webserver';
+import type { InterfaceAbi } from 'ethers';
+export interface IVaultLoan {
+    vault: VaultAddress;
+    address: IAddress;
+    lender: IAddress;
+    borrower: IAddress;
+    state: string;
+    totalRepaid: number;
+    principalToken: IWSTokenEntry;
+    principalAmount: number;
+    interestAmount: number;
+    upcomingPayment: {
+        amount: number;
+        dueDate: string;
+    };
+    apr: number;
+    initialPrincipalAmount: number;
+    deployedDate: string;
+    paymentInterval: number;
+    isIdleCapital: boolean;
+    allocation: number;
+}
+/**
+ * One row of borrower-health-factor data for a vault. `health_factor` is
+ * absent when the upstream August backend has no record for `borrower`
+ * (e.g. test loans whose borrower is not a registered subaccount), or when
+ * the per-borrower fetch failed — callers must handle the undefined case
+ * rather than assume a numeric value is present.
+ */
+export interface IVaultBorrowerHealthFactor {
+    borrower: IAddress;
+    loan: IAddress;
+    health_factor?: {
+        datetime: string;
+        health_factor: number;
+        id: string;
+        total_collateral_value: number;
+        total_loan_value: number;
+    };
+}
+export type IVaultUserHistoryItem = {
+    timestamp: number;
+    address: IAddress;
+    amount: INormalizedNumber;
+    pool: IAddress;
+    chainId: number;
+    type: 'withdraw-request' | 'deposit' | 'withdraw-processed' | 'redeem';
+    transactionHash: IAddress;
+    /**
+     * The token address that was actually deposited, when known. Pre-deposit
+     * vaults accept multiple deposit assets (e.g. a sentUSD vault taking RLUSD,
+     * USDC, and USDT), so the vault's own metadata cannot tell a consumer which
+     * asset a given deposit used — only this per-row address can. UIs should
+     * resolve the displayed asset symbol/logo from `assetIn` rather than assuming
+     * the vault's first deposit asset. Absent for single-asset vaults and for
+     * withdraw/redeem rows, where the vault's underlying asset applies.
+     */
+    assetIn?: IAddress;
+    /**
+     * Receipt-token (vault share) amount burned on a withdraw **request**. An
+     * async withdrawal burns shares immediately, but the assets received are not
+     * known until the request settles (share price can drift), so `amount`'s
+     * asset figure is only a preview. UIs rendering a pending request should show
+     * these `shares` with the receipt symbol — the concrete on-chain fact — and
+     * reserve the asset amount for the settled ("processed") row. Present only on
+     * `withdraw-request` items.
+     */
+    shares?: INormalizedNumber;
+};
+/**
+ * A single reward paired with its backend-provided logo.
+ *
+ * `id` is the reward's stable backend identifier ({@link ITokenizedVaultReward.id})
+ * and is the key consumers should join on — it is unique even when two rewards
+ * share a multiplier and text. `label` is display-only: it mirrors the
+ * corresponding {@link IVaultRewards.additionalPoints} string (and so carries a
+ * leading space when `multiplier === 1`, e.g. `" Cores"`), so it is fine to
+ * print but must not be treated as a unique key.
+ *
+ * `imgUrl` is `null` when the backend has no logo for the reward, in which
+ * case consumers fall back to a bundled asset.
+ */
+export type IVaultRewardDetail = {
+    id: string;
+    label: string;
+    text: string;
+    imgUrl: string | null;
+    multiplier: number;
+};
+export type IVaultRewards = {
+    points: string;
+    multiplier: number;
+    multipliers: {
+        value: number;
+        timestamp: number;
+    }[];
+    additionalPoints: string[];
+    /**
+     * Optional so this addition is non-breaking for external code that
+     * constructs an {@link IVaultRewards}. `getVaultRewards` always populates it;
+     * readers should treat an absent value as an empty list.
+     */
+    additionalPointsDetailed?: IVaultRewardDetail[];
+};
+export type IVaultExposureItem = {
+    amount: number;
+    chain: string;
+    decimals: number;
+    exposureType?: string;
+    id: string;
+    logoUrl?: string;
+    name: string;
+    protocol?: string;
+    symbol: string;
+};
+export type IExposurePerCategory = {
+    borrowing: IVaultExposureItem[];
+    supplying: IVaultExposureItem[];
+    lending: IWSSubaccountLoan[];
+    wallet: IVaultExposureItem[];
+    cefiBalance: number;
+    defiBalance: number;
+    walletBalance: number;
+    loanBalance: number;
+};
+/**
+ * @todo clean up to minimize data transfer
+ * ```typescript
+ * {
+ *  defi: IOctavfiPortfolio[]
+ *  cefi: IWSSubaccountCefi[]
+ *  otc: Record<string, IOTCPosition>
+ *  breakdown: { // this will be total net values
+ *    defi: number;
+ *    cefi: number;
+ *    otc: number;
+ *    total: number;
+ *  }
+ * }
+ * ```
+ */
+export interface IVaultAllocations {
+    defi: IDebankProtocolExposure[];
+    tokens: IDebankTokenExposure[];
+    cefi: IWSSubaccountCefi[];
+    unfilteredTokens: IDebankTokenExposure[];
+    otc: Record<string, IOTCPosition>;
+    exposurePerCategory?: IExposurePerCategory;
+    netValue?: number;
+    defiPerBorrower: Record<`0x${string}`, {
+        exposure: any[];
+        positions: any[];
+    }>;
+}
+/**
+ * A vault's APY breakdown.
+ *
+ * **Unit contract: every rate on this type is a PERCENTAGE, not a decimal
+ * fraction.** `7.95` means 7.95%. The backend reports these as decimal fractions
+ * (`0.0795`); the SDK multiplies by 100 exactly once, uniformly across every rate
+ * field, before returning them. Consumers must therefore divide by 100 at most once
+ * — and must apply the same treatment to `apy`, `liquidApy`, `pointsApy`,
+ * `campaignApy` and `underlyingApy`, because they all arrive in the same unit.
+ *
+ * This is stated explicitly because the convention going undocumented let a
+ * consumer scale a subset of these fields twice, making them contribute 1/100th of
+ * their value to a displayed total (AUGUST-6967). The unit is uniform here by
+ * design; treating some of these fields as decimals and others as percentages is
+ * always a bug on the consumer side.
+ */
+export interface IVaultApy {
+    /** Base vault APY as a percentage (7.95 = 7.95%). */
+    apy: number;
+    /** Human-readable note on how the APY is derived; empty or null when unset. */
+    explainer: string;
+    /** Liquid-yield component as a percentage. */
+    liquidApy: number;
+    /** Points-program APY as a percentage, or null when the vault has no points. */
+    pointsApy: number | null;
+    /** Campaign-boost APY as a percentage, or null when no campaign is running. */
+    campaignApy: number | null;
+    /** Claimable rewards, in the reward token's own units — not a percentage. */
+    rewardsClaimable: number;
+    /** Compounded rewards, in the reward token's own units — not a percentage. */
+    rewardsCompounded: number;
+    /** Underlying-asset APY as a percentage (e.g. staking yield on the deposit asset). */
+    underlyingApy: number;
+}
+export interface IVaultStrategist {
+    address: IAddress;
+    logo: string;
+    name: string;
+    type?: string;
+    website_url: string | null;
+}
+export type IVaultVersion = 'evm-0' | 'evm-1' | 'evm-2' | 'sol-0' | 'sui-0' | 'stellar-0';
+export type { ChainType } from './web3';
+/**
+ * Adapter configuration for vaults that support deposits with alternative tokens
+ */
+export interface IVaultAdapterConfig {
+    lpTokenAddress?: IAddress;
+    isNativeTokenDeposit: boolean;
+    isWrappedTokenDeposit: boolean;
+    wrappedTokenAddress?: IAddress;
+    referralId?: IAddress | string;
+    abi?: InterfaceAbi;
+    wrapperAddress?: IAddress;
+    viewAdapter?: IAddress;
+    tokens?: IAddress[];
+    bridgeId?: number;
+}
+/**
+ * Provenance timestamps for a vault's server-side data, mapped from the backend
+ * `freshness` object.
+ *
+ * A vault's share price and its APY come from two different pipelines: the SDK
+ * reads share price live from chain (`totalAssets()/totalSupply()`), while APY is a
+ * backend column recomputed on a schedule. These stamps make the remaining gap
+ * visible so a UI can render "data as of X" instead of implying both numbers are
+ * equally current.
+ *
+ * The three fields are **independently nullable and independently meaningful** —
+ * none of them is a fallback for another. In particular, when
+ * `shareRatioSnapshotAt` is later than `apyComputedAt`, a share-price snapshot has
+ * landed that the APY has not yet been recomputed from: that ordering is the
+ * staleness signal.
+ *
+ * Every value is an RFC 3339 UTC string with a trailing `Z`, exactly as the backend
+ * sends it — the SDK does not reformat or reinterpret them. Keep the `Z` if you
+ * pass these anywhere: `new Date('2026-07-25T00:01:46')` (no `Z`) is parsed as
+ * *local* time and silently shifts by the viewer's UTC offset.
+ *
+ * @example
+ * ```ts
+ * const vault = await sdk.vaults.getVault(address);
+ * const { apyComputedAt, shareRatioSnapshotAt } = vault.freshness ?? {};
+ * // Only comparable when BOTH are present.
+ * const apyLagsSharePrice =
+ *   !!apyComputedAt &&
+ *   !!shareRatioSnapshotAt &&
+ *   new Date(shareRatioSnapshotAt) > new Date(apyComputedAt);
+ * ```
+ */
+export interface IVaultFreshness {
+    /**
+     * When the backend last recomputed `historical_apy`, TVL and drawdown for this
+     * vault. Null if never computed.
+     */
+    apyComputedAt: string | null;
+    /**
+     * Timestamp of the newest persisted share-price snapshot the backend holds. Null
+     * only when the vault has no snapshot yet.
+     *
+     * Populated regardless of whether the read loaded snapshots — the backend stamps
+     * it from a scalar `max(snapshot_datetime)`, so it is present even on
+     * `load_snapshots=false` reads (the basic and sub-accounts views). When it is
+     * null, treat it as absent: do not fall back to `apyComputedAt` or `cachedAt` in
+     * its place.
+     */
+    shareRatioSnapshotAt: string | null;
+    /**
+     * When the backend assembled the response body this vault came from, before its
+     * own response cache. Note this does **not** account for the SDK's client-side
+     * LRU (10–15 min on `fetchTokenizedVault` / `fetchTokenizedVaults`), so a vault
+     * served from that cache can be older than this stamp suggests is possible.
+     */
+    cachedAt: string | null;
+}
+export interface IVault {
+    max_drawdown?: number | null;
+    historical_apy?: Record<number, number> | null;
+    /**
+     * Compound-annualized historical APY keyed by horizon in days (1/7/30), as
+     * decimal fractions. Same shape and per-horizon null semantics as
+     * `historical_apy`. Display is opted in per vault via
+     * `apyOverride.is_show_compound_apy`; absent on older/cached responses.
+     */
+    historical_compound_apy?: Record<number, number> | null;
+    /** @deprecated Use getVaultHistoricalTimeseries instead */
+    historical_snapshots?: IHIstoricalSnapshot[];
+    depositCap?: INormalizedNumber;
+    maxDepositAmount?: INormalizedNumber;
+    /**
+     * Vault contract address. May be an EVM hex address, Solana base58 address,
+     * or Stellar base32 address depending on the vault's chain.
+     */
+    address: VaultAddress;
+    chainId: number;
+    name: string;
+    logoUrl: string;
+    receipt: {
+        address: VaultAddress;
+        symbol: string;
+        decimals: number;
+    };
+    description: string;
+    startDatetime: string;
+    status: 'active' | 'closed' | 'testing';
+    version: IVaultVersion;
+    tags: string[];
+    isFeatured: boolean;
+    isSpotlighted?: boolean;
+    withdrawalOnly?: boolean;
+    isVisible: boolean;
+    reserveTarget: number;
+    reserveTolerance: number;
+    decimals: number;
+    totalAssets: INormalizedNumber;
+    totalSupply: INormalizedNumber;
+    maxSupply: INormalizedNumber;
+    operators: ITokenizedVaultOperator[];
+    eoa_operators: ITokenizedVaultEoaOperator[];
+    depositAssets: {
+        address: VaultAddress;
+        symbol: string;
+        decimals: number;
+    }[];
+    apy: IVaultApy;
+    operator: IAddress;
+    rewards: IVaultRewards;
+    strategists: IVaultStrategist[];
+    fees: {
+        management: number;
+        isManagementWaived: boolean;
+        managementFeeWaivedUntilDate: string | null;
+        managementFeeWaivedUntilTvl: number | null;
+        performance: number;
+        isPerformanceWaived: boolean;
+        performanceFeeWaivedUntilDate: string | null;
+        performanceFeeWaivedUntilTvl: number | null;
+    };
+    lagDuration: number;
+    /**
+     * Backend-configured display buffer in seconds added on top of
+     * `lagDuration` for the withdrawal period shown to users. Null when the
+     * backend has not set a value — consumers apply their own default.
+     */
+    withdrawalMarginSeconds?: number | null;
+    /**
+     * IAT trader wallet addresses for the vault, from the backend
+     * `iat_traders` field. Address format follows the vault's chain
+     * (EVM hex / Solana base58 / Stellar). Null when not configured.
+     */
+    iatTraders?: string[] | null;
+    maxDailyDrawdown: number;
+    risk: string;
+    isWithdrawalPaused: boolean;
+    isDepositPaused: boolean;
+    idleAssets: INormalizedNumber;
+    loans?: IVaultLoan[];
+    allocations?: IVaultAllocations;
+    position?: IVaultPosition;
+    linkOnly?: boolean;
+    composabilityIntegrations?: Array<{
+        name: string;
+        description: string;
+        earningMultiplier: number;
+        protocolUrl: string;
+        logoUrl: string;
+        tokenizedVaultId: string;
+        id: string;
+    }>;
+    dailyPnlPerShare?: {
+        timestamp: string;
+        value: number;
+    }[];
+    enabled_historical_price_horizons?: number[];
+    defaultApyHorizon?: 7 | 30 | null;
+    latest_reported_tvl?: number | null;
+    cachedAt?: string | null;
+    /**
+     * Provenance timestamps for the vault's server-side data — when its APY was last
+     * recomputed, when its newest share-price snapshot was taken, and when the
+     * backend built the response. Null (or a null member) when the backend did not
+     * report that stamp; see {@link IVaultFreshness}.
+     */
+    freshness?: IVaultFreshness | null;
+    showCapFilled?: boolean | null;
+    /** Controls how the vault's APY is displayed; null when the backend has not set an override. */
+    apyOverride?: IApyOverride | null;
+    programId?: string;
+    /** Instant redemption config, populated from backend instant_redeem_config */
+    instant_redeem_config?: {
+        subaccountAddress: IAddress;
+        outputAssetSymbol: string;
+        redeemableAssets: Array<{
+            address: IAddress;
+            symbol: string;
+            decimals: number;
+            spreadBps: number;
+        }>;
+        isPaused: boolean;
+        availableLiquidity: number;
+    } | null;
+}
+export declare enum VaultRedemptionStatus {
+    AWAITING_COOLDOWN = "awaiting_cooldown",
+    READY_TO_CLAIM = "ready_to_claim"
+}
+export type IVaultAvailableRedemption = {
+    id: string;
+    hash: string;
+    timestamp: number;
+    receiver: IAddress;
+    day: INormalizedNumber;
+    month: INormalizedNumber;
+    year: INormalizedNumber;
+    amount: INormalizedNumber;
+    date: Date;
+    vault: IAddress;
+    status?: VaultRedemptionStatus;
+};
+export type IVaultRedemptionHistoryItem = {
+    receiver: IAddress;
+    amount: INormalizedNumber;
+    processed: Date;
+    requested: Date;
+    vault: IAddress;
+    transactionHash?: string;
+};
+export interface IVaultPosition {
+    vault: VaultAddress;
+    status: string;
+    availableRedemptions: IVaultAvailableRedemption[];
+    pendingRedemptions: IVaultAvailableRedemption[];
+    redeemable: INormalizedNumber;
+    walletBalance: INormalizedNumber;
+}
+export type IVaultOrderParam = 'asc' | 'desc';
+export type IVaultHistoricalParams = {
+    daysAgo?: number;
+    order?: IVaultOrderParam;
+    interval?: 'days' | 'weeks' | 'months' | 'years';
+};
+export interface IVaultUserLifetimePnl {
+    tokenSymbol: string;
+    totalDeposited: INormalizedNumber;
+    totalDepositedUsd: number;
+    totalWithdrawn: INormalizedNumber;
+    totalWithdrawnUsd: number;
+    currentPositionValue: INormalizedNumber;
+    currentPositionValueUsd: number;
+    lifetimePnl: INormalizedNumber;
+    lifetimePnlUsd: number;
+    pnlPercentage: number;
+}
+export interface IVaultPnl {
+    totalPnl: INormalizedNumber;
+    pnlUsd: number;
+}
+/**
+ * Response for GET /tokenized_vault/annualized_apy/{vault_address}
+ *
+ * Supported Vaults: cUSDO, tETH, wstETH, rsETH
+ *
+ * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` fields are deprecated.
+ * These fields will be removed on 2026-01-01.
+ * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
+ */
+export interface IVaultAnnualizedApy {
+    vaultAddress: IAddress;
+    liquidityApy: number;
+    annualizedApy: number;
+    /** @deprecated Use `liquidAPY7Day` instead. Will be removed on 2026-01-01. */
+    hgETH7dLiquidAPY?: number;
+    /** @deprecated Use `liquidAPY30Day` instead. Will be removed on 2026-01-01. */
+    hgETH30dLiquidAPY?: number;
+    liquidAPY7Day?: number;
+    liquidAPY30Day?: number;
+}
+/**
+ * Response for GET /tokenized_vault/vault_summary/{vault_address}
+ */
+export interface IVaultSummary {
+    vaultAddress: IAddress;
+    name: string;
+    type: string;
+    chain: string;
+    recentReturns: {
+        day: number;
+        week: number;
+        month: number;
+    };
+}
+/**
+ * Response for GET /withdrawals/{chain}/{vault_address}
+ */
+export interface IVaultWithdrawals {
+    vaultAddress: IAddress;
+    chain: string;
+    totalWithdrawals: INormalizedNumber;
+    pendingQueue: Array<{
+        id: string;
+        amount: INormalizedNumber;
+        requestedAt: string;
+        estimatedCompletionDate: string;
+        receiver: IAddress;
+    }>;
+}
+/**
+ * Response for GET /vaults/\{vault_addr\}/pending-redemptions
+ */
+export interface IVaultPendingRedemptions {
+    vault: {
+        address: string;
+        chainId: number;
+        name: string | null;
+        symbol: string | null;
+    };
+    asset: {
+        address: string;
+        symbol: string | null;
+        decimals: number | null;
+    };
+    liquidity: {
+        available: number;
+    };
+    summary: {
+        totalPending: number;
+        pendingCount: number;
+        pendingToLiquidityRatio: number | null;
+        isLiquiditySufficient: boolean;
+        shortfall: number | null;
+        nextRedemptionDate: string | null;
+        isOverdue: boolean;
+    };
+    redemptionsByDate: Array<{
+        date: string;
+        assets: number;
+        daysUntilDue: number;
+        isOverdue: boolean;
+    }>;
+}
+/**
+ * One unrealized-PnL snapshot for a vault, computed by the August backend
+ * from periodic vault state. `timestamp` is an ISO-8601 datetime; monetary
+ * fields are denominated in the vault's reference asset
+ * (`referenceAsset`) except `assetPrice`, which is the asset's USD price.
+ */
+export type IUnrealizedPnlSnapshot = {
+    timestamp: string;
+    vaultName: string;
+    vaultAddress: string;
+    strategistName: string | null;
+    referenceAsset: string;
+    assetPrice: number;
+    tvlOnVault: number;
+    currentRedeemRatio: number;
+    actualTvl: number;
+    adjustedRedeemRatio: number;
+    unrealizedPnl: number;
+    unrealizedPnlInAsset: number;
+};
+/**
+ * Vault metadata item from upshift API
+ */
+export interface IVaultMetadataItem {
+    symbol: string;
+    subgraph: string;
+    address: string;
+}
+/**
+ * Response type for getVaultMetadata
+ * Keys are lowercase of the symbol value
+ */
+export type IVaultMetadata = Record<string, IVaultMetadataItem>;
+/**
+ * Numeric vault-type tag used by the on-chain `SwapRouter` to branch between
+ * the ERC-4626 (`deposit(uint256, address)`) and multi-asset
+ * (`deposit(address, uint256, address)`) deposit interfaces.
+ *
+ * Values match the contract's `VAULT_TYPE_ERC4626` / `VAULT_TYPE_TOKENIZED_VAULT_V2`
+ * constants exactly. Set by an admin per-vault via `enableVault` and looked
+ * up via `vaultInfo(vaultAddr).vaultType`. SDK callers normally do not pass
+ * this — the router resolves it internally.
+ */
+export declare enum SwapRouterVaultType {
+    ERC4626 = 1,
+    TokenizedVaultV2 = 2
+}
+/**
+ * One swap leg passed to `SwapRouter.swapAndDeposit`.
+ *
+ * The router pulls `amountIn` of `tokenIn` from the caller, approves the
+ * configured `tokenTransferProxies[router]` address, and calls `router` with
+ * `payload`. Output is measured by balance-diff and must clear `minAmountOut`
+ * or the call reverts with `SlippageError`.
+ *
+ * For a single-hop swap, `tokenOut` is typically the vault's reference asset.
+ * For multi-hop, intermediate legs use any whitelisted token.
+ */
+export interface ISwapParams {
+    /** ERC-20 address pulled from the caller. Must be whitelisted via `whitelistedTokens`. */
+    tokenIn: IAddress;
+    /** ERC-20 address the router is expected to produce. */
+    tokenOut: IAddress;
+    /** Input amount in `tokenIn`'s smallest unit (no decimals). */
+    amountIn: bigint;
+    /** Minimum acceptable `tokenOut` output. Below this the call reverts. */
+    minAmountOut: bigint;
+    /** Whitelisted DEX router target (enabled via `enableRouter`). */
+    router: IAddress;
+    /** ABI-encoded calldata to invoke on `router`. */
+    payload: `0x${string}`;
+}
+/**
+ * Common options shared by every public SwapRouter SDK method.
+ */
+export interface ISwapRouterBaseOptions {
+    /** EVM chain ID — must have an entry in `SWAP_ROUTER_ADDRESSES`. */
+    chainId: number;
+    /** August vault address. Must be registered via `enableVault` on the router. */
+    vault: IAddress;
+    /** Address that receives the minted vault shares. */
+    receiver: IAddress;
+    /**
+     * 32-byte origin/referral code registered via `addOrigin`. Drives the
+     * origin-fee accrual. Defaults to {@link ORIGIN_CODES.default} when omitted.
+     */
+    originCode?: `0x${string}`;
+    /** When `true`, the helper awaits a single confirmation before returning. */
+    wait?: boolean;
+}
+/**
+ * Options for `swapAndDeposit` — ERC-20 in, vault reference asset out.
+ */
+export interface ISwapAndDepositOptions extends ISwapRouterBaseOptions {
+    /** One or more swap legs. Capped by the contract's `MAX_SWAPS`. */
+    swaps: ISwapParams[];
+}
+/**
+ * Options for `depositViaSwapRouter` — direct deposit (no swap) of an
+ * already-held asset, routed through the SwapRouter so origin/swap-fee
+ * accounting still applies.
+ */
+export interface ISwapRouterDirectDepositOptions extends ISwapRouterBaseOptions {
+    /** Deposited ERC-20 asset. For ERC-4626 vaults this must equal the reference asset. */
+    asset: IAddress;
+    /** Amount in `asset`'s smallest unit. */
+    amount: bigint;
+}
+/**
+ * Options for `depositNativeViaSwapRouter` — wraps `msg.value` to the
+ * chain's wrapped-native token and deposits. Only valid when the vault's
+ * reference asset equals `wrappedNativeTokenAddress`.
+ */
+export interface ISwapRouterNativeDepositOptions extends ISwapRouterBaseOptions {
+    /** Native token amount in wei. Sent as `msg.value`. */
+    amount: bigint;
+}
+/**
+ * Options for {@link swapRouterDeposit} — the high-level, explicit SwapRouter
+ * deposit entry point. It reads the vault's reference asset and decimals
+ * on-chain, then picks the correct router path from `depositAsset`, so callers
+ * do not hand-build swap legs or pre-resolve decimals themselves.
+ *
+ * Prefer this over relying on the implicit routing inside `vaultDeposit`: here
+ * the caller opts into the SwapRouter deliberately, so a vault is never
+ * silently routed through a swap it does not need — the failure mode that broke
+ * native multi-asset deposits when a multi-asset vault was added to
+ * `VAULTS_USING_SWAP_ROUTER`.
+ *
+ * Unlike {@link ISwapRouterBaseOptions}, `receiver` is optional here and
+ * defaults to the signer's resolved EOA.
+ */
+export interface ISwapRouterDepositOptions extends Omit<ISwapRouterBaseOptions, 'receiver'> {
+    /**
+     * Token being deposited, held by the signer. Its relationship to the vault's
+     * reference asset selects the router path:
+     *  - equals the reference asset → direct router deposit (no swap);
+     *  - the zero address → native-token deposit (only when the reference asset
+     *    is the chain's wrapped-native token);
+     *  - any other ERC-20 → a swap to the reference asset via the chain's
+     *    whitelisted DEX aggregator, bundled into the deposit.
+     */
+    depositAsset: IAddress;
+    /** Amount in `depositAsset`'s smallest unit (decimal string or bigint). */
+    amount: string | bigint;
+    /** Address that receives the minted shares. Defaults to the signer's EOA. */
+    receiver?: IAddress;
+    /**
+     * Max slippage in basis points for the swap leg. Only used when `depositAsset`
+     * differs from the reference asset; passed through to the swap quote, whose
+     * own default applies when omitted.
+     */
+    slippageBps?: number;
+}
+/**
+ * Options for {@link getSwapRouterDepositResult} — resolves the real,
+ * post-execution outcome of a SwapRouter deposit from its mined transaction
+ * receipt, rather than the pre-trade quote shown before submission.
+ */
+export interface ISwapRouterDepositResultOptions {
+    /** Hash of a mined SwapRouter deposit transaction (e.g. from {@link swapRouterDeposit}). */
+    txHash: string;
+    /** The vault that was deposited into — isolates its own `Deposit` event from the router's unrelated logs. */
+    vault: IAddress;
+}
+/**
+ * Real, on-chain outcome of a SwapRouter deposit, decoded from the vault's own
+ * `Deposit` event (the SwapRouter contract itself emits no deposit/amount-out
+ * event — see {@link getSwapRouterDepositResult}). For a swap deposit this is
+ * the actual post-swap amount that reached the vault, which can differ from
+ * the pre-trade quote a UI shows before the user submits.
+ */
+export interface ISwapRouterDepositResult {
+    /** Raw amount of the vault's reference asset recorded as deposited (reference-asset decimals). */
+    amountOut: bigint;
+    /** Raw vault shares minted to the receiver (share-token decimals). */
+    sharesOut: bigint;
+}