@pafi-dev/issuer 0.21.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: {
@@ -2890,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
@@ -2937,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;
     /**
@@ -2958,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
@@ -3698,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, PointTokenDomainResolver, type PointTokenDomainResolverConfig, 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: {
@@ -2890,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
@@ -2937,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;
     /**
@@ -2958,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
@@ -3698,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, PointTokenDomainResolver, type PointTokenDomainResolverConfig, 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.js

@@ -1391,6 +1391,10 @@ var DEFAULT_BATCH_SIZE2 = 2000n;
 var DEFAULT_POLL_INTERVAL_MS2 = 5e3;
 var BurnIndexer = class {
   provider;
+  /**
+   * The PointToken this indexer watches. Exposed so callers can key
+   * leader-election locks / cursor stores by token (audit H-04 fix).
+   */
   pointTokenAddress;
   ledger;
   cursorStore;
@@ -1550,6 +1554,45 @@ var BurnIndexer = class {
   }
 };
 
+// src/indexer/postgresSingletonLock.ts
+function makePostgresSingletonLock(runner) {
+  return {
+    async acquire(key) {
+      const lockId = hashKeyToInt64(key);
+      const rows = await runner.query(
+        "SELECT pg_try_advisory_lock($1::bigint) AS got",
+        [lockId]
+      );
+      const got = rows[0]?.got === true;
+      if (!got) return null;
+      return {
+        async release() {
+          try {
+            await runner.query("SELECT pg_advisory_unlock($1::bigint)", [
+              lockId
+            ]);
+          } catch {
+          }
+        }
+      };
+    }
+  };
+}
+function hashKeyToInt64(key) {
+  const FNV_OFFSET = 0xcbf29ce484222325n;
+  const FNV_PRIME = 0x100000001b3n;
+  const MASK_64 = (1n << 64n) - 1n;
+  let hash = FNV_OFFSET;
+  for (let i = 0; i < key.length; i++) {
+    hash ^= BigInt(key.charCodeAt(i));
+    hash = hash * FNV_PRIME & MASK_64;
+  }
+  const SIGNED_MAX = (1n << 63n) - 1n;
+  const TWO64 = 1n << 64n;
+  const signed = hash > SIGNED_MAX ? hash - TWO64 : hash;
+  return signed.toString();
+}
+
 // src/api/handlers.ts
 import { getAddress as getAddress5 } from "viem";
 import {
@@ -2861,8 +2904,16 @@ var PTClaimHandler = class {
           domain,
           mintRequestNonce: request.mintRequestNonce,
           deadline: signatureDeadline,
-          mintFeeWrapperAddress: resolvedWrapper
-          // No feeAmount/feeRecipient — RelayService auto-resolves.
+          mintFeeWrapperAddress: resolvedWrapper,
+          // Pass the bundler-estimated `feeAmount` explicitly so the
+          // RelayService skips its legacy `quoteOperatorFeePt` path
+          // (which uses the SDK's old 12_000 bps premium default).
+          // Without this, the response's `feeAmount` (from FeeManager,
+          // 100% premium on top of PAFI's 110% server-side estimate)
+          // would diverge from the actual PT.transfer amount in the
+          // UserOp batch (`quoteOperatorFeePt`'s 120%), and the user
+          // would see one value while the wallet transferred another.
+          feeAmount
         });
       } catch (err) {
         throw new PTClaimError(
@@ -4469,7 +4520,7 @@ var RedemptionService = class {
 };
 
 // src/config.ts
-function createIssuerService(config) {
+async function createIssuerService(config) {
   if (!config.provider) {
     throw new Error("createIssuerService: provider is required");
   }
@@ -4588,9 +4639,26 @@ function createIssuerService(config) {
     handlersConfig.mintFeeWrapperAddress = resolvedWrapperAddress;
   }
   const handlers = new IssuerApiHandlers(handlersConfig);
+  const indexerLeaderLocks = [];
   if (config.indexer?.autoStart) {
-    for (const idx of indexers.values()) {
-      idx.start();
+    const lock = config.indexer.singletonLock;
+    if (!lock) {
+      console.warn(
+        "[@pafi-dev/issuer] indexer.autoStart=true without singletonLock \u2014 this is UNSAFE in multi-replica deployments (audit finding H-04). Either set replicas=1 + INDEXER_AUTOSTART=false on non-leader pods, or pass `singletonLock: makePostgresSingletonLock(dataSource)`. This permissive path will be removed in a future major release."
+      );
+      for (const idx of indexers.values()) {
+        idx.start();
+      }
+    } else {
+      for (const [tokenAddr, idx] of indexers.entries()) {
+        const key = `pafi-issuer:point-indexer:${tokenAddr.toLowerCase()}`;
+        const handle = await lock.acquire(key);
+        if (!handle) {
+          continue;
+        }
+        idx.start();
+        indexerLeaderLocks.push(handle);
+      }
     }
   }
   return {
@@ -4601,6 +4669,7 @@ function createIssuerService(config) {
     relay: relayService,
     fee: feeManager,
     indexers,
+    indexerLeaderLocks,
     api: handlers,
     redemption
   };
@@ -4813,7 +4882,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.21.0" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.22.0" : "dev";
 export {
   AdapterMisconfiguredError,
   AuthError,
@@ -4879,6 +4948,7 @@ export {
   handleMobilePrepare,
   handleMobileSubmit,
   handleRedeemStatus,
+  makePostgresSingletonLock,
   mergePaymasterFields,
   payloadFromGenericError,
   payloadFromHttpException,