@pafi-dev/issuer 0.20.0 → 0.22.0

package/dist/index.d.cts

@@ -983,6 +983,56 @@ declare class InMemoryCursorStore implements IIndexerCursorStore {
     load(): Promise<bigint | undefined>;
     save(blockNumber: bigint): Promise<void>;
 }
+/**
+ * Lock handle returned by a successful `ISingletonLock.acquire()`.
+ *
+ * The holder is the leader for the keyed indexer; non-holders MUST NOT
+ * call `indexer.start()` (else they race against the leader's polling
+ * loop and last-writer-wins cursor save corrupts replay state).
+ *
+ * `release()` is called by the leader on graceful shutdown. If the
+ * leader crashes without calling release, the lock implementation
+ * MUST drop the lock automatically (e.g. Postgres advisory locks
+ * auto-release on connection close).
+ */
+interface SingletonLockHandle {
+    release(): Promise<void>;
+}
+/**
+ * Leader-election primitive for indexer singletons.
+ *
+ * **Why this exists (audit finding H-04):** the `BurnIndexer` and
+ * `PointIndexer` classes are stateful polling loops with a cursor
+ * stored in an external store. Running them on multiple replicas
+ * simultaneously causes:
+ *
+ *   1. Double-credit — both replicas see the same Transfer event
+ *      and call `ledger.resolveCreditByBurnTx` twice.
+ *   2. Cursor rewind — last-writer-wins `save()` causes the newer
+ *      cursor to be overwritten by a lagging replica's older value,
+ *      causing the next poll to replay events.
+ *   3. Skipped blocks — chunked range reads can leave gaps when two
+ *      replicas race-advance the cursor.
+ *
+ * **Adoption:** pass `singletonLock` into `IssuerServiceConfig.indexer`
+ * (or wire it directly in your provider). The factory will only call
+ * `indexer.start()` on the indexers it successfully acquires a lock
+ * for; the rest stay idle and take over instantly on lock release.
+ *
+ * **Implementations:** `makePostgresSingletonLock(dataSource)` (recommended
+ * — uses `pg_try_advisory_lock`, auto-releases on connection close).
+ * You can also bring your own: Redis SETNX with TTL, etcd lease, etc.
+ */
+interface ISingletonLock {
+    /**
+     * Attempt to acquire the lock for `key`. Returns a handle on success
+     * (caller is the leader), or `null` if another holder owns it.
+     *
+     * Implementations MUST be non-blocking — if the lock is held, return
+     * null immediately. The factory polls / retries at a higher layer.
+     */
+    acquire(key: string): Promise<SingletonLockHandle | null>;
+}
 
 interface PointIndexerConfig {
     provider: PublicClient;
@@ -1190,7 +1240,11 @@ interface BurnIndexerConfig {
  */
 declare class BurnIndexer {
     private readonly provider;
-    private readonly pointTokenAddress;
+    /**
+     * The PointToken this indexer watches. Exposed so callers can key
+     * leader-election locks / cursor stores by token (audit H-04 fix).
+     */
+    readonly pointTokenAddress: Address;
     private readonly ledger;
     private readonly cursorStore;
     private readonly startBlock;
@@ -1222,6 +1276,60 @@ declare class BurnIndexer {
     private finalize;
 }
 
+/**
+ * Minimal duck-typed adapter so we don't drag a TypeORM / pg dep into
+ * the SDK. The caller passes anything that can execute a parameterised
+ * query and yield `{ got: boolean }` rows — TypeORM `DataSource.query`,
+ * a raw `pg` client, knex's `raw`, kysely, etc.
+ *
+ * The helper requires `int8` (signed 64-bit) lock IDs. We derive them
+ * from the lock `key` via a deterministic hash so different replicas
+ * agree on the int regardless of casing / whitespace drift.
+ */
+interface PostgresQueryRunner {
+    query(sql: string, params?: unknown[]): Promise<unknown>;
+}
+/**
+ * Build an `ISingletonLock` backed by PostgreSQL session-level advisory
+ * locks (`pg_try_advisory_lock`).
+ *
+ * Why advisory locks (vs. row-level locks or a leases table):
+ *   1. **Non-blocking** — `pg_try_advisory_lock` returns immediately;
+ *      perfect for the "try then idle" pattern the SDK uses on boot.
+ *   2. **Auto-release on connection drop** — if the leader pod crashes,
+ *      its PG connection closes, and the lock is freed automatically.
+ *      No timeout tuning, no lease renewal loops, no zombie locks.
+ *   3. **Zero schema** — no extra table, no migration, no contention
+ *      with application reads.
+ *
+ * **Caveat — long-lived connection required.** Session-level locks are
+ * held only for the lifetime of the PG connection that called
+ * `pg_try_advisory_lock`. PgBouncer in `transaction` pooling mode will
+ * release the lock between statements; you MUST run in `session`
+ * pooling or skip the bouncer for the indexer process. The advisory
+ * `transaction` variant exists but doesn't fit the "hold while polling"
+ * pattern — for that you'd need a periodic re-acquire, which we don't
+ * implement here.
+ *
+ * @example
+ *   import { DataSource } from "typeorm";
+ *   import { makePostgresSingletonLock } from "@pafi-dev/issuer";
+ *
+ *   const dataSource = new DataSource({ ... });
+ *   const lock = makePostgresSingletonLock({
+ *     query: (sql, params) => dataSource.query(sql, params),
+ *   });
+ *
+ *   createIssuerService({
+ *     ...,
+ *     indexer: {
+ *       autoStart: true,
+ *       singletonLock: lock,
+ *     },
+ *   });
+ */
+declare function makePostgresSingletonLock(runner: PostgresQueryRunner): ISingletonLock;
+
 interface ApiConfigResponse {
     chainId: number;
     contracts: {
@@ -1652,6 +1760,43 @@ declare class IssuerApiHandlers {
     private requireSupportedToken;
 }
 
+/**
+ * Resolves the EIP-712 domain `name` for a PointToken. Used by handlers
+ * (PTClaimHandler / PTRedeemHandler) that sign requests for multiple
+ * PointTokens within the same issuer backend.
+ *
+ * Resolution order per address:
+ *   1. Cache hit → return immediately (no RPC)
+ *   2. Static override map (config.overrides) → cache + return
+ *   3. On-chain `name()` lookup → cache + return
+ *
+ * Cache is per-instance — share one resolver across handlers so mint +
+ * redeem paths amortise the same set of lookups.
+ *
+ * Why the override map: production issuers often know their PTs at
+ * boot (env / DB) and want to avoid RPC quota churn + tolerate transient
+ * RPC failures. The on-chain fallback handles ad-hoc PTs not in the map
+ * (e.g. newly deployed during the process lifetime).
+ */
+interface PointTokenDomainResolverConfig {
+    provider: PublicClient;
+    /**
+     * Optional pre-configured map — checksummed (or lowercased) PointToken
+     * address → ERC-20 `name()` value. When a PT's address is in this map,
+     * the resolver short-circuits without an RPC call.
+     */
+    overrides?: Record<string, string>;
+}
+declare class PointTokenDomainResolver {
+    private readonly provider;
+    private readonly overrides;
+    private readonly cache;
+    constructor(config: PointTokenDomainResolverConfig);
+    resolve(pointTokenAddress: Address): Promise<string>;
+    /** Invalidate one address (after deploy / proxy upgrade) or all. */
+    invalidate(pointTokenAddress?: Address): void;
+}
+
 /**
  * Reverse flow — user-initiated PT redeem.
  *
@@ -1681,22 +1826,20 @@ interface PTRedeemHandlerConfig {
     ledger: IPointLedger;
     relayService: RelayService;
     provider: PublicClient;
-    /** PointToken contract address (chain-specific). */
-    pointTokenAddress: Address;
     /** BatchExecutor delegation target (chain-specific). */
     batchExecutorAddress: Address;
     /** Chain id — used for the BurnRequest EIP-712 domain. */
     chainId: number;
     /**
-     * EIP-712 domain fields. Must match the on-chain PointToken's domain
-     * separator, or on-chain signature recovery fails. `name` is
-     * typically the PointToken's ERC-20 name. `verifyingContract`
-     * defaults to `pointTokenAddress`.
+     * Resolver for the EIP-712 domain `name` (= PointToken.name() on-chain).
+     * Required because mint/redeem now route the `pointTokenAddress` per
+     * request — the handler can't bind a single domain at construction.
+     * Pass a shared resolver instance so mint + redeem amortise the same
+     * cache. The handler always uses `pointTokenAddress` as the EIP-712
+     * `verifyingContract` — no override (per-PT domain separator is
+     * isolated by contract address).
      */
-    domain: {
-        name: string;
-        verifyingContract?: Address;
-    };
+    domainResolver: PointTokenDomainResolver;
     /**
      * Issuer burner signer wallet — signs the `BurnRequest` EIP-712.
      * Must be whitelisted via `PointToken.addBurner(signerAddr)` at
@@ -1739,6 +1882,10 @@ interface PTRedeemRequest {
     authenticatedAddress: Address;
     userAddress: Address;
     amount: bigint;
+    /** PointToken contract to redeem. The handler resolves the EIP-712
+     *  domain (name + verifyingContract) from this address via the
+     *  configured `domainResolver`. */
+    pointTokenAddress: Address;
     /** ERC-4337 account nonce for the user's EOA. */
     aaNonce: bigint;
     /**
@@ -1806,10 +1953,9 @@ declare class PTRedeemHandler {
     private readonly relayService;
     private readonly provider;
     private readonly feeService?;
-    private readonly pointTokenAddress;
     private readonly batchExecutorAddress;
     private readonly chainId;
-    private readonly domain;
+    private readonly domainResolver;
     private readonly burnerSignerWallet;
     private readonly redeemLockDurationMs;
     private readonly signatureDeadlineSeconds;
@@ -2524,11 +2670,14 @@ interface PTClaimHandlerConfig {
     /** Issuer minter signer wallet — passed through to RelayService.prepareMint. */
     issuerSignerWallet: WalletClient;
     /**
-     * EIP-712 domain `name` for `MintRequest`. Typically the PointToken
-     * ERC-20 name. RelayService will set chainId + verifyingContract from
-     * the request.
+     * Resolver for the EIP-712 domain `name` (= PointToken.name() on-chain).
+     * Required because mint routes the `pointTokenAddress` per request —
+     * the handler can't bind a single domain at construction. Pass a
+     * shared resolver instance so mint + redeem amortise the same cache.
+     * `chainId` + `verifyingContract` are derived from the request's
+     * `chainId` + `pointTokenAddress` respectively.
      */
-    pointTokenDomainName: string;
+    domainResolver: PointTokenDomainResolver;
     /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
     feeService?: FeeManager;
     /** Optional — pre-validates issuer status + cap before locking balance. */
@@ -2849,8 +2998,27 @@ interface IssuerServiceConfig {
         /**
          * If `true`, the factory calls `indexer.start()` before returning.
          * Default: `false` — the caller decides when to begin polling.
+         *
+         * **SAFETY (H-04):** in a multi-replica deployment, ALWAYS pair
+         * `autoStart: true` with `singletonLock` below. Without leader
+         * election, every replica starts its own indexer fleet and races
+         * against the others — see `ISingletonLock` docs for the
+         * consequences.
          */
         autoStart?: boolean;
+        /**
+         * Leader-election primitive. When provided, the factory wraps
+         * `indexer.start()` with a `singletonLock.acquire(key)` call and
+         * only starts the indexer if it wins the lock. Non-leaders stay
+         * idle and take over on the next acquire attempt (when the leader
+         * pod's connection drops, the lock auto-releases).
+         *
+         * The lock key includes the indexer kind + the PointToken address,
+         * so different tokens can be sharded across replicas if desired.
+         *
+         * Recommended: `makePostgresSingletonLock(dataSource)`.
+         */
+        singletonLock?: ISingletonLock;
         /**
          * Override the MintFeeWrapper address used by the indexer. When
          * omitted, the factory auto-resolves from
@@ -2896,6 +3064,13 @@ interface IssuerService {
     fee: FeeManager | undefined;
     /** All indexers keyed by PointToken address. */
     indexers: Map<Address, PointIndexer>;
+    /**
+     * Lock handles for the indexers this replica was elected leader for.
+     * Empty when `autoStart` is false, or when no `singletonLock` was
+     * provided. Call `release()` on each during graceful shutdown so
+     * peers can take over without waiting for the connection to die.
+     */
+    indexerLeaderLocks: SingletonLockHandle[];
     /** Framework-agnostic HTTP handlers — wire into Express / Fastify / Hono. */
     api: IssuerApiHandlers;
     /**
@@ -2917,7 +3092,7 @@ interface IssuerService {
  *
  * Throws synchronously if any required field is missing.
  */
-declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
+declare function createIssuerService(config: IssuerServiceConfig): Promise<IssuerService>;
 
 /**
  * Adapter that absorbs every "framework-agnostic" endpoint body into a
@@ -3096,6 +3271,7 @@ declare class IssuerApiAdapter {
     redeem(input: {
         authenticatedAddress: Address;
         chainId: number;
+        pointTokenAddress: Address;
         amount: bigint;
         aaNonce: bigint;
     }): Promise<RedeemDto>;
@@ -3656,4 +3832,4 @@ declare class MemoryRedemptionHistoryStore implements IRedemptionHistoryStore {
 
 declare const PAFI_ISSUER_SDK_VERSION: string;
 
-export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, type BundlerEstimatorClient, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EstimateGasFeeOptions, type EvaluateInput, FeeManager, type FeeManagerConfig, type FeeManagerMetrics, type FetchFailureReason, type FetchImpl, type FetchResult, type GasFeeDto, type GasFeeSource, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PafiEstimatorClientConfig, PafiEstimatorHttpError, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type PreviewBurnParams, type PreviewMintParams, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createPafiEstimatorClient, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, type BundlerEstimatorClient, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EstimateGasFeeOptions, type EvaluateInput, FeeManager, type FeeManagerConfig, type FeeManagerMetrics, type FetchFailureReason, type FetchImpl, type FetchResult, type GasFeeDto, type GasFeeSource, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, type ISingletonLock, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PafiEstimatorClientConfig, PafiEstimatorHttpError, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, PointTokenDomainResolver, type PointTokenDomainResolverConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PostgresQueryRunner, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type PreviewBurnParams, type PreviewMintParams, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SingletonLockHandle, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createPafiEstimatorClient, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, makePostgresSingletonLock, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };

package/dist/index.d.ts

@@ -983,6 +983,56 @@ declare class InMemoryCursorStore implements IIndexerCursorStore {
     load(): Promise<bigint | undefined>;
     save(blockNumber: bigint): Promise<void>;
 }
+/**
+ * Lock handle returned by a successful `ISingletonLock.acquire()`.
+ *
+ * The holder is the leader for the keyed indexer; non-holders MUST NOT
+ * call `indexer.start()` (else they race against the leader's polling
+ * loop and last-writer-wins cursor save corrupts replay state).
+ *
+ * `release()` is called by the leader on graceful shutdown. If the
+ * leader crashes without calling release, the lock implementation
+ * MUST drop the lock automatically (e.g. Postgres advisory locks
+ * auto-release on connection close).
+ */
+interface SingletonLockHandle {
+    release(): Promise<void>;
+}
+/**
+ * Leader-election primitive for indexer singletons.
+ *
+ * **Why this exists (audit finding H-04):** the `BurnIndexer` and
+ * `PointIndexer` classes are stateful polling loops with a cursor
+ * stored in an external store. Running them on multiple replicas
+ * simultaneously causes:
+ *
+ *   1. Double-credit — both replicas see the same Transfer event
+ *      and call `ledger.resolveCreditByBurnTx` twice.
+ *   2. Cursor rewind — last-writer-wins `save()` causes the newer
+ *      cursor to be overwritten by a lagging replica's older value,
+ *      causing the next poll to replay events.
+ *   3. Skipped blocks — chunked range reads can leave gaps when two
+ *      replicas race-advance the cursor.
+ *
+ * **Adoption:** pass `singletonLock` into `IssuerServiceConfig.indexer`
+ * (or wire it directly in your provider). The factory will only call
+ * `indexer.start()` on the indexers it successfully acquires a lock
+ * for; the rest stay idle and take over instantly on lock release.
+ *
+ * **Implementations:** `makePostgresSingletonLock(dataSource)` (recommended
+ * — uses `pg_try_advisory_lock`, auto-releases on connection close).
+ * You can also bring your own: Redis SETNX with TTL, etcd lease, etc.
+ */
+interface ISingletonLock {
+    /**
+     * Attempt to acquire the lock for `key`. Returns a handle on success
+     * (caller is the leader), or `null` if another holder owns it.
+     *
+     * Implementations MUST be non-blocking — if the lock is held, return
+     * null immediately. The factory polls / retries at a higher layer.
+     */
+    acquire(key: string): Promise<SingletonLockHandle | null>;
+}
 
 interface PointIndexerConfig {
     provider: PublicClient;
@@ -1190,7 +1240,11 @@ interface BurnIndexerConfig {
  */
 declare class BurnIndexer {
     private readonly provider;
-    private readonly pointTokenAddress;
+    /**
+     * The PointToken this indexer watches. Exposed so callers can key
+     * leader-election locks / cursor stores by token (audit H-04 fix).
+     */
+    readonly pointTokenAddress: Address;
     private readonly ledger;
     private readonly cursorStore;
     private readonly startBlock;
@@ -1222,6 +1276,60 @@ declare class BurnIndexer {
     private finalize;
 }
 
+/**
+ * Minimal duck-typed adapter so we don't drag a TypeORM / pg dep into
+ * the SDK. The caller passes anything that can execute a parameterised
+ * query and yield `{ got: boolean }` rows — TypeORM `DataSource.query`,
+ * a raw `pg` client, knex's `raw`, kysely, etc.
+ *
+ * The helper requires `int8` (signed 64-bit) lock IDs. We derive them
+ * from the lock `key` via a deterministic hash so different replicas
+ * agree on the int regardless of casing / whitespace drift.
+ */
+interface PostgresQueryRunner {
+    query(sql: string, params?: unknown[]): Promise<unknown>;
+}
+/**
+ * Build an `ISingletonLock` backed by PostgreSQL session-level advisory
+ * locks (`pg_try_advisory_lock`).
+ *
+ * Why advisory locks (vs. row-level locks or a leases table):
+ *   1. **Non-blocking** — `pg_try_advisory_lock` returns immediately;
+ *      perfect for the "try then idle" pattern the SDK uses on boot.
+ *   2. **Auto-release on connection drop** — if the leader pod crashes,
+ *      its PG connection closes, and the lock is freed automatically.
+ *      No timeout tuning, no lease renewal loops, no zombie locks.
+ *   3. **Zero schema** — no extra table, no migration, no contention
+ *      with application reads.
+ *
+ * **Caveat — long-lived connection required.** Session-level locks are
+ * held only for the lifetime of the PG connection that called
+ * `pg_try_advisory_lock`. PgBouncer in `transaction` pooling mode will
+ * release the lock between statements; you MUST run in `session`
+ * pooling or skip the bouncer for the indexer process. The advisory
+ * `transaction` variant exists but doesn't fit the "hold while polling"
+ * pattern — for that you'd need a periodic re-acquire, which we don't
+ * implement here.
+ *
+ * @example
+ *   import { DataSource } from "typeorm";
+ *   import { makePostgresSingletonLock } from "@pafi-dev/issuer";
+ *
+ *   const dataSource = new DataSource({ ... });
+ *   const lock = makePostgresSingletonLock({
+ *     query: (sql, params) => dataSource.query(sql, params),
+ *   });
+ *
+ *   createIssuerService({
+ *     ...,
+ *     indexer: {
+ *       autoStart: true,
+ *       singletonLock: lock,
+ *     },
+ *   });
+ */
+declare function makePostgresSingletonLock(runner: PostgresQueryRunner): ISingletonLock;
+
 interface ApiConfigResponse {
     chainId: number;
     contracts: {
@@ -1652,6 +1760,43 @@ declare class IssuerApiHandlers {
     private requireSupportedToken;
 }
 
+/**
+ * Resolves the EIP-712 domain `name` for a PointToken. Used by handlers
+ * (PTClaimHandler / PTRedeemHandler) that sign requests for multiple
+ * PointTokens within the same issuer backend.
+ *
+ * Resolution order per address:
+ *   1. Cache hit → return immediately (no RPC)
+ *   2. Static override map (config.overrides) → cache + return
+ *   3. On-chain `name()` lookup → cache + return
+ *
+ * Cache is per-instance — share one resolver across handlers so mint +
+ * redeem paths amortise the same set of lookups.
+ *
+ * Why the override map: production issuers often know their PTs at
+ * boot (env / DB) and want to avoid RPC quota churn + tolerate transient
+ * RPC failures. The on-chain fallback handles ad-hoc PTs not in the map
+ * (e.g. newly deployed during the process lifetime).
+ */
+interface PointTokenDomainResolverConfig {
+    provider: PublicClient;
+    /**
+     * Optional pre-configured map — checksummed (or lowercased) PointToken
+     * address → ERC-20 `name()` value. When a PT's address is in this map,
+     * the resolver short-circuits without an RPC call.
+     */
+    overrides?: Record<string, string>;
+}
+declare class PointTokenDomainResolver {
+    private readonly provider;
+    private readonly overrides;
+    private readonly cache;
+    constructor(config: PointTokenDomainResolverConfig);
+    resolve(pointTokenAddress: Address): Promise<string>;
+    /** Invalidate one address (after deploy / proxy upgrade) or all. */
+    invalidate(pointTokenAddress?: Address): void;
+}
+
 /**
  * Reverse flow — user-initiated PT redeem.
  *
@@ -1681,22 +1826,20 @@ interface PTRedeemHandlerConfig {
     ledger: IPointLedger;
     relayService: RelayService;
     provider: PublicClient;
-    /** PointToken contract address (chain-specific). */
-    pointTokenAddress: Address;
     /** BatchExecutor delegation target (chain-specific). */
     batchExecutorAddress: Address;
     /** Chain id — used for the BurnRequest EIP-712 domain. */
     chainId: number;
     /**
-     * EIP-712 domain fields. Must match the on-chain PointToken's domain
-     * separator, or on-chain signature recovery fails. `name` is
-     * typically the PointToken's ERC-20 name. `verifyingContract`
-     * defaults to `pointTokenAddress`.
+     * Resolver for the EIP-712 domain `name` (= PointToken.name() on-chain).
+     * Required because mint/redeem now route the `pointTokenAddress` per
+     * request — the handler can't bind a single domain at construction.
+     * Pass a shared resolver instance so mint + redeem amortise the same
+     * cache. The handler always uses `pointTokenAddress` as the EIP-712
+     * `verifyingContract` — no override (per-PT domain separator is
+     * isolated by contract address).
      */
-    domain: {
-        name: string;
-        verifyingContract?: Address;
-    };
+    domainResolver: PointTokenDomainResolver;
     /**
      * Issuer burner signer wallet — signs the `BurnRequest` EIP-712.
      * Must be whitelisted via `PointToken.addBurner(signerAddr)` at
@@ -1739,6 +1882,10 @@ interface PTRedeemRequest {
     authenticatedAddress: Address;
     userAddress: Address;
     amount: bigint;
+    /** PointToken contract to redeem. The handler resolves the EIP-712
+     *  domain (name + verifyingContract) from this address via the
+     *  configured `domainResolver`. */
+    pointTokenAddress: Address;
     /** ERC-4337 account nonce for the user's EOA. */
     aaNonce: bigint;
     /**
@@ -1806,10 +1953,9 @@ declare class PTRedeemHandler {
     private readonly relayService;
     private readonly provider;
     private readonly feeService?;
-    private readonly pointTokenAddress;
     private readonly batchExecutorAddress;
     private readonly chainId;
-    private readonly domain;
+    private readonly domainResolver;
     private readonly burnerSignerWallet;
     private readonly redeemLockDurationMs;
     private readonly signatureDeadlineSeconds;
@@ -2524,11 +2670,14 @@ interface PTClaimHandlerConfig {
     /** Issuer minter signer wallet — passed through to RelayService.prepareMint. */
     issuerSignerWallet: WalletClient;
     /**
-     * EIP-712 domain `name` for `MintRequest`. Typically the PointToken
-     * ERC-20 name. RelayService will set chainId + verifyingContract from
-     * the request.
+     * Resolver for the EIP-712 domain `name` (= PointToken.name() on-chain).
+     * Required because mint routes the `pointTokenAddress` per request —
+     * the handler can't bind a single domain at construction. Pass a
+     * shared resolver instance so mint + redeem amortise the same cache.
+     * `chainId` + `verifyingContract` are derived from the request's
+     * `chainId` + `pointTokenAddress` respectively.
      */
-    pointTokenDomainName: string;
+    domainResolver: PointTokenDomainResolver;
     /** Optional — when wired, used to estimate the PT gas-reimbursement fee. */
     feeService?: FeeManager;
     /** Optional — pre-validates issuer status + cap before locking balance. */
@@ -2849,8 +2998,27 @@ interface IssuerServiceConfig {
         /**
          * If `true`, the factory calls `indexer.start()` before returning.
          * Default: `false` — the caller decides when to begin polling.
+         *
+         * **SAFETY (H-04):** in a multi-replica deployment, ALWAYS pair
+         * `autoStart: true` with `singletonLock` below. Without leader
+         * election, every replica starts its own indexer fleet and races
+         * against the others — see `ISingletonLock` docs for the
+         * consequences.
          */
         autoStart?: boolean;
+        /**
+         * Leader-election primitive. When provided, the factory wraps
+         * `indexer.start()` with a `singletonLock.acquire(key)` call and
+         * only starts the indexer if it wins the lock. Non-leaders stay
+         * idle and take over on the next acquire attempt (when the leader
+         * pod's connection drops, the lock auto-releases).
+         *
+         * The lock key includes the indexer kind + the PointToken address,
+         * so different tokens can be sharded across replicas if desired.
+         *
+         * Recommended: `makePostgresSingletonLock(dataSource)`.
+         */
+        singletonLock?: ISingletonLock;
         /**
          * Override the MintFeeWrapper address used by the indexer. When
          * omitted, the factory auto-resolves from
@@ -2896,6 +3064,13 @@ interface IssuerService {
     fee: FeeManager | undefined;
     /** All indexers keyed by PointToken address. */
     indexers: Map<Address, PointIndexer>;
+    /**
+     * Lock handles for the indexers this replica was elected leader for.
+     * Empty when `autoStart` is false, or when no `singletonLock` was
+     * provided. Call `release()` on each during graceful shutdown so
+     * peers can take over without waiting for the connection to die.
+     */
+    indexerLeaderLocks: SingletonLockHandle[];
     /** Framework-agnostic HTTP handlers — wire into Express / Fastify / Hono. */
     api: IssuerApiHandlers;
     /**
@@ -2917,7 +3092,7 @@ interface IssuerService {
  *
  * Throws synchronously if any required field is missing.
  */
-declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
+declare function createIssuerService(config: IssuerServiceConfig): Promise<IssuerService>;
 
 /**
  * Adapter that absorbs every "framework-agnostic" endpoint body into a
@@ -3096,6 +3271,7 @@ declare class IssuerApiAdapter {
     redeem(input: {
         authenticatedAddress: Address;
         chainId: number;
+        pointTokenAddress: Address;
         amount: bigint;
         aaNonce: bigint;
     }): Promise<RedeemDto>;
@@ -3656,4 +3832,4 @@ declare class MemoryRedemptionHistoryStore implements IRedemptionHistoryStore {
 
 declare const PAFI_ISSUER_SDK_VERSION: string;
 
-export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, type BundlerEstimatorClient, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EstimateGasFeeOptions, type EvaluateInput, FeeManager, type FeeManagerConfig, type FeeManagerMetrics, type FetchFailureReason, type FetchImpl, type FetchResult, type GasFeeDto, type GasFeeSource, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PafiEstimatorClientConfig, PafiEstimatorHttpError, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type PreviewBurnParams, type PreviewMintParams, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createPafiEstimatorClient, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, type BundlerEstimatorClient, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EstimateGasFeeOptions, type EvaluateInput, FeeManager, type FeeManagerConfig, type FeeManagerMetrics, type FetchFailureReason, type FetchImpl, type FetchResult, type GasFeeDto, type GasFeeSource, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, type ISingletonLock, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PafiEstimatorClientConfig, PafiEstimatorHttpError, type PaymasterGasEstimates, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, PointTokenDomainResolver, type PointTokenDomainResolverConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PostgresQueryRunner, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type PreviewBurnParams, type PreviewMintParams, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SingletonLockHandle, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, applyPaymasterGasEstimates, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createPafiEstimatorClient, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, makePostgresSingletonLock, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };