@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/types/vaults.d.ts

@@ -0,0 +1,886 @@
+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 Upshift 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;
+    /** DeBank `pool.id` of the portfolio item the token belongs to — tells
+     * apart two positions in the same protocol holding the same token. */
+    poolId?: 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;
+ *  }
+ * }
+ * ```
+ */
+/**
+ * How far a Solana vault's allocations fall short of its on-chain AUM.
+ *
+ * Portfolio indexers miss positions (Octav once skipped ~$1M of Kamino Multiply
+ * obligations for one vault), and nothing else in {@link IVaultAllocations}
+ * would show it. All values are USD, and they add up:
+ * `defiBalance + walletBalance + cefiBalance + idleUsd + usd === onChainAumUsd`,
+ * with the balances from `exposurePerCategory`.
+ */
+export interface IVaultUnattributed {
+    /**
+     * On-chain deployed AUM minus the allocations' total. Signed and not
+     * thresholded: positive is value no allocation accounts for, such as a
+     * protocol the indexer doesn't cover; negative is double counting or a
+     * mispriced token. A small value either way is price drift between the
+     * indexer's read and the chain, so apply a display floor of your own.
+     */
+    usd: number;
+    /** The vault's on-chain AUM (`local_aum + deployed_aum`), read fresh. */
+    onChainAumUsd: number;
+    /**
+     * What the vault program itself holds (`local_aum`). It sits with no
+     * operator, so no allocation covers it; show it as its own slice.
+     */
+    idleUsd: number;
+}
+export interface IVaultAllocations {
+    defi: IDebankProtocolExposure[];
+    /**
+     * The vault's asset composition, in USD (`amount` is a dollar value).
+     *
+     * On Stellar this is Untangled's `byAsset` breakdown, which decomposes the
+     * same `tvlUsd` that `defi` does along a different axis — assets rather than
+     * venues. The two do not join: which venue holds which asset is not published,
+     * so this is the only place a Stellar vault's assets are stated, and reading a
+     * per-venue asset split out of `exposurePerCategory` is not supported for
+     * multi-asset Stellar vaults.
+     */
+    tokens: IDebankTokenExposure[];
+    cefi: IWSSubaccountCefi[];
+    unfilteredTokens: IDebankTokenExposure[];
+    otc: Record<string, IOTCPosition>;
+    exposurePerCategory?: IExposurePerCategory;
+    netValue?: number;
+    /**
+     * Solana vaults only: the gap between the allocations and the vault's
+     * on-chain AUM. Absent for other chains, and for a Solana vault whose state
+     * or deposit-token price could not be read.
+     */
+    unattributed?: IVaultUnattributed;
+    defiPerBorrower: Record<`0x${string}`, {
+        /**
+         * De-duplicated exposure rows: `value` is a token id or pool controller,
+         * `label` its symbol or adapter id, `usd` the summed USD value.
+         */
+        exposure: {
+            value: string;
+            label: string;
+            usd: number;
+        }[];
+        /** Protocols the borrower has positions in: `value` is the logo URL. */
+        positions: {
+            value: string;
+            label: string;
+        }[];
+    }>;
+}
+/**
+ * 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. 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;
+    /**
+     * Wrapper vaults only: the vault this one wraps, which holds the assets. A
+     * wrapper's own on-chain `totalAssets` reads 0, so its TVL is the underlying
+     * vault's. Null on a non-wrapper vault. Address casing is preserved verbatim.
+     */
+    underlyingVaultAddress?: VaultAddress | null;
+    /** Chain id of {@link IVault.underlyingVaultAddress}; null on a non-wrapper vault. */
+    underlyingChainId?: 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;
+    /**
+     * Solana only: the vault's withdrawal queue, when it has one. Absent for
+     * other chains and for Solana vaults that never had a queue. See
+     * {@link IVaultWithdrawalQueue}.
+     */
+    withdrawalQueue?: IVaultWithdrawalQueue;
+    /** 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",
+    /**
+     * Solana withdrawal queue only: the request's fulfillment window has closed.
+     * It can no longer be claimed, only cancelled, which returns its shares.
+     */
+    EXPIRED = "expired"
+}
+/**
+ * A Solana vault's withdrawal queue, as `IVault.withdrawalQueue`.
+ *
+ * With a queue attached, holders cannot redeem directly: they request a
+ * withdrawal, wait out the cooldown, then claim. Read from the queue account on
+ * each vault fetch, so the counts are live.
+ */
+export interface IVaultWithdrawalQueue {
+    /** The queue account (PDA) address, base58. */
+    address: string;
+    /**
+     * Whether the vault's redeem gate points at this queue, i.e. whether new
+     * requests are accepted and direct redemption is closed. `false` for a
+     * released queue, which may still hold requests made before the release.
+     */
+    enabled: boolean;
+    /** Seconds between a new request and when it can be claimed. */
+    cooldownSeconds: number;
+    /**
+     * Seconds after the cooldown that a new request stays claimable, or `0` for
+     * no limit. A request past its window can only be cancelled.
+     */
+    fulfillmentWindowSeconds: number;
+    /** Number of requests not yet claimed or cancelled, across all holders. */
+    pendingCount: number;
+    /** Shares escrowed across all pending requests, in share-token units. */
+    pendingShares: INormalizedNumber;
+}
+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;
+    /**
+     * Solana withdrawal queue only: what claiming would pay now, in deposit-token
+     * units and net of the vault's withdrawal fee. The payout is priced when the
+     * request is claimed, so this moves with the share price. Absent when the
+     * vault has no share price to quote.
+     */
+    estimatedAssets?: INormalizedNumber;
+};
+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;
+    /**
+     * `true` when the on-chain reads for this vault threw (e.g. the RPC
+     * rejected or the receipt token could not be resolved), so the row is a
+     * zero `PENDING` placeholder rather than a real empty position. Absent on
+     * successful reads.
+     *
+     * Today this only covers the EVM path. The Solana and Stellar branches
+     * handle their own read failures internally and return an unflagged zero
+     * row, so an absent flag on a non-EVM row does not guarantee the read
+     * succeeded.
+     *
+     * `getVaultPositions` drops `PENDING` rows by default, so failed rows are
+     * only returned when the caller passes `showAllVaults: true`. Treat a
+     * flagged row as "unknown", not "no position".
+     */
+    readFailed?: boolean;
+}
+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;
+    /**
+     * The part of `totalDeposited` that is shares the wallet received from
+     * another holder (a migration airdrop, a DEX purchase, a transfer from
+     * another wallet), valued at the vault's share ratio on the day each
+     * arrived. Zero when no such shares counted. Optional only so objects built
+     * before it existed still type-check; `getVaultUserLifetimePnl` always sets
+     * it.
+     */
+    receivedByTransfer?: INormalizedNumber;
+    /** `receivedByTransfer` in USD, at the same price as the other USD fields. */
+    receivedByTransferUsd?: 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 in the next major release.
+ * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
+ */
+export interface IVaultAnnualizedApy {
+    vaultAddress: IAddress;
+    liquidityApy: number;
+    annualizedApy: number;
+    /** @deprecated Use `liquidAPY7Day` instead. Will be removed in the next major release. */
+    hgETH7dLiquidAPY?: number;
+    /** @deprecated Use `liquidAPY30Day` instead. Will be removed in the next major release. */
+    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 Upshift 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;
+    /**
+     * Subgraph indexing the vault's separate receipt token (evm-2 vaults), when
+     * one is deployed. Absent for vaults whose shares are the vault token itself.
+     */
+    receipt_subgraph?: 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. The v2 router has no vault registry, so the caller passes
+ * this on every deposit. SDK callers normally do not pass it: the SDK derives
+ * it from the vault version (a multi-asset `evm-2` vault is
+ * `TokenizedVaultV2`, any other EVM vault `ERC4626`).
+ */
+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;
+    /** Upshift vault address. */
+    vault: IAddress;
+    /**
+     * The vault's router type, sent with the deposit so the router calls the
+     * right deposit interface. When omitted, the SDK reads the vault's version
+     * from the Upshift API (`evm-2` → `TokenizedVaultV2`, otherwise `ERC4626`).
+     * A wrong value makes the router call the wrong interface and revert.
+     */
+    vaultType?: SwapRouterVaultType;
+    /** Address that receives the minted vault shares. */
+    receiver: IAddress;
+    /**
+     * 32-byte origin/referral code registered via `addOrigin`. Drives the
+     * origin-fee accrual. Defaults to the SDK instance's `attribution.originCode`
+     * when omitted on Ethereum mainnet, else {@link ORIGIN_CODES.default}. A code
+     * passed here that is not registered throws before any approval; an
+     * unregistered instance code falls back to the sentinel with an
+     * `attribution-skipped` warning (or throws under `attribution.strictOrigin`).
+     */
+    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.
+ *
+ * `vaultDeposit` never swaps; this is the explicit, opt-in entry point for
+ * swap deposits, so a vault is never silently routed through a swap it does
+ * not need — the failure mode that broke native multi-asset deposits when
+ * `vaultDeposit` still auto-routed allowlisted vaults.
+ *
+ * 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;
+}
+/** Options for {@link getOriginInfo}. */
+export interface IGetOriginInfoOptions {
+    /** EVM chain ID whose `SwapRouter` to read. */
+    chainId: number;
+    /** The `bytes32` origin code, `0x` + 64 hex chars. */
+    originCode: `0x${string}`;
+    /** RPC endpoint for `chainId`. */
+    rpcUrl: string;
+}
+/** A SwapRouter origin code's registration, from `origins(bytes32)`. */
+export interface IOriginInfo {
+    /** `true` when registered via `addOrigin` and not revoked (non-zero collector). */
+    registered: boolean;
+    /** Origin fee in basis points; `0` for an attribution-only code. */
+    originFeeBps: number;
+    /** Fee recipient; the zero address when the code is not registered. */
+    collector: 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;
+}