@aegis-engine/core 0.2.0 → 0.3.0

package/dist/services/kyberSwap.d.ts

@@ -1,4 +1,5 @@
 import { type Address, type Hex } from 'viem';
+import { z } from 'zod';
 export type KyberSwapFeeParams = {
     feeAmount: string;
     chargeFeeBy: 'currency_in' | 'currency_out';
@@ -46,6 +47,13 @@ export type KyberSwapBuild = {
     routerAddress: Address;
     transactionValue?: string;
     requestId?: string;
+    /**
+     * Unix-seconds deadline this build was requested with. Client-computed (it
+     * is a request parameter, not part of the wire response); the encoded
+     * calldata reverts on-chain past this moment, so callers can fail fresh
+     * checks closed before prompting the wallet.
+     */
+    deadline?: number;
 };
 export type KyberSwapError = {
     code?: number;
@@ -64,8 +72,16 @@ export declare class KyberSwapApiError extends Error {
         body?: unknown;
     });
 }
+export declare class KyberSwapContractError extends Error {
+    readonly endpoint: string;
+    readonly issues: z.core.$ZodIssue[];
+    constructor({ endpoint, issues }: {
+        endpoint: string;
+        issues: z.core.$ZodIssue[];
+    });
+}
 export declare function isRetryableKyberSwapError(error: unknown): boolean;
-export declare function fetchKyberSwapRoute({ tokenIn, tokenOut, amountIn, chainId, origin, fee, signal }: {
+export declare function fetchKyberSwapRoute({ tokenIn, tokenOut, amountIn, chainId, origin, fee, signal, timeoutMs }: {
     tokenIn: Address;
     tokenOut: Address;
     amountIn: string;
@@ -73,12 +89,16 @@ export declare function fetchKyberSwapRoute({ tokenIn, tokenOut, amountIn, chain
     origin?: Address | null;
     fee?: KyberSwapFeeParams | null;
     signal?: AbortSignal;
+    /** Abort after this many ms (composes with `signal`); defaults to 20s. */
+    timeoutMs?: number;
 }): Promise<KyberSwapRoute>;
-export declare function buildKyberSwapRoute({ routeSummary, sender, recipient, slippageBps, chainId, signal }: {
+export declare function buildKyberSwapRoute({ routeSummary, sender, recipient, slippageBps, chainId, signal, timeoutMs }: {
     routeSummary: KyberSwapRouteSummary;
     sender: Address;
     recipient: Address;
     slippageBps: number;
     chainId?: number;
     signal?: AbortSignal;
+    /** Abort after this many ms (composes with `signal`); defaults to 20s. */
+    timeoutMs?: number;
 }): Promise<KyberSwapBuild>;

package/dist/swap/receiptWait.d.ts

@@ -0,0 +1,17 @@
+import { type Hex, type PublicClient, type TransactionReceipt } from 'viem';
+export declare const APPROVAL_RECEIPT_TIMEOUT_MS: number;
+export declare const SWAP_RECEIPT_TIMEOUT_MS: number;
+type OnReplacedParameter = NonNullable<Parameters<PublicClient['waitForTransactionReceipt']>[0]['onReplaced']>;
+/**
+ * waitForTransactionReceipt with a hard timeout, mapping viem's timeout error
+ * to the SDK's TransactionReceiptTimeoutError (which carries the tx hash so
+ * the UI can degrade to an explorer link). Every other failure passes through
+ * untouched.
+ */
+export declare function waitForReceiptWithTimeout(args: {
+    publicClient: PublicClient;
+    hash: Hex;
+    timeoutMs: number;
+    onReplaced?: OnReplacedParameter;
+}): Promise<TransactionReceipt>;
+export {};

package/dist/swap/sendSwapTransaction.d.ts

@@ -1,16 +1,44 @@
 import { type Address, type Chain, type Hex, type PublicClient, type TransactionReceipt } from 'viem';
 import type { AegisSwapReceiptSummary } from '../transactionProgress.js';
+import { type SwapSettlementContext } from './settlement.js';
 import type { AegisSwapSubmitDetails, WalletSession } from './types.js';
 /**
- * Sends a prepared swap transaction and waits for its receipt.
+ * Guarded send pipeline shared by the swap and engine planes.
+ *
+ * Immediately before requesting the signature it re-reads the wallet's active
+ * chain and fails closed on a mismatch (assertChainMatches): multi-prompt
+ * flows leave room for a wallet-side chain switch, and viem's chainId field
+ * is only honored by well-behaved wallets.
  *
  * Surfaces the optimistic hash through `onHash` (and `onSubmitted`) before
- * mining, then tracks replacements: a wallet speed-up swaps in the hash that
- * actually mines, while a wallet cancel mines a no-op whose "successful" receipt
- * must not count as a swap — so a cancelled or reverted receipt throws. Callers
- * compute their own gas and pass it via `gas`, so each keeps its gas strategy
- * (omit `gas` to let the wallet estimate).
+ * mining; a throwing host `onSubmitted` callback is swallowed with a warning
+ * rather than failing an already-submitted transaction. Then tracks
+ * replacements: a wallet speed-up swaps in the hash that actually mines,
+ * while a wallet cancel mines a no-op whose "successful"
+ * receipt must not count as success — so a cancelled or reverted receipt
+ * throws (`cancelledMessage`/`revertedMessage`). Callers compute their own
+ * gas and pass it via `gas`, so each keeps its gas strategy (omit `gas` to
+ * let the wallet estimate). The receipt wait carries a hard timeout; a
+ * dropped transaction surfaces as TransactionReceiptTimeoutError (with the
+ * hash) instead of hanging the flow forever.
  */
+export declare function sendGuardedTransactionAndAwait(args: {
+    wallet: WalletSession;
+    publicClient: PublicClient;
+    chain: Chain;
+    to: Address;
+    data: Hex;
+    value: bigint;
+    gas?: bigint;
+    cancelledMessage: string;
+    revertedMessage: string;
+    onHash?: (hash: Hex | null) => void;
+    onSubmitted?: (hash: Hex) => void;
+}): Promise<{
+    receipt: TransactionReceipt;
+    summary: AegisSwapReceiptSummary;
+}>;
+/** Sends a prepared swap transaction through the shared guarded-send pipeline. */
 export declare function sendSwapTransactionAndAwait(args: {
     wallet: WalletSession;
     publicClient: PublicClient;
@@ -20,6 +48,12 @@ export declare function sendSwapTransactionAndAwait(args: {
     value: bigint;
     gas?: bigint;
     swapDetails: AegisSwapSubmitDetails;
+    /**
+     * When provided, the summary also carries `settledAmountOut` decoded from
+     * the mined receipt (Transfer logs for ERC-20 output, balance delta for
+     * native). Best-effort: decoding failures leave the field undefined.
+     */
+    settlement?: SwapSettlementContext;
     onHash?: (hash: Hex | null) => void;
     onSubmitted?: (hash: Hex, swap?: AegisSwapSubmitDetails) => void;
 }): Promise<{

package/dist/swap/settlement.d.ts

@@ -0,0 +1,15 @@
+import { type Address, type PublicClient, type TransactionReceipt } from 'viem';
+export type SwapSettlementContext = {
+    /** Account the swap output settles to (the tx sender in both action flows). */
+    recipient: Address;
+    /** Output token address; zero address or the 0xEeee… sentinel means native. */
+    outputToken: Address;
+};
+/**
+ * Best-effort decode of what the swap actually settled to the recipient:
+ * summed ERC-20 Transfer logs for token output, balance delta for native
+ * output. Returns undefined — never throws — when the receipt cannot answer
+ * (lean RPC without logs, balance lookup failure), so a successful swap is
+ * never failed retroactively over display data.
+ */
+export declare function resolveSettledAmountOut(publicClient: PublicClient, receipt: TransactionReceipt, settlement: SwapSettlementContext): Promise<bigint | undefined>;

package/dist/transactionProgress.d.ts

@@ -12,6 +12,13 @@ export type AegisSwapReceiptSummary = {
     effectiveGasPrice: bigint;
     /** gasUsed * effectiveGasPrice — the L2-exclusive execution fee in native wei. */
     feeWei: bigint;
+    /**
+     * Output amount that actually settled to the recipient, decoded from the
+     * mined receipt (summed ERC-20 Transfer logs, or the native balance delta).
+     * Best-effort and optional: absent when the receipt cannot answer, in which
+     * case UIs should keep showing the quote estimate with a "~" affordance.
+     */
+    settledAmountOut?: bigint;
 };
 export declare function isBusy(status: SubmitStatus): boolean;
 export type TransactionProgressState = 'pending' | 'mining' | 'success' | 'error';
@@ -43,7 +50,7 @@ export declare function transactionProgressView({ status, inputSymbol, txHash, a
 export type AegisSwapStatusSnapshot = {
     status: SubmitStatus;
     progress: TransactionProgressState | null;
-    /** The rail's phase copy (e.g. "Approving USDC for Permit2 · wallet prompt 1 of 3"); null while idle. */
+    /** The rail's phase copy (e.g. "Approving USDC"); null while idle. */
     label: string | null;
     /** Swap-flow wallet provider prompt count/progress, derived from current allowances. */
     walletPrompts: AegisSwapWalletPromptProgress;

package/dist/types/aggregatedSwap.d.ts

@@ -15,6 +15,20 @@ export type AggregatedSwapQuote = {
     hops: HopInfo[];
     routerAddress: Address;
     calldata: Hex | null;
+    /**
+     * keccak256 of `calldata`, committed when the route was built. Execution
+     * verifies the bytes handed to the wallet against this hash
+     * (assertCalldataHash) so tx economics cannot be rewritten in between.
+     * Optional so host-constructed display quotes stay valid.
+     */
+    calldataHash?: Hex | null;
+    /**
+     * ISO timestamp of the built calldata's embedded deadline; the transaction
+     * reverts on-chain past it, so execution fails closed (assertQuoteFresh)
+     * instead of prompting the wallet for a doomed swap. Absent on display
+     * quotes fetched without an account.
+     */
+    expiresAt?: string;
     transactionValue: bigint;
     priceImpact: number;
     feeAmount: bigint;
@@ -22,6 +36,10 @@ export type AggregatedSwapQuote = {
     feeRecipient: Address | null;
     userAmountOutMinimum: bigint;
     amountOutMinimum: bigint;
+    /** USD values from the aggregator's route summary, when present. */
+    amountInUsd?: number;
+    amountOutUsd?: number;
+    gasUsd?: number;
 };
 export type AggregatedSwapRoute = {
     inputToken: AegisSwapToken;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aegis-engine/core",
-  "version": "0.2.0",
-  "description": "React-free Aegis swap operations for direct Uniswap v4 pools and KyberSwap routes.",
+  "version": "0.3.0",
+  "description": "React-free Aegis Swap and Engine quoting, risk, approval, and execution operations.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/aegis-core.js",
@@ -10,22 +10,30 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/aegis-core.js"
-    }
+      "import": "./dist/aegis-core.js",
+      "require": null,
+      "default": "./dist/aegis-core.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "peerDependencies": {
-    "viem": "^2"
+    "viem": "^2.23.1"
   },
   "devDependencies": {
+    "@labs-solo/aegis-engine-sdk": "0.30.0",
     "@types/node": "^25.9.1",
     "openapi-typescript": "^7.13.0",
     "typescript": "~5.6.2",
-    "viem": "^2.52.0",
+    "viem": "^2.54.3",
     "vite": "^6.0.1",
     "vitest": "^4.1.8"
   },