@pafi-dev/issuer 0.22.0 → 0.23.0

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
@@ -1242,7 +1237,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;

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
@@ -1242,7 +1237,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;

package/dist/index.js

@@ -1122,14 +1122,28 @@ function createPafiEstimatorClient(config) {
 }
 
 // src/indexer/types.ts
-var InMemoryCursorStore = class {
+var InMemoryCursorStore = class _InMemoryCursorStore {
   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.
+   */
+  children = /* @__PURE__ */ new Map();
   async load() {
     return this.cursor;
   }
   async save(blockNumber) {
     this.cursor = blockNumber;
   }
+  forKey(key) {
+    let child = this.children.get(key);
+    if (!child) {
+      child = new _InMemoryCursorStore();
+      this.children.set(key, child);
+    }
+    return child;
+  }
 };
 
 // src/indexer/pointIndexer.ts
@@ -1393,7 +1407,7 @@ 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).
+   * leader-election locks / cursor stores by token
    */
   pointTokenAddress;
   ledger;
@@ -4567,6 +4581,13 @@ async function createIssuerService(config) {
   const sdkWrapperAddress = getContractAddresses7(config.chainId).mintFeeWrapper;
   const wrapperOverride = config.indexer?.mintFeeWrapperAddress;
   const resolvedWrapperAddress = wrapperOverride !== void 0 ? wrapperOverride : sdkWrapperAddress;
+  const baseCursorStore = config.indexer?.cursorStore;
+  const sharedCursorWithMultipleTokens = baseCursorStore !== void 0 && typeof baseCursorStore.forKey !== "function" && tokenAddresses.length > 1;
+  if (sharedCursorWithMultipleTokens) {
+    console.warn(
+      `[@pafi-dev/issuer] cursorStore lacks forKey() and ${tokenAddresses.length} PointTokens are configured. All PointIndexers will share one cursor row, causing token-skipping (audit finding H-05). Implement IIndexerCursorStore.forKey to return per-token derived stores. This permissive path will be removed in a future major release.`
+    );
+  }
   const indexers = /* @__PURE__ */ new Map();
   for (const tokenAddress of tokenAddresses) {
     const indexerConfig = {
@@ -4580,8 +4601,10 @@ async function createIssuerService(config) {
     if (config.indexer?.fromBlock !== void 0) {
       indexerConfig.fromBlock = config.indexer.fromBlock;
     }
-    if (config.indexer?.cursorStore) {
-      indexerConfig.cursorStore = config.indexer.cursorStore;
+    if (baseCursorStore) {
+      indexerConfig.cursorStore = typeof baseCursorStore.forKey === "function" ? baseCursorStore.forKey(
+        `point-indexer:${tokenAddress.toLowerCase()}`
+      ) : baseCursorStore;
     }
     if (config.indexer?.confirmations !== void 0) {
       indexerConfig.confirmations = config.indexer.confirmations;
@@ -4882,7 +4905,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.22.0" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.23.0" : "dev";
 export {
   AdapterMisconfiguredError,
   AuthError,