@pafi-dev/issuer 0.3.0-beta.9 → 0.5.0

package/README.md

@@ -1,352 +1,323 @@
 # @pafi-dev/issuer
 
-Issuer backend boilerplate for the PAFI point token system. Wraps
-`@pafi-dev/core` with everything a partner needs to run the off-chain side
-of the mint-and-cash-out flow: authentication, point ledger, policy
-engine, EIP-712 issuer signing, relay submission, mint event indexing,
-and framework-agnostic HTTP handlers.
-
-## What's new in 0.3.0-alpha.0 — sponsored UserOp flow (v1.4 preview)
-
-Preview release that wires the SDK into the new **sponsored path**:
-user EOAs delegate to a BatchExecutor via EIP-7702, UserOps are
-signed by the user and submitted to a Bundler, and gas is paid by
-Coinbase Paymaster — proxied through the new PAFI-hosted
-`paymaster-proxy` service.
-
-**What ships in this alpha:**
-
-- `PafiBackendClient` — HTTP client for `paymaster-proxy` with retry +
-  backoff on `safeToRetry` errors (opt-in via `retry.maxAttempts`)
-- `BalanceAggregator` — merge off-chain + on-chain balance into one number
-- `BurnIndexer` — watches `Transfer(user → 0x0)` events, finalizes
-  pending off-chain credits for the reverse flow
-- `IPointLedger.reservePendingCredit()` / `resolveCreditByBurnTx()` —
-  additive ledger methods for burn→credit flow
-- `ApiConfigResponse.pafiWebUrl` + `contracts.pointTokens[]` — new
-  fields surfaced by `handleConfig()`
-- `FeeManager` slimmed: no more `operatorWallet` /
-  `usdtAddress` / `nativeWrappedAddress`; rebalancing gone (operator
-  doesn't hold ETH anymore); `quoteNativeToFee` replaces
-  `quoteNativeToUsdt` so fee currency is caller-chosen (PT for
-  mint/burn, USDT for swap/perp_deposit)
-
-**What's still blocked (comes in 0.3.0-beta / stable):**
-
-- `processMint()` / `processBurn()` — blocked on SC Relayer v2 ABI
-  (blocker B1). Current `processMintAndCashOut()` is `@deprecated`
-  but still works
-- `PTRedeemHandler` + `TopUpRedemptionHandler` — blocked on B1 +
-  `paymaster-proxy` staging env being live
-- Deletion of legacy `claimAndSwap` flow — kept for v0.2.x consumers
-  until 2.0
-
-**Install the alpha:**
+[![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)
 
-```bash
-pnpm add @pafi-dev/issuer@0.3.0-alpha.0 @pafi-dev/core@0.3.0-alpha.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.
 
-Pin the exact version, or use the `@alpha` dist-tag.
+> **Server-only.** This package pulls in `jose` and `node:crypto`. Do not bundle into a browser app.
 
-## What's new in 0.2.0 — multi-token support
+---
 
-An issuer backend can now support more than one PointToken in a single
-service instance. Pass `pointTokenAddresses: Address[]` in
-`IssuerServiceConfig`; the factory creates one `PointIndexer` per token
-and handlers validate the requested `pointTokenAddress` against the
-configured set.
+## Requirements
 
-`IPointLedger` methods take an optional `tokenAddress?: Address` param.
-Single-token issuers can ignore it — legacy 0.1.x code keeps working.
-Multi-token issuers must persist balances keyed by `(user, token)`.
+- Node.js >= 18
+- TypeScript >= 5.0
+- `viem` ^2.0.0 and `@pafi-dev/core` ^0.4.0 (peer dependencies)
 
-Legacy `pointTokenAddress: Address` still works as a shorthand for a
-one-element list. No code change is required if you only have one token.
+---
 
-## Install
+## Installation
 
 ```bash
+npm install @pafi-dev/issuer @pafi-dev/core viem
+# or
 pnpm add @pafi-dev/issuer @pafi-dev/core viem
 ```
 
-Peer deps: `viem ^2.0`, `@pafi-dev/core` (workspace), `jose ^5` (transitive).
+---
+
+## 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
 
-## At a glance
+The SDK deliberately does not ship production implementations for:
+
+| 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 |
+
+---
+
+## Quick start
 
 ```ts
-import { createIssuerService, PrivateKeySigner } from "@pafi-dev/issuer";
+import { createIssuerService } from "@pafi-dev/issuer";
+import { getContractAddresses } from "@pafi-dev/core";
 import { createPublicClient, createWalletClient, http } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
 import { base } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+
+const addrs = getContractAddresses(8453);
 
-const provider = createPublicClient({ chain: base, transport: http(RPC_URL) });
-const operatorWallet = createWalletClient({
-  account: privateKeyToAccount(OPERATOR_PK),
+// 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(RPC_URL),
+  transport: http(process.env.RPC_URL),
 });
 
 const service = createIssuerService({
   chainId: 8453,
-  pointTokenAddress: "0x5F...",
-  relayAddress: "0x92...",
-  contracts: { pointToken, relay, issuerRegistry, usdt },
-  provider,
-  operatorWallet,
+  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",
   },
-  // ⚠️ NOT for production — replace with a KMS-backed IIssuerSigner
-  signer: new PrivateKeySigner({ privateKey: ISSUER_PK, chain: base }),
+  ledger: new YourPostgresLedger(),          // implements IPointLedger
+  sessionStore: new YourRedisSessionStore(), // implements ISessionStore
+  claim: {
+    issuerSignerWallet,
+    batchExecutorAddress: addrs.batchExecutor,
+  },
 });
 
-// Wire `service.handlers` into Express / Fastify / Hono — see
-// examples/express-issuer/ for a full runnable server.
+// 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));
 ```
 
-## What you get
+---
 
-| Component               | Default               | Replace for production?               |
-| ----------------------- | --------------------- | ------------------------------------- |
-| `IPointLedger`          | `MemoryPointLedger`   | ✅ Postgres / Prisma                    |
-| `ISessionStore`         | `MemorySessionStore`  | ✅ Redis                                |
-| `IPolicyEngine`         | `DefaultPolicyEngine` | ➕ extend for KYC / caps / claim budget |
-| `IIssuerSigner`         | `PrivateKeySigner`    | 🚨 **MUST replace** — KMS / HSM / MPC   |
-| `AuthService`           | ✅ built-in            | —                                     |
-| `RelayService`          | ✅ built-in            | —                                     |
-| `FeeManager`            | ✅ built-in (opt-in)   | injection-based — no DEX lock-in      |
-| `MintingGateway`        | ✅ built-in            | —                                     |
-| `PointIndexer`          | ✅ built-in (polling)  | —                                     |
-| `IssuerApiHandlers`     | ✅ built-in            | —                                     |
+## Implementing IPointLedger
 
-See [`examples/adapters/`](./examples/adapters) for reference
-implementations of the three interfaces you must replace.
+Every issuer provides their own database-backed implementation:
 
-## The minting flow
+```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> { ... }
+}
+```
 
-The SDK's central orchestrator is `MintingGateway.processMintAndCashOut()`,
-which runs the full 11-step flow documented in
-[`docs/PAFI_ISSUER_SDK_SPEC.md`](../../../pafi-backend/docs/PAFI_ISSUER_SDK_SPEC.md):
+---
 
-```
-1. Validate request fields (cheap rejects)
-2. Verify ReceiverConsent signature via @pafi-dev/core
-3. Check off-chain balance via ledger
-4. Check locked requests via ledger
-5. Run policy engine (balance + cap + issuer rules)
-6. Lock the requested amount in the ledger
-7. Sign MintRequest as the issuer (via IIssuerSigner)
-8. Build Relay calldata (MintParams + SwapParams)
-9. Submit via RelayService (simulate → write → receipt)
-10. Return { txHash, lockId, block/gas }
-11. PointIndexer finalizes the ledger on the Mint event (out of band)
-```
+## Production signing — KMS
 
-**The gateway never deducts the balance directly.** Deduction is
-driven by the `PointIndexer` when it observes the on-chain Mint event.
-That makes the system crash-safe: if the gateway dies between
-broadcast and receipt, the indexer still finalizes the ledger the next
-time it polls.
+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:
+
+```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
+  },
+});
 
-### Lock release semantics
+const issuerSignerWallet = createWalletClient({
+  account: kmsAccount,
+  chain: base,
+  transport: http(process.env.RPC_URL),
+});
+```
 
-Every `MintingGatewayError` carries a `safeToRetry: boolean` flag that
-tells the API layer whether the underlying ledger lock was released:
+---
 
-| Error code                  | Lock released? | `safeToRetry` |
-| --------------------------- | -------------- | ------------- |
-| `INVALID_REQUEST`           | never locked   | `true`        |
-| `INVALID_CONSENT_SIGNATURE` | never locked   | `true`        |
-| `CONSENT_EXPIRED`           | never locked   | `true`        |
-| `POLICY_REJECTED`           | never locked   | `true`        |
-| `INSUFFICIENT_BALANCE`      | never locked   | `true`        |
-| `SIGNER_FAILED`             | ✅ released     | `true`        |
-| `RELAY_SIMULATION_FAILED`   | ✅ released     | `true`        |
-| `RELAY_SUBMIT_FAILED`       | ✅ released     | `true`        |
-| `RELAY_REVERTED`            | 🔒 kept         | `false`       |
-| `RELAY_TIMEOUT`             | 🔒 kept         | `false`       |
+## Event indexers
 
-`RELAY_REVERTED` and `RELAY_TIMEOUT` keep the lock because the tx may
-still be in the mempool or already mined — releasing would enable a
-double-spend on retry. Your API should surface `409 Conflict` in these
-cases and require manual reconciliation.
+Indexers sync on-chain mint/burn events back to the off-chain ledger.
 
-## Authentication
+```ts
+import { PointIndexer, BurnIndexer } from "@pafi-dev/issuer";
+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,
+});
 
-Wallet-based login uses EIP-4361 (Sign-In with Ethereum):
+// 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();
 ```
-Frontend                           Issuer backend
-────────                           ──────────────
-1. GET /auth/nonce              →  authService.getNonce()
-                                ←  { nonce }
-2. Build EIP-4361 message with
-   nonce (via PafiSDK or
-   @pafi-dev/core createLoginMessage)
-3. Sign with wallet
-4. POST /auth/login             →  authService.login(message, sig)
-   { message, signature }           → parse → verify → consume nonce
-                                    → create session → issue JWT
-                                ←  { token, userAddress, expiresAt }
-5. Authorization: Bearer <jwt>  →  authenticateRequest()
-                                    → verify JWT + session
-                                    → pass { userAddress, chainId } to handlers
-```
-
-Key property: a failed signature does **not** burn the nonce. Users can
-retry with the correct wallet on the same nonce without hitting the
-backend again.
 
-## HTTP endpoints
+> **Indexers must be singletons.** Run exactly one instance per token per deployment.
+> Use a Kubernetes `Deployment` with `replicas: 1`.
 
-The handlers are framework-agnostic — `async` functions that take plain
-inputs and return plain outputs. Wrap them in Express / Fastify / Hono /
-whatever you use. See `examples/express-issuer/server.ts` for the full
-wiring.
+---
 
-| Method | Path             | Auth | Handler              |
-| ------ | ---------------- | ---- | -------------------- |
-| GET    | /auth/nonce      | no   | `handleGetNonce`     |
-| POST   | /auth/login      | no   | `handleLogin`        |
-| GET    | /config          | no   | `handleConfig`       |
-| GET    | /gas-fee         | no   | `handleGasFee`       |
-| POST   | /auth/logout     | yes  | `handleLogout`       |
-| GET    | /pools           | yes  | `handlePools`        |
-| GET    | /user            | yes  | `handleUser`         |
-| POST   | /claim-and-swap  | yes  | `handleClaimAndSwap` |
+## PafiBackendClient
 
-## Security notes
+HTTP client for requesting paymaster sponsorship from the PAFI backend:
 
-- 🚨 **Never deploy `PrivateKeySigner` to production.** The private key lives in process memory and is trivially extractable from a compromised host. Use `examples/adapters/kms-signer.ts` as a starting point for a KMS/HSM integration.
-- 🔑 **`jwtSecret` must be at least 16 characters (32+ recommended) and rotated periodically.** Sessions survive a rotation because the JWT lookup cross-checks the session store — but existing tokens signed with the old secret will fail `verifyToken`, forcing users to re-login.
-- 🕐 **The default `MemorySessionStore` does not survive restarts.** Nonces and sessions are both lost. Use `examples/adapters/redis-session-store.ts` for anything past local development.
-- 🔒 **The `MintingGatewayError.safeToRetry` flag is load-bearing.** Do not ignore it in your API layer — surfacing `RELAY_REVERTED` as a retryable 400 will cause double-spend the moment a tx lands after the first response.
+```ts
+import { PafiBackendClient } from "@pafi-dev/issuer";
 
-## Tests
+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 },
+});
 
-The package ships with 142 unit tests covering every collaborator + the
-full gateway flow through mocked providers. Run them with:
+const sponsorship = await pafiClient.requestSponsorship({
+  chainId: 8453,
+  scenario: "mint",
+  userOp: {
+    sender: userAddress,
+    callData: userOp.callData,
+    // ...gas fields
+  },
+  target: {
+    contractAddress: addrs.pointToken,
+    functionSelector: "0x...",
+  },
+});
 
-```bash
-pnpm --filter @pafi-dev/issuer test
+// sponsorship.paymaster
+// sponsorship.paymasterData
+// sponsorship.paymasterVerificationGasLimit
+// sponsorship.paymasterPostOpGasLimit
+// sponsorship.expiresAt
 ```
 
-No network or on-chain state is required — all tests are hermetic.
+---
+
+## Error handling
+
+### AuthError
 
-## Exports
+Thrown by `AuthService` and `authenticateRequest` middleware:
 
 ```ts
-import {
-  // Factory (recommended entry point)
-  createIssuerService,
-  type IssuerService,
-  type IssuerServiceConfig,
-
-  // Ledger
-  MemoryPointLedger,
-  type IPointLedger,
-  type LockedMintRequest,
-  type MintingStatus,
-
-  // Policy
-  DefaultPolicyEngine,
-  type IPolicyEngine,
-  type PolicyDecision,
-  type PolicyEvalRequest,
-
-  // Signer
-  PrivateKeySigner,                  // DEV ONLY
-  type IIssuerSigner,
-
-  // Auth
-  AuthService,
-  AuthError,
-  type AuthErrorCode,
-  type AuthContext,
-  MemorySessionStore,
-  type ISessionStore,
-  type Session,
-  NonceManager,
-  authenticateRequest,
-
-  // Relay + fees
-  RelayService,
-  RelayError,
-  type RelayErrorCode,
-  type SubmitMintAndSwapParams,
-  type RelayResult,
-  type OperatorWalletLike,
-  FeeManager,
-  type FeeManagerConfig,
-
-  // Gateway
-  MintingGateway,
-  MintingGatewayError,
-  type MintingGatewayErrorCode,
-  type MintAndCashOutRequest,
-  type MintAndCashOutResponse,
-  encodeExtData,
-
-  // Indexer
-  PointIndexer,
-  type PointIndexerConfig,
-  type MintEvent,
-  type IIndexerCursorStore,
-  InMemoryCursorStore,
-
-  // API handlers + HTTP contract (source of truth — FE imports these type-only)
-  IssuerApiHandlers,
-  type IssuerApiHandlersConfig,
-  type ApiConfigResponse,
-  type ApiNonceResponse,
-  type ApiLoginRequest,
-  type ApiLoginResponse,
-  type ApiGasFeeResponse,
-  type ApiPoolsRequest,
-  type ApiPoolsResponse,
-  type ApiUserRequest,
-  type ApiUserResponse,
-  type ApiClaimAndSwapRequest,
-  type ApiClaimAndSwapResponse,
-  type PoolsProvider,
-} from "@pafi-dev/issuer";
+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
+  }
+}
 ```
 
-### HTTP contract ownership
+### PafiBackendError
 
-`@pafi-dev/issuer` is the **single source of truth** for the HTTP API contract
-between the issuer backend and any frontend / mobile / SDK consumer. The
-request/response types above are defined once here, then imported
-**type-only** by frontend code so browser bundles never pull in server
-code (`jose`, `node:crypto`, indexer polling loops, etc):
+Thrown by `PafiBackendClient`:
 
 ```ts
-// Frontend — type-only import, erased at build time
-import type {
-  ApiLoginRequest,
-  ApiClaimAndSwapRequest,
-  ApiUserResponse,
-} from "@pafi-dev/issuer";
-
-// Build your own fetch call with full type safety
-const res = await fetch(`${API_URL}/claim-and-swap`, {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${token}`,
-  },
-  body: JSON.stringify(request satisfies ApiClaimAndSwapRequest),
-});
-const body = (await res.json()) as ApiClaimAndSwapResponse;
+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
+    }
+  }
+}
 ```
 
-**`@pafi-dev/core` deliberately does NOT ship an HTTP client** — it handles
-only cryptography (EIP-712 / EIP-4361), contract reads, and V4 quoting.
-That's what keeps the frontend bundle small and keeps the protocol
-contract in exactly one place.
+---
+
+## Changelog
+
+### 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`
+
+### 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`
+
+### 0.3.0-beta.9
+- `PTRedeemHandler` enforces on-chain balance check before signing `BurnRequest`
 
-## License
+### 0.3.0-beta.8
+- `BalanceAggregator`, `BurnIndexer`, `PTRedeemHandler`, `TopUpRedemptionHandler`
 
-Apache-2.0
+### 0.3.0-alpha.0
+- Initial `RelayService`, `PointIndexer`, `AuthService`, `IssuerApiHandlers`