@aegis-engine/core 0.4.0 → 0.5.0

package/dist/engine/types.d.ts

@@ -2,6 +2,7 @@ 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';
+import type { AegisEngineTapInfeasibleReason, AegisEngineTapRootPolicy } from './trade/sizing.js';
 export type AegisEngineMode = 'lend' | 'borrow' | 'positions';
 export type AegisEngineMarketSource = 'rest' | 'static';
 export type AegisEngineMarketStatus = 'enabled' | 'disabled' | 'hidden' | 'malformed';
@@ -254,12 +255,21 @@ export type AegisEngineVaultLedgerAction = (AegisEngineActivityActionBase & {
     initialLtvPips: number | null;
 });
 export type AegisEngineLendLedgerAction = (AegisEngineActivityActionBase & {
-    kind: 'deposit' | 'withdraw';
+    kind: 'deposit';
     deltaSharesRaw: string;
     deltaAmount0Raw: string;
     deltaAmount1Raw: string;
 }) | (AegisEngineActivityActionBase & {
-    kind: 'transfer_in' | 'transfer_out';
+    kind: 'withdraw';
+    deltaSharesRaw: string;
+    deltaAmount0Raw: string;
+    deltaAmount1Raw: string;
+}) | (AegisEngineActivityActionBase & {
+    kind: 'transfer_in';
+    sharesRaw: string;
+    counterparty: Address;
+}) | (AegisEngineActivityActionBase & {
+    kind: 'transfer_out';
     sharesRaw: string;
     counterparty: Address;
 });
@@ -275,6 +285,20 @@ export type AegisEngineActivityMarketState = {
     shareTotalSupply: string | null;
     warnings: string[];
 };
+/** Indexed lot facts derived from the activity ledger + market borrow index.
+ *  Raw rL / wad strings only — this plane does not synthesize USD. */
+export type AegisEngineActivityLotDisplay = {
+    deposited: {
+        raw: string;
+        side: 0 | 1;
+    } | null;
+    principalRaw: string | null;
+    openBorrowIndexWad: string | null;
+    indexedBorrowIndexWad: string | null;
+    debtAtOpenRl: string | null;
+    debtIndexedRl: string | null;
+    interestAccruedRl: string | null;
+};
 export type AegisEnginePositionVaultActivity = {
     vaultId: string;
     poolId: Hex;
@@ -284,6 +308,8 @@ export type AegisEnginePositionVaultActivity = {
     burnedAt: string | null;
     /** Oldest-first on-chain execution order. */
     actions: AegisEngineVaultLedgerAction[];
+    /** Present on REST-parsed snapshots. Hand-built fixtures may omit it. */
+    display?: AegisEngineActivityLotDisplay;
 };
 export type AegisEnginePositionLendActivity = {
     poolId: Hex;
@@ -294,7 +320,8 @@ export type AegisEnginePositionLendActivity = {
 };
 /** 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. */
+ * this endpoint does not synthesize USD values. Core attaches indexed lot
+ * `display` fields after parse from the ledger already in the payload. */
 export type AegisEnginePositionActivitySnapshot = {
     schemaVersion: '1';
     chainId: number;
@@ -311,11 +338,51 @@ export type AegisEnginePositionActivitySnapshot = {
         lendActionCount: number;
     };
     freshness: {
-        source: 'subgraph';
+        source: 'subgraph' | 'static';
         /** Oldest indexed block across all pages; null when any page omitted it. */
         blockNumber: number | null;
     };
 };
+/** Off-chain opening intent for one confirmed Long/Short transaction. The
+ * Engine transaction does not encode its target scenario or average leverage,
+ * so consumers may persist this small record and join it back to the indexed
+ * opening transaction. Indexed actions remain authoritative for direction and
+ * entry price. */
+export type AegisEngineTradePositionIntent = {
+    schemaVersion: '1';
+    chainId: number;
+    account: Address;
+    marketId: string;
+    poolId: Hex;
+    txHash: Hex;
+    direction: AegisEngineTradeDirection;
+    /** Average leverage over the reviewed move to `targetPrice`. */
+    averageLeverage: number;
+    /** Reviewed target scenario in token1 per token0. Not an on-chain order. */
+    targetPrice: number;
+    horizonSeconds: number;
+    recordedAt: string;
+};
+/** Durable Long/Short identity reconstructed from one vault's indexed opening
+ * transaction. Optional scenario fields are present only when a matching
+ * off-chain intent record survived; they never override indexed direction or
+ * entry price. */
+export type AegisEngineTradePositionStrategy = {
+    kind: 'trade';
+    vaultId: string;
+    poolId: Hex;
+    direction: AegisEngineTradeDirection;
+    openTxHash: Hex;
+    openedAt: number;
+    /** Executed opening spot, token1 per token0, derived from DebtModified. */
+    entryPrice: number | null;
+    /** Reviewed average leverage to the target scenario, not current leverage. */
+    averageLeverage: number | null;
+    /** Reviewed scenario only. Null when no matching intent record is available. */
+    targetPrice: number | null;
+    horizonSeconds: number | null;
+    source: 'indexed-actions' | 'indexed-actions+stored-intent';
+};
 export type AegisEngineBorrowPositionHydration = {
     positionId: string;
     vaultId: bigint;
@@ -391,6 +458,9 @@ export type AegisEngineStaticSource = {
     markets: AegisEngineMarket[];
     positions?: AegisEnginePosition[];
     lendPositions?: AegisEngineLendSharesPosition[];
+    /** Vault action ledgers for the static positions. Lets offline demos and
+     *  tests reconstruct Long/Short identity exactly like the REST ledger does. */
+    vaultActivity?: AegisEnginePositionVaultActivity[];
 };
 export type AegisEngineDataSource = AegisEngineRestSource | AegisEngineStaticSource;
 export type AegisEngineMarketReadInput = {
@@ -424,8 +494,28 @@ export type AegisEngineMarketSnapshot = {
         hardLtvPips: number;
     };
 };
+/**
+ * Live pool mid for one market in token1-per-token0 display units — the same
+ * price plane trade quotes size against (`Ppool` from `sqrtPriceX96`), read
+ * on-chain. Indexed token `priceUsd` metadata is a different, slower plane;
+ * never mix the two in one comparison.
+ */
+export type AegisEngineMarketMark = {
+    poolId: Hex;
+    chainId: number;
+    /** token1 per token0, display units. */
+    price: number;
+    sqrtPriceX96: bigint;
+    /** Local wall-clock read time, in Unix milliseconds. */
+    observedAt: number;
+};
 export type AegisEngineReadFrame = {
     blockNumber: bigint;
+    /**
+     * Canonical identity of `blockNumber`. SDK-backed reads always provide it;
+     * optional only while legacy hosts migrate hand-built quote contexts.
+     */
+    blockHash?: Hex;
     blockTimestamp: bigint;
     /** Local wall-clock time when the frame was assembled, in Unix milliseconds. */
     observedAt: number;
@@ -681,6 +771,143 @@ export type AegisEngineBorrowQuote = {
     costProjection: AegisEngineBorrowCostProjection;
     tx: AegisEnginePreparedTransaction | null;
 };
+export type AegisEngineTradeDirection = 'long' | 'short';
+export type AegisEngineTradeOpenQuoteInput = {
+    publicClient: PublicClient;
+    market: AegisEngineMarket;
+    owner: Address;
+    direction: AegisEngineTradeDirection;
+    /** Collateral in base units of the token named by `inputIsToken0`. */
+    collateralIn: bigint;
+    inputIsToken0: boolean;
+    /** Horizon the opening LTV is derived from, in seconds. */
+    horizonSeconds: number;
+    /**
+     * Magnitude of the move to the target price, relative to the pool price.
+     * `direction` sets the sign; a zero move has no target and is rejected.
+     */
+    priceMove: number;
+    /**
+     * Absolute LTV ceiling, independent of the horizon. Defaults to the live
+     * market open cap, where only the horizon and the solver's own margin bind.
+     */
+    tauPips?: number;
+    /** Average leverage to open at. Omitted opens the band's maximum. */
+    leverage?: number;
+    /** @deprecated Ignored. Spec-0168 always selects the lower-debt frontier. */
+    rootPolicy?: AegisEngineTapRootPolicy;
+    slippageBps: number;
+    deadline?: bigint;
+    /** Abort a superseded indicative quote between its block-pinned phases. */
+    signal?: AbortSignal;
+    /** Submit paths set this after changing router authorization. */
+    forceExecutionEvidenceRefresh?: boolean;
+};
+export type AegisEngineTradeOpenInfeasibleReason = AegisEngineTapInfeasibleReason['kind']
+/** The chosen root's swap trades against the requested direction at entry. */
+ | 'swap-direction-mismatch'
+/** Post-borrow idle cannot fund the swap the chosen root needs. */
+ | 'insufficient-idle'
+/** Principal below the engine's `lockVault` minimum; it would revert. */
+ | 'debt-below-minimum' | 'delta-above-cap'
+/** LTV recomputed from the encoded amounts is at or above the open cap. */
+ | 'ltv-above-max'
+/** The swap was quoted at a different block than the sizing state. */
+ | 'stale-frame';
+/** Actionable bounds for a rejected quote. Each field is null when the
+ *  rejection did not produce one. */
+export type AegisEngineTradeOpenLimits = {
+    /** Highest average leverage on the openable debt-minimizing frontier. */
+    maxLeverage: number | null;
+    /** Lowest average leverage on that frontier. */
+    minLeverage: number | null;
+    /** Largest collateral the utilization cap still finances, in base units. */
+    maxCollateralIn: bigint | null;
+};
+export type AegisEngineTradeOpenPosition = {
+    /** Exposure ratio the α band settled on. */
+    alpha: number;
+    /** Average leverage over the move to the target price, evaluated from the
+     *  exact balances the router locks. Always positive. */
+    leverage: number;
+    /** Instantaneous leverage at entry from the exact locked balances. */
+    localLeverage: number;
+    /** Leverage as price runs away from entry, from the exact locked balances. */
+    asymptoticLeverage: number;
+    /** Opening LTV from the sized band. */
+    ltvPips: number;
+    /** LTV recomputed from the exact encoded amounts — what `lockVault` checks. */
+    executionLtvPips: number;
+    /**
+     * Days until interest accrual drifts LTV into the liquidation threshold.
+     * Realized at the position's LTV, never the caller's `horizonSeconds`: the
+     * solver holds a margin below the cap that stretches short horizons.
+     */
+    daysToLiquidation: AegisEngineDaysToLiquidation;
+    /** Simple interest on the exact execution debt over the horizon at the rate
+     *  used to size the quote, in token1 base units. */
+    interestCostToken1: bigint;
+    /**
+     * `min E(P) / E_0` over ALL prices from the exact locked balances. Equity is
+     * convex in `√P` with a strictly negative discriminant, so this floor is never
+     * zero and there is no liquidation price — only this ratio and
+     * {@link daysToLiquidation}.
+     */
+    worstEquityRatio: number;
+    entryPrice: number;
+    targetPrice: number;
+    /** Gross return from exact entry equity to target equity, before horizon
+     *  interest. The encoded swap output floor is already reflected in both. */
+    grossReturnAtTargetPct: number;
+    /** Borrow principal in rL units. */
+    principalDeltaRl: bigint;
+    /** Vault idle at lock, in base units — the collateral `lockVault` values. */
+    collateral0: bigint;
+    collateral1: bigint;
+};
+export type AegisEngineTradeOpenSwap = {
+    inputIsToken0: boolean;
+    amountIn: bigint;
+    amountOutQuoted: bigint;
+    /** Encoded on-chain floor; also the exact amount redeposited to the vault. */
+    amountOutMinimum: bigint;
+    /** Execution price against the pool mid, in basis points. Positive when the
+     *  pool fills worse than mid. */
+    priceImpactBps: number;
+    /** True when vault idle, not the solver, set `amountIn`. */
+    clampedByIdle: boolean;
+};
+/**
+ * One block-pinned tap open: create a vault, deposit, borrow, swap the borrow
+ * into the target exposure, and lock — as a single router call.
+ */
+export type AegisEngineTradeOpenQuote = {
+    kind: 'trade-open';
+    market: AegisEngineMarket;
+    direction: AegisEngineTradeDirection;
+    collateralToken: AegisEngineToken;
+    /** Thresholds read in the same live frame used to size the position. */
+    thresholds: {
+        maxLtvPips: number;
+        hardLtvPips: number;
+    };
+    feasible: boolean;
+    executable: boolean;
+    infeasibleReason: AegisEngineTradeOpenInfeasibleReason | null;
+    limits: AegisEngineTradeOpenLimits;
+    gateFailures: readonly AegisEngineLifecycleGateFailure[];
+    approvals: readonly AegisEngineLifecycleApprovalPlan[];
+    position: AegisEngineTradeOpenPosition | null;
+    /** Null when the borrow already delivers the target mix. */
+    swap: AegisEngineTradeOpenSwap | null;
+    deposit: {
+        amount0: bigint;
+        amount1: bigint;
+    };
+    frame: AegisEngineReadFrame;
+    expiresAt: bigint;
+    tx: AegisEnginePreparedTransaction | null;
+};
 export type AegisEnginePositionActionKind = 'add-collateral' | 'repay' | 'close' | 'withdraw' | 'redeem';
 export type AegisEngineBorrowPositionTarget = {
     kind: 'borrow_vault';
@@ -965,6 +1192,70 @@ export type AegisEngineTransactionResult = {
         feeWei: bigint;
     };
 };
+/** Wallet actions that can precede a fresh Engine Long/Short position. */
+export type AegisEngineAuthorizationStepKind = 'vault-operator' | 'erc20-reset' | 'erc20-permit2' | 'permit2-router' | 'open-position';
+export type AegisEngineAuthorizationStepStatus = 'satisfied' | 'required';
+export type AegisEngineAuthorizationStep = {
+    /** Stable semantic id. A plan contains at most one step of each kind. */
+    id: AegisEngineAuthorizationStepKind;
+    kind: AegisEngineAuthorizationStepKind;
+    status: AegisEngineAuthorizationStepStatus;
+    /** Every current Long/Short authorization is an on-chain wallet transaction. */
+    walletAction: 'transaction';
+    /** Contract the wallet action targets. */
+    target: Address;
+    /** Contract receiving authority, when distinct from the target. */
+    spender: Address | null;
+    /** Token governed by this step. Null for vault and final-position actions. */
+    token: AegisEngineToken | null;
+    /** Current on-chain allowance, when the step governs a token amount. */
+    currentAmount: bigint | null;
+    /** Amount a required wallet action will set. Null for satisfied or non-token actions. */
+    requestedAmount: bigint | null;
+    /** Permit2 expiry in Unix seconds. Null when the authority has no expiry field. */
+    expiration: number | null;
+    /** Whether authority remains after the requested position is opened. */
+    persistent: boolean;
+    scope: 'all-vaults' | 'token-allowance-reset' | 'exact-token-amount' | 'existing-token-amount' | 'maximum-token-amount' | 'position-open';
+};
+export type AegisEngineAuthorizationPlan = {
+    kind: 'engine-authorization-plan';
+    /** Fresh Long/Short only. Do not widen in place for borrow or lend. */
+    operation: 'trade-open';
+    account: Address;
+    chainId: number;
+    marketId: string;
+    token: AegisEngineToken;
+    amount: bigint;
+    approvalMode: 'exact' | 'max';
+    router: Address;
+    permit2: Address;
+    vaultRegistry: Address;
+    steps: readonly AegisEngineAuthorizationStep[];
+    /** Missing permission grants, excluding a zero-first reset and the final open. */
+    missingPermissionCount: number;
+    /** True when the known wallet chain adds a network-switch request; null when unknown. */
+    walletChainSwitchRequired: boolean | null;
+    /** Sequential transaction request count. A network switch is reported separately. */
+    walletPromptCount: number;
+    /** True when only the final position transaction remains. */
+    readyForOpen: boolean;
+};
+/** Fresh Long/Short only. No `vaultId`: this plan reads blanket operator approval. */
+export type AegisEngineAuthorizationPlanInput = {
+    publicClient: PublicClient;
+    market: AegisEngineMarket;
+    owner: Address;
+    /** Current wallet chain. Omit or pass null when it has not resolved yet. */
+    walletChainId?: number | null;
+    token: AegisEngineToken;
+    amount: bigint;
+    approvalMode?: 'exact' | 'max';
+};
+export type AegisEngineAuthorizationProgress = {
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'requesting' | 'confirmed';
+};
 export type AegisEngineApprovalInput = {
     wallet: AegisEngineWalletSession;
     publicClient: PublicClient;
@@ -975,13 +1266,24 @@ export type AegisEngineApprovalInput = {
     amount: bigint;
     approvalMode?: 'exact' | 'max';
     permit2AuthorizationMode?: 'signature' | 'spending-cap';
+    /** Stops the sequence between wallet requests when its reviewed context changes. */
+    signal?: AbortSignal;
     onStatus?: AegisEngineActionCallbacks['onStatus'];
+    /** Fine-grained prerequisite progress for truthful wallet onboarding. */
+    onAuthorizationProgress?: (progress: AegisEngineAuthorizationProgress) => void;
+    /** Awaited after each prerequisite receipt and before another wallet request. */
+    onAuthorizationCheckpoint?: () => Promise<void>;
 };
 export type AegisEngineSendInput = {
     wallet: AegisEngineWalletSession;
     publicClient: PublicClient;
     activeChain: AegisSwapChainConfig;
     tx: AegisEnginePreparedTransaction;
+    /**
+     * Cancels preparation before broadcast when the reviewed UI context changes.
+     * Once a wallet returns a transaction hash, receipt tracking always finishes.
+     */
+    signal?: AbortSignal;
     /**
      * Absolute Unix timestamp encoded into the prepared Engine transaction.
      * When present, the send boundary refuses to open the wallet if too little

package/dist/errors.d.ts

@@ -1,6 +1,19 @@
 import type { Hex } from 'viem';
+/** Failure families the widget surfaces reason about (retry affordances,
+    toast dwell, explorer-link degradation) without string comparison. */
+export type UserFacingErrorKind = 'rpc' | 'quote' | 'backend' | 'wallet-rejected' | 'wrong-chain' | 'tx-reverted' | 'tx-timeout' | 'market-not-ready' | 'validation' | 'unknown';
+export type ClassifiedError = {
+    message: string;
+    kind: UserFacingErrorKind;
+    retryable: boolean;
+};
 export declare class UserFacingError extends Error {
-    constructor(message: string);
+    readonly kind: UserFacingErrorKind;
+    readonly retryable: boolean;
+    constructor(message: string, options?: {
+        kind?: UserFacingErrorKind;
+        retryable?: boolean;
+    });
 }
 export declare class TransactionReceiptTimeoutError extends UserFacingError {
     readonly hash: Hex;
@@ -10,4 +23,14 @@ export declare class TransactionReceiptTimeoutError extends UserFacingError {
 }
 export declare function isUserRejectedError(error: unknown): boolean;
 export declare const USER_REJECTED_MESSAGE = "Request rejected.";
+/**
+ * Map raw wallet/RPC errors to short, user-facing messages plus their failure
+ * family and retryability. UserFacingError subclasses win first (their copy
+ * and kind are authored at the throw site); everything else must earn its way
+ * through the legacy substring whitelist. Anything unrecognized (including
+ * quote aborts) collapses to the caller-supplied fallback as retryable
+ * 'unknown'.
+ */
+export declare function classifyError(error: unknown, fallbackMessage: string): ClassifiedError;
+/** Message-only compat wrapper over {@link classifyError}. */
 export declare function errorMessage(error: unknown, fallbackMessage: string): string;