aegis-swap-widget 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,17 @@
 # Aegis Swap Widget
 
-Embeddable React swap widget for WATER, WOOD, GRASS, and STONE. It does not import the private Aegis Engine SDK and does not use Uniswap widget packages.
+Embeddable React swap widget for Aegis direct pools. It does not import the private Aegis Engine SDK and does not use Uniswap widget packages.
 
 The widget quotes the configured Uniswap v4 pool, handles ERC20 approval to Permit2, signs a Permit2 batch for the Aegis router, and submits the direct pool swap.
 
+Typing in the Sell field creates an exact-input swap. Typing in the Buy field
+creates an exact-output swap. Active quotes refresh every five seconds while the
+amount is valid.
+
+On Ethereum mainnet, widget swaps apply a fixed 50 bps output-token fee to
+`0x8ea2C7de60ef1Cd4dcE64ea2DDDe2f99F0127eFC`. The widget does not apply this
+fee on other chains yet.
+
 ## Install
 
 ```bash
@@ -19,7 +27,6 @@ import 'aegis-swap-widget/styles.css'
 export function Swap() {
   return (
     <AegisSwapWidget
-      defaultTarget="GRASS"
       theme="dark"
       accentColor="#31d48a"
     />
@@ -27,6 +34,8 @@ export function Swap() {
 }
 ```
 
+Without a `pools` prop, the widget uses the bundled Aegis WATER, WOOD, GRASS, and STONE pool configs. For production integrations, pass the pools the host app wants to expose.
+
 By default the component uses `window.ethereum` when available, so injected wallets
 like MetaMask and Rabby work without any wallet props.
 
@@ -48,34 +57,99 @@ Hosts can choose the widget surface and brand accent at instantiation time:
 
 `theme` supports `dark` and `light`. `accentColor` accepts any CSS color value and is used for the CTA, selected pools, focus states, links, and swap controls. `accentTextColor` is optional and only needed when the accent color needs a different CTA text color for contrast.
 
-## Instantiate From Pool Keys
+## Configure Pools
+
+Pass the direct pools you want to expose. This is the recommended integration path because it is not tied to any specific asset list.
+
+For the first WATER, WOOD, GRASS, and STONE implementors, use the bundled mainnet pool configs:
+
+```tsx
+import { AegisSwapWidget, AEGIS_SWAP_MARKETS } from 'aegis-swap-widget'
+import 'aegis-swap-widget/styles.css'
+
+const pools = [
+  AEGIS_SWAP_MARKETS.WATER_USDC,
+  AEGIS_SWAP_MARKETS.WOOD_USDC,
+  AEGIS_SWAP_MARKETS.GRASS_USDC,
+  AEGIS_SWAP_MARKETS.STONE_USDC,
+]
+
+export function Swap() {
+  return (
+    <AegisSwapWidget
+      pools={pools}
+      defaultPoolId="WATER_USDC"
+      theme="dark"
+      accentColor="#31d48a"
+    />
+  )
+}
+```
+
+Use `defaultPoolId` to choose which pool opens first. Use `targets` when a host wants a different pool order or subset:
+
+```tsx
+<AegisSwapWidget
+  pools={pools}
+  defaultPoolId="GRASS_USDC"
+  targets={['GRASS_USDC', 'WATER_USDC']}
+/>
+```
+
+## Fees
+
+The widget applies a fixed output-token fee only on Ethereum mainnet:
+
+- Fee: `50` bps
+- Recipient: `0x8ea2C7de60ef1Cd4dcE64ea2DDDe2f99F0127eFC`
 
-Pass the direct pools you want to expose. When `poolKeys` is provided, the widget only renders those token buttons unless you also pass `targets`.
+This fee is internal to the widget and is not configured by host sites.
+
+For custom assets, provide full pool and token metadata:
 
 ```tsx
 import {
   AegisSwapWidget,
-  AEGIS_SWAP_MARKETS,
-  type AegisSwapPoolKeys,
+  AEGIS_DYNAMIC_FEE_FLAG,
+  AEGIS_SWAP_HOOK,
+  type AegisSwapPoolConfig,
 } from 'aegis-swap-widget'
 
-const poolKeys: AegisSwapPoolKeys = {
-  GRASS: {
-    poolKey: AEGIS_SWAP_MARKETS.GRASS.poolKey,
-    label: 'USDC / GRASS',
-  },
-  WATER: {
-    poolKey: AEGIS_SWAP_MARKETS.WATER.poolKey,
-    label: 'USDC / WATER',
+const pools: AegisSwapPoolConfig[] = [
+  {
+    id: 'usdc-example',
+    label: 'USDC / EXAMPLE',
+    poolKey: {
+      currency0: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      currency1: '0xYourTokenAddress',
+      fee: AEGIS_DYNAMIC_FEE_FLAG,
+      tickSpacing: 60,
+      hooks: AEGIS_SWAP_HOOK,
+    },
+    counterToken: {
+      chainId: 1,
+      address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      name: 'USD Coin',
+      symbol: 'USDC',
+      decimals: 6,
+    },
+    token: {
+      chainId: 1,
+      address: '0xYourTokenAddress',
+      name: 'Example Token',
+      symbol: 'EXAMPLE',
+      decimals: 18,
+      iconUrl: 'https://example.com/token.svg',
+    },
   },
-}
+]
 
 export function Swap() {
-  return <AegisSwapWidget poolKeys={poolKeys} defaultTarget="GRASS" />
+  return <AegisSwapWidget pools={pools} defaultPoolId="usdc-example" />
 }
 ```
 
-For the built-in WATER, WOOD, GRASS, and STONE symbols, the widget fills in token metadata, router, Permit2, Quoter, and pool id automatically. You can override any of those fields inside each pool-key config.
+Each pool can override `router`, `permit2`, `quoter`, and `poolId`. If omitted, those values come from the active chain config.
 
 ## Chains
 
@@ -92,11 +166,38 @@ import { mainnet } from 'viem/chains'
       rpcUrls: ['https://your-mainnet-rpc.example'],
     },
   }}
-  poolKeys={poolKeys}
+  pools={pools}
+/>
+```
+
+Uniswap v4 deployments are configured per chain. The package exports
+`UNISWAP_V4_CONTRACTS_BY_CHAIN` for the supported mainnet deployments listed in
+the official Uniswap v4 deployment docs: Ethereum, Optimism, Unichain, Polygon,
+Base, and Arbitrum.
+
+```tsx
+import { base } from 'viem/chains'
+import { UNISWAP_V4_CONTRACTS_BY_CHAIN } from 'aegis-swap-widget'
+
+<AegisSwapWidget
+  chainId={8453}
+  chains={{
+    8453: {
+      chain: base,
+      router: '0xYourAegisRouter',
+      rpcUrls: ['https://your-base-rpc.example'],
+      v4Contracts: UNISWAP_V4_CONTRACTS_BY_CHAIN[8453],
+    },
+  }}
+  pools={pools}
 />
 ```
 
-For a new chain, provide a viem `chain`, router, Permit2, Quoter, and RPC URLs. Pool-key entries can set `chainId`, `token`, and `counterToken` when the token addresses differ by chain.
+For a new chain that is not bundled, provide a viem `chain`, Aegis router, RPC
+URLs, and `v4Contracts` with at least `permit2` and `quoter`. Include
+`poolManager`, `positionManager`, `stateView`, and `universalRouter` when the
+host app needs those addresses too. Pool entries can set `chainId`, `token`, and
+`counterToken` when token addresses differ by chain.
 
 ## Token Icons
 
@@ -106,11 +207,11 @@ The widget fetches token icons by address using the metadata IDs from the Aegis
 ```tsx
 <AegisSwapWidget
   metadataEndpoint="/graphql/meta"
-  poolKeys={poolKeys}
+  pools={pools}
 />
 ```
 
-Use `metadataEndpoint={null}` to disable backend icon hydration. Tokens can also provide `iconUrl` directly when passed through a custom `market` or pool-key token override.
+Use `metadataEndpoint={null}` to disable backend icon hydration. Tokens can also provide `iconUrl` directly.
 
 ## With Existing Wallet UI
 
@@ -121,7 +222,7 @@ If a site already has wallet state, pass its EIP-1193 provider and account:
   provider={provider}
   account={account}
   onConnectWallet={openWallet}
-  defaultTarget="STONE"
+  defaultPoolId="STONE_USDC"
   onSubmitted={(hash) => console.log(hash)}
 />
 ```
@@ -161,16 +262,15 @@ automatically when it renders and again when the user clicks connect/swap.
 - `getProvider`: optional provider resolver for wallet libraries with async providers.
 - `onConnectWallet`: optional callback for opening the host wallet modal. It may return `{ provider, account }`.
 - `chainId`: active chain id. Defaults to Ethereum mainnet.
-- `chains`: optional chain config overrides or additional chain configs.
-- `poolKeys`: optional direct pool keys to render and swap against.
-- `targets`: optional token button order/subset.
-- `defaultTarget`: `WATER`, `WOOD`, `GRASS`, or `STONE`.
+- `chains`: optional chain config overrides or additional chain configs, including per-chain `v4Contracts`.
+- `pools`: direct pool configs to render and swap against.
+- `defaultPoolId`: initial pool id when `pools` is provided.
+- `targets`: optional pool id order/subset.
 - `defaultDirection`: `intoTarget` for USDC to target, or `outOfTarget` for target to USDC.
-- `markets`: optional override for pool/router/quoter config.
+- `markets`: advanced override for normalized pool/router/quoter config.
 - `rpcUrls`: optional RPC fallback list for the active chain.
 - `metadataEndpoint`: optional metadata GraphQL endpoint for `GlobalToken.iconURL` token icons. Set to `null` to disable.
 - `theme`: `dark` or `light`. Defaults to `dark`.
-- `themeMode`: legacy alias for `theme`.
 - `accentColor`: CSS accent color for the CTA, selected pools, focus states, links, and swap controls.
 - `accentTextColor`: optional CTA text color for contrast with the chosen accent.
 
@@ -183,7 +283,9 @@ The package ships mainnet direct-pool configs for:
 - `USDC / GRASS`
 - `USDC / STONE`
 
-These use the Aegis mainnet router `0x00581261a1200956ea05d1810fF28ffd66D8E254`, Permit2, and the public Uniswap v4 Quoter.
+These use the Aegis mainnet router `0x00581261a1200956ea05d1810fF28ffd66D8E254`
+and the Ethereum entry in `UNISWAP_V4_CONTRACTS_BY_CHAIN` for Permit2 and the
+public Uniswap v4 Quoter.
 
 ## Local Demo