@aegis-engine/core 0.4.0 → 0.6.0

package/README.md

@@ -31,8 +31,9 @@ the published Core package; consumers do not need GitHub Packages credentials.
   bounded session caches, and explicit indexed freshness.
 - Engine 12-hour market-metric history for optional rate, utilization, and
   liquidity charts.
-- Engine lend and borrow quotes, exact rounded LP-shaped debt/carry
-  projections, collateral sizing, Permit2 preparation, and guarded execution.
+- Engine lend, borrow, and directional Long/Short quotes; exact rounded
+  LP-shaped debt/carry projections; collateral sizing; Permit2 preparation;
+  and guarded execution.
 
 Direct pool swaps support `exactIn` and `exactOut`. KyberSwap routes currently
 support `exactIn` only because Kyber's route/build flow is exact-input.
@@ -46,8 +47,10 @@ Engine discovery and wallet positions default to partner-safe REST:
 
 ```ts
 import {
+  deriveEngineTradePositionStrategy,
   fetchEngineMarketHistory,
   fetchEngineMarkets,
+  fetchEnginePositionActivitySnapshot,
   fetchEnginePositionsSnapshot
 } from '@aegis-engine/core'
 
@@ -63,6 +66,16 @@ const positions = await fetchEnginePositionsSnapshot({
   chainId: 1,
   account
 })
+const activity = await fetchEnginePositionActivitySnapshot({
+  source,
+  chainId: 1,
+  account
+})
+const position = positions.positions[0]
+const vault = activity?.vaults.find((entry) => entry.vaultId === position?.vaultId)
+const strategy = position && vault
+  ? deriveEngineTradePositionStrategy(position, vault)
+  : null
 const marketHistory = await fetchEngineMarketHistory({
   source,
   marketId: markets[0].id,
@@ -71,7 +84,10 @@ const marketHistory = await fetchEngineMarketHistory({
 ```
 
 Hosts that already own deterministic market/position metadata can instead use
-the typed `static` source. Engine market history remains a REST capability.
+the typed `static` source. Supply `vaultActivity` when an offline fixture must
+reconstruct Long/Short identity; position rows alone are ordinary borrow-vault
+facts and are not enough to classify a trade. Engine market history remains a
+REST capability.
 
 The REST service supplies facts and provenance. Core owns live RPC reads,
 collateral/debt math, quote freshness, recipe construction, simulation,
@@ -106,6 +122,124 @@ 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
+block-pinned Engine and Uniswap v4 frame. It returns the selected average and
+live leverage, exact opening LTV after the swap minimum, interest carry, risk
+thresholds, gross return at the configured target, actionable solver limits,
+and atomic router calldata when all execution gates pass.
+
+Successful and leverage-bound quotes expose `limits.minLeverage` and
+`limits.maxLeverage`. Treat these as live, request-specific bounds rather than
+a protocol-wide constant.
+
+`deriveEngineTradePositionStrategy` recognizes the indexed Tap opening action
+shape and recovers its Long/Short direction and executed entry price after a
+reload. The selected target and average-to-target leverage are not transaction
+fields. A host can pass persisted intent records to augment those fields only
+when chain, account, market, pool, transaction, and direction all match.
+A no-swap opening has no indexed direction signal, so this helper deliberately
+leaves it unclassified instead of trusting off-chain intent alone.
+
+```ts
+import { quoteEngineTradeOpen } from '@aegis-engine/core'
+
+const quote = await quoteEngineTradeOpen({
+  publicClient,
+  market,
+  owner: account,
+  direction: 'long',
+  collateralIn: 1_000_000n,
+  inputIsToken0: false,
+  leverage: 1.5,
+  horizonSeconds: 30 * 24 * 60 * 60,
+  priceMove: 0.2,
+  slippageBps: 100
+})
+```
+
+Treat `feasible` and `executable` separately. A feasible quote can still need
+the trusted router's vault-operator grant or Permit2 authorization. After an
+authorization transaction, request the submit quote with
+`forceExecutionEvidenceRefresh: true`; then pass its fresh `tx` and `expiresAt`
+to `sendEngineTransaction`. The prebuilt `AegisLeverageWidget` performs this
+sequence for frontend integrations.
+
+Use `readEngineAuthorizationPlan` to present the connected account's current
+wallet sequence before submission:
+
+```ts
+import { readEngineAuthorizationPlan } from '@aegis-engine/core'
+
+const plan = await readEngineAuthorizationPlan({
+  publicClient,
+  market,
+  owner: account,
+  walletChainId,
+  token: market.token0,
+  amount: 1_000_000n,
+  approvalMode: 'exact'
+})
+```
+
+`missingPermissionCount` excludes the final open and any zero-first reset.
+`walletPromptCount` includes every required sequential transaction.
+`walletChainSwitchRequired` reports the network switch separately and is null
+until the wallet chain is known. The plan is a read-only presentation snapshot, not authorization
+evidence. Submission must still re-read permissions and obtain a fresh
+executable quote. Exact ERC-20 and Permit2 limits are consumed by the successful
+opening transfer; maximum limits and the VaultRegistry operator grant remain
+active until revoked.
+
 ## Historical token prices
 
 Historical prices are intentionally separate from Engine market and
@@ -113,10 +247,7 @@ transaction truth. A host reads one exact token through the public REST
 backend without placing private data-service credentials in the client:
 
 ```ts
-import {
-  AEGIS_BACKEND_PROD_BASE_URL,
-  fetchTokenPriceHistory
-} from '@aegis-engine/core'
+import { AEGIS_BACKEND_PROD_BASE_URL, fetchTokenPriceHistory } from '@aegis-engine/core'
 
 const history = await fetchTokenPriceHistory({
   baseUrl: AEGIS_BACKEND_PROD_BASE_URL,
@@ -189,10 +320,7 @@ const wallet = await resolveWalletSession({
 Create a read-side viem client from an Aegis chain config:
 
 ```ts
-import {
-  AEGIS_SWAP_MAINNET_CHAIN,
-  createSwapPublicClient
-} from '@aegis-engine/core'
+import { AEGIS_SWAP_MAINNET_CHAIN, createSwapPublicClient } from '@aegis-engine/core'
 
 const publicClient = createSwapPublicClient(
   AEGIS_SWAP_MAINNET_CHAIN.chain,
@@ -212,10 +340,7 @@ metadata, market discovery, allowlists, and fee policy come from REST. Swap
 execution remains client-side.
 
 ```ts
-import {
-  AEGIS_BACKEND_PROD_BASE_URL,
-  createAegisBackendApiClient
-} from '@aegis-engine/core'
+import { AEGIS_BACKEND_PROD_BASE_URL, createAegisBackendApiClient } from '@aegis-engine/core'
 
 const aegisApi = createAegisBackendApiClient({
   baseUrl: AEGIS_BACKEND_PROD_BASE_URL
@@ -281,10 +406,7 @@ provided, core verifies it matches the key.
 ## Direct Pool Quote
 
 ```ts
-import {
-  AEGIS_SWAP_MAINNET_CHAIN,
-  fetchDirectPoolSwapQuote
-} from '@aegis-engine/core'
+import { AEGIS_SWAP_MAINNET_CHAIN, fetchDirectPoolSwapQuote } from '@aegis-engine/core'
 
 const quote = await fetchDirectPoolSwapQuote({
   publicClient,
@@ -339,10 +461,7 @@ protection the user saw.
 ## KyberSwap Quote
 
 ```ts
-import {
-  AGGREGATED_SWAP_DEFAULT_TOKENS,
-  fetchAggregatedSwapQuote
-} from '@aegis-engine/core'
+import { AGGREGATED_SWAP_DEFAULT_TOKENS, fetchAggregatedSwapQuote } from '@aegis-engine/core'
 
 const quote = await fetchAggregatedSwapQuote(
   AGGREGATED_SWAP_DEFAULT_TOKENS.USDC,
@@ -454,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/THIRD_PARTY_NOTICES.md

@@ -2,7 +2,7 @@
 
 The lazy Engine implementation includes code from these MIT-licensed works:
 
-- `@labs-solo/aegis-engine-sdk` 0.30.0 — Copyright (c) 2026 Solo Labs
+- `@labs-solo/aegis-engine-sdk` 0.33.0 — Copyright (c) 2026 Solo Labs
 - `@uniswap/sdk-core` 6.1.1 and 7.18.0 — Copyright (c) 2021 Uniswap Labs
 - `@uniswap/v3-sdk` 3.27.0 — Copyright (c) 2021 Uniswap Labs
 - `tiny-invariant` 1.3.3 — Copyright (c) 2019 Alexander Reardon

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;