@augustdigital/sdk 8.3.2 → 8.6.0

package/lib/services/swap-quotes/paraswap.d.ts

@@ -7,9 +7,24 @@ export interface IParaswapQuoteInput {
     destDecimals: number;
     amount: bigint;
     receiver: IAddress;
+    /**
+     * Slippage tolerance in bps (1 bp = 0.01%). Used to derive the
+     * `destAmount` minimum baked into the resulting Paraswap calldata, so the
+     * on-chain DEX leg enforces the same tolerance the SwapRouter does
+     * (otherwise the leg reverts at the aggregator's exact-out check before
+     * the SwapRouter's `minAmountOut` is ever evaluated).
+     */
     slippageBps: number;
     partner: string;
     partnerAddress: IAddress;
+    /**
+     * Optional `includeContractMethods` value passed to Paraswap's `/prices`. When
+     * set, Paraswap is restricted to this single contract method so the resulting
+     * calldata's leading selector is deterministic and matches the one the
+     * SwapRouter authorizes for this router. When omitted, Paraswap is free to
+     * pick whichever method is optimal for the route.
+     */
+    contractMethod?: string;
     fetchImpl: typeof fetch;
     signal?: AbortSignal;
 }
@@ -19,6 +34,16 @@ export interface IParaswapQuoteOutput {
     expectedAmountOut: bigint;
     fetchedAt: number;
 }
+/**
+ * Fetch a Paraswap quote and the calldata to execute it on behalf of the
+ * SwapRouter. Throws `AugustNetworkError` on fetch-layer failure and
+ * `AugustServerError` on Paraswap-side error responses or malformed bodies.
+ *
+ * `fetchedAt` is the wall-clock timestamp captured *after* the calldata
+ * response — callers downstream can use it to decide whether the leg is
+ * fresh enough to broadcast (DEX pool state moves; stale calldata may
+ * silently revert at the on-chain slippage check).
+ */
 export declare function fetchParaswapQuote(input: IParaswapQuoteInput): Promise<IParaswapQuoteOutput>;
 export declare const PARASWAP_DEFAULTS: {
     readonly partner: "august";

package/lib/services/swap-quotes/paraswap.js

@@ -10,6 +10,16 @@ const DEFAULT_PARTNER = 'august';
 const DEFAULT_PARTNER_ADDRESS = '0xb60ee0FA5B6bA917255A03e744967E0Bda531dD0';
 const PARASWAP_VERSION = '6.2';
 const BPS_DENOMINATOR = 10000n;
+/**
+ * Fetch a Paraswap quote and the calldata to execute it on behalf of the
+ * SwapRouter. Throws `AugustNetworkError` on fetch-layer failure and
+ * `AugustServerError` on Paraswap-side error responses or malformed bodies.
+ *
+ * `fetchedAt` is the wall-clock timestamp captured *after* the calldata
+ * response — callers downstream can use it to decide whether the leg is
+ * fresh enough to broadcast (DEX pool state moves; stale calldata may
+ * silently revert at the on-chain slippage check).
+ */
 async function fetchParaswapQuote(input) {
     const priceRoute = await getPriceRoute(input);
     const destAmountRaw = priceRoute.destAmount;
@@ -32,6 +42,14 @@ async function getPriceRoute(input) {
         partnerAddress: input.partnerAddress,
         version: PARASWAP_VERSION,
     });
+    // Restrict the route to a single contract method when the caller pins one,
+    // so the calldata's selector is deterministic and matches the SwapRouter's
+    // per-router authorized selector. Without this the aggregator may return a
+    // route-optimized method (e.g. swapExactAmountInOnUniswapV3) whose selector
+    // the SwapRouter has not whitelisted, reverting with InvalidNotWhitelisted().
+    if (input.contractMethod) {
+        params.append('includeContractMethods', input.contractMethod);
+    }
     const url = `${PARASWAP_PRICES_URL}?${params.toString()}`;
     let response;
     try {
@@ -58,6 +76,10 @@ async function getPriceRoute(input) {
 }
 async function getTransactionData(input, priceRoute) {
     const url = `${PARASWAP_TRANSACTIONS_BASE_URL}/${input.chainId}/?ignoreChecks=true&ignoreGasEstimate=true&onlyParams=false`;
+    // Bake slippage into the destAmount Paraswap embeds as the aggregator's
+    // own min-out, so the DEX leg enforces the same lower bound the
+    // SwapRouter will check. Without this the aggregator uses the exact
+    // priceRoute quote (0% tolerance) and reverts on any adverse movement.
     const expectedDestAmount = BigInt(priceRoute.destAmount);
     const minDestAmount = (expectedDestAmount * (BPS_DENOMINATOR - BigInt(input.slippageBps))) /
         BPS_DENOMINATOR;

package/lib/types/pools.d.ts

@@ -1,5 +1,8 @@
-import { IAddress, INormalizedNumber } from './web3';
-import { IDebankProtocolExposure, IDebankTokenExposure, ITokenizedVaultStrategist, IWSSubaccountCefi } from './webserver';
+/**
+ * @deprecated
+ */
+import type { IAddress, INormalizedNumber } from './web3';
+import type { IDebankProtocolExposure, IDebankTokenExposure, ITokenizedVaultStrategist, IWSSubaccountCefi } from './webserver';
 type ILabelValue = {
     label: string;
     value: string;

package/lib/types/staking.d.ts

@@ -1,4 +1,4 @@
-import { IAddress, INormalizedNumber } from './web3';
+import type { IAddress, INormalizedNumber } from './web3';
 export type IActiveStakingPosition = {
     stakingToken: {
         decimals: number;

package/lib/types/sub-accounts.d.ts

@@ -1,4 +1,4 @@
-import { IAddress } from './web3';
+import type { IAddress } from './web3';
 export interface IWSSubAccountHealthFactor {
     id: IAddress;
     datetime: string;

package/lib/types/subgraph.d.ts

@@ -1,4 +1,4 @@
-import { IAddress } from './web3';
+import type { IAddress } from './web3';
 export interface ISubgraphBase {
     id: string;
     contractId_: IAddress;
@@ -12,6 +12,15 @@ export interface ISubgraphUserHistoryItem extends ISubgraphBase {
     type: 'withdraw-request' | 'deposit' | 'withdraw-processed';
     decimals?: number;
     isInstant?: boolean;
+    /**
+     * Deposit asset token address, when known. Pre-deposit vaults accept
+     * multiple deposit assets with differing decimals (e.g. USDS at 18,
+     * USDC at 6), so `amount` cannot be normalized with the vault's own
+     * decimals alone — consumers (notably lifetime PnL) key off this address
+     * to resolve the correct per-asset decimals and USD price. Absent for
+     * single-asset vaults, where the vault `decimals` is correct.
+     */
+    assetIn?: IAddress;
 }
 export interface ISubgraphWithdrawProccessed extends ISubgraphBase {
     processedOn: string;

package/lib/types/typed-contract.d.ts

@@ -1,3 +1,12 @@
+/**
+ * TypedContract type definitions for ethers v6 with abitype.
+ *
+ * This is a local copy of types from ethers-abitype to avoid the global
+ * abitype module augmentation that pollutes AddressType with `string | Addressable`,
+ * which breaks viem type compatibility.
+ *
+ * @see https://github.com/ethers-io/ethers.js/issues/4475
+ */
 import type { BaseContract, ContractTransaction, ContractTransactionResponse, DeferredTopicFilter, EventFragment, FunctionFragment, Result, Overrides } from 'ethers';
 import type { Abi, AbiParametersToPrimitiveTypes, ExtractAbiEvent, ExtractAbiEventNames, ExtractAbiEvents, ExtractAbiFunction, ExtractAbiFunctionNames, ExtractAbiFunctions } from 'abitype';
 type AsArray<T> = T extends readonly unknown[] ? T : never;
@@ -11,26 +20,81 @@ export type TypedFragment<TAbi extends Abi, TFunctionName extends string, TFunct
 };
 export interface TypedContractFunction<TAbi extends Abi, TFunctionName extends string, TFunction extends ExtractAbiFunctions<TAbi> = ExtractAbiFunction<TAbi, TFunctionName>, TInputArgs extends readonly unknown[] = AsArray<AbiParametersToPrimitiveTypes<TFunction['inputs']>>, TResult = TypedContractFunctionResult<TAbi, TFunctionName>, TFragment = TypedFragment<TAbi, TFunctionName>> {
     (...args: [...TInputArgs, overrides?: Overrides]): Promise<TFunction['stateMutability'] extends 'view' | 'pure' ? TResult : ContractTransactionResponse>;
+    /**
+     * The name of the Contract method.
+     */
     name: TFunctionName;
+    /**
+     * The fragment of the Contract method. This will throw on ambiguous
+     * method names.
+     */
     fragment: TFragment;
+    /**
+     * Returns the fragment constrained by %%args%%. This can be used to
+     * resolve ambiguous method names.
+     */
     getFragment(...args: [...TInputArgs]): TFragment;
+    /**
+     * Returns a populated transaction that can be used to perform the
+     * contract method with %%args%%.
+     */
     populateTransaction(...args: [...TInputArgs, overrides?: Overrides]): Promise<ContractTransaction>;
+    /**
+     * Call the contract method with %%args%% and return the value.
+     *
+     * If the return value is a single type, it will be dereferenced and
+     * returned directly, otherwise the full Result will be returned.
+     */
     staticCall(...args: [...TInputArgs, overrides?: Overrides]): Promise<TResult>;
+    /**
+     * Send a transaction for the contract method with %%args%%.
+     */
     send(...args: [...TInputArgs, overrides?: Overrides]): Promise<ContractTransactionResponse>;
+    /**
+     * Estimate the gas to send the contract method with %%args%%.
+     */
     estimateGas(...args: [...TInputArgs, overrides?: Overrides]): Promise<bigint>;
+    /**
+     * Call the contract method with %%args%% and return the Result
+     * without any dereferencing.
+     */
     staticCallResult(...args: [...TInputArgs, overrides?: Overrides]): Promise<Result>;
 }
 export interface TypedContractEvent<TAbi extends Abi, TEventName extends string, TEvent extends ExtractAbiEvents<TAbi> = ExtractAbiEvent<TAbi, TEventName>, TEventArgs extends readonly unknown[] = AsArray<Partial<AbiParametersToPrimitiveTypes<TEvent['inputs']>>>> {
     (...args: [...TEventArgs]): DeferredTopicFilter;
+    /**
+     * The name of the Contract event.
+     */
     name: TEventName;
+    /**
+     * The fragment of the Contract event. This will throw on ambiguous
+     * method names.
+     */
     fragment: EventFragment;
+    /**
+     * Returns the fragment constrained by %%args%%. This can be used to
+     * resolve ambiguous event names.
+     */
     getFragment(...args: [...TEventArgs]): EventFragment;
 }
 export type TypedContract<TAbi extends Abi> = Omit<BaseContract, 'getFunction' | 'getEvent'> & {
     [Method in ExtractAbiFunctionNames<TAbi>]: TypedContractFunction<TAbi, Method>;
 } & {
+    /**
+     * Return the function for a given name. This is useful when a contract
+     * method name conflicts with a JavaScript name such as ``prototype`` or
+     * when using a Contract programatically.
+     */
     getFunction<T extends ExtractAbiFunctionNames<TAbi>>(key: T | TypedFragment<TAbi, T>): TypedContractFunction<TAbi, T>;
+    /**
+     * Return the event for a given name. This is useful when a contract
+     * event name conflicts with a JavaScript name such as ``prototype`` or
+     * when using a Contract programatically.
+     */
     getEvent<T extends ExtractAbiEventNames<TAbi>>(key: T | EventFragment): TypedContractEvent<TAbi, T>;
+    /**
+     * All the Events available on this contract.
+     */
     filters: {
         [EventName in ExtractAbiEventNames<TAbi>]: TypedContractEvent<TAbi, EventName>;
     };

package/lib/types/vaults.d.ts

@@ -1,5 +1,5 @@
-import { IAddress, INormalizedNumber, VaultAddress } from './web3';
-import { IDebankProtocolExposure, IDebankTokenExposure, IOTCPosition, IWSSubaccountCefi, IWSSubaccountLoan, IWSTokenEntry, ITokenizedVaultOperator, ITokenizedVaultEoaOperator, IHIstoricalSnapshot, IApyOverride } from './webserver';
+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;
@@ -22,6 +22,13 @@ export interface IVaultLoan {
     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;
@@ -42,6 +49,26 @@ export type IVaultUserHistoryItem = {
     type: 'withdraw-request' | 'deposit' | 'withdraw-processed' | 'redeem';
     transactionHash: IAddress;
 };
+/**
+ * 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;
@@ -50,6 +77,12 @@ export type IVaultRewards = {
         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;
@@ -72,6 +105,22 @@ export type IExposurePerCategory = {
     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[];
@@ -104,6 +153,9 @@ export interface IVaultStrategist {
 }
 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;
@@ -119,9 +171,14 @@ export interface IVaultAdapterConfig {
 export interface IVault {
     max_drawdown?: number | null;
     historical_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;
@@ -195,8 +252,10 @@ export interface IVault {
     latest_reported_tvl?: number | null;
     cachedAt?: string | 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;
@@ -265,15 +324,29 @@ 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;
@@ -285,6 +358,9 @@ export interface IVaultSummary {
         month: number;
     };
 }
+/**
+ * Response for GET /withdrawals/{chain}/{vault_address}
+ */
 export interface IVaultWithdrawals {
     vaultAddress: IAddress;
     chain: string;
@@ -297,6 +373,9 @@ export interface IVaultWithdrawals {
         receiver: IAddress;
     }>;
 }
+/**
+ * Response for GET /vaults/\{vault_addr\}/pending-redemptions
+ */
 export interface IVaultPendingRedemptions {
     vault: {
         address: string;
@@ -328,38 +407,120 @@ export interface IVaultPendingRedemptions {
         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;
 }

package/lib/types/vaults.js

@@ -6,6 +6,16 @@ var VaultRedemptionStatus;
     VaultRedemptionStatus["AWAITING_COOLDOWN"] = "awaiting_cooldown";
     VaultRedemptionStatus["READY_TO_CLAIM"] = "ready_to_claim";
 })(VaultRedemptionStatus || (exports.VaultRedemptionStatus = VaultRedemptionStatus = {}));
+/**
+ * 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.
+ */
 var SwapRouterVaultType;
 (function (SwapRouterVaultType) {
     SwapRouterVaultType[SwapRouterVaultType["ERC4626"] = 1] = "ERC4626";

package/lib/types/web3.d.ts

@@ -1,8 +1,16 @@
-import { Signer, Provider } from 'ethers';
+import type { Signer, Provider } from 'ethers';
 export type IAddress = `0x${string}`;
+/**
+ * Address type for vault contracts across all supported chains.
+ * EVM vaults use `0x`-prefixed hex addresses, Solana vaults use base58,
+ * and Stellar vaults use 56-character base32 addresses (G/C prefix).
+ *
+ * Use this instead of `IAddress` when the address may belong to any chain.
+ */
 export type VaultAddress = string;
 export type IChainId = number;
 export type ChainType = 'evm' | 'solana' | 'sui' | 'stellar';
+/** Runtime type guard for ChainType values (e.g. at API deserialization boundaries). */
 export declare function isChainType(value: unknown): value is ChainType;
 export type IChainObj = {
     chainId: number;

package/lib/types/web3.js

@@ -7,6 +7,7 @@ const VALID_CHAIN_TYPES = new Set([
     'sui',
     'stellar',
 ]);
+/** Runtime type guard for ChainType values (e.g. at API deserialization boundaries). */
 function isChainType(value) {
     return typeof value === 'string' && VALID_CHAIN_TYPES.has(value);
 }

package/lib/types/webserver.d.ts

@@ -1,5 +1,15 @@
-import { IUserRoles } from './user';
-import { IAddress, type ChainType, type IStellarNetwork } from './web3';
+import type { IUserRoles } from './user';
+import type { IAddress, ChainType, IStellarNetwork } from './web3';
+/**
+ * Table of Contents
+ * 1) Subaccounts
+ * 2) Metrics
+ * 3) Tokens
+ * 4) Users
+ * 5) Statuses
+ * 6) Integrations
+ * 7) Lending Pools
+ */
 export type IHIstoricalSnapshot = {
     total_assets: number;
     total_shares: number;
@@ -14,6 +24,9 @@ export interface IWSMonitorHeaders {
     'x-user-id'?: string;
     'x-environment'?: string;
 }
+/**
+ * Subaccounts
+ */
 export type IWSSubaccountPermission = {
     name: string;
     chain: number;
@@ -117,6 +130,9 @@ export interface IWSSubaccountLoan {
     payment_interval: number;
     lender_apr: number;
 }
+/**
+ * Metrics
+ */
 export type IWSMetricsPnlAttributes = {
     pnl: number;
     percent_return: number;
@@ -289,6 +305,9 @@ export type IWSMetricsTimeseries = {
     total_pnl_7d: number | null;
     total_pnl_30d: number | null;
 };
+/**
+ * Tokens
+ */
 export type IWSTokenEntry = {
     symbol: string;
     address: `0x${string}`;
@@ -306,6 +325,9 @@ export type IWSTokenPrice = {
     price: number;
     dt: string;
 };
+/**
+ * Users
+ */
 export type IWSUserSubaccount = {
     internal_name: string;
     friendly_name: string;
@@ -332,12 +354,21 @@ export type IWSUser = {
     disabled: boolean;
     id: string;
 };
+/**
+ * Statuses
+ */
 export type IWSFireblocksTxStatus = 'SUBMITTED' | 'PENDING_AML_SCREENING' | 'PENDING_AUTHORIZATION' | 'QUEUED' | 'PENDING_SIGNATURE' | 'PENDING_3RD_PARTY_MANUAL_APPROVAL' | 'PENDING_3RD_PARTY' | 'BROADCASTING' | 'CONFIRMING' | 'COMPLETED' | 'CANCELLING' | 'BLOCKED' | 'REJECTED' | 'FAILED';
+/**
+ * Integrations
+ */
 export interface IWSIntegrationMorphoApy {
     apy: number;
     vault_positions: any[];
     token: IWSTokenEntry;
 }
+/**
+ * Lending Pools
+ */
 export interface IWSVaultLoan {
     address: IAddress;
     lender: IAddress;
@@ -392,14 +423,23 @@ export interface ITokenizedVaultEoaOperator {
     id: string;
     name: string;
 }
+/**
+ * Controls how the vault's APY is displayed in the UI.
+ * When `is_show_target_apy` is true, the UI should show a target/projected APY.
+ * When `is_show_hardcoded_apy` is true, `hardcoded_apy` overrides the computed APY.
+ */
 export interface IApyOverride {
+    /** Whether to display a target APY rather than historical performance. */
     is_show_target_apy: boolean;
+    /** Whether to display `hardcoded_apy` in place of the computed APY. */
     is_show_hardcoded_apy: boolean;
+    /** The fixed APY value to display when `is_show_hardcoded_apy` is true, or null. */
     hardcoded_apy: number | null;
 }
 export interface ITokenizedVaultStrategist {
     strategist_name: string;
     strategist_logo: string;
+    /** URL of the strategist's website, or null if not provided. */
     website_url: string | null;
     id: string;
 }
@@ -534,6 +574,7 @@ export interface ITokenizedVault {
     stellar_vault_metadata?: IStellarVaultMetadata | null;
     lagDuration: number;
     historical_apy: Record<number, number> | null;
+    /** @deprecated Use getVaultHistoricalTimeseries instead */
     historical_snapshots?: IHIstoricalSnapshot[];
     max_drawdown: number | null;
     daily_pnl_per_share: Record<string, number>;
@@ -552,8 +593,12 @@ export interface ITokenizedVault {
         }>;
     };
     show_cap_filled: boolean | null;
+    /** Controls APY display behaviour in the UI; null when the server has not set an override. */
     apy_override: IApyOverride | null;
 }
+/**
+ * @deprecated
+ */
 export interface IWSVaultHistoricalApy {
     data: {
         labels: string[];