@aegis-engine/core 0.1.0 → 0.1.1

package/README.md

@@ -2,41 +2,308 @@
 
 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.
+
+## 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)
+})
+```
+
+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)
 })
 ```
 
-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.
+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/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;