@pafi-dev/issuer 0.12.6 → 0.13.0

package/README.md

@@ -4,26 +4,51 @@
 [![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).
 
 ---
 
-## Requirements
+## What's new in 0.13.0 (breaking)
 
-- Node.js >= 18
-- TypeScript >= 5.0
-- `viem` ^2.0.0 (peer)
-- `@pafi-dev/core` (peer — re-exported types)
+Tracks `@pafi-dev/core@0.10.0`. The `ReceiverConsent` mint path was
+removed from the entire SDK chain because the deployed `PointToken`
+contract never had it — what was conceptually a "sponsored mint" is
+actually the path-2 `MintForRequest` sig-gated mint with sponsor-relayer
+paying gas.
+
+| Change | Detail |
+|---|---|
+| `ApiUserResponse.receiverConsentNonce` removed | The `/user` endpoint no longer returns this field. Callers using it for signing should call the path-2 mint flow with `mintRequestNonce` instead. |
+| `UserDto.receiverConsentNonce` removed | Wire DTO drops the field — `IssuerApiAdapter.user()` response is one field smaller. |
+| Action required for issuer backends | Bump `@pafi-dev/core` to `0.10.0`, remove any `receiverConsentNonce` field from your own DTOs / mobile API surface, drop FE code that signed `ReceiverConsent` typed data. |
+
+### What's new in v1.6 / 0.12.x
+
+| Change | Detail |
+|---|---|
+| `RelayService.prepareMint` branches direct vs wrapper | Auto-detects `MintFeeWrapper` from chainId. Direct: `pointToken.mint(...)`. Wrapper: `mintFeeWrapper.mintWithFee(...)` |
+| `PTClaimHandler` auto-resolves wrapper | No env config needed — `getContractAddresses(chainId).mintFeeWrapper`. Override via `mintFeeWrapperAddress` for fork tests |
+| `PointIndexer` wrapper mode | Listens to `MintFeeWrapper.MintWithFee(pointToken, to, gross, net, fee)` instead of `Transfer(0x0→user)` when wrapper is configured |
+| `IssuerStateValidator` v1.6 struct | Reads 7-field Issuer struct + queries `MintingOracle.tokenCaps()` for caps |
+| `/config` exposes `mintFeeBpsByToken` | FE can preview "you'll receive net = gross × (1-bps/10000)" before user signs |
+| Operator fee fallback enabled by default | Mint not blocked when subgraph has no pool yet |
+| `PafiBackendClient` error envelope fix | Reads nested `error.message` — exposes Pimlico AA codes instead of generic "HTTP 500" |
 
 ---
 
+## Requirements
+
+- Node.js ≥ 18
+- TypeScript ≥ 5.0
+- `viem` ^2.0.0 (peer)
+- `@pafi-dev/core` (transitive — re-exported)
+
 ## Installation
 
 ```bash
@@ -38,11 +63,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 +78,16 @@ 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 (v1.6 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 (v1.6 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 +99,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
+                        (v1.6: routes to wrapper.mintWithFee)
 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
 ```
 
 ---
 
+## v1.6 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 +168,6 @@ import {
   PTRedeemHandler,
   PerpDepositHandler,
   MemoryPendingUserOpStore,
-  createSubgraphPoolsProvider,
   type IssuerService,
 } from "@pafi-dev/issuer";
 import { PostgresPointLedger } from "@pafi-dev/issuer-postgres";
@@ -117,41 +175,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 +248,6 @@ export class IssuerController {
       aaNonce, mintRequestNonce,
     }));
   }
-  // ... other endpoints similarly thin
 }
 ```
 
@@ -191,16 +255,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 +269,148 @@ 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` | v1.6: 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 | v1.6 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 — v1.6 default)
+//   - 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 |
+
+---
+
+## v1.5 → v1.6 migration checklist
+
+1. `pnpm add @pafi-dev/issuer@latest @pafi-dev/core@latest` (≥ 0.12.7 + ≥ 0.9.6)
+2. Update env: drop `MINT_FEE_WRAPPER_ADDRESS` if previously set
+   (SDK auto-resolves from chainId)
+3. Re-deploy your issuer backend — `RelayService` now branches based on
+   wrapper presence; calldata changes from `mint(...)` to `mintWithFee(...)`
+4. Verify on-chain prerequisites (PAFI ops responsibility):
+   - `IssuerRegistry.addIssuer(...)` cascade configures wrapper recipients
+   - `MintingOracle.registerToken(pointToken, issuer)` sets cap
+   - `PointToken.addMinter(signerAddress)` whitelists your signer
+5. Indexer will pick up `MintWithFee` events automatically. If you wrote
+   custom Transfer-event consumers, switch to `MintWithFee`.
+6. `/config` response now includes `mintFeeBpsByToken` — FE can preview
+   fee without round-tripping `getMintFeeBps()` separately.
 
 ---
 
+## References
+
+- Architecture: [`ARCHITECTURE.md`](../../ARCHITECTURE.md) at SDK root
+- Fee flow & math: [`docs/FEE_FLOW.md`](../../../docs/FEE_FLOW.md)
+- v1.6 SC commits: `cc26f62` (struct simplification), wrapper added
+
 ## License
 
 Apache-2.0

package/dist/index.cjs

@@ -1846,16 +1846,14 @@ var IssuerApiHandlers = class _IssuerApiHandlers {
         { requested: pointToken }
       );
     }
-    const [mintRequestNonce, receiverConsentNonce, offChainBalance, onChainBalance, minter] = await Promise.all([
+    const [mintRequestNonce, offChainBalance, onChainBalance, minter] = await Promise.all([
       (0, import_core6.getMintRequestNonce)(this.provider, pointToken, normalizedAuthed),
-      (0, import_core6.getReceiverConsentNonce)(this.provider, pointToken, normalizedAuthed),
       this.ledger.getBalance(normalizedAuthed, pointToken),
       (0, import_core6.getPointTokenBalance)(this.provider, pointToken, normalizedAuthed),
       (0, import_core6.isMinter)(this.provider, pointToken, normalizedAuthed)
     ]);
     return {
       mintRequestNonce,
-      receiverConsentNonce,
       offChainBalance,
       onChainBalance,
       totalBalance: offChainBalance + onChainBalance,
@@ -3151,7 +3149,6 @@ var IssuerApiAdapter = class {
     );
     return {
       mintRequestNonce: result.mintRequestNonce.toString(),
-      receiverConsentNonce: result.receiverConsentNonce.toString(),
       offChainBalance: result.offChainBalance.toString(),
       onChainBalance: result.onChainBalance.toString(),
       totalBalance: result.totalBalance.toString(),
@@ -4739,7 +4736,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.12.5" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.13.0" : "dev";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdapterMisconfiguredError,