@pafi-dev/trading 0.3.3 → 0.4.1

package/README.md

@@ -187,6 +187,99 @@ simulations.
 
 ---
 
+## Direct path — no AA, no bundler, no sponsor-relayer
+
+`v0.4.0+` 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.
+
+**Precondition:** user EOA must already be EIP-7702 delegated (run
+`delegateDirect()` from `@pafi-dev/core` first; both helpers throw a
+clear error otherwise).
+
+### `swapDirect`
+
+```ts
+import { swapDirect, fetchPafiPools } from "@pafi-dev/trading";
+import { createPublicClient, createWalletClient, custom, http, parseUnits } from "viem";
+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,
+  transport: custom(await wallet.getEthereumProvider()),
+});
+
+const pools = await fetchPafiPools(8453, POINT_TOKEN);
+
+const result = await swapDirect({
+  userAddress: wallet.address,
+  chainId: 8453,
+  inputTokenAddress: POINT_TOKEN,
+  outputTokenAddress: USDT,
+  amount: parseUnits("100", 18),
+  pools,
+  publicClient,
+  walletClient,
+  // optional: slippageBps, deadline, gasFeeAmountOutput, waitForReceipt
+});
+
+console.log("Swap tx:", result.txHash);
+// {
+//   txHash, receipt?, estimatedOutputAmount, minAmountOut, hops,
+//   deadline, feeAmountUsed
+// }
+```
+
+**Operator fee:** default `0n` (skip — PAFI not sponsoring this swap).
+Pass an explicit `gasFeeAmountOutput: bigint` only if you want to mirror
+the sponsored flow's fee transfer.
+
+### `perpDepositDirect`
+
+```ts
+import { perpDepositDirect } from "@pafi-dev/trading";
+
+const result = await perpDepositDirect({
+  userAddress: wallet.address,
+  chainId: 8453,
+  amount: parseUnits("10", 6), // 10 USDC
+  brokerId: "orderly",         // | "woofi_pro" | "logx"
+  publicClient,
+  walletClient,
+  // optional: maxRelayFee, gasFeeUsdc, waitForReceipt
+});
+
+// {
+//   txHash, receipt?, relayTokenFee, maxFee, netDeposit,
+//   feeAmountUsed, accountId, brokerHash, usdcAddress, relayAddress
+// }
+```
+
+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).
+
+### When to use direct vs. AA path
+
+| Aspect | `swapDirect` / `perpDepositDirect` | `TradingHandlers.handleSwap` / `handlePerpDeposit` |
+| --- | --- | --- |
+| User pays gas | ETH (native) | Free (sponsor) or ETH (fallback) |
+| Bundler required | No | Yes (Pimlico) |
+| Sponsor-relayer required | No | Yes (sponsored path) |
+| Operator fee charged | Default skip | Default included |
+| Round trips | 1 (broadcast tx) | 2+ (paymaster + bundler) |
+| Precondition | EIP-7702 delegated | Same |
+
+Use direct for FE dev/test, integrations without a Pimlico key, or
+production paths where users explicitly opt to pay gas. Use AA path for
+the production gas-free UX via sponsor-relayer.
+
+---
+
 ## API reference
 
 ### `TradingHandlers`
@@ -213,6 +306,8 @@ Methods:
 - `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)
 
 ---