@aegis-engine/core 0.1.0 → 0.1.2

package/README.md

@@ -2,41 +2,370 @@
 
 React-free swap operations for Aegis integrations.
 
-This package exposes the operational pieces that the widget uses internally:
-direct pool quotes and execution, KyberSwap quotes and execution, Permit2
-authorization helpers, chain/wallet helpers, token and market config, and
-transaction progress types.
+`@aegis-engine/core` is the operations layer behind the Aegis swap experience.
+Use it when you want Aegis direct-pool swaps or KyberSwap aggregated routes
+inside your own UI instead of using a prebuilt widget.
+
+## Install
+
+```sh
+npm install @aegis-engine/core viem
+```
+
+`viem` is a peer dependency because hosts usually already own their wallet and
+RPC setup.
+
+## What It Supports
+
+- Direct Aegis pool quotes and execution against host-supplied Uniswap v4 pool
+  configs.
+- KyberSwap aggregated quotes and execution through the Kyber aggregator API.
+- ERC-20 approvals, Permit2 signing, Permit2 on-chain fallback, wallet chain
+  switching, transaction submission, replacement tracking, and receipt summaries.
+- Token, market, chain, metadata, polling, and progress helpers for custom UIs.
+
+Direct pool swaps support `exactIn` and `exactOut`. KyberSwap routes currently
+support `exactIn` only because Kyber's route/build flow is exact-input.
+
+Core does not ship a hardcoded pool list. The widget or host app should own pool
+selection and pass the selected market into the operation functions.
+
+## Wallet Sessions
+
+Execution functions take a `WalletSession`:
+
+```ts
+type WalletSession = {
+  provider: Eip1193Provider
+  account: Address
+}
+```
+
+If your app already uses wagmi, RainbowKit, Privy, Dynamic, or another wallet
+manager, you can build this object yourself and skip `resolveWalletSession`.
+
+`resolveWalletSession` is a convenience for simple browser integrations. It:
+
+- uses a supplied `provider` and `account` when provided,
+- otherwise calls `getProvider`,
+- otherwise falls back to `window.ethereum`,
+- optionally calls your `connectWallet` callback,
+- requests an account by default when one is missing.
+
+Call it from a user action, not during render, because it may open the wallet
+connection prompt.
+
+```ts
+import { resolveWalletSession } from '@aegis-engine/core'
+
+const wallet = await resolveWalletSession()
+```
+
+With a host wallet manager:
+
+```ts
+const wallet = await resolveWalletSession({
+  account: address,
+  getProvider: () => connector.getProvider()
+})
+```
+
+To only read an already connected account without prompting:
+
+```ts
+const wallet = await resolveWalletSession({
+  provider,
+  requestAccount: false
+})
+```
+
+## Public Client
+
+Create a read-side viem client from an Aegis chain config:
 
 ```ts
 import {
   AEGIS_SWAP_MAINNET_CHAIN,
-  AEGIS_SWAP_MARKETS,
-  AEGIS_SWAP_TOKENS,
-  createSwapPublicClient,
-  executeDirectPoolSwap,
-  resolveWalletSession
+  createSwapPublicClient
 } from '@aegis-engine/core'
 
 const publicClient = createSwapPublicClient(
   AEGIS_SWAP_MAINNET_CHAIN.chain,
   AEGIS_SWAP_MAINNET_CHAIN.rpcUrls
 )
+```
+
+For production integrations, prefer passing your own viem `PublicClient` backed
+by your RPC provider. `createSwapPublicClient` is a convenience fallback for
+simple integrations and demos.
+
+## Backend V1 API
+
+The V1 backend/indexer contract is exposed as typed REST helpers. This is the
+public boundary for widget/core integrations once the backend service is live:
+AppSync, DynamoDB, indexer reads, provider adapters, quote storage, route hashes,
+allowlists, and final simulation stay behind the backend.
+
+```ts
+import { createAegisBackendApiClient } from '@aegis-engine/core'
+
+const aegisApi = createAegisBackendApiClient({
+  baseUrl: 'https://api.aegis.markets'
+})
+
+const config = await aegisApi.config()
+const tokens = await aegisApi.tokens({ chainId: 1 })
+const markets = await aegisApi.markets({ chainId: 1 })
+
+const quote = await aegisApi.quote({
+  chainId: 1,
+  provider: 'aegis-direct-v4',
+  marketId: 'WATER_USDC',
+  mode: 'exactIn',
+  tokenIn: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+  tokenOut: '0x828B22c9ea1c20B551EeFC6198174C4bb7a8CBF6',
+  amountIn: '1000000',
+  slippageBps: config.quote.defaultSlippageBps,
+  account
+})
+
+const build = await aegisApi.build({
+  quoteId: quote.quoteId,
+  account,
+  recipient: account
+})
+```
+
+The backend endpoints are:
+
+- `GET /v1/health`
+- `GET /v1/config`
+- `GET /v1/tokens?chainId=1`
+- `GET /v1/tokens/by-address?chainId=1&addresses=0x...,0x...`
+- `GET /v1/markets?chainId=1`
+- `POST /v1/swap/quote`
+- `POST /v1/swap/build`
+- `GET /v1/status/tx/:chainId/:txHash`
+
+`quote` returns a short-lived `quoteId`, `quoteHash`, `routeHash`, expiry, gas,
+approval, and normalized fee data. `build` accepts only `quoteId`, `account`,
+`recipient`, and an optional Permit2 signature; token amounts, slippage, provider
+route data, router addresses, and spender addresses are not accepted in the
+build request. The backend must reject expired or tampered quotes, validate the
+chain/router/spender/pool allowlists, and simulate the unsigned transaction
+before returning wallet-ready `tx` data.
+
+Core still includes direct-pool and Kyber client-side helpers for the current
+widget flow. Those helpers are transitional for swap execution: once the backend
+service is available, production widget paths should fetch config, tokens,
+markets, quotes, builds, and transaction status through this REST client while
+wallet signing and transaction sending remain client-side.
+
+## Direct Pool Market Config
+
+The direct pool operations take an `AegisSwapMarket`. Hosts can build one from
+their own pool config:
+
+```ts
+import { createAegisSwapPoolMarket } from '@aegis-engine/core'
+
+const market = createAegisSwapPoolMarket({
+  id: 'HOST_POOL_ID',
+  token: targetToken,
+  counterToken,
+  poolKey: {
+    currency0,
+    currency1,
+    fee,
+    tickSpacing,
+    hooks
+  },
+  poolId
+})
+```
+
+The pool key must use Uniswap v4 canonical currency ordering. If `poolId` is
+provided, core verifies it matches the key.
+
+## Direct Pool Quote
+
+```ts
+import {
+  AEGIS_SWAP_MAINNET_CHAIN,
+  fetchDirectPoolSwapQuote
+} from '@aegis-engine/core'
+
+const quote = await fetchDirectPoolSwapQuote({
+  publicClient,
+  account,
+  activeChain: AEGIS_SWAP_MAINNET_CHAIN,
+  market,
+  inputToken,
+  outputToken,
+  mode: 'exactIn',
+  amount: 1_000_000n,
+  slippageBps: 100
+})
+```
+
+Amounts are raw token base units. `slippageBps: 100` means 1%.
+The Aegis 0.5% output fee is applied by the high-level quote and execution
+helpers.
+
+## Direct Pool Execution
+
+```ts
+import {
+  AEGIS_SWAP_MAINNET_CHAIN,
+  executeDirectPoolSwap,
+  resolveWalletSession
+} from '@aegis-engine/core'
+
 const wallet = await resolveWalletSession()
 
 const result = await executeDirectPoolSwap({
   wallet,
   publicClient,
   activeChain: AEGIS_SWAP_MAINNET_CHAIN,
-  market: AEGIS_SWAP_MARKETS.WATER_USDC,
-  inputToken: AEGIS_SWAP_TOKENS.USDC,
-  outputToken: AEGIS_SWAP_TOKENS.WATER,
+  market,
+  inputToken,
+  outputToken,
   mode: 'exactIn',
   amount: 1_000_000n,
-  slippageBps: 100
+  slippageBps: 100,
+  displayedQuote: quote,
+  approvalMode: 'exact',
+  onStatus: (status) => setStatus(status),
+  onTxHash: (hash) => setTxHash(hash),
+  onSubmitted: (hash, swap) => trackSwapSubmitted(hash, swap)
 })
 ```
 
-For Kyber routes, call `executeKyberSwap` with an input token, output token,
-amount, and slippage. Both execution actions accept callbacks for status,
-transaction hash, and submitted swap details so a host UI can render its own
-progress surfaces.
+Passing `displayedQuote` is recommended. Core requotes immediately before
+submission and refuses to submit if the fresh quote no longer satisfies the
+protection the user saw.
+
+## KyberSwap Quote
+
+```ts
+import {
+  AGGREGATED_SWAP_DEFAULT_TOKENS,
+  fetchAggregatedSwapQuote
+} from '@aegis-engine/core'
+
+const quote = await fetchAggregatedSwapQuote(
+  AGGREGATED_SWAP_DEFAULT_TOKENS.USDC,
+  AGGREGATED_SWAP_DEFAULT_TOKENS.USDT,
+  1_000_000n,
+  100,
+  'exactIn'
+)
+```
+
+For a display-only quote, omit the account. For executable calldata, pass the
+user account:
+
+```ts
+const executableQuote = await fetchAggregatedSwapQuote(
+  inputToken,
+  outputToken,
+  amount,
+  slippageBps,
+  'exactIn',
+  wallet.account
+)
+```
+
+## KyberSwap Execution
+
+```ts
+import {
+  AEGIS_SWAP_MAINNET_CHAIN,
+  AGGREGATED_SWAP_DEFAULT_TOKENS,
+  executeKyberSwap,
+  resolveWalletSession
+} from '@aegis-engine/core'
+
+const wallet = await resolveWalletSession()
+
+const result = await executeKyberSwap({
+  wallet,
+  publicClient,
+  activeChain: AEGIS_SWAP_MAINNET_CHAIN,
+  inputToken: AGGREGATED_SWAP_DEFAULT_TOKENS.USDC,
+  outputToken: AGGREGATED_SWAP_DEFAULT_TOKENS.USDT,
+  amount: 1_000_000n,
+  slippageBps: 100,
+  displayedQuote: quote,
+  approvalMode: 'exact',
+  onStatus: (status) => setStatus(status),
+  onTxHash: (hash) => setTxHash(hash)
+})
+```
+
+Kyber execution will:
+
+- switch the wallet to the active chain when needed,
+- approve the Kyber router for ERC-20 input tokens,
+- skip approval for native ETH-style input tokens,
+- rebuild the route with executable calldata for the connected account,
+- reject submission if the route moved below the displayed minimum,
+- send the transaction and wait for a receipt.
+
+## Approval Modes
+
+`approvalMode` controls ERC-20 approval sizing.
+
+- `exact`: approve only the current quote spend.
+- `max`: approve the maximum spender allowance to reduce future approval prompts.
+
+Direct pool swaps also use Permit2. Core first attempts an off-chain Permit2
+signature and falls back to an on-chain Permit2 approval if the wallet cannot
+produce a compatible typed-data signature.
+
+## Result Shape
+
+Execution returns:
+
+```ts
+{
+  hash: Hex
+  explorerUrl: string
+  quote: DirectSwapQuote | AggregatedSwapQuote
+  receiptSummary: {
+    transactionHash: Hex
+    blockNumber: bigint
+    gasUsed: bigint
+    effectiveGasPrice: bigint
+    feeWei: bigint
+  }
+  swap: {
+    mode: 'exactIn' | 'exactOut'
+    inputSymbol: string
+    outputSymbol: string
+    amountIn: bigint
+    amountOut: bigint
+    feeAmount: bigint
+    feeBps: number
+  }
+}
+```
+
+## Errors To Handle
+
+- `DirectPoolSwapPriceMovedError`: direct pool submit-time quote moved beyond
+  the displayed tolerance. The error includes the fresh `quote`.
+- `KyberSwapPriceMovedError`: Kyber executable route moved below the displayed
+  minimum. The error includes the fresh `quote`.
+- User rejection errors normalize through `errorMessage(error, fallback)`.
+- Kyber temporary failures can be mapped with
+  `aggregatedSwapErrorMessage(error, fallback)`.
+
+## Publishing
+
+This package is configured with `prepack`, so `npm publish` builds `dist` before
+creating the tarball.
+
+```sh
+npm publish --access public
+```

package/dist/actions/allowance.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Polls an ERC-20 allowance read until it covers `minimum`, then asserts it did.
+ * Shared by the direct-pool and KyberSwap approval flows after they submit an
+ * approval transaction: a confirmed approval whose allowance is still short means
+ * the wallet approved a smaller amount, so the swap must not proceed.
+ */
+export declare function confirmAllowanceReached(read: () => Promise<bigint>, minimum: bigint): Promise<bigint>;

package/dist/actions/directPoolSwap.d.ts

@@ -1,5 +1,5 @@
 import { type Hex, type PublicClient } from 'viem';
-import type { AegisSwapChainConfig, AegisSwapFeeConfig, AegisSwapMarket, AegisSwapToken } from '../config';
+import type { AegisSwapChainConfig, AegisSwapMarket, AegisSwapToken } from '../config';
 import { type DirectSwapQuote, type SwapQuoteMode } from '../quote';
 import type { AegisSwapApprovalMode, WalletSession } from '../swap/types';
 import type { AegisSwapActionCallbacks, AegisSwapActionResult } from './types';
@@ -11,6 +11,18 @@ export type DirectPoolSwapApprovalResult = {
     approvalHash: Hex | null;
     allowance: bigint;
 };
+export declare function fetchDirectPoolSwapQuote(args: {
+    publicClient: PublicClient;
+    account: WalletSession['account'];
+    activeChain: AegisSwapChainConfig;
+    market: AegisSwapMarket;
+    inputToken: AegisSwapToken;
+    outputToken: AegisSwapToken;
+    mode: SwapQuoteMode;
+    amount: bigint;
+    slippageBps: number;
+    signal?: AbortSignal;
+}): Promise<DirectSwapQuote>;
 export declare function approveDirectPoolSwapInput(args: {
     wallet: WalletSession;
     publicClient: PublicClient;
@@ -31,7 +43,6 @@ export declare function executeDirectPoolSwap(args: {
     mode: SwapQuoteMode;
     amount: bigint;
     slippageBps: number;
-    fee?: AegisSwapFeeConfig | null;
     displayedQuote?: DirectSwapQuote | null;
     approvalMode?: AegisSwapApprovalMode;
     signal?: AbortSignal;