@pafi-dev/trading 0.4.3 → 0.5.0

package/README.md

@@ -3,25 +3,29 @@
 [![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)
 
-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.
+On-chain trading for PAFI: V3 swap quote + UserOp build, Orderly
+perp deposit. **Direction-agnostic** — quote and swap any
+ERC-20 → ERC-20 routable through PAFI's Uniswap V3 pools.
 
-**Browser + Node-safe.** Stateless (no DB, no signer, no auth). Peer-deps:
-`viem ^2`. Plus `@pafi-dev/core` for primitives.
+**Browser + Node-safe.** Stateless (no DB, no signer, no auth).
+Peer-deps: `viem ^2`. Plus `@pafi-dev/core` for primitives.
+
+> PAFI's PT pools are standard Uniswap V3 (no hooks). USDT ↔ PT swaps
+> incur only the standard LP fee on top of the SDK's operator fee.
 
 ---
 
 ## Why this exists
 
-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:
+Issuer backends (`@pafi-dev/issuer`) cover issuer-signed flows (claim,
+redeem). Trading is the FE-callable surface for actions that don't need
+an issuer signature:
 
-- **Quote** PT → USDT, USDT → PT, PT0 → PT1 — pure on-chain V4 Quoter
+- **Quote** PT → USDT, USDT → PT, PT0 → PT1 — pure on-chain V3 QuoterV2
   read, multicall'd.
 - **Build swap UserOp** with operator gas-reimbursement fee in the
-  input token (auto-quoted via Chainlink). Sponsored + fallback variants.
+  input token (auto-quoted via Chainlink + V3 subgraph). Sponsored +
+  fallback variants.
 - **Build perp deposit UserOp** via the PAFI Orderly Relay (Relay
   covers LayerZero `msg.value`, user pays USDC fee).
 
@@ -36,6 +40,9 @@ server-canonical quote/swap can wrap `TradingHandlers` directly.
 pnpm add @pafi-dev/trading @pafi-dev/core viem
 ```
 
+Make sure to install **`@pafi-dev/core`** explicitly at top-level
+to avoid pnpm deduping into a nested copy with stale URLs/addresses.
+
 ---
 
 ## Quick start (FE)
@@ -66,7 +73,7 @@ const q = await trading.handleQuote({
 // q.estimatedOutputAmount — bigint USDT raw (6 dec)
 
 // Swap — builds UserOp ready to submit via Bundler + EIP-7702.
-const swap = await trading.handleSwap({
+const swap = await trading.handleSwap(userAddress, {
   chainId: 8453,
   userAddress,
   inputTokenAddress: POINT_TOKEN,
@@ -74,42 +81,53 @@ const swap = await trading.handleSwap({
   amount: 100n * 10n ** 18n,
   aaNonce,
   pools,
-  // gasFeeAmount auto-quotes when input is a PT; pass explicit bigint to override.
+  // gasFeeAmount auto-quotes; pass explicit bigint to override.
   // slippageBps auto-picks 50 bps single-hop / 100 bps multi-hop.
 });
 // swap.userOp + swap.userOpFallback (when fee > 0)
-// swap.hops — number of hops in chosen route
+// swap.hops, swap.estimatedOutputAmount, swap.minAmountOut
 ```
 
 ---
 
 ## Direction matrix
 
-| Direction | Use case | Hop count | Hook fee | Operator fee token |
+| Direction | Use case | Hop count | 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 |
-
-**Same-issuer only** for PT0 → PT1 — caller is responsible for
-ensuring both PTs belong to the same issuer. SDK doesn't enforce.
+| `PT → USDT` | Cashout | 1 | 0.3% pool fee | USDT (output) |
+| `USDT → PT` | Buy PT | 1 | 0.3% pool fee | PT (output) |
+| `PT0 → PT1` | Multi-token swap | 2 (via USDT) | 0.3% × 2 hops | output PT |
 
-The PAFI V4 hook charges 10% on PT → USDT direction at pool level
-(applied inside `UniversalRouter.execute`). Reflected in
-`estimatedOutputAmount` from `findBestQuote`.
+**Cross-issuer OK** for PT0 → PT1 (e.g. TPT ↔ LTR if both issuers ship
+V3 pools with USDT). The router auto-routes through `USDT`.
 
 ---
 
 ## Operator fee strategy
 
-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.
+The operator gas-reimbursement fee is charged in the **output token**.
+User receives `(net - operatorFee)` instead of `net` after the swap.
 
-| Input | Auto-quote source | Caller needs to override? |
+| Output | Auto-quote source | Caller override |
 | --- | --- | --- |
-| PT | `quoteOperatorFeePt` (Chainlink + V4 subgraph) | No |
-| USDT | falls back to 0 — pass `gasFeeAmount` explicitly | Yes (use `quoteOperatorFeeUsdt`) |
+| PT | `quoteOperatorFeePt` (Chainlink + V3 subgraph) | `gasFeeAmountOutput: bigint` |
+| USDT | `quoteOperatorFeeUsdt` (Chainlink only) | `gasFeeAmountOutput: bigint` |
+
+```ts
+// USDT-output swap (e.g. PT → USDT cashout)
+const swap = await trading.handleSwap(user, {
+  // ...
+  inputTokenAddress: PT,
+  outputTokenAddress: USDT,
+  // gasFeeAmountOutput auto-quotes ~$0.008 USDT
+});
+
+// Or override:
+const swap = await trading.handleSwap(user, {
+  // ...
+  gasFeeAmountOutput: 10_000n,  // 0.01 USDT explicit
+});
+```
 
 ---
 
@@ -125,7 +143,7 @@ const [poolsA, poolsB] = await Promise.all([
 ]);
 const pools = [...poolsA, ...poolsB];
 
-const swap = await trading.handleSwap({
+const swap = await trading.handleSwap(user, {
   chainId: 8453,
   userAddress,
   inputTokenAddress: POINT_TOKEN_0,
@@ -138,9 +156,14 @@ const swap = await trading.handleSwap({
 console.log(swap.hops);  // 2 — went through USDT
 ```
 
-V4 router auto-picks the best route across `pools + COMMON_POOLS`
+V3 router auto-picks the best route across `pools + COMMON_POOLS`
 (default `maxHops=3`). Slippage auto-bumps to 100 bps for multi-hop.
 
+Verify via subgraph that both PTs have indexed pools with USDT:
+```graphql
+{ pafiTokens { id pool { token0 { id symbol } token1 { id symbol } } } }
+```
+
 ---
 
 ## Perp deposit
@@ -149,9 +172,9 @@ V4 router auto-picks the best route across `pools + COMMON_POOLS`
 const deposit = await trading.handlePerpDeposit({
   chainId: 8453,
   userAddress,
-  amount: 1_000_000n,     // 1 USDC (6 dec)
+  amount: 1_000_000n,           // 1 USDC (6 dec)
   aaNonce,
-  brokerId: "orderly",    // "orderly" | "woofi_pro" | "logx"
+  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
 });
@@ -168,17 +191,26 @@ native ETH.
 
 ## Standalone primitives
 
-For callers that want to compose flows beyond what `TradingHandlers`
-provides:
+For callers that want to compose flows beyond `TradingHandlers`:
 
 ```ts
 import {
   buildSwapUserOp,
+  buildSwapUserOpExactOut,
   findBestQuote,
+  findBestQuoteExactOut,
   simulateSwap,
   buildUniversalRouterExecuteArgs,
+  buildUniversalRouterExecuteArgsExactOut,
+  buildV3SwapInputExactIn,
+  buildV3SwapInputExactOut,
+  buildSwapFromQuote,
   buildPermit2ApprovalCalldata,
+  buildErc20ApprovalCalldata,
+  checkAllowance,
   fetchPafiPools,
+  V3_SWAP_EXACT_IN,
+  V3_SWAP_EXACT_OUT,
 } from "@pafi-dev/trading";
 ```
 
@@ -189,7 +221,7 @@ simulations.
 
 ## Direct path — no AA, no bundler, no sponsor-relayer
 
-`v0.4.0+` ships `swapDirect()` + `perpDepositDirect()` for the FE-only
+Trading ships `swapDirect()` + `perpDepositDirect()` for the FE-only
 flow where the user pays gas in ETH and broadcasts a single type-2 tx
 calling its own EIP-7702 delegated bytecode. No Pimlico API key, no
 sponsor-relayer, no PAFI infra.
@@ -206,7 +238,6 @@ import { createPublicClient, createWalletClient, custom, http, parseUnits } from
 import { base } from "viem/chains";
 
 const publicClient = createPublicClient({ chain: base, transport: http() });
-// `walletClient` from Privy embedded wallet, MetaMask, etc.
 const walletClient = createWalletClient({
   account: wallet.address,
   chain: base,
@@ -227,7 +258,6 @@ const result = await swapDirect({
   // optional: slippageBps, deadline, gasFeeAmountOutput, waitForReceipt
 });
 
-console.log("Swap tx:", result.txHash);
 // {
 //   txHash, receipt?, estimatedOutputAmount, minAmountOut, hops,
 //   deadline, feeAmountUsed
@@ -260,8 +290,8 @@ const result = await perpDepositDirect({
 ```
 
 The Relay still charges its own USDC fee (`Relay.quoteTokenFee`) to
-cover LayerZero `msg.value`; that's separate from PAFI's operator fee
-(which is skipped by default on the direct path).
+cover LayerZero `msg.value`; separate from PAFI's operator fee
+(skipped by default on direct path).
 
 ### When to use direct vs. AA path
 
@@ -280,6 +310,30 @@ the production gas-free UX via sponsor-relayer.
 
 ---
 
+## Plain Swap (Permit2 sig — FE only, no AA)
+
+For external wallets (MetaMask) that can't EIP-7702 delegate. Standard
+Uniswap pattern: ERC-20 approve to PERMIT2, off-chain PermitSingle sig,
+`UR.execute([PERMIT2_PERMIT, V3_SWAP_EXACT_IN], ...)`.
+
+```ts
+// Step 1: one-time ERC-20 approve to Permit2 (skip if allowance set)
+// Step 2: sign Permit2 PermitSingle EIP-712 (skip if sub-allowance valid)
+// Step 3: send UR.execute tx — user pays gas in ETH
+
+// See privy-pimlico-eip7702-example/app/components/WalletPanel.tsx
+// handleSwapPlain for the full flow.
+```
+
+**Cold start**: 1 tx + 1 sig + 1 tx (3 popups).
+**Warm** (sub-allowance fresh): 1 tx.
+
+> ⚠️ Common bug: `permitExpiration = (1 << 48) - 1` overflows to
+> `65535` in JS (int32 shift). Use `2 ** 48 - 1` or BigInt for
+> uint48 timestamps.
+
+---
+
 ## API reference
 
 ### `TradingHandlers`
@@ -292,25 +346,32 @@ Methods:
 
 | 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 |
+| `handleQuote({ inputTokenAddress, outputTokenAddress, amount, pools? })` | V3 exact-input quote. Returns `{ inputAmount, estimatedOutputAmount, gasEstimate, quoteError? }` |
+| `handleQuoteExactOut({ ... })` | V3 exact-output quote |
+| `handleSwap(authedAddr, { userAddress, inputTokenAddress, outputTokenAddress, amount, aaNonce, pools?, gasFeeAmountOutput?, slippageBps? })` | Build UserOp. Returns `{ userOp, userOpFallback?, estimatedOutputAmount, minAmountOut, hops, deadline, feeAmountUsed, feeRecipient }` |
+| `handleSwapExactOut(authedAddr, { ... })` | Build exact-output swap UserOp |
+| `handlePerpDeposit({ userAddress, amount, aaNonce, brokerId, viaRelay?, maxRelayFee?, pointTokenAddress?, gasFeePt? })` | Build perp deposit UserOp |
 
 ### Free functions
 
 - `findBestQuote(client, chainId, tokenIn, tokenOut, amount, pools, quoterAddress?, maxHops?)`
-- `quoteBestRoute`, `quoteExactInput`, `quoteExactInputSingle`
-- `buildAllPaths`, `combineRoutes`
-- `buildSwapUserOp(params)` — direction-agnostic UserOp builder
-- `buildUniversalRouterExecuteArgs`, `buildV4SwapInput`, `buildSwapFromQuote`
+- `findBestQuoteExactOut(...)`
+- `quoteBestRoute`, `quoteBestRouteExactOut`, `quoteExactInput`, `quoteExactInputSingle`, `quoteExactOutput`, `quoteExactOutputSingle`
+- `buildSwapUserOp(params)` / `buildSwapUserOpExactOut(params)` — direction-agnostic UserOp builder
+- `buildUniversalRouterExecuteArgs`, `buildUniversalRouterExecuteArgsExactOut`, `buildV3SwapInputExactIn`, `buildV3SwapInputExactOut`, `buildSwapFromQuote`
 - `buildPermit2ApprovalCalldata`, `buildErc20ApprovalCalldata`, `checkAllowance`
 - `simulateSwap` — `eth_call` dry-run
-- `fetchPafiPools(chainId, pointTokenAddress, subgraphUrl?)`
-- `swapDirect(params)` — FE-direct swap (no AA, user pays gas) — see "Direct path" section
-- `perpDepositDirect(params)` — FE-direct perp deposit (no AA, user pays gas)
+- `fetchPafiPools(chainId, pointTokenAddress, subgraphUrl?)` — re-exported from core
+- `swapDirect(params)`, `perpDepositDirect(params)` — FE-direct flows
+- `V3_SWAP_EXACT_IN`, `V3_SWAP_EXACT_OUT` — Universal Router V3 command constants
 
 ---
 
+## References
+
+- Fee math: [`docs/FEE_FLOW.md`](../../../docs/FEE_FLOW.md)
+- Architecture: [`ARCHITECTURE.md`](../../ARCHITECTURE.md) at SDK root
+
 ## License
 
 Apache-2.0