@pafi-dev/trading 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -22,8 +22,26 @@ type ApiQuoteError = "QUOTE_UNAVAILABLE" | "AMOUNT_TOO_SMALL_FOR_GAS";
 interface ApiQuoteResponse {
     /** Echoes `request.amount` for FE bookkeeping. */
     inputAmount: bigint;
-    /** Quoted output amount before slippage. 0n when `quoteError` set. */
+    /**
+     * Gross output from the V4 quoter — before operator fee deduction.
+     * Use for "you swap X for ~Y" UI; do not promise this number to user.
+     * 0n when `quoteError` set.
+     */
     estimatedOutputAmount: bigint;
+    /**
+     * Net output after the operator fee transfer is subtracted from the
+     * gross. This is what the user actually receives in their wallet.
+     * `outputNet = estimatedOutputAmount - feeAmountOutput`.
+     *
+     * v0.3 — added when fee model switched to output-side. Display this
+     * to the user; the on-chain post-swap fee transfer enforces it.
+     */
+    outputNet: bigint;
+    /**
+     * Operator gas fee deducted from the swap output, in OUTPUT token
+     * raw units. 0n on the fallback path or when handler couldn't quote.
+     */
+    feeAmountOutput: bigint;
     /** V4 Quoter's gas estimate for the route. */
     gasEstimate: bigint;
     quoteError?: ApiQuoteError;
@@ -46,15 +64,19 @@ interface ApiSwapRequest {
     /** Pools to consider. Caller pre-fetches per-PT pools and merges. */
     pools?: PoolKey[];
     /**
-     * Operator fee in INPUT token units, paid to PAFI fee recipient as
-     * reimbursement for sponsoring ERC-4337 gas.
+     * Operator fee in OUTPUT token units, paid to PAFI fee recipient as
+     * reimbursement for sponsoring ERC-4337 gas. Applied AFTER the swap.
      *
      * - `undefined` (default): handler auto-quotes via
-     *   `quoteOperatorFeeInputToken` (Chainlink USD/ETH + token oracle).
+     *   `quoteOperatorFeeUsdt` when output is USDT, `quoteOperatorFeePt`
+     *   when output is a PT.
      * - `0n`: strip the fee transfer (unsponsored fallback path).
      * - explicit `bigint`: override for issuer markup/subsidy scenarios.
+     *
+     * v0.3 — renamed from `gasFeeAmount` (input-side). See
+     * SDK_ARCHITECTURE.md "Fee positioning rule".
      */
-    gasFeeAmount?: bigint;
+    gasFeeAmountOutput?: bigint;
 }
 interface ApiSwapResponse {
     /** Unsigned UserOp — attach paymaster + user signature, submit to Bundler. */
@@ -74,7 +96,8 @@ interface ApiSwapResponse {
     deadline: bigint;
     /**
      * Operator fee amount embedded — echoes auto-quote result or override.
-     * Denominated in the INPUT token. `0n` when caller forced no-fee mode.
+     * Denominated in the OUTPUT token (v0.3+). `0n` when caller forced
+     * no-fee mode.
      */
     feeAmountUsed: bigint;
     feeRecipient: Address;
@@ -124,22 +147,18 @@ interface ApiPerpDepositRequest {
      */
     maxRelayFee?: bigint;
     /**
-     * Address of the user's PointToken — required when the operator-fee
-     * transfer is included in the batch (every sponsored path). When
-     * omitted, the handler skips the fee transfer entirely; useful for
-     * the unsponsored fallback variant.
-     */
-    pointTokenAddress?: Address;
-    /**
-     * PT operator fee. Same semantics as `ApiSwapRequest.gasFeePt`:
-     * - `undefined` (default): auto-quote via `quoteOperatorFeePt`
-     * - `0n`: strip fee transfer (force unsponsored mode)
-     * - explicit `bigint`: override
+     * USDC operator fee — paid as input-token transfer prepended to the
+     * batch (token-availability rule: user holds USDC before deposit).
      *
-     * `pointTokenAddress` must be set whenever the fee transfer is
-     * actually included (i.e. when fee resolves to > 0).
+     * - `undefined` (default): auto-quote via `quoteOperatorFeeUsdt`
+     *   (USDC = stablecoin 6-dec, same shape).
+     * - `0n`: strip fee transfer (force unsponsored mode).
+     * - explicit `bigint`: override.
+     *
+     * v0.3 — replaced PT-side fee (`gasFeePt` + `pointTokenAddress`).
+     * User now needs only USDC to complete the deposit.
      */
-    gasFeePt?: bigint;
+    gasFeeUsdc?: bigint;
 }
 interface ApiPerpDepositResponse {
     /** Unsigned UserOp — attach paymaster data + user signature, then submit to Bundler. */
@@ -223,13 +242,16 @@ declare class TradingHandlers {
      */
     handleQuote(request: ApiQuoteRequest): Promise<ApiQuoteResponse>;
     /**
-     * Build a PT → USDT swap UserOp.
+     * Build a swap UserOp (direction-agnostic).
      *
      * Quotes the best route, applies slippage, then encodes a 4-step
-     * batch: PT.approve → Permit2.approve → UniversalRouter.execute →
-     * PT.transfer (fee, omitted when gasFeePt = 0). Returns an unsigned
-     * `PartialUserOperation`; caller attaches paymaster data + user
-     * signature and submits to the Bundler.
+     * batch: input.approve → Permit2.approve → UniversalRouter.execute →
+     * output.transfer (fee in OUTPUT token, omitted when fee = 0).
+     *
+     * v0.3 — Fee model is OUTPUT-side (token-availability rule). User
+     * holds exactly `amountIn` of input; receives `outputGross - fee`
+     * net. Quote response surfaces both `estimatedOutputAmount` (gross)
+     * and `outputNet` so the FE can display reality.
      */
     handleSwap(request: ApiSwapRequest): Promise<ApiSwapResponse>;
     /**
@@ -329,7 +351,7 @@ interface SwapSimulationResult {
 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
+ * v0.3 — Generalized swap UserOp builder. Direction-agnostic: works
  * for **any** ERC-20 → ERC-20 pair routable through PAFI's V4 pools:
  *
  *   - PT → USDT      (cashout)
@@ -338,22 +360,27 @@ declare function simulateSwap(client: PublicClient, routerAddress: Address, comm
  *
  * UserOp shape (atomic batch via EIP-7702 BatchExecutor):
  *
- *   1. `inputToken.approve(Permit2, amountIn + gasFeeAmount)` — single
- *      approve covers both swap input + operator gas reimbursement.
+ *   1. `inputToken.approve(Permit2, amountIn)` — exactly the swap amount.
  *   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).
+ *   4. `outputToken.transfer(feeRecipient, gasFeeAmountOutput)` —
+ *      operator gas reimbursement, paid in OUTPUT token (omitted when 0).
  *
- * ## Fee model — input-token strategy
+ * ## Fee model — output-token strategy (token-availability rule)
  *
- * 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.
+ * Fee is charged in the **output token** AFTER the swap, because the
+ * user holds output token at that point in the batch. Three benefits:
  *
- * User must hold `amountIn + gasFeeAmount` of `inputTokenAddress`.
+ *   - User holds exactly `amountIn` of input token (FE quote = chain
+ *     reality). No "you need 1010 to swap 1000" UX surprise.
+ *   - Quote API returns `outputNet = outputGross - feeOutput` directly,
+ *     matching what user actually receives.
+ *   - PT → USDT: PAFI receives USDT (universally liquid, clean accounting).
+ *
+ * Caller MUST ensure `minAmountOut >= gasFeeAmountOutput` (fee transfer
+ * reverts otherwise → whole batch reverts).
  *
  * ## PAFI Hook fee
  *
@@ -365,11 +392,6 @@ declare function simulateSwap(client: PublicClient, routerAddress: Address, comm
  *   - 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). */
@@ -382,12 +404,12 @@ interface BuildSwapUserOpParams {
     outputTokenAddress: Address;
     /** UniversalRouter contract address (chain-specific). */
     universalRouterAddress: Address;
-    /** Input token units to swap. User's balance must be ≥ `amountIn + gasFeeAmount`. */
+    /** Input token units to swap. User must hold exactly this much input token. */
     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.
+     * Minimum output (gross) to accept from the swap. Caller applies
+     * slippage against a fresh quote. MUST be ≥ `gasFeeAmountOutput` or
+     * the post-swap fee transfer reverts.
      */
     minAmountOut: bigint;
     /**
@@ -398,12 +420,14 @@ interface BuildSwapUserOpParams {
     /** 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`).
+     * Operator gas-reimbursement fee — paid in OUTPUT token. Omitted
+     * from the batch when 0n. Caller quotes this via `quoteOperatorFee*`
+     * helpers (USDT/PT depending on output token).
+     *
+     * v0.3 — switched from input-side fee (v0.2 `gasFeeAmount`) to
+     * output-side fee. See "Fee model" comment above.
      */
-    gasFeeAmount: bigint;
+    gasFeeAmountOutput: bigint;
     /**
      * Where the gas fee lands — typically the canonical PAFI fee
      * recipient from `getContractAddresses(chainId).pafiFeeRecipient`.
@@ -419,8 +443,8 @@ interface BuildSwapUserOpParams {
 /**
  * Build an unsigned UserOp for the generalized swap flow.
  *
- * @throws when `amountIn` is non-positive, `gasFeeAmount` is negative,
- *   or `swapPath` is empty.
+ * @throws when `amountIn` is non-positive, `gasFeeAmountOutput` is
+ *   negative, `swapPath` is empty, or `minAmountOut < gasFeeAmountOutput`.
  */
 declare function buildSwapUserOp(params: BuildSwapUserOpParams): PartialUserOperation;
 

package/dist/index.d.ts

@@ -22,8 +22,26 @@ type ApiQuoteError = "QUOTE_UNAVAILABLE" | "AMOUNT_TOO_SMALL_FOR_GAS";
 interface ApiQuoteResponse {
     /** Echoes `request.amount` for FE bookkeeping. */
     inputAmount: bigint;
-    /** Quoted output amount before slippage. 0n when `quoteError` set. */
+    /**
+     * Gross output from the V4 quoter — before operator fee deduction.
+     * Use for "you swap X for ~Y" UI; do not promise this number to user.
+     * 0n when `quoteError` set.
+     */
     estimatedOutputAmount: bigint;
+    /**
+     * Net output after the operator fee transfer is subtracted from the
+     * gross. This is what the user actually receives in their wallet.
+     * `outputNet = estimatedOutputAmount - feeAmountOutput`.
+     *
+     * v0.3 — added when fee model switched to output-side. Display this
+     * to the user; the on-chain post-swap fee transfer enforces it.
+     */
+    outputNet: bigint;
+    /**
+     * Operator gas fee deducted from the swap output, in OUTPUT token
+     * raw units. 0n on the fallback path or when handler couldn't quote.
+     */
+    feeAmountOutput: bigint;
     /** V4 Quoter's gas estimate for the route. */
     gasEstimate: bigint;
     quoteError?: ApiQuoteError;
@@ -46,15 +64,19 @@ interface ApiSwapRequest {
     /** Pools to consider. Caller pre-fetches per-PT pools and merges. */
     pools?: PoolKey[];
     /**
-     * Operator fee in INPUT token units, paid to PAFI fee recipient as
-     * reimbursement for sponsoring ERC-4337 gas.
+     * Operator fee in OUTPUT token units, paid to PAFI fee recipient as
+     * reimbursement for sponsoring ERC-4337 gas. Applied AFTER the swap.
      *
      * - `undefined` (default): handler auto-quotes via
-     *   `quoteOperatorFeeInputToken` (Chainlink USD/ETH + token oracle).
+     *   `quoteOperatorFeeUsdt` when output is USDT, `quoteOperatorFeePt`
+     *   when output is a PT.
      * - `0n`: strip the fee transfer (unsponsored fallback path).
      * - explicit `bigint`: override for issuer markup/subsidy scenarios.
+     *
+     * v0.3 — renamed from `gasFeeAmount` (input-side). See
+     * SDK_ARCHITECTURE.md "Fee positioning rule".
      */
-    gasFeeAmount?: bigint;
+    gasFeeAmountOutput?: bigint;
 }
 interface ApiSwapResponse {
     /** Unsigned UserOp — attach paymaster + user signature, submit to Bundler. */
@@ -74,7 +96,8 @@ interface ApiSwapResponse {
     deadline: bigint;
     /**
      * Operator fee amount embedded — echoes auto-quote result or override.
-     * Denominated in the INPUT token. `0n` when caller forced no-fee mode.
+     * Denominated in the OUTPUT token (v0.3+). `0n` when caller forced
+     * no-fee mode.
      */
     feeAmountUsed: bigint;
     feeRecipient: Address;
@@ -124,22 +147,18 @@ interface ApiPerpDepositRequest {
      */
     maxRelayFee?: bigint;
     /**
-     * Address of the user's PointToken — required when the operator-fee
-     * transfer is included in the batch (every sponsored path). When
-     * omitted, the handler skips the fee transfer entirely; useful for
-     * the unsponsored fallback variant.
-     */
-    pointTokenAddress?: Address;
-    /**
-     * PT operator fee. Same semantics as `ApiSwapRequest.gasFeePt`:
-     * - `undefined` (default): auto-quote via `quoteOperatorFeePt`
-     * - `0n`: strip fee transfer (force unsponsored mode)
-     * - explicit `bigint`: override
+     * USDC operator fee — paid as input-token transfer prepended to the
+     * batch (token-availability rule: user holds USDC before deposit).
      *
-     * `pointTokenAddress` must be set whenever the fee transfer is
-     * actually included (i.e. when fee resolves to > 0).
+     * - `undefined` (default): auto-quote via `quoteOperatorFeeUsdt`
+     *   (USDC = stablecoin 6-dec, same shape).
+     * - `0n`: strip fee transfer (force unsponsored mode).
+     * - explicit `bigint`: override.
+     *
+     * v0.3 — replaced PT-side fee (`gasFeePt` + `pointTokenAddress`).
+     * User now needs only USDC to complete the deposit.
      */
-    gasFeePt?: bigint;
+    gasFeeUsdc?: bigint;
 }
 interface ApiPerpDepositResponse {
     /** Unsigned UserOp — attach paymaster data + user signature, then submit to Bundler. */
@@ -223,13 +242,16 @@ declare class TradingHandlers {
      */
     handleQuote(request: ApiQuoteRequest): Promise<ApiQuoteResponse>;
     /**
-     * Build a PT → USDT swap UserOp.
+     * Build a swap UserOp (direction-agnostic).
      *
      * Quotes the best route, applies slippage, then encodes a 4-step
-     * batch: PT.approve → Permit2.approve → UniversalRouter.execute →
-     * PT.transfer (fee, omitted when gasFeePt = 0). Returns an unsigned
-     * `PartialUserOperation`; caller attaches paymaster data + user
-     * signature and submits to the Bundler.
+     * batch: input.approve → Permit2.approve → UniversalRouter.execute →
+     * output.transfer (fee in OUTPUT token, omitted when fee = 0).
+     *
+     * v0.3 — Fee model is OUTPUT-side (token-availability rule). User
+     * holds exactly `amountIn` of input; receives `outputGross - fee`
+     * net. Quote response surfaces both `estimatedOutputAmount` (gross)
+     * and `outputNet` so the FE can display reality.
      */
     handleSwap(request: ApiSwapRequest): Promise<ApiSwapResponse>;
     /**
@@ -329,7 +351,7 @@ interface SwapSimulationResult {
 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
+ * v0.3 — Generalized swap UserOp builder. Direction-agnostic: works
  * for **any** ERC-20 → ERC-20 pair routable through PAFI's V4 pools:
  *
  *   - PT → USDT      (cashout)
@@ -338,22 +360,27 @@ declare function simulateSwap(client: PublicClient, routerAddress: Address, comm
  *
  * UserOp shape (atomic batch via EIP-7702 BatchExecutor):
  *
- *   1. `inputToken.approve(Permit2, amountIn + gasFeeAmount)` — single
- *      approve covers both swap input + operator gas reimbursement.
+ *   1. `inputToken.approve(Permit2, amountIn)` — exactly the swap amount.
  *   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).
+ *   4. `outputToken.transfer(feeRecipient, gasFeeAmountOutput)` —
+ *      operator gas reimbursement, paid in OUTPUT token (omitted when 0).
  *
- * ## Fee model — input-token strategy
+ * ## Fee model — output-token strategy (token-availability rule)
  *
- * 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.
+ * Fee is charged in the **output token** AFTER the swap, because the
+ * user holds output token at that point in the batch. Three benefits:
  *
- * User must hold `amountIn + gasFeeAmount` of `inputTokenAddress`.
+ *   - User holds exactly `amountIn` of input token (FE quote = chain
+ *     reality). No "you need 1010 to swap 1000" UX surprise.
+ *   - Quote API returns `outputNet = outputGross - feeOutput` directly,
+ *     matching what user actually receives.
+ *   - PT → USDT: PAFI receives USDT (universally liquid, clean accounting).
+ *
+ * Caller MUST ensure `minAmountOut >= gasFeeAmountOutput` (fee transfer
+ * reverts otherwise → whole batch reverts).
  *
  * ## PAFI Hook fee
  *
@@ -365,11 +392,6 @@ declare function simulateSwap(client: PublicClient, routerAddress: Address, comm
  *   - 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). */
@@ -382,12 +404,12 @@ interface BuildSwapUserOpParams {
     outputTokenAddress: Address;
     /** UniversalRouter contract address (chain-specific). */
     universalRouterAddress: Address;
-    /** Input token units to swap. User's balance must be ≥ `amountIn + gasFeeAmount`. */
+    /** Input token units to swap. User must hold exactly this much input token. */
     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.
+     * Minimum output (gross) to accept from the swap. Caller applies
+     * slippage against a fresh quote. MUST be ≥ `gasFeeAmountOutput` or
+     * the post-swap fee transfer reverts.
      */
     minAmountOut: bigint;
     /**
@@ -398,12 +420,14 @@ interface BuildSwapUserOpParams {
     /** 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`).
+     * Operator gas-reimbursement fee — paid in OUTPUT token. Omitted
+     * from the batch when 0n. Caller quotes this via `quoteOperatorFee*`
+     * helpers (USDT/PT depending on output token).
+     *
+     * v0.3 — switched from input-side fee (v0.2 `gasFeeAmount`) to
+     * output-side fee. See "Fee model" comment above.
      */
-    gasFeeAmount: bigint;
+    gasFeeAmountOutput: bigint;
     /**
      * Where the gas fee lands — typically the canonical PAFI fee
      * recipient from `getContractAddresses(chainId).pafiFeeRecipient`.
@@ -419,8 +443,8 @@ interface BuildSwapUserOpParams {
 /**
  * Build an unsigned UserOp for the generalized swap flow.
  *
- * @throws when `amountIn` is non-positive, `gasFeeAmount` is negative,
- *   or `swapPath` is empty.
+ * @throws when `amountIn` is non-positive, `gasFeeAmountOutput` is
+ *   negative, `swapPath` is empty, or `minAmountOut < gasFeeAmountOutput`.
  */
 declare function buildSwapUserOp(params: BuildSwapUserOpParams): PartialUserOperation;