@pafi-dev/core 0.6.1 → 0.7.0

package/README.md

@@ -3,344 +3,237 @@
 [![npm](https://img.shields.io/npm/v/@pafi-dev/core)](https://www.npmjs.com/package/@pafi-dev/core)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Core TypeScript SDK for the PAFI point token system. Covers EIP-712 signing, contract addresses + ABIs, ERC-4337 UserOp building, swap/perp calldata encoding, and on-chain quoting.
+Pure primitives for the PAFI point-token system. EIP-712 signing,
+contract ABIs + addresses, ERC-4337 UserOp building, EIP-7702
+delegation, sponsor-auth signing, perp deposit calldata, fee quoting.
 
-**No HTTP client.** Safe to use in both browser (frontend) and Node.js (issuer backend).
+**Browser + Node-safe.** Zero HTTP client. Peer-dep: `viem ^2`.
 
 ---
 
 ## Requirements
 
-- Node.js >= 18
+- Node.js >= 18 (or modern browser with native `fetch`)
 - TypeScript >= 5.0
-- `viem` ^2.0.0 (peer dependency)
-
-> **Latest:** `0.5.16` — ERC-4337 v0.8 hash + EIP-712 signing fixes for the
-> EIP-7702 mobile flow. See [Changelog](#changelog) for the full breakdown
-> of the AA24/AA23 bugs this release closes.
+- `viem` ^2.0.0 (peer)
 
 ---
 
 ## Installation
 
 ```bash
-npm install @pafi-dev/core viem
-# or
 pnpm add @pafi-dev/core viem
 ```
 
 ---
 
-## Modules
-
-| Import path | What it provides |
-|---|---|
-| `@pafi-dev/core` | All exports below |
-| `@pafi-dev/core/eip712` | `signMintRequest`, `verifyMintRequest`, `signBurnRequest`, `signReceiverConsent` |
-| `@pafi-dev/core/contract` | `getContractAddresses()`, ABIs, address constants |
-| `@pafi-dev/core/swap` | `buildSwapWithGasDeduction()` — PT→USDT via UniversalRouter |
-| `@pafi-dev/core/quoting` | `findBestQuote()` — on-chain V4 Quoter multicall |
-| `@pafi-dev/core/auth` | `createLoginMessage()`, `signSponsorAuth()`, `verifySponsorAuth()` |
-| `@pafi-dev/core/relay` | `buildDelegationUserOp()`, `getAaNonce()` |
+## What's in core (and what's not)
+
+Core ships **data + primitives** only. Higher-level orchestration lives
+in sibling packages:
+
+| Concern | Package |
+| --- | --- |
+| Pure primitives (this package) | `@pafi-dev/core` |
+| Issuer backend (claim / redeem / mobile flows) | `@pafi-dev/issuer` |
+| Issuer DB ledger (TypeORM + Postgres) | `@pafi-dev/issuer-postgres` |
+| Trading (swap + quote, FE-callable) | `@pafi-dev/trading` |
+
+> **0.6.0 (2026-04-27):** swap UserOp builders + V4 quoting moved
+> from core to `@pafi-dev/trading`. Core retains the underlying
+> `universalRouterAbi`, `permit2Abi`, `v4QuoterAbi`, `PoolKey`,
+> `PathKey`, `QuoteResult` types — trading wraps them with the actual
+> swap logic. The `PafiSDK` class also drops `quote` / `swap`
+> namespaces; use trading or import primitives directly.
+>
+> **0.6.1 (2026-04-27):** added `quoteOperatorFeeUsdt` so FE can
+> compute USDT-denominated gas fee without round-tripping the issuer
+> backend (`/gas-fee` is now optional).
 
 ---
 
-## Contract addresses
-
-All deployed PAFI contract addresses live in one place, keyed by `chainId`:
-
-```ts
-import { getContractAddresses, POINT_TOKEN_FACTORY_ADDRESSES } from "@pafi-dev/core";
+## Modules
 
-const addrs = getContractAddresses(8453); // Base mainnet
-// addrs.pointToken      "0x7d25E7156E51F865D522fd3ef257a6B5DD41b97e"
-// addrs.issuerRegistry  "0xda2D3338CF70F462Ac175F5f2edfa45660CA4f31"
-// addrs.mintingOracle   "0xD85165939C700E51c8a45099316C6482634C2Ab9"
-// addrs.pafiHook        "0x870cAF9882d3160602AaC1769C2B264A2d8EC044"
-// addrs.usdt            "0x5d313485Ba59C3bb91e1A9C0C11782F0b83d5dcd"
-// addrs.batchExecutor   "0x7702cb554e6bFb442cb743A7dF23154544a7176C"
+| Symbol / area | What it provides |
+| --- | --- |
+| `getContractAddresses(chainId)` | All deployed PAFI contract addresses keyed by chain |
+| `signMintRequest`, `verifyMintRequest` | EIP-712 sign / recover for `MintRequest` |
+| `signBurnRequest`, `verifyBurnRequest` | EIP-712 sign / recover for `BurnRequest` |
+| `signReceiverConsent`, `verifyReceiverConsent` | EIP-712 for sponsored-mint consent |
+| `signSponsorAuth`, `verifySponsorAuth`, `buildAndSignSponsorAuth` | EIP-712 for sponsor-relayer auth |
+| `buildPartialUserOperation`, `assembleUserOperation`, `computeUserOpHash` | ERC-4337 v0.7+ UserOp builder + hash |
+| `encodeBatchExecute`, `decodeBatchExecuteCalls` | BatchExecutor (Coinbase SW v2) calldata |
+| `buildDelegationUserOp`, `computeAuthorizationHash`, `parseEip7702DelegatedAddress` | EIP-7702 helpers |
+| `splitAuthorizationSig`, `buildEip7702Authorization` | Split user's authSig + assemble bundler tuple |
+| `buildPerpDepositViaRelay`, `buildPerpDepositWithGasDeduction`, `ORDERLY_RELAY_ABI`, `ORDERLY_VAULT_ABI`, `BROKER_HASHES`, `TOKEN_HASHES`, `computeAccountId` | Orderly perp deposit calldata + types |
+| `quoteOperatorFeePt`, `quoteOperatorFeeUsdt` | Off-issuer fee quoter (Chainlink + V4 subgraph) |
+| `fetchPafiPools`, `PAFI_SUBGRAPH_URL` | Pool discovery via PAFI subgraph |
+| `pointTokenAbi` (alias `POINT_TOKEN_V2_ABI`), `issuerRegistryAbi`, `mintingOracleAbi`, `pointTokenFactoryAbi`, `erc20Abi`, `permit2Abi`, `universalRouterAbi`, `v4QuoterAbi` | Contract ABIs |
+| `getMintRequestNonce`, `getBurnRequestNonce`, `getReceiverConsentNonce`, `getPointTokenBalance`, `isMinter`, `getTokenName` | On-chain read helpers |
+| `createLoginMessage` | EIP-4361 SIWE login message builder |
+| `parseEip7702DelegatedAddress`, `checkDelegation`, `isDelegatedTo`, `isDelegatedToTarget` | EIP-7702 delegation introspection |
 
-POINT_TOKEN_FACTORY_ADDRESSES[8453] // "0x36c0BAb2faBE45EfA6d13001143e43A266Af673B"
-```
+---
 
-Protocol constants (same on all EVM chains):
+## Contract addresses
 
 ```ts
-import {
-  ENTRY_POINT_V07,
-  ENTRY_POINT_V08,
-  PERMIT2_ADDRESS,
-} from "@pafi-dev/core";
-// ENTRY_POINT_V07   "0x0000000071727De22E5E9d8BAf0edAc6f37da032"
-// ENTRY_POINT_V08   "0x4337084d9e255ff0702461cf8895ce9e3b5ff108"
-// PERMIT2_ADDRESS   "0x000000000022D473030F116dDEE9F6B43aC78BA3"
+import { getContractAddresses } from "@pafi-dev/core";
+
+const {
+  pointToken,
+  batchExecutor,        // EIP-7702 delegation target (Coinbase SW v2)
+  usdt,
+  issuerRegistry,
+  mintingOracle,
+  pafiHook,             // Uniswap V4 hook (10% fee on PT→USDT only)
+  chainlinkEthUsd,
+  orderlyRelay,
+  pafiFeeRecipient,
+  universalRouter,
+} = getContractAddresses(8453);
 ```
 
-For Pimlico's `Simple7702Account` (the EIP-7702 delegate target you get
-when using Privy embedded wallets) you **must** use `ENTRY_POINT_V08`.
-Mixing v0.7 with a v0.8 account reverts with `AA23 reverted account: not
-from EntryPoint`.
+Throws if `chainId` isn't in the map. Base mainnet (8453) is the only
+chain in active use.
 
 ---
 
 ## EIP-712 signing
 
-Used by the **issuer backend** to sign mint/burn authorization. The frontend
-sends the signature alongside the UserOp to the Relay contract.
-
 ```ts
-import { signMintRequest, verifyMintRequest } from "@pafi-dev/core";
+import { signMintRequest, getContractAddresses } from "@pafi-dev/core";
+import { privateKeyToAccount } from "viem/accounts";
+import { createWalletClient, http } from "viem";
 
-const domain = {
-  name: "GG56 Points",            // must match PointToken.name() on-chain
-  chainId: 8453,
-  verifyingContract: addrs.pointToken,
-};
-
-const { signature } = await signMintRequest(issuerWalletClient, domain, {
-  to: userAddress,
-  amount: 500n * 10n ** 18n,
-  nonce: await getMintRequestNonce(publicClient, addrs.pointToken, userAddress),
-  deadline: BigInt(Math.floor(Date.now() / 1000) + 900), // 15 min
+const wallet = createWalletClient({
+  account: privateKeyToAccount(MINTER_PK),
+  transport: http(),
 });
 
-// Offline verification (optional — Relay contract verifies on-chain)
-const { valid } = await verifyMintRequest(domain, request, signature, expectedSigner);
-```
-
----
-
-## SponsorAuth — paymaster authorization
-
-The issuer backend signs a `SponsorAuth` payload so the PAFI paymaster proxy can
-verify the request is authorized before spending gas on behalf of the user.
-
-```ts
-import {
-  signSponsorAuth,
-  verifySponsorAuth,
-  computeCallDataHash,
-  type SponsorAuthPayload,
-} from "@pafi-dev/core";
+const { pointToken } = getContractAddresses(8453);
+const sig = await signMintRequest(
+  wallet,
+  { name: "POINT", chainId: 8453, verifyingContract: pointToken },
+  {
+    to: userAddress,
+    amount: 1000n * 10n ** 18n,
+    nonce: currentMintRequestNonce,
+    deadline: BigInt(Math.floor(Date.now() / 1000) + 900),
+  },
+);
 
-// Issuer backend: build + sign
-const payload: SponsorAuthPayload = {
-  chainId: 8453,
-  sender: userAddress,
-  callDataHash: computeCallDataHash(userOp.callData),
-  nonce: BigInt(Date.now()) * 1_000_000n + BigInt(Math.floor(Math.random() * 1_000_000)),
-  expiresAt: Math.floor(Date.now() / 1000) + 600, // 10 min
-  scenario: "mint",   // "mint" | "burn" | "swap"
-  issuerId: "gg56",
-};
-
-const sig = await signSponsorAuth(issuerWalletClient, payload);
-
-// Paymaster proxy: verify before forwarding to Pimlico
-const result = await verifySponsorAuth(payload, sig, expectedIssuerAddress);
-// result.ok             true/false
-// result.reason         "EXPIRED" | "INVALID_SIGNER" | "INVALID_SIGNATURE_FORMAT"
+// sig.serialized — bytes hex passed to PointToken.mint(...)
 ```
 
----
+Same pattern for `signBurnRequest`, `signReceiverConsent`,
+`signSponsorAuth`. KMS-backed wallets work — pass any
+`viem WalletClient`.
 
-## Swap calldata — PT → USDT
+---
 
-Builds the `callData` for a `BatchExecutor.execute()` call that:
-1. Approves Permit2
-2. Sets a Permit2 allowance for UniversalRouter
-3. Swaps PT → USDT via UniversalRouter
-4. Optionally deducts a gas fee in PT
+## ERC-4337 UserOp building
 
 ```ts
-import {
-  buildSwapWithGasDeduction,
-  findBestQuote,
-  getContractAddresses,
-  UNIVERSAL_ROUTER_ADDRESSES,
-} from "@pafi-dev/core";
-
-const addrs = getContractAddresses(8453);
+import { encodeBatchExecute, buildPartialUserOperation } from "@pafi-dev/core";
 
-// 1. Quote (on-chain V4 Quoter multicall — read-only)
-const quote = await findBestQuote(
-  publicClient,
-  8453,
-  addrs.pointToken,
-  addrs.usdt,
-  500n * 10n ** 18n,
-  pools, // PoolKey[] from issuer backend GET /pools
-);
+const callData = encodeBatchExecute([
+  { target: pointToken, value: 0n, data: mintCallData },
+  { target: pointToken, value: 0n, data: feeTransferCallData }, // optional
+]);
 
-// 2. Build unsigned UserOp
-const userOp = buildSwapWithGasDeduction({
-  chainId: 8453,
+const partial = buildPartialUserOperation({
   sender: userAddress,
-  pointTokenAddress: addrs.pointToken,
-  usdtAddress: addrs.usdt,
-  universalRouterAddress: UNIVERSAL_ROUTER_ADDRESSES[8453],
-  pafiHookAddress: addrs.pafiHook,
-  quote,
-  slippageBps: 50,
-  deadline: BigInt(Math.floor(Date.now() / 1000) + 300),
-  aaNonce: await getAaNonce(publicClient, userAddress),
-  batchExecutorAddress: addrs.batchExecutor,
-  gasFeePt: 0n, // set > 0 to deduct operator fee in PT
+  nonce: aaNonce,
+  operations: [...],
+  gasLimits: { callGasLimit: 300_000n, verificationGasLimit: 150_000n, preVerificationGas: 50_000n },
 });
 ```
 
----
+`computeUserOpHash(userOp, chainId)` — EntryPoint v0.8 EIP-712 digest.
+The mobile prepare/submit flow signs this hash via Privy
+`personal_sign`.
 
-## EIP-7702 delegation
+---
 
-One-time setup: sponsors the EIP-7702 delegation so the user's EOA gains
-`BatchExecutor` capabilities without spending native ETH.
+## EIP-7702 delegation helpers
 
 ```ts
 import {
-  buildDelegationUserOp,
-  getAaNonce,
-  getContractAddresses,
-  BATCH_EXECUTOR_ADDRESS_BASE_MAINNET,
+  computeAuthorizationHash,
+  parseEip7702DelegatedAddress,
+  splitAuthorizationSig,
+  buildEip7702Authorization,
 } from "@pafi-dev/core";
 
-const aaNonce = await getAaNonce(publicClient, userAddress);
+// Check whether user EOA already has delegation installed
+const code = await provider.getCode({ address: userAddress });
+const designator = parseEip7702DelegatedAddress(code);  // null = not delegated
 
-const userOp = buildDelegationUserOp({
-  userAddress,
-  aaNonce,
-});
-
-// Then: sign the EIP-7702 authorization off-chain via Privy
-// const authorization = await signAuthorization({ contractAddress: BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, ... });
-// await smartClient.sendTransaction({ to: userAddress, data: "0x", authorization });
-```
-
----
-
-## SIWE login message
-
-```ts
-import { createLoginMessage } from "@pafi-dev/core";
+// Build the hash the user signs to authorize delegation
+const accountNonce = BigInt(await provider.getTransactionCount({ address: userAddress }));
+const authHash = computeAuthorizationHash(8453, batchExecutor, accountNonce);
 
-const message = createLoginMessage({
-  address: userAddress,
-  domain: "app.gg56.com",
+// On the bundler side: split the user's 65-byte signature into the tuple
+const { r, s, yParity } = splitAuthorizationSig(authSig);
+const authorization = buildEip7702Authorization({
   chainId: 8453,
-  nonce: nonceFromServer,     // GET /auth/nonce
-  issuedAt: new Date().toISOString(),
-  uri: "https://app.gg56.com",
+  address: batchExecutor,
+  nonce: accountNonce,
+  authSig,
 });
-
-// User signs with wallet, then POST /auth/login { message, signature }
 ```
 
 ---
 
-## Perp deposit calldata — USDC → Orderly
+## Operator fee quoter
+
+Two helpers for FE direct-mode usage (no backend round-trip):
 
 ```ts
-import {
-  buildPerpDepositWithGasDeduction,
-  computeAccountId,
-  BROKER_HASHES,
-  TOKEN_HASHES,
-  ORDERLY_VAULT_ADDRESSES,
-} from "@pafi-dev/core";
+import { quoteOperatorFeeUsdt, quoteOperatorFeePt } from "@pafi-dev/core";
 
-const accountId = computeAccountId(userAddress, BROKER_HASHES["woofi_pro"]);
+// USDT-denominated (replaces issuer's GET /gas-fee).
+// Pure RPC + Chainlink read.
+const gasFeeUsdt = await quoteOperatorFeeUsdt({ provider, chainId: 8453 });
 
-const userOp = buildPerpDepositWithGasDeduction({
+// PT-denominated (used by the swap flow as operator gas reimbursement
+// in PT). Needs a subgraph call to read PT spot price.
+const gasFeePt = await quoteOperatorFeePt({
+  provider,
   chainId: 8453,
-  sender: userAddress,
-  usdcAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-  vaultAddress: ORDERLY_VAULT_ADDRESSES[8453],
-  amount: 100n * 10n ** 6n,
-  accountId,
-  brokerHash: BROKER_HASHES["woofi_pro"],
-  tokenHash: TOKEN_HASHES["USDC"],
-  layerZeroFee: await vault.getDepositFee(),
-  aaNonce: await getAaNonce(publicClient, userAddress),
-  batchExecutorAddress: addrs.batchExecutor,
+  pointTokenAddress: POINT_TOKEN,
 });
 ```
 
+Both return `bigint` raw units. Sponsor-relayer's `FeeValidator` runs
+the same math server-side with a 5% tolerance window — minor drift
+between client and server is accepted.
+
 ---
 
-## Changelog
-
-### 0.5.16
-
-ERC-4337 v0.8 + EIP-7702 mobile flow correctness fixes.
-
-**Why this release.** The mobile prepare/submit flow (issuer backend computes
-the userOpHash, mobile client signs it, backend submits to the bundler)
-was reverting on Pimlico with `AA24 signature error` even though the same
-UserOp validated cleanly on the web flow via `permissionless`. Three
-distinct bugs stacked on top of each other; this release fixes them.
-
-**1. `computeUserOpHash` now produces the EIP-712 typed digest used by
-EntryPoint v0.8.** Previous versions hashed via the v0.7 scheme
-(`keccak256(packed userOp || entryPoint || chainId)`), which produces a
-totally different hash than what Pimlico's `Simple7702Account` (impl
-`0xe6Cae8…`, `entryPoint() = 0x4337084d…`) actually validates against.
-Symptom: `AA24` on every mobile UserOp.
-
-**2. `buildUserOpTypedData()` exposed for client-side signing.** The
-deployed Pimlico `Simple7702Account` validates the user signature with
-`SignatureCheckerLib.isValidSignatureNow(address(this), userOpHash, sig)`
-— **no EIP-191 prefix wrapping.** That means
-`personal_sign` / `signMessage({ raw: userOpHash })` produces a signature
-that `ecrecover`s to the wrong address; AA24 again. The new helper returns
-`{ domain, types, primaryType, message }` ready to pass straight into
-`walletClient.signTypedData(...)`. Because `userOpHash` IS the EIP-712
-digest of `PackedUserOperation`, signing the typed data yields a
-signature that recovers the EOA from the raw userOpHash — which is what
-the contract checks.
+## Sponsor-auth signing
 
 ```ts
-import { buildUserOpTypedData, computeUserOpHash } from "@pafi-dev/core";
-
-// Backend (gg56-backend, claim/prepare):
-const typedData = buildUserOpTypedData(userOpWithPaymaster, chainId);
-const userOpHash = computeUserOpHash(userOpWithPaymaster, chainId);
-return { lockId, userOpHash, typedData /* serialise bigints */ };
-
-// Client (Privy embedded wallet):
-const signature = await walletClient.signTypedData({
-  domain: typedData.domain,
-  types: typedData.types,
-  primaryType: typedData.primaryType,
-  message: typedData.message,
-});
-// Submit { lockId, signature } to /claim/submit. AA24 stays away.
-```
-
-**Do NOT use `signMessage({ raw })` or `personal_sign` to sign a v0.8
-userOpHash for `Simple7702Account`** — that path is a foot-gun the SDK
-intentionally no longer offers a helper for.
+import { buildAndSignSponsorAuth } from "@pafi-dev/core";
 
-**3. `ENTRY_POINT_V08` constant added.** v0.7 EntryPoint
-(`0x0000000071727De22E5E9d8BAf0edAc6f37da032`) is incompatible with
-v0.8 accounts — calling `pm_sponsorUserOperation` with v0.7 reverts
-inside `_validateUserOp` with `"AA23 reverted account: not from
-EntryPoint"` because `msg.sender (v0.7 EP) ≠ account.entryPoint() (v0.8 EP)`.
+const sponsorAuth = await buildAndSignSponsorAuth({
+  userAddress,
+  callData: userOp.callData,
+  chainId: 8453,
+  scenario: "mint",          // "mint" | "burn" | "swap" | "perp-deposit" | "delegate"
+  issuerId: ISSUER_ID,
+  issuerSignerWallet,        // KMS-backed in prod
+});
 
-```ts
-import { ENTRY_POINT_V08 } from "@pafi-dev/core";
-// 0x4337084d9e255ff0702461cf8895ce9e3b5ff108
+// Pass to sponsor-relayer's POST /paymaster/sponsor as the `sponsorAuth` field.
 ```
 
-### 0.4.0
-- `sponsorAuth` module added — `signSponsorAuth`, `verifySponsorAuth`, `computeCallDataHash`
-- `PERMIT2_ADDRESS` and `ENTRY_POINT_V07` centralised in `constants.ts`
-- `BATCH_EXECUTOR_ADDRESS_BASE_*` derived from `addresses.ts` — no duplicate hardcoding
+The issuer signer must be registered in PAFI's `IssuerRegistry`
+(`signerAddress` field).
 
-### 0.3.0-beta.10
-- All Base mainnet contract addresses live and verified against deployed contracts
+---
 
-### 0.3.0-beta.8/9
-- Full 4-scenario UserOp builders (mint, burn, swap, perp_deposit)
+## License
 
-### 0.3.0-alpha.0
-- Initial EIP-7702 BatchExecutor support, UserOp primitives
+Apache-2.0

package/dist/index.cjs

@@ -396,26 +396,19 @@ function buildPerpDepositViaRelay(params) {
     throw new Error("buildPerpDepositViaRelay: relayAddress required");
   }
   const operations = [];
-  if (params.gasFeePt && params.gasFeePt > 0n) {
-    if (!params.pointTokenAddress) {
+  if (params.gasFeeUsdc && params.gasFeeUsdc > 0n) {
+    if (!params.gasFeeUsdcRecipient) {
       throw new Error(
-        "buildPerpDepositViaRelay: pointTokenAddress required when gasFeePt > 0"
+        "buildPerpDepositViaRelay: gasFeeUsdcRecipient required when gasFeeUsdc > 0"
       );
     }
-    if (!params.gasFeePtRecipient) {
-      throw new Error(
-        "buildPerpDepositViaRelay: gasFeePtRecipient required when gasFeePt > 0"
-      );
-    }
-    operations.push({
-      target: params.pointTokenAddress,
-      value: 0n,
-      data: _viem.encodeFunctionData.call(void 0, {
-        abi: _viem.erc20Abi,
-        functionName: "transfer",
-        args: [params.gasFeePtRecipient, params.gasFeePt]
-      })
-    });
+    operations.push(
+      erc20TransferOp(
+        params.request.token,
+        params.gasFeeUsdcRecipient,
+        params.gasFeeUsdc
+      )
+    );
   }
   operations.push(
     erc20ApproveOp(