@pafi-dev/trading 0.2.0 → 0.3.0

package/README.md

@@ -3,462 +3,216 @@
 [![npm](https://img.shields.io/npm/v/@pafi-dev/trading)](https://www.npmjs.com/package/@pafi-dev/trading)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Stateless on-chain trading handlers for PAFI — swap PT → USDT and deposit USDC into Orderly perp.
+On-chain trading for PAFI: V4 swap quote + UserOp build, Orderly
+perp deposit. **Direction-agnostic** since 0.2.0 — quote and swap any
+ERC-20 → ERC-20 routable through PAFI's V4 pools.
 
-All handlers are purely on-chain (Uniswap V4 Quoter + UniversalRouter + Orderly Vault). No
-ledger, no signer, no database. Safe to use in any backend (NestJS, Express, Hono) or
-client-side (React, React Native).
+**Browser + Node-safe.** Stateless (no DB, no signer, no auth). Peer-deps:
+`viem ^2`. Plus `@pafi-dev/core` for primitives.
 
 ---
 
-## Requirements
+## Why this exists
 
-- Node.js >= 18 (server) or any modern bundler (client)
-- TypeScript >= 5.0
-- `viem` ^2.0.0 and `@pafi-dev/core` ^0.5.17 (peer dependencies)
+Issuer backends (`@pafi-dev/issuer`) cover the issuer-signed flows
+(claim, redeem). Trading is the FE-callable surface for actions that
+don't need an issuer signature:
 
-> **Latest:** `0.1.9` — `handleSwap` / `handlePerpDeposit` now
-> auto-quote the operator fee and auto-resolve the PAFI fee recipient.
-> Caller no longer pre-fetches anything from the issuer backend. See
-> [Changelog](#changelog).
+- **Quote** PT → USDT, USDT → PT, PT0 → PT1 — pure on-chain V4 Quoter
+  read, multicall'd.
+- **Build swap UserOp** with operator gas-reimbursement fee in the
+  input token (auto-quoted via Chainlink). Sponsored + fallback variants.
+- **Build perp deposit UserOp** via the PAFI Orderly Relay (Relay
+  covers LayerZero `msg.value`, user pays USDC fee).
+
+Stateless and HTTP-free — issuer backends or FE apps that want a
+server-canonical quote/swap can wrap `TradingHandlers` directly.
 
 ---
 
 ## Installation
 
 ```bash
-npm install @pafi-dev/trading @pafi-dev/core viem
-# or
 pnpm add @pafi-dev/trading @pafi-dev/core viem
 ```
 
 ---
 
-## Quick start
+## Quick start (FE)
 
 ```ts
 import { createPublicClient, http } from "viem";
-import { base } from "viem/chains";
-import { TradingHandlers } from "@pafi-dev/trading";
+import {
+  TradingHandlers,
+  fetchPafiPools,
+} from "@pafi-dev/trading";
+import { getContractAddresses } from "@pafi-dev/core";
 
-const provider = createPublicClient({ chain: base, transport: http(RPC_URL) });
+const provider = createPublicClient({ transport: http("https://mainnet.base.org") });
 const trading = new TradingHandlers({ provider, chainId: 8453 });
-```
-
----
-
-## Handlers
-
-### `handleQuote` — GET /quote
+const { usdt } = getContractAddresses(8453);
 
-Quote exact-input PT → USDT via Uniswap V4 on-chain Quoter. Uses multicall to batch all
-candidate routes into a single RPC call.
+// Pool discovery — loop call when both sides are PT (PT0 → PT1 multi-hop).
+const pools = await fetchPafiPools(8453, POINT_TOKEN);
 
-```ts
-const quote = await trading.handleQuote({
+// Quote — direction-agnostic.
+const q = await trading.handleQuote({
   chainId: 8453,
-  pointTokenAddress: "0x7d25E7156E51F865D522fd3ef257a6B5DD41b97e",
-  amount: 1000n * 10n ** 18n,   // 1000 PT
-  pools: poolsFromSubgraph,     // optional — combined with COMMON_POOLS
+  inputTokenAddress: POINT_TOKEN,
+  outputTokenAddress: usdt,
+  amount: 100n * 10n ** 18n,    // 100 PT
+  pools,
 });
+// q.estimatedOutputAmount — bigint USDT raw (6 dec)
 
-// quote.estimatedUsdtOut  — raw USDT (6 decimals)
-// quote.gasEstimate       — estimated gas units
-// quote.quoteError        — "QUOTE_UNAVAILABLE" | "AMOUNT_TOO_SMALL_FOR_GAS" | undefined
-```
-
-Returns `quoteError` instead of throwing when no pool/path is found, so the caller can
-show a soft "unavailable" UI state without 500-ing.
-
-#### Frontend "quote review" pattern
-
-Quotes are pure on-chain reads (Uniswap V4 Quoter via Base RPC) — **no
-auth, no issuer-side state, nothing to proxy through the issuer
-backend.** Call `handleQuote` directly from the browser / React Native.
-
-```tsx
-import { TradingHandlers, fetchPafiPools } from "@pafi-dev/trading";
-import { createPublicClient, http, formatUnits } from "viem";
-import { base } from "viem/chains";
-
-const trading = new TradingHandlers({
-  provider: createPublicClient({ chain: base, transport: http(RPC_URL) }),
+// Swap — builds UserOp ready to submit via Bundler + EIP-7702.
+const swap = await trading.handleSwap({
   chainId: 8453,
+  userAddress,
+  inputTokenAddress: POINT_TOKEN,
+  outputTokenAddress: usdt,
+  amount: 100n * 10n ** 18n,
+  aaNonce,
+  pools,
+  // gasFeeAmount auto-quotes when input is a PT; pass explicit bigint to override.
+  // slippageBps auto-picks 50 bps single-hop / 100 bps multi-hop.
 });
-
-useEffect(() => {
-  if (amount <= 0n) return setQuote(null);
-  const t = setTimeout(async () => {
-    const pools = await fetchPafiPools(8453, POINT_TOKEN);
-    const result = await trading.handleQuote({
-      chainId: 8453,
-      pointTokenAddress: POINT_TOKEN,
-      amount,
-      pools,
-    });
-    setQuote(result);
-  }, 400);
-  return () => clearTimeout(t);
-}, [amount]);
-
-// Render:
-//   In:           formatUnits(amount, 18)                     PT
-//   You receive:  formatUnits(quote.estimatedUsdtOut, 6)      USDT
-//   Rate:         estimatedUsdtOut · 1e18 / amount / 1e6      USDT per 1 PT
-// On `quote.quoteError === "QUOTE_UNAVAILABLE"` → hide the Swap CTA.
+// swap.userOp + swap.userOpFallback (when fee > 0)
+// swap.hops — number of hops in chosen route
 ```
 
-Why client-direct (no `GET /quote` HTTP hop):
-
-- The quoter is stateless and reads from the public RPC — there's no
-  secret to hide and nothing to validate against an issuer's database.
-- One fewer round-trip on every keystroke (debounce hits the Quoter
-  directly, ~150 ms vs. ~400 ms via a backend proxy).
-- The quote stays internally consistent with the swap path that
-  `handleSwap` will pick — both use the same `findBestQuote()` call
-  under the hood with the same `pools` array, so what the user sees in
-  the review card is what they get on submit.
-
-> **Operator fee in USDT** is **NOT** part of the quote — it's an
-> issuer-policy concern decided at swap-build time. If you want a
-> "net out after fee" preview, fetch the issuer's gas-fee endpoint
-> separately and subtract on the client.
-
-Reference implementation lives in
-[`privy-pimlico-eip7702-example/app/components/WalletPanel.tsx`](https://github.com/pacific-finance/pafi-backend/blob/main/privy-pimlico-eip7702-example/app/components/WalletPanel.tsx)
-(search for `Quote review`).
-
 ---
 
-### `handleSwap` — POST /swap
-
-Quote the best route, apply slippage, and build an unsigned `PartialUserOperation` that
-batches: `PT.approve` → `Permit2.approve` → `UniversalRouter.execute` (→ `PT.transfer` fee).
+## Direction matrix
 
-```ts
-const swap = await trading.handleSwap({
-  chainId: 8453,
-  userAddress: "0xUserEOA",
-  pointTokenAddress: "0x7d25E7156E51F865D522fd3ef257a6B5DD41b97e",
-  amount: 1000n * 10n ** 18n,
-  aaNonce: 0n,          // from EntryPoint.getNonce(user, 0)
-  slippageBps: 50,      // 0.5% — default
-  pools: poolsFromSubgraph,
-  // optional gas fee deduction in PT:
-  // gasFeePt: 5n * 10n ** 18n,
-  // feeRecipient: "0xOperatorAddress",
-});
+| Direction | Use case | Hop count | Hook fee | Operator fee token |
+| --- | --- | --- | --- | --- |
+| `PT → USDT` | Cashout | 1 | 10% on this leg | PT |
+| `USDT → PT` | Buy PT | 1 | 0% | USDT |
+| `PT0 → PT1` | Same-issuer multi-token swap | 2 (via USDT) | 10% on PT0 leg only | PT0 |
 
-// swap.userOp            — unsigned PartialUserOperation
-// swap.estimatedUsdtOut  — raw USDT before slippage
-// swap.minAmountOut      — encoded in UserOp (revert if less)
-// swap.deadline          — unix seconds (now + 5 min)
-```
+**Same-issuer only** for PT0 → PT1 — caller is responsible for
+ensuring both PTs belong to the same issuer. SDK doesn't enforce.
 
-After receiving the response, the frontend:
-1. Requests paymaster sponsorship from `POST /pimlico` (sponsor-relayer, Privy auth)
-2. Signs the UserOp hash via Privy
-3. Submits to the Bundler
+The PAFI V4 hook charges 10% on PT → USDT direction at pool level
+(applied inside `UniversalRouter.execute`). Reflected in
+`estimatedOutputAmount` from `findBestQuote`.
 
 ---
 
-### `handlePerpDeposit` — POST /perp-deposit
+## Operator fee strategy
 
-Build an unsigned UserOp that deposits USDC into Orderly perp. The
-handler picks one of two paths automatically:
+The operator gas-reimbursement fee is charged in the **input token**
+(0.2.0+). Single approve covers `amountIn + gasFeeAmount`. User only
+needs to hold a single token.
 
-#### Path 1 — Relay (default, gas-sponsored)
+| Input | Auto-quote source | Caller needs to override? |
+| --- | --- | --- |
+| PT | `quoteOperatorFeePt` (Chainlink + V4 subgraph) | No |
+| USDT | falls back to 0 — pass `gasFeeAmount` explicitly | Yes (use `quoteOperatorFeeUsdt`) |
 
-`USDC.approve(relay)` → `relay.deposit(req)`
+---
 
-The PAFI Orderly Relay holds an ETH reserve and pays Orderly's
-LayerZero `msg.value` out of it. The user pays a USDC fee instead
-(quoted via `Relay.quoteTokenFee` and capped by `maxRelayFee`).
-Combined with paymaster sponsorship of ERC-4337 gas, **the user does
-not need any native ETH** — they only need USDC.
+## Multi-hop PT → PT1
 
 ```ts
-const deposit = await trading.handlePerpDeposit({
-  chainId: 8453,
-  userAddress: "0xUserEOA",
-  amount: 100_000_000n,    // 100 USDC (6 decimals)
-  aaNonce: 0n,
-  brokerId: "woofi_pro",   // "woofi_pro" | "orderly" | "logx"
-  // viaRelay: true,       // default
-  // maxRelayFee: 5_000_000n,  // optional, default = 5% of amount
-});
-
-// deposit.path === "relay"
-// deposit.userOp          — USDC.approve(relay) + relay.deposit(req)
-// deposit.relayTokenFee   — USDC fee charged by the Relay
-// deposit.layerZeroFee    — ETH wei the Relay covers on the user's behalf (informational)
-// deposit.relayAddress    — getContractAddresses(chainId).orderlyRelay
-```
+import { fetchPafiPools, TradingHandlers } from "@pafi-dev/trading";
 
-#### Path 2 — Vault (fallback, requires native ETH)
+// Loop call — fetch pools for both PTs, merge.
+const [poolsA, poolsB] = await Promise.all([
+  fetchPafiPools(8453, POINT_TOKEN_0),
+  fetchPafiPools(8453, POINT_TOKEN_1),
+]);
+const pools = [...poolsA, ...poolsB];
 
-`USDC.approve(vault)` → `vault.deposit{value: layerZeroFee}(data)`
-
-```ts
-const deposit = await trading.handlePerpDeposit({
+const swap = await trading.handleSwap({
   chainId: 8453,
-  userAddress: "0xUserEOA",
-  amount: 100_000_000n,
-  aaNonce: 0n,
-  brokerId: "woofi_pro",
-  viaRelay: false,         // explicit opt-out of Relay
+  userAddress,
+  inputTokenAddress: POINT_TOKEN_0,
+  outputTokenAddress: POINT_TOKEN_1,
+  amount: 100n * 10n ** 18n,
+  aaNonce,
+  pools,
 });
 
-// deposit.path === "vault"
-// deposit.userOp        — unsigned PartialUserOperation
-// deposit.layerZeroFee  — REQUIRED native ETH balance on the sender
-// deposit.relayTokenFee — 0n
+console.log(swap.hops);  // 2 — went through USDT
 ```
 
-> **Vault path = native ETH required.** The paymaster sponsors ERC-4337
-> gas, but `msg.value` (the LayerZero fee) must come from the user's
-> own ETH balance. Always check `walletEth >= layerZeroFee` before
-> submitting, OR — far better — leave `viaRelay` at its default to
-> stay on the zero-ETH path.
-
-#### Auto-fallback
-
-When `viaRelay` is `true` (default) but
-`getContractAddresses(chainId).orderlyRelay` is the placeholder
-sentinel (Relay not deployed for that chain), the handler silently
-falls back to the Vault path. Inspect `deposit.path` if you need to
-distinguish.
+V4 router auto-picks the best route across `pools + COMMON_POOLS`
+(default `maxHops=3`). Slippage auto-bumps to 100 bps for multi-hop.
 
 ---
 
-## Wiring into a NestJS controller
+## Perp deposit
 
 ```ts
-import { Controller, Get, Post, Body, Query } from "@nestjs/common";
-import { TradingHandlers } from "@pafi-dev/trading";
-
-@Controller()
-export class TradingController {
-  constructor(private readonly trading: TradingHandlers) {}
-
-  @Get("quote")
-  async quote(@Query() q: QuoteQueryDto) {
-    return this.trading.handleQuote({
-      chainId: q.chainId,
-      pointTokenAddress: q.pointToken,
-      amount: BigInt(q.amount),
-    });
-  }
-
-  @Post("swap")
-  async swap(@Body() body: SwapBodyDto) {
-    return this.trading.handleSwap({
-      chainId: body.chainId,
-      userAddress: body.userAddress,
-      pointTokenAddress: body.pointTokenAddress,
-      amount: BigInt(body.amount),
-      aaNonce: BigInt(body.aaNonce),
-      slippageBps: body.slippageBps,
-    });
-  }
-
-  @Post("perp-deposit")
-  async perpDeposit(@Body() body: PerpDepositBodyDto) {
-    return this.trading.handlePerpDeposit({
-      chainId: body.chainId,
-      userAddress: body.userAddress,
-      amount: BigInt(body.amount),
-      aaNonce: BigInt(body.aaNonce),
-      brokerId: body.brokerId,
-    });
-  }
-}
-```
-
-Register `TradingHandlers` as a provider:
+const deposit = await trading.handlePerpDeposit({
+  chainId: 8453,
+  userAddress,
+  amount: 1_000_000n,     // 1 USDC (6 dec)
+  aaNonce,
+  brokerId: "orderly",    // "orderly" | "woofi_pro" | "logx"
+  // viaRelay: true (default) — uses PAFI Orderly Relay (no msg.value needed)
+  pointTokenAddress: POINT_TOKEN,  // optional — for PT operator fee
+});
 
-```ts
-import { createPublicClient, http } from "viem";
-import { base } from "viem/chains";
-import { TradingHandlers } from "@pafi-dev/trading";
-
-@Module({
-  providers: [
-    {
-      provide: TradingHandlers,
-      useFactory: (config: ConfigService) =>
-        new TradingHandlers({
-          provider: createPublicClient({
-            chain: base,
-            transport: http(config.get("RPC_URL")),
-          }),
-          chainId: config.get<number>("CHAIN_ID"),
-        }),
-      inject: [ConfigService],
-    },
-    TradingController,
-  ],
-})
-export class TradingModule {}
+// deposit.userOp — submit via Bundler + Paymaster
+// deposit.path — "relay" (preferred) or "vault" (direct, requires native ETH)
 ```
 
+The PAFI Relay covers LayerZero `msg.value` from its ETH reserve and
+charges a USDC fee (`Relay.quoteTokenFee`). User wallet doesn't need
+native ETH.
+
 ---
 
-## API types
+## Standalone primitives
 
-All request/response types are exported for use in frontend SDKs or OpenAPI generation:
+For callers that want to compose flows beyond what `TradingHandlers`
+provides:
 
 ```ts
-import type {
-  ApiQuoteRequest,
-  ApiQuoteResponse,
-  ApiQuoteError,
-  ApiSwapRequest,
-  ApiSwapResponse,
-  ApiPerpDepositRequest,
-  ApiPerpDepositResponse,
+import {
+  buildSwapUserOp,
+  findBestQuote,
+  simulateSwap,
+  buildUniversalRouterExecuteArgs,
+  buildPermit2ApprovalCalldata,
+  fetchPafiPools,
 } from "@pafi-dev/trading";
 ```
 
-Since `bigint` does not serialize to JSON natively, HTTP controllers should convert
-`bigint` fields to strings in the response (e.g. `.toString()`).
+Use these to build custom direction-agnostic swap flows or pre-flight
+simulations.
 
 ---
 
-## Relationship to other PAFI packages
+## API reference
 
-| Package | Scope |
-|---|---|
-| `@pafi-dev/core` | Chain primitives — EIP-712, UserOp builders, on-chain reads, ABIs |
-| `@pafi-dev/issuer` | Issuer backend — mint/redeem auth, ledger, policy, indexer |
-| `@pafi-dev/trading` | On-chain trading — swap quote + UserOp, perp deposit UserOp |
-
-`@pafi-dev/trading` depends on `@pafi-dev/core` for `findBestQuote`,
-`buildSwapWithGasDeduction`, `buildPerpDepositWithGasDeduction`, and contract addresses.
-It does not depend on `@pafi-dev/issuer`.
-
----
-
-## Changelog
-
-### 0.1.9
-
-`handleSwap` and `handlePerpDeposit` now **auto-quote the operator fee
-+ auto-resolve the PAFI fee recipient**. Caller no longer needs to
-pre-fetch anything from the issuer backend.
-
-**API changes** (additive — passing the old explicit values still works
-as overrides):
-
-- `ApiSwapRequest.gasFeePt` — semantics changed:
-  - `undefined` (default): handler runs `quoteOperatorFeePt` (Chainlink
-    + V4 subgraph) to compute the PT fee.
-  - `0n`: strips the `PT.transfer(...)` from the batch (unsponsored
-    fallback).
-  - explicit bigint: override (issuer markup / subsidy).
-- `ApiSwapRequest.feeRecipient` — **REMOVED**. Hardcoded to
-  `getContractAddresses(chainId).pafiFeeRecipient`. Sponsor-relayer's
-  L1 gate would reject any other recipient anyway, so the option was
-  removed to keep the API honest.
-- `ApiPerpDepositRequest.gasFeePtRecipient` — **REMOVED** (same
-  reason). `pointTokenAddress` still required when fee > 0 (handler
-  needs the token to call `transfer` against).
-- `ApiSwapResponse.feeAmountUsed` / `.feeRecipient` — **NEW**. Echo
-  what the handler actually embedded so the FE can display it without
-  re-quoting.
-- `ApiPerpDepositResponse.feeAmountUsed` / `.feeRecipient` — same.
-
-**Migration**:
-
-```diff
-- const gasFeePt = await quoteOperatorFeePt({...});
-- const result = await trading.handleSwap({
--   ..., gasFeePt, feeRecipient: PAFI_FEE_RECIPIENT,
-- });
-+ const result = await trading.handleSwap({...});
-+ console.log(`Fee charged: ${result.feeAmountUsed} → ${result.feeRecipient}`);
-```
-
-Force unsponsored / fallback (no fee transfer):
+### `TradingHandlers`
 
 ```ts
-const result = await trading.handleSwap({ ..., gasFeePt: 0n });
+new TradingHandlers({ provider: PublicClient, chainId: number })
 ```
 
-Fee policy override (rare):
+Methods:
 
-```ts
-const result = await trading.handleSwap({ ..., gasFeePt: customAmount });
-```
+| Method | Purpose |
+| --- | --- |
+| `handleQuote({ inputTokenAddress, outputTokenAddress, amount, pools? })` | V4 quote. Returns `{ inputAmount, estimatedOutputAmount, gasEstimate, quoteError? }` |
+| `handleSwap({ userAddress, inputTokenAddress, outputTokenAddress, amount, aaNonce, pools?, gasFeeAmount?, slippageBps? })` | Build UserOp. Returns `{ userOp, userOpFallback?, estimatedOutputAmount, minAmountOut, hops, deadline, feeAmountUsed, feeRecipient }` |
+| `handlePerpDeposit({ userAddress, amount, aaNonce, brokerId, viaRelay?, maxRelayFee?, pointTokenAddress?, gasFeePt? })` | Build UserOp. Returns Orderly deposit response |
+
+### Free functions
 
-### 0.1.5
-
-`handlePerpDeposit` now defaults to the **PAFI Orderly Relay** path —
-zero native ETH required.
-
-**Why.** The previous Vault-direct path required the user wallet to
-hold `layerZeroFee` as native ETH (paymaster sponsors ERC-4337 gas
-but never `msg.value`). For users coming through Privy embedded
-wallets / sponsored onboarding flows that's often `0 ETH`, so the
-deposit reverted with `BatchExecutor.CallFailed(1, 0x)` (no-data
-revert from the Vault when it can't pay LayerZero out of the EOA).
-
-The Relay (deployed at `getContractAddresses(8453).orderlyRelay
-=` `0xDA082DAce1522c185aeB5A713FcA6fa6B6E99e7f` on Base) holds an ETH
-reserve and pays LayerZero out of it; the user pays a USDC fee
-instead. Combined with paymaster sponsorship, the user only needs
-USDC.
-
-**API additions** on `ApiPerpDepositRequest`:
-
-- `viaRelay?: boolean` — default `true`. Set `false` to force the
-  Vault fallback.
-- `maxRelayFee?: bigint` — slippage cap on the Relay's USDC fee.
-  Defaults to 5% of `amount`.
-- `pointTokenAddress?` / `gasFeePt?` / `gasFeePtRecipient?` — optional
-  PT gas-fee transfer prepended to the batch (sponsored issuer flow).
-
-**API additions** on `ApiPerpDepositResponse`:
-
-- `path: "relay" | "vault"` — which execution path the handler chose.
-  Inspect this when `viaRelay` was left at its default to know if the
-  auto-fallback to Vault triggered (e.g. on a chain without a deployed
-  Relay).
-- `relayTokenFee: bigint` — USDC fee the Relay will charge. `0n` when
-  `path === "vault"`.
-- `relayAddress: Address` — the address the UserOp targets. Equal to
-  the Vault address when `path === "vault"`.
-
-When `viaRelay` is `true` but no Relay is deployed for the chain
-(`getContractAddresses(chainId).orderlyRelay` is a placeholder), the
-handler silently falls back to the Vault path — inspect
-`response.path` to detect this.
-
-### 0.1.4
-
-- README rewrite for the **frontend "quote review" pattern** — direct
-  client-side `trading.handleQuote` call, no HTTP hop through the
-  issuer backend. Quotes are stateless on-chain reads, so the
-  pre-existing `GET /quote` proxy was redundant.
-
-### 0.1.3
-
-- Peer dependency `@pafi-dev/core` bumped to `0.5.17` so the swap path
-  picks up `buildUserOpTypedData()` + the v0.8 EIP-712 `computeUserOpHash`.
-  Required for the EIP-7702 mobile swap flow on Pimlico's
-  `Simple7702Account` — the previous v0.7 hash format and EIP-191
-  signing path both reverted with `AA24 signature error`. See
-  [`@pafi-dev/core` changelog 0.5.16](../core/README.md#0516).
-- README adds a **frontend "quote review" pattern** — debounced
-  `/quote` polling so the user sees `X PT → ~Y USDT` (after operator
-  gas fee) before submitting the swap UserOp. Reference implementation
-  in `privy-pimlico-eip7702-example/app/components/WalletPanel.tsx`.
-
-### 0.1.2
-
-- Initial public release. `handleQuote`, `handleSwap`,
-  `handlePerpDeposit` stateless handlers + `fetchPafiPools` subgraph
-  helper.
+- `findBestQuote(client, chainId, tokenIn, tokenOut, amount, pools, quoterAddress?, maxHops?)`
+- `quoteBestRoute`, `quoteExactInput`, `quoteExactInputSingle`
+- `buildAllPaths`, `combineRoutes`
+- `buildSwapUserOp(params)` — direction-agnostic UserOp builder
+- `buildUniversalRouterExecuteArgs`, `buildV4SwapInput`, `buildSwapFromQuote`
+- `buildPermit2ApprovalCalldata`, `buildErc20ApprovalCalldata`, `checkAllowance`
+- `simulateSwap` — `eth_call` dry-run
+- `fetchPafiPools(chainId, pointTokenAddress, subgraphUrl?)`
 
 ---