@aegis-engine/core 0.6.0 → 0.8.0

package/dist/engine/account/positionPerformance.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { Address, Hex } from 'viem';
+import type { AegisEngineRestSource } from '../types.js';
+import { PositionPerformanceResponseSchema } from './positionPerformanceSchemas.js';
+export type AegisEnginePositionPerformance = z.infer<typeof PositionPerformanceResponseSchema>;
+export type AegisEnginePositionPerformanceInput = {
+    source: AegisEngineRestSource;
+    account: Address;
+    chainId: number;
+    poolId: Hex;
+    vaultId: string;
+    snapshotId: string;
+    portfolioSnapshotId?: string;
+    signal?: AbortSignal;
+};
+/** One frozen accounting/portfolio pair. The caller captures portfolio first
+ * for an open position and never substitutes local mark-price calculations. */
+export declare function fetchEnginePositionPerformance(input: AegisEnginePositionPerformanceInput): Promise<AegisEnginePositionPerformance>;

package/dist/engine/account/positionPerformanceSchemas.d.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+export declare const PositionPerformanceResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodString;
+    schemaVersion: z.ZodLiteral<"1">;
+    modelVersion: z.ZodLiteral<"position-usd-performance-v1">;
+    snapshotId: z.ZodString;
+    portfolioSnapshotId: z.ZodNullable<z.ZodString>;
+    chainId: z.ZodNumber;
+    account: z.ZodString;
+    poolId: z.ZodString;
+    vaultId: z.ZodString;
+    capturedAt: z.ZodString;
+    expiresAt: z.ZodString;
+    canonicality: z.ZodLiteral<"rpc-checked-at-capture">;
+    finality: z.ZodLiteral<"not-a-finality-verdict">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"estimated">;
+    positionStatus: z.ZodEnum<{
+        open: "open";
+        closed: "closed";
+    }>;
+    denomination: z.ZodLiteral<"USD">;
+    basis: z.ZodLiteral<"equity-plus-withdrawals-minus-contributions">;
+    roiBasis: z.ZodLiteral<"initial-net-contribution">;
+    asOf: z.ZodString;
+    equityUsd: z.ZodString;
+    contributionUsd: z.ZodString;
+    withdrawalsUsd: z.ZodString;
+    pnlUsd: z.ZodString;
+    roiPercent: z.ZodString;
+    costs: z.ZodObject<{
+        tradingAndBorrowing: z.ZodLiteral<"embedded-in-equity-and-cashflows">;
+        gas: z.ZodLiteral<"excluded">;
+    }, z.core.$strict>;
+    coverage: z.ZodLiteral<"single-opening-no-intermediate-mutations">;
+    equityFrame: z.ZodNullable<z.ZodObject<{
+        blockNumber: z.ZodNumber;
+        blockHash: z.ZodString;
+        blockTimestamp: z.ZodNumber;
+        deployment: z.ZodString;
+    }, z.core.$strict>>;
+    currentPrices: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        chainId: z.ZodNumber;
+        address: z.ZodString;
+        decimals: z.ZodNullable<z.ZodNumber>;
+        symbol: z.ZodNullable<z.ZodString>;
+        status: z.ZodEnum<{
+            unavailable: "unavailable";
+            observed: "observed";
+            assumed: "assumed";
+        }>;
+        priceUsd: z.ZodNullable<z.ZodString>;
+        reasons: z.ZodArray<z.ZodString>;
+        source: z.ZodNullable<z.ZodEnum<{
+            custom: "custom";
+            coingecko: "coingecko";
+            configured_peg: "configured_peg";
+            pool: "pool";
+            cross_chain: "cross_chain";
+        }>>;
+        observedAt: z.ZodNullable<z.ZodString>;
+        fetchedAt: z.ZodNullable<z.ZodString>;
+        resolvedAt: z.ZodNullable<z.ZodString>;
+        recordedAt: z.ZodNullable<z.ZodString>;
+        effectiveObservedAt: z.ZodNullable<z.ZodString>;
+        assumptions: z.ZodArray<z.ZodString>;
+        dependencies: z.ZodArray<z.ZodObject<{
+            tokenId: z.ZodString;
+            effectiveObservedAt: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    historicalPrices: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            open: "open";
+            close: "close";
+        }>;
+        address: z.ZodString;
+        decimals: z.ZodNumber;
+        priceUsd: z.ZodString;
+        transactionTimestamp: z.ZodNumber;
+        bucketStart: z.ZodNumber;
+        bucketSeconds: z.ZodLiteral<43200>;
+        source: z.ZodLiteral<"historical-token-prices">;
+        observationTime: z.ZodNull;
+    }, z.core.$strict>>;
+    assumptions: z.ZodArray<z.ZodString>;
+    schemaVersion: z.ZodLiteral<"1">;
+    modelVersion: z.ZodLiteral<"position-usd-performance-v1">;
+    snapshotId: z.ZodString;
+    portfolioSnapshotId: z.ZodNullable<z.ZodString>;
+    chainId: z.ZodNumber;
+    account: z.ZodString;
+    poolId: z.ZodString;
+    vaultId: z.ZodString;
+    capturedAt: z.ZodString;
+    expiresAt: z.ZodString;
+    canonicality: z.ZodLiteral<"rpc-checked-at-capture">;
+    finality: z.ZodLiteral<"not-a-finality-verdict">;
+}, z.core.$strict>], "status">;

package/dist/engine/account/positionPnl.d.ts

@@ -0,0 +1,18 @@
+import { type Address, type Hex } from 'viem';
+import { z } from 'zod';
+import type { AegisEngineRestSource } from '../types.js';
+import { PositionPnlResponseSchema } from './positionPnlSchemas.js';
+export type AegisEnginePositionPnl = z.infer<typeof PositionPnlResponseSchema>;
+export type AegisEnginePositionPnlInput = {
+    source: AegisEngineRestSource;
+    account: Address;
+    chainId: number;
+    poolId: Hex;
+    vaultId: string;
+    /** A retained snapshot returned by fetchEnginePositionAccounting for this vault. */
+    snapshotId: string;
+    signal?: AbortSignal;
+};
+/** One bounded read of closed-trade token cash flows. Does not refresh accounting,
+ * poll, fetch prices or turn partial fee coverage into total economic PnL. */
+export declare function fetchEnginePositionPnl(input: AegisEnginePositionPnlInput): Promise<AegisEnginePositionPnl>;

package/dist/engine/account/positionPnlSchemas.d.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+export declare const PositionPnlSettlementSchema: z.ZodObject<{
+    phase: z.ZodEnum<{
+        open: "open";
+        close: "close";
+    }>;
+    transactionHash: z.ZodString;
+    block: z.ZodObject<{
+        number: z.ZodNumber;
+        hash: z.ZodString;
+        timestamp: z.ZodNumber;
+        transactionIndex: z.ZodNumber;
+    }, z.core.$strict>;
+    paid: z.ZodObject<{
+        amount0Raw: z.ZodString;
+        amount1Raw: z.ZodString;
+    }, z.core.$strict>;
+    received: z.ZodObject<{
+        amount0Raw: z.ZodString;
+        amount1Raw: z.ZodString;
+    }, z.core.$strict>;
+    net: z.ZodObject<{
+        amount0Raw: z.ZodString;
+        amount1Raw: z.ZodString;
+    }, z.core.$strict>;
+    executionGasFeeWei: z.ZodString;
+}, z.core.$strict>;
+export declare const PositionPnlResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodEnum<{
+        "incomplete-accounting": "incomplete-accounting";
+        "incomplete-ownership": "incomplete-ownership";
+        "position-not-closed": "position-not-closed";
+        "unsupported-lifecycle": "unsupported-lifecycle";
+        "settlement-unavailable": "settlement-unavailable";
+        "native-settlement-unavailable": "native-settlement-unavailable";
+    }>;
+    schemaVersion: z.ZodLiteral<"1">;
+    modelVersion: z.ZodLiteral<"closed-tap-token-pnl-v1">;
+    snapshotId: z.ZodString;
+    chainId: z.ZodNumber;
+    account: z.ZodString;
+    poolId: z.ZodString;
+    vaultId: z.ZodString;
+    capturedAt: z.ZodString;
+    expiresAt: z.ZodString;
+    canonicality: z.ZodLiteral<"rpc-checked-at-capture">;
+    finality: z.ZodLiteral<"not-a-finality-verdict">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"token-pnl">;
+    basis: z.ZodLiteral<"closed-position-wallet-cashflows">;
+    key: z.ZodObject<{
+        currency0: z.ZodString;
+        currency1: z.ZodString;
+        fee: z.ZodNumber;
+        tickSpacing: z.ZodNumber;
+        hooks: z.ZodString;
+    }, z.core.$strict>;
+    opening: z.ZodObject<{
+        phase: z.ZodEnum<{
+            open: "open";
+            close: "close";
+        }>;
+        transactionHash: z.ZodString;
+        block: z.ZodObject<{
+            number: z.ZodNumber;
+            hash: z.ZodString;
+            timestamp: z.ZodNumber;
+            transactionIndex: z.ZodNumber;
+        }, z.core.$strict>;
+        paid: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        received: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        net: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        executionGasFeeWei: z.ZodString;
+    }, z.core.$strict>;
+    closing: z.ZodObject<{
+        phase: z.ZodEnum<{
+            open: "open";
+            close: "close";
+        }>;
+        transactionHash: z.ZodString;
+        block: z.ZodObject<{
+            number: z.ZodNumber;
+            hash: z.ZodString;
+            timestamp: z.ZodNumber;
+            transactionIndex: z.ZodNumber;
+        }, z.core.$strict>;
+        paid: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        received: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        net: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        executionGasFeeWei: z.ZodString;
+    }, z.core.$strict>;
+    totals: z.ZodObject<{
+        paid: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        received: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        net: z.ZodObject<{
+            amount0Raw: z.ZodString;
+            amount1Raw: z.ZodString;
+        }, z.core.$strict>;
+        executionGasFeeWei: z.ZodString;
+    }, z.core.$strict>;
+    costs: z.ZodObject<{
+        tradingAndBorrowing: z.ZodLiteral<"embedded-in-cashflows">;
+        gasCoverage: z.ZodLiteral<"opening-and-closing-execution-only">;
+        totalTransactionCost: z.ZodLiteral<"unavailable">;
+    }, z.core.$strict>;
+    historicalUsdPnl: z.ZodNull;
+    netEconomicPnl: z.ZodLiteral<"unavailable">;
+    schemaVersion: z.ZodLiteral<"1">;
+    modelVersion: z.ZodLiteral<"closed-tap-token-pnl-v1">;
+    snapshotId: z.ZodString;
+    chainId: z.ZodNumber;
+    account: z.ZodString;
+    poolId: z.ZodString;
+    vaultId: z.ZodString;
+    capturedAt: z.ZodString;
+    expiresAt: z.ZodString;
+    canonicality: z.ZodLiteral<"rpc-checked-at-capture">;
+    finality: z.ZodLiteral<"not-a-finality-verdict">;
+}, z.core.$strict>], "status">;
+export type PositionPnlResponse = z.infer<typeof PositionPnlResponseSchema>;
+export declare const PositionPnlErrorSchema: z.ZodObject<{
+    error: z.ZodLiteral<"Engine PnL unavailable">;
+    code: z.ZodString;
+}, z.core.$strict>;

package/dist/engine/account/transactionHistory.d.ts

@@ -0,0 +1,50 @@
+import type { Hex, PublicClient } from 'viem';
+import { type AegisEngineTransactionRecord, type AegisEngineTransactionScope } from './transactions.js';
+/** Metadata only. Browser Storage and synchronous host stores use the same contract. */
+export type AegisEngineTransactionStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+};
+export type AegisEngineTransactionHistorySnapshot = Readonly<{
+    records: readonly AegisEngineTransactionRecord[];
+    pending: readonly AegisEngineTransactionRecord[];
+    blockingPending: readonly AegisEngineTransactionRecord[];
+    acknowledgeable: readonly AegisEngineTransactionRecord[];
+    restored: boolean;
+    error: boolean;
+    checking: boolean;
+}>;
+type ReceiptClient = Pick<PublicClient, 'chain' | 'waitForTransactionReceipt'>;
+export declare function serializeEngineTransactionRecords(records: readonly AegisEngineTransactionRecord[], scope: AegisEngineTransactionScope): string;
+/** A fixed wallet/chain owns this history for its entire lifetime. Restores,
+ * replacement chains and read-only receipt recovery share the same rules in
+ * React, server/Node and custom browser consumers. No send/sign path exists. */
+export declare function createEngineTransactionHistory({ scope: inputScope, storage: initialStorage }: {
+    scope: AegisEngineTransactionScope;
+    storage?: AegisEngineTransactionStorage | null;
+}): {
+    key: string;
+    getSnapshot: () => Readonly<{
+        records: readonly AegisEngineTransactionRecord[];
+        pending: readonly AegisEngineTransactionRecord[];
+        blockingPending: readonly AegisEngineTransactionRecord[];
+        acknowledgeable: readonly AegisEngineTransactionRecord[];
+        restored: boolean;
+        error: boolean;
+        checking: boolean;
+    }>;
+    subscribe: (listener: () => void) => () => void;
+    restore: (eventValue?: string | null) => void;
+    setStorage: (next: AegisEngineTransactionStorage | null) => void;
+    upsert: (record: AegisEngineTransactionRecord) => void;
+    checkPendingTransactions: (publicClient: ReceiptClient, { signal, timeoutMs }?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }) => Promise<{
+        checked: number;
+        settled: number;
+    }>;
+    acknowledgeUnresolvedTransaction: (hash: Hex) => boolean;
+};
+export type AegisEngineTransactionHistory = ReturnType<typeof createEngineTransactionHistory>;
+export {};

package/dist/engine/account/transactionSchemas.d.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+export declare const TransactionQuerySchema: z.ZodObject<{
+    account: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    chainIds: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number[], string>>, z.ZodTransform<number[], number[]>>;
+    chainId: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
+    txHash: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    observedBlockNumber: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>>;
+    observedBlockHash: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strip>;
+export type TransactionQuery = z.infer<typeof TransactionQuerySchema>;
+export declare const TransactionReceiptSchema: z.ZodObject<{
+    transactionHash: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    from: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    to: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    blockNumber: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>;
+    blockHash: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    transactionIndex: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>;
+    status: z.ZodEnum<{
+        "0x0": "0x0";
+        "0x1": "0x1";
+    }>;
+    logs: z.ZodArray<z.ZodObject<{
+        address: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        topics: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        data: z.ZodString;
+        blockNumber: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>;
+        blockHash: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        transactionHash: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        transactionIndex: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>;
+        logIndex: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>;
+        removed: z.ZodLiteral<false>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TransactionReceipt = z.infer<typeof TransactionReceiptSchema>;
+export declare const TransactionStatusSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    chainId: z.ZodNumber;
+    txHash: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    account: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    chainIds: z.ZodArray<z.ZodNumber>;
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        reverted: "reverted";
+        confirmed: "confirmed";
+        ready: "ready";
+        indexing: "indexing";
+        reorged: "reorged";
+        unsupported: "unsupported";
+    }>;
+    checkedAt: z.ZodString;
+    retryAfterSeconds: z.ZodLiteral<5>;
+    reasons: z.ZodArray<z.ZodString>;
+    receipt: z.ZodNullable<z.ZodObject<{
+        blockNumber: z.ZodNumber;
+        blockHash: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        transactionIndex: z.ZodNumber;
+        from: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        to: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        succeeded: z.ZodBoolean;
+        canonicality: z.ZodEnum<{
+            "checked-at-read": "checked-at-read";
+            changed: "changed";
+        }>;
+    }, z.core.$strict>>;
+    indexed: z.ZodNullable<z.ZodObject<{
+        frame: z.ZodObject<{
+            blockNumber: z.ZodNumber;
+            blockHash: z.ZodString;
+            blockTimestamp: z.ZodNumber;
+            deployment: z.ZodString;
+        }, z.core.$strict>;
+        expectedEvents: z.ZodNumber;
+        acknowledgedEvents: z.ZodNumber;
+    }, z.core.$strict>>;
+    portfolio: z.ZodNullable<z.ZodObject<{
+        snapshotId: z.ZodString;
+        createdAt: z.ZodString;
+        expiresAt: z.ZodString;
+        status: z.ZodEnum<{
+            partial: "partial";
+            complete: "complete";
+        }>;
+        chainIds: z.ZodArray<z.ZodNumber>;
+        frame: z.ZodObject<{
+            blockNumber: z.ZodNumber;
+            blockHash: z.ZodString;
+            blockTimestamp: z.ZodNumber;
+            deployment: z.ZodString;
+        }, z.core.$strict>;
+        acknowledged: z.ZodBoolean;
+    }, z.core.$strict>>;
+    finality: z.ZodLiteral<"checked-at-read-not-finalized">;
+}, z.core.$strict>;
+export declare const TransactionStatusErrorSchema: z.ZodObject<{
+    error: z.ZodLiteral<"Engine transaction status unavailable">;
+    code: z.ZodString;
+    status: z.ZodEnum<{
+        unavailable: "unavailable";
+        rate_limited: "rate_limited";
+    }>;
+}, z.core.$strict>;

package/dist/engine/account/transactions.d.ts

@@ -0,0 +1,26 @@
+import type { Address, Hex } from 'viem';
+export type AegisEngineTransactionScope = {
+    chainId: number;
+    account: Address;
+};
+export type AegisEngineTransactionRecord = AegisEngineTransactionScope & {
+    hash: Hex;
+    /** Superseded hashes preserve identity across replacement and storage merges. */
+    replacedHashes?: Hex[];
+    stage?: 'authorization' | 'action';
+    /** User accepted the risk of starting new actions while this hash is unresolved. */
+    recoveryAcknowledgedAt?: number;
+    executionChanged?: boolean;
+    kind: 'swap' | 'lend' | 'borrow' | 'trade';
+    status: 'submitted' | 'success' | 'reverted' | 'cancelled';
+    title: string;
+    detail: string;
+    createdAt: number;
+};
+export declare function engineTransactionStorageKey(scope: AegisEngineTransactionScope): string;
+/** Display metadata and identity only. Unknown fields, including signatures,
+ * permits and calldata, are rejected before the record reaches a consumer. */
+export declare function parseEngineTransactionRecords(value: string | null, scope: AegisEngineTransactionScope): AegisEngineTransactionRecord[];
+/** Pending identities are never evicted for completed history. A repeated
+ * submitted notification cannot weaken a receipt-backed outcome. */
+export declare function mergeEngineTransactionRecord(records: readonly AegisEngineTransactionRecord[], next: AegisEngineTransactionRecord): AegisEngineTransactionRecord[];

package/dist/engine/account/transport.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { AegisEngineAccountReadInput } from './types.js';
+export declare class AegisEngineAccountReadError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly retryAfterSeconds: number | null;
+    readonly name = "AegisEngineAccountReadError";
+    constructor(code: string, status?: number, retryAfterSeconds?: number | null);
+}
+export declare function parseEngineRetryAfter(retryHeader: string | null, cap?: number): number | null;
+export type ReadContext = {
+    input: AegisEngineAccountReadInput;
+    query: {
+        account: string;
+        chainIds: number[];
+    };
+    baseUrl: string;
+    signal: AbortSignal | undefined;
+    remainingBytes: number;
+};
+export declare function invalidResponse(): never;
+export declare function sameChains(actual: readonly number[], expected: readonly number[]): boolean;
+export declare function withAccountRead<T>(input: AegisEngineAccountReadInput, read: (context: ReadContext) => Promise<T>): Promise<T>;
+export declare function readResponse<T>(context: ReadContext, path: string, extra: Record<string, string>, schema: z.ZodType<T>, options?: {
+    omitChainIds?: boolean;
+    responseLimit?: number;
+}): Promise<T>;
+export declare function assertScope(context: ReadContext, payload: {
+    account: string;
+    chainIds: number[];
+}): void;

package/dist/engine/account/types.d.ts

@@ -0,0 +1,39 @@
+import type { z } from 'zod';
+import type { Address, Hex } from 'viem';
+import type { AegisEngineRestSource } from '../types.js';
+import type { ActivityPageResponseSchema, ActivityEventSchema } from './activitySchemas.js';
+import type { PortfolioResponseSchema, PortfolioPositionSchema, PortfolioMetricSchema, PortfolioPriceMarkSchema } from './portfolioSchemas.js';
+import type { TransactionStatusSchema } from './transactionSchemas.js';
+export type AegisEnginePortfolioPosition = z.output<typeof PortfolioPositionSchema>;
+export type AegisEnginePortfolioMetric = z.output<typeof PortfolioMetricSchema>;
+export type AegisEnginePortfolioPrice = z.output<typeof PortfolioPriceMarkSchema>;
+export type AegisEngineAccountPortfolio = Omit<z.output<typeof PortfolioResponseSchema>, 'page'> & {
+    /** Every page belongs to this snapshot; no partial page accumulation is returned. */
+    positions: AegisEnginePortfolioPosition[];
+    performance: {
+        status: 'unavailable';
+        reason: 'cashflow-cost-basis-unavailable';
+    };
+};
+export type AegisEngineAccountActivityEvent = z.output<typeof ActivityEventSchema>;
+export type AegisEngineAccountActivityPage = z.output<typeof ActivityPageResponseSchema>;
+export type AegisEngineTransactionStatus = z.output<typeof TransactionStatusSchema>;
+export type AegisEngineAccountReadInput = {
+    source: AegisEngineRestSource;
+    account: Address;
+    /** Distinct host-selected Engine chains. Each is retained in coverage. */
+    chainIds: readonly number[];
+    signal?: AbortSignal;
+};
+export type AegisEngineTransactionStatusInput = AegisEngineAccountReadInput & {
+    chainId: number;
+    txHash: Hex;
+    /** Optional previously observed receipt identity. Supply both fields together. */
+    observedReceipt?: {
+        blockNumber: number;
+        blockHash: Hex;
+    };
+};
+/** Identity for a persisted transaction; hashes alone are not cross-chain identities. */
+export declare function engineAccountTransactionKey(chainId: number, txHash: string): string;
+export declare function engineAccountPositionKey(position: Pick<AegisEnginePortfolioPosition, 'kind' | 'chainId' | 'engine' | 'vaultRegistry' | 'vaultId' | 'poolId'>, account: string): string;

package/dist/engine/actions.d.ts

@@ -12,8 +12,11 @@ export declare function engineTokenGrantSatisfies(args: {
     spendAmount: bigint;
     approvalMode: 'exact' | 'max';
 }): boolean;
-/** Mode-aware satisfaction for the Permit2 → router cap. `max` requires an
- *  effectively unlimited amount that is also not about to expire. */
+/** Mode-aware satisfaction for the Permit2 → router cap, on the same rule the
+ *  swap path uses: `max` requires an effectively unlimited amount, `exact`
+ *  requires coverage, and both require a cap that outlives the tx deadline. A
+ *  zero-amount draft asks only whether any live grant stands, so 1n stands in
+ *  for the amount and a revoked cap still fails. */
 export declare function enginePermit2GrantSatisfies(args: {
     allowance: Awaited<ReturnType<typeof readPermit2RouterAllowance>>;
     spendAmount: bigint;
@@ -30,7 +33,9 @@ export type AegisEnginePositionRouterAuthorizationInput = {
     /** Cancels preparation before the authorization transaction is broadcast. */
     signal?: AegisEngineSendInput['signal'];
     onStatus?: AegisEngineActionCallbacks['onStatus'];
+    onWalletRequest?: AegisEngineActionCallbacks['onWalletRequest'];
     onTxHash?: AegisEngineActionCallbacks['onTxHash'];
+    onTransactionObservation?: AegisEngineActionCallbacks['onTransactionObservation'];
 };
 /**
  * Read the wallet actions required to open a fresh Long/Short position.
@@ -50,12 +55,16 @@ export type AegisEnginePositionRouterAuthorizationInput = {
  * executable quote after prerequisite receipts are mined.
  */
 export declare function readEngineAuthorizationPlan(args: AegisEngineAuthorizationPlanInput): Promise<AegisEngineAuthorizationPlan>;
+type EngineAllowanceUpdateInput = AegisEngineApprovalInput & {
+    replaceAllowance?: boolean;
+    revokeAllowance?: boolean;
+};
 /** Grants only the ERC-20 allowance from the token to Permit2. */
-export declare function approveEngineTokenToPermit2(args: AegisEngineApprovalInput): Promise<{
+export declare function approveEngineTokenToPermit2(args: EngineAllowanceUpdateInput): Promise<{
     approvalHash: Hex | null;
 }>;
 /** Grants only the Permit2 spending cap from Permit2 to the Engine router. */
-export declare function approveEnginePermit2ToRouter(args: AegisEngineApprovalInput): Promise<void>;
+export declare function approveEnginePermit2ToRouter(args: EngineAllowanceUpdateInput): Promise<void>;
 export declare function prepareEnginePermit(args: AegisEngineApprovalInput): Promise<{
     approvalHash: Hex | null;
     permit: AegisEngineSignedPermitBatch | null;
@@ -99,3 +108,4 @@ export declare function missingEngineExecutionReason(market: {
     v4StateView?: Address;
     v4Quoter?: Address;
 }): string | null;
+export {};

package/dist/engine/adaptiveFee.d.ts

@@ -0,0 +1,14 @@
+import type { PublicClient } from 'viem';
+import type { AegisEngineAdaptiveFeeEvidence, AegisEngineMarket } from './types.js';
+/**
+ * Read the Engine v1.0.3 dynamic-fee state at the same block as a quote.
+ *
+ * `adaptiveTickThresholdTicks` is deliberately not called a price limit. The
+ * deployed Hook evaluates it after the swap and uses a breach to update surge
+ * state; it does not clamp or revert the transaction that crossed it.
+ */
+export declare function readEngineAdaptiveFeeEvidence(input: Readonly<{
+    publicClient: PublicClient;
+    market: AegisEngineMarket;
+    blockNumber: bigint;
+}>): Promise<AegisEngineAdaptiveFeeEvidence>;