@pafi-dev/issuer 0.22.1 → 0.24.1

package/dist/index.d.cts

@@ -967,12 +967,37 @@ interface BurnEvent {
  * 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.
+ *
+ * **Per-token keying (audit finding H-05).** When multiple PointTokens
+ * are wired through a single `createIssuerService` call, each
+ * `PointIndexer` MUST get its own cursor — otherwise token A advances
+ * the shared cursor past token B's events and token B's mints are
+ * never finalized (off-chain balance never deducts → on-chain PT
+ * supply for token B exceeds off-chain backing). Combined with the
+ * H-04 monotonic-save fix this becomes a catastrophic-and-stable
+ * state where token B's cursor can never catch up. Implementations
+ * SHOULD expose `forKey(key)` returning a derived store keyed under
+ * a distinct namespace; the SDK factory calls it once per token.
+ *
+ * When `forKey` is absent, the SDK falls back to the bare store and
+ * emits a runtime warning if more than one token is configured. New
+ * implementations are strongly encouraged to add `forKey`.
  */
 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>;
+    /**
+     * Return a derived store keyed under `key`. The returned store is
+     * an independent `IIndexerCursorStore` so the same persistence
+     * backend can serve N indexers with N distinct cursors.
+     *
+     * Optional for backwards compatibility, but REQUIRED in practice
+     * whenever more than one PointToken is wired through the SDK
+     * factory (see H-05).
+     */
+    forKey?(key: string): IIndexerCursorStore;
 }
 /**
  * No-op cursor store. Useful when the caller wants to drive the cursor
@@ -980,49 +1005,19 @@ interface IIndexerCursorStore {
  */
 declare class InMemoryCursorStore implements IIndexerCursorStore {
     private cursor;
+    /**
+     * Child stores keyed by `forKey()`. Each child has its own cursor
+     * (the H-05 fix), so a single InMemoryCursorStore can back N
+     * PointIndexers in tests / single-process callers.
+     */
+    private readonly children;
     load(): Promise<bigint | undefined>;
     save(blockNumber: bigint): Promise<void>;
+    forKey(key: string): IIndexerCursorStore;
 }
-/**
- * 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
@@ -1034,6 +1029,23 @@ interface ISingletonLock {
     acquire(key: string): Promise<SingletonLockHandle | null>;
 }
 
+declare class PointIndexerFinalizeError extends Error {
+    readonly context: {
+        pointToken: Address;
+        to: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+    };
+    readonly cause: unknown;
+    constructor(message: string, context: {
+        pointToken: Address;
+        to: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+    }, cause: unknown);
+}
 interface PointIndexerConfig {
     provider: PublicClient;
     pointTokenAddress: Address;
@@ -1184,6 +1196,33 @@ declare class PointIndexer {
     private finalize;
 }
 
+/**
+ * Mirror of `PointIndexerFinalizeError` — raised when
+ * `ledger.resolveCreditByBurnTx` rejects. See audit M-12: pre-fix this
+ * was silently swallowed and the cursor advanced regardless,
+ * permanently dropping confirmed on-chain burns from the off-chain
+ * credit pipeline. Post-fix the error propagates, the chunk's cursor
+ * save is skipped, and the next tick retries.
+ */
+declare class BurnIndexerFinalizeError extends Error {
+    readonly context: {
+        pointToken: Address;
+        from: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+        lockId: string;
+    };
+    readonly cause: unknown;
+    constructor(message: string, context: {
+        pointToken: Address;
+        from: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+        lockId: string;
+    }, cause: unknown);
+}
 interface BurnIndexerConfig {
     provider: PublicClient;
     pointTokenAddress: Address;
@@ -1242,7 +1281,7 @@ declare class BurnIndexer {
     private readonly provider;
     /**
      * The PointToken this indexer watches. Exposed so callers can key
-     * leader-election locks / cursor stores by token (audit H-04 fix).
+     * leader-election locks / cursor stores by token
      */
     readonly pointTokenAddress: Address;
     private readonly ledger;
@@ -3651,34 +3690,48 @@ declare function relayUserOp(params: RelayUserOpParams): Promise<{
     userOpHash: Hex;
 }>;
 
+/**
+ * Registry record returned by `IssuerRegistry.getIssuer()` in V2
+ * dual-bucket. Schema reshape from V1:
+ *
+ *   V1: { issuerAddress, signerAddress, name, symbol, active, pointToken, mintingOracle }
+ *   V2: { signerAddress, name, active, capitalBase, basisPoints }
+ *
+ * `issuerAddress` is the lookup key the caller passed; we don't
+ * re-emit it here because the caller already has it. `capitalBase` +
+ * `basisPoints` drive the EQUITY-bucket cap (`capitalBase *
+ * basisPoints / 10000`).
+ */
 interface IssuerRegistryRecord {
-    issuerAddress: Address;
     signerAddress: Address;
     name: string;
-    symbol: string;
     active: boolean;
-    pointToken: Address;
-    mintingOracle: Address;
+    capitalBase: bigint;
+    basisPoints: number;
 }
 /**
- * Per-token cap config read from `MintingOracle.tokenCaps()`. Caps
- * live per PointToken (not per issuer), so a single issuer can run
- * many PointTokens with different supply policies.
+ * Equity-bucket cap snapshot computed from the `IssuerRegistryRecord`.
+ *
+ * V1 had a separate `TokenCapRecord` sourced from
+ * `MintingOracle.tokenCaps`; in V2 the oracle is stateless and the
+ * EQUITY cap derives from the registry's `capitalBase` + `basisPoints`.
+ * Kept as a distinct shape (rather than inlining into
+ * `PreValidateMintResult`) so admin tooling can read it without
+ * re-deriving the multiplication.
  */
-interface TokenCapRecord {
-    declaredTotalSupply: bigint;
-    capBasisPoints: number;
+interface EquityCapRecord {
+    capitalBase: bigint;
+    basisPoints: number;
+    hardCap: bigint;
 }
 interface PreValidateMintResult {
     /** Registry record read at pre-validation time. */
     issuer: IssuerRegistryRecord;
-    /** Per-token cap config from MintingOracle. */
-    tokenCap: TokenCapRecord;
-    /** Current on-chain PointToken.totalSupply(). */
-    totalSupply: bigint;
-    /** declaredTotalSupply × capBasisPoints / 10000. */
-    hardCap: bigint;
-    /** hardCap − totalSupply (clamped to 0). */
+    /** Equity-bucket cap derived from issuer.capitalBase × basisPoints. */
+    equityCap: EquityCapRecord;
+    /** Current on-chain `PointToken.equitySupply()`. */
+    equitySupply: bigint;
+    /** equityCap.hardCap − equitySupply (clamped to 0). */
     remaining: bigint;
 }
 /**
@@ -3832,4 +3885,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, 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 };
+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, BurnIndexerFinalizeError, 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, PointIndexerFinalizeError, 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

@@ -967,12 +967,37 @@ interface BurnEvent {
  * 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.
+ *
+ * **Per-token keying (audit finding H-05).** When multiple PointTokens
+ * are wired through a single `createIssuerService` call, each
+ * `PointIndexer` MUST get its own cursor — otherwise token A advances
+ * the shared cursor past token B's events and token B's mints are
+ * never finalized (off-chain balance never deducts → on-chain PT
+ * supply for token B exceeds off-chain backing). Combined with the
+ * H-04 monotonic-save fix this becomes a catastrophic-and-stable
+ * state where token B's cursor can never catch up. Implementations
+ * SHOULD expose `forKey(key)` returning a derived store keyed under
+ * a distinct namespace; the SDK factory calls it once per token.
+ *
+ * When `forKey` is absent, the SDK falls back to the bare store and
+ * emits a runtime warning if more than one token is configured. New
+ * implementations are strongly encouraged to add `forKey`.
  */
 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>;
+    /**
+     * Return a derived store keyed under `key`. The returned store is
+     * an independent `IIndexerCursorStore` so the same persistence
+     * backend can serve N indexers with N distinct cursors.
+     *
+     * Optional for backwards compatibility, but REQUIRED in practice
+     * whenever more than one PointToken is wired through the SDK
+     * factory (see H-05).
+     */
+    forKey?(key: string): IIndexerCursorStore;
 }
 /**
  * No-op cursor store. Useful when the caller wants to drive the cursor
@@ -980,49 +1005,19 @@ interface IIndexerCursorStore {
  */
 declare class InMemoryCursorStore implements IIndexerCursorStore {
     private cursor;
+    /**
+     * Child stores keyed by `forKey()`. Each child has its own cursor
+     * (the H-05 fix), so a single InMemoryCursorStore can back N
+     * PointIndexers in tests / single-process callers.
+     */
+    private readonly children;
     load(): Promise<bigint | undefined>;
     save(blockNumber: bigint): Promise<void>;
+    forKey(key: string): IIndexerCursorStore;
 }
-/**
- * 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
@@ -1034,6 +1029,23 @@ interface ISingletonLock {
     acquire(key: string): Promise<SingletonLockHandle | null>;
 }
 
+declare class PointIndexerFinalizeError extends Error {
+    readonly context: {
+        pointToken: Address;
+        to: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+    };
+    readonly cause: unknown;
+    constructor(message: string, context: {
+        pointToken: Address;
+        to: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+    }, cause: unknown);
+}
 interface PointIndexerConfig {
     provider: PublicClient;
     pointTokenAddress: Address;
@@ -1184,6 +1196,33 @@ declare class PointIndexer {
     private finalize;
 }
 
+/**
+ * Mirror of `PointIndexerFinalizeError` — raised when
+ * `ledger.resolveCreditByBurnTx` rejects. See audit M-12: pre-fix this
+ * was silently swallowed and the cursor advanced regardless,
+ * permanently dropping confirmed on-chain burns from the off-chain
+ * credit pipeline. Post-fix the error propagates, the chunk's cursor
+ * save is skipped, and the next tick retries.
+ */
+declare class BurnIndexerFinalizeError extends Error {
+    readonly context: {
+        pointToken: Address;
+        from: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+        lockId: string;
+    };
+    readonly cause: unknown;
+    constructor(message: string, context: {
+        pointToken: Address;
+        from: Address;
+        amount: bigint;
+        txHash: `0x${string}`;
+        blockNumber: bigint;
+        lockId: string;
+    }, cause: unknown);
+}
 interface BurnIndexerConfig {
     provider: PublicClient;
     pointTokenAddress: Address;
@@ -1242,7 +1281,7 @@ declare class BurnIndexer {
     private readonly provider;
     /**
      * The PointToken this indexer watches. Exposed so callers can key
-     * leader-election locks / cursor stores by token (audit H-04 fix).
+     * leader-election locks / cursor stores by token
      */
     readonly pointTokenAddress: Address;
     private readonly ledger;
@@ -3651,34 +3690,48 @@ declare function relayUserOp(params: RelayUserOpParams): Promise<{
     userOpHash: Hex;
 }>;
 
+/**
+ * Registry record returned by `IssuerRegistry.getIssuer()` in V2
+ * dual-bucket. Schema reshape from V1:
+ *
+ *   V1: { issuerAddress, signerAddress, name, symbol, active, pointToken, mintingOracle }
+ *   V2: { signerAddress, name, active, capitalBase, basisPoints }
+ *
+ * `issuerAddress` is the lookup key the caller passed; we don't
+ * re-emit it here because the caller already has it. `capitalBase` +
+ * `basisPoints` drive the EQUITY-bucket cap (`capitalBase *
+ * basisPoints / 10000`).
+ */
 interface IssuerRegistryRecord {
-    issuerAddress: Address;
     signerAddress: Address;
     name: string;
-    symbol: string;
     active: boolean;
-    pointToken: Address;
-    mintingOracle: Address;
+    capitalBase: bigint;
+    basisPoints: number;
 }
 /**
- * Per-token cap config read from `MintingOracle.tokenCaps()`. Caps
- * live per PointToken (not per issuer), so a single issuer can run
- * many PointTokens with different supply policies.
+ * Equity-bucket cap snapshot computed from the `IssuerRegistryRecord`.
+ *
+ * V1 had a separate `TokenCapRecord` sourced from
+ * `MintingOracle.tokenCaps`; in V2 the oracle is stateless and the
+ * EQUITY cap derives from the registry's `capitalBase` + `basisPoints`.
+ * Kept as a distinct shape (rather than inlining into
+ * `PreValidateMintResult`) so admin tooling can read it without
+ * re-deriving the multiplication.
  */
-interface TokenCapRecord {
-    declaredTotalSupply: bigint;
-    capBasisPoints: number;
+interface EquityCapRecord {
+    capitalBase: bigint;
+    basisPoints: number;
+    hardCap: bigint;
 }
 interface PreValidateMintResult {
     /** Registry record read at pre-validation time. */
     issuer: IssuerRegistryRecord;
-    /** Per-token cap config from MintingOracle. */
-    tokenCap: TokenCapRecord;
-    /** Current on-chain PointToken.totalSupply(). */
-    totalSupply: bigint;
-    /** declaredTotalSupply × capBasisPoints / 10000. */
-    hardCap: bigint;
-    /** hardCap − totalSupply (clamped to 0). */
+    /** Equity-bucket cap derived from issuer.capitalBase × basisPoints. */
+    equityCap: EquityCapRecord;
+    /** Current on-chain `PointToken.equitySupply()`. */
+    equitySupply: bigint;
+    /** equityCap.hardCap − equitySupply (clamped to 0). */
     remaining: bigint;
 }
 /**
@@ -3832,4 +3885,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, 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 };
+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, BurnIndexerFinalizeError, 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, PointIndexerFinalizeError, 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 };