@pafi-dev/issuer 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1303 @@
+import { Address, Hex, PublicClient, Chain } from 'viem';
+import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, ReceiverConsent, PathKey, PoolKey } from '@pafi-dev/core';
+export { encodeExtData } from '@pafi-dev/core';
+
+/**
+ * Lifecycle of a minting request as tracked by the issuer's point ledger.
+ *
+ *   PENDING ── on-chain mint confirmed ──▶ MINTED
+ *      │
+ *      ├── deadline elapsed without mint ─▶ EXPIRED
+ *      │
+ *      └── tx reverted / cancelled ──────▶ FAILED
+ */
+type MintingStatus = "PENDING" | "MINTED" | "EXPIRED" | "FAILED";
+/** A locked-amount entry tracking an in-flight mint request. */
+interface LockedMintRequest {
+    /** Opaque lock id (used to release / update later) */
+    lockId: string;
+    userAddress: Address;
+    amount: bigint;
+    /** Lifecycle status */
+    status: MintingStatus;
+    /** When the lock was created (epoch ms) */
+    createdAt: number;
+    /** When the lock auto-expires if not resolved (epoch ms) */
+    expiresAt: number;
+    /** On-chain transaction hash, set once the mint is confirmed */
+    txHash?: Hex;
+}
+/**
+ * Issuer point ledger interface — the source of truth for off-chain user
+ * point balances and in-flight minting requests.
+ *
+ * Issuers replace the in-memory default with their own database-backed
+ * implementation (Postgres, Redis, etc.).
+ */
+interface IPointLedger {
+    /** Get a user's available off-chain point balance (excluding locked). */
+    getBalance(userAddress: Address): Promise<bigint>;
+    /**
+     * Lock an amount for a pending mint request. Locked amounts are reserved
+     * but not yet deducted; they protect against double-spend during the
+     * EIP-712 validity window.
+     *
+     * @param lockDurationMs how long the lock should be held before auto-expiry
+     * @returns lockId — opaque handle used by `releaseLock` / `updateMintStatus`
+     * @throws if the user's available balance is below `amount`
+     */
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number): Promise<string>;
+    /** Release a previously created lock (e.g. on tx failure / cancel). */
+    releaseLock(lockId: string): Promise<void>;
+    /**
+     * Permanently deduct an amount from a user's balance after the on-chain
+     * mint has been observed by the indexer. Should also resolve any matching
+     * lock so the funds aren't double-counted.
+     */
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex): Promise<void>;
+    /** Credit points to a user's balance (e.g. from merchant activity). */
+    creditBalance(userAddress: Address, amount: bigint, reason: string): Promise<void>;
+    /** List currently-pending locked mint requests for a user. */
+    getLockedRequests(userAddress: Address): Promise<LockedMintRequest[]>;
+    /**
+     * Transition a lock to a new lifecycle status. The on-chain tx hash is
+     * supplied when the status is `MINTED`.
+     */
+    updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
+}
+
+/**
+ * In-memory IPointLedger implementation for development and tests.
+ *
+ * NOT for production — state is lost on restart. Issuers should ship their
+ * own database-backed implementation.
+ *
+ * Concurrency model: single-process, single-threaded (Node.js event loop).
+ * The lock check + insert is atomic within a tick because no awaits sit
+ * between balance read and lock write.
+ */
+declare class MemoryPointLedger implements IPointLedger {
+    private balances;
+    private locks;
+    private nextLockId;
+    private now;
+    constructor(opts?: {
+        now?: () => number;
+    });
+    getBalance(userAddress: Address): Promise<bigint>;
+    getLockedRequests(userAddress: Address): Promise<LockedMintRequest[]>;
+    creditBalance(userAddress: Address, amount: bigint, _reason: string): Promise<void>;
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number): Promise<string>;
+    releaseLock(lockId: string): Promise<void>;
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex): Promise<void>;
+    updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
+    /**
+     * Auto-expire any PENDING lock past its expiry. Called lazily on every
+     * read/write so the in-memory state stays self-cleaning without a timer.
+     */
+    private purgeExpired;
+    private lockedTotalFor;
+}
+
+/**
+ * Input to a policy evaluation. Policy engines use this to decide whether
+ * a user's mint request should be approved.
+ */
+interface PolicyEvalRequest {
+    userAddress: Address;
+    amount: bigint;
+    pointTokenAddress: Address;
+    chainId: number;
+}
+/** Outcome of a policy evaluation. */
+interface PolicyDecision {
+    approved: boolean;
+    /**
+     * Human-readable reason for rejection (empty on approval). Callers surface
+     * this back to the user, so keep it short and non-leaky.
+     */
+    reason?: string;
+}
+/**
+ * Policy engine — evaluates whether a minting request passes issuer rules.
+ * Issuers extend the default implementation to add KYC, volume caps, claim
+ * budgets, etc.
+ */
+interface IPolicyEngine {
+    evaluate(request: PolicyEvalRequest): Promise<PolicyDecision>;
+}
+
+/**
+ * Options for constructing a DefaultPolicyEngine.
+ *
+ * `mintingOracleAddress` and `provider` are optional — if omitted, the
+ * engine skips the on-chain cap check (useful for dev/testing).
+ *
+ * `verifyMintCap` is injectable so tests can simulate cap rejections
+ * without needing a real contract.
+ */
+interface DefaultPolicyEngineOptions {
+    ledger: IPointLedger;
+    provider?: PublicClient;
+    mintingOracleAddress?: Address;
+    /**
+     * Override the on-chain cap check. Defaults to `@pafi/core`'s
+     * `verifyMintCap`, which reverts if the issuer's declared supply would
+     * be exceeded. A rejected check should throw; returning normally is pass.
+     */
+    verifyMintCap?: (client: PublicClient, oracle: Address, issuer: Address, amount: bigint) => Promise<void>;
+    /**
+     * Resolve a point-token address to the issuer address for the cap check.
+     * Required iff `mintingOracleAddress + provider` are supplied.
+     */
+    resolveIssuer?: (pointToken: Address) => Promise<Address>;
+}
+/**
+ * Default policy engine — performs two checks:
+ *
+ *  1. **Off-chain balance** — the user must have at least `amount` of
+ *     unlocked point balance in the issuer ledger.
+ *  2. **On-chain cap** — (optional) calls the MintingOracle via
+ *     `verifyMintCap` to confirm that minting this amount would not exceed
+ *     the issuer's declared total supply.
+ *
+ * Issuers extend this class (or implement `IPolicyEngine` directly) to add
+ * KYC, volume caps, claim budgets, or anti-abuse rules.
+ */
+declare class DefaultPolicyEngine implements IPolicyEngine {
+    private readonly ledger;
+    private readonly provider?;
+    private readonly mintingOracleAddress?;
+    private readonly verifyMintCap?;
+    private readonly resolveIssuer?;
+    constructor(opts: DefaultPolicyEngineOptions);
+    evaluate(request: PolicyEvalRequest): Promise<PolicyDecision>;
+}
+
+/**
+ * Issuer signer — produces the MintRequest EIP-712 signature that the Relay
+ * contract verifies against the issuer's on-chain authorized minter.
+ *
+ * This is a trust boundary: the default `PrivateKeySigner` holds the key in
+ * process memory and is intended for local development only. Production
+ * issuers replace this with an HSM/KMS/MPC integration.
+ */
+interface IIssuerSigner {
+    /**
+     * Sign a `MintRequest` message against the point token's EIP-712 domain.
+     * The returned signature is what the Relay contract passes to
+     * `PointToken.verify` during `mintAndSwap`.
+     */
+    signMintRequest(domain: PointTokenDomainConfig, message: MintRequest): Promise<EIP712Signature>;
+    /** Get the signer's on-chain address (used for verification / logging). */
+    getAddress(): Promise<Address>;
+}
+
+interface PrivateKeySignerOptions {
+    /** 0x-prefixed 32-byte hex private key */
+    privateKey: Hex;
+    /**
+     * Chain metadata for the viem WalletClient. Only the chain id is actually
+     * used for signing; a minimal stub is acceptable (it does not need to
+     * match the deployed chain config beyond id).
+     */
+    chain: Chain;
+    /**
+     * Optional RPC URL. `signTypedData` is offline, so this can usually be
+     * left unset — viem only requires a transport to construct the client.
+     */
+    rpcUrl?: string;
+}
+/**
+ * Local-key implementation of `IIssuerSigner`. Wraps viem's `signTypedData`
+ * via the shared `@pafi/core` `signMintRequest` helper.
+ *
+ * ⚠️ **NOT for production use.** The private key lives in process memory
+ * and is trivially extractable from a compromised host. Replace with an
+ * HSM/KMS/MPC-backed `IIssuerSigner` before deployment.
+ */
+declare class PrivateKeySigner implements IIssuerSigner {
+    private readonly account;
+    private readonly walletClient;
+    constructor(opts: PrivateKeySignerOptions);
+    signMintRequest(domain: PointTokenDomainConfig, message: MintRequest): Promise<EIP712Signature>;
+    getAddress(): Promise<Address>;
+}
+
+/**
+ * A server-issued session created after a successful wallet login. The
+ * token id is embedded in the JWT so sessions can be revoked without
+ * invalidating the JWT signing key.
+ */
+interface Session {
+    tokenId: string;
+    userAddress: Address;
+    chainId: number;
+    issuedAt: Date;
+    expiresAt: Date;
+}
+/**
+ * Backend store for login nonces and active sessions.
+ *
+ * The default in-memory implementation is fine for local development but
+ * production issuers should plug in Redis / a SQL table so sessions
+ * survive restarts and are visible across replicas.
+ */
+interface ISessionStore {
+    /**
+     * Create a single-use login nonce and return it to the caller. Consumers
+     * must call {@link consumeNonce} exactly once when the client returns a
+     * signed login message quoting this nonce.
+     */
+    createNonce(): Promise<string>;
+    /**
+     * Atomically validate + consume a login nonce. Returns `true` if the
+     * nonce was known and unexpired (and is now removed); `false` otherwise.
+     */
+    consumeNonce(nonce: string): Promise<boolean>;
+    /** Persist a newly issued session. */
+    createSession(session: Session): Promise<void>;
+    /** Look up a session by token id, or `null` if unknown / revoked / expired. */
+    getSession(tokenId: string): Promise<Session | null>;
+    /** Revoke a session by token id (logout). No-op if not found. */
+    revokeSession(tokenId: string): Promise<void>;
+    /**
+     * Revoke every session for a user address. Used when an issuer needs to
+     * force re-login (e.g. after a permissions change or suspected abuse).
+     */
+    revokeAllSessions(userAddress: Address): Promise<void>;
+}
+
+interface MemorySessionStoreOptions {
+    /**
+     * How long a login nonce is valid before auto-expiry. Defaults to 5 min,
+     * matching typical SIWE recommendations.
+     */
+    nonceTtlMs?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+/**
+ * In-memory `ISessionStore` — Map-backed nonces and sessions with lazy
+ * expiry sweeps on every read/write.
+ *
+ * Not safe across processes or restarts; intended for dev/test only.
+ */
+declare class MemorySessionStore implements ISessionStore {
+    private nonces;
+    private sessions;
+    private readonly nonceTtlMs;
+    private readonly now;
+    constructor(opts?: MemorySessionStoreOptions);
+    createNonce(): Promise<string>;
+    consumeNonce(nonce: string): Promise<boolean>;
+    createSession(session: Session): Promise<void>;
+    getSession(tokenId: string): Promise<Session | null>;
+    revokeSession(tokenId: string): Promise<void>;
+    revokeAllSessions(userAddress: Address): Promise<void>;
+    private purgeExpiredNonces;
+    private purgeExpiredSessions;
+}
+
+/**
+ * Thin wrapper around an `ISessionStore` exposing nonce generation and
+ * single-use consumption as its own named surface. AuthService uses it
+ * internally, and issuers can also use it directly for other flows that
+ * need replay protection (e.g. a CSRF-style challenge).
+ */
+declare class NonceManager {
+    private readonly store;
+    constructor(store: ISessionStore);
+    /** Generate a fresh login nonce. The store is responsible for TTL. */
+    generate(): Promise<string>;
+    /**
+     * Atomically validate + consume a nonce. Returns `true` iff the nonce
+     * was known and unexpired (and is now removed from the store).
+     */
+    consume(nonce: string): Promise<boolean>;
+}
+
+interface AuthServiceConfig {
+    sessionStore: ISessionStore;
+    /** HMAC secret for signing JWTs (HS256). At least 32 bytes recommended. */
+    jwtSecret: string;
+    /**
+     * JWT lifetime passed to `jose`. Accepts any of `jose`'s time strings
+     * (`"24h"`, `"7d"`, `"45m"`, …). Defaults to `"24h"`.
+     */
+    jwtExpiresIn?: string;
+    /**
+     * Expected domain in the login message, e.g. `"app.example.com"`. The
+     * SIWE spec requires the frontend to build the message with this exact
+     * domain; the backend rejects any mismatch.
+     */
+    domain: string;
+    /** Expected chain id. */
+    chainId: number;
+    /** Clock override for tests. */
+    now?: () => Date;
+}
+interface LoginResult {
+    token: string;
+    userAddress: Address;
+    tokenId: string;
+    expiresAt: Date;
+}
+interface AuthContext {
+    userAddress: Address;
+    chainId: number;
+    tokenId: string;
+}
+/**
+ * Wallet-based authentication service implementing the EIP-4361 (Sign-In
+ * With Ethereum) login flow with server-issued JWTs.
+ *
+ * Flow:
+ *   1. `getNonce()` — client fetches a nonce, stores it locally
+ *   2. Client constructs a login message with the nonce + signs with wallet
+ *   3. `login(message, signature)` — server validates fields + signature,
+ *      consumes the nonce, persists a session, returns a JWT
+ *   4. Protected endpoints call `verifyToken(token)` to resolve the user
+ *      context; the session is re-checked on every call, so `logout()`
+ *      revokes access immediately.
+ */
+declare class AuthService {
+    private readonly sessionStore;
+    private readonly jwtSecret;
+    private readonly jwtExpiresIn;
+    private readonly domain;
+    private readonly chainId;
+    private readonly nonceManager;
+    private readonly now;
+    constructor(config: AuthServiceConfig);
+    /** Generate a fresh login nonce. */
+    getNonce(): Promise<string>;
+    /**
+     * Verify a signed login message and issue a JWT on success.
+     * Throws an `AuthError` on any validation failure.
+     */
+    login(message: string, signature: Hex): Promise<LoginResult>;
+    /** Revoke the session backing the given JWT (logout). */
+    logout(token: string): Promise<void>;
+    /**
+     * Verify a JWT and return the authenticated user context. Throws an
+     * `AuthError` if the token is missing, malformed, expired, revoked, or
+     * signed by a different key.
+     */
+    verifyToken(token: string): Promise<AuthContext>;
+}
+
+/**
+ * Extracts a Bearer token from an `Authorization` header value and verifies
+ * it via the supplied `AuthService`. Framework-agnostic — issuers wrap this
+ * in their framework's middleware pattern (Express, Fastify, Hono, …).
+ *
+ * Throws an `AuthError` if the header is missing, malformed, or the token
+ * fails verification. Callers should translate the `err.code` into an
+ * appropriate HTTP status (401 for auth failures, 500 for anything else).
+ */
+declare function authenticateRequest(authHeader: string | undefined, authService: AuthService): Promise<AuthContext>;
+
+/**
+ * Error codes surfaced by the auth subsystem. Issuers can pattern-match on
+ * `err.code` to translate into framework-specific HTTP responses.
+ */
+type AuthErrorCode = "INVALID_MESSAGE" | "DOMAIN_MISMATCH" | "CHAIN_MISMATCH" | "NONCE_INVALID" | "MESSAGE_EXPIRED" | "MESSAGE_NOT_YET_VALID" | "SIGNATURE_INVALID" | "MISSING_TOKEN" | "MALFORMED_TOKEN" | "TOKEN_INVALID" | "TOKEN_EXPIRED" | "SESSION_REVOKED";
+declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    constructor(code: AuthErrorCode, message: string);
+}
+
+/**
+ * Parameters for a single `mintAndSwap` relay submission. This is the
+ * exact shape the Relay contract expects, with the two structs the
+ * `@pafi/core` calldata helpers build. The RelayService wires these
+ * through viem's `writeContract`.
+ */
+interface SubmitMintAndSwapParams {
+    mint: MintParams;
+    swap: SwapParams;
+}
+/**
+ * Result of a relay submission. `txHash` is returned immediately after
+ * the tx is broadcast; `receipt` is present only when the caller opted to
+ * wait for confirmation.
+ */
+interface RelayResult {
+    txHash: Hex;
+    blockNumber?: bigint;
+    gasUsed?: bigint;
+    status?: "success" | "reverted";
+}
+/**
+ * Errors raised by RelayService carry a `code` so the MintingGateway (or
+ * any caller) can decide whether to release the ledger lock.
+ */
+type RelayErrorCode = "NOT_CONFIGURED" | "ENCODE_FAILED" | "SIMULATION_FAILED" | "SUBMIT_FAILED" | "TX_REVERTED" | "TIMEOUT";
+declare class RelayError extends Error {
+    readonly code: RelayErrorCode;
+    readonly cause?: unknown;
+    constructor(code: RelayErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Interface an operator wallet must satisfy for the RelayService. Matches
+ * the subset of viem's `WalletClient` we actually call, so tests can pass
+ * a minimal mock instead of a full client.
+ */
+interface OperatorWalletLike {
+    writeContract: (args: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+        account?: {
+            address: Address;
+        };
+    }) => Promise<Hex>;
+    account?: {
+        address: Address;
+    } | undefined;
+}
+
+interface RelayServiceConfig {
+    /** Address of the deployed Relay contract (chain-specific). */
+    relayAddress: Address;
+    /** Operator wallet that pays gas and receives the operator fee. */
+    operatorWallet: OperatorWalletLike;
+    /**
+     * Provider used for pre-flight simulation and receipt waiting. Optional —
+     * if omitted, the service still broadcasts but returns only `txHash`
+     * (caller is responsible for confirmation tracking).
+     */
+    provider?: PublicClient;
+    /**
+     * If a provider is supplied, wait up to this many milliseconds for a
+     * receipt before timing out. Default: 60_000 (one minute).
+     */
+    confirmationTimeoutMs?: number;
+    /**
+     * Whether to run `simulateContract` before submitting. Catches most
+     * reverts locally without wasting gas. Default: true (when provider is
+     * supplied).
+     */
+    simulateBeforeSubmit?: boolean;
+}
+/**
+ * Submits `mintAndSwap` transactions to the Relay contract on behalf of
+ * the issuer. This is the single place the operator wallet is touched; the
+ * MintingGateway calls into `submitMintAndSwap()` after it has signed the
+ * MintRequest and verified the ReceiverConsent.
+ *
+ * The service is intentionally thin: calldata encoding stays in `@pafi/core`
+ * (`encodeMintAndSwap`), so on-chain ABI changes only ripple through one
+ * package.
+ */
+declare class RelayService {
+    private readonly relayAddress;
+    private readonly operatorWallet;
+    private readonly provider?;
+    private readonly confirmationTimeoutMs;
+    private readonly simulateBeforeSubmit;
+    constructor(config: RelayServiceConfig);
+    /** Address the operator wallet is broadcasting from (for logging). */
+    operatorAddress(): Address | undefined;
+    /**
+     * Build calldata for the Relay `mintAndSwap` function. Kept public so
+     * callers (e.g. the MintingGateway) can log or persist the encoded call
+     * for audit before broadcasting.
+     */
+    encodeCall(params: SubmitMintAndSwapParams): Hex;
+    /**
+     * Submit a `mintAndSwap` transaction. Flow:
+     *
+     *   1. (optional) pre-flight simulate via provider
+     *   2. writeContract through the operator wallet
+     *   3. (optional) wait for the receipt and surface gasUsed / status
+     *
+     * Throws a typed `RelayError` on any failure so the MintingGateway can
+     * decide whether to release the ledger lock (`SUBMIT_FAILED` and
+     * `SIMULATION_FAILED` are safe to release; `TX_REVERTED` and `TIMEOUT`
+     * need manual review because the tx may still land).
+     */
+    submitMintAndSwap(params: SubmitMintAndSwapParams): Promise<RelayResult>;
+}
+
+interface FeeManagerConfig {
+    /** Provider used for gas price + balance reads. */
+    provider: PublicClient;
+    /** Operator wallet whose native balance the manager monitors. */
+    operatorWallet: OperatorWalletLike;
+    /** USDT token address on the target chain (used for rebalance swaps). */
+    usdtAddress: Address;
+    /** Wrapped-native token address (WETH on Base/Ethereum, WMATIC, etc). */
+    nativeWrappedAddress: Address;
+    /**
+     * Typical gas used by a `mintAndSwap` transaction. Default: 500_000. The
+     * manager multiplies this by current gas price to get the native cost,
+     * then converts to USDT via the injected `quoteNativeToUsdt`.
+     */
+    mintAndSwapGasUnits?: bigint;
+    /**
+     * Safety margin applied to the gas estimate before charging the user.
+     * Expressed as a basis-point multiplier, e.g. 12_000 = 120%. Default 12_000.
+     */
+    gasPremiumBps?: number;
+    /**
+     * Price conversion: given an amount of native token (wei), return the
+     * equivalent amount of USDT. Injected so the manager is chain-agnostic —
+     * production wires this to `@pafi/core` V4 quoting or an oracle feed.
+     */
+    quoteNativeToUsdt: (amountNative: bigint) => Promise<bigint>;
+    /**
+     * Rebalance trigger: when the operator's native balance falls below
+     * `rebalanceThresholdWei`, `rebalanceIfNeeded()` swaps `rebalanceUsdtAmount`
+     * worth of USDT into native. Both optional — omit to disable rebalancing.
+     */
+    rebalanceThresholdWei?: bigint;
+    rebalanceUsdtAmount?: bigint;
+    /**
+     * Actual swap executor — the manager calls this when a rebalance is
+     * triggered. Injected so the SDK does not hard-code a DEX choice; the
+     * issuer wires it to the UniversalRouter (via `@pafi/core swap/`) or
+     * whatever liquidity venue they trust. Required iff the rebalance
+     * fields above are set.
+     */
+    swapUsdtToNative?: (amountUsdt: bigint) => Promise<void>;
+}
+/**
+ * Manages the operator wallet's economics:
+ *
+ *   1. `estimateGasFee()` — how many USDT to deduct from the swap proceeds
+ *      to cover the operator's gas cost for the upcoming `mintAndSwap`.
+ *   2. `rebalanceIfNeeded()` — when the operator's native balance gets
+ *      low, swap some of the accumulated USDT fee back into native gas
+ *      token so the operator never runs dry.
+ *
+ * Both calculations are intentionally injection-based: gas estimation and
+ * USDT→native swapping both depend on DEX state, which the SDK deliberately
+ * does not own. Issuers supply the conversion + swap functions.
+ */
+declare class FeeManager {
+    private readonly provider;
+    private readonly operatorWallet;
+    private readonly mintAndSwapGasUnits;
+    private readonly gasPremiumBps;
+    private readonly quoteNativeToUsdt;
+    private readonly rebalanceThresholdWei?;
+    private readonly rebalanceUsdtAmount?;
+    private readonly swapUsdtToNative?;
+    constructor(config: FeeManagerConfig);
+    /**
+     * Estimate the USDT fee the operator should charge for a single
+     * `mintAndSwap`. Computed as:
+     *
+     *   nativeCost = gasUnits × gasPrice
+     *   premiumNativeCost = nativeCost × premiumBps / 10_000
+     *   usdtFee = quoteNativeToUsdt(premiumNativeCost)
+     */
+    estimateGasFee(): Promise<bigint>;
+    /**
+     * Check the operator's native balance and, if it has dropped below the
+     * configured threshold, trigger a USDT→native rebalance via the injected
+     * `swapUsdtToNative` function.
+     *
+     * Returns `true` if a rebalance was performed, `false` otherwise.
+     * Silently no-ops when rebalance is not configured.
+     */
+    rebalanceIfNeeded(): Promise<boolean>;
+}
+
+/**
+ * End-user request for a full "burn points → receive USDT" flow. The
+ * receiver has already signed the `ReceiverConsent` EIP-712 message on
+ * the frontend; the issuer backend runs everything else.
+ */
+interface MintAndCashOutRequest {
+    /** Address owning the off-chain points (== receiver in the consent). */
+    userAddress: Address;
+    /** Point token contract to mint. */
+    pointTokenAddress: Address;
+    /** Chain id the relay will submit on. */
+    chainId: number;
+    /**
+     * EIP-712 domain for `pointTokenAddress`. The gateway passes this
+     * straight through to `@pafi/core` `verifyReceiverConsent` and the
+     * issuer signer. Callers typically fetch it once via
+     * `PafiSDK.getDomain()` and cache it.
+     */
+    domain: PointTokenDomainConfig;
+    /**
+     * Receiver consent message + signature, pre-built by the frontend. The
+     * message specifies `onBehalfOf = relay contract` and
+     * `originalReceiver = userAddress`, plus the amount, nonce, deadline,
+     * and encoded extData.
+     */
+    receiverConsent: ReceiverConsent;
+    receiverSignature: Hex;
+    /**
+     * Swap path for the USDT output. Empty array = "no swap" (rare — only
+     * useful for testing). Normally a single hop pointToken → USDT.
+     */
+    swapPath: PathKey[];
+    /** Swap deadline (unix seconds). */
+    swapDeadline: bigint;
+    /**
+     * Lock TTL (ms) to apply to the off-chain balance. The gateway computes
+     * a safe default from `receiverConsent.deadline` if omitted.
+     */
+    lockDurationMs?: number;
+}
+/**
+ * Result returned to the caller after a successful `processMintAndCashOut`.
+ * The `lockId` is preserved so the indexer can correlate the on-chain
+ * Mint event back to the ledger row (though that correlation is typically
+ * done by `(userAddress, amount)` in the default `MemoryPointLedger`).
+ */
+interface MintAndCashOutResponse {
+    txHash: Hex;
+    lockId: string;
+    blockNumber?: bigint;
+    gasUsed?: bigint;
+}
+/**
+ * Error codes a MintingGateway can surface. Callers (API handlers) map
+ * these to HTTP status codes. The `SAFE_TO_RETRY` field tells the caller
+ * whether the underlying lock was released — if not, the user should
+ * wait before retrying to avoid double-spend.
+ */
+type MintingGatewayErrorCode = "INVALID_REQUEST" | "INVALID_CONSENT_SIGNATURE" | "CONSENT_EXPIRED" | "POLICY_REJECTED" | "INSUFFICIENT_BALANCE" | "SIGNER_FAILED" | "RELAY_SIMULATION_FAILED" | "RELAY_SUBMIT_FAILED" | "RELAY_REVERTED" | "RELAY_TIMEOUT";
+declare class MintingGatewayError extends Error {
+    readonly code: MintingGatewayErrorCode;
+    /**
+     * True if the ledger lock was released before this error was thrown,
+     * meaning the user can safely retry. False means the funds are still
+     * locked (e.g. tx may still land on-chain) and retry would double-spend.
+     */
+    readonly safeToRetry: boolean;
+    readonly cause?: unknown;
+    constructor(code: MintingGatewayErrorCode, message: string, opts: {
+        safeToRetry: boolean;
+        cause?: unknown;
+    });
+}
+
+interface MintingGatewayConfig {
+    ledger: IPointLedger;
+    policy: IPolicyEngine;
+    signer: IIssuerSigner;
+    relayService: RelayService;
+    /**
+     * Clock override for tests. Defaults to `() => Date.now()`. Used to
+     * compute safe lock TTLs and to check consent deadlines.
+     */
+    now?: () => number;
+    /**
+     * Extra buffer (ms) added on top of `(consent.deadline - now)` when the
+     * caller doesn't supply a `lockDurationMs`. Default: 60_000 (one minute
+     * — roughly 2× the Base L2 block confirmation time).
+     */
+    defaultLockBufferMs?: number;
+}
+/**
+ * The MintingGateway is the central orchestrator that turns a user's
+ * signed ReceiverConsent into an on-chain `mintAndSwap` tx and a
+ * consistent off-chain ledger update.
+ *
+ * 11-step flow (per `PAFI_ISSUER_SDK_SPEC.md` §4.3):
+ *
+ *   1. Field validation (cheap rejects before any crypto)
+ *   2. Verify ReceiverConsent signature via `@pafi/core`
+ *   3. Check off-chain balance via ledger
+ *   4. Check locked requests via ledger
+ *   5. Run policy engine (balance + on-chain cap + issuer rules)
+ *   6. Lock the requested amount in the ledger
+ *   7. Sign MintRequest as issuer
+ *   8. Build MintParams + SwapParams
+ *   9. Submit via RelayService (encode + simulate + broadcast + wait)
+ *  10. Return { txHash, lockId, receipt fields }
+ *  11. On any failure, release the lock IF it's safe to retry — i.e. we
+ *      know the tx cannot still land on-chain. If the tx may have made
+ *      it (`TX_REVERTED` or `TIMEOUT`), we leave the lock alone and
+ *      surface `safeToRetry: false` so the caller doesn't double-spend.
+ *
+ * The gateway deliberately does NOT deduct the balance here. Deduction
+ * happens in the `PointIndexer` when the on-chain Mint event is observed,
+ * which is what makes the system crash-safe: if the gateway dies between
+ * broadcast and receipt, the indexer will still finalize the ledger.
+ */
+declare class MintingGateway {
+    private readonly ledger;
+    private readonly policy;
+    private readonly signer;
+    private readonly relayService;
+    private readonly now;
+    private readonly defaultLockBufferMs;
+    constructor(config: MintingGatewayConfig);
+    processMintAndCashOut(request: MintAndCashOutRequest): Promise<MintAndCashOutResponse>;
+    private computeLockDurationMs;
+    /**
+     * Map a RelayError to a MintingGatewayError, releasing the lock only
+     * when the tx definitely did not land. `TX_REVERTED` and `TIMEOUT`
+     * leave the lock in place because the tx may still be in the mempool
+     * or already mined — releasing would enable a double-spend on retry.
+     * Always throws.
+     */
+    private handleRelayFailure;
+    /**
+     * Release a lock, swallowing any secondary error. We never want a lock
+     * release failure to mask the original error — the lock will auto-expire
+     * via TTL anyway.
+     */
+    private releaseLockSafely;
+}
+
+/** Decoded Transfer(from=0x0 → to) event used to finalize a mint. */
+interface MintEvent {
+    /** Destination address (the user who received the minted points) */
+    to: Address;
+    /** Amount minted (in wei / base units) */
+    amount: bigint;
+    /** Block number the mint was included in */
+    blockNumber: bigint;
+    /** Transaction hash that emitted the event */
+    txHash: Hex;
+    /** Log index within the tx, for deterministic ordering */
+    logIndex: number;
+}
+/**
+ * Cursor persistence interface — the indexer reports the next block
+ * number it is about to process so the caller can write it to Redis /
+ * Postgres / a file. The SDK does not own persistence because every
+ * issuer has their own storage stack.
+ */
+interface IIndexerCursorStore {
+    /** Return the last persisted cursor (`undefined` on first run). */
+    load(): Promise<bigint | undefined>;
+    /** Persist a new cursor value. Called after each successful batch. */
+    save(blockNumber: bigint): Promise<void>;
+}
+/**
+ * No-op cursor store. Useful when the caller wants to drive the cursor
+ * entirely via `processBlockRange()` and doesn't need persistence.
+ */
+declare class InMemoryCursorStore implements IIndexerCursorStore {
+    private cursor;
+    load(): Promise<bigint | undefined>;
+    save(blockNumber: bigint): Promise<void>;
+}
+
+interface PointIndexerConfig {
+    provider: PublicClient;
+    pointTokenAddress: Address;
+    ledger: IPointLedger;
+    /**
+     * Block to start from on first run. Ignored if the cursor store already
+     * has a value. Defaults to `0n`.
+     */
+    fromBlock?: bigint;
+    /**
+     * Persistent cursor store. Defaults to an `InMemoryCursorStore` which
+     * only survives inside the current process.
+     */
+    cursorStore?: IIndexerCursorStore;
+    /**
+     * Reorg safety: only treat events as final after this many confirmations.
+     * The indexer reads `latestBlock - confirmations` as its high-water mark.
+     * Default: 3 (a conservative number for Base L2).
+     */
+    confirmations?: number;
+    /**
+     * How many blocks to scan per `getLogs` call. Keeps RPC pages bounded.
+     * Default: 2000 (comfortably under most provider page limits).
+     */
+    batchSize?: number;
+    /**
+     * Polling interval (ms) used by `start()`. Default: 5000 (5s).
+     */
+    pollIntervalMs?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+/**
+ * Watches `PointToken.Transfer(from=0x0 → to)` events and finalizes the
+ * issuer ledger on each confirmed mint.
+ *
+ * Finalization strategy (per event):
+ *   1. Find a PENDING locked mint request for `to` with matching amount.
+ *   2. Call `ledger.deductBalance(to, amount, txHash)` — this is idempotent
+ *      in the default `MemoryPointLedger` because deducting also resolves
+ *      the matching lock.
+ *   3. If no matching lock is found (e.g. a manual `PointToken.mint()` call
+ *      or a race where the lock already expired), log and skip — this
+ *      intentionally does NOT credit the ledger, because the gateway is
+ *      the only sanctioned way to spawn a mint.
+ *
+ * Reorg safety: events are only processed when they are at least
+ * `confirmations` blocks deep. A new `getLogs` call on every poll picks
+ * up finalized blocks from the persisted cursor.
+ *
+ * Pure-polling design (rather than `watchContractEvent`) keeps the SDK
+ * compatible with HTTP-only providers and with RPC rotation.
+ */
+declare class PointIndexer {
+    private readonly provider;
+    private readonly pointTokenAddress;
+    private readonly ledger;
+    private readonly cursorStore;
+    private readonly startBlock;
+    private readonly confirmations;
+    private readonly batchSize;
+    private readonly pollIntervalMs;
+    private running;
+    private timer;
+    constructor(config: PointIndexerConfig);
+    /** Begin polling. Schedules `tick()` on a loop. */
+    start(): void;
+    /** Stop polling. Safe to call multiple times. */
+    stop(): void;
+    /**
+     * Run one poll cycle: load cursor → scan [cursor, safeHead] in
+     * `batchSize` chunks → persist new cursor. Swallows any error and
+     * schedules the next tick. Visible for test harnesses via a public name.
+     */
+    tick(): Promise<void>;
+    private scheduleNext;
+    /**
+     * Scan `[from, to]` inclusive for mint events in `batchSize` chunks.
+     * Callers can use this directly to backfill a specific range without
+     * engaging `start()`. On completion, the cursor is advanced to `to + 1`.
+     */
+    processBlockRange(from: bigint, to: bigint): Promise<void>;
+    private decodeMintEvents;
+    /**
+     * Finalize a single mint event: match it to a PENDING lock in the
+     * ledger, then call `deductBalance` (which also resolves the lock in
+     * the default `MemoryPointLedger`).
+     *
+     * No-matching-lock is a valid state: it means either the lock already
+     * expired, or the mint was authorized out-of-band (e.g. a direct
+     * `PointToken.mint()` from an EOA minter for testing). In that case we
+     * do NOT touch the ledger — crediting here would silently allow the
+     * issuer to mint without going through the gateway.
+     */
+    private finalize;
+}
+
+interface ApiConfigResponse {
+    chainId: number;
+    contracts: {
+        pointToken?: Address;
+        relay?: Address;
+        issuerRegistry?: Address;
+        pointTokenFactory?: Address;
+        mintingOracle?: Address;
+        poolManager?: Address;
+        usdt?: Address;
+    };
+}
+interface ApiNonceResponse {
+    nonce: string;
+}
+interface ApiLoginRequest {
+    message: string;
+    signature: Hex;
+}
+interface ApiLoginResponse {
+    token: string;
+    userAddress: Address;
+    /** Unix ms when the JWT (and backing session) expires. */
+    expiresAt: number;
+}
+interface ApiGasFeeResponse {
+    /** Gas fee quoted in USDT (6-decimal base units). */
+    gasFeeUsdt: bigint;
+}
+interface ApiPoolsRequest {
+    chainId: number;
+    pointTokenAddress: Address;
+}
+interface ApiPoolsResponse {
+    pools: PoolKey[];
+}
+interface ApiUserRequest {
+    chainId: number;
+    userAddress: Address;
+    pointTokenAddress: Address;
+}
+interface ApiUserResponse {
+    mintRequestNonce: bigint;
+    receiverConsentNonce: bigint;
+    balance: bigint;
+    isMinter: boolean;
+}
+interface ApiClaimAndSwapRequest {
+    chainId: number;
+    pointTokenAddress: Address;
+    /**
+     * EIP-712 domain for the point token. Frontends read this once (via
+     * `PafiSDK.getDomain()` or a direct contract call) and include it on
+     * every claim request so the backend doesn't need to re-read it.
+     */
+    domain: PointTokenDomainConfig;
+    /** The full signed ReceiverConsent message. */
+    receiverConsent: ReceiverConsent;
+    /** Detached EIP-712 signature (`serialized` form from `@pafi/core`). */
+    receiverSignature: Hex;
+    /** Swap hop(s) from pointToken → USDT. */
+    swapPath: PathKey[];
+    /** Unix seconds. */
+    swapDeadline: bigint;
+}
+interface ApiClaimAndSwapResponse {
+    txHash: Hex;
+    lockId: string;
+    blockNumber?: bigint;
+    gasUsed?: bigint;
+}
+interface ApiBuildConsentTypedDataRequest {
+    chainId: number;
+    pointTokenAddress: Address;
+    receiverConsent: ReceiverConsent;
+}
+interface ApiBuildConsentTypedDataResponse {
+    typedData: {
+        domain: {
+            name: string;
+            version: string;
+            chainId: number;
+            verifyingContract: Address;
+        };
+        types: Record<string, {
+            name: string;
+            type: string;
+        }[]>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    };
+}
+type PoolsProvider = (request: ApiPoolsRequest) => Promise<ApiPoolsResponse>;
+
+interface IssuerApiHandlersConfig {
+    authService: AuthService;
+    gateway: MintingGateway;
+    ledger: IPointLedger;
+    /** Used by `handleUser` to read on-chain nonces and minter status. */
+    provider: PublicClient;
+    pointTokenAddress: Address;
+    chainId: number;
+    contracts: ApiConfigResponse["contracts"];
+    /** Required by `handleGasFee`; omit to disable the endpoint. */
+    feeManager?: FeeManager;
+    /** Required by `handlePools`; omit to disable the endpoint. */
+    poolsProvider?: PoolsProvider;
+}
+/**
+ * Framework-agnostic HTTP handlers that match the endpoints a `PafiSDK`
+ * frontend expects to call. Issuers wrap these in Express / Fastify /
+ * Hono / whatever — the handlers take plain inputs and return plain
+ * outputs, with `AuthError` / `MintingGatewayError` surfaced as typed
+ * exceptions.
+ *
+ * Every protected handler takes a pre-verified `userAddress` as its first
+ * argument. The issuer's middleware wraps `authenticateRequest()` from
+ * `@pafi/issuer` to extract that address from the Bearer token before
+ * routing.
+ */
+declare class IssuerApiHandlers {
+    private readonly authService;
+    private readonly gateway;
+    private readonly ledger;
+    private readonly provider;
+    private readonly pointTokenAddress;
+    private readonly chainId;
+    private readonly contracts;
+    private readonly feeManager?;
+    private readonly poolsProvider?;
+    constructor(config: IssuerApiHandlersConfig);
+    /** `GET /auth/nonce` */
+    handleGetNonce(): Promise<ApiNonceResponse>;
+    /** `POST /auth/login` */
+    handleLogin(body: ApiLoginRequest): Promise<ApiLoginResponse>;
+    /**
+     * `GET /config?chainId=<id>`
+     *
+     * Returns the contract addresses and chain id that the frontend SDK
+     * needs to build EIP-712 messages and interact with on-chain.
+     */
+    handleConfig(chainId: number): Promise<ApiConfigResponse>;
+    /** `GET /gas-fee` — quoted in USDT (6-decimal base units). */
+    handleGasFee(): Promise<ApiGasFeeResponse>;
+    /** `POST /auth/logout` */
+    handleLogout(token: string): Promise<void>;
+    /**
+     * `GET /pools?chainId=<id>&pointToken=<addr>`
+     *
+     * Delegates to the injected `PoolsProvider`. The handler itself does
+     * not know where pools come from — that's an issuer decision.
+     */
+    handlePools(_userAddress: Address, request: ApiPoolsRequest): Promise<ApiPoolsResponse>;
+    /**
+     * `GET /user?chainId=<id>&user=<addr>&pointToken=<addr>`
+     *
+     * Returns per-user state the frontend needs to build a fresh
+     * `ReceiverConsent`: on-chain nonces + minter status + off-chain
+     * balance.
+     */
+    handleUser(userAddress: Address, request: ApiUserRequest): Promise<ApiUserResponse>;
+    /**
+     * `POST /build-consent-typed-data`
+     *
+     * Backend builds the full EIP-712 typed data payload for a
+     * ReceiverConsent message. The domain (name, version, chainId,
+     * verifyingContract) is read from the PointToken contract — mobile
+     * never needs to know or hardcode these values. Forward the
+     * response directly to `wallet.signTypedData()`.
+     *
+     * This ensures a single source of truth for domain + types, and
+     * makes contract upgrades (domain version bump) transparent to
+     * mobile apps — no app store review needed.
+     */
+    handleBuildConsentTypedData(userAddress: Address, request: ApiBuildConsentTypedDataRequest): Promise<ApiBuildConsentTypedDataResponse>;
+    /**
+     * `POST /claim-and-swap`
+     *
+     * The terminal handler: forwards the verified consent to the
+     * MintingGateway, which runs the 11-step flow.
+     */
+    handleClaimAndSwap(userAddress: Address, request: ApiClaimAndSwapRequest): Promise<ApiClaimAndSwapResponse>;
+}
+
+/**
+ * Config for `createSubgraphPoolsProvider`.
+ */
+interface SubgraphPoolsProviderConfig {
+    /**
+     * Fully qualified subgraph GraphQL endpoint. Example:
+     * `https://graph.pacificfinance.org/subgraphs/name/pafi`
+     */
+    subgraphUrl: string;
+    /**
+     * Cache TTL in milliseconds. Pool discovery is near-static — a 30s
+     * cache removes subgraph load without meaningfully delaying UX.
+     * Set to 0 to disable caching. Default: 30_000.
+     */
+    cacheTtlMs?: number;
+    /**
+     * Optional fetch override for test harnesses. Defaults to global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional clock override for tests.
+     */
+    now?: () => number;
+}
+/**
+ * Create a `PoolsProvider` backed by the PAFI subgraph.
+ *
+ * Queries the `pafiTokens` entity for the given `pointTokenAddress`,
+ * reads its linked `Pool`, and returns a single-element `PoolKey[]`.
+ * Multiple pools per token would require a subgraph schema change.
+ *
+ * The result is cached in-process with a short TTL (default 30s). Pool
+ * discovery is near-static so this avoids hammering the subgraph without
+ * blocking config changes for long.
+ *
+ * Returns `{ pools: [] }` if:
+ *  - the token is not registered on PAFI yet (no PafiToken entity)
+ *  - the token is registered but its pool has not been initialised
+ *  - the subgraph is unreachable or returns an error (logs to console,
+ *    does not throw — callers should handle empty pool list gracefully)
+ *
+ * Assumes the PAFI subgraph schema. Issuers with a custom subgraph must
+ * implement `PoolsProvider` themselves instead of using this helper.
+ *
+ * @example
+ * ```ts
+ * import { createSubgraphPoolsProvider, createIssuerService } from "@pafi/issuer";
+ *
+ * const service = createIssuerService({
+ *   // ...other config
+ *   poolsProvider: createSubgraphPoolsProvider({
+ *     subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
+ *   }),
+ * });
+ * ```
+ */
+declare function createSubgraphPoolsProvider(config: SubgraphPoolsProviderConfig): PoolsProvider;
+
+/**
+ * Config for `createSubgraphNativeUsdtQuoter`.
+ */
+interface SubgraphNativeUsdtQuoterConfig {
+    /**
+     * Fully qualified subgraph GraphQL endpoint. Same URL used by
+     * `createSubgraphPoolsProvider`.
+     */
+    subgraphUrl: string;
+    /**
+     * Decimals of the USDT token. Defaults to 6 (standard USDT/USDC on
+     * Base, Ethereum, Polygon). Override for chains where USDT uses a
+     * different decimals value.
+     */
+    usdtDecimals?: number;
+    /**
+     * Decimals of the native token (ETH on Base/mainnet/Arbitrum/Optimism,
+     * MATIC on Polygon). Default: 18.
+     */
+    nativeDecimals?: number;
+    /**
+     * Cache TTL in milliseconds. ETH price drifts slowly relative to gas
+     * estimation needs — a 30s cache keeps fees stable across bursts of
+     * requests without letting them go stale during volatile markets.
+     * Set to 0 to disable caching. Default: 30_000.
+     */
+    cacheTtlMs?: number;
+    /**
+     * Fallback price (USDT per native token, human-readable float) used
+     * when the subgraph is unreachable. This keeps the backend operational
+     * during subgraph outages rather than bricking cashouts. The fee will
+     * be slightly off but the operator still gets paid. Default: 3000.
+     */
+    fallbackEthPriceUsd?: number;
+    /** Optional fetch override for test harnesses. */
+    fetchImpl?: typeof fetch;
+    /** Optional clock override for tests. */
+    now?: () => number;
+}
+/**
+ * Create a `quoteNativeToUsdt` function backed by the PAFI subgraph's
+ * `Bundle.ethPriceUSD`.
+ *
+ * Used by `FeeManager.estimateGasFee()` to convert the operator's native
+ * gas cost into the USDT amount deducted from the user's cashout. Price
+ * precision is not critical here — a 1-2% drift is acceptable since
+ * the operator already takes a `gasPremiumBps` buffer.
+ *
+ * The result is cached in-process with a short TTL (default 30s). If the
+ * subgraph is unreachable, falls back to `fallbackEthPriceUsd` so gas
+ * estimation doesn't block cashouts during a subgraph outage.
+ *
+ * @example
+ * ```ts
+ * import { createSubgraphNativeUsdtQuoter, createIssuerService } from "@pafi/issuer";
+ *
+ * const service = createIssuerService({
+ *   // ...other config
+ *   fee: {
+ *     quoteNativeToUsdt: createSubgraphNativeUsdtQuoter({
+ *       subgraphUrl: "https://graph.pacificfinance.org/subgraphs/name/pafi",
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function createSubgraphNativeUsdtQuoter(config: SubgraphNativeUsdtQuoterConfig): (amountNative: bigint) => Promise<bigint>;
+
+/**
+ * Top-level configuration for `createIssuerService`. Everything except
+ * the chain metadata, wallets, auth secret, and `signer` is optional and
+ * falls back to the in-memory dev defaults — that makes the happy path
+ * a single-call wire-up while still letting production issuers plug in
+ * their own ledger, session store, policy engine, and KMS signer.
+ */
+interface IssuerServiceConfig {
+    chainId: number;
+    /** Address of the deployed PointToken (one per issuer instance). */
+    pointTokenAddress: Address;
+    /** Address of the deployed Relay contract. */
+    relayAddress: Address;
+    /**
+     * Full contract address bundle returned verbatim by `handleConfig` so
+     * the frontend SDK can pick them up.
+     */
+    contracts: ApiConfigResponse["contracts"];
+    /**
+     * Shared `PublicClient` used for on-chain reads, simulation, indexer
+     * polling, and gas-price lookups. Must be pointed at the target chain.
+     */
+    provider: PublicClient;
+    /** Operator wallet — pays gas, receives the operator fee. */
+    operatorWallet: OperatorWalletLike;
+    auth: {
+        jwtSecret: string;
+        /** SIWE-style login-message domain, e.g. `"app.example.com"`. */
+        domain: string;
+        /** Passed straight to `jose` (`"24h"`, `"7d"`, …). Default `"24h"`. */
+        jwtExpiresIn?: string;
+    };
+    /**
+     * Issuer signer. No default — production issuers MUST plug in an
+     * HSM/KMS-backed implementation. For local development use
+     * `PrivateKeySigner` directly.
+     */
+    signer: IIssuerSigner;
+    ledger?: IPointLedger;
+    policy?: IPolicyEngine;
+    sessionStore?: ISessionStore;
+    /**
+     * Fee management config. If omitted the `handleGasFee` endpoint will
+     * throw "not configured" at request time. Pass any subset of fields
+     * to opt in — provider + operatorWallet are inherited from the outer
+     * config automatically.
+     */
+    fee?: Omit<FeeManagerConfig, "provider" | "operatorWallet">;
+    /**
+     * Pool discovery function for `handlePools`. If omitted the endpoint
+     * throws "not configured" at request time.
+     */
+    poolsProvider?: PoolsProvider;
+    indexer?: {
+        fromBlock?: bigint;
+        cursorStore?: IIndexerCursorStore;
+        confirmations?: number;
+        batchSize?: number;
+        pollIntervalMs?: number;
+        /**
+         * If `true`, the factory calls `indexer.start()` before returning.
+         * Default: `false` — the caller decides when to begin polling.
+         */
+        autoStart?: boolean;
+    };
+    relay?: {
+        simulateBeforeSubmit?: boolean;
+        confirmationTimeoutMs?: number;
+    };
+    gateway?: {
+        /** Extra lock TTL buffer beyond consent deadline. Default 60_000 ms. */
+        defaultLockBufferMs?: number;
+    };
+}
+interface IssuerService {
+    authService: AuthService;
+    sessionStore: ISessionStore;
+    ledger: IPointLedger;
+    policy: IPolicyEngine;
+    signer: IIssuerSigner;
+    relayService: RelayService;
+    feeManager: FeeManager | undefined;
+    gateway: MintingGateway;
+    indexer: PointIndexer;
+    handlers: IssuerApiHandlers;
+}
+/**
+ * Wire a fully-functional issuer service from a single config object.
+ * Returns every constructed collaborator so the caller can also use the
+ * indexer or relay service directly outside the HTTP layer.
+ *
+ * Defaults:
+ *  - `ledger`          → `MemoryPointLedger`
+ *  - `sessionStore`    → `MemorySessionStore`
+ *  - `policy`          → `DefaultPolicyEngine({ ledger })`
+ *  - `feeManager`      → undefined (handleGasFee throws until configured)
+ *  - `poolsProvider`   → undefined (handlePools throws until configured)
+ *  - `indexer.autoStart` → false
+ *
+ * Throws synchronously if any required field (`signer`, `provider`,
+ * `operatorWallet`, `auth.jwtSecret`, `pointTokenAddress`, …) is missing.
+ */
+declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
+
+/** SDK package version — bumped on every release */
+declare const PAFI_ISSUER_SDK_VERSION = "0.1.0";
+
+export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IIssuerSigner, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemoryPointLedger, MemorySessionStore, type MemorySessionStoreOptions, type MintAndCashOutRequest, type MintAndCashOutResponse, type MintEvent, MintingGateway, type MintingGatewayConfig, MintingGatewayError, type MintingGatewayErrorCode, type MintingStatus, NonceManager, type OperatorWalletLike, PAFI_ISSUER_SDK_VERSION, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, PrivateKeySigner, type PrivateKeySignerOptions, RelayError, type RelayErrorCode, type RelayResult, RelayService, type RelayServiceConfig, type Session, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SubmitMintAndSwapParams, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };