@pafi-dev/issuer 0.6.0 → 0.6.1

package/README.md

@@ -3,11 +3,15 @@
 [![npm](https://img.shields.io/npm/v/@pafi-dev/issuer)](https://www.npmjs.com/package/@pafi-dev/issuer)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-Issuer backend SDK for the PAFI point token system. Wraps `@pafi-dev/core` with everything
-a partner needs to run the off-chain side of the cashout flow: SIWE authentication, point
-ledger, policy engine, EIP-712 issuer signing, relay submission, and mint/burn event indexing.
+Backend SDK for PAFI issuer servers — claim, redeem, perp deposit,
+mobile prepare/submit, EIP-7702 delegation, status polling, and the
+`IssuerApiAdapter` that thins issuer controllers to one line per
+endpoint.
 
-> **Server-only.** This package pulls in `jose` and `node:crypto`. Do not bundle into a browser app.
+**Server-only.** Pulls in signer wallets, HTTP clients, ledger
+interfaces. Don't bundle into a browser app — use
+`@pafi-dev/trading` (FE swap/quote) or `@pafi-dev/core` (primitives)
+instead.
 
 ---
 
@@ -15,501 +19,281 @@ ledger, policy engine, EIP-712 issuer signing, relay submission, and mint/burn e
 
 - Node.js >= 18
 - TypeScript >= 5.0
-- `viem` ^2.0.0 and `@pafi-dev/core` ^0.5.16 (peer dependencies)
-
-> **Latest:** `0.5.31` — `RelayService.prepareMint` / `prepareBurn`
-> now auto-quote the operator fee and auto-resolve the PAFI fee
-> recipient. Drop `feeAmount` / `feeRecipient` from your call sites;
-> SDK reads gas price + Chainlink + V4 subgraph internally. See
-> [Changelog](#changelog).
+- `viem` ^2.0.0 (peer)
+- `@pafi-dev/core` (peer — re-exported types)
 
 ---
 
 ## Installation
 
 ```bash
-npm install @pafi-dev/issuer @pafi-dev/core viem
-# or
 pnpm add @pafi-dev/issuer @pafi-dev/core viem
+# Optional ledger backend:
+pnpm add @pafi-dev/issuer-postgres typeorm pg
 ```
 
 ---
 
-## Modules
-
-| Module | What it provides |
-|---|---|
-| `relay/` | `RelayService` — build unsigned UserOps for mint + burn |
-| `auth/` | `AuthService` — SIWE verification + JWT issuance; `authenticateRequest` middleware |
-| `ledger/` | `IPointLedger` interface — implement against your own database |
-| `policy/` | `IPolicyEngine`, `DefaultPolicyEngine` — off-chain balance gate |
-| `indexer/` | `PointIndexer` (mint events) + `BurnIndexer` (burn events) |
-| `balance/` | `BalanceAggregator` — merge off-chain ledger + on-chain `balanceOf` |
-| `api/` | `IssuerApiHandlers` — framework-agnostic HTTP handlers |
-| `pafi-backend/` | `PafiBackendClient` — HTTP client for PAFI paymaster backend |
-
----
-
-## What you must bring
+## What's in this package
 
-The SDK deliberately does not ship production implementations for:
+```
+@pafi-dev/issuer
+├── handlers           — flow handlers (PTClaimHandler, PTRedeemHandler,
+│                        PerpDepositHandler)
+├── api/IssuerApiAdapter
+│                      — single class, every endpoint is one line in
+│                        your controller
+├── api/handleMobilePrepare/Submit
+│                      — mobile claim/redeem orchestrators
+├── api/handleClaimStatus/handleRedeemStatus
+│                      — polling helpers w/ bundler-receipt fallback
+├── api/handleDelegateSubmit
+│                      — EIP-7702 delegation submit (empty-batch + auth)
+├── api/createSdkErrorMapper
+│                      — framework-agnostic error → HTTP status mapper
+├── ledger             — IPointLedger interface + InMemoryCursorStore
+├── userop-store       — IPendingUserOpStore + MemoryPendingUserOpStore
+├── pafi-backend       — sponsor-relayer client + relay/paymaster helpers
+├── auth               — ISessionStore, AuthService (SIWE), MemorySessionStore
+├── relay              — RelayService, FeeManager
+├── pools              — createSubgraphPoolsProvider, NativePtQuoter
+├── policy             — IPolicyEngine + DefaultPolicyEngine
+├── balance            — BalanceAggregator (off-chain + on-chain)
+├── indexer            — PointIndexer, BurnIndexer (singleton workers)
+├── issuer-state       — IssuerStateValidator (registry + cap pre-check)
+└── errors             — PafiSdkError base class for typed errors
+```
 
-| What | Why you own it |
-|---|---|
-| **`IPointLedger`** | Your database, your schema, your row-level locking strategy |
-| **`ISessionStore`** | Must be shared across pods — use Redis or Postgres |
-| **Signing wallet** | Private key must never touch server memory — use KMS |
+> **Removed in 0.6.0** (2026-04-27): `SwapHandler`, `quotePointTokenToUsdt`,
+> and `IssuerApiAdapter.swap()/quote()` — moved to `@pafi-dev/trading`.
+> FE PAFI calls trading directly. `IssuerApiHandlers.handleClaim/handleRedeem`
+> legacy methods + `TopUpRedemptionHandler` (Variant B) also dropped.
 
 ---
 
-## Quick start
-
-```ts
-import { createIssuerService } from "@pafi-dev/issuer";
-import { getContractAddresses } from "@pafi-dev/core";
-import { createPublicClient, createWalletClient, http } from "viem";
-import { base } from "viem/chains";
-import { privateKeyToAccount } from "viem/accounts";
-
-const addrs = getContractAddresses(8453);
-
-// Production: replace with a KMS-backed WalletClient (see "Production signing" below)
-const issuerSignerWallet = createWalletClient({
-  account: privateKeyToAccount(process.env.MINTER_PRIVATE_KEY as `0x${string}`),
-  chain: base,
-  transport: http(process.env.RPC_URL),
-});
-
-const service = createIssuerService({
-  chainId: 8453,
-  pointTokenAddresses: [addrs.pointToken],
-  contracts: {
-    relay:           "0x92327F5c9383796Dd46D43E0995cc938038A98c4",
-    issuerRegistry:  addrs.issuerRegistry,
-    usdt:            addrs.usdt,
-    batchExecutor:   addrs.batchExecutor,
-  },
-  provider: createPublicClient({ chain: base, transport: http(process.env.RPC_URL) }),
-  auth: {
-    jwtSecret: process.env.JWT_SECRET!,
-    domain: "app.example.com",
-  },
-  ledger: new YourPostgresLedger(),          // implements IPointLedger
-  sessionStore: new YourRedisSessionStore(), // implements ISessionStore
-  claim: {
-    issuerSignerWallet,
-    batchExecutorAddress: addrs.batchExecutor,
-  },
-});
+## Architecture
 
-// Mount into your framework (Express, Fastify, NestJS, Hono...)
-app.get("/auth/nonce",  () => service.handlers.handleGetNonce());
-app.post("/auth/login", (req) => service.handlers.handleLogin(req.body));
-app.get("/user",        (req) => service.handlers.handleUser(req.user, req.query));
-app.post("/claim",      (req) => service.handlers.handleClaim(req.user, req.body));
 ```
-
----
-
-## Implementing IPointLedger
-
-Every issuer provides their own database-backed implementation:
-
-```ts
-import type { IPointLedger, LockedMintRequest, MintingStatus } from "@pafi-dev/issuer";
-import type { Address, Hex } from "viem";
-
-export class PostgresPointLedger implements IPointLedger {
-  async getBalance(user: Address, tokenAddress?: Address): Promise<bigint> { ... }
-
-  // Must use a row-level lock (SELECT ... FOR UPDATE) to prevent
-  // concurrent pods from reading the same available balance and double-spending.
-  async lockForMinting(user: Address, amount: bigint, durationMs: number, tokenAddress?: Address): Promise<string> { ... }
-
-  async releaseLock(lockId: string): Promise<void> { ... }
-  async deductBalance(user: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void> { ... }
-  async creditBalance(user: Address, amount: bigint, reason: string, tokenAddress?: Address): Promise<void> { ... }
-  async getLockedRequests(user: Address, tokenAddress?: Address): Promise<LockedMintRequest[]> { ... }
-  async updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void> { ... }
-
-  // Burn flow: reserve → resolve when burn tx confirmed
-  async reservePendingCredit(user: Address, amount: bigint, durationMs: number, tokenAddress?: Address): Promise<string> { ... }
-  async resolveCreditByBurnTx(lockId: string, txHash: Hex): Promise<void> { ... }
-}
+HTTP request (NestJS / Fastify / Express)
+    ↓
+Auth guard            ← issuer-specific (SIWE / Privy / NextAuth)
+    ↓
+Controller            ← thin: routing + DTO + auth context
+    ↓
+IssuerApiAdapter      ← @pafi-dev/issuer (orchestrates flows)
+    ↓
+PTClaimHandler        ← signs MintRequest, locks balance, builds UserOp
+PTRedeemHandler       ← signs BurnRequest, reserves credit, builds UserOp
+PerpDepositHandler    ← Orderly Vault via PAFI Relay
+    ↓
+PostgresPointLedger   ← @pafi-dev/issuer-postgres (TypeORM)
+RelayService          ← UserOp builders for mint/burn
+PafiBackendClient     ← sponsor-relayer proxy
 ```
 
 ---
 
-## Production signing — KMS
-
-In production the `issuerSignerWallet` must be backed by a hardware key.
-The SDK accepts any viem `WalletClient` — wire it to AWS KMS via a custom account:
+## Quick start (NestJS)
 
-```ts
-import { KMSClient } from "@aws-sdk/client-kms";
-import { createWalletClient, http } from "viem";
-import { base } from "viem/chains";
-
-// Custom viem account that delegates signTypedData to KMS.
-// Full DER→(r,s) conversion + v-byte recovery omitted for brevity.
-const kmsAccount = toAccount({
-  address: process.env.KMS_MINTER_ADDRESS as `0x${string}`,
-  async signTypedData(typedData) {
-    const digest = hashTypedData(typedData);
-    const { Signature } = await kms.send(new SignCommand({
-      KeyId: process.env.KMS_MINTER_KEY_ID!,
-      Message: digest,
-      MessageType: "DIGEST",
-      SigningAlgorithm: "ECDSA_SHA_256",
-    }));
-    return derToViem(Signature!); // convert DER → 65-byte viem hex signature
-  },
-});
+Minimal reference at `examples/nestjs-issuer/` — full working backend
+with all 11 endpoints, ~940 LoC total.
 
-const issuerSignerWallet = createWalletClient({
-  account: kmsAccount,
-  chain: base,
-  transport: http(process.env.RPC_URL),
-});
-```
-
----
-
-## Event indexers
-
-Indexers sync on-chain mint/burn events back to the off-chain ledger.
+### 1. Wire `IssuerApiAdapter`
 
 ```ts
-import { PointIndexer, BurnIndexer } from "@pafi-dev/issuer";
+import { Provider } from "@nestjs/common";
+import {
+  IssuerApiAdapter,
+  IssuerStateValidator,
+  PTClaimHandler,
+  PTRedeemHandler,
+  PerpDepositHandler,
+  MemoryPendingUserOpStore,
+  createSubgraphPoolsProvider,
+  type IssuerService,
+} from "@pafi-dev/issuer";
+import { PostgresPointLedger } from "@pafi-dev/issuer-postgres";
 import { getContractAddresses } from "@pafi-dev/core";
 
-const addrs = getContractAddresses(8453);
-
-// Mint indexer: Transfer(0x0 → user) → deducts off-chain locked balance
-const mintIndexer = new PointIndexer({
-  provider: publicClient,
-  pointTokenAddress: addrs.pointToken,
-  ledger,
-  cursorStore,       // persists last-processed block; use Postgres or Redis
-  fromBlock: 28_000_000n,
-  confirmations: 2,
-  pollIntervalMs: 3_000,
-});
-
-// Burn indexer: Transfer(user → 0x0) → resolves pending off-chain credit
-const burnIndexer = new BurnIndexer({
-  provider: publicClient,
-  pointTokenAddress: addrs.pointToken,
-  ledger,
-  cursorStore,
-  matchLockId: async (evt) => {
-    // Return the lockId from reservePendingCredit() that matches this burn.
-    // Typically a DB lookup by (from, amount, status=PENDING).
-    return db.findPendingCreditLockId(evt.from, evt.amount);
-  },
-});
-
-mintIndexer.start();
-burnIndexer.start();
-```
-
-> **Indexers must be singletons.** Run exactly one instance per token per deployment.
-> Use a Kubernetes `Deployment` with `replicas: 1`.
-
----
-
-## PafiBackendClient
-
-HTTP client for requesting paymaster sponsorship from the PAFI backend:
-
-```ts
-import { PafiBackendClient } from "@pafi-dev/issuer";
-
-const pafiClient = new PafiBackendClient({
-  url: "https://api-dev.pacificfinance.org/api/sponsor",
-  issuerId: "gg56",
-  apiKey: process.env.PAFI_API_KEY!,
-  retry: { maxAttempts: 3, maxRetryAfterMs: 5_000 },
-});
-
-const sponsorship = await pafiClient.requestSponsorship({
-  chainId: 8453,
-  scenario: "mint",
-  userOp: {
-    sender: userAddress,
-    callData: userOp.callData,
-    // ...gas fields
+export const issuerApiAdapterProvider: Provider = {
+  provide: ISSUER_API_ADAPTER,
+  useFactory: (issuerService, provider, walletClient, dataSource) => {
+    const ledger = new PostgresPointLedger(dataSource);
+    const { issuerRegistry, batchExecutor } = getContractAddresses(8453);
+
+    return new IssuerApiAdapter({
+      issuerService,
+      ledger,
+      provider,
+      issuerSignerWallet: walletClient,
+      pafiIssuerId: process.env.PAFI_ISSUER_ID,
+
+      ptClaimHandler: new PTClaimHandler({
+        ledger, relayService: issuerService.relay, provider,
+        issuerSignerWallet: walletClient,
+        pointTokenDomainName: "POINT",
+        feeService: issuerService.fee,
+        issuerStateValidator: new IssuerStateValidator(provider, issuerRegistry),
+      }),
+
+      ptRedeemHandler: new PTRedeemHandler({
+        ledger, relayService: issuerService.relay, provider,
+        pointTokenAddress: POINT_TOKEN,
+        batchExecutorAddress: batchExecutor,
+        chainId: 8453,
+        domain: { name: "POINT", verifyingContract: POINT_TOKEN },
+        burnerSignerWallet: walletClient,
+        feeService: issuerService.fee,
+      }),
+
+      perpHandler: new PerpDepositHandler({
+        provider, feeService: issuerService.fee, pointTokenAddress: POINT_TOKEN,
+      }),
+
+      pendingUserOpStore: new MemoryPendingUserOpStore(),
+      pafiBackendClient,  // optional — required for mobile submit / sponsor-relayer
+    });
   },
-  target: {
-    contractAddress: addrs.pointToken,
-    functionSelector: "0x...",
-  },
-});
-
-// Paymaster fields
-// sponsorship.paymaster
-// sponsorship.paymasterData
-// sponsorship.paymasterVerificationGasLimit
-// sponsorship.paymasterPostOpGasLimit
-// Pimlico's re-estimated values — MUST overwrite the userOp's matching
-// fields BEFORE computing the userOpHash, or both AA24 (sender sig) and
-// AA34 (paymaster sig) fire on the bundler. See "Critical: apply gas
-// overrides" below.
-// sponsorship.callGasLimit?
-// sponsorship.verificationGasLimit?
-// sponsorship.preVerificationGas?
-// sponsorship.maxFeePerGas?           // bundler-required floor
-// sponsorship.maxPriorityFeePerGas?
-// sponsorship.expiresAt
+  inject: [...],
+};
 ```
 
-### Critical: apply gas overrides before computing the userOpHash
+Skip handlers you don't need — adapter throws clear "<handler> not
+wired" if the corresponding method is called.
 
-Pimlico's `pm_sponsorUserOperation` does two things the SDK didn't
-previously echo back:
-
-1. **Re-estimates** `callGasLimit` / `verificationGasLimit` /
-   `preVerificationGas`. The paymaster signature signs over these new
-   values.
-2. **Quotes the bundler-required gas price** — `eth_feeHistory` on Base
-   regularly underestimates the bundler floor by 10–15 %, producing
-   `maxFeePerGas must be at least …` rejections.
-
-Both sets of values are now returned on `SponsorshipResponse`. Apply
-them to the userOp **before** calling `computeUserOpHash`:
-
-```ts
-function applyOverrides<T extends Record<string, unknown>>(
-  userOp: T,
-  fields: Awaited<ReturnType<typeof pafiClient.requestSponsorship>> | undefined,
-): T {
-  if (!fields) return userOp;
-  const merged: Record<string, unknown> = { ...userOp };
-  for (const [k, v] of Object.entries(fields)) if (v !== undefined) merged[k] = v;
-  return merged as T;
-}
-
-const fields = await pafiClient.requestSponsorship({ /* ... */ });
-const final = applyOverrides(userOp, fields);
-const userOpHash = computeUserOpHash(final, chainId);  // matches what the bundler will hash
-```
-
-### Bundler receipt fallback for status polling
-
-`PointIndexer.deductBalance` matches `(user, token, amount, oldest
-PENDING)`. When several PENDING locks share the same amount, the
-indexer can resolve a *different* lock than the one the user is
-currently polling — symptom: `/claim/status` returns PENDING forever
-even though the on-chain mint succeeded.
-
-`PafiBackendClient.getUserOpReceipt(userOpHash)` proxies
-`eth_getUserOperationReceipt` through PAFI's authenticated `/bundler/receipt`
-endpoint, letting status handlers short-circuit the indexer:
+### 2. Slim controller
 
 ```ts
-import { PafiBackendClient } from "@pafi-dev/issuer";
-
-// Inside POST /claim/submit, persist the bundler-returned userOpHash on
-// the lock (add a `user_op_hash` column to your locked_mint_requests).
-await ledger.bindMintUserOpHash(lockId, result.userOpHash);
-
-// Inside GET /claim/status/:lockId
-const lock = await ledger.getMintLock(lockId);
-if (lock.status === "PENDING" && lock.userOpHash) {
-  const receipt = await pafiClient.getUserOpReceipt(lock.userOpHash);
-  if (receipt) {
-    const status = receipt.success ? "MINTED" : "FAILED";
-    await ledger.updateMintStatus(lock.id, status, receipt.txHash);
-    return { ...lock, status, txHash: receipt.txHash };
+@Controller()
+export class IssuerController {
+  constructor(@Inject(ISSUER_API_ADAPTER) private api: IssuerApiAdapter) {}
+
+  @Post("claim/prepare")
+  @UseGuards(JwtGuard)
+  async claimPrepare(@User() user: AuthContext, @Body() body) {
+    const [aaNonce, mintRequestNonce] = await Promise.all([
+      fetchAaNonce(this.provider, user.userAddress),
+      fetchMintRequestNonce(this.provider, body.pointTokenAddress, user.userAddress),
+    ]);
+    return wrap(() => this.api.claimPrepare({
+      authenticatedAddress: user.userAddress,
+      chainId: body.chainId,
+      pointTokenAddress: body.pointTokenAddress,
+      amount: BigInt(body.amount),
+      aaNonce, mintRequestNonce,
+    }));
   }
+  // ... other endpoints similarly thin
 }
-return lock;  // bundler hasn't seen it yet — keep polling
 ```
 
-Returns `null` when the bundler hasn't confirmed yet (still in mempool /
-not bundled). The indexer continues to do off-chain accounting in the
-background; the receipt fallback only affects *user-visible status*,
-not balance correctness.
-
----
-
-## Error handling
-
-### AuthError
-
-Thrown by `AuthService` and `authenticateRequest` middleware:
+### 3. Wire error mapper
 
 ```ts
-import { AuthError, type AuthErrorCode } from "@pafi-dev/issuer";
-
-// AuthErrorCode:
-// "INVALID_MESSAGE"    | "INVALID_SIGNATURE" | "NONCE_MISMATCH"
-// "NONCE_EXPIRED"      | "TOKEN_EXPIRED"     | "TOKEN_INVALID"
-// "SESSION_NOT_FOUND"  | "DOMAIN_MISMATCH"   | "CHAIN_MISMATCH"
-
-try {
-  const user = await authService.login(message, signature);
-} catch (err) {
-  if (err instanceof AuthError) {
-    console.log(err.code); // AuthErrorCode
-  }
-}
-```
-
-### PafiBackendError
-
-Thrown by `PafiBackendClient`:
+import { createSdkErrorMapper, type SdkErrorBody } from "@pafi-dev/issuer";
+import {
+  NotFoundException, ForbiddenException,
+  UnprocessableEntityException, ServiceUnavailableException,
+} from "@nestjs/common";
+
+const sdkErrorMapper: (err: unknown) => never = createSdkErrorMapper({
+  notFound:           (b: SdkErrorBody) => new NotFoundException(b),
+  forbidden:          (b: SdkErrorBody) => new ForbiddenException(b),
+  unprocessable:      (b: SdkErrorBody) => new UnprocessableEntityException(b),
+  serviceUnavailable: (b: SdkErrorBody) => new ServiceUnavailableException(b),
+});
 
-```ts
-import { PafiBackendError, type PafiBackendErrorCode } from "@pafi-dev/issuer";
-
-// PafiBackendErrorCode:
-// "RATE_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED_DAILY" | "RATE_LIMIT_EXCEEDED_PER_USER"
-// "RATE_LIMITER_UNAVAILABLE"
-// "INTENT_REJECTED"     | "MINT_CAP_EXCEEDED"         | "ISSUER_INACTIVE"
-// "ISSUER_UNAUTHORIZED" | "USER_UNAUTHORIZED"
-// "PAYMASTER_UNAVAILABLE" | "TARGET_NOT_ALLOWLISTED"
-// "BAD_REQUEST"         | "INTERNAL_ERROR"            | "TIMEOUT" | "NETWORK_ERROR"
-
-try {
-  await pafiClient.requestSponsorship(request);
-} catch (err) {
-  if (err instanceof PafiBackendError) {
-    if (err.code === "RATE_LIMIT_EXCEEDED") {
-      // err.retryAfter — seconds to wait before retrying
-    }
-  }
+async function wrap<T>(fn: () => Promise<T>): Promise<T> {
+  try { return await fn(); }
+  catch (err) { sdkErrorMapper(err); }
 }
 ```
 
----
+Every typed SDK error (`PafiSdkError` subclass) routes through this
+funnel — `code`, `safeToRetry`, `details`, `httpStatus` come straight
+off the error class. No magic strings, no per-error mapping.
 
-## Changelog
-
-### 0.5.31
-
-`RelayService.prepareMint` / `prepareBurn` now auto-quote the operator
-fee + auto-resolve the PAFI fee recipient when the service is
-constructed with `provider + chainId`. `createIssuerService` wires
-this automatically — issuer integrations don't need to change
-anything to pick it up.
-
-**API changes** (additive, backwards-compatible):
-
-- `RelayService` constructor accepts an optional `RelayServiceConfig`
-  with `provider` + `chainId`. When set, callers can drop `feeAmount`
-  / `feeRecipient` from `prepareMint` / `prepareBurn` calls — the
-  service runs `quoteOperatorFeePt` (Chainlink ETH/USD + V4 subgraph
-  PT/USDT spot price) internally and pulls the canonical recipient
-  from `getContractAddresses(chainId).pafiFeeRecipient`.
-- `prepareBurn` is now `async` (was sync) — the auto-quote requires
-  RPC + subgraph reads. Callers must `await`. `PTRedeemHandler`
-  already does this.
-- `feeAmount: 0n` explicit means "no fee transfer" (force unsponsored
-  fallback variant). `undefined` means "auto-quote".
-- Existing callers that pass `feeAmount + feeRecipient` keep working
-  — those values override the auto-resolve.
-
-**Migration**: in your controller, drop the manual fee fetch when
-calling `relayService.prepareMint`:
-
-```diff
-- const { pafiFeeRecipient: feeRecipient } = getContractAddresses(chainId);
-- const feeAmount = await issuerService.fee.estimateGasFee();
-  const userOp = await relayService.prepareMint({
-    ...,
--   feeAmount,
--   feeRecipient,
-  });
-```
+---
 
-### 0.5.28
+## `IssuerApiAdapter` methods
+
+| Method | HTTP route in your controller |
+| --- | --- |
+| `pools(authedAddr, chainId, pointToken)` | `GET /pools` |
+| `user(authedAddr, chainId, userAddr, pointToken)` | `GET /user` |
+| `claim({ ...nonces, ... })` | `POST /claim` (web — sync `calls[]`) |
+| `redeem({ amount, aaNonce, ... })` | `POST /redeem` |
+| `perpDeposit({ amount, brokerId, aaNonce, ... })` | `POST /perp-deposit` |
+| `claimPrepare(...)` / `claimSubmit(...)` | Mobile claim flow |
+| `redeemPrepare(...)` / `redeemSubmit(...)` | Mobile redeem flow |
+| `claimStatus(authedAddr, lockId)` / `redeemStatus(...)` | Status polling |
+| `delegateStatus(authedAddr, chainId)` | EIP-7702 — check delegation installed |
+| `delegatePrepare(authedAddr, chainId)` | EIP-7702 — build authorization hash |
+| `delegateSubmit({ authSig, delegationNonce, aaNonce, ... })` | EIP-7702 — relay empty-batch UserOp |
+
+> `swap()` and `quote()` removed in 0.6.0 — see `@pafi-dev/trading`.
+> `config()` and `gasFee()` are optional read endpoints; FE can call
+> `getContractAddresses()` and `quoteOperatorFeeUsdt()` from
+> `@pafi-dev/core` directly with no backend round-trip.
 
-`PafiBackendClient.getUserOpReceipt(userOpHash)` added.
+---
 
-**Why.** When several PENDING mint/redeem locks share the same amount,
-`PointIndexer` / `BurnIndexer` resolve them by `(user, token, amount,
-oldest PENDING)` — the userOp's actual bundler hash isn't part of the
-match. A lock the user is *currently polling* can be left PENDING while
-a *sibling* lock gets the on-chain `tx_hash`, so `/claim/status`
-returns PENDING forever even though the mint succeeded.
+## Mobile prepare/submit flow
 
-The new method calls PAFI's authenticated bundler-receipt proxy and
-returns `{ success, txHash, blockNumber } | null`. Status handlers can
-look up the user's specific userOpHash and bypass the indexer race
-entirely:
+Mobile clients (Privy expo) can't `useSign7702Authorization` — they
+sign just the `userOpHash` via `personal_sign`. The adapter handles
+the orchestration:
 
 ```ts
-const receipt = await pafiClient.getUserOpReceipt(lock.userOpHash);
-if (receipt?.success) markMinted(lock.id, receipt.txHash);
-```
-
-Pair this with a `user_op_hash` column on your locks table that you set
-inside `/claim/submit` from the value returned by `relayUserOperation`.
+// 1. mobile sends POST /claim/prepare → backend runs:
+const prepared = await api.claimPrepare({ authenticatedAddress, chainId, pointTokenAddress, amount, aaNonce, mintRequestNonce });
+// returns: { lockId, userOpHash, typedData, userOpHashFallback?, typedDataFallback?, sponsored, needsDelegation, ... }
 
-### 0.5.27
+// 2. mobile signs prepared.userOpHash via Privy personal_sign
 
-`SponsorshipResponse` now carries Pimlico's re-estimated gas + bundler
-gas price.
+// 3. mobile sends POST /claim/submit → backend runs:
+const result = await api.claimSubmit({ authenticatedAddress, lockId, signature, variant: "sponsored" | "fallback" });
+// returns: { userOpHash } — bundler hash for status polling
+```
 
-**Why this fixes AA34 / AA24.** `pm_sponsorUserOperation` re-estimates
-`callGasLimit` / `verificationGasLimit` / `preVerificationGas` AND
-quotes the bundler-required `maxFeePerGas` / `maxPriorityFeePerGas`. The
-paymaster signature is computed *over those new values*, not the values
-the SDK originally proposed. If the caller submits the userOp with the
-*original* gas fields:
+`handleMobileSubmit` enforces ownership: `entry.sender ===
+authenticatedAddress`. Without this, user A could submit user B's
+pending UserOp once they leak/guess the lockId.
 
-- The bundler hashes the on-chain UserOp with the original values
-- The paymaster signature recovers a different signer → `AA34
-  signature error`
-- The user signature, computed over a different `userOpHash`, also
-  fails → `AA24 signature error` (whichever fires first depends on the
-  validation order)
+---
 
-The response now exposes:
+## Status polling
 
 ```ts
-interface SponsorshipResponse {
-  paymaster: Address;
-  paymasterData: Hex;
-  paymasterVerificationGasLimit: bigint;
-  paymasterPostOpGasLimit: bigint;
-  callGasLimit?: bigint;             // NEW — Pimlico re-estimate
-  verificationGasLimit?: bigint;     // NEW
-  preVerificationGas?: bigint;       // NEW
-  maxFeePerGas?: bigint;             // NEW — bundler-required floor
-  maxPriorityFeePerGas?: bigint;     // NEW
-  expiresAt: number;
-}
+// GET /claim/status/:lockId
+const status = await api.claimStatus(user.userAddress, lockId);
+// { lockId, status: 'PENDING' | 'MINTED' | 'EXPIRED' | 'FAILED', txHash, ... }
 ```
 
-**Callers must merge these (skipping `undefined`) into the userOp
-before computing `userOpHash`** — see the
-"Critical: apply gas overrides" section above.
+Falls back to bundler receipt when `status === 'PENDING'` and
+`userOpHash` is bound — bypasses `PointIndexer`'s amount-match race
+(multiple PENDING locks with the same amount can be resolved to the
+wrong tx_hash).
 
-### 0.5.26
+---
 
-`@pafi-dev/core` peer dependency bumped to `0.5.16` to pull in the v0.8
-EIP-712 userOpHash + `buildUserOpTypedData()` helpers. This is what
-makes the EIP-7702 mobile flow validate cleanly on Pimlico's
-`Simple7702Account` (no AA24).
+## Error classes
 
-### 0.4.0
-- `PafiBackendClient` added — HTTP client for PAFI paymaster backend with retry logic and bigint serialization
-- `SponsorAuth` support — issuer signs EIP-712 authorization for FE to request paymaster sponsorship
-- `PAYMASTER_UNAVAILABLE`, `TARGET_NOT_ALLOWLISTED` added to `PafiBackendErrorCode`
+All SDK errors inherit `PafiSdkError`. Subclasses + their HTTP status:
 
-### 0.3.0-beta.10
-- `MemoryPointLedger` removed from public exports — each issuer must implement `IPointLedger`
-- `PrivateKeySigner` / `IIssuerSigner` removed — SDK accepts viem `WalletClient` directly
-- `ledger` is now a required field in `IssuerServiceConfig`
-- `handleClaim` added to `IssuerApiHandlers`
+| Error | `httpStatus` | `safeToRetry` |
+| --- | --- | --- |
+| `PendingUserOpNotFoundError` | `not_found` | false |
+| `PendingUserOpForbiddenError` | `forbidden` | false |
+| `LockNotFoundError` | `not_found` | false |
+| `IssuerStateError` | `unprocessable` | true if `MINT_CAP_EXCEEDED` |
+| `PerpDepositError` | `unprocessable` | true if `RELAY_FEE_EXCEEDS_AMOUNT` |
+| `PTClaimError`, `PTRedeemError` | `unprocessable` | false |
+| `BundlerNotConfiguredError` | `service_unavailable` | false |
+| `BundlerRejectedError` | `unprocessable` | false |
 
-### 0.3.0-beta.9
-- `PTRedeemHandler` enforces on-chain balance check before signing `BurnRequest`
+---
 
-### 0.3.0-beta.8
-- `BalanceAggregator`, `BurnIndexer`, `PTRedeemHandler`, `TopUpRedemptionHandler`
+## License
 
-### 0.3.0-alpha.0
-- Initial `RelayService`, `PointIndexer`, `AuthService`, `IssuerApiHandlers`
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pafi-dev/issuer",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Issuer backend API and services for the PAFI point token system",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,7 +23,7 @@
   ],
   "dependencies": {
     "jose": "^5.9.0",
-    "@pafi-dev/core": "0.6.0"
+    "@pafi-dev/core": "0.6.2"
   },
   "peerDependencies": {
     "viem": "^2.0.0"