@aegis-engine/core 0.2.0 → 0.3.1

package/dist/contract/schemas.d.ts

@@ -16,16 +16,16 @@ export declare const aegisBackendMarketStatusSchema: z.ZodEnum<{
     enabled: "enabled";
     disabled: "disabled";
 }>;
-export declare const aegisBackendChainIdSchema: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+export declare const aegisBackendChainIdSchema: z.ZodLiteral<1 | 130 | 8453>;
 export declare const aegisBackendChainSchema: z.ZodObject<{
-    chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+    chainId: z.ZodNumber;
     slug: z.ZodString;
     name: z.ZodString;
 }, z.core.$strip>;
 export declare const aegisBackendQuoteDefaultsSchema: z.ZodObject<{
-    ttlSeconds: z.ZodLiteral<15>;
-    defaultSlippageBps: z.ZodLiteral<100>;
-    maxSlippageBps: z.ZodLiteral<2000>;
+    ttlSeconds: z.ZodNumber;
+    defaultSlippageBps: z.ZodNumber;
+    maxSlippageBps: z.ZodNumber;
 }, z.core.$strip>;
 export declare const aegisBackendContractRegistrySchema: z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>>;
 export declare const aegisBackendAddressAllowlistSchema: z.ZodObject<{
@@ -52,13 +52,13 @@ export declare const aegisBackendAllowlistsByChainSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const aegisBackendFeeConfigSchema: z.ZodObject<{
-    outputFeeBps: z.ZodLiteral<50>;
+    outputFeeBps: z.ZodNumber;
     recipient: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
 }, z.core.$strip>;
 export declare const aegisBackendConfigSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<"1">;
     chains: z.ZodArray<z.ZodObject<{
-        chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+        chainId: z.ZodNumber;
         slug: z.ZodString;
         name: z.ZodString;
     }, z.core.$strip>>;
@@ -67,9 +67,9 @@ export declare const aegisBackendConfigSchema: z.ZodObject<{
         kyber: "kyber";
     }>>;
     quote: z.ZodObject<{
-        ttlSeconds: z.ZodLiteral<15>;
-        defaultSlippageBps: z.ZodLiteral<100>;
-        maxSlippageBps: z.ZodLiteral<2000>;
+        ttlSeconds: z.ZodNumber;
+        defaultSlippageBps: z.ZodNumber;
+        maxSlippageBps: z.ZodNumber;
     }, z.core.$strip>;
     contracts: z.ZodObject<{
         '1': z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>>;
@@ -91,13 +91,13 @@ export declare const aegisBackendConfigSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>;
     fee: z.ZodObject<{
-        outputFeeBps: z.ZodLiteral<50>;
+        outputFeeBps: z.ZodNumber;
         recipient: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const aegisBackendTokenSchema: z.ZodObject<{
     id: z.ZodString;
-    chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+    chainId: z.ZodNumber;
     address: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
     symbol: z.ZodString;
     displayName: z.ZodString;
@@ -120,8 +120,8 @@ export declare const aegisPoolKeySchema: z.ZodObject<{
     hooks: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
 }, z.core.$strip>;
 export declare const aegisBackendMarketSchema: z.ZodObject<{
-    id: z.ZodString;
-    chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+    id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    chainId: z.ZodNumber;
     status: z.ZodEnum<{
         enabled: "enabled";
         disabled: "disabled";
@@ -152,7 +152,7 @@ export declare const aegisBackendMarketSchema: z.ZodObject<{
 export declare const aegisBackendSwapQuoteRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     mode: z.ZodLiteral<"exactIn">;
     amountIn: z.ZodString;
-    chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+    chainId: z.ZodLiteral<1 | 130 | 8453>;
     provider: z.ZodEnum<{
         "aegis-direct-v4": "aegis-direct-v4";
         kyber: "kyber";
@@ -165,7 +165,7 @@ export declare const aegisBackendSwapQuoteRequestSchema: z.ZodDiscriminatedUnion
 }, z.core.$loose>, z.ZodObject<{
     mode: z.ZodLiteral<"exactOut">;
     amountOut: z.ZodString;
-    chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+    chainId: z.ZodLiteral<1 | 130 | 8453>;
     provider: z.ZodEnum<{
         "aegis-direct-v4": "aegis-direct-v4";
         kyber: "kyber";
@@ -190,7 +190,7 @@ export declare const aegisBackendSwapQuoteResponseSchema: z.ZodObject<{
     price: z.ZodNumber;
     slippageBps: z.ZodNumber;
     fee: z.ZodObject<{
-        outputFeeBps: z.ZodLiteral<50>;
+        outputFeeBps: z.ZodNumber;
         recipient: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
     }, z.core.$strip>;
     asOf: z.ZodISODateTime;
@@ -201,7 +201,7 @@ export declare const aegisBackendHealthResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const aegisBackendTokensResponseSchema: z.ZodArray<z.ZodObject<{
     id: z.ZodString;
-    chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+    chainId: z.ZodNumber;
     address: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
     symbol: z.ZodString;
     displayName: z.ZodString;
@@ -212,8 +212,8 @@ export declare const aegisBackendTokensResponseSchema: z.ZodArray<z.ZodObject<{
     stable: z.ZodBoolean;
 }, z.core.$strip>>;
 export declare const aegisBackendMarketsResponseSchema: z.ZodArray<z.ZodObject<{
-    id: z.ZodString;
-    chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<130>, z.ZodLiteral<8453>]>;
+    id: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    chainId: z.ZodNumber;
     status: z.ZodEnum<{
         enabled: "enabled";
         disabled: "disabled";
@@ -241,3 +241,10 @@ export declare const aegisBackendMarketsResponseSchema: z.ZodArray<z.ZodObject<{
         "cap-event": "cap-event";
     }>>;
 }, z.core.$strip>>;
+export declare function refineHistorySeries(value: {
+    status: 'ready' | 'warming_up' | 'no_data';
+    pointCount: number;
+    points: ReadonlyArray<{
+        t: number;
+    }>;
+}, context: z.RefinementCtx): void;

package/dist/engine/actions.d.ts

@@ -0,0 +1,56 @@
+import { type Address, type Hex } from 'viem';
+import type { AegisEngineActionCallbacks, AegisEngineApprovalInput, AegisEngineMarket, AegisEnginePositionTarget, AegisEngineSendInput, AegisEngineSignedPermitBatch, AegisEngineTransactionResult } from './types.js';
+export type AegisEnginePositionRouterAuthorizationInput = {
+    wallet: AegisEngineSendInput['wallet'];
+    publicClient: AegisEngineSendInput['publicClient'];
+    activeChain: AegisEngineSendInput['activeChain'];
+    market: AegisEngineMarket;
+    target: AegisEnginePositionTarget;
+    /** Exact ERC-6909 share allowance required for a lender-position action. */
+    amount?: bigint;
+    onStatus?: AegisEngineActionCallbacks['onStatus'];
+    onTxHash?: AegisEngineActionCallbacks['onTxHash'];
+};
+export declare function prepareEnginePermit(args: AegisEngineApprovalInput): Promise<{
+    approvalHash: Hex | null;
+    permit: AegisEngineSignedPermitBatch | null;
+}>;
+/**
+ * Authorize the trusted Engine router to manage an already-open position.
+ *
+ * Borrow vaults use a per-vault ERC-721 approval; lender positions use a
+ * per-pool, amount-bounded ERC-6909 allowance. The helper deliberately
+ * does not accept `onSubmitted`: authorization is a prerequisite transaction,
+ * not the host's requested position action.
+ */
+export declare function authorizeEnginePositionRouter(args: AegisEnginePositionRouterAuthorizationInput): Promise<AegisEngineTransactionResult>;
+/**
+ * Whether the trusted router may already move this borrow vault — either a
+ * per-vault approval or a blanket operator approval. Lets a borrow into an
+ * existing vault skip a redundant ERC-721 approval on repeat borrows. Without
+ * a `vaultId` (createVault path) only the blanket operator approval can
+ * exist, so only that is read.
+ */
+export declare function readEngineVaultRouterApproved(args: {
+    publicClient: AegisEngineSendInput['publicClient'];
+    market: AegisEngineMarket;
+    owner: Address;
+    vaultId?: bigint;
+}): Promise<boolean>;
+/**
+ * Blanket operator approval for the trusted router on the vault registry.
+ * A first borrow (createVault) has no vault to approve per-token, and the
+ * SDK's execution evidence for a fresh vault checks `isApprovedForAll` only —
+ * this is the only authorization that can satisfy its router gate. Existing
+ * vaults should keep the narrower per-vault approval via
+ * `authorizeEnginePositionRouter`.
+ */
+export declare function authorizeEngineVaultOperator(args: Omit<AegisEnginePositionRouterAuthorizationInput, 'target' | 'amount'>): Promise<AegisEngineTransactionResult>;
+export declare function sendEngineTransaction(args: AegisEngineSendInput): Promise<AegisEngineTransactionResult>;
+export declare function missingEngineExecutionReason(market: {
+    router?: Address;
+    permit2?: Address;
+    stateView?: Address;
+    v4StateView?: Address;
+    v4Quoter?: Address;
+}): string | null;

package/dist/engine/borrowCostProjection.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine/dataSource.d.ts

@@ -0,0 +1,63 @@
+import type { Address } from 'viem';
+import type { AegisEngineDataSource, AegisEngineHistoryWindow, AegisEngineMarket, AegisEngineMetricHistory, AegisEnginePositionActivitySnapshot, AegisEngineVaultActivityEntry, AegisEnginePositionsSnapshot } from './types.js';
+export declare function clearEngineMarketsCache(): void;
+export declare function clearEngineMarketHistoryCache(): void;
+export declare function clearEnginePositionsCache(): void;
+export declare function clearEnginePositionActivityCache(): void;
+export declare function clearEnginePositionsV2ProbeCache(): void;
+export declare function fetchEngineMarkets(args: {
+    source: AegisEngineDataSource;
+    chainId: number;
+    signal?: AbortSignal;
+    defaultV4Quoter?: Address;
+}): Promise<AegisEngineMarket[]>;
+export declare function fetchEngineMarketHistory(args: {
+    source: AegisEngineDataSource;
+    marketId: string;
+    window?: AegisEngineHistoryWindow;
+    signal?: AbortSignal;
+}): Promise<AegisEngineMetricHistory | null>;
+export declare function fetchEnginePositionsSnapshot(args: {
+    source: AegisEngineDataSource;
+    chainId: number;
+    account: Address;
+    signal?: AbortSignal;
+    /** Explicit user refresh and post-transaction reconciliation bypass the
+     * short display cache; normal tab re-entry does not. */
+    force?: boolean;
+}): Promise<AegisEnginePositionsSnapshot>;
+/** Loads the complete account-scoped Engine action ledger. Static sources have
+ * no activity plane and return null rather than presenting fixture data as
+ * indexed history. */
+export declare function fetchEnginePositionActivitySnapshot(args: {
+    source: AegisEngineDataSource;
+    chainId: number;
+    account: Address;
+    signal?: AbortSignal;
+    /** Explicit refresh and post-transaction reconciliation bypass the cache. */
+    force?: boolean;
+}): Promise<AegisEnginePositionActivitySnapshot | null>;
+/** Convenience view for the latest debt/idle transaction of one vault. The
+ * full REST ledger remains available through fetchEnginePositionActivitySnapshot. */
+export declare function fetchEngineVaultActivity(args: {
+    source: AegisEngineDataSource;
+    chainId: number;
+    account: Address;
+    vaultId: bigint | string;
+    signal?: AbortSignal;
+    force?: boolean;
+}): Promise<AegisEngineVaultActivityEntry | null>;
+/** Convenience view for the wallet's latest lend transaction in one market.
+ * Deposit/withdraw only: share transfers move pool shares between wallets
+ * without a token leg, so presenting one as the market's latest transaction
+ * would misstate what the wallet last did with tokens. Rides the shared
+ * wallet activity snapshot cache — no extra request beyond
+ * fetchEnginePositionActivitySnapshot. */
+export declare function fetchEngineLendActivity(args: {
+    source: AegisEngineDataSource;
+    chainId: number;
+    account: Address;
+    poolId: string;
+    signal?: AbortSignal;
+    force?: boolean;
+}): Promise<AegisEngineVaultActivityEntry | null>;

package/dist/engine/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './dataSource.js';
+export * from './marketAdapter.js';
+export * from './registry.js';
+export * from './reads.js';
+export * from './quotes.js';
+export * from './actions.js';
+export * from './positionAmounts.js';

package/dist/engine/marketAdapter.d.ts

@@ -0,0 +1,8 @@
+import type { Address } from 'viem';
+import type { AegisEngineMarket, AegisEngineMarketSource } from './types.js';
+export declare function normalizeEngineMarkets(args: {
+    chainId: number;
+    markets: readonly unknown[];
+    source?: AegisEngineMarketSource;
+    defaultV4Quoter?: Address;
+}): AegisEngineMarket[];

package/dist/engine/positionAmounts.d.ts

@@ -0,0 +1,37 @@
+/** Conservative cap to size a withdrawal preview against. */
+export declare function enginePreviewMaxLtvPips(marketMaxLtvPips: number): number;
+export type AegisEngineIdleWithdrawSide = 'token0' | 'token1';
+export type AegisEngineIdleWithdrawAmountInput = {
+    /** Same-frame live idle token amounts. */
+    idle0: bigint;
+    idle1: bigint;
+    /**
+     * Same-frame accrued debt in L units, rounded up by position hydration.
+     * Using the rounded-up value makes this preview no less conservative than
+     * the Engine's exact rL × borrow-index residual check.
+     */
+    debtLLatest: bigint;
+    maxLtvPips: number;
+    side: AegisEngineIdleWithdrawSide;
+};
+/**
+ * Mirrors the idle-only residual-LTV inequality used by the Engine lifecycle
+ * quote. Engine idle balances are int128-packed, so their product fits uint256
+ * and `floor(sqrt(idle0 × idle1)) >= requiredFloor` is exactly equivalent to
+ * `idle0 × idle1 >= requiredFloor²`.
+ */
+export declare function engineIdleWithdrawPassesResidualLtv(input: AegisEngineIdleWithdrawAmountInput): boolean;
+/**
+ * Maximum independently withdrawable idle amount for one selected token.
+ * The opposite token remains untouched. This is a conservative preview; the
+ * exact amount is always re-quoted from a fresh block before submission.
+ */
+export declare function computeEngineMaxIdleWithdraw(input: AegisEngineIdleWithdrawAmountInput): bigint;
+/**
+ * Projected idle-only LTV after one exact withdrawal. Returns null for a
+ * debt-free vault or an invalid/zero-collateral post-state. The exact action
+ * remains quote-driven; this is display math over the same hydrated frame.
+ */
+export declare function computeEngineIdleWithdrawPostLtvPips(input: AegisEngineIdleWithdrawAmountInput & {
+    withdrawAmount: bigint;
+}): number | null;

package/dist/engine/quotes.d.ts

@@ -0,0 +1,9 @@
+import type { AegisEngineBorrowCapacity, AegisEngineBorrowCapacityInput, AegisEngineBorrowQuote, AegisEngineBorrowQuoteInput, AegisEngineAddCollateralQuoteInput, AegisEngineCloseQuoteInput, AegisEngineDepositQuote, AegisEngineDepositQuoteInput, AegisEngineIdleWithdrawQuoteInput, AegisEnginePositionActionQuote, AegisEngineRedeemQuoteInput, AegisEngineRepayQuoteInput } from './types.js';
+export declare function quoteEngineDeposit(input: AegisEngineDepositQuoteInput): Promise<AegisEngineDepositQuote>;
+export declare function quoteEngineBorrow(input: AegisEngineBorrowQuoteInput): Promise<AegisEngineBorrowQuote>;
+export declare function quoteEngineAddCollateral(input: AegisEngineAddCollateralQuoteInput): Promise<AegisEnginePositionActionQuote>;
+export declare function quoteEngineBorrowCapacity(input: AegisEngineBorrowCapacityInput): Promise<AegisEngineBorrowCapacity>;
+export declare function quoteEngineRepay(input: AegisEngineRepayQuoteInput): Promise<AegisEnginePositionActionQuote>;
+export declare function quoteEngineCloseVault(input: AegisEngineCloseQuoteInput): Promise<AegisEnginePositionActionQuote>;
+export declare function quoteEngineIdleWithdraw(input: AegisEngineIdleWithdrawQuoteInput): Promise<AegisEnginePositionActionQuote>;
+export declare function quoteEngineRedeem(input: AegisEngineRedeemQuoteInput): Promise<AegisEnginePositionActionQuote>;

package/dist/engine/reads.d.ts

@@ -0,0 +1,43 @@
+import type { Address } from 'viem';
+import type { AegisEngineBorrowQuoteContext, AegisEngineMarket, AegisEngineMarketReadInput, AegisEngineMarketSnapshot, AegisEnginePositionsHydration, AegisEnginePositionsHydrationInput, AegisEngineVaultActivityEntry } from './types.js';
+export declare class AegisEngineMarketNotReadyError extends Error {
+    constructor(message: string);
+}
+/** Test-only reset for the module-owned, weakly client-scoped read caches. */
+export declare function clearEngineReadCaches(): void;
+export declare function readEngineMarketSnapshot(input: AegisEngineMarketReadInput): Promise<AegisEngineMarketSnapshot>;
+export declare function readEngineBorrowQuoteContext(input: AegisEngineMarketReadInput, execution?: {
+    owner: Address;
+    vaultId?: bigint;
+}, options?: {
+    forceRefresh?: boolean;
+}): Promise<AegisEngineBorrowQuoteContext>;
+/**
+ * Hydrates REST/subgraph-discovered borrow and lender positions in one
+ * block-pinned SDK frame. Results remain one-to-one with the discovery arrays
+ * and carry their stable position ids so consumers can merge without relying
+ * on list order after the read completes.
+ */
+export declare function readEnginePositionsHydration(input: AegisEnginePositionsHydrationInput): Promise<AegisEnginePositionsHydration>;
+/** Classifies one transaction's vault actions into a ledger entry: the shared
+ *  grammar for turning a group of debt/idle action rows into a
+ *  {@link AegisEngineVaultActivityEntry}. Public so hosts rendering their own
+ *  activity list classify transactions the same way core does. */
+export declare function classifyEngineVaultActivity(group: {
+    txHash: `0x${string}`;
+    timestamp: number;
+    debt: readonly {
+        principalDeltaActual: bigint;
+    }[];
+    idle: readonly {
+        deltaAmount0: bigint;
+        deltaAmount1: bigint;
+    }[];
+}): AegisEngineVaultActivityEntry;
+/** Latest transaction that touched a vault, from the public Engine subgraph.
+ *  Read-only and wallet-free; returns null for an untraceable vault (no
+ *  trusted deployment, empty ledger, or subgraph outage — callers degrade). */
+export declare function readEngineVaultActivity(input: {
+    market: AegisEngineMarket;
+    vaultId: bigint;
+}): Promise<AegisEngineVaultActivityEntry | null>;

package/dist/engine/registry.d.ts

@@ -0,0 +1,27 @@
+import type { Address } from 'viem';
+import type { AegisEngineVersion } from './types.js';
+/** Engine hard utilization cap as a percentage of supplied liquidity.
+ *  Mirrors the SDK's UTILIZATION_CAP_PIPS (950_000/1_000_000), inlined so
+ *  sync widget code can read cap state off REST `utilizationPct` without
+ *  loading the SDK. Drift-guarded by engineRegistry.test.ts. */
+export declare const ENGINE_UTILIZATION_CAP_PCT = 95;
+export type AegisEngineChainAddresses = {
+    aegisEngine: Address;
+    aegisHook: Address;
+    aegisRouterV1: Address;
+    aegisStateView: Address;
+    vaultRegistry: Address;
+    variableInterestRate: Address;
+    oracleManager: Address;
+    limitOrderManager: Address;
+    dynamicFeeManager: Address;
+    poolManager: Address;
+    positionManager: Address;
+    stateView: Address;
+    uniswapV4Quoter: Address;
+    permit2: Address;
+    weth9: Address;
+};
+export declare function trustedEngineVersionForChain(chainId: number): AegisEngineVersion | null;
+export declare function trustedEngineRegistryForChain(chainId: number): AegisEngineChainAddresses | null;
+export declare function engineRouterForChain(chainId: number): Address;