@pafi-dev/issuer 0.32.0 → 0.34.0

package/dist/index.d.cts

@@ -1551,17 +1551,8 @@ interface SettlementClientConfig {
     /**
      * chainId — used to derive the issuer-api base URL via
      * `getPafiServiceUrls(chainId).issuerApi`. SDK ships with the URL
-     * per chainId; bump SDK version to retarget — OR pass `baseUrl`
-     * to override per-deployment.
      */
     chainId: number;
-    /**
-     * Optional override for the issuer-api base URL. Audit PACI5-17 —
-     * production issuer backends should set this from an env var
-     * (e.g. `PAFI_ISSUER_API_URL`) so the deployed binary doesn't
-     * depend on the SDK ship-default that may target dev infrastructure.
-     * Undefined / empty → use the ship-default for `chainId`.
-     */
     baseUrl?: string;
     /** PAFI-assigned issuer id used in `X-Issuer-Id` header. */
     issuerId: string;
@@ -1575,33 +1566,7 @@ interface SettlementClientConfig {
 interface PolicyProviderConfig extends SettlementClientConfig {
     /** Cache TTL in milliseconds. Default 5 * 60 * 1000 (5min). */
     cacheTtlMs?: number;
-    /**
-     * Behavior khi settlement-api fetch fail (network blip, 5xx, timeout).
-     *
-     * Audit PACI5-17 — the pre-flight redeem limit is the SOLE gate
-     * before the issuer signer mints a BurnRequest. Silently degrading
-     * to a permissive default during settlement outages let users
-     * exceed their configured limit until the outage cleared.
-     *
-     *  - `'fail-closed'` (DEFAULT, recommended): throw
-     *    `PolicyProviderUnavailableError`. Caller maps to HTTP 503 so
-     *    the FE can retry; redemptions are blocked until policy fetch
-     *    succeeds.
-     *
-     *  - `'permissive-default'`: return `defaultPolicyFor(issuerId)` and
-     *    fire `onWarning`. Pre-fix behavior. Operators who genuinely
-     *    prefer availability over enforcement (e.g. test issuers, low-
-     *    risk PT) MUST opt in explicitly AND wire `onWarning` to a
-     *    pager / Slack / Sentry alert. Silent permissive fallback is no
-     *    longer the default.
-     */
     onFetchFailure?: "fail-closed" | "permissive-default";
-    /**
-     * Observability hook for non-fatal events: permissive-default
-     * fallbacks (when explicitly opted in). Wire to your logger /
-     * Sentry / Datadog so the `policy_provider_fallback` event reaches
-     * the on-call dashboard.
-     */
     onWarning?: (msg: string, ctx: Record<string, unknown>) => void;
     /**
      * Optional clock for testability. Returns unix milliseconds.
@@ -2078,17 +2043,8 @@ interface PafiBackendConfig {
     /**
      * chainId — used to derive the sponsor-relayer base URL via
      * `getPafiServiceUrls(chainId).sponsorRelayer`. SDK ships with the
-     * URL per chainId; bump SDK version to retarget — OR pass
-     * `baseUrl` to override per-deployment.
      */
     chainId: number;
-    /**
-     * Optional override for the sponsor-relayer base URL. Audit
-     * PACI5-17 — production issuer backends should set this from an env
-     * var (e.g. `PAFI_SPONSOR_RELAYER_URL`) so the binary doesn't depend
-     * on the SDK ship-default that may target dev infrastructure.
-     * Undefined / empty → use the ship-default for `chainId`.
-     */
     baseUrl?: string;
     issuerId: string;
     apiKey: string;
@@ -2246,12 +2202,31 @@ interface MintStatusParams {
      *   - lock.status === "PENDING"
      *   - lock.userOpHash is bound (set by `/claim/submit`)
      *
-     * If the bundler reports the UserOp confirmed, the handler updates
+     * If the bundler reports the UserOp confirmed AND the receipt block
+     * is past the configured `confirmations` depth, the handler updates
      * the ledger lock + returns `MINTED` immediately, bypassing
      * `PointIndexer`'s amount-based race (multiple PENDING locks with
      * the same amount can be matched to the wrong tx_hash).
      */
     pafiBackendClient?: PafiBackendClient | null;
+    /**
+     * Guard for the bundler-receipt fallback. The bundler returns success at zero
+     * confs, but `PointIndexer` enforces a 3-block reorg window;
+     * crediting / debiting off-chain at 0 confs while the indexer waits
+     * for finality leaves an unbacked durable mutation if the tx is
+     * reorged out. Pass the SAME PublicClient that the indexer uses so
+     * both paths see consistent chain head. Optional only for legacy
+     * callers that don't supply `pafiBackendClient`; required whenever
+     * the receipt-fallback path can run.
+     */
+    provider?: PublicClient;
+    /**
+     * Confirmation depth required before the receipt
+     * fallback applies the credit / debit. MUST match
+     * `PointIndexer.confirmations` (default 3). Operators who reduce
+     * the indexer depth must set this to the same value.
+     */
+    confirmations?: number;
     /** Optional logger for "ledger update failed" warnings. */
     onWarning?: (msg: string) => void;
 }
@@ -2260,6 +2235,20 @@ interface BurnStatusParams {
     userAddress: Address;
     ledger: IPointLedger;
     pafiBackendClient?: PafiBackendClient | null;
+    /**
+     * BurnStatusParams.provider` for full
+     * rationale. The receipt-fallback path applies a spendable
+     * off-chain credit; without a confirmation-depth gate a reorg
+     * before `BurnIndexer.confirmations` leaves durable unbacked
+     * credit with no reversal mechanism.
+     */
+    provider?: PublicClient;
+    /**
+     * Confirmation depth required before the receipt
+     * fallback applies the credit. MUST match
+     * `BurnIndexer.confirmations` (default 3).
+     */
+    confirmations?: number;
     onWarning?: (msg: string) => void;
 }
 declare class LockNotFoundError extends PafiSdkError {
@@ -3235,7 +3224,6 @@ interface IssuerServiceConfig {
         historyStore: IRedemptionHistoryStore;
         /**
          * Optional override for the PAFI issuer-api base URL. Audit
-         * PACI5-17 — production issuer backends should set this from an
          * env var (e.g. `PAFI_ISSUER_API_URL`) so policy fetch hits the
          * canonical environment for the deploy. Undefined → SDK
          * ship-default per chainId.
@@ -3243,9 +3231,6 @@ interface IssuerServiceConfig {
         baseUrl?: string;
         /**
          * Behavior khi settlement-api fetch fail. Default `'fail-closed'`
-         * (audit PACI5-17 — pre-flight redeem limit is the sole gate; do
-         * not silently degrade to a permissive default).
-         *
          * Opt in to `'permissive-default'` ONLY when paired with an alert
          * on the `policy_provider_fallback` event surfaced via
          * `onPolicyWarning`.
@@ -3965,9 +3950,12 @@ declare class IssuerStateError extends PafiSdkError {
  *
  * Caching:
  *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
- *   - Full state (registry + totalSupply) — 30s TTL per PointToken
+ *   - Full state (registry + totalSupply) — 10s TTL per PointToken
+ *     (was 30s pre-audit PACI5-3; see `ISSUER_RECORD_TTL_MS` comment)
  *   - Burst calls while a fetch is in-flight share the same Promise
  *     (thundering-herd protection)
+ *   - Operators can call `invalidate()` after admin txs land to bust
+ *     the cache immediately instead of waiting up to TTL.
  *
  * Usage in NestJS: wrap this in an `@Injectable()` service; pass
  * `PublicClient` and `registryAddress` from your DI container.
@@ -3986,7 +3974,9 @@ declare class IssuerStateValidator {
     static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
     /**
      * Invalidate cached state for one PointToken, or everything if omitted.
-     * Call after admin txs that change registry or cap settings.
+     * Call after admin txs that change registry or cap settings — closes
+     * the split-brain window described in audit PACI5-3 ahead of the
+     * passive TTL. Idempotent: safe to call when no entry exists.
      */
     invalidate(pointToken?: Address): void;
     /**

package/dist/index.d.ts

@@ -1551,17 +1551,8 @@ interface SettlementClientConfig {
     /**
      * chainId — used to derive the issuer-api base URL via
      * `getPafiServiceUrls(chainId).issuerApi`. SDK ships with the URL
-     * per chainId; bump SDK version to retarget — OR pass `baseUrl`
-     * to override per-deployment.
      */
     chainId: number;
-    /**
-     * Optional override for the issuer-api base URL. Audit PACI5-17 —
-     * production issuer backends should set this from an env var
-     * (e.g. `PAFI_ISSUER_API_URL`) so the deployed binary doesn't
-     * depend on the SDK ship-default that may target dev infrastructure.
-     * Undefined / empty → use the ship-default for `chainId`.
-     */
     baseUrl?: string;
     /** PAFI-assigned issuer id used in `X-Issuer-Id` header. */
     issuerId: string;
@@ -1575,33 +1566,7 @@ interface SettlementClientConfig {
 interface PolicyProviderConfig extends SettlementClientConfig {
     /** Cache TTL in milliseconds. Default 5 * 60 * 1000 (5min). */
     cacheTtlMs?: number;
-    /**
-     * Behavior khi settlement-api fetch fail (network blip, 5xx, timeout).
-     *
-     * Audit PACI5-17 — the pre-flight redeem limit is the SOLE gate
-     * before the issuer signer mints a BurnRequest. Silently degrading
-     * to a permissive default during settlement outages let users
-     * exceed their configured limit until the outage cleared.
-     *
-     *  - `'fail-closed'` (DEFAULT, recommended): throw
-     *    `PolicyProviderUnavailableError`. Caller maps to HTTP 503 so
-     *    the FE can retry; redemptions are blocked until policy fetch
-     *    succeeds.
-     *
-     *  - `'permissive-default'`: return `defaultPolicyFor(issuerId)` and
-     *    fire `onWarning`. Pre-fix behavior. Operators who genuinely
-     *    prefer availability over enforcement (e.g. test issuers, low-
-     *    risk PT) MUST opt in explicitly AND wire `onWarning` to a
-     *    pager / Slack / Sentry alert. Silent permissive fallback is no
-     *    longer the default.
-     */
     onFetchFailure?: "fail-closed" | "permissive-default";
-    /**
-     * Observability hook for non-fatal events: permissive-default
-     * fallbacks (when explicitly opted in). Wire to your logger /
-     * Sentry / Datadog so the `policy_provider_fallback` event reaches
-     * the on-call dashboard.
-     */
     onWarning?: (msg: string, ctx: Record<string, unknown>) => void;
     /**
      * Optional clock for testability. Returns unix milliseconds.
@@ -2078,17 +2043,8 @@ interface PafiBackendConfig {
     /**
      * chainId — used to derive the sponsor-relayer base URL via
      * `getPafiServiceUrls(chainId).sponsorRelayer`. SDK ships with the
-     * URL per chainId; bump SDK version to retarget — OR pass
-     * `baseUrl` to override per-deployment.
      */
     chainId: number;
-    /**
-     * Optional override for the sponsor-relayer base URL. Audit
-     * PACI5-17 — production issuer backends should set this from an env
-     * var (e.g. `PAFI_SPONSOR_RELAYER_URL`) so the binary doesn't depend
-     * on the SDK ship-default that may target dev infrastructure.
-     * Undefined / empty → use the ship-default for `chainId`.
-     */
     baseUrl?: string;
     issuerId: string;
     apiKey: string;
@@ -2246,12 +2202,31 @@ interface MintStatusParams {
      *   - lock.status === "PENDING"
      *   - lock.userOpHash is bound (set by `/claim/submit`)
      *
-     * If the bundler reports the UserOp confirmed, the handler updates
+     * If the bundler reports the UserOp confirmed AND the receipt block
+     * is past the configured `confirmations` depth, the handler updates
      * the ledger lock + returns `MINTED` immediately, bypassing
      * `PointIndexer`'s amount-based race (multiple PENDING locks with
      * the same amount can be matched to the wrong tx_hash).
      */
     pafiBackendClient?: PafiBackendClient | null;
+    /**
+     * Guard for the bundler-receipt fallback. The bundler returns success at zero
+     * confs, but `PointIndexer` enforces a 3-block reorg window;
+     * crediting / debiting off-chain at 0 confs while the indexer waits
+     * for finality leaves an unbacked durable mutation if the tx is
+     * reorged out. Pass the SAME PublicClient that the indexer uses so
+     * both paths see consistent chain head. Optional only for legacy
+     * callers that don't supply `pafiBackendClient`; required whenever
+     * the receipt-fallback path can run.
+     */
+    provider?: PublicClient;
+    /**
+     * Confirmation depth required before the receipt
+     * fallback applies the credit / debit. MUST match
+     * `PointIndexer.confirmations` (default 3). Operators who reduce
+     * the indexer depth must set this to the same value.
+     */
+    confirmations?: number;
     /** Optional logger for "ledger update failed" warnings. */
     onWarning?: (msg: string) => void;
 }
@@ -2260,6 +2235,20 @@ interface BurnStatusParams {
     userAddress: Address;
     ledger: IPointLedger;
     pafiBackendClient?: PafiBackendClient | null;
+    /**
+     * BurnStatusParams.provider` for full
+     * rationale. The receipt-fallback path applies a spendable
+     * off-chain credit; without a confirmation-depth gate a reorg
+     * before `BurnIndexer.confirmations` leaves durable unbacked
+     * credit with no reversal mechanism.
+     */
+    provider?: PublicClient;
+    /**
+     * Confirmation depth required before the receipt
+     * fallback applies the credit. MUST match
+     * `BurnIndexer.confirmations` (default 3).
+     */
+    confirmations?: number;
     onWarning?: (msg: string) => void;
 }
 declare class LockNotFoundError extends PafiSdkError {
@@ -3235,7 +3224,6 @@ interface IssuerServiceConfig {
         historyStore: IRedemptionHistoryStore;
         /**
          * Optional override for the PAFI issuer-api base URL. Audit
-         * PACI5-17 — production issuer backends should set this from an
          * env var (e.g. `PAFI_ISSUER_API_URL`) so policy fetch hits the
          * canonical environment for the deploy. Undefined → SDK
          * ship-default per chainId.
@@ -3243,9 +3231,6 @@ interface IssuerServiceConfig {
         baseUrl?: string;
         /**
          * Behavior khi settlement-api fetch fail. Default `'fail-closed'`
-         * (audit PACI5-17 — pre-flight redeem limit is the sole gate; do
-         * not silently degrade to a permissive default).
-         *
          * Opt in to `'permissive-default'` ONLY when paired with an alert
          * on the `policy_provider_fallback` event surfaced via
          * `onPolicyWarning`.
@@ -3965,9 +3950,12 @@ declare class IssuerStateError extends PafiSdkError {
  *
  * Caching:
  *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
- *   - Full state (registry + totalSupply) — 30s TTL per PointToken
+ *   - Full state (registry + totalSupply) — 10s TTL per PointToken
+ *     (was 30s pre-audit PACI5-3; see `ISSUER_RECORD_TTL_MS` comment)
  *   - Burst calls while a fetch is in-flight share the same Promise
  *     (thundering-herd protection)
+ *   - Operators can call `invalidate()` after admin txs land to bust
+ *     the cache immediately instead of waiting up to TTL.
  *
  * Usage in NestJS: wrap this in an `@Injectable()` service; pass
  * `PublicClient` and `registryAddress` from your DI container.
@@ -3986,7 +3974,9 @@ declare class IssuerStateValidator {
     static forChain(provider: PublicClient, chainId: number): IssuerStateValidator;
     /**
      * Invalidate cached state for one PointToken, or everything if omitted.
-     * Call after admin txs that change registry or cap settings.
+     * Call after admin txs that change registry or cap settings — closes
+     * the split-brain window described in audit PACI5-3 ahead of the
+     * passive TTL. Idempotent: safe to call when no entry exists.
      */
     invalidate(pointToken?: Address): void;
     /**

package/dist/index.js

@@ -2422,6 +2422,45 @@ var PTRedeemHandler = class {
 };
 
 // src/api/statusHandlers.ts
+var DEFAULT_STATUS_CONFIRMATIONS = 3;
+async function isReceiptPastConfirmations(receipt, provider, confirmations, onWarning, handlerName) {
+  if (!provider) {
+    onWarning?.(
+      `${handlerName}: provider missing \u2014 cannot enforce confirmation depth; deferring receipt fallback to on-chain indexer.`
+    );
+    return false;
+  }
+  if (!receipt.blockNumber) {
+    onWarning?.(
+      `${handlerName}: receipt has no blockNumber \u2014 cannot enforce confirmation depth; deferring to indexer.`
+    );
+    return false;
+  }
+  const requiredConfs = BigInt(confirmations ?? DEFAULT_STATUS_CONFIRMATIONS);
+  let receiptBlock;
+  try {
+    receiptBlock = BigInt(receipt.blockNumber);
+  } catch {
+    onWarning?.(
+      `${handlerName}: malformed receipt blockNumber (${receipt.blockNumber}) \u2014 deferring to indexer.`
+    );
+    return false;
+  }
+  let head;
+  try {
+    head = await provider.getBlockNumber();
+  } catch (err) {
+    onWarning?.(
+      `${handlerName}: getBlockNumber failed (${err instanceof Error ? err.message : String(err)}) \u2014 deferring to indexer.`
+    );
+    return false;
+  }
+  const depth = head - receiptBlock;
+  if (depth < requiredConfs) {
+    return false;
+  }
+  return true;
+}
 var LockNotFoundError = class extends PafiSdkError {
   code = "LOCK_NOT_FOUND";
   httpStatus = "not_found";
@@ -2450,6 +2489,23 @@ async function handleClaimStatus(params) {
         lock.userOpHash
       );
       if (receipt) {
+        const passesConfirmationDepth = await isReceiptPastConfirmations(
+          receipt,
+          params.provider,
+          params.confirmations,
+          params.onWarning,
+          "handleClaimStatus"
+        );
+        if (!passesConfirmationDepth) {
+          return {
+            lockId: lock.lockId,
+            status: "PENDING",
+            txHash: lock.txHash ?? null,
+            amount: lock.amount.toString(),
+            createdAt: new Date(lock.createdAt).toISOString(),
+            expiresAt: new Date(lock.expiresAt).toISOString()
+          };
+        }
         if (receipt.success && receipt.txHash) {
           if (!lock.tokenAddress) {
             params.onWarning?.(
@@ -2524,14 +2580,23 @@ async function handleRedeemStatus(params) {
         credit.userOpHash
       );
       if (receipt && receipt.success) {
-        status = "RESOLVED";
-        txHash = receipt.txHash;
-        if (params.ledger.resolveCreditByBurnTx) {
-          await params.ledger.resolveCreditByBurnTx(credit.lockId, receipt.txHash).catch((err) => {
-            params.onWarning?.(
-              `handleRedeemStatus: resolveCreditByBurnTx failed for lock ${credit.lockId}: ${err}`
-            );
-          });
+        const passesConfirmationDepth = await isReceiptPastConfirmations(
+          receipt,
+          params.provider,
+          params.confirmations,
+          params.onWarning,
+          "handleRedeemStatus"
+        );
+        if (passesConfirmationDepth) {
+          status = "RESOLVED";
+          txHash = receipt.txHash;
+          if (params.ledger.resolveCreditByBurnTx) {
+            await params.ledger.resolveCreditByBurnTx(credit.lockId, receipt.txHash).catch((err) => {
+              params.onWarning?.(
+                `handleRedeemStatus: resolveCreditByBurnTx failed for lock ${credit.lockId}: ${err}`
+              );
+            });
+          }
         }
       }
     } catch (err) {
@@ -3729,6 +3794,7 @@ var IssuerApiAdapter = class {
       userAddress: authenticatedAddress,
       ledger: this.cfg.ledger,
       pafiBackendClient: this.cfg.pafiBackendClient,
+      provider: this.cfg.provider,
       onWarning: this.cfg.onWarning
     });
   }
@@ -3738,6 +3804,7 @@ var IssuerApiAdapter = class {
       userAddress: authenticatedAddress,
       ledger: this.cfg.ledger,
       pafiBackendClient: this.cfg.pafiBackendClient,
+      provider: this.cfg.provider,
       onWarning: this.cfg.onWarning
     });
   }
@@ -4554,9 +4621,6 @@ var SettlementClient = class {
     if (!config.issuerId) throw new Error("SettlementClient: issuerId is required");
     if (!config.apiKey) throw new Error("SettlementClient: apiKey is required");
     this.config = {
-      // Audit PACI5-17 — honor optional baseUrl override wired from
-      // an env var (e.g. PAFI_ISSUER_API_URL). Empty / undefined →
-      // ship-default for chainId.
       baseUrl: getPafiServiceUrls2(config.chainId, {
         issuerApi: config.baseUrl
       }).issuerApi.replace(/\/+$/, ""),
@@ -4959,7 +5023,7 @@ import {
   issuerRegistryAbi,
   getContractAddresses as getContractAddresses8
 } from "@pafi-dev/core";
-var ISSUER_RECORD_TTL_MS = 3e4;
+var ISSUER_RECORD_TTL_MS = 1e4;
 var IssuerStateValidator = class _IssuerStateValidator {
   constructor(provider, registryAddress) {
     this.provider = provider;
@@ -4980,7 +5044,9 @@ var IssuerStateValidator = class _IssuerStateValidator {
   }
   /**
    * Invalidate cached state for one PointToken, or everything if omitted.
-   * Call after admin txs that change registry or cap settings.
+   * Call after admin txs that change registry or cap settings — closes
+   * the split-brain window described in audit PACI5-3 ahead of the
+   * passive TTL. Idempotent: safe to call when no entry exists.
    */
   invalidate(pointToken) {
     if (pointToken) {
@@ -5153,7 +5219,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.32.0" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.34.0" : "dev";
 export {
   AdapterMisconfiguredError,
   AuthError,