@pafi-dev/trading 0.1.0

package/README.md

@@ -0,0 +1,239 @@
+# @pafi-dev/trading
+
+[![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.
+
+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).
+
+---
+
+## Requirements
+
+- Node.js >= 18 (server) or any modern bundler (client)
+- TypeScript >= 5.0
+- `viem` ^2.0.0 and `@pafi-dev/core` ^0.5.0 (peer dependencies)
+
+---
+
+## Installation
+
+```bash
+npm install @pafi-dev/trading @pafi-dev/core viem
+# or
+pnpm add @pafi-dev/trading @pafi-dev/core viem
+```
+
+---
+
+## Quick start
+
+```ts
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { TradingHandlers } from "@pafi-dev/trading";
+
+const provider = createPublicClient({ chain: base, transport: http(RPC_URL) });
+const trading = new TradingHandlers({ provider, chainId: 8453 });
+```
+
+---
+
+## Handlers
+
+### `handleQuote` — GET /quote
+
+Quote exact-input PT → USDT via Uniswap V4 on-chain Quoter. Uses multicall to batch all
+candidate routes into a single RPC call.
+
+```ts
+const quote = await trading.handleQuote({
+  chainId: 8453,
+  pointTokenAddress: "0x7d25E7156E51F865D522fd3ef257a6B5DD41b97e",
+  amount: 1000n * 10n ** 18n,   // 1000 PT
+  pools: poolsFromSubgraph,     // optional — combined with COMMON_POOLS
+});
+
+// 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.
+
+---
+
+### `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).
+
+```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",
+});
+
+// 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)
+```
+
+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
+
+---
+
+### `handlePerpDeposit` — POST /perp-deposit
+
+Quote the LayerZero fee and build an unsigned UserOp that batches:
+`USDC.approve(vault)` → `vault.deposit{value: layerZeroFee}(data)`.
+
+```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"
+});
+
+// deposit.userOp        — unsigned PartialUserOperation
+// deposit.layerZeroFee  — ETH wei — user wallet must hold this as native ETH
+// deposit.accountId     — Orderly account ID for (user, broker) pair
+// deposit.brokerHash    — keccak256(brokerId)
+// deposit.usdcAddress   — USDC resolved from Vault.getAllowedToken()
+```
+
+> **Native ETH constraint:** The paymaster sponsors ERC-4337 gas, but `msg.value` (the
+> LayerZero fee) must come from the user's own native ETH balance. Surface `layerZeroFee`
+> in the UI and warn the user if their ETH is insufficient before submitting.
+
+---
+
+## Wiring into a NestJS controller
+
+```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:
+
+```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 {}
+```
+
+---
+
+## API types
+
+All request/response types are exported for use in frontend SDKs or OpenAPI generation:
+
+```ts
+import type {
+  ApiQuoteRequest,
+  ApiQuoteResponse,
+  ApiQuoteError,
+  ApiSwapRequest,
+  ApiSwapResponse,
+  ApiPerpDepositRequest,
+  ApiPerpDepositResponse,
+} 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()`).
+
+---
+
+## Relationship to other PAFI packages
+
+| 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`.
+
+---
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,220 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TradingHandlers: () => TradingHandlers
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/api/handlers.ts
+var import_viem = require("viem");
+var import_core = require("@pafi-dev/core");
+var TradingHandlers = class {
+  provider;
+  chainId;
+  constructor(config) {
+    this.provider = config.provider;
+    this.chainId = config.chainId;
+  }
+  // =========================================================================
+  // GET /quote
+  // =========================================================================
+  /**
+   * Quote exact-input PT → USDT via Uniswap V4 on-chain Quoter.
+   *
+   * Uses multicall to batch all candidate routes into a single RPC call.
+   * Returns `quoteError: "QUOTE_UNAVAILABLE"` when no pool/path exists
+   * rather than throwing, so callers can show a soft "unavailable" UI
+   * state without 500-ing.
+   */
+  async handleQuote(request) {
+    if (request.chainId !== this.chainId) {
+      throw new Error(`handleQuote: unsupported chainId ${request.chainId}`);
+    }
+    if (request.amount === 0n) {
+      return { pointAmount: 0n, estimatedUsdtOut: 0n, gasEstimate: 0n };
+    }
+    const { usdt } = (0, import_core.getContractAddresses)(request.chainId);
+    const pointTokenAddress = (0, import_viem.getAddress)(request.pointTokenAddress);
+    const pools = request.pools ?? [];
+    try {
+      const best = await (0, import_core.findBestQuote)(
+        this.provider,
+        request.chainId,
+        pointTokenAddress,
+        usdt,
+        request.amount,
+        pools
+      );
+      return {
+        pointAmount: request.amount,
+        estimatedUsdtOut: best.bestRoute.amountOut,
+        gasEstimate: best.bestRoute.gasEstimate
+      };
+    } catch {
+      return {
+        pointAmount: request.amount,
+        estimatedUsdtOut: 0n,
+        gasEstimate: 0n,
+        quoteError: "QUOTE_UNAVAILABLE"
+      };
+    }
+  }
+  // =========================================================================
+  // POST /swap
+  // =========================================================================
+  /**
+   * Build a PT → USDT swap UserOp.
+   *
+   * 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.
+   */
+  async handleSwap(request) {
+    if (request.chainId !== this.chainId) {
+      throw new Error(`handleSwap: unsupported chainId ${request.chainId}`);
+    }
+    if (request.amount <= 0n) {
+      throw new Error("handleSwap: amount must be positive");
+    }
+    const { usdt } = (0, import_core.getContractAddresses)(request.chainId);
+    const universalRouter = import_core.UNIVERSAL_ROUTER_ADDRESSES[request.chainId];
+    if (!universalRouter) {
+      throw new Error(`handleSwap: no UniversalRouter for chainId ${request.chainId}`);
+    }
+    const pointTokenAddress = (0, import_viem.getAddress)(request.pointTokenAddress);
+    const userAddress = (0, import_viem.getAddress)(request.userAddress);
+    const pools = request.pools ?? [];
+    const slippageBps = request.slippageBps ?? 50;
+    const gasFeePt = request.gasFeePt ?? 0n;
+    if (gasFeePt > 0n && !request.feeRecipient) {
+      throw new Error("handleSwap: feeRecipient required when gasFeePt > 0");
+    }
+    let quoteResult;
+    try {
+      quoteResult = await (0, import_core.findBestQuote)(
+        this.provider,
+        request.chainId,
+        pointTokenAddress,
+        usdt,
+        request.amount,
+        pools
+      );
+    } catch {
+      throw new Error("handleSwap: no swap path found for this point token");
+    }
+    const estimatedUsdtOut = quoteResult.bestRoute.amountOut;
+    const minAmountOut = estimatedUsdtOut * BigInt(1e4 - slippageBps) / 10000n;
+    const deadline = BigInt(Math.floor(Date.now() / 1e3) + 5 * 60);
+    const userOp = (0, import_core.buildSwapWithGasDeduction)({
+      userAddress,
+      aaNonce: request.aaNonce,
+      pointTokenAddress,
+      outputTokenAddress: usdt,
+      universalRouterAddress: universalRouter,
+      amountIn: request.amount,
+      minAmountOut,
+      swapPath: quoteResult.bestRoute.path,
+      deadline,
+      gasFeePt,
+      feeRecipient: request.feeRecipient ?? userAddress
+    });
+    return { userOp, estimatedUsdtOut, minAmountOut, deadline };
+  }
+  // =========================================================================
+  // POST /perp-deposit
+  // =========================================================================
+  /**
+   * Build an Orderly perp deposit UserOp.
+   *
+   * Resolves USDC address and LayerZero fee from on-chain Vault reads,
+   * then encodes a 2-step batch: USDC.approve → Vault.deposit{value}.
+   * The `layerZeroFee` in the response is the ETH the user must hold
+   * natively — paymaster sponsors ERC-4337 gas only, not msg.value.
+   */
+  async handlePerpDeposit(request) {
+    if (request.chainId !== this.chainId) {
+      throw new Error(`handlePerpDeposit: unsupported chainId ${request.chainId}`);
+    }
+    if (request.amount <= 0n) {
+      throw new Error("handlePerpDeposit: amount must be positive");
+    }
+    const vault = import_core.ORDERLY_VAULT_ADDRESSES[request.chainId];
+    if (!vault) {
+      throw new Error(`handlePerpDeposit: no Orderly Vault for chainId ${request.chainId}`);
+    }
+    const brokerHash = import_core.BROKER_HASHES[request.brokerId];
+    if (!brokerHash) {
+      throw new Error(`handlePerpDeposit: unknown brokerId "${request.brokerId}"`);
+    }
+    const tokenHash = import_core.TOKEN_HASHES.USDC;
+    const userAddress = (0, import_viem.getAddress)(request.userAddress);
+    const [usdcAddress, brokerAllowed] = await Promise.all([
+      this.provider.readContract({
+        address: vault,
+        abi: import_core.ORDERLY_VAULT_ABI,
+        functionName: "getAllowedToken",
+        args: [tokenHash]
+      }),
+      this.provider.readContract({
+        address: vault,
+        abi: import_core.ORDERLY_VAULT_ABI,
+        functionName: "getAllowedBroker",
+        args: [brokerHash]
+      })
+    ]);
+    if (!brokerAllowed) {
+      throw new Error(
+        `handlePerpDeposit: broker "${request.brokerId}" is not whitelisted on Orderly Vault`
+      );
+    }
+    const accountId = (0, import_core.computeAccountId)(userAddress, brokerHash);
+    const depositData = {
+      accountId,
+      brokerHash,
+      tokenHash,
+      tokenAmount: request.amount
+    };
+    const layerZeroFee = await this.provider.readContract({
+      address: vault,
+      abi: import_core.ORDERLY_VAULT_ABI,
+      functionName: "getDepositFee",
+      args: [userAddress, depositData]
+    });
+    const userOp = (0, import_core.buildPerpDepositWithGasDeduction)({
+      userAddress,
+      aaNonce: request.aaNonce,
+      chainId: request.chainId,
+      usdcAddress,
+      amount: request.amount,
+      depositData,
+      layerZeroFee
+    });
+    return { userOp, layerZeroFee, accountId, brokerHash, usdcAddress };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TradingHandlers
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/api/handlers.ts"],"sourcesContent":["export { TradingHandlers } from \"./api/handlers\";\nexport type { TradingHandlersConfig } from \"./api/handlers\";\n\nexport type {\n  ApiQuoteRequest,\n  ApiQuoteResponse,\n  ApiQuoteError,\n  ApiSwapRequest,\n  ApiSwapResponse,\n  ApiPerpDepositRequest,\n  ApiPerpDepositResponse,\n} from \"./api/types\";\n","import { getAddress } from \"viem\";\nimport type { Address, PublicClient } from \"viem\";\nimport {\n  findBestQuote,\n  buildSwapWithGasDeduction,\n  buildPerpDepositWithGasDeduction,\n  getContractAddresses,\n  UNIVERSAL_ROUTER_ADDRESSES,\n  ORDERLY_VAULT_ABI,\n  ORDERLY_VAULT_ADDRESSES,\n  BROKER_HASHES,\n  TOKEN_HASHES,\n  computeAccountId,\n} from \"@pafi-dev/core\";\nimport type {\n  ApiQuoteRequest,\n  ApiQuoteResponse,\n  ApiSwapRequest,\n  ApiSwapResponse,\n  ApiPerpDepositRequest,\n  ApiPerpDepositResponse,\n} from \"./types\";\n\nexport interface TradingHandlersConfig {\n  provider: PublicClient;\n  chainId: number;\n}\n\n/**\n * Framework-agnostic handlers for on-chain trading actions.\n *\n * All handlers are stateless — they need only a PublicClient for RPC\n * calls. No ledger, no signer, no DB. Issuers wrap these in their own\n * HTTP controllers (Express / NestJS / Hono / etc.) the same way they\n * wrap `IssuerApiHandlers` from `@pafi-dev/issuer`.\n *\n * Example (NestJS):\n *\n *   const trading = new TradingHandlers({ provider, chainId });\n *\n *   // GET /quote\n *   const quote = await trading.handleQuote({ chainId, pointTokenAddress, amount, pools });\n *\n *   // POST /swap\n *   const swap = await trading.handleSwap({ chainId, userAddress, pointTokenAddress, amount, aaNonce });\n *\n *   // POST /perp-deposit\n *   const deposit = await trading.handlePerpDeposit({ chainId, userAddress, amount, aaNonce, brokerId });\n */\nexport class TradingHandlers {\n  private readonly provider: PublicClient;\n  private readonly chainId: number;\n\n  constructor(config: TradingHandlersConfig) {\n    this.provider = config.provider;\n    this.chainId = config.chainId;\n  }\n\n  // =========================================================================\n  // GET /quote\n  // =========================================================================\n\n  /**\n   * Quote exact-input PT → USDT via Uniswap V4 on-chain Quoter.\n   *\n   * Uses multicall to batch all candidate routes into a single RPC call.\n   * Returns `quoteError: \"QUOTE_UNAVAILABLE\"` when no pool/path exists\n   * rather than throwing, so callers can show a soft \"unavailable\" UI\n   * state without 500-ing.\n   */\n  async handleQuote(request: ApiQuoteRequest): Promise<ApiQuoteResponse> {\n    if (request.chainId !== this.chainId) {\n      throw new Error(`handleQuote: unsupported chainId ${request.chainId}`);\n    }\n    if (request.amount === 0n) {\n      return { pointAmount: 0n, estimatedUsdtOut: 0n, gasEstimate: 0n };\n    }\n\n    const { usdt } = getContractAddresses(request.chainId);\n    const pointTokenAddress = getAddress(request.pointTokenAddress);\n    const pools = request.pools ?? [];\n\n    try {\n      const best = await findBestQuote(\n        this.provider,\n        request.chainId,\n        pointTokenAddress,\n        usdt,\n        request.amount,\n        pools,\n      );\n      return {\n        pointAmount: request.amount,\n        estimatedUsdtOut: best.bestRoute.amountOut,\n        gasEstimate: best.bestRoute.gasEstimate,\n      };\n    } catch {\n      return {\n        pointAmount: request.amount,\n        estimatedUsdtOut: 0n,\n        gasEstimate: 0n,\n        quoteError: \"QUOTE_UNAVAILABLE\",\n      };\n    }\n  }\n\n  // =========================================================================\n  // POST /swap\n  // =========================================================================\n\n  /**\n   * Build a PT → USDT swap UserOp.\n   *\n   * Quotes the best route, applies slippage, then encodes a 4-step\n   * batch: PT.approve → Permit2.approve → UniversalRouter.execute →\n   * PT.transfer (fee, omitted when gasFeePt = 0). Returns an unsigned\n   * `PartialUserOperation`; caller attaches paymaster data + user\n   * signature and submits to the Bundler.\n   */\n  async handleSwap(request: ApiSwapRequest): Promise<ApiSwapResponse> {\n    if (request.chainId !== this.chainId) {\n      throw new Error(`handleSwap: unsupported chainId ${request.chainId}`);\n    }\n    if (request.amount <= 0n) {\n      throw new Error(\"handleSwap: amount must be positive\");\n    }\n\n    const { usdt } = getContractAddresses(request.chainId);\n    const universalRouter = UNIVERSAL_ROUTER_ADDRESSES[request.chainId];\n    if (!universalRouter) {\n      throw new Error(`handleSwap: no UniversalRouter for chainId ${request.chainId}`);\n    }\n\n    const pointTokenAddress = getAddress(request.pointTokenAddress);\n    const userAddress = getAddress(request.userAddress);\n    const pools = request.pools ?? [];\n    const slippageBps = request.slippageBps ?? 50;\n    const gasFeePt = request.gasFeePt ?? 0n;\n\n    if (gasFeePt > 0n && !request.feeRecipient) {\n      throw new Error(\"handleSwap: feeRecipient required when gasFeePt > 0\");\n    }\n\n    let quoteResult: Awaited<ReturnType<typeof findBestQuote>>;\n    try {\n      quoteResult = await findBestQuote(\n        this.provider,\n        request.chainId,\n        pointTokenAddress,\n        usdt,\n        request.amount,\n        pools,\n      );\n    } catch {\n      throw new Error(\"handleSwap: no swap path found for this point token\");\n    }\n\n    const estimatedUsdtOut = quoteResult.bestRoute.amountOut;\n    const minAmountOut = (estimatedUsdtOut * BigInt(10000 - slippageBps)) / 10000n;\n    const deadline = BigInt(Math.floor(Date.now() / 1000) + 5 * 60);\n\n    const userOp = buildSwapWithGasDeduction({\n      userAddress,\n      aaNonce: request.aaNonce,\n      pointTokenAddress,\n      outputTokenAddress: usdt,\n      universalRouterAddress: universalRouter,\n      amountIn: request.amount,\n      minAmountOut,\n      swapPath: quoteResult.bestRoute.path,\n      deadline,\n      gasFeePt,\n      feeRecipient: request.feeRecipient ?? userAddress,\n    });\n\n    return { userOp, estimatedUsdtOut, minAmountOut, deadline };\n  }\n\n  // =========================================================================\n  // POST /perp-deposit\n  // =========================================================================\n\n  /**\n   * Build an Orderly perp deposit UserOp.\n   *\n   * Resolves USDC address and LayerZero fee from on-chain Vault reads,\n   * then encodes a 2-step batch: USDC.approve → Vault.deposit{value}.\n   * The `layerZeroFee` in the response is the ETH the user must hold\n   * natively — paymaster sponsors ERC-4337 gas only, not msg.value.\n   */\n  async handlePerpDeposit(request: ApiPerpDepositRequest): Promise<ApiPerpDepositResponse> {\n    if (request.chainId !== this.chainId) {\n      throw new Error(`handlePerpDeposit: unsupported chainId ${request.chainId}`);\n    }\n    if (request.amount <= 0n) {\n      throw new Error(\"handlePerpDeposit: amount must be positive\");\n    }\n\n    const vault = ORDERLY_VAULT_ADDRESSES[request.chainId];\n    if (!vault) {\n      throw new Error(`handlePerpDeposit: no Orderly Vault for chainId ${request.chainId}`);\n    }\n\n    const brokerHash = BROKER_HASHES[request.brokerId as keyof typeof BROKER_HASHES];\n    if (!brokerHash) {\n      throw new Error(`handlePerpDeposit: unknown brokerId \"${request.brokerId}\"`);\n    }\n    const tokenHash = TOKEN_HASHES.USDC;\n    const userAddress = getAddress(request.userAddress);\n\n    const [usdcAddress, brokerAllowed] = await Promise.all([\n      this.provider.readContract({\n        address: vault,\n        abi: ORDERLY_VAULT_ABI,\n        functionName: \"getAllowedToken\",\n        args: [tokenHash],\n      }) as Promise<Address>,\n      this.provider.readContract({\n        address: vault,\n        abi: ORDERLY_VAULT_ABI,\n        functionName: \"getAllowedBroker\",\n        args: [brokerHash],\n      }) as Promise<boolean>,\n    ]);\n\n    if (!brokerAllowed) {\n      throw new Error(\n        `handlePerpDeposit: broker \"${request.brokerId}\" is not whitelisted on Orderly Vault`,\n      );\n    }\n\n    const accountId = computeAccountId(userAddress, brokerHash);\n    const depositData = {\n      accountId,\n      brokerHash,\n      tokenHash,\n      tokenAmount: request.amount,\n    };\n\n    const layerZeroFee = await this.provider.readContract({\n      address: vault,\n      abi: ORDERLY_VAULT_ABI,\n      functionName: \"getDepositFee\",\n      args: [userAddress, depositData],\n    }) as bigint;\n\n    const userOp = buildPerpDepositWithGasDeduction({\n      userAddress,\n      aaNonce: request.aaNonce,\n      chainId: request.chainId,\n      usdcAddress,\n      amount: request.amount,\n      depositData,\n      layerZeroFee,\n    });\n\n    return { userOp, layerZeroFee, accountId, brokerHash, usdcAddress };\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,140 @@
+import { Address, PublicClient } from 'viem';
+import { PartialUserOperation, PoolKey } from '@pafi-dev/core';
+
+interface ApiQuoteRequest {
+    chainId: number;
+    pointTokenAddress: Address;
+    /** PT amount (18-decimal raw units). */
+    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?: PoolKey[];
+}
+type ApiQuoteError = "QUOTE_UNAVAILABLE" | "AMOUNT_TOO_SMALL_FOR_GAS";
+interface ApiQuoteResponse {
+    pointAmount: bigint;
+    estimatedUsdtOut: bigint;
+    gasEstimate: bigint;
+    quoteError?: ApiQuoteError;
+}
+interface ApiSwapRequest {
+    chainId: number;
+    userAddress: Address;
+    pointTokenAddress: Address;
+    /** PT amount to swap (18-decimal raw units). */
+    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%). */
+    slippageBps?: number;
+    /** PT/USDT pools. Combined with COMMON_POOLS. Pass empty to use only COMMON_POOLS. */
+    pools?: PoolKey[];
+    /**
+     * PT amount deducted from user balance as operator gas fee.
+     * Default: 0n (no fee deduction). When > 0, `feeRecipient` is required.
+     */
+    gasFeePt?: bigint;
+    /** Recipient of the gasFeePt deduction. Required when gasFeePt > 0. */
+    feeRecipient?: Address;
+}
+interface ApiSwapResponse {
+    /** Unsigned UserOp — attach paymaster data + user signature, then submit to Bundler. */
+    userOp: PartialUserOperation;
+    /** Raw USDT out before slippage (6 decimals). For display. */
+    estimatedUsdtOut: bigint;
+    /** Minimum USDT accepted — encoded in the UserOp calldata. */
+    minAmountOut: bigint;
+    /** Swap deadline (unix seconds). Re-request if user doesn't submit in time. */
+    deadline: bigint;
+}
+interface ApiPerpDepositRequest {
+    chainId: number;
+    userAddress: Address;
+    /** USDC amount to deposit (6-decimal raw units). */
+    amount: bigint;
+    /** ERC-4337 account nonce for the user's EOA (from EntryPoint). */
+    aaNonce: bigint;
+    /**
+     * Orderly broker ID — must be whitelisted on the Vault.
+     * Known values: woofi_pro, orderly, logx.
+     */
+    brokerId: string;
+}
+interface ApiPerpDepositResponse {
+    /** Unsigned UserOp — attach paymaster data + user signature, then submit to Bundler. */
+    userOp: PartialUserOperation;
+    /**
+     * LayerZero fee in ETH wei. User wallet must hold at least this as
+     * native ETH — even when ERC-4337 gas is sponsored by paymaster.
+     */
+    layerZeroFee: bigint;
+    /** Orderly account ID for this (user, broker) pair. */
+    accountId: `0x${string}`;
+    /** keccak256(brokerId) — for client-side verification. */
+    brokerHash: `0x${string}`;
+    /** USDC contract address (resolved from Vault.getAllowedToken). */
+    usdcAddress: Address;
+}
+
+interface TradingHandlersConfig {
+    provider: PublicClient;
+    chainId: number;
+}
+/**
+ * Framework-agnostic handlers for on-chain trading actions.
+ *
+ * All handlers are stateless — they need only a PublicClient for RPC
+ * calls. No ledger, no signer, no DB. Issuers wrap these in their own
+ * HTTP controllers (Express / NestJS / Hono / etc.) the same way they
+ * wrap `IssuerApiHandlers` from `@pafi-dev/issuer`.
+ *
+ * Example (NestJS):
+ *
+ *   const trading = new TradingHandlers({ provider, chainId });
+ *
+ *   // GET /quote
+ *   const quote = await trading.handleQuote({ chainId, pointTokenAddress, amount, pools });
+ *
+ *   // POST /swap
+ *   const swap = await trading.handleSwap({ chainId, userAddress, pointTokenAddress, amount, aaNonce });
+ *
+ *   // POST /perp-deposit
+ *   const deposit = await trading.handlePerpDeposit({ chainId, userAddress, amount, aaNonce, brokerId });
+ */
+declare class TradingHandlers {
+    private readonly provider;
+    private readonly chainId;
+    constructor(config: TradingHandlersConfig);
+    /**
+     * Quote exact-input PT → USDT via Uniswap V4 on-chain Quoter.
+     *
+     * Uses multicall to batch all candidate routes into a single RPC call.
+     * Returns `quoteError: "QUOTE_UNAVAILABLE"` when no pool/path exists
+     * rather than throwing, so callers can show a soft "unavailable" UI
+     * state without 500-ing.
+     */
+    handleQuote(request: ApiQuoteRequest): Promise<ApiQuoteResponse>;
+    /**
+     * Build a PT → USDT swap UserOp.
+     *
+     * 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.
+     */
+    handleSwap(request: ApiSwapRequest): Promise<ApiSwapResponse>;
+    /**
+     * Build an Orderly perp deposit UserOp.
+     *
+     * Resolves USDC address and LayerZero fee from on-chain Vault reads,
+     * then encodes a 2-step batch: USDC.approve → Vault.deposit{value}.
+     * The `layerZeroFee` in the response is the ETH the user must hold
+     * natively — paymaster sponsors ERC-4337 gas only, not msg.value.
+     */
+    handlePerpDeposit(request: ApiPerpDepositRequest): Promise<ApiPerpDepositResponse>;
+}
+
+export { type ApiPerpDepositRequest, type ApiPerpDepositResponse, type ApiQuoteError, type ApiQuoteRequest, type ApiQuoteResponse, type ApiSwapRequest, type ApiSwapResponse, TradingHandlers, type TradingHandlersConfig };

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+import { Address, PublicClient } from 'viem';
+import { PartialUserOperation, PoolKey } from '@pafi-dev/core';
+
+interface ApiQuoteRequest {
+    chainId: number;
+    pointTokenAddress: Address;
+    /** PT amount (18-decimal raw units). */
+    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?: PoolKey[];
+}
+type ApiQuoteError = "QUOTE_UNAVAILABLE" | "AMOUNT_TOO_SMALL_FOR_GAS";
+interface ApiQuoteResponse {
+    pointAmount: bigint;
+    estimatedUsdtOut: bigint;
+    gasEstimate: bigint;
+    quoteError?: ApiQuoteError;
+}
+interface ApiSwapRequest {
+    chainId: number;
+    userAddress: Address;
+    pointTokenAddress: Address;
+    /** PT amount to swap (18-decimal raw units). */
+    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%). */
+    slippageBps?: number;
+    /** PT/USDT pools. Combined with COMMON_POOLS. Pass empty to use only COMMON_POOLS. */
+    pools?: PoolKey[];
+    /**
+     * PT amount deducted from user balance as operator gas fee.
+     * Default: 0n (no fee deduction). When > 0, `feeRecipient` is required.
+     */
+    gasFeePt?: bigint;
+    /** Recipient of the gasFeePt deduction. Required when gasFeePt > 0. */
+    feeRecipient?: Address;
+}
+interface ApiSwapResponse {
+    /** Unsigned UserOp — attach paymaster data + user signature, then submit to Bundler. */
+    userOp: PartialUserOperation;
+    /** Raw USDT out before slippage (6 decimals). For display. */
+    estimatedUsdtOut: bigint;
+    /** Minimum USDT accepted — encoded in the UserOp calldata. */
+    minAmountOut: bigint;
+    /** Swap deadline (unix seconds). Re-request if user doesn't submit in time. */
+    deadline: bigint;
+}
+interface ApiPerpDepositRequest {
+    chainId: number;
+    userAddress: Address;
+    /** USDC amount to deposit (6-decimal raw units). */
+    amount: bigint;
+    /** ERC-4337 account nonce for the user's EOA (from EntryPoint). */
+    aaNonce: bigint;
+    /**
+     * Orderly broker ID — must be whitelisted on the Vault.
+     * Known values: woofi_pro, orderly, logx.
+     */
+    brokerId: string;
+}
+interface ApiPerpDepositResponse {
+    /** Unsigned UserOp — attach paymaster data + user signature, then submit to Bundler. */
+    userOp: PartialUserOperation;
+    /**
+     * LayerZero fee in ETH wei. User wallet must hold at least this as
+     * native ETH — even when ERC-4337 gas is sponsored by paymaster.
+     */
+    layerZeroFee: bigint;
+    /** Orderly account ID for this (user, broker) pair. */
+    accountId: `0x${string}`;
+    /** keccak256(brokerId) — for client-side verification. */
+    brokerHash: `0x${string}`;
+    /** USDC contract address (resolved from Vault.getAllowedToken). */
+    usdcAddress: Address;
+}
+
+interface TradingHandlersConfig {
+    provider: PublicClient;
+    chainId: number;
+}
+/**
+ * Framework-agnostic handlers for on-chain trading actions.
+ *
+ * All handlers are stateless — they need only a PublicClient for RPC
+ * calls. No ledger, no signer, no DB. Issuers wrap these in their own
+ * HTTP controllers (Express / NestJS / Hono / etc.) the same way they
+ * wrap `IssuerApiHandlers` from `@pafi-dev/issuer`.
+ *
+ * Example (NestJS):
+ *
+ *   const trading = new TradingHandlers({ provider, chainId });
+ *
+ *   // GET /quote
+ *   const quote = await trading.handleQuote({ chainId, pointTokenAddress, amount, pools });
+ *
+ *   // POST /swap
+ *   const swap = await trading.handleSwap({ chainId, userAddress, pointTokenAddress, amount, aaNonce });
+ *
+ *   // POST /perp-deposit
+ *   const deposit = await trading.handlePerpDeposit({ chainId, userAddress, amount, aaNonce, brokerId });
+ */
+declare class TradingHandlers {
+    private readonly provider;
+    private readonly chainId;
+    constructor(config: TradingHandlersConfig);
+    /**
+     * Quote exact-input PT → USDT via Uniswap V4 on-chain Quoter.
+     *
+     * Uses multicall to batch all candidate routes into a single RPC call.
+     * Returns `quoteError: "QUOTE_UNAVAILABLE"` when no pool/path exists
+     * rather than throwing, so callers can show a soft "unavailable" UI
+     * state without 500-ing.
+     */
+    handleQuote(request: ApiQuoteRequest): Promise<ApiQuoteResponse>;
+    /**
+     * Build a PT → USDT swap UserOp.
+     *
+     * 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.
+     */
+    handleSwap(request: ApiSwapRequest): Promise<ApiSwapResponse>;
+    /**
+     * Build an Orderly perp deposit UserOp.
+     *
+     * Resolves USDC address and LayerZero fee from on-chain Vault reads,
+     * then encodes a 2-step batch: USDC.approve → Vault.deposit{value}.
+     * The `layerZeroFee` in the response is the ETH the user must hold
+     * natively — paymaster sponsors ERC-4337 gas only, not msg.value.
+     */
+    handlePerpDeposit(request: ApiPerpDepositRequest): Promise<ApiPerpDepositResponse>;
+}
+
+export { type ApiPerpDepositRequest, type ApiPerpDepositResponse, type ApiQuoteError, type ApiQuoteRequest, type ApiQuoteResponse, type ApiSwapRequest, type ApiSwapResponse, TradingHandlers, type TradingHandlersConfig };

package/dist/index.js

@@ -0,0 +1,204 @@
+// src/api/handlers.ts
+import { getAddress } from "viem";
+import {
+  findBestQuote,
+  buildSwapWithGasDeduction,
+  buildPerpDepositWithGasDeduction,
+  getContractAddresses,
+  UNIVERSAL_ROUTER_ADDRESSES,
+  ORDERLY_VAULT_ABI,
+  ORDERLY_VAULT_ADDRESSES,
+  BROKER_HASHES,
+  TOKEN_HASHES,
+  computeAccountId
+} from "@pafi-dev/core";
+var TradingHandlers = class {
+  provider;
+  chainId;
+  constructor(config) {
+    this.provider = config.provider;
+    this.chainId = config.chainId;
+  }
+  // =========================================================================
+  // GET /quote
+  // =========================================================================
+  /**
+   * Quote exact-input PT → USDT via Uniswap V4 on-chain Quoter.
+   *
+   * Uses multicall to batch all candidate routes into a single RPC call.
+   * Returns `quoteError: "QUOTE_UNAVAILABLE"` when no pool/path exists
+   * rather than throwing, so callers can show a soft "unavailable" UI
+   * state without 500-ing.
+   */
+  async handleQuote(request) {
+    if (request.chainId !== this.chainId) {
+      throw new Error(`handleQuote: unsupported chainId ${request.chainId}`);
+    }
+    if (request.amount === 0n) {
+      return { pointAmount: 0n, estimatedUsdtOut: 0n, gasEstimate: 0n };
+    }
+    const { usdt } = getContractAddresses(request.chainId);
+    const pointTokenAddress = getAddress(request.pointTokenAddress);
+    const pools = request.pools ?? [];
+    try {
+      const best = await findBestQuote(
+        this.provider,
+        request.chainId,
+        pointTokenAddress,
+        usdt,
+        request.amount,
+        pools
+      );
+      return {
+        pointAmount: request.amount,
+        estimatedUsdtOut: best.bestRoute.amountOut,
+        gasEstimate: best.bestRoute.gasEstimate
+      };
+    } catch {
+      return {
+        pointAmount: request.amount,
+        estimatedUsdtOut: 0n,
+        gasEstimate: 0n,
+        quoteError: "QUOTE_UNAVAILABLE"
+      };
+    }
+  }
+  // =========================================================================
+  // POST /swap
+  // =========================================================================
+  /**
+   * Build a PT → USDT swap UserOp.
+   *
+   * 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.
+   */
+  async handleSwap(request) {
+    if (request.chainId !== this.chainId) {
+      throw new Error(`handleSwap: unsupported chainId ${request.chainId}`);
+    }
+    if (request.amount <= 0n) {
+      throw new Error("handleSwap: amount must be positive");
+    }
+    const { usdt } = getContractAddresses(request.chainId);
+    const universalRouter = UNIVERSAL_ROUTER_ADDRESSES[request.chainId];
+    if (!universalRouter) {
+      throw new Error(`handleSwap: no UniversalRouter for chainId ${request.chainId}`);
+    }
+    const pointTokenAddress = getAddress(request.pointTokenAddress);
+    const userAddress = getAddress(request.userAddress);
+    const pools = request.pools ?? [];
+    const slippageBps = request.slippageBps ?? 50;
+    const gasFeePt = request.gasFeePt ?? 0n;
+    if (gasFeePt > 0n && !request.feeRecipient) {
+      throw new Error("handleSwap: feeRecipient required when gasFeePt > 0");
+    }
+    let quoteResult;
+    try {
+      quoteResult = await findBestQuote(
+        this.provider,
+        request.chainId,
+        pointTokenAddress,
+        usdt,
+        request.amount,
+        pools
+      );
+    } catch {
+      throw new Error("handleSwap: no swap path found for this point token");
+    }
+    const estimatedUsdtOut = quoteResult.bestRoute.amountOut;
+    const minAmountOut = estimatedUsdtOut * BigInt(1e4 - slippageBps) / 10000n;
+    const deadline = BigInt(Math.floor(Date.now() / 1e3) + 5 * 60);
+    const userOp = buildSwapWithGasDeduction({
+      userAddress,
+      aaNonce: request.aaNonce,
+      pointTokenAddress,
+      outputTokenAddress: usdt,
+      universalRouterAddress: universalRouter,
+      amountIn: request.amount,
+      minAmountOut,
+      swapPath: quoteResult.bestRoute.path,
+      deadline,
+      gasFeePt,
+      feeRecipient: request.feeRecipient ?? userAddress
+    });
+    return { userOp, estimatedUsdtOut, minAmountOut, deadline };
+  }
+  // =========================================================================
+  // POST /perp-deposit
+  // =========================================================================
+  /**
+   * Build an Orderly perp deposit UserOp.
+   *
+   * Resolves USDC address and LayerZero fee from on-chain Vault reads,
+   * then encodes a 2-step batch: USDC.approve → Vault.deposit{value}.
+   * The `layerZeroFee` in the response is the ETH the user must hold
+   * natively — paymaster sponsors ERC-4337 gas only, not msg.value.
+   */
+  async handlePerpDeposit(request) {
+    if (request.chainId !== this.chainId) {
+      throw new Error(`handlePerpDeposit: unsupported chainId ${request.chainId}`);
+    }
+    if (request.amount <= 0n) {
+      throw new Error("handlePerpDeposit: amount must be positive");
+    }
+    const vault = ORDERLY_VAULT_ADDRESSES[request.chainId];
+    if (!vault) {
+      throw new Error(`handlePerpDeposit: no Orderly Vault for chainId ${request.chainId}`);
+    }
+    const brokerHash = BROKER_HASHES[request.brokerId];
+    if (!brokerHash) {
+      throw new Error(`handlePerpDeposit: unknown brokerId "${request.brokerId}"`);
+    }
+    const tokenHash = TOKEN_HASHES.USDC;
+    const userAddress = getAddress(request.userAddress);
+    const [usdcAddress, brokerAllowed] = await Promise.all([
+      this.provider.readContract({
+        address: vault,
+        abi: ORDERLY_VAULT_ABI,
+        functionName: "getAllowedToken",
+        args: [tokenHash]
+      }),
+      this.provider.readContract({
+        address: vault,
+        abi: ORDERLY_VAULT_ABI,
+        functionName: "getAllowedBroker",
+        args: [brokerHash]
+      })
+    ]);
+    if (!brokerAllowed) {
+      throw new Error(
+        `handlePerpDeposit: broker "${request.brokerId}" is not whitelisted on Orderly Vault`
+      );
+    }
+    const accountId = computeAccountId(userAddress, brokerHash);
+    const depositData = {
+      accountId,
+      brokerHash,
+      tokenHash,
+      tokenAmount: request.amount
+    };
+    const layerZeroFee = await this.provider.readContract({
+      address: vault,
+      abi: ORDERLY_VAULT_ABI,
+      functionName: "getDepositFee",
+      args: [userAddress, depositData]
+    });
+    const userOp = buildPerpDepositWithGasDeduction({
+      userAddress,
+      aaNonce: request.aaNonce,
+      chainId: request.chainId,
+      usdcAddress,
+      amount: request.amount,
+      depositData,
+      layerZeroFee
+    });
+    return { userOp, layerZeroFee, accountId, brokerHash, usdcAddress };
+  }
+};
+export {
+  TradingHandlers
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api/handlers.ts"],"sourcesContent":["import { getAddress } from \"viem\";\nimport type { Address, PublicClient } from \"viem\";\nimport {\n  findBestQuote,\n  buildSwapWithGasDeduction,\n  buildPerpDepositWithGasDeduction,\n  getContractAddresses,\n  UNIVERSAL_ROUTER_ADDRESSES,\n  ORDERLY_VAULT_ABI,\n  ORDERLY_VAULT_ADDRESSES,\n  BROKER_HASHES,\n  TOKEN_HASHES,\n  computeAccountId,\n} from \"@pafi-dev/core\";\nimport type {\n  ApiQuoteRequest,\n  ApiQuoteResponse,\n  ApiSwapRequest,\n  ApiSwapResponse,\n  ApiPerpDepositRequest,\n  ApiPerpDepositResponse,\n} from \"./types\";\n\nexport interface TradingHandlersConfig {\n  provider: PublicClient;\n  chainId: number;\n}\n\n/**\n * Framework-agnostic handlers for on-chain trading actions.\n *\n * All handlers are stateless — they need only a PublicClient for RPC\n * calls. No ledger, no signer, no DB. Issuers wrap these in their own\n * HTTP controllers (Express / NestJS / Hono / etc.) the same way they\n * wrap `IssuerApiHandlers` from `@pafi-dev/issuer`.\n *\n * Example (NestJS):\n *\n *   const trading = new TradingHandlers({ provider, chainId });\n *\n *   // GET /quote\n *   const quote = await trading.handleQuote({ chainId, pointTokenAddress, amount, pools });\n *\n *   // POST /swap\n *   const swap = await trading.handleSwap({ chainId, userAddress, pointTokenAddress, amount, aaNonce });\n *\n *   // POST /perp-deposit\n *   const deposit = await trading.handlePerpDeposit({ chainId, userAddress, amount, aaNonce, brokerId });\n */\nexport class TradingHandlers {\n  private readonly provider: PublicClient;\n  private readonly chainId: number;\n\n  constructor(config: TradingHandlersConfig) {\n    this.provider = config.provider;\n    this.chainId = config.chainId;\n  }\n\n  // =========================================================================\n  // GET /quote\n  // =========================================================================\n\n  /**\n   * Quote exact-input PT → USDT via Uniswap V4 on-chain Quoter.\n   *\n   * Uses multicall to batch all candidate routes into a single RPC call.\n   * Returns `quoteError: \"QUOTE_UNAVAILABLE\"` when no pool/path exists\n   * rather than throwing, so callers can show a soft \"unavailable\" UI\n   * state without 500-ing.\n   */\n  async handleQuote(request: ApiQuoteRequest): Promise<ApiQuoteResponse> {\n    if (request.chainId !== this.chainId) {\n      throw new Error(`handleQuote: unsupported chainId ${request.chainId}`);\n    }\n    if (request.amount === 0n) {\n      return { pointAmount: 0n, estimatedUsdtOut: 0n, gasEstimate: 0n };\n    }\n\n    const { usdt } = getContractAddresses(request.chainId);\n    const pointTokenAddress = getAddress(request.pointTokenAddress);\n    const pools = request.pools ?? [];\n\n    try {\n      const best = await findBestQuote(\n        this.provider,\n        request.chainId,\n        pointTokenAddress,\n        usdt,\n        request.amount,\n        pools,\n      );\n      return {\n        pointAmount: request.amount,\n        estimatedUsdtOut: best.bestRoute.amountOut,\n        gasEstimate: best.bestRoute.gasEstimate,\n      };\n    } catch {\n      return {\n        pointAmount: request.amount,\n        estimatedUsdtOut: 0n,\n        gasEstimate: 0n,\n        quoteError: \"QUOTE_UNAVAILABLE\",\n      };\n    }\n  }\n\n  // =========================================================================\n  // POST /swap\n  // =========================================================================\n\n  /**\n   * Build a PT → USDT swap UserOp.\n   *\n   * Quotes the best route, applies slippage, then encodes a 4-step\n   * batch: PT.approve → Permit2.approve → UniversalRouter.execute →\n   * PT.transfer (fee, omitted when gasFeePt = 0). Returns an unsigned\n   * `PartialUserOperation`; caller attaches paymaster data + user\n   * signature and submits to the Bundler.\n   */\n  async handleSwap(request: ApiSwapRequest): Promise<ApiSwapResponse> {\n    if (request.chainId !== this.chainId) {\n      throw new Error(`handleSwap: unsupported chainId ${request.chainId}`);\n    }\n    if (request.amount <= 0n) {\n      throw new Error(\"handleSwap: amount must be positive\");\n    }\n\n    const { usdt } = getContractAddresses(request.chainId);\n    const universalRouter = UNIVERSAL_ROUTER_ADDRESSES[request.chainId];\n    if (!universalRouter) {\n      throw new Error(`handleSwap: no UniversalRouter for chainId ${request.chainId}`);\n    }\n\n    const pointTokenAddress = getAddress(request.pointTokenAddress);\n    const userAddress = getAddress(request.userAddress);\n    const pools = request.pools ?? [];\n    const slippageBps = request.slippageBps ?? 50;\n    const gasFeePt = request.gasFeePt ?? 0n;\n\n    if (gasFeePt > 0n && !request.feeRecipient) {\n      throw new Error(\"handleSwap: feeRecipient required when gasFeePt > 0\");\n    }\n\n    let quoteResult: Awaited<ReturnType<typeof findBestQuote>>;\n    try {\n      quoteResult = await findBestQuote(\n        this.provider,\n        request.chainId,\n        pointTokenAddress,\n        usdt,\n        request.amount,\n        pools,\n      );\n    } catch {\n      throw new Error(\"handleSwap: no swap path found for this point token\");\n    }\n\n    const estimatedUsdtOut = quoteResult.bestRoute.amountOut;\n    const minAmountOut = (estimatedUsdtOut * BigInt(10000 - slippageBps)) / 10000n;\n    const deadline = BigInt(Math.floor(Date.now() / 1000) + 5 * 60);\n\n    const userOp = buildSwapWithGasDeduction({\n      userAddress,\n      aaNonce: request.aaNonce,\n      pointTokenAddress,\n      outputTokenAddress: usdt,\n      universalRouterAddress: universalRouter,\n      amountIn: request.amount,\n      minAmountOut,\n      swapPath: quoteResult.bestRoute.path,\n      deadline,\n      gasFeePt,\n      feeRecipient: request.feeRecipient ?? userAddress,\n    });\n\n    return { userOp, estimatedUsdtOut, minAmountOut, deadline };\n  }\n\n  // =========================================================================\n  // POST /perp-deposit\n  // =========================================================================\n\n  /**\n   * Build an Orderly perp deposit UserOp.\n   *\n   * Resolves USDC address and LayerZero fee from on-chain Vault reads,\n   * then encodes a 2-step batch: USDC.approve → Vault.deposit{value}.\n   * The `layerZeroFee` in the response is the ETH the user must hold\n   * natively — paymaster sponsors ERC-4337 gas only, not msg.value.\n   */\n  async handlePerpDeposit(request: ApiPerpDepositRequest): Promise<ApiPerpDepositResponse> {\n    if (request.chainId !== this.chainId) {\n      throw new Error(`handlePerpDeposit: unsupported chainId ${request.chainId}`);\n    }\n    if (request.amount <= 0n) {\n      throw new Error(\"handlePerpDeposit: amount must be positive\");\n    }\n\n    const vault = ORDERLY_VAULT_ADDRESSES[request.chainId];\n    if (!vault) {\n      throw new Error(`handlePerpDeposit: no Orderly Vault for chainId ${request.chainId}`);\n    }\n\n    const brokerHash = BROKER_HASHES[request.brokerId as keyof typeof BROKER_HASHES];\n    if (!brokerHash) {\n      throw new Error(`handlePerpDeposit: unknown brokerId \"${request.brokerId}\"`);\n    }\n    const tokenHash = TOKEN_HASHES.USDC;\n    const userAddress = getAddress(request.userAddress);\n\n    const [usdcAddress, brokerAllowed] = await Promise.all([\n      this.provider.readContract({\n        address: vault,\n        abi: ORDERLY_VAULT_ABI,\n        functionName: \"getAllowedToken\",\n        args: [tokenHash],\n      }) as Promise<Address>,\n      this.provider.readContract({\n        address: vault,\n        abi: ORDERLY_VAULT_ABI,\n        functionName: \"getAllowedBroker\",\n        args: [brokerHash],\n      }) as Promise<boolean>,\n    ]);\n\n    if (!brokerAllowed) {\n      throw new Error(\n        `handlePerpDeposit: broker \"${request.brokerId}\" is not whitelisted on Orderly Vault`,\n      );\n    }\n\n    const accountId = computeAccountId(userAddress, brokerHash);\n    const depositData = {\n      accountId,\n      brokerHash,\n      tokenHash,\n      tokenAmount: request.amount,\n    };\n\n    const layerZeroFee = await this.provider.readContract({\n      address: vault,\n      abi: ORDERLY_VAULT_ABI,\n      functionName: \"getDepositFee\",\n      args: [userAddress, depositData],\n    }) as bigint;\n\n    const userOp = buildPerpDepositWithGasDeduction({\n      userAddress,\n      aaNonce: request.aaNonce,\n      chainId: request.chainId,\n      usdcAddress,\n      amount: request.amount,\n      depositData,\n      layerZeroFee,\n    });\n\n    return { userOp, layerZeroFee, accountId, brokerHash, usdcAddress };\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@pafi-dev/trading",
+  "version": "0.1.0",
+  "description": "Stateless on-chain trading handlers for PAFI — swap, quote, perp deposit",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@pafi-dev/core": "0.5.1"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "viem": "^2.21.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}