@aegis-engine/core 0.6.0 → 0.8.0

package/dist/engine/types.d.ts

@@ -1,3 +1,4 @@
+import type { AegisTransactionObservation } from '../swap/receiptWait.js';
 import type { Address, Hex, PublicClient, TransactionReceipt } from 'viem';
 import type { AegisSwapChainConfig, AegisSwapToken } from '../config/index.js';
 import type { SignedPermitBatch } from '../encoding.js';
@@ -30,6 +31,13 @@ export type AegisEngineMarketMetrics = {
     manualOverride?: boolean | null;
     perSwapMode?: boolean | null;
     feeSource?: string | null;
+    /** Post-swap surge-trigger threshold from the opt-in REST v2 market plane.
+     * It is observability data, not a hard price, tick, or slippage limit. */
+    adaptiveTickThresholdTicks?: number;
+    /** Present exactly when adaptiveTickThresholdTicks is present. */
+    adaptiveTickThresholdMode?: 'post_swap_surge_trigger';
+    /** Fee-quote observation time from the opt-in REST v2 market plane. */
+    feeObservedAt?: string | null;
     computedAt?: string | null;
     updatedAt?: string | null;
     engineUpdatedAt?: string | null;
@@ -55,6 +63,7 @@ export type AegisEngineMarket = {
     source: AegisEngineMarketSource;
     status: AegisEngineMarketStatus;
     displayName: string;
+    labels?: string[];
     poolId: Hex;
     token0: AegisEngineToken;
     token1: AegisEngineToken;
@@ -109,6 +118,14 @@ export type AegisEngineMetricPoint = {
     inCapEvent: boolean | null;
     manualOverride: boolean | null;
     perSwapMode: boolean | null;
+    /** Required-nullable on the REST v2 wire; absent only after a 404 fallback
+     * to the frozen v1 history endpoint. */
+    adaptiveTickThresholdTicks?: number | null;
+    /** Paired with adaptiveTickThresholdTicks; describes a post-swap trigger,
+     * never an execution cap. */
+    adaptiveTickThresholdMode?: 'post_swap_surge_trigger' | null;
+    /** Required-nullable on the REST v2 wire; absent after a v1 fallback. */
+    feeObservedAt?: string | null;
     warnings: string[];
 };
 export type AegisEngineMetricHistory = {
@@ -347,8 +364,8 @@ export type AegisEnginePositionActivitySnapshot = {
 /** 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. */
+ * opening transaction. Indexed actions identify the opening direction; they do not prove an
+ * executed entry price. */
 export type AegisEngineTradePositionIntent = {
     schemaVersion: '1';
     chainId: number;
@@ -367,7 +384,7 @@ export type AegisEngineTradePositionIntent = {
 /** 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. */
+ * supply execution evidence. */
 export type AegisEngineTradePositionStrategy = {
     kind: 'trade';
     vaultId: string;
@@ -375,8 +392,16 @@ export type AegisEngineTradePositionStrategy = {
     direction: AegisEngineTradeDirection;
     openTxHash: Hex;
     openedAt: number;
-    /** Executed opening spot, token1 per token0, derived from DebtModified. */
+    /** Receipt-reconciled opening swap price in token1 per token0. Indexed
+     * Engine actions alone leave this null; this is not wallet cost basis or PnL. */
     entryPrice: number | null;
+    /** Missing on legacy host records; consumers must treat those as unverified. */
+    entryPriceBasis?: 'receipt-reconciled' | 'unavailable';
+    /** Informational debt-action ratio only. Never substitute it for entryPrice. */
+    referencePrice?: {
+        basis: 'debt-action-token-ratio';
+        price: 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. */
@@ -396,6 +421,12 @@ export type AegisEngineBorrowPositionHydration = {
         rL: bigint;
         /** Accrued debt in L units at this hydration frame. */
         debtLLatest: bigint;
+        /** Rounded-up full-range repayment legs at the same verified block.
+         * Null/absent means USD debt and equity must not be estimated from L alone. */
+        debtAmounts?: {
+            amount0: bigint;
+            amount1: bigint;
+        } | null;
         idle0: bigint;
         idle1: bigint;
         /** Null when the vault has no debt, never a synthetic zero. */
@@ -440,6 +471,7 @@ export type AegisEnginePositionsHydrationInput = {
 export type AegisEngineRestSource = {
     kind: 'rest';
     baseUrl: string;
+    includeLabels?: boolean;
     headers?: Record<string, string>;
     /**
      * Maximum time for a shared REST request, including response-body parsing.
@@ -456,6 +488,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[];
@@ -521,6 +556,21 @@ export type AegisEngineReadFrame = {
     /** Local wall-clock time when the frame was assembled, in Unix milliseconds. */
     observedAt: number;
 };
+/** Block-pinned DFM state. The threshold is observed after execution and can
+ * activate or adapt surge fees; it is not an on-chain swap limit. */
+export type AegisEngineAdaptiveFeeEvidence = {
+    source: 'rpc';
+    enforcement: 'post-swap-surge-trigger';
+    evaluationScope: 'per-swap' | 'per-block';
+    blockNumber: bigint;
+    activeFeePpm: number;
+    baseFeePpm: number;
+    surgeFeePpm: number;
+    adaptiveTickThresholdTicks: number;
+    surgeActive: boolean;
+    inCapEvent: boolean;
+    manualOverride: boolean;
+};
 export type AegisEngineVersion = 'v0.4.0' | 'v1.0.2' | 'v1.0.3';
 export type AegisEngineBorrowMarketContext = {
     poolId: Hex;
@@ -584,6 +634,9 @@ export type AegisEngineQuoteBase = {
 };
 export type AegisEngineDepositQuoteInput = AegisEngineQuoteBase & {
     amountIn: bigint;
+    /** Required host policy. A swap quote above this block-pinned impact is
+     *  returned as non-executable; this is independent of output slippage. */
+    maxPriceImpactBps: number;
 };
 /**
  * Live snapshot of an already-open borrow vault, in the pool's real token
@@ -632,6 +685,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;
@@ -641,7 +698,7 @@ export type AegisEngineBorrowCapacityInput = Omit<AegisEngineQuoteBase, 'owner'
 export type AegisEngineDepositQuoteResult = {
     feasible: boolean;
     executable: boolean;
-    infeasibleReason?: 'invalid-input' | 'quote-unavailable' | 'insufficient-output' | 'zero-liquidity' | 'builder-error';
+    infeasibleReason?: 'invalid-input' | 'quote-unavailable' | 'price-impact-unavailable' | 'price-impact-limit' | 'insufficient-output' | 'zero-liquidity' | 'builder-error';
     /** SDK recipe input retained for diagnostics. Use `tx` on the enclosing
      * Core quote for execution instead of encoding this value downstream. */
     encodeInput: unknown | null;
@@ -699,6 +756,9 @@ export type AegisEngineDepositQuote = {
     kind: 'lend';
     market: AegisEngineMarket;
     inputToken: AegisEngineToken;
+    /** Same-block DFM evidence when the trusted RPC read succeeded. Null means
+     *  the quote carries no adaptive-fee observation, never a zero threshold. */
+    adaptiveFee?: AegisEngineAdaptiveFeeEvidence | null;
     quote: AegisEngineDepositQuoteResult;
     tx: AegisEnginePreparedTransaction | null;
 };
@@ -798,12 +858,28 @@ export type AegisEngineTradeOpenQuoteInput = {
     /** @deprecated Ignored. Spec-0168 always selects the lower-debt frontier. */
     rootPolicy?: AegisEngineTapRootPolicy;
     slippageBps: number;
+    /** Required host policy. Core rejects a block-pinned internal swap whose
+     *  price impact exceeds this value. It is not a pool-movement invariant. */
+    maxPriceImpactBps: 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;
 };
+/** Exact caller-owned strategy and safety policy that produced a Trade quote.
+ * Execution sessions bind this echo before any wallet request. */
+export type AegisEngineTradeOpenQuoteIntent = Readonly<{
+    owner: Address;
+    inputIsToken0: boolean;
+    collateralIn: bigint;
+    /** Null means the quote selected the live maximum. */
+    leverage: number | null;
+    horizonSeconds: number;
+    priceMove: number;
+    slippageBps: number;
+    maxPriceImpactBps: number;
+}>;
 export type AegisEngineTradeOpenInfeasibleReason = AegisEngineTapInfeasibleReason['kind']
 /** The chosen root's swap trades against the requested direction at entry. */
  | 'swap-direction-mismatch'
@@ -814,7 +890,11 @@ export type AegisEngineTradeOpenInfeasibleReason = AegisEngineTapInfeasibleReaso
 /** 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';
+ | 'stale-frame'
+/** The block-pinned quote could not produce a finite impact assessment. */
+ | 'price-impact-unavailable'
+/** The block-pinned quote exceeded the host's required impact limit. */
+ | 'price-impact-limit';
 /** Actionable bounds for a rejected quote. Each field is null when the
  *  rejection did not produce one. */
 export type AegisEngineTradeOpenLimits = {
@@ -860,8 +940,25 @@ export type AegisEngineTradeOpenPosition = {
     /** Gross return from exact entry equity to target equity, before horizon
      *  interest. The encoded swap output floor is already reflected in both. */
     grossReturnAtTargetPct: number;
+    /** Indicative equity at the reviewed prices, in token1 major units. Uses
+     * the quote rate held constant; excludes gas and future closing costs. */
+    scenario?: {
+        entryEquity: number;
+        targetEquityAfterInterest: number;
+        targetInterest: number;
+    };
     /** Borrow principal in rL units. */
     principalDeltaRl: bigint;
+    /**
+     * Market utilization immediately before and after this position's final,
+     * integer-rounded debt is added. Both values come from the quote's pinned
+     * market frame; consumers must not mix in a REST utilization snapshot.
+     */
+    marketUtilization?: {
+        beforePips: number;
+        afterPips: number;
+        capPips?: number;
+    };
     /** Vault idle at lock, in base units — the collateral `lockVault` values. */
     collateral0: bigint;
     collateral1: bigint;
@@ -887,6 +984,8 @@ export type AegisEngineTradeOpenQuote = {
     market: AegisEngineMarket;
     direction: AegisEngineTradeDirection;
     collateralToken: AegisEngineToken;
+    /** Exact request identity used to build this quote. */
+    intent: AegisEngineTradeOpenQuoteIntent;
     /** Thresholds read in the same live frame used to size the position. */
     thresholds: {
         maxLtvPips: number;
@@ -901,6 +1000,8 @@ export type AegisEngineTradeOpenQuote = {
     position: AegisEngineTradeOpenPosition | null;
     /** Null when the borrow already delivers the target mix. */
     swap: AegisEngineTradeOpenSwap | null;
+    /** Same-block DFM evidence. This is review telemetry, not an execution cap. */
+    adaptiveFee?: AegisEngineAdaptiveFeeEvidence | null;
     deposit: {
         amount0: bigint;
         amount1: bigint;
@@ -967,6 +1068,13 @@ export type AegisEnginePositionActionQuote = {
     } | null;
     /** Borrow principal affected by repay/close, in rL units. */
     principalDeltaRl: bigint | null;
+    requestedRepayProjection?: {
+        ltvPips: number | null;
+        debtFree: boolean;
+        idle0: bigint;
+        idle1: bigint;
+        debtL: bigint;
+    } | null;
     /** Exact idle token amounts requested by withdraw. */
     withdraw: {
         amount0: bigint;
@@ -1120,6 +1228,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;
@@ -1135,16 +1261,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;
@@ -1177,7 +1312,10 @@ export type AegisEnginePreparedTransaction = {
 export type AegisEngineSignedPermitBatch = SignedPermitBatch;
 export type AegisEngineWalletSession = WalletSession;
 export type AegisEngineActionCallbacks = {
+    onTransactionObservation?: (event: AegisTransactionObservation) => void;
     onStatus?: (status: 'approving' | 'signing' | 'submitting' | 'success' | 'idle') => void;
+    /** Fires after simulation and chain guards, immediately before the wallet request. */
+    onWalletRequest?: () => void;
     onTxHash?: (hash: Hex | null) => void;
     onSubmitted?: (hash: Hex) => void;
 };
@@ -1201,8 +1339,11 @@ export type AegisEngineAuthorizationStep = {
     id: AegisEngineAuthorizationStepKind;
     kind: AegisEngineAuthorizationStepKind;
     status: AegisEngineAuthorizationStepStatus;
-    /** Every current Long/Short authorization is an on-chain wallet transaction. */
-    walletAction: 'transaction';
+    /**
+     * Wallet interaction required by this step. Permit2 signature mode can fall
+     * back to an on-chain spending-cap transaction when typed data is unavailable.
+     */
+    walletAction: 'transaction' | 'signature-or-transaction';
     /** Contract the wallet action targets. */
     target: Address;
     /** Contract receiving authority, when distinct from the target. */
@@ -1211,6 +1352,7 @@ export type AegisEngineAuthorizationStep = {
     token: AegisEngineToken | null;
     /** Current on-chain allowance, when the step governs a token amount. */
     currentAmount: bigint | null;
+    currentExpiration?: number | 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. */
@@ -1229,6 +1371,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;
@@ -1237,7 +1385,7 @@ export type AegisEngineAuthorizationPlan = {
     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. */
+    /** Sequential wallet-action count. A network switch is reported separately. */
     walletPromptCount: number;
     /** True when only the final position transaction remains. */
     readyForOpen: boolean;
@@ -1252,12 +1400,16 @@ export type AegisEngineAuthorizationPlanInput = {
     token: AegisEngineToken;
     amount: bigint;
     approvalMode?: 'exact' | 'max';
+    /** Must match the authorization mode used when the reviewed plan is executed. */
+    permit2AuthorizationMode?: 'signature' | 'spending-cap';
 };
 export type AegisEngineAuthorizationProgress = {
     kind: AegisEngineAuthorizationStepKind;
     status: 'requesting' | 'confirmed';
 };
-/** Lifecycle evidence for one Engine permission request. */
+/** Truthful per-prerequisite lifecycle. Kept separate from the legacy
+ * requesting/confirmed projection so existing exhaustive consumers do not
+ * break when submitted and terminal states are added. */
 export type AegisEngineAuthorizationExecutionEvent = Readonly<{
     kind: AegisEngineAuthorizationStepKind;
     status: 'wallet-requested';
@@ -1266,13 +1418,15 @@ export type AegisEngineAuthorizationExecutionEvent = Readonly<{
     kind: AegisEngineAuthorizationStepKind;
     status: 'submitted';
     hash: Hex;
+    replacesHash?: Hex;
+    executionChanged?: boolean;
 }> | Readonly<{
     kind: AegisEngineAuthorizationStepKind;
     status: 'confirmed';
     hash: Hex | null;
 }> | Readonly<{
     kind: AegisEngineAuthorizationStepKind;
-    status: 'cancelled' | 'failed';
+    status: 'failed' | 'cancelled';
     hash: Hex | null;
     error: ClassifiedError;
 }>;
@@ -1280,9 +1434,9 @@ export type AegisEngineApprovalInput = {
     wallet: AegisEngineWalletSession;
     publicClient: PublicClient;
     activeChain: AegisSwapChainConfig;
+    /** Reviewed market used to resolve Permit2 and router from the trusted registry. */
+    market: AegisEngineMarket;
     token: AegisEngineToken;
-    permit2: Address;
-    router: Address;
     amount: bigint;
     approvalMode?: 'exact' | 'max';
     permit2AuthorizationMode?: 'signature' | 'spending-cap';
@@ -1291,7 +1445,7 @@ 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. */
+    /** Full prerequisite lifecycle at the real wallet and receipt boundaries. */
     onAuthorizationExecution?: (event: AegisEngineAuthorizationExecutionEvent) => void;
     /** Awaited after each prerequisite receipt and before another wallet request. */
     onAuthorizationCheckpoint?: () => Promise<void>;

package/dist/engine/v4Quote.d.ts

@@ -0,0 +1,5 @@
+export type AegisEngineV4ExactInputFrameQuote = Readonly<{
+    amountOut: bigint;
+    gasEstimate: bigint;
+    blockNumber: bigint;
+}>;

package/dist/index.d.ts

@@ -1,37 +1,40 @@
-export { AEGIS_DYNAMIC_FEE_FLAG, AEGIS_SWAP_CHAINS, AEGIS_SWAP_CHAIN_ID, AEGIS_SWAP_DEFAULT_FEE_BPS, AEGIS_SWAP_DEFAULT_FEE_RECIPIENT, AEGIS_SWAP_DEFAULT_METADATA_ENDPOINT, AEGIS_SWAP_DEFAULT_RPC_URLS, AEGIS_SWAP_HOOK, AEGIS_SWAP_MAINNET_CHAIN, AEGIS_SWAP_MAINNET_UNISWAP_V4_CONTRACTS, AEGIS_SWAP_PERMIT2, AEGIS_SWAP_ROUTER, AEGIS_SWAP_TOKENS, AEGIS_SWAP_TRUSTED_ROUTERS_BY_CHAIN, AEGIS_SWAP_V4_QUOTER, AGGREGATED_SWAP_CURATED_TOKENS, AGGREGATED_SWAP_DEFAULT_TOKEN_LIST, AGGREGATED_SWAP_DEFAULT_TOKENS, AGGREGATED_SWAP_SUPPORTED_CHAIN_IDS, AGGREGATED_SWAP_TOKEN_PRESETS, AGGREGATED_SWAP_WOLFGAME_TOKEN_LIST, AGGREGATED_SWAP_WOLFGAME_TOKENS, UNISWAP_V4_CONTRACTS_BY_CHAIN, createAegisSwapChainConfig, createAegisSwapChains, createAegisSwapMarketsFromPools, createAegisSwapPoolMarket, createAegisSwapUniswapV4Contracts, getExplorerUrl } from './config/index.js';
-export type { AegisPoolKey, AegisSwapBuiltInTokenSymbol, AegisSwapChainConfig, AegisSwapChainConfigInput, AegisSwapFeeConfig, AegisSwapMarket, AegisSwapPoolConfig, AegisSwapToken, AegisSwapTokenSymbol, AegisSwapUniswapV4Contracts, AegisSwapUniswapV4ContractsInput, AggregatedSwapDefaultTokenSymbol, AggregatedSwapToken, AggregatedSwapTokenSymbol, AggregatedSwapWolfGameTokenSymbol } from './config/index.js';
+export { AEGIS_DYNAMIC_FEE_FLAG, AEGIS_SWAP_BSC_CHAIN, AEGIS_SWAP_BSC_CHAIN_ID, AEGIS_SWAP_BSC_HOOK, AEGIS_SWAP_BSC_ROUTER, AEGIS_SWAP_BSC_RPC_URLS, AEGIS_SWAP_BSC_TOKENS, AEGIS_SWAP_CHAINS, AEGIS_SWAP_CHAIN_ID, AEGIS_SWAP_DEFAULT_FEE_BPS, AEGIS_SWAP_DEFAULT_FEE_RECIPIENT, AEGIS_SWAP_DEFAULT_METADATA_ENDPOINT, AEGIS_SWAP_DEFAULT_RPC_URLS, AEGIS_SWAP_HOOK, AEGIS_SWAP_MAINNET_CHAIN, AEGIS_SWAP_MAINNET_UNISWAP_V4_CONTRACTS, AEGIS_SWAP_PERMIT2, AEGIS_SWAP_ROUTER, AEGIS_SWAP_TOKENS, AEGIS_SWAP_TRUSTED_ROUTERS_BY_CHAIN, AEGIS_SWAP_V4_QUOTER, AGGREGATED_SWAP_CURATED_TOKENS, AGGREGATED_SWAP_DEFAULT_TOKEN_LIST, AGGREGATED_SWAP_DEFAULT_TOKENS, AGGREGATED_SWAP_SUPPORTED_CHAIN_IDS, AGGREGATED_SWAP_TOKEN_PRESETS, AGGREGATED_SWAP_WOLFGAME_TOKEN_LIST, AGGREGATED_SWAP_WOLFGAME_TOKENS, UNISWAP_V4_CONTRACTS_BY_CHAIN, createAegisSwapChainConfig, createAegisSwapChains, createAegisSwapMarketsFromPools, createAegisSwapPoolMarket, createAegisSwapUniswapV4Contracts, getExplorerUrl } from './config/index.js';
+export type { AegisPoolKey, AegisSwapBscTokenSymbol, AegisSwapBuiltInTokenSymbol, AegisSwapChainConfig, AegisSwapChainConfigInput, AegisSwapFeeConfig, AegisSwapMarket, AegisSwapPoolConfig, AegisSwapToken, AegisSwapTokenSymbol, AegisSwapUniswapV4Contracts, AegisSwapUniswapV4ContractsInput, AggregatedSwapDefaultTokenSymbol, AggregatedSwapToken, AggregatedSwapTokenSymbol, AggregatedSwapWolfGameTokenSymbol } from './config/index.js';
 export { assertUint128, buildExactInSwapTransaction, buildExactOutSwapTransaction, computePoolId, MAX_UINT128 } from './encoding.js';
 export type { BuiltSwapTransaction, ExecutionBatch, PermitBatch, PermitDetails, SignedPermitBatch, SwapOutputFee } from './encoding.js';
 export { getZeroForOne, outputFeeForQuote, quoteSpendAmount, reconcileSubmitQuote, sameQuote } from './quote.js';
 export type { DirectSwapQuote, ReconciledSubmitQuote, SwapQuoteMode } from './quote.js';
 export { AggregatedSwapBuildMismatchError, aggregatedSwapErrorMessage, fetchAggregatedSwapQuote } from './quote/aggregatedSwapQuote.js';
+export type { AggregatedSwapExecutionIntent } from './quote/aggregatedSwapQuote.js';
 export { AggregatedSwapCalldataError } from './quote/kyberCalldata.js';
 export type { AggregatedSwapQuote, AggregatedSwapRoute, HopInfo } from './types/aggregatedSwap.js';
-export { KyberSwapApiError, KyberSwapContractError, buildKyberSwapRoute, fetchKyberSwapRoute, isRetryableKyberSwapError } from './services/kyberSwap.js';
+export { KyberSwapApiError, KyberSwapContractError, KyberSwapResourceLimitError, buildKyberSwapRoute, fetchKyberSwapRoute, isRetryableKyberSwapError } from './services/kyberSwap.js';
 export type { KyberSwapBuild, KyberSwapError, KyberSwapFeeParams, KyberSwapRoute, KyberSwapRouteLeg, KyberSwapRouteSummary } from './services/kyberSwap.js';
-export { approveErc20Spender, approveErc20ToPermit2, approvePermit2ToRouter, buildSignedPermitBatch, DEFAULT_PERMIT_EXPIRATION_SECONDS, MAX_UINT160, MAX_UINT256, PERMIT2_FAR_FUTURE_EXPIRATION, readErc20Allowance, readPermit2RouterAllowance, SWAP_TX_DEADLINE_SECONDS } from './permit.js';
+export { approveErc20Spender, approveErc20ToPermit2, approvePermit2ToRouter, buildSignedPermitBatch, DEFAULT_PERMIT_EXPIRATION_SECONDS, hasUsablePermit2Allowance, isUnlimitedErc20Approval, isUnlimitedPermit2Approval, MAX_UINT160, MAX_UINT256, PERMIT2_FAR_FUTURE_EXPIRATION, readErc20Allowance, readPermit2RouterAllowance, SWAP_TX_DEADLINE_SECONDS, UNLIMITED_ERC20_FLOOR, UNLIMITED_PERMIT2_FLOOR } from './permit.js';
 export { fetchGlobalTokenMetadata, resolveTokenIconUrl } from './metadata.js';
 export type { AegisSwapGlobalTokenMetadata, TokenMetadataByAddress } from './metadata.js';
-export { clearTokenPriceHistoryCache, fetchTokenPriceHistory, peekTokenPriceHistory } from './historicalPrices.js';
+export { clearTokenPriceHistoryCache, fetchTokenPriceHistory, peekTokenPriceHistory, tokenPriceHistoryRestResponseSchema } from './historicalPrices.js';
 export type { AegisTokenPriceHistory, AegisTokenPriceHistoryStatus, AegisTokenPriceHistoryWindow, AegisTokenPricePoint } from './historicalPrices.js';
-export { createSwapPublicClient, getInjectedProvider, getProviderAccount, getProviderChainId, isEip1193Provider, normalizeAccount, normalizeWalletConnection, requestProviderAccount, subscribeProvider, switchProviderChain } from './wallet.js';
+export { createSwapPublicClient, getInjectedProvider, getProviderAccount, getProviderChainId, isEip1193Provider, normalizeAccount, normalizeWalletConnection, requestProviderAccount, SDK_RPC_MULTICALL_RULE_ID, subscribeProvider, switchProviderChain } from './wallet.js';
 export type { AegisSwapProviderResolver, AegisSwapWalletConnection, Eip1193Provider, ProviderChainConfig } from './wallet.js';
 export { approveDirectPoolSwapInput, DirectPoolSwapPriceMovedError, executeDirectPoolSwap, fetchDirectPoolSwapQuote } from './actions/directPoolSwap.js';
 export type { DirectPoolSwapApprovalResult } from './actions/directPoolSwap.js';
 export { isNativeAssetAddress } from './address.js';
 export { approveKyberSwapInput, executeKyberSwap, isNativeToken, KyberSwapPriceMovedError, NATIVE_TOKEN_ADDRESS } from './actions/kyberSwap.js';
 export type { KyberSwapApprovalResult } from './actions/kyberSwap.js';
+export { erc20ApprovalRequest, requiresErc20ApprovalReset } from './actions/allowance.js';
 export { ensureWalletChain, resolveWalletSession, waitForProviderChain } from './actions/wallet.js';
 export type { AegisSwapActionCallbacks, AegisSwapActionResult, AegisSwapApprovalProgress, AegisSwapApprovalRequest, AegisSwapAuthorizationProgress } from './actions/types.js';
 export { estimateSwapGasWithBuffer } from './swap/gas.js';
 export type { SwapGasRequest } from './swap/gas.js';
+export { assertDirectSwapMarketTrusted, authorizeHostDirectSwapMarket, DIRECT_SWAP_MARKET_TRUST_RULE_ID, DirectSwapMarketTrustError, isDirectSwapMarketTrusted } from './swap/trustedMarket.js';
 export type { AegisSwapApprovalMode, AegisSwapSubmitDetails, WalletSession } from './swap/types.js';
 export { classifyError, errorMessage, isSubmittedTransactionReceiptError, isUserRejectedError, SubmittedTransactionReceiptError, TransactionReceiptTimeoutError, USER_REJECTED_MESSAGE, UserFacingError } from './errors.js';
 export type { ClassifiedError, UserFacingErrorKind } from './errors.js';
-export { isBusy, transactionProgressView } from './transactionProgress.js';
+export { isBusy, progressRailSteps, transactionProgressView, transactionSequenceProgress } from './transactionProgress.js';
 export type { AegisSwapReceiptSummary, AegisSwapStatusSnapshot, AegisSwapStatusTransactionContext, AegisSwapStatusTransactionToken, AegisSwapWalletPromptProgress, SubmitStatus, TransactionProgressState, TransactionProgressView } from './transactionProgress.js';
 export { reconcileSubmittedReceipt } from './swap/receiptWait.js';
-export type { SubmittedReceiptOutcome } from './swap/receiptWait.js';
+export type { SubmittedReceiptOutcome, AegisTransactionObservation } from './swap/receiptWait.js';
 export { summarizeTransactionReceipt } from './swap/sendSwapTransaction.js';
 export { isDocumentVisible, pollUntil, retryOnError } from './polling.js';
 export { AEGIS_BACKEND_PROD_BASE_URL, AegisBackendApiError, AegisBackendContractError, createAegisBackendApiClient, isRetryableAegisBackendApiError, normalizeAegisBackendBaseUrl } from './contract/backendClient.js';
@@ -40,4 +43,6 @@ export { backendTokenToAegisSwapToken, backendTokensToAegisSwapTokens, createAeg
 export type { AegisBackendAdapterSkip, AegisBackendAdapterSkipHandler, AegisBackendChainOptions } from './backendAdapters.js';
 export { aegisBackendAddressAllowlistSchema, aegisBackendAddressSchema, aegisBackendAllowlistsByChainSchema, aegisBackendChainSchema, aegisBackendChainIdSchema, aegisBackendConfigSchema, aegisBackendContractsByChainSchema, aegisBackendContractRegistrySchema, aegisBackendDecimalStringSchema, aegisBackendFeeConfigSchema, aegisBackendHealthResponseSchema, aegisBackendHexSchema, aegisBackendIsoDateTimeSchema, aegisBackendMarketMetricsSchema, aegisBackendMarketSchema, aegisBackendMarketStatusSchema, aegisBackendMarketsResponseSchema, aegisBackendQuoteDefaultsSchema, aegisBackendQuoteModeSchema, aegisBackendSwapProviderSchema, aegisBackendSwapQuoteRequestSchema, aegisBackendSwapQuoteResponseSchema, aegisBackendTokenSchema, aegisBackendTokensResponseSchema, aegisPoolKeySchema, AegisContractGuardError, assertCalldataHash, assertChainMatches, assertQuoteFresh, assertRouterAllowlisted, assertSpenderAllowlisted } from './contract/index.js';
 export type { AegisContractGuardCode } from './contract/index.js';
+export { engineMarketsRestResponseSchema } from './engine/restSchemas.js';
 export * from './engine/index.js';
+export { PortfolioQuerySchema, PortfolioPageQuerySchema, PortfolioResponseSchema, PortfolioPageSchema } from './engine/account/portfolioSchemas.js';

package/dist/internal/guardedWalletTransaction.d.ts

@@ -0,0 +1,31 @@
+import type { Chain, Hex, PublicClient, TransactionReceipt } from 'viem';
+import { type Eip1193Provider } from '../wallet.js';
+import { type AegisTransactionObservation } from '../swap/receiptWait.js';
+/**
+ * Sends one already-prepared wallet transaction through the safety boundary
+ * shared by swaps and authorization writes.
+ *
+ * Preparation and simulation stay with the caller. This helper owns the
+ * invariants that begin immediately before the wallet prompt: verify the
+ * active chain, honor cancellation until a hash exists, publish submitted and
+ * replacement hashes without trusting host callbacks, and reconcile the
+ * receipt. Once submitted, caller cancellation cannot hide the mined result.
+ */
+export declare function runGuardedWalletTransaction(args: {
+    provider: Eip1193Provider;
+    publicClient: PublicClient;
+    chain: Chain;
+    signal?: AbortSignal;
+    timeoutMs: number;
+    submit: () => Promise<Hex>;
+    unreadableChainMessage: string;
+    cancelledMessage: string;
+    revertedMessage: string;
+    onWalletRequest?: () => void;
+    onHash?: (hash: Hex, replacement?: {
+        replacesHash: Hex;
+        executionChanged: boolean;
+    }) => void;
+    onTransactionObservation?: (event: AegisTransactionObservation) => void;
+    onSubmitted?: (hash: Hex) => void;
+}): Promise<TransactionReceipt>;

package/dist/permit.d.ts

@@ -1,8 +1,20 @@
 import { type Address, type Chain, type Hex, type PublicClient } from 'viem';
-import type { Eip1193Provider } from './wallet.js';
+import { type Eip1193Provider } from './wallet.js';
 import type { SignedPermitBatch } from './encoding.js';
 export declare const MAX_UINT160: bigint;
 export declare const MAX_UINT256: bigint;
+/** "No limit" only counts once the standing grant still reads as effectively
+ *  unlimited. Half the type maximum tolerates tokens and Permit2 flows that
+ *  decrement a max grant on spend — an equality test against the maximum would
+ *  re-approve before every swap — while an exact-sized allowance, however large
+ *  against today's amount, never qualifies. */
+export declare const UNLIMITED_ERC20_FLOOR: bigint;
+export declare const UNLIMITED_PERMIT2_FLOOR: bigint;
+/** Whether an ERC-20 grant reads as "no limit" rather than a number worth
+ *  showing — formatting the integer yields a quantity nobody can read. */
+export declare function isUnlimitedErc20Approval(amount: bigint): boolean;
+/** The Permit2 counterpart, against the uint160 wire type's own floor. */
+export declare function isUnlimitedPermit2Approval(amount: bigint): boolean;
 export declare const SWAP_TX_DEADLINE_SECONDS = 600;
 export declare const DEFAULT_PERMIT_EXPIRATION_SECONDS: number;
 export declare const PERMIT2_FAR_FUTURE_EXPIRATION: number;
@@ -14,8 +26,14 @@ export declare function approveErc20ToPermit2(args: {
     token: Address;
     permit2: Address;
     amount?: bigint;
+    /** Stops preparation before the approval is handed to the wallet. */
+    signal?: AbortSignal;
     onWalletRequest?: () => void;
-    onHash?: (hash: Hex) => void;
+    onHash?: (hash: Hex, replacement?: {
+        replacesHash: Hex;
+        executionChanged: boolean;
+    }) => void;
+    onSubmitted?: (hash: Hex) => void;
 }): Promise<Hex>;
 export declare function readErc20Allowance(args: {
     publicClient: PublicClient;
@@ -31,7 +49,24 @@ export declare function approveErc20Spender(args: {
     token: Address;
     spender: Address;
     amount?: bigint;
+    /** Stops preparation before the approval is handed to the wallet. */
+    signal?: AbortSignal;
+    onWalletRequest?: () => void;
+    onHash?: (hash: Hex, replacement?: {
+        replacesHash: Hex;
+        executionChanged: boolean;
+    }) => void;
+    onSubmitted?: (hash: Hex) => void;
 }): Promise<Hex>;
+/**
+ * Installs a Permit2 -> router spending cap on-chain: the fallback for wallets
+ * whose typed-data signature Permit2 will not accept.
+ *
+ * `amount` follows the same convention as the ERC-20 writers above — omitted
+ * means maximum authority (MAX_UINT160), and an explicit `0n` revokes. Anything
+ * wider than the uint160 wire type is clamped. `expiration` defaults to
+ * Permit2's far-future sentinel.
+ */
 export declare function approvePermit2ToRouter(args: {
     provider: Eip1193Provider;
     publicClient: PublicClient;
@@ -42,8 +77,14 @@ export declare function approvePermit2ToRouter(args: {
     router: Address;
     amount?: bigint;
     expiration?: number;
+    /** Stops preparation before the approval is handed to the wallet. */
+    signal?: AbortSignal;
     onWalletRequest?: () => void;
-    onHash?: (hash: Hex) => void;
+    onHash?: (hash: Hex, replacement?: {
+        replacesHash: Hex;
+        executionChanged: boolean;
+    }) => void;
+    onSubmitted?: (hash: Hex) => void;
 }): Promise<Hex>;
 export declare function readPermit2RouterAllowance(args: {
     publicClient: PublicClient;
@@ -52,7 +93,36 @@ export declare function readPermit2RouterAllowance(args: {
     token: Address;
     router: Address;
 }): Promise<readonly [amount: bigint, expiration: number, nonce: number]>;
-export declare function hasUsablePermit2Allowance(allowance: Awaited<ReturnType<typeof readPermit2RouterAllowance>>, amount: bigint): boolean;
+export declare function hasUsablePermit2Allowance(allowance: Awaited<ReturnType<typeof readPermit2RouterAllowance>>, amount: bigint, sizing?: 'exact' | 'max'): boolean;
+/**
+ * True only when Permit2's own `SignatureVerification` would accept this
+ * signature. It branches on the owner's code, not on the signature's shape: an
+ * address with code is checked through ERC-1271 alone, with no ecrecover
+ * fallback, so an EIP-7702-delegated EOA whose delegate does not implement
+ * `isValidSignature` rejects the ordinary 65-byte signature its own key just
+ * produced. A codeless owner takes the other branch and reverts on any length
+ * other than 64 or 65, which is where an ERC-6492 wrapper from an undeployed
+ * smart account dies.
+ *
+ * viem's `verifyTypedData` is used only for the codeless branch it models
+ * exactly, in `eoa` mode: its default `auto` mode opens with an `eth_call` that
+ * deploys viem's ERC-6492 validator, a blocking round trip sitting between the
+ * wallet signature and the submit on every ordinary swap.
+ *
+ * `false` means the owner refused, never "the check could not run": an RPC
+ * failure throws so the caller cannot mistake it for an unsignable wallet.
+ */
+export declare function isPermit2AcceptableSignature(args: {
+    publicClient: PublicClient;
+    chainId: number;
+    permit2: Address;
+    signed: SignedPermitBatch;
+    /**
+     * The owner's deployed code, read by the caller so a failed read propagates
+     * instead of arriving here as a `false`.
+     */
+    ownerCode: Hex | undefined;
+}): Promise<boolean>;
 export declare function buildSignedPermitBatch(args: {
     provider: Eip1193Provider;
     publicClient: PublicClient;
@@ -66,11 +136,15 @@ export declare function buildSignedPermitBatch(args: {
     /**
      * 'max' signs a MAX_UINT160 permit (still expiring in 30 minutes) so quick
      * follow-up swaps reuse it instead of prompting for a new signature each
-     * time — Permit2 decrements exact-sized permits to zero on transfer.
-     * Defaults to 'exact'.
+     * time — Permit2 decrements exact-sized permits to zero on transfer. It also
+     * re-signs over a merely amount-covering standing cap, because that cap is
+     * not the unlimited authority 'max' asked for. Defaults to 'exact'.
      */
     sizing?: 'exact' | 'max';
     /** Pre-started readPermit2RouterAllowance result to overlap with other RPC work. */
     allowanceRead?: ReturnType<typeof readPermit2RouterAllowance>;
+    /** Stops preparation before typed data is handed to the wallet. */
+    signal?: AbortSignal;
+    /** Fires only when a new typed-data signature is actually requested. */
     onWalletRequest?: () => void;
 }): Promise<SignedPermitBatch | null>;