@aegis-engine/core 0.2.0 → 0.3.0

package/dist/engine/types.d.ts

@@ -0,0 +1,992 @@
+import type { Address, Hex, PublicClient, TransactionReceipt } from 'viem';
+import type { AegisSwapChainConfig, AegisSwapToken } from '../config/index.js';
+import type { SignedPermitBatch } from '../encoding.js';
+import type { WalletSession } from '../swap/types.js';
+export type AegisEngineMode = 'lend' | 'borrow' | 'positions';
+export type AegisEngineMarketSource = 'rest' | 'static';
+export type AegisEngineMarketStatus = 'enabled' | 'disabled' | 'hidden' | 'malformed';
+export type AegisEngineToken = AegisSwapToken;
+export type AegisEngineMarketMetrics = {
+    tvlUsd?: number | null;
+    suppliedUsd?: number | null;
+    borrowedUsd?: number | null;
+    availableToBorrowUsd?: number | null;
+    utilizationPct?: number | null;
+    borrowAprPct?: number | null;
+    lendApyPct?: number | null;
+    activeDebtVaultCount?: number | null;
+    sharePriceWad?: string | null;
+    ratePerSecondWad?: string | null;
+    fullUtilizationRate?: string | null;
+    rateSource?: string | null;
+    totalLendShares?: string | null;
+    baseFeePpm?: number | null;
+    activeFeePpm?: number | null;
+    surgeFeePpm?: number | null;
+    surgeActive?: boolean | null;
+    inCapEvent?: boolean | null;
+    manualOverride?: boolean | null;
+    perSwapMode?: boolean | null;
+    feeSource?: string | null;
+    computedAt?: string | null;
+    updatedAt?: string | null;
+    engineUpdatedAt?: string | null;
+    rateUpdatedAt?: string | null;
+    feeUpdatedAt?: string | null;
+};
+export type AegisEngineMarketFreshness = {
+    source: 'canopy';
+    updatedAt?: string | null;
+    engineUpdatedAt?: string | null;
+    rateUpdatedAt?: string | null;
+    feeUpdatedAt?: string | null;
+    blockNumber?: number | null;
+    blockTimestamp?: number | null;
+};
+export type AegisEngineDisabledReasons = {
+    borrow: string[];
+    lend: string[];
+};
+export type AegisEngineMarket = {
+    id: string;
+    chainId: number;
+    source: AegisEngineMarketSource;
+    status: AegisEngineMarketStatus;
+    displayName: string;
+    poolId: Hex;
+    token0: AegisEngineToken;
+    token1: AegisEngineToken;
+    poolKey: {
+        currency0: Address;
+        currency1: Address;
+        fee: number;
+        tickSpacing: number;
+        hooks: Address;
+    };
+    engine?: Address;
+    stateView?: Address;
+    v4StateView?: Address;
+    v4Quoter?: Address;
+    router?: Address;
+    permit2?: Address;
+    vaultRegistry?: Address;
+    borrowEnabled: boolean;
+    lendEnabled: boolean;
+    canBorrow?: boolean | null;
+    canLend?: boolean | null;
+    maxLtvPips?: number | null;
+    hardLtvPips?: number | null;
+    warnings: string[];
+    disabledReasons?: AegisEngineDisabledReasons;
+    metrics?: AegisEngineMarketMetrics;
+    /** Coherent backend read frame. Static host fixtures may omit it. */
+    freshness?: AegisEngineMarketFreshness;
+};
+export type AegisEngineHistoryWindow = '7d' | '30d' | '60d';
+export type AegisEngineHistoryStatus = 'ready' | 'warming_up' | 'no_data';
+export type AegisEngineMetricPoint = {
+    /** Start of the 12-hour UTC bucket, in Unix seconds. */
+    t: number;
+    observedAt: string;
+    blockNumber: number;
+    utilizationPct: number | null;
+    borrowAprPct: number | null;
+    lendApyPct: number | null;
+    ratePerSecondWad: string | null;
+    rateSource: string | null;
+    fullUtilizationRate: string | null;
+    sharePriceWad: string | null;
+    suppliedUsd: number | null;
+    borrowedUsd: number | null;
+    availableToBorrowUsd: number | null;
+    baseFeePpm: number | null;
+    activeFeePpm: number | null;
+    surgeFeePpm: number | null;
+    feeSource: string | null;
+    surgeActive: boolean | null;
+    inCapEvent: boolean | null;
+    manualOverride: boolean | null;
+    perSwapMode: boolean | null;
+    warnings: string[];
+};
+export type AegisEngineMetricHistory = {
+    marketId: string;
+    resolution: '12h';
+    window: AegisEngineHistoryWindow;
+    status: AegisEngineHistoryStatus;
+    pointCount: number;
+    points: AegisEngineMetricPoint[];
+    updatedAt: string | null;
+};
+export type AegisEnginePositionTokenAmount = {
+    raw: string;
+    formatted: string;
+    valueUsd?: number | null;
+};
+export type AegisEnginePositionDebt = {
+    principalRaw: string;
+    borrowIndexWadAtLastDebt?: string | null;
+};
+export type AegisEnginePositionLtv = {
+    /** Subgraph-indexed value captured when the vault was last locked. It is
+     * not a live health measurement; current LTV requires a StateView read. */
+    lastLockedPips?: number | null;
+    lastLockedPct?: number | null;
+    maxLtvPips?: number | null;
+    hardLtvPips?: number | null;
+};
+export type AegisEnginePositionNft = {
+    id?: string | null;
+    kind?: string | null;
+    tokenId?: string | null;
+    liquidityRaw?: string | null;
+};
+export type AegisEnginePosition = {
+    id: string;
+    chainId: number;
+    account: Address;
+    vaultId: string;
+    status: 'open' | 'debt' | 'collateral' | 'empty';
+    marketId?: string | null;
+    marketName?: string | null;
+    poolId: Hex;
+    token0?: AegisEngineToken | null;
+    token1?: AegisEngineToken | null;
+    amount0: AegisEnginePositionTokenAmount;
+    amount1: AegisEnginePositionTokenAmount;
+    collateralValueUsd?: number | null;
+    debt: AegisEnginePositionDebt;
+    ltv: AegisEnginePositionLtv;
+    nfts: {
+        count: number;
+        items: AegisEnginePositionNft[];
+    };
+    createdAt?: string | null;
+    createdBlockNumber?: number | null;
+    updatedAt?: string | null;
+    warnings: string[];
+};
+export type AegisEngineLendSharesPosition = {
+    kind: 'lend_shares';
+    id: string;
+    chainId: number;
+    account: Address;
+    marketId: string | null;
+    marketName: string | null;
+    poolId: Hex;
+    token0: AegisEngineToken | null;
+    token1: AegisEngineToken | null;
+    /** Indexed lender balance in raw Engine share units (bigint decimal string).
+     * Not a token amount — value it with a current share price. */
+    indexedBalanceRaw: string;
+    warnings: string[];
+    freshness: {
+        source: 'subgraph';
+        indexedBlockNumber: number | null;
+    };
+};
+export type AegisEnginePositionsSnapshot = {
+    schemaVersion: '1' | '2';
+    chainId: number;
+    account: Address;
+    positions: AegisEnginePosition[];
+    /** Lender-share positions. Every loader emits an array (empty for v1
+     * responses and when v2 is unavailable), so consumers read it
+     * unconditionally. */
+    lendPositions: AegisEngineLendSharesPosition[];
+    totals: {
+        collateralValueUsd?: number | null;
+        positionCount: number;
+        /** Number of borrow-vault rows in `positions`. */
+        borrowVaultCount: number;
+        /** Number of lender-share rows in `lendPositions`. */
+        lendPositionCount: number;
+    };
+    freshness: {
+        source: 'subgraph' | 'static';
+        blockNumber?: number | null;
+        positionCount: number;
+    };
+};
+export type AegisEngineActivityActionBase = {
+    /** Stable subgraph row id. */
+    id: string;
+    /** Event block time in Unix seconds. */
+    timestamp: number;
+    blockNumber: number;
+    transactionIndex: number;
+    txHash: Hex;
+    logIndex: number;
+};
+export type AegisEngineVaultLedgerAction = (AegisEngineActivityActionBase & {
+    kind: 'vault_created';
+    owner: Address;
+}) | (AegisEngineActivityActionBase & {
+    kind: 'vault_burned';
+    /** Executor/periphery address, not necessarily the vault owner. */
+    caller: Address;
+}) | (AegisEngineActivityActionBase & {
+    kind: 'vault_locked';
+    /** Historical LTV at this lock; null is unknown, not zero. */
+    ltvPips: number | null;
+}) | (AegisEngineActivityActionBase & {
+    kind: 'debt_modified';
+    principalDeltaRequestedRaw: string;
+    principalDeltaActualRaw: string;
+    borrowIndexWad: string;
+    deltaIdle0Raw: string;
+    deltaIdle1Raw: string;
+}) | (AegisEngineActivityActionBase & {
+    kind: 'idle_modified';
+    deltaAmount0Raw: string;
+    deltaAmount1Raw: string;
+}) | (AegisEngineActivityActionBase & {
+    kind: 'vault_micro_liquidated';
+    caller: Address;
+    zeroForOne: boolean;
+    swapDelta0Raw: string;
+    swapDelta1Raw: string;
+    debtRepaidRlRaw: string;
+    idleDelta0Raw: string;
+    idleDelta1Raw: string;
+    keeperFee0Raw: string;
+    keeperFee1Raw: string;
+    initialLtvPips: number | null;
+});
+export type AegisEngineLendLedgerAction = (AegisEngineActivityActionBase & {
+    kind: 'deposit' | 'withdraw';
+    deltaSharesRaw: string;
+    deltaAmount0Raw: string;
+    deltaAmount1Raw: string;
+}) | (AegisEngineActivityActionBase & {
+    kind: 'transfer_in' | 'transfer_out';
+    sharesRaw: string;
+    counterparty: Address;
+});
+export type AegisEngineActivityMarketState = {
+    marketId: string | null;
+    marketName: string | null;
+    poolId: Hex;
+    borrowIndexWad: string | null;
+    lastAccrueTimestamp: number | null;
+    ratePerSecondWad: string | null;
+    rateUpdatedAt: string | null;
+    totalRlBorrowed: string | null;
+    shareTotalSupply: string | null;
+    warnings: string[];
+};
+export type AegisEnginePositionVaultActivity = {
+    vaultId: string;
+    poolId: Hex;
+    marketId: string | null;
+    marketName: string | null;
+    createdAt: string | null;
+    burnedAt: string | null;
+    /** Oldest-first on-chain execution order. */
+    actions: AegisEngineVaultLedgerAction[];
+};
+export type AegisEnginePositionLendActivity = {
+    poolId: Hex;
+    marketId: string | null;
+    marketName: string | null;
+    /** Oldest-first on-chain execution order. */
+    actions: AegisEngineLendLedgerAction[];
+};
+/** Wallet-scoped action ledger returned by GET /v1/engine/positions/activity.
+ * Raw amount strings preserve the backend's exact signed bigint wire values;
+ * this endpoint does not synthesize USD values. */
+export type AegisEnginePositionActivitySnapshot = {
+    schemaVersion: '1';
+    chainId: number;
+    account: Address;
+    marketState: AegisEngineActivityMarketState[];
+    /** Newest-first by numeric vault id; burned vaults remain present. */
+    vaults: AegisEnginePositionVaultActivity[];
+    /** Ascending by pool id. */
+    lend: AegisEnginePositionLendActivity[];
+    totals: {
+        vaultCount: number;
+        lendMarketCount: number;
+        vaultActionCount: number;
+        lendActionCount: number;
+    };
+    freshness: {
+        source: 'subgraph';
+        /** Oldest indexed block across all pages; null when any page omitted it. */
+        blockNumber: number | null;
+    };
+};
+export type AegisEngineBorrowPositionHydration = {
+    positionId: string;
+    vaultId: bigint;
+} & ({
+    status: 'ok';
+    vault: {
+        poolId: Hex;
+        owner: Address;
+        /** Principal debt in rL units. */
+        rL: bigint;
+        /** Accrued debt in L units at this hydration frame. */
+        debtLLatest: bigint;
+        idle0: bigint;
+        idle1: bigint;
+        /** Null when the vault has no debt, never a synthetic zero. */
+        ltvPipsLatest: bigint | null;
+        maxLtvPips: number;
+        hardLtvPips: number;
+    };
+} | {
+    status: 'failed';
+    reason: 'read-error' | 'owner-mismatch' | 'vault-burned';
+    detail?: string;
+});
+export type AegisEngineLendPositionHydration = {
+    positionId: string;
+    account: Address;
+    poolId: Hex;
+} & ({
+    status: 'ok';
+    shareBalance: bigint;
+    totalShares: bigint;
+    sharePriceWad: bigint;
+    equityLWad: bigint;
+} | {
+    status: 'failed';
+    reason: 'read-error';
+    detail?: string;
+});
+export type AegisEnginePositionsHydration = {
+    /** One block-pinned frame shared by every borrow and lend result. */
+    frame: AegisEngineReadFrame;
+    borrowPositions: AegisEngineBorrowPositionHydration[];
+    lendPositions: AegisEngineLendPositionHydration[];
+};
+export type AegisEnginePositionsHydrationInput = {
+    publicClient: PublicClient;
+    chainId: number;
+    expectedAccount: Address;
+    positions: readonly AegisEnginePosition[];
+    lendPositions: readonly AegisEngineLendSharesPosition[];
+    signal?: AbortSignal;
+};
+export type AegisEngineRestSource = {
+    kind: 'rest';
+    baseUrl: string;
+    headers?: Record<string, string>;
+    /**
+     * Maximum time for a shared REST request, including response-body parsing.
+     * Consumer abort signals remain isolated from the shared request. Defaults
+     * to 10 seconds.
+     */
+    timeoutMs?: number;
+};
+/**
+ * Markets supplied inline by the host. No network call is made — the source is
+ * returned as-is (filtered to the active chain). Useful for offline demos,
+ * deterministic tests/screenshots, and partners who already hold market
+ * metadata and only want the widget to own quoting/execution.
+ */
+export type AegisEngineStaticSource = {
+    kind: 'static';
+    markets: AegisEngineMarket[];
+    positions?: AegisEnginePosition[];
+    lendPositions?: AegisEngineLendSharesPosition[];
+};
+export type AegisEngineDataSource = AegisEngineRestSource | AegisEngineStaticSource;
+export type AegisEngineMarketReadInput = {
+    publicClient: PublicClient;
+    market: AegisEngineMarket;
+};
+/** Public, SDK-independent snapshot facts used by Core's lend quote path. */
+export type AegisEngineProtocolMarket = {
+    poolId: Hex;
+    poolKey: AegisEngineMarket['poolKey'];
+    initialized: boolean;
+    maxLtvPips: number;
+    hardLtvPips: number;
+    borrowIndexWad: bigint;
+    equityLWad: bigint;
+    borrowedLWad: bigint;
+};
+export type AegisEnginePoolState = {
+    sqrtPriceX96: bigint;
+    tick: number;
+    protocolFee: number;
+    lpFee: number;
+    liquidity: bigint;
+};
+export type AegisEngineMarketSnapshot = {
+    market: AegisEngineProtocolMarket;
+    poolState: AegisEnginePoolState;
+    sharePriceWadLatest: bigint;
+    thresholds: {
+        maxLtvPips: number;
+        hardLtvPips: number;
+    };
+};
+export type AegisEngineReadFrame = {
+    blockNumber: bigint;
+    blockTimestamp: bigint;
+    /** Local wall-clock time when the frame was assembled, in Unix milliseconds. */
+    observedAt: number;
+};
+export type AegisEngineVersion = 'v0.4.0' | 'v1.0.2';
+export type AegisEngineBorrowMarketContext = {
+    poolId: Hex;
+    poolKey: AegisEngineMarket['poolKey'];
+    sqrtPriceX96: bigint;
+    tickCurrent: number;
+    tickSpacing: number;
+    inRangeLiquidity: bigint;
+    borrowIndexWad: bigint;
+    equityLWad: bigint;
+    borrowedLWad: bigint;
+    maxLtvPips: number;
+    hardLtvPips: number;
+    currentRatePerSecWad: bigint;
+    decimals0: number;
+    decimals1: number;
+};
+/**
+ * In-frame authorization evidence read alongside the borrow context when it
+ * is hydrated with an owner. Structural mirror of the SDK's
+ * `BorrowExecutionEvidence`; quotes pass it back verbatim so the SDK can
+ * gate its guarded call against the same block.
+ */
+export type AegisEngineBorrowExecutionEvidence = {
+    owner: Address;
+    vaultId: bigint | null;
+    chainId: number;
+    permit2: Address;
+    ownerOnChain: Address | null;
+    vaultPoolId: Hex | null;
+    routerApproved: boolean;
+    router: Address;
+    vaultRegistry: Address;
+    blockNumber: bigint;
+};
+export type AegisEngineBorrowQuoteContext = {
+    chainId: number;
+    version: AegisEngineVersion;
+    poolId: Hex;
+    market: AegisEngineBorrowMarketContext;
+    aprProjection: {
+        chainId: number;
+        version: AegisEngineVersion;
+        rateOracleAddress: Address;
+        fullUtilRate: bigint;
+    };
+    frame: AegisEngineReadFrame;
+    /** Present only when the context read was asked to hydrate evidence. */
+    execution: AegisEngineBorrowExecutionEvidence | null;
+};
+export type AegisEngineQuoteBase = {
+    publicClient: PublicClient;
+    market: AegisEngineMarket;
+    owner: Address;
+    inputIsToken0: boolean;
+    slippageBps: number;
+    deadline?: bigint;
+    quoteTtlSeconds?: bigint;
+    signal?: AbortSignal;
+    permit?: AegisEngineSignedPermitBatch | null;
+};
+export type AegisEngineDepositQuoteInput = AegisEngineQuoteBase & {
+    amountIn: bigint;
+};
+/**
+ * Live snapshot of an already-open borrow vault, in the pool's real token
+ * orientation. Passing it to a borrow quote sizes the new debt against the
+ * vault's existing idle and debt and encodes the recipe on the same `vaultId`
+ * (a `modifyVault`) instead of minting a fresh vault. Mirrors the SDK's
+ * `BorrowVaultContext`.
+ */
+export type AegisEngineBorrowVaultContext = {
+    vaultId: bigint;
+    poolId: Hex;
+    owner: Address;
+    /** Idle balance of currency0 (token wei). */
+    x0: bigint;
+    /** Idle balance of currency1 (token wei). */
+    y0: bigint;
+    /** Existing debt principal in rL units. */
+    rL0: bigint;
+};
+export type AegisEngineBorrowQuoteInput = AegisEngineQuoteBase & {
+    collateralIn: bigint;
+    borrowOut: bigint;
+    tauPips?: number;
+    /**
+     * Target LTV as a percentage of the live market maximum. Core resolves this
+     * only after reading the block-pinned market context, so stale REST
+     * thresholds cannot turn a conservative percentage into the live maximum.
+     */
+    tauPercentOfMaxLtv?: number;
+    comfortCapLtvPips?: number;
+    /**
+     * When present, borrow into this existing vault instead of opening a new one.
+     * Core validates its pool/owner against the market before sizing.
+     */
+    vault?: AegisEngineBorrowVaultContext | null;
+    /**
+     * Hydrate in-frame authorization evidence for `owner` and request the SDK's
+     * guarded call. Submit paths set this; indicative display quotes omit it and
+     * receive `tx: null` (`executable` stays false — an unproven quote never
+     * labels itself executable).
+     */
+    withExecutionEvidence?: boolean;
+};
+export type AegisEngineBorrowCapacityInput = Omit<AegisEngineQuoteBase, 'owner' | 'deadline' | 'permit'> & {
+    collateralIn: bigint;
+    /** Optional output-first target. When supplied, the result includes the
+     *  collateral floor for the deterministic no-swap path. */
+    borrowOut?: bigint;
+    tauPips?: number;
+    /** See `AegisEngineBorrowQuoteInput.tauPercentOfMaxLtv`. */
+    tauPercentOfMaxLtv?: number;
+    /** Existing vault to size headroom against; see `AegisEngineBorrowQuoteInput.vault`. */
+    vault?: AegisEngineBorrowVaultContext | null;
+};
+export type AegisEngineDepositQuoteResult = {
+    feasible: boolean;
+    executable: boolean;
+    infeasibleReason?: 'invalid-input' | 'quote-unavailable' | 'insufficient-output' | 'zero-liquidity' | 'builder-error';
+    /** SDK recipe input retained for diagnostics. Use `tx` on the enclosing
+     * Core quote for execution instead of encoding this value downstream. */
+    encodeInput: unknown | null;
+    call: {
+        calldata: Hex;
+        value: bigint;
+    } | null;
+    swap: {
+        needed: boolean;
+        amountIn: bigint;
+        isToken0: boolean;
+        amountOut: bigint;
+        minAmountOut: bigint;
+    } | null;
+    deposit: {
+        amount0: bigint;
+        amount1: bigint;
+        liquidityDelta: bigint;
+        expectedShares: bigint;
+        minDeltaShares: bigint;
+        expectedSharePriceWad: bigint;
+        amount0Max: bigint;
+        amount1Max: bigint;
+    } | null;
+    expectedSharePriceWad: bigint;
+    routeSummary: string | null;
+    priceImpactBps: number | null;
+    approvalPlan: {
+        approvalType: string;
+        token: Address;
+        amount: bigint;
+        required: boolean;
+        nativeValue: bigint;
+        spender?: Address;
+    };
+    gateFailures: readonly AegisEngineLifecycleGateFailure[];
+    display: {
+        lendAprPct: number | null;
+        lendApyPct: number | null;
+    };
+    apyEstimate: unknown | null;
+    postDeposit: {
+        basis: 'projected-post-deposit';
+        aprPct: number | null;
+        apyPct: number | null;
+        unavailableReason: string | null;
+        assumptions: readonly string[];
+    } | null;
+    frame: AegisEngineReadFrame | null;
+    warnings: string[];
+    expiresAt: bigint;
+    quoteCount: number;
+};
+export type AegisEngineDepositQuote = {
+    kind: 'lend';
+    market: AegisEngineMarket;
+    inputToken: AegisEngineToken;
+    quote: AegisEngineDepositQuoteResult;
+    tx: AegisEnginePreparedTransaction | null;
+};
+export type AegisEngineBorrowRecipeEncodeInput = {
+    maxLtvPips: number;
+};
+/** Days until liquidation, or `'INF'` when the position never drifts in. */
+export type AegisEngineDaysToLiquidation = number | 'INF';
+export type AegisEngineBorrowQuoteResult = {
+    feasible: boolean;
+    executable: boolean;
+    /** Failed execution gates; `[]` when no evidence was supplied. */
+    gateFailures: readonly AegisEngineLifecycleGateFailure[];
+    infeasibleReason?: string;
+    encodeInput: AegisEngineBorrowRecipeEncodeInput | null;
+    call: {
+        calldata: Hex;
+        value: bigint;
+    } | null;
+    recipe: {
+        encodeInput: AegisEngineBorrowRecipeEncodeInput | null;
+    };
+    swap: {
+        needed: boolean;
+        amountIn: bigint;
+        isToken0: boolean;
+        minAmountOut: bigint;
+    } | null;
+    finalVault: {
+        xV: bigint;
+        yV: bigint;
+        gammaTotalLTarget: bigint;
+        gammaNewLTarget: bigint;
+        rL0Post: bigint;
+        gammaTotalLPostRounded: bigint;
+    } | null;
+    display: {
+        postBorrowLtvPips: number | null;
+        preBorrowAprPct: number | null;
+        postBorrowAprPct: number | null;
+        postBorrowUtilPips: bigint | null;
+        /**
+         * Days until LTV drifts into the liquidation threshold at the CURRENT
+         * per-second rate. Engine LTV is `γ_L / √(x·y)` — both terms are liquidity
+         * amounts, so it carries no price and only interest accrual moves it
+         * toward the threshold. Time, not price, is this protocol's liquidation
+         * axis, and this is the only horizon the SDK will state.
+         * `'INF'` = the rate is zero and the position never drifts in; null = the
+         * market's rate is unavailable (non-canonical oracle), never a fabricated
+         * horizon.
+         */
+        daysToLiquidationAtCurrentApr: AegisEngineDaysToLiquidation | null;
+        /** Same horizon at the projected post-borrow APR; null unless the rate
+         *  projection resolved. */
+        postBorrowDaysToLiquidation: AegisEngineDaysToLiquidation | null;
+    };
+    frame: AegisEngineReadFrame | null;
+    expiresAt: bigint | null;
+};
+export type AegisEngineBorrowQuote = {
+    kind: 'borrow';
+    market: AegisEngineMarket;
+    collateralToken: AegisEngineToken;
+    borrowToken: AegisEngineToken;
+    /** Thresholds read in the same live frame used to build the quote. */
+    thresholds: {
+        maxLtvPips: number;
+        hardLtvPips: number;
+    };
+    quote: AegisEngineBorrowQuoteResult;
+    costProjection: AegisEngineBorrowCostProjection;
+    tx: AegisEnginePreparedTransaction | null;
+};
+export type AegisEnginePositionActionKind = 'repay' | 'close' | 'withdraw' | 'redeem';
+export type AegisEngineBorrowPositionTarget = {
+    kind: 'borrow_vault';
+    positionId: string;
+    chainId: number;
+    marketId: string | null;
+    poolId: Hex;
+    vaultId: bigint;
+};
+export type AegisEngineLendPositionTarget = {
+    kind: 'lend_shares';
+    positionId: string;
+    chainId: number;
+    marketId: string | null;
+    poolId: Hex;
+};
+/**
+ * Stable identity for an already-open Engine position. Keeping this distinct
+ * from the new Borrow/Lend draft prevents a manage action from silently
+ * falling back to `vault: null` (open a new vault).
+ */
+export type AegisEnginePositionTarget = AegisEngineBorrowPositionTarget | AegisEngineLendPositionTarget;
+export type AegisEngineLifecycleGateFailure = {
+    gate: string;
+    [key: string]: unknown;
+};
+export type AegisEngineLifecycleApprovalPlan = {
+    approvalType: 'permit2';
+    token: Address;
+    amount: bigint;
+    required: boolean;
+    nativeValue: bigint;
+    spender?: Address;
+};
+export type AegisEnginePositionActionQuote = {
+    kind: AegisEnginePositionActionKind;
+    market: AegisEngineMarket;
+    target: AegisEnginePositionTarget;
+    feasible: boolean;
+    executable: boolean;
+    infeasibleReason: string | null;
+    gateFailures: readonly AegisEngineLifecycleGateFailure[];
+    approvals: readonly AegisEngineLifecycleApprovalPlan[];
+    /** Wallet token top-ups required by repay/close. */
+    fromWallet0: bigint;
+    fromWallet1: bigint;
+    /** Expected two-token output for close/redeem, when the quote can price it. */
+    expected: {
+        amount0: bigint;
+        amount1: bigint;
+    } | null;
+    /** Encoded output protection for redeem. Close has no encodable minimum. */
+    minimum: {
+        amount0: bigint;
+        amount1: bigint;
+    } | null;
+    /** Borrow principal affected by repay/close, in rL units. */
+    principalDeltaRl: bigint | null;
+    /** Exact idle token amounts requested by withdraw. */
+    withdraw: {
+        amount0: bigint;
+        amount1: bigint;
+    } | null;
+    /** Engine shares affected by redeem. */
+    sharesDelta: bigint | null;
+    shareBalance: bigint | null;
+    postShareBalance: bigint | null;
+    /**
+     * Live, block-pinned lend exit capacity. Present only for redeem quotes
+     * requested with `shares: "available"`.
+     */
+    redeemAvailability?: {
+        /** Whether the live frame can return the whole position or only part. */
+        mode: 'full' | 'partial';
+        /** Exact shares encoded by this quote. */
+        redeemableShares: bigint;
+        /** Owner balance observed in the same frame. */
+        shareBalance: bigint;
+        /** Shares that remain deposited after this quote executes. */
+        remainingShares: bigint;
+    };
+    expiresAt: bigint;
+    warnings: readonly string[];
+    tx: AegisEnginePreparedTransaction | null;
+};
+type AegisEnginePositionActionQuoteBase = {
+    publicClient: PublicClient;
+    market: AegisEngineMarket;
+    owner: Address;
+    target: AegisEnginePositionTarget;
+    deadline?: bigint;
+    quoteTtlSeconds?: bigint;
+    signal?: AbortSignal;
+};
+export type AegisEngineRepayQuoteInput = AegisEnginePositionActionQuoteBase & {
+    target: AegisEngineBorrowPositionTarget;
+    repayRl?: bigint | 'full';
+    slippageBps: number;
+};
+export type AegisEngineCloseQuoteInput = AegisEnginePositionActionQuoteBase & {
+    target: AegisEngineBorrowPositionTarget;
+};
+export type AegisEngineIdleWithdrawQuoteInput = AegisEnginePositionActionQuoteBase & {
+    target: AegisEngineBorrowPositionTarget;
+    withdraw?: 'all' | {
+        amount0: bigint;
+        amount1: bigint;
+    };
+};
+export type AegisEngineRedeemQuoteInput = AegisEnginePositionActionQuoteBase & {
+    target: AegisEngineLendPositionTarget;
+    /**
+     * `available` quotes the full balance when possible, otherwise the exact
+     * maximum currently supported by unborrowed market equity.
+     */
+    shares?: bigint | 'all' | 'available';
+    slippageBps: number;
+};
+export type AegisEngineBorrowRateBasis = 'projected-post-borrow';
+/** Which rate the liquidation horizon was projected at. */
+export type AegisEngineLiquidationHorizonBasis = 'projected-post-borrow' | 'current-apr';
+export type AegisEngineBorrowCostMissingInput = 'rounded-debt-frame' | 'debt-valuation' | 'usd-valuation-basis' | 'borrow-apr';
+export type AegisEngineBorrowCostLimitation = 'constant-rate-estimate' | 'gas-not-included' | 'collateral-opportunity-cost-not-included' | 'liquidation-risk-not-modeled' | 'repay-quote-not-modeled';
+/**
+ * One SDK `computeVaultStateSnapshot` expressed in the two pool-token
+ * denominations plus the quote's explicit USD basis. "Collateral" here is
+ * the vault's live idle-token value; it intentionally does not invent a value
+ * for attached NFT/LP collateral the SDK snapshot does not expose.
+ */
+export type AegisEngineBorrowVaultValueSnapshot = {
+    collateralValueToken0: number | null;
+    collateralValueToken1: number | null;
+    collateralValueUsd: number | null;
+    debtValueToken0: number | null;
+    debtValueToken1: number | null;
+    debtValueUsd: number | null;
+};
+/**
+ * Display-only economics derived from the exact rounded post-quote debt
+ * frame. This is not an executable repay quote and must never authorize a
+ * transaction.
+ */
+export type AegisEngineBorrowCostProjection = {
+    gammaTotalLPostRounded: bigint | null;
+    /**
+     * Authoritative money comparison from SDK vault-state snapshots. `before`
+     * is null for a first loan (or when an existing vault could not be valued);
+     * `after` is null when the quote did not return a valid final vault.
+     */
+    vaultValues: {
+        before: AegisEngineBorrowVaultValueSnapshot | null;
+        after: AegisEngineBorrowVaultValueSnapshot | null;
+    };
+    /** @deprecated Read `vaultValues.after.debtValueToken0`. */
+    debtValueToken0: number | null;
+    /** @deprecated Read `vaultValues.after.debtValueToken1`. */
+    debtValueToken1: number | null;
+    /** @deprecated Read `vaultValues.after.debtValueUsd`. */
+    debtValueUsd: number | null;
+    usdValuationBasis: 'token0' | 'token1' | null;
+    rate: {
+        aprPct: number | null;
+        basis: AegisEngineBorrowRateBasis | null;
+    };
+    /**
+     * Days until interest accrual drifts LTV into the liquidation threshold.
+     * Engine LTV is `γ_L / √(x·y)` — both terms are liquidity amounts — so price
+     * does not move it and accrual is the only clock. This protocol therefore
+     * has no liquidation PRICE; time is the whole risk axis.
+     *
+     * Feasibility-gated like {@link AegisEngineBorrowCostProjection.rate}: an
+     * infeasible quote can retain display math, and a retained horizon presented
+     * as a liquidation countdown is the worst claim this panel can make.
+     */
+    liquidationHorizon: {
+        days: AegisEngineDaysToLiquidation | null;
+        basis: AegisEngineLiquidationHorizonBasis | null;
+    };
+    constantRateMonthlyCarryUsd: number | null;
+    missingInputs: AegisEngineBorrowCostMissingInput[];
+    limitations: AegisEngineBorrowCostLimitation[];
+};
+export type AegisEngineVaultActivityKind = 'borrow' | 'repay' | 'add-collateral' | 'withdraw-collateral' | 'vault-activity' | 'deposit' | 'withdraw';
+/** One transaction's effect on a position, replayed from the Engine
+ *  subgraph's action ledger. Deltas are signed token base units. `received*`
+ *  is the requested-token amount delivered to the wallet on a borrow,
+ *  identified from the trace's single-token idle withdrawal; null when
+ *  ambiguous. Lend entries ('deposit'/'withdraw') reuse the collateral-delta
+ *  slots for the token amounts moved, with no principal or received leg. */
+export type AegisEngineVaultActivityEntry = {
+    txHash: `0x${string}`;
+    /** Unix seconds. */
+    timestamp: number;
+    kind: AegisEngineVaultActivityKind;
+    /** Signed debt principal change in RL units (no cross-market unit). */
+    principalDeltaRl: bigint;
+    /** Net collateral movement, excluding the identified borrow delivery. */
+    collateralDelta0: bigint;
+    collateralDelta1: bigint;
+    receivedRaw: bigint | null;
+    receivedIsToken0: boolean | null;
+};
+export type AegisEngineBorrowCapacity = {
+    kind: 'borrow-capacity';
+    market: AegisEngineMarket;
+    collateralToken: AegisEngineToken;
+    borrowToken: AegisEngineToken;
+    /** Thresholds read in the same live frame used for capacity math. */
+    thresholds: {
+        maxLtvPips: number;
+        hardLtvPips: number;
+    };
+    tauPips: number;
+    /** Echoes percentage-based sizing; null for an absolute/default tau. */
+    tauPercentOfMaxLtv: number | null;
+    /** Echoed output target used to derive `minimumNoSwapCollateralIn`. */
+    borrowOut: bigint | null;
+    /** Minimum fresh-vault deposit that crosses the SDK's integer no-swap
+     *  boundary. Null when no output target was supplied, no closed-form
+     *  no-swap solution exists, or the market is utilization-capped. */
+    minimumNoSwapCollateralIn: bigint | null;
+    /** Equals `capacity.utilizationPre >= capacity.utilizationCap` at quote
+     *  time. Named (rather than derived by consumers) because the SDK's stage
+     *  classifier can mask a cap block behind preserve-vs-allow reachability
+     *  (`preserve-collateral-blocked`), so `bindingConstraint`/quote reasons
+     *  can't be trusted for it. When true no borrow executes for any deposit
+     *  and no collateral floor is published. */
+    utilizationCapped: boolean;
+    capacity: {
+        yMaxLtv: bigint;
+        yMaxFromUtilization: bigint | null;
+        yMaxNoDebt: bigint;
+        yMaxBorrow: bigint;
+        yMaxEffective: bigint;
+        yMaxNoDebtAtHaircut: bigint;
+        yMaxBorrowAtHaircut: bigint;
+        /** Haircut-aware maximum borrow output in receive-token base units. */
+        yMaxEffectiveAtHaircut: bigint;
+        quoteHaircutBpsApplied: number;
+        collateralPolicyApplied: 'allow-collateral-swap' | 'preserve-collateral';
+        yKnee: bigint | null;
+        utilizationPre: number;
+        utilizationCap: number;
+        minDebtFloorRl: bigint;
+        bindingConstraint: 'idle' | 'ltv-no-new-borrow' | 'zero-debt-swap' | 'ltv' | 'utilization' | 'regime-b' | 'min-debt' | 'unknown';
+        bindingConstraintAtHaircut?: 'idle' | 'ltv-no-new-borrow' | 'zero-debt-swap' | 'ltv' | 'utilization' | 'regime-b' | 'min-debt' | 'unknown';
+        dMinNoSwap: bigint | null;
+        gammaNewLAtEffectiveMax: bigint | null;
+        deltaLWadAtEffectiveMax: bigint | null;
+    };
+};
+export type AegisEnginePreparedTransaction = {
+    to: Address;
+    data: Hex;
+    value: bigint;
+};
+export type AegisEngineSignedPermitBatch = SignedPermitBatch;
+export type AegisEngineWalletSession = WalletSession;
+export type AegisEngineActionCallbacks = {
+    onStatus?: (status: 'approving' | 'signing' | 'submitting' | 'success' | 'idle') => void;
+    onTxHash?: (hash: Hex | null) => void;
+    onSubmitted?: (hash: Hex) => void;
+};
+export type AegisEngineTransactionResult = {
+    hash: Hex;
+    explorerUrl: string;
+    receipt: TransactionReceipt;
+    summary: {
+        transactionHash: Hex;
+        blockNumber: bigint;
+        gasUsed: bigint;
+        effectiveGasPrice: bigint;
+        feeWei: bigint;
+    };
+};
+export type AegisEngineApprovalInput = {
+    wallet: AegisEngineWalletSession;
+    publicClient: PublicClient;
+    activeChain: AegisSwapChainConfig;
+    token: AegisEngineToken;
+    permit2: Address;
+    router: Address;
+    amount: bigint;
+    approvalMode?: 'exact' | 'max';
+    permit2AuthorizationMode?: 'signature' | 'spending-cap';
+    onStatus?: AegisEngineActionCallbacks['onStatus'];
+};
+export type AegisEngineSendInput = {
+    wallet: AegisEngineWalletSession;
+    publicClient: PublicClient;
+    activeChain: AegisSwapChainConfig;
+    tx: AegisEnginePreparedTransaction;
+    /**
+     * Absolute Unix timestamp encoded into the prepared Engine transaction.
+     * When present, the send boundary refuses to open the wallet if too little
+     * validity remains.
+     */
+    expiresAt?: bigint;
+    /** Required validity remaining before a wallet request may be opened. */
+    minimumValiditySeconds?: bigint;
+    permit2Context?: {
+        token: AegisEngineToken;
+        permit2: Address;
+        router: Address;
+        amount: bigint;
+        inlinePermit: boolean;
+    };
+} & AegisEngineActionCallbacks;
+export {};