@aegis-engine/core 0.5.0 → 0.7.0

package/dist/engine/simpleYield.d.ts

@@ -0,0 +1,39 @@
+import type { AegisEngineLendPositionHydration, AegisEngineLendSharesPosition, AegisEngineMarket, AegisEngineMetricHistory } from './types.js';
+export type AegisEngineSimpleYieldPositionSummaryInput = Readonly<{
+    position: AegisEngineLendSharesPosition | null;
+    market: AegisEngineMarket;
+    hydration?: AegisEngineLendPositionHydration;
+    history?: AegisEngineMetricHistory | null;
+    additionalValueUsd?: number | null;
+    /** Override the current time for deterministic freshness checks. */
+    nowMs?: number;
+}>;
+export type AegisEngineSimpleYieldPositionSummary = Readonly<{
+    hasPosition: boolean;
+    valuation: Readonly<{
+        shareFraction: number;
+        suppliedUsd: number;
+        currentValueUsd: number;
+        source: 'live-shares' | 'indexed-shares';
+    }> | null;
+    projection: Readonly<{
+        addedValueUsd: number;
+        projectedValueUsd: number;
+    }> | null;
+    growth: Readonly<{
+        weeklyEarningsPer100Usd: number;
+        currentWeeklyEarningsUsd: number | null;
+        projectedWeeklyEarningsUsd: number | null;
+        coverageSeconds: number;
+        stale: boolean;
+    }> | null;
+}>;
+/**
+ * Summarizes an Engine lend-share position for a simple-yield surface.
+ *
+ * Live share hydration wins over indexed share balances. Realized weekly
+ * growth comes only from share-price history, never from the market's modeled
+ * `lendApyPct`. Existing positions fail closed when their value is unavailable,
+ * so an add-funds preview cannot accidentally present them as a fresh deposit.
+ */
+export declare function summarizeEngineSimpleYieldPosition(input: AegisEngineSimpleYieldPositionSummaryInput): AegisEngineSimpleYieldPositionSummary;

package/dist/engine/types.d.ts

@@ -1,6 +1,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 { ClassifiedError } from '../errors.js';
 import type { WalletSession } from '../swap/types.js';
 import type { AegisEngineTapInfeasibleReason, AegisEngineTapRootPolicy } from './trade/sizing.js';
 export type AegisEngineMode = 'lend' | 'borrow' | 'positions';
@@ -455,6 +456,9 @@ export type AegisEngineRestSource = {
  */
 export type AegisEngineStaticSource = {
     kind: 'static';
+    /** Read current balances and vault state for supplied positions through the
+     * host's public client. Opt in for interactive simulation or host indexes. */
+    hydratePositions?: boolean;
     markets: AegisEngineMarket[];
     positions?: AegisEnginePosition[];
     lendPositions?: AegisEngineLendSharesPosition[];
@@ -631,6 +635,10 @@ export type AegisEngineBorrowCapacityInput = Omit<AegisEngineQuoteBase, 'owner'
     /** Optional output-first target. When supplied, the result includes the
      *  collateral floor for the deterministic no-swap path. */
     borrowOut?: bigint;
+    /** Include wallet and market quick-fill limits in this same live frame. */
+    includeBorrowLimits?: boolean;
+    /** Spendable collateral after the native gas reserve; omitted when unknown. */
+    walletCollateralIn?: bigint;
     tauPips?: number;
     /** See `AegisEngineBorrowQuoteInput.tauPercentOfMaxLtv`. */
     tauPercentOfMaxLtv?: number;
@@ -1119,6 +1127,24 @@ export type AegisEngineVaultActivityEntry = {
     receivedRaw: bigint | null;
     receivedIsToken0: boolean | null;
 };
+/** Settled sizing result. A floor is planning data, never execution permission. */
+export type AegisEngineBorrowCollateralFloor = {
+    status: 'not-requested';
+} | {
+    status: 'ready-positive';
+    amountIn: bigint;
+} | {
+    status: 'ready-zero';
+    amountIn: 0n;
+    outputSource: 'existing-idle' | 'new-debt' | 'unknown';
+} | {
+    status: 'infeasible';
+    reason: 'utilization-capped';
+} | {
+    status: 'unavailable';
+    reason: 'closed-form-not-applicable' | 'forward-validation-unavailable' | 'legacy-no-floor';
+    retryable: boolean;
+};
 export type AegisEngineBorrowCapacity = {
     kind: 'borrow-capacity';
     market: AegisEngineMarket;
@@ -1134,16 +1160,25 @@ export type AegisEngineBorrowCapacity = {
     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
+    /** Minimum deposit for the supplied vault 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;
+    /** Always emitted by quoteEngineBorrowCapacity; optional for older host snapshots. */
+    collateralFloor?: AegisEngineBorrowCollateralFloor;
+    /** Market frame used for sizing; vault inputs still need executable revalidation. */
+    frame?: AegisEngineReadFrame;
     /** 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. */
+    borrowLimits?: {
+        walletCollateralIn: bigint | null;
+        walletBorrowOut: bigint | null;
+        marketBorrowOut: bigint;
+    };
     utilizationCapped: boolean;
     capacity: {
         yMaxLtv: bigint;
@@ -1228,6 +1263,12 @@ export type AegisEngineAuthorizationPlan = {
     token: AegisEngineToken;
     amount: bigint;
     approvalMode: 'exact' | 'max';
+    /** Read observations drive permission presentation only, never submission authority. */
+    observations?: {
+        erc20Allowance: bigint | null;
+        permit2Allowance: readonly [bigint, number, number] | null;
+        permit2AuthorizationMode: 'signature' | 'spending-cap';
+    };
     router: Address;
     permit2: Address;
     vaultRegistry: Address;
@@ -1256,6 +1297,25 @@ export type AegisEngineAuthorizationProgress = {
     kind: AegisEngineAuthorizationStepKind;
     status: 'requesting' | 'confirmed';
 };
+/** Lifecycle evidence for one Engine permission request. */
+export type AegisEngineAuthorizationExecutionEvent = Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'wallet-requested';
+    hash: null;
+}> | Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'submitted';
+    hash: Hex;
+}> | Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'confirmed';
+    hash: Hex | null;
+}> | Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'cancelled' | 'failed';
+    hash: Hex | null;
+    error: ClassifiedError;
+}>;
 export type AegisEngineApprovalInput = {
     wallet: AegisEngineWalletSession;
     publicClient: PublicClient;
@@ -1271,6 +1331,8 @@ export type AegisEngineApprovalInput = {
     onStatus?: AegisEngineActionCallbacks['onStatus'];
     /** Fine-grained prerequisite progress for truthful wallet onboarding. */
     onAuthorizationProgress?: (progress: AegisEngineAuthorizationProgress) => void;
+    /** Full prerequisite lifecycle at the wallet and receipt boundaries. */
+    onAuthorizationExecution?: (event: AegisEngineAuthorizationExecutionEvent) => void;
     /** Awaited after each prerequisite receipt and before another wallet request. */
     onAuthorizationCheckpoint?: () => Promise<void>;
 };

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
 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 UserFacingErrorKind = 'rpc' | 'quote' | 'backend' | 'wallet-rejected' | 'tx-cancelled' | 'wrong-chain' | 'tx-reverted' | 'tx-timeout' | 'market-not-ready' | 'validation' | 'unknown';
 export type ClassifiedError = {
     message: string;
     kind: UserFacingErrorKind;
@@ -15,8 +15,19 @@ export declare class UserFacingError extends Error {
         retryable?: boolean;
     });
 }
-export declare class TransactionReceiptTimeoutError extends UserFacingError {
+export declare class SubmittedTransactionReceiptError extends UserFacingError {
     readonly hash: Hex;
+    readonly cause: unknown;
+    constructor({ hash, cause, message, kind }: {
+        hash: Hex;
+        cause?: unknown;
+        message?: string;
+        kind?: UserFacingErrorKind;
+    });
+}
+/** True only for Core receipt failures that happened after a known broadcast. */
+export declare function isSubmittedTransactionReceiptError(error: unknown): error is SubmittedTransactionReceiptError;
+export declare class TransactionReceiptTimeoutError extends SubmittedTransactionReceiptError {
     constructor({ hash }: {
         hash: Hex;
     });