@pafi-dev/issuer 0.12.7 → 0.15.0

package/README.md

@@ -4,25 +4,30 @@
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 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.
+mobile prepare/submit, EIP-7702 delegation, status polling, redemption
+restriction enforcement, and the `IssuerApiAdapter` that thins issuer
+controllers to one line per endpoint.
 
 **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.
+`@pafi-dev/trading` (FE swap/quote) or `@pafi-dev/core` (primitives).
 
 ---
 
+## v0.15.0 — Uniswap V3 migration (breaking)
+
+- `createSubgraphPoolsProvider` now returns the V3 `PoolKey` shape (`{ token0, token1, fee }`) instead of the V4 shape (`{ currency0, currency1, fee, tickSpacing, hooks }`). Pulls through from `@pafi-dev/core`.
+- New `onError?: (err: Error) => void` option — forward recoverable errors (network, GraphQL, parse) to your observability stack. Throws inside the callback are swallowed so the provider stays total.
+- `feeTier` is range-checked (uint24, < 1_000_000) before building the `PoolKey`; invalid values are skipped with a console.error + `onError` invocation.
+- Subgraph endpoint default → `…/pafi-subgraph-v4` (PAFI V3-fork DEX + extensions); see `@pafi-dev/core` for the constant.
+- Bumps peer-deps on `@pafi-dev/core` to `^0.13.0` (V3 types + ABIs).
+
 ## Requirements
 
-- Node.js >= 18
-- TypeScript >= 5.0
+- Node.js ≥ 18
+- TypeScript ≥ 5.0
 - `viem` ^2.0.0 (peer)
-- `@pafi-dev/core` (peer — re-exported types)
-
----
+- `@pafi-dev/core` ^0.13.0 (transitive — re-exported)
 
 ## Installation
 
@@ -38,11 +43,9 @@ pnpm add @pafi-dev/issuer-postgres typeorm pg
 
 ```
 @pafi-dev/issuer
-├── handlers           — flow handlers (PTClaimHandler, PTRedeemHandler,
-│                        PerpDepositHandler)
+├── handlers           — PTClaimHandler, PTRedeemHandler, PerpDepositHandler
 ├── api/IssuerApiAdapter
-│                      — single class, every endpoint is one line in
-│                        your controller
+│                      — single class, every endpoint is one line in controller
 ├── api/handleMobilePrepare/Submit
 │                      — mobile claim/redeem orchestrators
 ├── api/handleClaimStatus/handleRedeemStatus
@@ -55,20 +58,15 @@ pnpm add @pafi-dev/issuer-postgres typeorm pg
 ├── userop-store       — IPendingUserOpStore + MemoryPendingUserOpStore
 ├── pafi-backend       — sponsor-relayer client + relay/paymaster helpers
 ├── auth               — ISessionStore, AuthService (SIWE), MemorySessionStore
-├── relay              — RelayService, FeeManager
+├── relay              — RelayService (wrapper-aware), 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)
+├── indexer            — PointIndexer (wrapper + direct mode), BurnIndexer
+├── issuer-state       — IssuerStateValidator (7-field struct + oracle.tokenCaps)
+├── redemption         — RedemptionService (per-issuer policy enforcement)
 └── errors             — PafiSdkError base class for typed errors
 ```
 
-> **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.
-
 ---
 
 ## Architecture
@@ -80,23 +78,63 @@ Auth guard            ← issuer-specific (SIWE / Privy / NextAuth)
     ↓
 Controller            ← thin: routing + DTO + auth context
     ↓
-IssuerApiAdapter      ← @pafi-dev/issuer (orchestrates flows)
+IssuerApiAdapter      ← orchestrates flows
     ↓
-PTClaimHandler        ← signs MintRequest, locks balance, builds UserOp
+PTClaimHandler        ← signs MintForRequest, locks balance, builds UserOp
+                        (routes to wrapper.mintWithFee when wrapper configured)
 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
+IPointLedger          ← your DB impl (Postgres recommended)
+RelayService          ← UserOp builders (auto-branches direct vs wrapper)
 PafiBackendClient     ← sponsor-relayer proxy
 ```
 
 ---
 
+## Wrapper-mediated mint flow
+
+```
+[FE / mobile] → POST /claim/prepare
+    ↓
+[gg56] IssuerApiAdapter.claimPrepare()
+    ↓
+[gg56] PTClaimHandler:
+    1. Lock off-chain balance (gross amount)
+    2. Pre-validate via IssuerStateValidator (oracle cap check)
+    3. Sign MintForRequest EIP-712 with receiver = wrapper
+    4. Build UserOp callData:
+       BatchExecute([
+         { mintFeeWrapper, mintWithFee(pt, user, gross, deadline, sig) },
+         { pointToken, transfer(pafiFeeRecipient, operatorFeePT) }
+       ])
+    ↓
+[gg56] PafiBackendClient.requestSponsorship() → sponsor-relayer
+    ↓
+[sponsor-relayer] decode calldata, recognize MINT_WITH_FEE (0x5284d08b),
+                  validate intent, forward to Pimlico paymaster
+    ↓
+[gg56] returns { userOp, typedData, userOpHash, sponsored: true|false,
+                 typedDataFallback, userOpHashFallback }
+    ↓
+[FE / mobile] sign typedData via signTypedData_v4
+    ↓
+[FE / mobile] POST /claim/submit { lockId, signature, variant }
+    ↓
+[gg56] forwards signed UserOp to Pimlico bundler → on-chain mint
+    ↓
+[chain] wrapper.mintWithFee → PointToken.mint(gross to wrapper) →
+        wrapper splits fee to recipients → transfers net to user
+    ↓
+[gg56] PointIndexer (wrapper mode) catches MintWithFee event →
+       deduct off-chain balance, lock → MINTED
+```
+
+---
+
 ## Quick start (NestJS)
 
-Minimal reference at `examples/nestjs-issuer/` — full working backend
-with all 11 endpoints, ~940 LoC total.
+Minimal reference at `examples/nestjs-issuer/` — full working backend.
 
 ### 1. Wire `IssuerApiAdapter`
 
@@ -109,7 +147,6 @@ import {
   PTRedeemHandler,
   PerpDepositHandler,
   MemoryPendingUserOpStore,
-  createSubgraphPoolsProvider,
   type IssuerService,
 } from "@pafi-dev/issuer";
 import { PostgresPointLedger } from "@pafi-dev/issuer-postgres";
@@ -117,41 +154,48 @@ import { getContractAddresses } from "@pafi-dev/core";
 
 export const issuerApiAdapterProvider: Provider = {
   provide: ISSUER_API_ADAPTER,
-  useFactory: (issuerService, provider, walletClient, dataSource) => {
+  useFactory: (issuerService, provider, walletClient, dataSource, config) => {
     const ledger = new PostgresPointLedger(dataSource);
     const { issuerRegistry, batchExecutor } = getContractAddresses(8453);
+    const chainId = config.get<number>("CHAIN_ID");
+    const pointToken = config.get<`0x${string}`>("POINT_TOKEN_ADDRESS");
 
     return new IssuerApiAdapter({
       issuerService,
       ledger,
       provider,
       issuerSignerWallet: walletClient,
-      pafiIssuerId: process.env.PAFI_ISSUER_ID,
+      pafiIssuerId: config.get("PAFI_ISSUER_ID"),
 
       ptClaimHandler: new PTClaimHandler({
-        ledger, relayService: issuerService.relay, provider,
+        ledger,
+        relayService: issuerService.relay,
+        provider,
         issuerSignerWallet: walletClient,
-        pointTokenDomainName: "POINT",
+        pointTokenDomainName: config.get("POINT_TOKEN_DOMAIN_NAME"),
         feeService: issuerService.fee,
         issuerStateValidator: new IssuerStateValidator(provider, issuerRegistry),
+        // mintFeeWrapperAddress: optional override; SDK auto-resolves from chainId
       }),
 
       ptRedeemHandler: new PTRedeemHandler({
-        ledger, relayService: issuerService.relay, provider,
-        pointTokenAddress: POINT_TOKEN,
+        ledger,
+        relayService: issuerService.relay,
+        provider,
+        pointTokenAddress: pointToken,
         batchExecutorAddress: batchExecutor,
-        chainId: 8453,
-        domain: { name: "POINT", verifyingContract: POINT_TOKEN },
+        chainId,
+        domain: { name: config.get("POINT_TOKEN_DOMAIN_NAME"), verifyingContract: pointToken },
         burnerSignerWallet: walletClient,
         feeService: issuerService.fee,
       }),
 
       perpHandler: new PerpDepositHandler({
-        provider, feeService: issuerService.fee, pointTokenAddress: POINT_TOKEN,
+        provider, feeService: issuerService.fee, pointTokenAddress: pointToken,
       }),
 
       pendingUserOpStore: new MemoryPendingUserOpStore(),
-      pafiBackendClient,  // optional — required for mobile submit / sponsor-relayer
+      pafiBackendClient,  // optional — sponsor-relayer client for sponsored flows
     });
   },
   inject: [...],
@@ -183,7 +227,6 @@ export class IssuerController {
       aaNonce, mintRequestNonce,
     }));
   }
-  // ... other endpoints similarly thin
 }
 ```
 
@@ -191,16 +234,12 @@ export class IssuerController {
 
 ```ts
 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),
+
+const sdkErrorMapper = createSdkErrorMapper({
+  notFound:           (b) => new NotFoundException(b),
+  forbidden:          (b) => new ForbiddenException(b),
+  unprocessable:      (b) => new UnprocessableEntityException(b),
+  serviceUnavailable: (b) => new ServiceUnavailableException(b),
 });
 
 async function wrap<T>(fn: () => Promise<T>): Promise<T> {
@@ -209,91 +248,129 @@ async function wrap<T>(fn: () => Promise<T>): Promise<T> {
 }
 ```
 
-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.
-
 ---
 
 ## `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.
+| Method | HTTP route | Notes |
+| --- | --- | --- |
+| `pools(authedAddr, chainId, pointToken)` | `GET /pools` | |
+| `user(authedAddr, chainId, userAddr, pointToken)` | `GET /user` | |
+| `config(chainId)` | `GET /config` | Includes `mintFeeBpsByToken` + `contracts.mintFeeWrapper` |
+| `claim({ ...nonces })` | `POST /claim` (web — sync `calls[]`) | |
+| `redeem({ amount, aaNonce, ... })` | `POST /redeem` | |
+| `perpDeposit({ amount, brokerId, aaNonce, ... })` | `POST /perp-deposit` | |
+| `claimPrepare(...)` / `claimSubmit(...)` | Mobile claim flow | wrapper-aware |
+| `redeemPrepare(...)` / `redeemSubmit(...)` | Mobile redeem flow | |
+| `claimStatus(authedAddr, lockId)` / `redeemStatus(...)` | Status polling | |
+| `delegateStatus(authedAddr, chainId)` | EIP-7702 — check delegation | |
+| `delegatePrepare(authedAddr, chainId)` | EIP-7702 — build auth hash | |
+| `delegateSubmit({ authSig, ... })` | EIP-7702 — relay empty-batch | |
 
 ---
 
-## Mobile prepare/submit flow
+## Redemption restriction (v0.10+)
 
-Mobile clients (Privy expo) can't `useSign7702Authorization` — they
-sign just the `userOpHash` via `personal_sign`. The adapter handles
-the orchestration:
+Per-issuer policy enforced at `/redeem/prepare` time. Fetched from
+PAFI issuer-api with 5-min cache + fail-open default.
 
 ```ts
-// 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, ... }
+import { RedemptionService, PolicyProvider } from "@pafi-dev/issuer";
+import { PostgresRedemptionHistoryStore } from "@pafi-dev/issuer-postgres";
+
+const redemption = new RedemptionService({
+  policyProvider: new PolicyProvider({
+    chainId: 8453,
+    issuerId: "gg56",
+    apiKey: process.env.PAFI_API_KEY,
+  }),
+  historyStore: new PostgresRedemptionHistoryStore(dataSource),
+});
+```
+
+Wire to `createIssuerService({ redemption: {...} })`. Adapter exposes
+`/redemption/preview` + `/redemption/evaluate` automatically.
+
+---
 
-// 2. mobile signs prepared.userOpHash via Privy personal_sign
+## Mobile prepare/submit flow
 
-// 3. mobile sends POST /claim/submit → backend runs:
-const result = await api.claimSubmit({ authenticatedAddress, lockId, signature, variant: "sponsored" | "fallback" });
+```ts
+// 1. mobile → POST /claim/prepare → backend runs:
+const prepared = await api.claimPrepare({
+  authenticatedAddress, chainId, pointTokenAddress, amount, aaNonce, mintRequestNonce,
+});
+// returns: {
+//   lockId, userOpHash, typedData,
+//   userOpHashFallback, typedDataFallback,
+//   sponsored,           // true if paymaster signed; false → use fallback
+//   needsDelegation,     // true if user EOA not delegated yet
+//   feeAmount, signatureDeadline, expiresInSeconds,
+// }
+
+// 2. mobile signs typedData via Privy/MetaMask signTypedData_v4
+//    (NOT personal_sign — Pimlico Simple7702Account does raw ecrecover)
+//    If `sponsored: false`, sign `typedDataFallback` instead
+
+// 3. mobile → POST /claim/submit:
+const result = await api.claimSubmit({
+  authenticatedAddress, lockId, signature,
+  variant: prepared.sponsored ? "sponsored" : "fallback",
+});
 // returns: { userOpHash } — bundler hash for status polling
 ```
 
 `handleMobileSubmit` enforces ownership: `entry.sender ===
-authenticatedAddress`. Without this, user A could submit user B's
-pending UserOp once they leak/guess the lockId.
+authenticatedAddress`. Lock has 15-min TTL.
 
 ---
 
-## Status polling
+## PointIndexer modes
 
 ```ts
-// GET /claim/status/:lockId
-const status = await api.claimStatus(user.userAddress, lockId);
-// { lockId, status: 'PENDING' | 'MINTED' | 'EXPIRED' | 'FAILED', txHash, ... }
+// Default — auto-resolves wrapper from chainId
+const service = createIssuerService({
+  chainId: 8453,
+  // ...
+  indexer: { autoStart: true, pollIntervalMs: 5000 },
+});
+
+// Indexer listens to:
+//   - mode wrapper:  MintFeeWrapper.MintWithFee filtered by pointToken
+//                    (when wrapper is configured at chainId)
+//   - mode direct:   PointToken.Transfer(0x0 → user) (legacy / no wrapper)
 ```
 
-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).
+Override for fork tests:
+```ts
+indexer: { mintFeeWrapperAddress: "0x000...dead" }  // force direct mode
+```
 
 ---
 
 ## Error classes
 
-All SDK errors inherit `PafiSdkError`. Subclasses + their HTTP status:
+All SDK errors inherit `PafiSdkError`. Subclasses + HTTP mapping:
 
 | Error | `httpStatus` | `safeToRetry` |
 | --- | --- | --- |
 | `PendingUserOpNotFoundError` | `not_found` | false |
 | `PendingUserOpForbiddenError` | `forbidden` | false |
 | `LockNotFoundError` | `not_found` | false |
-| `IssuerStateError` | `unprocessable` | true if `MINT_CAP_EXCEEDED` |
+| `IssuerStateError` (`ISSUER_NOT_REGISTERED` / `ISSUER_INACTIVE` / `MINT_CAP_EXCEEDED`) | `unprocessable` | true if cap exceeded |
 | `PerpDepositError` | `unprocessable` | true if `RELAY_FEE_EXCEEDS_AMOUNT` |
 | `PTClaimError`, `PTRedeemError` | `unprocessable` | false |
 | `BundlerNotConfiguredError` | `service_unavailable` | false |
 | `BundlerRejectedError` | `unprocessable` | false |
+| `RedemptionPolicyError` (`REDEMPTION_DENIED` / `RATE_LIMIT_EXCEEDED` / ...) | `unprocessable` | varies |
 
 ---
 
+## References
+
+- Architecture: [`ARCHITECTURE.md`](../../ARCHITECTURE.md) at SDK root
+- Fee flow & math: [`docs/FEE_FLOW.md`](../../../docs/FEE_FLOW.md)
+
 ## License
 
 Apache-2.0