@aegis-engine/core 0.5.0 → 0.6.0

package/README.md

@@ -122,6 +122,54 @@ remaining collateral stays in the vault until a separate withdrawal. A
 one-token lend is a zap into a two-sided full-range LP, not single-token
 lending.
 
+### Simple-yield position summaries
+
+Use `summarizeEngineSimpleYieldPosition` when a custom UI needs one honest,
+React-free summary of an Engine lender-share position. The helper values live
+shares first, falls back to trusted indexed shares, projects an optional added
+USD amount, and converts realized share-price growth into a weekly estimate.
+
+```ts
+import {
+  readEnginePositionsHydration,
+  summarizeEngineSimpleYieldPosition
+} from '@aegis-engine/core'
+
+const market = markets[0]
+const positionsHydration = await readEnginePositionsHydration({
+  publicClient,
+  chainId: market.chainId,
+  expectedAccount: account,
+  positions: positions.positions,
+  lendPositions: positions.lendPositions
+})
+const position = positions.lendPositions.find(
+  (entry) =>
+    entry.chainId === market.chainId &&
+    entry.poolId.toLowerCase() === market.poolId.toLowerCase()
+) ?? null
+const live = position
+  ? positionsHydration.lendPositions.find(
+      (entry) => entry.positionId === position.id
+    )
+  : undefined
+
+const summary = summarizeEngineSimpleYieldPosition({
+  market,
+  position,
+  hydration: live,
+  history: marketHistory,
+  additionalValueUsd: 100
+})
+```
+
+`summary.valuation` identifies whether live or indexed shares produced the
+current USD value. `summary.projection` is null when an existing position cannot
+be valued, so an add-funds UI cannot mislabel it as a new deposit.
+`summary.growth.weeklyEarningsPer100Usd` is a historical share-growth estimate,
+not a promise. `market.metrics.lendApyPct` is the current modeled lender rate;
+it is a different metric and is never substituted for realized history.
+
 ### Directional Engine positions
 
 `quoteEngineTradeOpen` sizes a fresh-vault Long or Short against one
@@ -525,9 +573,12 @@ Execution returns:
 
 ## Publishing
 
-This package is configured with `prepack`, so `npm publish` builds `dist` before
-creating the tarball.
+Releases use Changesets and npm trusted publishing. The release workflow builds
+all publishable packages once, validates their tarballs, then publishes the
+prebuilt artifacts with package lifecycle scripts disabled. This prevents
+concurrent package publishes from rebuilding shared workspace artifacts.
 
 ```sh
-npm publish --access public
+pnpm build
+pnpm pack:check
 ```

package/dist/actions/directPoolSwap.d.ts

@@ -32,6 +32,7 @@ export declare function approveDirectPoolSwapInput(args: {
     amount: bigint;
     approvalMode?: AegisSwapApprovalMode;
     onStatus?: AegisSwapActionCallbacks['onStatus'];
+    onApprovalProgress?: AegisSwapActionCallbacks['onApprovalProgress'];
 }): Promise<DirectPoolSwapApprovalResult>;
 export declare function executeDirectPoolSwap(args: {
     wallet: WalletSession;

package/dist/actions/types.d.ts

@@ -3,10 +3,65 @@ import type { DirectSwapQuote } from '../quote.js';
 import type { AegisSwapReceiptSummary, SubmitStatus } from '../transactionProgress.js';
 import type { AggregatedSwapQuote } from '../types/aggregatedSwap.js';
 import type { AegisSwapSubmitDetails } from '../swap/types.js';
+/**
+ * The grant the approval prompt asks for, as the executor resolved it from the
+ * sizing rule. It travels with the progress report so a surface renders the
+ * number that will actually be signed instead of re-deriving one from form
+ * state — the input amount and the requested amount are the same only under
+ * 'exact' sizing. There is no `formatted` field: the unlimited case has no
+ * honest formatting and has to be rendered as a word.
+ */
+export type AegisSwapApprovalRequest = {
+    /** The exact value passed to `approve()`. */
+    value: bigint;
+    /** Decimals of the approved token, so `value` is renderable on its own. */
+    decimals: number;
+    /** True when `value` reads as no limit at all; render a word, not `value`. */
+    unlimited: boolean;
+};
+/**
+ * The approval step's wallet prompts: how many it will open, how many the
+ * wallet has already confirmed, and what they ask for. Only the executor can
+ * answer any of it — its allowance read decides whether a USDT-style zero-reset
+ * adds a second prompt, and only it sees that reset's receipt.
+ */
+export type AegisSwapApprovalProgress = {
+    /** Prompts the approval step opens: 0, 1, or 2 when a zero-reset precedes it. */
+    planned: number;
+    /** How many of `planned` have landed on-chain. */
+    completed: number;
+    /** Absent exactly when `planned` is 0 — nothing will be approved. */
+    request?: AegisSwapApprovalRequest;
+};
+/**
+ * Wallet prompts used to authorize Permit2 for the router. Usually this is one
+ * typed-data signature. A wallet that explicitly reports typed-data as
+ * unsupported uses one on-chain spending-cap prompt instead. Returned invalid
+ * signatures fail closed, so this is a count rather than a boolean.
+ */
+export type AegisSwapAuthorizationProgress = {
+    /** Prompts this authorization step will open from the executor's live state. */
+    planned: number;
+    /** Prompts already completed by the wallet/user. */
+    completed: number;
+};
 export type AegisSwapActionCallbacks<TSwapDetails = AegisSwapSubmitDetails> = {
     onStatus?: (status: SubmitStatus) => void;
     onTxHash?: (hash: Hex | null) => void;
     onSubmitted?: (hash: Hex, swap?: TSwapDetails) => void;
+    /**
+     * Fires with the plan before the first approval prompt opens, then again
+     * after each approval transaction mines. Once allowance resolution is
+     * reached, no required approval reports `{ planned: 0, completed: 0 }`.
+     * Earlier chain-validation or quote failures can stop before this callback.
+     */
+    onApprovalProgress?: (progress: AegisSwapApprovalProgress) => void;
+    /**
+     * Fires before the first Permit2 authorization prompt, whenever the plan
+     * changes, and after each completed prompt. A reusable standing cap reports
+     * `{ planned: 0, completed: 0 }`.
+     */
+    onAuthorizationProgress?: (progress: AegisSwapAuthorizationProgress) => void;
 };
 export type AegisSwapActionResult<TQuote = DirectSwapQuote | AggregatedSwapQuote> = {
     hash: Hex;

package/dist/aegis-core.js

@@ -1,30 +1,30 @@
-import { A as s, b as i, c as r, d as n, e as t, f as o, g as c, h as E, i as A, j as S, k as g, l as d, m as _, n as l, o as P, p as b, q as p, r as T, t as u, u as h, v as k, w as I, x as C, y as R, z as m, B as w, C as G, D as B, E as D, F as N, G as M, H as y, K as v, I as W, J as U, M as O, L as F, N as L, O as f, P as K, S as H, T as V, U as x, Q, R as q, V as z, W as X, X as Y, Y as j, Z, _ as J, $, a0 as aa, a1 as ea, a2 as sa, a3 as ia, a4 as ra, a5 as na, a6 as ta, a7 as oa, a8 as ca, a9 as Ea, aa as Aa, ab as Sa, ac as ga, ad as da, ae as _a, af as la, ag as Pa, ah as ba, ai as pa, aj as Ta, ak as ua, al as ha, am as ka, an as Ia, ao as Ca, ap as Ra, aq as ma, ar as wa, as as Ga, at as Ba, au as Da, av as Na, aw as Ma, ax as ya, ay as va, az as Wa, aA as Ua, aB as Oa, aC as Fa, aD as La, aE as fa, aF as Ka, aG as Ha, aH as Va, aI as xa, aJ as Qa, aK as qa, aL as za, aM as Xa, aN as Ya, aO as ja, aP as Za, aQ as Ja, aR as $a, aS as ae, aT as ee, aU as se, aV as ie, aW as re, aX as ne, aY as te, aZ as oe, a_ as ce, a$ as Ee, b0 as Ae, b1 as Se, b2 as ge, b3 as de, b4 as _e, b5 as le, b6 as Pe, b7 as be, b8 as pe, b9 as Te, ba as ue, bb as he, bc as ke, bd as Ie, be as Ce, bf as Re, bg as me, bh as we, bi as Ge, bj as Be, bk as De, bl as Ne, bm as Me, bn as ye, bo as ve, bp as We, bq as Ue, br as Oe, bs as Fe, bt as Le, bu as fe, bv as Ke, bw as He, bx as Ve, by as xe, bz as Qe, bA as qe, bB as ze, bC as Xe, bD as Ye, bE as je, bF as Ze, bG as Je, bH as $e, bI as as, bJ as es, bK as ss, bL as is, bM as rs, bN as ns, bO as ts, bP as os, bQ as cs, bR as Es, bS as As, bT as Ss, bU as gs, bV as ds, bW as _s, bX as ls, bY as Ps, bZ as bs, b_ as ps, b$ as Ts, c0 as us, c1 as hs, c2 as ks, c3 as Is, c4 as Cs, c5 as Rs, c6 as ms, c7 as ws, c8 as Gs, c9 as Bs, ca as Ds, cb as Ns, cc as Ms, cd as ys } from "./index-DuoaODpB.js";
+import { A as s, b as i, c as r, d as t, e as n, f as o, g as c, h as E, i as S, j as A, k as g, l as d, m as _, n as l, o as p, p as b, q as P, r as T, t as u, u as h, v as m, w as k, x as I, y as R, z as C, B as w, C as G, D as B, E as D, F as N, G as M, H as y, K as v, I as W, J as U, M as O, L as F, N as L, O as f, P as K, S as H, Q as V, T as x, U as Q, R as q, V as z, W as X, X as Y, Y as j, Z, _ as J, $, a0 as aa, a1 as ea, a2 as sa, a3 as ia, a4 as ra, a5 as ta, a6 as na, a7 as oa, a8 as ca, a9 as Ea, aa as Sa, ab as Aa, ac as ga, ad as da, ae as _a, af as la, ag as pa, ah as ba, ai as Pa, aj as Ta, ak as ua, al as ha, am as ma, an as ka, ao as Ia, ap as Ra, aq as Ca, ar as wa, as as Ga, at as Ba, au as Da, av as Na, aw as Ma, ax as ya, ay as va, az as Wa, aA as Ua, aB as Oa, aC as Fa, aD as La, aE as fa, aF as Ka, aG as Ha, aH as Va, aI as xa, aJ as Qa, aK as qa, aL as za, aM as Xa, aN as Ya, aO as ja, aP as Za, aQ as Ja, aR as $a, aS as ae, aT as ee, aU as se, aV as ie, aW as re, aX as te, aY as ne, aZ as oe, a_ as ce, a$ as Ee, b0 as Se, b1 as Ae, b2 as ge, b3 as de, b4 as _e, b5 as le, b6 as pe, b7 as be, b8 as Pe, b9 as Te, ba as ue, bb as he, bc as me, bd as ke, be as Ie, bf as Re, bg as Ce, bh as we, bi as Ge, bj as Be, bk as De, bl as Ne, bm as Me, bn as ye, bo as ve, bp as We, bq as Ue, br as Oe, bs as Fe, bt as Le, bu as fe, bv as Ke, bw as He, bx as Ve, by as xe, bz as Qe, bA as qe, bB as ze, bC as Xe, bD as Ye, bE as je, bF as Ze, bG as Je, bH as $e, bI as as, bJ as es, bK as ss, bL as is, bM as rs, bN as ts, bO as ns, bP as os, bQ as cs, bR as Es, bS as Ss, bT as As, bU as gs, bV as ds, bW as _s, bX as ls, bY as ps, bZ as bs, b_ as Ps, b$ as Ts, c0 as us, c1 as hs, c2 as ms, c3 as ks, c4 as Is, c5 as Rs, c6 as Cs, c7 as ws, c8 as Gs, c9 as Bs, ca as Ds, cb as Ns, cc as Ms, cd as ys, ce as vs, cf as Ws, cg as Us, ch as Os, ci as Fs, cj as Ls } from "./index-D9EfUokZ.js";
 export {
   s as AEGIS_BACKEND_PROD_BASE_URL,
   i as AEGIS_DYNAMIC_FEE_FLAG,
   r as AEGIS_SWAP_CHAINS,
-  n as AEGIS_SWAP_CHAIN_ID,
-  t as AEGIS_SWAP_DEFAULT_FEE_BPS,
+  t as AEGIS_SWAP_CHAIN_ID,
+  n as AEGIS_SWAP_DEFAULT_FEE_BPS,
   o as AEGIS_SWAP_DEFAULT_FEE_RECIPIENT,
   c as AEGIS_SWAP_DEFAULT_METADATA_ENDPOINT,
   E as AEGIS_SWAP_DEFAULT_RPC_URLS,
-  A as AEGIS_SWAP_HOOK,
-  S as AEGIS_SWAP_MAINNET_CHAIN,
+  S as AEGIS_SWAP_HOOK,
+  A as AEGIS_SWAP_MAINNET_CHAIN,
   g as AEGIS_SWAP_MAINNET_UNISWAP_V4_CONTRACTS,
   d as AEGIS_SWAP_PERMIT2,
   _ as AEGIS_SWAP_ROUTER,
   l as AEGIS_SWAP_TOKENS,
-  P as AEGIS_SWAP_TRUSTED_ROUTERS_BY_CHAIN,
+  p as AEGIS_SWAP_TRUSTED_ROUTERS_BY_CHAIN,
   b as AEGIS_SWAP_V4_QUOTER,
-  p as AGGREGATED_SWAP_CURATED_TOKENS,
+  P as AGGREGATED_SWAP_CURATED_TOKENS,
   T as AGGREGATED_SWAP_DEFAULT_TOKENS,
   u as AGGREGATED_SWAP_DEFAULT_TOKEN_LIST,
   h as AGGREGATED_SWAP_SUPPORTED_CHAIN_IDS,
-  k as AGGREGATED_SWAP_TOKEN_PRESETS,
-  I as AGGREGATED_SWAP_WOLFGAME_TOKENS,
-  C as AGGREGATED_SWAP_WOLFGAME_TOKEN_LIST,
+  m as AGGREGATED_SWAP_TOKEN_PRESETS,
+  k as AGGREGATED_SWAP_WOLFGAME_TOKENS,
+  I as AGGREGATED_SWAP_WOLFGAME_TOKEN_LIST,
   R as AegisBackendApiError,
-  m as AegisBackendContractError,
+  C as AegisBackendContractError,
   w as AegisContractGuardError,
   G as AegisEngineMarketNotReadyError,
   B as AggregatedSwapBuildMismatchError,
@@ -41,157 +41,163 @@ export {
   f as NATIVE_TOKEN_ADDRESS,
   K as PERMIT2_FAR_FUTURE_EXPIRATION,
   H as SWAP_TX_DEADLINE_SECONDS,
-  V as TransactionReceiptTimeoutError,
-  x as UNISWAP_V4_CONTRACTS_BY_CHAIN,
-  Q as USER_REJECTED_MESSAGE,
-  q as UserFacingError,
-  z as aegisBackendAddressAllowlistSchema,
-  X as aegisBackendAddressSchema,
-  Y as aegisBackendAllowlistsByChainSchema,
-  j as aegisBackendChainIdSchema,
-  Z as aegisBackendChainSchema,
-  J as aegisBackendConfigSchema,
-  $ as aegisBackendContractRegistrySchema,
-  aa as aegisBackendContractsByChainSchema,
-  ea as aegisBackendDecimalStringSchema,
-  sa as aegisBackendFeeConfigSchema,
-  ia as aegisBackendHealthResponseSchema,
-  ra as aegisBackendHexSchema,
+  V as SubmittedTransactionReceiptError,
+  x as TransactionReceiptTimeoutError,
+  Q as UNISWAP_V4_CONTRACTS_BY_CHAIN,
+  q as USER_REJECTED_MESSAGE,
+  z as UserFacingError,
+  X as aegisBackendAddressAllowlistSchema,
+  Y as aegisBackendAddressSchema,
+  j as aegisBackendAllowlistsByChainSchema,
+  Z as aegisBackendChainIdSchema,
+  J as aegisBackendChainSchema,
+  $ as aegisBackendConfigSchema,
+  aa as aegisBackendContractRegistrySchema,
+  ea as aegisBackendContractsByChainSchema,
+  sa as aegisBackendDecimalStringSchema,
+  ia as aegisBackendFeeConfigSchema,
+  ra as aegisBackendHealthResponseSchema,
+  ta as aegisBackendHexSchema,
   na as aegisBackendIsoDateTimeSchema,
-  ta as aegisBackendMarketMetricsSchema,
-  oa as aegisBackendMarketSchema,
-  ca as aegisBackendMarketStatusSchema,
-  Ea as aegisBackendMarketsResponseSchema,
+  oa as aegisBackendMarketMetricsSchema,
+  ca as aegisBackendMarketSchema,
+  Ea as aegisBackendMarketStatusSchema,
+  Sa as aegisBackendMarketsResponseSchema,
   Aa as aegisBackendQuoteDefaultsSchema,
-  Sa as aegisBackendQuoteModeSchema,
-  ga as aegisBackendSwapProviderSchema,
-  da as aegisBackendSwapQuoteRequestSchema,
-  _a as aegisBackendSwapQuoteResponseSchema,
-  la as aegisBackendTokenSchema,
-  Pa as aegisBackendTokensResponseSchema,
-  ba as aegisPoolKeySchema,
-  pa as aggregatedSwapErrorMessage,
-  Ta as approveDirectPoolSwapInput,
-  ua as approveEnginePermit2ToRouter,
-  ha as approveEngineTokenToPermit2,
+  ga as aegisBackendQuoteModeSchema,
+  da as aegisBackendSwapProviderSchema,
+  _a as aegisBackendSwapQuoteRequestSchema,
+  la as aegisBackendSwapQuoteResponseSchema,
+  pa as aegisBackendTokenSchema,
+  ba as aegisBackendTokensResponseSchema,
+  Pa as aegisPoolKeySchema,
+  Ta as aggregatedSwapErrorMessage,
+  ua as approveDirectPoolSwapInput,
+  ha as approveEnginePermit2ToRouter,
+  ma as approveEngineTokenToPermit2,
   ka as approveErc20Spender,
   Ia as approveErc20ToPermit2,
-  Ca as approveKyberSwapInput,
-  Ra as approvePermit2ToRouter,
-  ma as assertCalldataHash,
-  wa as assertChainMatches,
-  Ga as assertQuoteFresh,
-  Ba as assertRouterAllowlisted,
-  Da as assertSpenderAllowlisted,
-  Na as assertUint128,
-  Ma as attachEngineActivityLotDisplays,
-  ya as authorizeEnginePositionRouter,
-  va as authorizeEngineVaultOperator,
-  Wa as backendTokenToAegisSwapToken,
-  Ua as backendTokensToAegisSwapTokens,
-  Oa as buildExactInSwapTransaction,
-  Fa as buildExactOutSwapTransaction,
-  La as buildKyberSwapRoute,
-  fa as buildSignedPermitBatch,
-  Ka as classifyEngineVaultActivity,
-  Ha as classifyError,
-  Va as clearEngineMarketHistoryCache,
-  xa as clearEngineMarketsCache,
-  Qa as clearEnginePositionActivityCache,
-  qa as clearEnginePositionsCache,
-  za as clearEnginePositionsV2ProbeCache,
-  Xa as clearEngineReadCaches,
-  Ya as clearTokenPriceHistoryCache,
-  ja as computeEngineIdleWithdrawPostLtvPips,
-  Za as computeEngineMaxIdleWithdraw,
-  Ja as computePoolId,
-  $a as createAegisBackendApiClient,
-  ae as createAegisSwapChainConfig,
-  ee as createAegisSwapChains,
-  se as createAegisSwapChainsFromBackendConfig,
-  ie as createAegisSwapMarketsFromPools,
-  re as createAegisSwapPoolMarket,
+  Ra as approveKyberSwapInput,
+  Ca as approvePermit2ToRouter,
+  wa as assertCalldataHash,
+  Ga as assertChainMatches,
+  Ba as assertQuoteFresh,
+  Da as assertRouterAllowlisted,
+  Na as assertSpenderAllowlisted,
+  Ma as assertUint128,
+  ya as attachEngineActivityLotDisplays,
+  va as authorizeEnginePositionRouter,
+  Wa as authorizeEngineVaultOperator,
+  Ua as backendTokenToAegisSwapToken,
+  Oa as backendTokensToAegisSwapTokens,
+  Fa as buildExactInSwapTransaction,
+  La as buildExactOutSwapTransaction,
+  fa as buildKyberSwapRoute,
+  Ka as buildSignedPermitBatch,
+  Ha as classifyEngineVaultActivity,
+  Va as classifyError,
+  xa as clearEngineMarketHistoryCache,
+  Qa as clearEngineMarketsCache,
+  qa as clearEnginePositionActivityCache,
+  za as clearEnginePositionsCache,
+  Xa as clearEnginePositionsV2ProbeCache,
+  Ya as clearEngineReadCaches,
+  ja as clearTokenPriceHistoryCache,
+  Za as computeEngineIdleWithdrawPostLtvPips,
+  Ja as computeEngineMaxIdleWithdraw,
+  $a as computePoolId,
+  ae as createAegisBackendApiClient,
+  ee as createAegisSwapChainConfig,
+  se as createAegisSwapChains,
+  ie as createAegisSwapChainsFromBackendConfig,
+  re as createAegisSwapMarketsFromPools,
+  te as createAegisSwapPoolMarket,
   ne as createAegisSwapPoolsFromBackendMarkets,
-  te as createAegisSwapUniswapV4Contracts,
-  oe as createSwapPublicClient,
-  ce as deriveEngineActivityLotDisplay,
-  Ee as deriveEngineTradePositionStrategy,
+  oe as createAegisSwapUniswapV4Contracts,
+  ce as createSwapPublicClient,
+  Ee as deriveEngineActivityLotDisplay,
+  Se as deriveEngineTradePositionStrategy,
   Ae as engineIdleWithdrawPassesResidualLtv,
-  Se as enginePermit2GrantSatisfies,
-  ge as enginePreviewMaxLtvPips,
-  de as engineRouterForChain,
-  _e as engineTokenGrantSatisfies,
-  le as ensureWalletChain,
-  Pe as errorMessage,
-  be as estimateSwapGasWithBuffer,
-  pe as executeDirectPoolSwap,
-  Te as executeKyberSwap,
-  ue as executionLtvGuardPips,
-  he as fetchAggregatedSwapQuote,
+  ge as enginePermit2GrantSatisfies,
+  de as enginePreviewMaxLtvPips,
+  _e as engineRouterForChain,
+  le as engineTokenGrantSatisfies,
+  pe as ensureWalletChain,
+  be as errorMessage,
+  Pe as estimateSwapGasWithBuffer,
+  Te as executeDirectPoolSwap,
+  ue as executeKyberSwap,
+  he as executionLtvGuardPips,
+  me as fetchAggregatedSwapQuote,
   ke as fetchDirectPoolSwapQuote,
   Ie as fetchEngineLendActivity,
-  Ce as fetchEngineMarketHistory,
-  Re as fetchEngineMarkets,
-  me as fetchEnginePositionActivitySnapshot,
-  we as fetchEnginePositionsSnapshot,
-  Ge as fetchEngineVaultActivity,
-  Be as fetchGlobalTokenMetadata,
-  De as fetchKyberSwapRoute,
-  Ne as fetchTokenPriceHistory,
-  Me as getExplorerUrl,
-  ye as getInjectedProvider,
-  ve as getProviderAccount,
-  We as getProviderChainId,
-  Ue as getZeroForOne,
-  Oe as isAegisEngineTradePositionIntent,
-  Fe as isBusy,
-  Le as isDocumentVisible,
-  fe as isEip1193Provider,
-  Ke as isNativeAssetAddress,
-  He as isNativeToken,
-  Ve as isRetryableAegisBackendApiError,
-  xe as isRetryableKyberSwapError,
-  Qe as isUserRejectedError,
-  qe as missingEngineExecutionReason,
-  ze as normalizeAccount,
-  Xe as normalizeAegisBackendBaseUrl,
-  Ye as normalizeEngineMarkets,
-  je as normalizeWalletConnection,
-  Ze as outputFeeForQuote,
-  Je as peekTokenPriceHistory,
-  $e as pollUntil,
-  as as prepareEnginePermit,
-  es as quoteEngineAddCollateral,
-  ss as quoteEngineBorrow,
-  is as quoteEngineBorrowCapacity,
-  rs as quoteEngineCloseVault,
-  ns as quoteEngineDeposit,
-  ts as quoteEngineIdleWithdraw,
-  os as quoteEngineRedeem,
-  cs as quoteEngineRepay,
-  Es as quoteEngineTradeOpen,
-  As as quoteSpendAmount,
-  Ss as readEngineAuthorizationPlan,
-  gs as readEngineBorrowQuoteContext,
-  ds as readEngineLendQuoteContext,
-  _s as readEngineMarketMark,
-  ls as readEngineMarketSnapshot,
+  Re as fetchEngineMarketHistory,
+  Ce as fetchEngineMarkets,
+  we as fetchEnginePositionActivitySnapshot,
+  Ge as fetchEnginePositionsSnapshot,
+  Be as fetchEngineVaultActivity,
+  De as fetchGlobalTokenMetadata,
+  Ne as fetchKyberSwapRoute,
+  Me as fetchTokenPriceHistory,
+  ye as getExplorerUrl,
+  ve as getInjectedProvider,
+  We as getProviderAccount,
+  Ue as getProviderChainId,
+  Oe as getZeroForOne,
+  Fe as isAegisEngineTradePositionIntent,
+  Le as isBusy,
+  fe as isDocumentVisible,
+  Ke as isEip1193Provider,
+  He as isNativeAssetAddress,
+  Ve as isNativeToken,
+  xe as isRetryableAegisBackendApiError,
+  Qe as isRetryableKyberSwapError,
+  qe as isSubmittedTransactionReceiptError,
+  ze as isUserRejectedError,
+  Xe as missingEngineExecutionReason,
+  Ye as normalizeAccount,
+  je as normalizeAegisBackendBaseUrl,
+  Ze as normalizeEngineMarkets,
+  Je as normalizeWalletConnection,
+  $e as outputFeeForQuote,
+  as as peekTokenPriceHistory,
+  es as pollUntil,
+  ss as prepareEnginePermit,
+  is as quoteEngineAddCollateral,
+  rs as quoteEngineBorrow,
+  ts as quoteEngineBorrowCapacity,
+  ns as quoteEngineCloseVault,
+  os as quoteEngineDeposit,
+  cs as quoteEngineIdleWithdraw,
+  Es as quoteEngineRedeem,
+  Ss as quoteEngineRepay,
+  As as quoteEngineTradeOpen,
+  gs as quoteSpendAmount,
+  ds as readEngineAuthorizationPlan,
+  _s as readEngineBorrowQuoteContext,
+  ls as readEngineLendQuoteContext,
+  ps as readEngineMarketMark,
+  bs as readEngineMarketSnapshot,
   Ps as readEnginePositionsHydration,
-  bs as readEngineVaultActivity,
-  ps as readEngineVaultRouterApproved,
-  Ts as readErc20Allowance,
-  us as readPermit2RouterAllowance,
-  hs as reconcileSubmitQuote,
-  ks as requestProviderAccount,
-  Is as resolveTokenIconUrl,
-  Cs as resolveWalletSession,
-  Rs as retryOnError,
-  ms as sameQuote,
-  ws as sendEngineTransaction,
-  Gs as subscribeProvider,
-  Bs as switchProviderChain,
-  Ds as transactionProgressView,
-  Ns as trustedEngineRegistryForChain,
-  Ms as trustedEngineVersionForChain,
-  ys as waitForProviderChain
+  Ts as readEngineVaultActivity,
+  us as readEngineVaultRouterApproved,
+  hs as readErc20Allowance,
+  ms as readPermit2RouterAllowance,
+  ks as reconcileSubmitQuote,
+  Is as reconcileSubmittedReceipt,
+  Rs as requestProviderAccount,
+  Cs as resolveTokenIconUrl,
+  ws as resolveWalletSession,
+  Gs as retryOnError,
+  Bs as sameQuote,
+  Ds as sendEngineTransaction,
+  Ns as subscribeProvider,
+  Ms as summarizeEngineLendShareGrowth,
+  ys as summarizeEngineSimpleYieldPosition,
+  vs as summarizeTransactionReceipt,
+  Ws as switchProviderChain,
+  Us as transactionProgressView,
+  Os as trustedEngineRegistryForChain,
+  Fs as trustedEngineVersionForChain,
+  Ls as waitForProviderChain
 };

package/dist/engine/index.d.ts

@@ -1,6 +1,8 @@
 export * from './types.js';
 export * from './activityLotDisplay.js';
 export * from './dataSource.js';
+export * from './lendHistory.js';
+export * from './simpleYield.js';
 export * from './marketAdapter.js';
 export * from './registry.js';
 export * from './reads.js';

package/dist/engine/lendHistory.d.ts

@@ -0,0 +1,21 @@
+import type { AegisEngineMetricHistory } from './types.js';
+export type AegisEngineLendShareGrowthSummary = Readonly<{
+    startTimestamp: number;
+    endTimestamp: number;
+    coverageSeconds: number;
+    apyPct: number;
+    weeklyEarningsPer100Usd: number;
+    /** Historical average weekly dollars per $100, recalculated from the first
+     * usable share-price observation through each later observation. */
+    points: ReadonlyArray<Readonly<{
+        t: number;
+        v: number;
+    }>>;
+}>;
+/**
+ * Converts the Engine history plane's realized share-price growth into a
+ * player-readable historical earnings rate. This deliberately does not use
+ * `lendApyPct`: that field is the current borrower-interest model, while share
+ * growth records what actually accrued to one pool share during the window.
+ */
+export declare function summarizeEngineLendShareGrowth(history: AegisEngineMetricHistory): AegisEngineLendShareGrowthSummary | null;

package/dist/engine/simpleYield.d.ts

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

package/dist/engine/types.d.ts

@@ -1,6 +1,7 @@
 import type { Address, Hex, PublicClient, TransactionReceipt } from 'viem';
 import type { AegisSwapChainConfig, AegisSwapToken } from '../config/index.js';
 import type { SignedPermitBatch } from '../encoding.js';
+import type { ClassifiedError } from '../errors.js';
 import type { WalletSession } from '../swap/types.js';
 import type { AegisEngineTapInfeasibleReason, AegisEngineTapRootPolicy } from './trade/sizing.js';
 export type AegisEngineMode = 'lend' | 'borrow' | 'positions';
@@ -1256,6 +1257,25 @@ export type AegisEngineAuthorizationProgress = {
     kind: AegisEngineAuthorizationStepKind;
     status: 'requesting' | 'confirmed';
 };
+/** Lifecycle evidence for one Engine permission request. */
+export type AegisEngineAuthorizationExecutionEvent = Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'wallet-requested';
+    hash: null;
+}> | Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'submitted';
+    hash: Hex;
+}> | Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'confirmed';
+    hash: Hex | null;
+}> | Readonly<{
+    kind: AegisEngineAuthorizationStepKind;
+    status: 'cancelled' | 'failed';
+    hash: Hex | null;
+    error: ClassifiedError;
+}>;
 export type AegisEngineApprovalInput = {
     wallet: AegisEngineWalletSession;
     publicClient: PublicClient;
@@ -1271,6 +1291,8 @@ export type AegisEngineApprovalInput = {
     onStatus?: AegisEngineActionCallbacks['onStatus'];
     /** Fine-grained prerequisite progress for truthful wallet onboarding. */
     onAuthorizationProgress?: (progress: AegisEngineAuthorizationProgress) => void;
+    /** Full prerequisite lifecycle at the wallet and receipt boundaries. */
+    onAuthorizationExecution?: (event: AegisEngineAuthorizationExecutionEvent) => void;
     /** Awaited after each prerequisite receipt and before another wallet request. */
     onAuthorizationCheckpoint?: () => Promise<void>;
 };

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
 import type { Hex } from 'viem';
 /** Failure families the widget surfaces reason about (retry affordances,
     toast dwell, explorer-link degradation) without string comparison. */
-export type UserFacingErrorKind = 'rpc' | 'quote' | 'backend' | 'wallet-rejected' | 'wrong-chain' | 'tx-reverted' | 'tx-timeout' | 'market-not-ready' | 'validation' | 'unknown';
+export type UserFacingErrorKind = 'rpc' | 'quote' | 'backend' | 'wallet-rejected' | 'tx-cancelled' | 'wrong-chain' | 'tx-reverted' | 'tx-timeout' | 'market-not-ready' | 'validation' | 'unknown';
 export type ClassifiedError = {
     message: string;
     kind: UserFacingErrorKind;
@@ -15,8 +15,19 @@ export declare class UserFacingError extends Error {
         retryable?: boolean;
     });
 }
-export declare class TransactionReceiptTimeoutError extends UserFacingError {
+export declare class SubmittedTransactionReceiptError extends UserFacingError {
     readonly hash: Hex;
+    readonly cause: unknown;
+    constructor({ hash, cause, message, kind }: {
+        hash: Hex;
+        cause?: unknown;
+        message?: string;
+        kind?: UserFacingErrorKind;
+    });
+}
+/** True only for Core receipt failures that happened after a known broadcast. */
+export declare function isSubmittedTransactionReceiptError(error: unknown): error is SubmittedTransactionReceiptError;
+export declare class TransactionReceiptTimeoutError extends SubmittedTransactionReceiptError {
     constructor({ hash }: {
         hash: Hex;
     });