@pafi-dev/trading 0.1.10 → 0.2.1

package/dist/index.d.ts

@@ -1,85 +1,82 @@
-import { Address, PublicClient } from 'viem';
-import { PartialUserOperation, PoolKey } from '@pafi-dev/core';
+import { Address, PublicClient, Hex } from 'viem';
+import { PartialUserOperation, PoolKey, QuoteResult, PathKey, BestQuote } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL, fetchPafiPools } from '@pafi-dev/core';
 
 interface ApiQuoteRequest {
     chainId: number;
-    pointTokenAddress: Address;
-    /** PT amount (18-decimal raw units). */
+    /** Token user is spending. */
+    inputTokenAddress: Address;
+    /** Token user wants to receive. */
+    outputTokenAddress: Address;
+    /** Input token amount (raw decimals — input token's native scale). */
     amount: bigint;
     /**
-     * PT/USDT pools to include in routing. Combined with COMMON_POOLS
-     * from `@pafi-dev/core`. Pass empty array to use only COMMON_POOLS.
+     * Pools to include in routing. Combined with COMMON_POOLS. When
+     * either side is a PT, the caller should fetch pools for ALL PTs
+     * involved (single PT → USDT → PT' multi-hop) and merge before
+     * passing here.
      */
     pools?: PoolKey[];
 }
 type ApiQuoteError = "QUOTE_UNAVAILABLE" | "AMOUNT_TOO_SMALL_FOR_GAS";
 interface ApiQuoteResponse {
-    pointAmount: bigint;
-    estimatedUsdtOut: bigint;
+    /** Echoes `request.amount` for FE bookkeeping. */
+    inputAmount: bigint;
+    /** Quoted output amount before slippage. 0n when `quoteError` set. */
+    estimatedOutputAmount: bigint;
+    /** V4 Quoter's gas estimate for the route. */
     gasEstimate: bigint;
     quoteError?: ApiQuoteError;
 }
 interface ApiSwapRequest {
     chainId: number;
     userAddress: Address;
-    pointTokenAddress: Address;
-    /** PT amount to swap (18-decimal raw units). */
+    inputTokenAddress: Address;
+    outputTokenAddress: Address;
+    /** Input token amount to swap (raw token decimals). */
     amount: bigint;
     /** ERC-4337 account nonce for the user's EOA (from EntryPoint). */
     aaNonce: bigint;
-    /** Slippage tolerance in basis points (1 bps = 0.01%). Default: 50 (0.5%). */
+    /**
+     * Slippage tolerance in basis points (1 bps = 0.01%). Default: 50
+     * for single-hop, 100 for multi-hop (handler picks based on
+     * `bestRoute.path.length`).
+     */
     slippageBps?: number;
-    /** PT/USDT pools. Combined with COMMON_POOLS. Pass empty to use only COMMON_POOLS. */
+    /** Pools to consider. Caller pre-fetches per-PT pools and merges. */
     pools?: PoolKey[];
     /**
-     * PT operator fee (paid to PAFI fee recipient as reimbursement for
-     * sponsoring ERC-4337 gas).
+     * Operator fee in INPUT token units, paid to PAFI fee recipient as
+     * reimbursement for sponsoring ERC-4337 gas.
      *
-     * - `undefined` (default): handler auto-quotes via Chainlink + V4
-     *   subgraph using `quoteOperatorFeePt` from `@pafi-dev/core`.
-     *   Recommended for normal usage — caller doesn't need to know the
-     *   fee policy or pre-fetch oracle data.
-     * - `0n`: strip the `PT.transfer(pafiFeeRecipient, ...)` call (used
-     *   for the unsponsored fallback path — user pays ETH gas
-     *   themselves so there's nothing to reimburse).
-     * - explicit `bigint`: override for issuer markup / subsidy
-     *   scenarios. Sponsor-relayer's `FeeValidator` enforces a 5%
-     *   tolerance vs its own quote — too low → `INSUFFICIENT_FEE`.
+     * - `undefined` (default): handler auto-quotes via
+     *   `quoteOperatorFeeInputToken` (Chainlink USD/ETH + token oracle).
+     * - `0n`: strip the fee transfer (unsponsored fallback path).
+     * - explicit `bigint`: override for issuer markup/subsidy scenarios.
      */
-    gasFeePt?: bigint;
+    gasFeeAmount?: bigint;
 }
 interface ApiSwapResponse {
-    /** Unsigned UserOp — attach paymaster data + user signature, then submit to Bundler. */
+    /** Unsigned UserOp — attach paymaster + user signature, submit to Bundler. */
     userOp: PartialUserOperation;
     /**
-     * Fee-stripped fallback variant. Emitted only when `gasFeePt > 0n` —
-     * otherwise it would equal `userOp` exactly and we omit it to avoid
-     * encouraging callers to redundantly resubmit.
-     *
-     * Submit this when the paymaster refuses sponsorship (the user pays
-     * ERC-4337 gas in ETH directly): there's no point charging the
-     * operator fee in PT for sponsorship that didn't happen. Pair with
-     * `sendWithPaymasterFallback({ txParams, txParamsFallback })`.
+     * Fee-stripped fallback variant. Emitted only when `gasFeeAmount > 0`.
+     * Submit when the paymaster refuses sponsorship (user pays ETH gas).
      */
     userOpFallback?: PartialUserOperation;
-    /** Raw USDT out before slippage (6 decimals). For display. */
-    estimatedUsdtOut: bigint;
-    /** Minimum USDT accepted — encoded in the UserOp calldata. */
+    /** Raw output amount before slippage. For display. */
+    estimatedOutputAmount: bigint;
+    /** Minimum output accepted — encoded in the UserOp calldata. */
     minAmountOut: bigint;
+    /** Number of hops in the chosen route. Used by FE to display "PT → USDT → PT1" etc. */
+    hops: number;
     /** Swap deadline (unix seconds). Re-request if user doesn't submit in time. */
     deadline: bigint;
     /**
-     * Actual PT fee amount the handler embedded in the sponsored
-     * UserOp. Echoes the auto-quote result (or the explicit override).
-     * `0n` when the caller forced no-fee mode.
+     * Operator fee amount embedded — echoes auto-quote result or override.
+     * Denominated in the INPUT token. `0n` when caller forced no-fee mode.
      */
     feeAmountUsed: bigint;
-    /**
-     * Recipient address used for the PT fee transfer (always
-     * `getContractAddresses(chainId).pafiFeeRecipient`). Echoed for
-     * client-side verification before signing.
-     */
     feeRecipient: Address;
 }
 interface ApiPerpDepositRequest {
@@ -256,4 +253,230 @@ declare class TradingHandlers {
     handlePerpDeposit(request: ApiPerpDepositRequest): Promise<ApiPerpDepositResponse>;
 }
 
-export { type ApiPerpDepositRequest, type ApiPerpDepositResponse, type ApiQuoteError, type ApiQuoteRequest, type ApiQuoteResponse, type ApiSwapRequest, type ApiSwapResponse, TradingHandlers, type TradingHandlersConfig };
+declare function checkAllowance(client: PublicClient, token: Address, owner: Address, spender: Address): Promise<bigint>;
+/**
+ * Encode an ERC-20 approve(spender, amount) call.
+ */
+declare function buildErc20ApprovalCalldata(spender: Address, amount: bigint): Hex;
+/**
+ * Encode a Permit2 approve(token, spender, amount, expiration) call.
+ */
+declare function buildPermit2ApprovalCalldata(token: Address, spender: Address, amount: bigint, expiration: number): Hex;
+
+/**
+ * Build the calldata inputs[0] (the V4_SWAP command payload) for
+ * UniversalRouter.execute.
+ *
+ * Actions encoded: SWAP_EXACT_IN → SETTLE_ALL → TAKE_ALL
+ *
+ * Encoding matches the Uniswap V4 SDK's V4Planner — each action's params
+ * are individually ABI-encoded, then wrapped together with the action bytes.
+ */
+declare function buildV4SwapInput(currencyIn: Address, path: PathKey[], amountIn: bigint, minAmountOut: bigint, outputCurrency: Address): Hex;
+/**
+ * Build the full commands + inputs args for UniversalRouter.execute.
+ */
+declare function buildUniversalRouterExecuteArgs(currencyIn: Address, path: PathKey[], amountIn: bigint, minAmountOut: bigint, outputCurrency: Address): {
+    commands: Hex;
+    inputs: Hex[];
+};
+/**
+ * Build UniversalRouter execute args from a quote result.
+ *
+ * Takes the output of `findBestQuote` / `quoteBestRoute` and produces
+ * ready-to-use `{ commands, inputs }` for `UniversalRouter.execute`.
+ *
+ * @param quote        - Quote result containing the path
+ * @param currencyIn   - Input token address
+ * @param currencyOut  - Output token address
+ * @param amountIn     - Exact input amount (same value passed to the quoter)
+ * @param minAmountOut - Minimum acceptable output (caller applies slippage)
+ *
+ * @deprecated Since v1.4 — the Issuer App no longer handles swaps.
+ * For the new PT→USDT batch call on PAFI Web (Scenario 4 with
+ * EIP-7702 gas deduction), use `buildSwapWithGasDeduction()` (v1.5).
+ * This helper is kept for legacy v0.2.x consumers; will be removed in v2.0.
+ */
+declare function buildSwapFromQuote(params: {
+    quote: QuoteResult;
+    currencyIn: Address;
+    currencyOut: Address;
+    amountIn: bigint;
+    minAmountOut: bigint;
+}): {
+    commands: Hex;
+    inputs: Hex[];
+};
+
+interface SwapSimulationResult {
+    success: boolean;
+    gasEstimate: bigint;
+}
+/**
+ * Simulate a UniversalRouter.execute swap call via eth_call (no gas spent).
+ *
+ * Runs the full V4 swap flow — token transfer via Permit2, swap via
+ * PoolManager, output settlement — without submitting a transaction.
+ * If the simulation reverts, throws a `SimulationError` with the reason.
+ *
+ * @param client        - viem PublicClient
+ * @param routerAddress - UniversalRouter contract address
+ * @param commands      - Packed command bytes (from buildSwapFromQuote)
+ * @param inputs        - Encoded inputs per command (from buildSwapFromQuote)
+ * @param deadline      - Unix timestamp after which the tx expires
+ * @param from          - Address that will execute the swap
+ */
+declare function simulateSwap(client: PublicClient, routerAddress: Address, commands: Hex, inputs: Hex[], deadline: bigint, from: Address): Promise<SwapSimulationResult>;
+
+/**
+ * v1.6 — Generalized swap UserOp builder. Direction-agnostic: works
+ * for **any** ERC-20 → ERC-20 pair routable through PAFI's V4 pools:
+ *
+ *   - PT → USDT      (cashout)
+ *   - USDT → PT      (buy PT with USDT)
+ *   - PT0 → PT1      (same-issuer multi-token swap; routes via USDT)
+ *
+ * UserOp shape (atomic batch via EIP-7702 BatchExecutor):
+ *
+ *   1. `inputToken.approve(Permit2, amountIn + gasFeeAmount)` — single
+ *      approve covers both swap input + operator gas reimbursement.
+ *   2. `Permit2.approve(inputToken, router, amountIn, deadline)` — Permit2
+ *      authorization to UniversalRouter.
+ *   3. `UniversalRouter.execute(commands, inputs, deadline)` — V4 swap
+ *      `inputToken → outputToken`; user receives ≥ `minAmountOut`.
+ *   4. `inputToken.transfer(feeRecipient, gasFeeAmount)` — operator
+ *      gas reimbursement, paid in INPUT token (omitted when 0).
+ *
+ * ## Fee model — input-token strategy
+ *
+ * Operator gas fee is charged in the **input token** (option (a) chosen
+ * 2026-04-27). Generic across directions; user only needs to hold a
+ * single token in sufficient quantity.
+ *
+ * User must hold `amountIn + gasFeeAmount` of `inputTokenAddress`.
+ *
+ * ## PAFI Hook fee
+ *
+ * The V4 PAFIHook charges 10% on PT → USDT direction (one-way). The
+ * 10% is taken at pool level inside `UniversalRouter.execute`, so this
+ * builder doesn't model it explicitly — it shows up as a smaller
+ * `amountOut` from `findBestQuote`.
+ *
+ *   - PT → USDT:   pool charges 10%  (output reduced)
+ *   - USDT → PT:   no hook fee
+ *   - PT0 → PT1:   10% on PT0 → USDT leg, 0% on USDT → PT1 leg
+ *
+ * ## Order of operations
+ *
+ * Fee transfer is LAST so a reverting swap also refunds the fee
+ * (atomic batch revert semantics).
+ */
+interface BuildSwapUserOpParams {
+    /** User's EOA (with EIP-7702 delegation to BatchExecutor). */
+    userAddress: Address;
+    /** ERC-4337 account nonce — fetched from EntryPoint by the caller. */
+    aaNonce: bigint;
+    /** Token being spent — approved to Permit2 + UniversalRouter. */
+    inputTokenAddress: Address;
+    /** Token user receives. */
+    outputTokenAddress: Address;
+    /** UniversalRouter contract address (chain-specific). */
+    universalRouterAddress: Address;
+    /** Input token units to swap. User's balance must be ≥ `amountIn + gasFeeAmount`. */
+    amountIn: bigint;
+    /**
+     * Minimum output to accept. Caller applies slippage (typically
+     * 50-100 bps; multi-hop routes should bias higher) against a fresh
+     * quote. Sub-minimum swap reverts.
+     */
+    minAmountOut: bigint;
+    /**
+     * V4 pool path for the swap. Single-hop = 1 PathKey, multi-hop = N.
+     * Get this from `findBestQuote().bestRoute.path`.
+     */
+    swapPath: PathKey[];
+    /** Unix seconds. After this, the router rejects the swap. */
+    deadline: bigint;
+    /**
+     * Operator gas-reimbursement fee — paid in INPUT token. Omitted from
+     * the batch when 0n. Caller is responsible for quoting this in input
+     * token units (typically USDT-denominated then converted via
+     * `quoteOperatorFee`).
+     */
+    gasFeeAmount: bigint;
+    /**
+     * Where the gas fee lands — typically the canonical PAFI fee
+     * recipient from `getContractAddresses(chainId).pafiFeeRecipient`.
+     */
+    feeRecipient: Address;
+    /** Override ERC-4337 gas estimates. Defaults are conservative. */
+    gasLimits?: {
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
+    };
+}
+/**
+ * Build an unsigned UserOp for the generalized swap flow.
+ *
+ * @throws when `amountIn` is non-positive, `gasFeeAmount` is negative,
+ *   or `swapPath` is empty.
+ */
+declare function buildSwapUserOp(params: BuildSwapUserOpParams): PartialUserOperation;
+
+/**
+ * Combine point-token-specific pools and common pools for a given chain.
+ * Point token pools are listed first so callers can prioritise them.
+ */
+declare function combineRoutes(chainId: number, pointTokenAddress: Address): PoolKey[];
+/**
+ * Build all possible swap paths from `tokenIn` to `tokenOut` using the given
+ * pools. Returns an array of PathKey[] routes (each up to `maxHops` hops).
+ *
+ * Supports both direct single-hop routes and multi-hop routes through
+ * intermediate tokens. Each pool is used at most once per path.
+ *
+ * @param pools    - Available pools to route through
+ * @param tokenIn  - Input token address
+ * @param tokenOut - Desired output token address
+ * @param maxHops  - Maximum number of hops (default 3)
+ */
+declare function buildAllPaths(pools: PoolKey[], tokenIn: Address, tokenOut: Address, maxHops?: number): PathKey[][];
+
+/**
+ * Quote exact-input for a multi-hop path.
+ */
+declare function quoteExactInput(client: PublicClient, quoterAddress: Address, exactCurrency: Address, path: PathKey[], exactAmount: bigint): Promise<QuoteResult>;
+/**
+ * Quote exact-input for a single-hop swap, given an explicit PoolKey and direction.
+ */
+declare function quoteExactInputSingle(client: PublicClient, quoterAddress: Address, poolKey: PoolKey, zeroForOne: boolean, exactAmount: bigint, hookData: `0x${string}`): Promise<{
+    amountOut: bigint;
+    gasEstimate: bigint;
+}>;
+/**
+ * Try multiple PathKey[] routes and return the best quote plus all results.
+ * Routes that fail (e.g. pool does not exist) are silently skipped.
+ *
+ * Uses viem multicall to batch all quotes into a single RPC call for speed.
+ */
+declare function quoteBestRoute(client: PublicClient, quoterAddress: Address, exactCurrency: Address, routes: PathKey[][], exactAmount: bigint): Promise<BestQuote>;
+/**
+ * Find and quote the best swap route from `tokenIn` to `tokenOut`.
+ *
+ * Combines the caller's `pools` with `COMMON_POOLS[chainId]`, builds all
+ * possible paths (up to `maxHops`), then quotes them all via a single
+ * multicall and returns the best result.
+ *
+ * @param client         - viem PublicClient
+ * @param chainId        - Chain ID (used to look up COMMON_POOLS and V4_QUOTER_ADDRESSES)
+ * @param tokenIn        - Input token address
+ * @param tokenOut       - Desired output token address
+ * @param exactAmount    - Exact input amount
+ * @param pools          - Additional pools to consider (e.g. point-token-specific)
+ * @param quoterAddress  - Override the default V4 Quoter address for this chain
+ * @param maxHops        - Maximum number of hops per path (default 3)
+ */
+declare function findBestQuote(client: PublicClient, chainId: number, tokenIn: Address, tokenOut: Address, exactAmount: bigint, pools?: PoolKey[], quoterAddress?: Address, maxHops?: number): Promise<BestQuote>;
+
+export { type ApiPerpDepositRequest, type ApiPerpDepositResponse, type ApiQuoteError, type ApiQuoteRequest, type ApiQuoteResponse, type ApiSwapRequest, type ApiSwapResponse, type BuildSwapUserOpParams, type SwapSimulationResult, TradingHandlers, type TradingHandlersConfig, buildAllPaths, buildErc20ApprovalCalldata, buildPermit2ApprovalCalldata, buildSwapFromQuote, buildSwapUserOp, buildUniversalRouterExecuteArgs, buildV4SwapInput, checkAllowance, combineRoutes, findBestQuote, quoteBestRoute, quoteExactInput, quoteExactInputSingle, simulateSwap };