upshift-finance 1.0.0

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

@@ -0,0 +1,105 @@
+/** @module core/services/swap-quotes */
+import type { IAddress } from '../../types';
+/** Quote-provider discriminant. Will widen as new providers are added. */
+export type ISwapQuoteProvider = 'paraswap';
+/**
+ * Input to {@link fetchSwapQuote}.
+ */
+export interface ISwapQuoteRequest {
+    /** EVM chain ID where the swap will execute. */
+    chainId: number;
+    /** ERC-20 the user holds. */
+    srcToken: IAddress;
+    /** `srcToken.decimals()`. */
+    srcDecimals: number;
+    /** ERC-20 the SwapRouter should produce — typically the vault's `referenceAsset`. */
+    destToken: IAddress;
+    /** `destToken.decimals()`. */
+    destDecimals: number;
+    /** Input amount in `srcToken`'s smallest unit. */
+    amount: bigint;
+    /**
+     * Address that will execute the resulting calldata. For SwapRouter use,
+     * pass the SwapRouter's address — the aggregator's calldata is bound to
+     * this address, so it must hold the tokens at swap time.
+     */
+    receiver: IAddress;
+    /**
+     * Slippage tolerance in bps (1 bp = 0.01%). Defaults to 100 (1%). Must be
+     * in `[0, 10_000)` — 10_000 disables protection entirely and is rejected.
+     */
+    slippageBps?: number;
+    /**
+     * Optional aggregator contract-method filter. When set, the aggregator is
+     * constrained to this single method (ParaSwap's `/prices`
+     * `includeContractMethods`), so the returned calldata's leading 4-byte
+     * selector is deterministic — required when the on-chain SwapRouter only
+     * authorizes one selector per router. When omitted, the aggregator picks the
+     * optimal method freely and the selector may vary between quotes.
+     */
+    contractMethod?: string;
+    /** Aggregator partner key. Defaults to `'august'`. */
+    partner?: string;
+    /** Aggregator partner-fee receiver. Defaults to the August partner address. */
+    partnerAddress?: IAddress;
+    /**
+     * `fetch`-compatible function override. Defaults to `globalThis.fetch`.
+     * Exposed so callers in Node environments lacking a global `fetch` can
+     * inject one, and so tests can mock without touching the global.
+     */
+    fetchImpl?: typeof fetch;
+    /** Optional AbortSignal to cancel the in-flight Paraswap requests. */
+    signal?: AbortSignal;
+}
+/**
+ * Output of {@link fetchSwapQuote}. The `router` + `payload` pair maps
+ * directly into one entry of an `ISwapParams[]` passed to
+ * `SwapRouter.swapAndDeposit`.
+ *
+ * Modeled as a discriminated union on `provider` so adding 1inch/0x is an
+ * additive change rather than a breaking widening.
+ */
+export type ISwapQuoteResult = {
+    /** Quote provider that produced this calldata. */
+    provider: 'paraswap';
+    /** DEX router that will execute the swap (the contract `payload` is calldata for). */
+    router: IAddress;
+    /** ABI-encoded calldata for `router`. */
+    payload: `0x${string}`;
+    /** Expected output in `destToken` units before slippage. */
+    expectedAmountOut: bigint;
+    /** Slippage-adjusted minimum output. Below this the on-chain call reverts. */
+    minAmountOut: bigint;
+    /**
+     * Epoch ms when the quote was fetched. Callers that prefetch a quote
+     * before submitting should re-fetch when this is older than ~60s — DEX
+     * pool state moves and a stale `minAmountOut` may have been computed
+     * against a price that no longer holds.
+     */
+    fetchedAt: number;
+};
+/**
+ * Fetch a swap quote and the calldata required for the on-chain SwapRouter
+ * to execute it.
+ *
+ * @throws {@link AugustValidationError} on invalid input (slippage out of
+ * range, zero amount, src===dst).
+ * @throws {@link AugustNetworkError} on transport failure.
+ * @throws {@link AugustServerError} on aggregator-side errors.
+ *
+ * @example
+ * ```ts
+ * const quote = await fetchSwapQuote({
+ *   chainId: 1,
+ *   srcToken: WBTC,
+ *   srcDecimals: 8,
+ *   destToken: USDC,
+ *   destDecimals: 6,
+ *   amount: 100_000_000n,
+ *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+ * });
+ * // quote.router  -> Paraswap augustor
+ * // quote.payload -> calldata
+ * ```
+ */
+export declare function fetchSwapQuote(request: ISwapQuoteRequest): Promise<ISwapQuoteResult>;

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

@@ -0,0 +1,77 @@
+"use strict";
+/** @module core/services/swap-quotes */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchSwapQuote = fetchSwapQuote;
+const errors_1 = require("../../core/errors");
+const paraswap_1 = require("./paraswap");
+const DEFAULT_SLIPPAGE_BPS = 100;
+const BPS_DENOMINATOR = 10000n;
+/**
+ * Fetch a swap quote and the calldata required for the on-chain SwapRouter
+ * to execute it.
+ *
+ * @throws {@link AugustValidationError} on invalid input (slippage out of
+ * range, zero amount, src===dst).
+ * @throws {@link AugustNetworkError} on transport failure.
+ * @throws {@link AugustServerError} on aggregator-side errors.
+ *
+ * @example
+ * ```ts
+ * const quote = await fetchSwapQuote({
+ *   chainId: 1,
+ *   srcToken: WBTC,
+ *   srcDecimals: 8,
+ *   destToken: USDC,
+ *   destDecimals: 6,
+ *   amount: 100_000_000n,
+ *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+ * });
+ * // quote.router  -> Paraswap augustor
+ * // quote.payload -> calldata
+ * ```
+ */
+async function fetchSwapQuote(request) {
+    validateRequest(request);
+    const slippageBps = request.slippageBps ?? DEFAULT_SLIPPAGE_BPS;
+    const fetchImpl = request.fetchImpl ?? globalThis.fetch;
+    const { router, payload, expectedAmountOut, fetchedAt } = await (0, paraswap_1.fetchParaswapQuote)({
+        chainId: request.chainId,
+        srcToken: request.srcToken,
+        srcDecimals: request.srcDecimals,
+        destToken: request.destToken,
+        destDecimals: request.destDecimals,
+        amount: request.amount,
+        receiver: request.receiver,
+        slippageBps,
+        partner: request.partner ?? paraswap_1.PARASWAP_DEFAULTS.partner,
+        partnerAddress: request.partnerAddress ?? paraswap_1.PARASWAP_DEFAULTS.partnerAddress,
+        contractMethod: request.contractMethod,
+        fetchImpl,
+        signal: request.signal,
+    });
+    const minAmountOut = applySlippage(expectedAmountOut, slippageBps);
+    return {
+        provider: 'paraswap',
+        router,
+        payload,
+        expectedAmountOut,
+        minAmountOut,
+        fetchedAt,
+    };
+}
+function validateRequest(req) {
+    if (req.slippageBps !== undefined &&
+        (req.slippageBps < 0 || req.slippageBps >= 10_000)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `fetchSwapQuote: slippageBps must be in [0, 10000), got ${req.slippageBps}. 10000 bps = 100% slippage and disables protection entirely; use a tighter bound.`);
+    }
+    if (req.amount === 0n) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', 'fetchSwapQuote: amount must be greater than zero');
+    }
+    if (req.srcToken.toLowerCase() === req.destToken.toLowerCase()) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', 'fetchSwapQuote: srcToken and destToken are identical — no swap needed');
+    }
+}
+function applySlippage(amount, slippageBps) {
+    return (amount * (BPS_DENOMINATOR - BigInt(slippageBps))) / BPS_DENOMINATOR;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,51 @@
+import type { IAddress } from '../../types';
+export interface IParaswapQuoteInput {
+    chainId: number;
+    srcToken: IAddress;
+    srcDecimals: number;
+    destToken: IAddress;
+    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;
+}
+export interface IParaswapQuoteOutput {
+    router: IAddress;
+    payload: `0x${string}`;
+    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";
+    readonly partnerAddress: `0x${string}`;
+};

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

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARASWAP_DEFAULTS = void 0;
+exports.fetchParaswapQuote = fetchParaswapQuote;
+const errors_1 = require("../../core/errors");
+const web3_1 = require("../../core/helpers/web3");
+const PARASWAP_PRICES_URL = 'https://api.paraswap.io/prices';
+const PARASWAP_TRANSACTIONS_BASE_URL = 'https://api.paraswap.io/transactions';
+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;
+    if (typeof destAmountRaw !== 'string' || !/^\d+$/.test(destAmountRaw)) {
+        throw new errors_1.AugustServerError(200, `fetchSwapQuote: Paraswap /prices returned non-numeric destAmount: ${String(destAmountRaw)}`, { context: { destAmount: destAmountRaw } });
+    }
+    const expectedAmountOut = BigInt(destAmountRaw);
+    const { router, payload } = await getTransactionData(input, priceRoute);
+    return { router, payload, expectedAmountOut, fetchedAt: Date.now() };
+}
+async function getPriceRoute(input) {
+    const params = new URLSearchParams({
+        network: String(input.chainId),
+        srcToken: input.srcToken,
+        srcDecimals: String(input.srcDecimals),
+        destToken: input.destToken,
+        destDecimals: String(input.destDecimals),
+        amount: input.amount.toString(),
+        partner: input.partner,
+        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 {
+        response = await input.fetchImpl(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+            signal: input.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.AugustNetworkError('fetchSwapQuote: Paraswap /prices fetch failed', { cause, context: { url } });
+    }
+    if (!response.ok) {
+        throw new errors_1.AugustServerError(response.status, `fetchSwapQuote: Paraswap /prices returned HTTP ${response.status}`, { context: { url } });
+    }
+    const body = (await response.json());
+    if (body.error) {
+        throw new errors_1.AugustServerError(response.status, `fetchSwapQuote: Paraswap /prices error: ${body.error}`, { context: { providerError: body.error } });
+    }
+    if (!body.priceRoute) {
+        throw new errors_1.AugustServerError(response.status, 'fetchSwapQuote: Paraswap /prices returned no priceRoute', { context: { body } });
+    }
+    return body.priceRoute;
+}
+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;
+    const requestBody = {
+        userAddress: input.receiver,
+        srcToken: input.srcToken,
+        destToken: input.destToken,
+        srcDecimals: input.srcDecimals,
+        destDecimals: input.destDecimals,
+        srcAmount: input.amount.toString(),
+        destAmount: minDestAmount.toString(),
+        priceRoute,
+        partner: input.partner,
+        partnerAddress: input.partnerAddress,
+    };
+    let response;
+    try {
+        response = await input.fetchImpl(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(requestBody),
+            signal: input.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.AugustNetworkError('fetchSwapQuote: Paraswap /transactions fetch failed', { cause, context: { url } });
+    }
+    if (!response.ok) {
+        throw new errors_1.AugustServerError(response.status, `fetchSwapQuote: Paraswap /transactions returned HTTP ${response.status}`, { context: { url } });
+    }
+    const body = (await response.json());
+    if (body.error) {
+        throw new errors_1.AugustServerError(response.status, `fetchSwapQuote: Paraswap /transactions error: ${body.error}`, { context: { providerError: body.error } });
+    }
+    if (!body.to || !body.data) {
+        throw new errors_1.AugustServerError(response.status, 'fetchSwapQuote: Paraswap /transactions returned no to/data', { context: { body } });
+    }
+    if (!(0, web3_1.checkAddress)(body.to, console, 'contract')) {
+        throw new errors_1.AugustServerError(response.status, `fetchSwapQuote: Paraswap /transactions returned an invalid router address: ${body.to}`, { context: { to: body.to } });
+    }
+    if (!/^0x[0-9a-fA-F]+$/.test(body.data) || body.data.length % 2 !== 0) {
+        throw new errors_1.AugustServerError(response.status, `fetchSwapQuote: Paraswap /transactions returned malformed calldata (${body.data.length} chars)`, { context: { dataPrefix: body.data.slice(0, 16) } });
+    }
+    if (body.data.length < 10) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', 'fetchSwapQuote: Paraswap /transactions returned calldata shorter than a 4-byte selector');
+    }
+    return {
+        router: body.to,
+        payload: body.data,
+    };
+}
+exports.PARASWAP_DEFAULTS = {
+    partner: DEFAULT_PARTNER,
+    partnerAddress: DEFAULT_PARTNER_ADDRESS,
+};
+//# sourceMappingURL=paraswap.js.map

package/lib/types/api.d.ts

@@ -0,0 +1,280 @@
+import type { IAddress } from './web3';
+/**
+ * A whitelisted token as embedded in loan-book records by the backend
+ * `WhitelistedTokenModel` schema. `chain` is the numeric August chain id
+ * (backend `Chain` IntEnum value, e.g. `1` for Ethereum mainnet).
+ */
+export interface IWhitelistedToken {
+    chain: number;
+    name: string;
+    token_type: string;
+    address: IAddress;
+    decimals: number;
+    symbol: string;
+    discount_factor: number;
+    img_url: string | null;
+    price: number | null;
+}
+/**
+ * The amount and due date of a loan's next scheduled payment, as serialized
+ * by the backend `UpcomingPayment` schema. `due_date` is an ISO-8601 datetime
+ * string.
+ */
+export interface ILoanUpcomingPayment {
+    amount: number;
+    due_date: string;
+}
+/**
+ * One loan-book entry from the admin loan-book endpoints (backend
+ * `LoanBookInfo` schema). Amounts are decimal-adjusted floats; monetary
+ * fields are denominated in the loan's principal token. `deployed_date` is an
+ * ISO-8601 datetime string; `state` is the backend `LoanStateStr` value
+ * (e.g. `"ACTIVE"`).
+ */
+export interface ILoanBookInfo {
+    address: IAddress;
+    lender: IAddress;
+    borrower: IAddress;
+    state: string;
+    total_repaid: number;
+    principal_token: IWhitelistedToken;
+    principal_amount: number;
+    interest_amount: number;
+    upcoming_payment: ILoanUpcomingPayment;
+    apr: number;
+    initial_principal_amount: number;
+    deployed_date: string;
+    payment_interval: number;
+    total_interest_payment_fees: number;
+    lender_apr: number;
+}
+/**
+ * A token's discount-factor ladder from `GET /risk/discount_factors`
+ * (backend `DiscountFactorRead` schema). `steps` are ascending notional
+ * thresholds (in the token's smallest unit) and `factors` the corresponding
+ * ascending haircut multipliers in `[0, 1]`; the two arrays are equal length.
+ * `chain` is the numeric August chain id.
+ */
+export interface IDiscountFactorLadder {
+    steps: number[] | null;
+    factors: number[] | null;
+    address: IAddress;
+    chain: number;
+}
+/**
+ * Result of `GET /risk/collateral_excess_or_deficit` (backend
+ * `CollateralExcessOrDeficit` schema). A positive value is excess collateral
+ * that could be withdrawn; a negative value is the shortfall that must be
+ * deposited to reach the target health factor.
+ */
+export interface ICollateralExcessOrDeficit {
+    amount_usd: number;
+    amount_token: number;
+}
+/**
+ * Request body for `POST /risk/collateral_simulation` (backend
+ * `CollateralSimulation` schema). Chain fields are numeric August chain ids.
+ * `collateral_tokens` is a list of `[chain, address]` pairs and
+ * `collateral_token_allocation` the matching per-token weights (normalized
+ * server-side, so relative magnitudes are what matter). When `on_platform`
+ * is `true`, both `loan_redeployed_token_*` fields are required by the
+ * backend.
+ */
+export interface ICollateralSimulationInput {
+    loan_token_chain: number;
+    loan_token_address: IAddress;
+    loan_amount: number;
+    on_platform?: boolean;
+    loan_redeployed_token_chain?: number | null;
+    loan_redeployed_token_address?: IAddress | null;
+    collateral_tokens: [number, IAddress][];
+    collateral_token_allocation: number[];
+    target_health_factor?: number;
+}
+/**
+ * Per-collateral-token breakdown within a collateral simulation (backend
+ * `CollateralDetailsResult` schema). `chain` is the numeric August chain id.
+ */
+export interface ICollateralDetailsResult {
+    chain: number;
+    token_address: IAddress;
+    price: number;
+    allocation: number;
+    collateral_value_from_redeployed_loan_usd: number;
+    collateral_value_usd: number;
+    amount_usd: number;
+    amount_token: number;
+    effective_discount_factor: number;
+    is_top_up: boolean;
+}
+/**
+ * Result of `POST /risk/collateral_simulation` (backend
+ * `CollateralSimulationResults` schema). `collateral_details` is keyed by
+ * `"<symbol>_<chainName>"`.
+ */
+export interface ICollateralSimulationResults {
+    total_debt_usd: number;
+    total_required_collateral_usd: number;
+    total_collateral_value_from_redeployed_loan_usd: number;
+    health_factor: number;
+    collateral_details: Record<string, ICollateralDetailsResult>;
+}
+/**
+ * Result of the public `GET /revert_reason` endpoint (backend `RevertResponse`
+ * schema) — the decoded failure reasons for a reverted transaction, collected
+ * from a `debug_traceTransaction` call tree. All three arrays are empty when
+ * no matching signal was found in the trace.
+ */
+export interface IRevertReason {
+    error_messages: string[];
+    revert_reasons: string[];
+    universal_subaccount_errors: string[];
+}
+/**
+ * One transaction record from `GET /transactions/v2` (backend
+ * `TransactionAPIRead` schema). `chain` is the numeric August chain id;
+ * `value` is decimal-adjusted; `timestamp` is a Unix epoch (seconds).
+ * `from_` mirrors the backend field name (`from` is reserved). Nested
+ * `logs` / `transfers` / `function_signature` / `otc_cashflow` are passed
+ * through as-is. `transaction_name` is the resolved function name (or the raw
+ * selector when unknown).
+ */
+export interface ISubaccountTransaction {
+    id: string;
+    tx_hash: string;
+    chain: number;
+    from_: IAddress;
+    to: IAddress;
+    value: number;
+    block_number: number;
+    timestamp: number;
+    selector: string | null;
+    logs: unknown[];
+    transfers: unknown[];
+    function_signature: Record<string, unknown> | null;
+    otc_cashflow: Record<string, unknown> | null;
+    transaction_name: string | null;
+}
+/**
+ * DeBank positions and tokens for a single account (backend
+ * `DebankAccountData` schema). `positions`, `app_positions`, and `tokens`
+ * are passed through as raw DeBank objects.
+ */
+export interface ISubaccountDebankData {
+    positions: unknown[];
+    app_positions: unknown[];
+    tokens: unknown[];
+}
+/**
+ * Cross-chain DeBank protocol positions for a subaccount and its associated
+ * strategies (backend `SubaccountDebankAccountData` schema). `strategies` is
+ * keyed by strategy address. This endpoint is slow (300-second server-side
+ * cache) as it fans out across every supported chain.
+ */
+export interface ISubaccountDebank {
+    subaccount: ISubaccountDebankData;
+    strategies: Record<string, ISubaccountDebankData>;
+}
+/**
+ * A tracked position from `GET /otc/position` (backend `IPositionRead`
+ * schema). `configs` is a free-form JSON object of position-specific
+ * settings; `category` is the position category (e.g. `"otc"`).
+ */
+export interface IOtcPositionRead {
+    id: string;
+    slug: string;
+    position_class: string | null;
+    configs: Record<string, unknown> | null;
+    category: string | null;
+    position_discount_factor: number | null;
+}
+/**
+ * An OTC margin requirement from `GET /otc/margin_requirement` (backend
+ * `IOTCMarginRequirementRead` schema) — the margin the `payer` must post to
+ * the given counterparty.
+ */
+export interface IOtcMarginRequirement {
+    otc_counter_party_id: string;
+    margin_requirement: number;
+    payer: IAddress;
+}
+/**
+ * On-chain whitelist status of one subaccount linked to a vault, from
+ * `GET /curator/vaults/{vault_address}/whitelist` (backend
+ * `WhitelistStatusResponse` schema). EVM vaults only.
+ */
+export interface ICuratorWhitelistStatus {
+    address: IAddress;
+    is_whitelisted: boolean;
+}
+/**
+ * One timelock request from `GET /timelock-requests` (backend
+ * `ITimelockRequestRead` schema). `chain_id` is the numeric chain id;
+ * `status` is one of `"scheduled" | "executed" | "cancelled"`; `params` is a
+ * free-form JSON object; datetime fields are ISO-8601 strings.
+ */
+export interface ITimelockRequest {
+    id: string;
+    hash: string;
+    vault_address: IAddress;
+    timelock_address: IAddress;
+    chain_id: number;
+    action_id: string;
+    params: Record<string, unknown>;
+    status: string;
+    schedule_tx_hash: string;
+    execute_tx_hash: string | null;
+    cancel_tx_hash: string | null;
+    submitted_by: string | null;
+    scheduled_at: string;
+    resolved_at: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+/**
+ * Performance-fee computation for a vault from
+ * `GET /metrics/vault_performance_fees` (backend `UpshiftVaultPerformanceFees`
+ * schema). High/low water marks are share-price levels; `*_datetime` fields
+ * are ISO-8601 strings. `calculation_period` is `"YearToDate"` /
+ * `"MonthToDate"` (null when a custom date range was supplied).
+ */
+export interface IVaultPerformanceFees {
+    previous_water_mark: number;
+    previous_water_mark_datetime: string;
+    last_water_mark: number;
+    last_water_mark_datetime: string;
+    is_in_drawdown: boolean;
+    asset_symbol: string | null;
+    total_pnl_in_asset: number;
+    total_perf_fees_asset: number;
+    calculation_period: string | null;
+    annualized_fees_pct: number;
+    underlying_asset_vs_native_perf: number | null;
+    native_token_symbol: string | null;
+}
+/**
+ * One row of a vault's NAV-oracle classification table (backend
+ * `OracleClassificationRow` schema) — how a single position/token is priced
+ * and its USD value.
+ */
+export interface IOracleClassificationRow {
+    position: string;
+    type: string;
+    oracle_source: string;
+    usd_value: number;
+}
+/**
+ * A vault's NAV-oracle classification from the public
+ * `GET /upshift/oracle_classification/{vault_address}` endpoint (backend
+ * `OracleClassificationResponse` schema). `warnings` lists tokens that could
+ * not be resolved (`"unresolved:<symbol>"`). `snapshot_at` is an ISO-8601
+ * datetime string.
+ */
+export interface IOracleClassification {
+    vault_address: IAddress;
+    chain_id: number;
+    snapshot_at: string;
+    methodology: string;
+    rows: IOracleClassificationRow[];
+    warnings: string[];
+}

package/lib/types/api.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=api.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,12 @@
+export type IEnv = 'DEV' | 'PROD';
+export * from './web3';
+export * from './typed-contract';
+export * from './user';
+export * from './webserver';
+export * from './pools';
+export * from './staking';
+export * from './subgraph';
+export * from './vaults';
+export * from './points';
+export * from './sub-accounts';
+export * from './api';