@pafi-dev/issuer 0.4.0 → 0.5.0

package/README.md

@@ -1,67 +1,73 @@
 # @pafi-dev/issuer
 
-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.
+[![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)
 
-**Version:** `0.3.0-beta.10`
+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.
 
-> This package runs on the **issuer backend server only** (Node.js). Do not
-> import into browser bundles — it pulls in `jose`, `node:crypto`, and
-> server-side dependencies.
+> **Server-only.** This package pulls in `jose` and `node:crypto`. Do not bundle into a browser app.
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.0
+- `viem` ^2.0.0 and `@pafi-dev/core` ^0.4.0 (peer dependencies)
 
 ---
 
 ## Installation
 
 ```bash
+npm install @pafi-dev/issuer @pafi-dev/core viem
+# or
 pnpm add @pafi-dev/issuer @pafi-dev/core viem
 ```
 
 ---
 
-## What this package provides
+## Modules
 
-| Module | What it does |
-|--------|-------------|
-| `relay/` | `RelayService.prepareMint()` / `prepareBurn()` — build unsigned UserOps |
-| `indexer/` | `PointIndexer` (Mint events) + `BurnIndexer` (Transfer→0x0 events) |
-| `auth/` | `AuthService` (SIWE verify + JWT issue) + `authenticateRequest` middleware |
+| 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/` | `DefaultPolicyEngine` + `IPolicyEngine` interface |
-| `pools/` | `PoolsProvider` — fetch V4 pool list from PAFI subgraph |
+| `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`, `PTRedeemHandler`, `TopUpRedemptionHandler` |
+| `api/` | `IssuerApiHandlers` — framework-agnostic HTTP handlers |
+| `pafi-backend/` | `PafiBackendClient` — HTTP client for PAFI paymaster backend |
 
 ---
 
 ## What you must bring
 
-The SDK deliberately does not ship production implementations for these
-three concerns — every issuer's infrastructure is different:
+The SDK deliberately does not ship production implementations for:
 
 | What | Why you own it |
-|------|---------------|
-| **`IPointLedger`** | Your database, your schema, your locking strategy |
-| **`ISessionStore`** | Must be shared across pods — Redis, Postgres, etc. |
+|---|---|
+| **`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 |
 
-See [`examples/adapters/`](./examples/adapters/) for reference implementations
-of all three (Postgres ledger, Redis session store, AWS KMS wallet).
-
 ---
 
 ## 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";
-
-// --- Production: replace with KMS-backed wallet (see examples/adapters/kms-signer.ts)
-// --- Dev only: raw private key
 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,
@@ -70,27 +76,27 @@ const issuerSignerWallet = createWalletClient({
 
 const service = createIssuerService({
   chainId: 8453,
-  pointTokenAddresses: ["0x<PointToken>"],
+  pointTokenAddresses: [addrs.pointToken],
   contracts: {
-    relay: "0x<Relay>",
-    issuerRegistry: "0x<IssuerRegistry>",
-    usdt: "0x<USDT>",
-    batchExecutor: "0x<BatchExecutor>",
+    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
+  ledger: new YourPostgresLedger(),          // implements IPointLedger
   sessionStore: new YourRedisSessionStore(), // implements ISessionStore
   claim: {
     issuerSignerWallet,
-    batchExecutorAddress: "0x<BatchExecutor>",
+    batchExecutorAddress: addrs.batchExecutor,
   },
 });
 
-// Mount handlers into your framework (Express, Fastify, NestJS, Hono...)
+// 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));
@@ -101,124 +107,217 @@ 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 } from "@pafi-dev/issuer";
+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> { ... }
-  // v1.4 reverse flow (burn → off-chain credit):
+
+  // 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> { ... }
 }
 ```
 
-Critical: `lockForMinting` must use a **row-level lock** (e.g. `SELECT ... FOR UPDATE`)
-so concurrent requests from multiple pods cannot read the same available balance and
-double-spend.
-
-See `examples/adapters/postgres-ledger.ts` for a full Prisma implementation.
-
 ---
 
 ## Production signing — KMS
 
-The `claim.issuerSignerWallet` must be backed by a hardware key in production.
-The SDK accepts any viem `WalletClient` — wire it to AWS KMS by giving viem
-a custom account:
+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 { createKmsWalletClient } from "./adapters/kms-signer";
 import { KMSClient } from "@aws-sdk/client-kms";
+import { createWalletClient, http } from "viem";
+import { base } from "viem/chains";
 
-const kms = new KMSClient({ region: "us-east-1" });
+// 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
+  },
+});
 
-const issuerSignerWallet = createKmsWalletClient({
-  kms,
-  keyId: process.env.KMS_MINTER_KEY_ID!,
-  address: process.env.KMS_MINTER_ADDRESS! as `0x${string}`,
+const issuerSignerWallet = createWalletClient({
+  account: kmsAccount,
   chain: base,
+  transport: http(process.env.RPC_URL),
 });
 ```
 
-See `examples/adapters/kms-signer.ts` for the full implementation including
-DER→(r,s) conversion and v-byte recovery.
-
 ---
 
-## Indexers
+## Event indexers
+
+Indexers sync on-chain mint/burn events back to the off-chain ledger.
 
 ```ts
 import { PointIndexer, BurnIndexer } from "@pafi-dev/issuer";
+import { getContractAddresses } from "@pafi-dev/core";
 
-// Watches Transfer(0x0 → user) — deducts off-chain balance when mint confirmed.
-const pointIndexer = new PointIndexer({
+const addrs = getContractAddresses(8453);
+
+// Mint indexer: Transfer(0x0 → user) → deducts off-chain locked balance
+const mintIndexer = new PointIndexer({
   provider: publicClient,
-  pointTokenAddress: "0x<PointToken>",
+  pointTokenAddress: addrs.pointToken,
   ledger,
-  cursorStore,        // PostgresCursorStore recommended
+  cursorStore,       // persists last-processed block; use Postgres or Redis
   fromBlock: 28_000_000n,
   confirmations: 2,
   pollIntervalMs: 3_000,
 });
-pointIndexer.start();
 
-// Watches Transfer(user → 0x0) — resolves pending credit when burn confirmed.
+// Burn indexer: Transfer(user → 0x0) → resolves pending off-chain credit
 const burnIndexer = new BurnIndexer({
   provider: publicClient,
-  pointTokenAddress: "0x<PointToken>",
+  pointTokenAddress: addrs.pointToken,
   ledger,
   cursorStore,
   matchLockId: async (evt) => {
-    // Return the lockId from ledger.reservePendingCredit() that matches
-    // this burn event. Typically a DB lookup by (from, amount, status=PENDING).
-    return yourDb.findPendingCreditLockId(evt.from, evt.amount);
+    // 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`, not a Deployment behind a load balancer.
+> **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
+  },
+  target: {
+    contractAddress: addrs.pointToken,
+    functionSelector: "0x...",
+  },
+});
+
+// sponsorship.paymaster
+// sponsorship.paymasterData
+// sponsorship.paymasterVerificationGasLimit
+// sponsorship.paymasterPostOpGasLimit
+// sponsorship.expiresAt
+```
 
 ---
 
-## Error codes
+## Error handling
+
+### AuthError
+
+Thrown by `AuthService` and `authenticateRequest` middleware:
+
+```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`:
 
 ```ts
 import { PafiBackendError, type PafiBackendErrorCode } from "@pafi-dev/issuer";
 
-type 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"
-  | "BAD_REQUEST" | "INTERNAL_ERROR" | "TIMEOUT" | "NETWORK_ERROR";
+// 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
+    }
+  }
+}
 ```
 
 ---
 
 ## 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 implements `IPointLedger` against their own DB
-- `PrivateKeySigner` / `IIssuerSigner` removed — SDK accepts viem `WalletClient` directly; see `examples/adapters/kms-signer.ts`
-- `ledger` is now a required field in `IssuerServiceConfig` (was optional with in-memory default)
-- `handleClaim` added to `IssuerApiHandlers` — enforces policy evaluation atomically before signing
+- `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
-- `handleBuildConsentTypedData` validates `receiverConsent.originalReceiver` against authenticated user
-- `PTRedeemHandler` enforces on-chain balance check before signing BurnRequest
+- `PTRedeemHandler` enforces on-chain balance check before signing `BurnRequest`
 
 ### 0.3.0-beta.8
 - `BalanceAggregator`, `BurnIndexer`, `PTRedeemHandler`, `TopUpRedemptionHandler`
-- `BurnIndexer.matchLockId` is now required (throws if not provided)
 
 ### 0.3.0-alpha.0
 - Initial `RelayService`, `PointIndexer`, `AuthService`, `IssuerApiHandlers`

package/dist/index.cjs

@@ -2062,20 +2062,20 @@ function createIssuerService(config) {
     }
   }
   return {
-    authService,
-    sessionStore,
+    auth: authService,
+    session: sessionStore,
     ledger,
     policy,
-    relayService,
-    feeManager,
+    relay: relayService,
+    fee: feeManager,
     indexers,
     indexer: firstIndexer,
-    handlers
+    api: handlers
   };
 }
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = "0.1.0";
+var PAFI_ISSUER_SDK_VERSION = "0.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,