@pafi-dev/issuer 0.5.8 → 0.5.10

package/dist/index.d.cts

@@ -1599,7 +1599,138 @@ interface IssuerService {
  */
 declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
 
+/**
+ * A pending UserOp serialized for persistent storage (Redis, Postgres, memory).
+ *
+ * All bigint fields are stored as decimal strings so the entry can be
+ * JSON-serialized without precision loss. Convert back to bigint before
+ * calling `computeUserOpHash` or `serializeUserOpToJsonRpc`.
+ */
+interface PendingUserOpEntry {
+    sender: Address;
+    nonce: string;
+    callData: Hex;
+    callGasLimit: string;
+    verificationGasLimit: string;
+    preVerificationGas: string;
+    maxFeePerGas: string;
+    maxPriorityFeePerGas: string;
+    paymaster?: Address;
+    paymasterVerificationGasLimit?: string;
+    paymasterPostOpGasLimit?: string;
+    paymasterData?: Hex;
+    chainId: number;
+    /** Hex-encoded userOpHash — the value the user signed via personal_sign. */
+    userOpHash: Hex;
+}
+/**
+ * Storage backend for pending UserOps in the mobile prepare/submit pattern.
+ *
+ * Implement this interface and wire it into your issuer backend:
+ *   - `save()` — called by `POST /claim/prepare` and `POST /redeem/prepare`
+ *   - `get()`  — called by `POST /claim/submit` and `POST /redeem/submit`
+ *   - `delete()` — called after successful submit or explicit cancellation
+ *
+ * The default implementation in the gg56 boilerplate uses Redis with
+ * a short TTL matching the MintRequest / BurnRequest deadline.
+ */
+interface IPendingUserOpStore {
+    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
+    get(lockId: string): Promise<PendingUserOpEntry | null>;
+    delete(lockId: string): Promise<void>;
+}
+
+interface IssuerRegistryRecord {
+    issuerAddress: Address;
+    signerAddress: Address;
+    name: string;
+    symbol: string;
+    declaredTotalSupply: bigint;
+    capBasisPoints: number;
+    active: boolean;
+    pointToken: Address;
+    mintingOracle: Address;
+}
+interface PreValidateMintResult {
+    /** Registry record read at pre-validation time. */
+    issuer: IssuerRegistryRecord;
+    /** Current on-chain PointToken.totalSupply(). */
+    totalSupply: bigint;
+    /** declaredTotalSupply × capBasisPoints / 10000. */
+    hardCap: bigint;
+    /** hardCap − totalSupply (clamped to 0). */
+    remaining: bigint;
+}
+/**
+ * Thrown by `IssuerStateValidator.preValidateMint()`.
+ * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
+ */
+declare class IssuerStateError extends Error {
+    readonly code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED", message: string, details?: Record<string, unknown> | undefined);
+}
+
+/**
+ * Pure (framework-agnostic) validator for issuer state.
+ *
+ * Reads IssuerRegistry + PointToken on-chain state and pre-validates
+ * mint requests before the user submits a UserOp. Catching these
+ * off-chain lets issuers fail fast with a clear error rather than
+ * wasting gas on a revert.
+ *
+ * Caching:
+ *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
+ *   - Full state (registry + totalSupply) — 30s TTL per PointToken
+ *   - Burst calls while a fetch is in-flight share the same Promise
+ *     (thundering-herd protection)
+ *
+ * Usage in NestJS: wrap this in an `@Injectable()` service; pass
+ * `PublicClient` and `registryAddress` from your DI container.
+ */
+declare class IssuerStateValidator {
+    private readonly provider;
+    private readonly registryAddress;
+    private readonly pointTokenIssuerCache;
+    private readonly stateCache;
+    private readonly inflight;
+    constructor(provider: PublicClient, registryAddress: Address);
+    /**
+     * Convenience factory — reads `registryAddress` from the SDK
+     * `CONTRACT_ADDRESSES` map for the given chain.
+     */
+    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.
+     */
+    invalidate(pointToken?: Address): void;
+    /**
+     * Resolve `PointToken.issuer()` once per token and memoize.
+     * The issuer field is set at `initialize()` and never changes.
+     */
+    getIssuerAddressForPointToken(pointToken: Address): Promise<Address>;
+    /**
+     * Read registry record + totalSupply, with 30s cache and in-flight
+     * deduplication. Does NOT throw on inactive/missing — returns raw state.
+     */
+    getIssuerState(pointToken: Address): Promise<PreValidateMintResult>;
+    /**
+     * Validate that `amount` PT can be minted on `pointToken` right now.
+     *
+     * Throws `IssuerStateError` with:
+     *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
+     *   - `ISSUER_INACTIVE`       — issuer.active is false
+     *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
+     *
+     * Returns the fetched state on success so callers can log without a
+     * second RPC round-trip.
+     */
+    preValidateMint(pointToken: Address, amount: bigint): Promise<PreValidateMintResult>;
+    private fetchIssuerState;
+}
+
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.4.0";
 
-export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintingStatus, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, RelayError, type RelayErrorCode, RelayService, type RelayUserOpRequest, type RelayUserOpResponse, type RetryConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };
+export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintingStatus, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, RelayError, type RelayErrorCode, RelayService, type RelayUserOpRequest, type RelayUserOpResponse, type RetryConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };

package/dist/index.d.ts

@@ -1599,7 +1599,138 @@ interface IssuerService {
  */
 declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
 
+/**
+ * A pending UserOp serialized for persistent storage (Redis, Postgres, memory).
+ *
+ * All bigint fields are stored as decimal strings so the entry can be
+ * JSON-serialized without precision loss. Convert back to bigint before
+ * calling `computeUserOpHash` or `serializeUserOpToJsonRpc`.
+ */
+interface PendingUserOpEntry {
+    sender: Address;
+    nonce: string;
+    callData: Hex;
+    callGasLimit: string;
+    verificationGasLimit: string;
+    preVerificationGas: string;
+    maxFeePerGas: string;
+    maxPriorityFeePerGas: string;
+    paymaster?: Address;
+    paymasterVerificationGasLimit?: string;
+    paymasterPostOpGasLimit?: string;
+    paymasterData?: Hex;
+    chainId: number;
+    /** Hex-encoded userOpHash — the value the user signed via personal_sign. */
+    userOpHash: Hex;
+}
+/**
+ * Storage backend for pending UserOps in the mobile prepare/submit pattern.
+ *
+ * Implement this interface and wire it into your issuer backend:
+ *   - `save()` — called by `POST /claim/prepare` and `POST /redeem/prepare`
+ *   - `get()`  — called by `POST /claim/submit` and `POST /redeem/submit`
+ *   - `delete()` — called after successful submit or explicit cancellation
+ *
+ * The default implementation in the gg56 boilerplate uses Redis with
+ * a short TTL matching the MintRequest / BurnRequest deadline.
+ */
+interface IPendingUserOpStore {
+    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
+    get(lockId: string): Promise<PendingUserOpEntry | null>;
+    delete(lockId: string): Promise<void>;
+}
+
+interface IssuerRegistryRecord {
+    issuerAddress: Address;
+    signerAddress: Address;
+    name: string;
+    symbol: string;
+    declaredTotalSupply: bigint;
+    capBasisPoints: number;
+    active: boolean;
+    pointToken: Address;
+    mintingOracle: Address;
+}
+interface PreValidateMintResult {
+    /** Registry record read at pre-validation time. */
+    issuer: IssuerRegistryRecord;
+    /** Current on-chain PointToken.totalSupply(). */
+    totalSupply: bigint;
+    /** declaredTotalSupply × capBasisPoints / 10000. */
+    hardCap: bigint;
+    /** hardCap − totalSupply (clamped to 0). */
+    remaining: bigint;
+}
+/**
+ * Thrown by `IssuerStateValidator.preValidateMint()`.
+ * `code` maps 1:1 to the HTTP error the issuer API surfaces to clients.
+ */
+declare class IssuerStateError extends Error {
+    readonly code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED";
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: "ISSUER_NOT_REGISTERED" | "ISSUER_INACTIVE" | "MINT_CAP_EXCEEDED", message: string, details?: Record<string, unknown> | undefined);
+}
+
+/**
+ * Pure (framework-agnostic) validator for issuer state.
+ *
+ * Reads IssuerRegistry + PointToken on-chain state and pre-validates
+ * mint requests before the user submits a UserOp. Catching these
+ * off-chain lets issuers fail fast with a clear error rather than
+ * wasting gas on a revert.
+ *
+ * Caching:
+ *   - `PointToken.issuer()` — memoized for the process lifetime (immutable)
+ *   - Full state (registry + totalSupply) — 30s TTL per PointToken
+ *   - Burst calls while a fetch is in-flight share the same Promise
+ *     (thundering-herd protection)
+ *
+ * Usage in NestJS: wrap this in an `@Injectable()` service; pass
+ * `PublicClient` and `registryAddress` from your DI container.
+ */
+declare class IssuerStateValidator {
+    private readonly provider;
+    private readonly registryAddress;
+    private readonly pointTokenIssuerCache;
+    private readonly stateCache;
+    private readonly inflight;
+    constructor(provider: PublicClient, registryAddress: Address);
+    /**
+     * Convenience factory — reads `registryAddress` from the SDK
+     * `CONTRACT_ADDRESSES` map for the given chain.
+     */
+    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.
+     */
+    invalidate(pointToken?: Address): void;
+    /**
+     * Resolve `PointToken.issuer()` once per token and memoize.
+     * The issuer field is set at `initialize()` and never changes.
+     */
+    getIssuerAddressForPointToken(pointToken: Address): Promise<Address>;
+    /**
+     * Read registry record + totalSupply, with 30s cache and in-flight
+     * deduplication. Does NOT throw on inactive/missing — returns raw state.
+     */
+    getIssuerState(pointToken: Address): Promise<PreValidateMintResult>;
+    /**
+     * Validate that `amount` PT can be minted on `pointToken` right now.
+     *
+     * Throws `IssuerStateError` with:
+     *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
+     *   - `ISSUER_INACTIVE`       — issuer.active is false
+     *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
+     *
+     * Returns the fetched state on success so callers can log without a
+     * second RPC round-trip.
+     */
+    preValidateMint(pointToken: Address, amount: bigint): Promise<PreValidateMintResult>;
+    private fetchIssuerState;
+}
+
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.4.0";
 
-export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintingStatus, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, RelayError, type RelayErrorCode, RelayService, type RelayUserOpRequest, type RelayUserOpResponse, type RetryConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };
+export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintingStatus, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, RelayError, type RelayErrorCode, RelayService, type RelayUserOpRequest, type RelayUserOpResponse, type RetryConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };

package/dist/index.js

@@ -2056,6 +2056,180 @@ function createIssuerService(config) {
   };
 }
 
+// src/issuer-state/validator.ts
+import { getAddress as getAddress9 } from "viem";
+import {
+  POINT_TOKEN_V2_ABI as POINT_TOKEN_V2_ABI3,
+  issuerRegistryAbi,
+  getContractAddresses as getContractAddresses2
+} from "@pafi-dev/core";
+
+// src/issuer-state/types.ts
+var IssuerStateError = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "IssuerStateError";
+  }
+  code;
+  details;
+};
+
+// src/issuer-state/validator.ts
+var ISSUER_RECORD_TTL_MS = 3e4;
+var IssuerStateValidator = class _IssuerStateValidator {
+  constructor(provider, registryAddress) {
+    this.provider = provider;
+    this.registryAddress = registryAddress;
+  }
+  provider;
+  registryAddress;
+  pointTokenIssuerCache = /* @__PURE__ */ new Map();
+  stateCache = /* @__PURE__ */ new Map();
+  inflight = /* @__PURE__ */ new Map();
+  /**
+   * Convenience factory — reads `registryAddress` from the SDK
+   * `CONTRACT_ADDRESSES` map for the given chain.
+   */
+  static forChain(provider, chainId) {
+    const { issuerRegistry } = getContractAddresses2(chainId);
+    return new _IssuerStateValidator(provider, issuerRegistry);
+  }
+  /**
+   * Invalidate cached state for one PointToken, or everything if omitted.
+   * Call after admin txs that change registry or cap settings.
+   */
+  invalidate(pointToken) {
+    if (pointToken) {
+      const key = getAddress9(pointToken);
+      this.pointTokenIssuerCache.delete(key);
+      this.stateCache.delete(key);
+      this.inflight.delete(key);
+    } else {
+      this.pointTokenIssuerCache.clear();
+      this.stateCache.clear();
+      this.inflight.clear();
+    }
+  }
+  /**
+   * Resolve `PointToken.issuer()` once per token and memoize.
+   * The issuer field is set at `initialize()` and never changes.
+   */
+  async getIssuerAddressForPointToken(pointToken) {
+    const key = getAddress9(pointToken);
+    const cached = this.pointTokenIssuerCache.get(key);
+    if (cached) return cached;
+    const issuer = await this.provider.readContract({
+      address: key,
+      abi: POINT_TOKEN_V2_ABI3,
+      functionName: "issuer"
+    });
+    this.pointTokenIssuerCache.set(key, getAddress9(issuer));
+    return getAddress9(issuer);
+  }
+  /**
+   * Read registry record + totalSupply, with 30s cache and in-flight
+   * deduplication. Does NOT throw on inactive/missing — returns raw state.
+   */
+  async getIssuerState(pointToken) {
+    const tokenAddr = getAddress9(pointToken);
+    const now = Date.now();
+    const cached = this.stateCache.get(tokenAddr);
+    if (cached && cached.expiresAt > now) return cached.value;
+    const existing = this.inflight.get(tokenAddr);
+    if (existing) return existing;
+    const promise = this.fetchIssuerState(tokenAddr).then((state) => {
+      this.stateCache.set(tokenAddr, {
+        value: state,
+        expiresAt: Date.now() + ISSUER_RECORD_TTL_MS
+      });
+      return state;
+    }).finally(() => {
+      this.inflight.delete(tokenAddr);
+    });
+    this.inflight.set(tokenAddr, promise);
+    return promise;
+  }
+  /**
+   * Validate that `amount` PT can be minted on `pointToken` right now.
+   *
+   * Throws `IssuerStateError` with:
+   *   - `ISSUER_NOT_REGISTERED` — registry has no record for this issuer
+   *   - `ISSUER_INACTIVE`       — issuer.active is false
+   *   - `MINT_CAP_EXCEEDED`     — totalSupply + amount would exceed hardCap
+   *
+   * Returns the fetched state on success so callers can log without a
+   * second RPC round-trip.
+   */
+  async preValidateMint(pointToken, amount) {
+    let state;
+    try {
+      state = await this.getIssuerState(pointToken);
+    } catch (err) {
+      if (err.message.includes("IssuerNotFound")) {
+        throw new IssuerStateError(
+          "ISSUER_NOT_REGISTERED",
+          `IssuerRegistry has no record for PointToken ${pointToken}`,
+          { pointToken }
+        );
+      }
+      throw err;
+    }
+    const { issuer, totalSupply, hardCap, remaining } = state;
+    if (!issuer.active) {
+      throw new IssuerStateError(
+        "ISSUER_INACTIVE",
+        `Issuer ${issuer.issuerAddress} is deactivated on IssuerRegistry`,
+        { issuer: issuer.issuerAddress, pointToken: issuer.pointToken }
+      );
+    }
+    if (totalSupply + amount > hardCap) {
+      throw new IssuerStateError(
+        "MINT_CAP_EXCEEDED",
+        `Requested ${amount} PT would exceed mint cap. Cap=${hardCap}, minted=${totalSupply}, remaining=${remaining}`,
+        {
+          requested: amount.toString(),
+          cap: hardCap.toString(),
+          minted: totalSupply.toString(),
+          remaining: remaining.toString()
+        }
+      );
+    }
+    return state;
+  }
+  async fetchIssuerState(tokenAddr) {
+    const issuerAddr = await this.getIssuerAddressForPointToken(tokenAddr);
+    const [tuple, totalSupply] = await Promise.all([
+      this.provider.readContract({
+        address: this.registryAddress,
+        abi: issuerRegistryAbi,
+        functionName: "getIssuer",
+        args: [issuerAddr]
+      }),
+      this.provider.readContract({
+        address: tokenAddr,
+        abi: POINT_TOKEN_V2_ABI3,
+        functionName: "totalSupply"
+      })
+    ]);
+    const issuer = {
+      issuerAddress: tuple[0],
+      signerAddress: tuple[1],
+      name: tuple[2],
+      symbol: tuple[3],
+      declaredTotalSupply: tuple[4],
+      capBasisPoints: tuple[5],
+      active: tuple[6],
+      pointToken: tuple[7],
+      mintingOracle: tuple[8]
+    };
+    const hardCap = issuer.declaredTotalSupply * BigInt(issuer.capBasisPoints) / 10000n;
+    const remaining = hardCap > totalSupply ? hardCap - totalSupply : 0n;
+    return { issuer, totalSupply, hardCap, remaining };
+  }
+};
+
 // src/index.ts
 var PAFI_ISSUER_SDK_VERSION = "0.4.0";
 export {
@@ -2067,6 +2241,8 @@ export {
   FeeManager,
   InMemoryCursorStore,
   IssuerApiHandlers,
+  IssuerStateError,
+  IssuerStateValidator,
   MemorySessionStore,
   NonceManager,
   PAFI_ISSUER_SDK_VERSION,