@pafi-dev/issuer-postgres 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import { DataSource } from 'typeorm';
 import { Address, Hex } from 'viem';
-import { IPointLedger, LockedMintRequest, PendingCredit, MintingStatus, IIndexerCursorStore } from '@pafi-dev/issuer';
+import { IPointLedger, LockedMintRequest, PendingCredit, MintingStatus, IIndexerCursorStore, IRedemptionHistoryStore } from '@pafi-dev/issuer';
 import { LockedMintEntity, PendingCreditEntity } from './entities/index.cjs';
-export { IndexerCursorEntity, LedgerJournalEntity, PAFI_ENTITIES, PendingCreditStatus, UserBalanceEntity } from './entities/index.cjs';
-export { InitialSchema1700000000000, PAFI_MIGRATIONS } from './migrations/index.cjs';
+export { IndexerCursorEntity, LedgerJournalEntity, PAFI_ENTITIES, PendingCreditStatus, RedemptionHistoryEntity, UserBalanceEntity } from './entities/index.cjs';
+export { CreateRedemptionHistory1746230400001, InitialSchema1700000000000, PAFI_MIGRATIONS } from './migrations/index.cjs';
 
 interface PostgresPointLedgerOptions {
     /**
@@ -38,6 +38,32 @@ declare class PostgresPointLedger implements IPointLedger {
     private readonly logger;
     constructor(dataSource: DataSource, options?: PostgresPointLedgerOptions);
     getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
+    /**
+     * Background sweep — marks all expired PENDING locks as EXPIRED in
+     * a single UPDATE. Issuers SHOULD call this periodically (e.g.
+     * every 1-5 minutes via a cron / NestJS `@Interval`) to keep the
+     * lock table from growing unbounded.
+     *
+     * A single sweep amortizes the write cost vs `getBalance` doing a
+     * wide UPDATE on every read. Returns the number of rows transitioned.
+     *
+     * @example
+     * ```ts
+     * import { Interval } from "@nestjs/schedule";
+     *
+     * @Injectable()
+     * export class LockSweepService {
+     *   constructor(private readonly ledger: PostgresPointLedger) {}
+     *
+     *   @Interval(5 * 60 * 1000) // 5 minutes
+     *   async sweep() {
+     *     const swept = await this.ledger.markExpiredLocks();
+     *     this.logger.debug(`expired ${swept} mint locks`);
+     *   }
+     * }
+     * ```
+     */
+    markExpiredLocks(): Promise<number>;
     getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
     getMintLock(lockId: string, userAddress?: Address): Promise<LockedMintRequest | null>;
     /** Raw TypeORM row — escape hatch for callers that need entity fields. */
@@ -94,4 +120,27 @@ declare class PostgresCursorStore implements IIndexerCursorStore {
     forKey(cursorId: string): IIndexerCursorStore;
 }
 
-export { LockedMintEntity, PendingCreditEntity, PostgresCursorStore, PostgresPointLedger, type PostgresPointLedgerOptions };
+/**
+ * Postgres-backed IRedemptionHistoryStore. Append-only — every
+ * `recordRedemption` writes a new row. Reads (`sumRedeemedSince` /
+ * `getLastRedeemedAtUnixSec`) hit the (user, time) composite index.
+ *
+ * Addresses are normalized to checksum form on write and lower-cased
+ * on read so the index works regardless of casing inconsistency. The
+ * entity stores the canonical (checksummed) form.
+ */
+declare class PostgresRedemptionHistoryStore implements IRedemptionHistoryStore {
+    private readonly dataSource;
+    constructor(dataSource: DataSource);
+    sumRedeemedSince(user: Address, sinceUnixSec: number, pointTokenAddress?: Address): Promise<bigint>;
+    getLastRedeemedAtUnixSec(user: Address, pointTokenAddress?: Address): Promise<number | null>;
+    recordRedemption(entry: {
+        user: Address;
+        amountPt: bigint;
+        pointTokenAddress?: Address;
+        unixSec: number;
+        reservationId?: string;
+    }): Promise<void>;
+}
+
+export { LockedMintEntity, PendingCreditEntity, PostgresCursorStore, PostgresPointLedger, type PostgresPointLedgerOptions, PostgresRedemptionHistoryStore };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { DataSource } from 'typeorm';
 import { Address, Hex } from 'viem';
-import { IPointLedger, LockedMintRequest, PendingCredit, MintingStatus, IIndexerCursorStore } from '@pafi-dev/issuer';
+import { IPointLedger, LockedMintRequest, PendingCredit, MintingStatus, IIndexerCursorStore, IRedemptionHistoryStore } from '@pafi-dev/issuer';
 import { LockedMintEntity, PendingCreditEntity } from './entities/index.js';
-export { IndexerCursorEntity, LedgerJournalEntity, PAFI_ENTITIES, PendingCreditStatus, UserBalanceEntity } from './entities/index.js';
-export { InitialSchema1700000000000, PAFI_MIGRATIONS } from './migrations/index.js';
+export { IndexerCursorEntity, LedgerJournalEntity, PAFI_ENTITIES, PendingCreditStatus, RedemptionHistoryEntity, UserBalanceEntity } from './entities/index.js';
+export { CreateRedemptionHistory1746230400001, InitialSchema1700000000000, PAFI_MIGRATIONS } from './migrations/index.js';
 
 interface PostgresPointLedgerOptions {
     /**
@@ -38,6 +38,32 @@ declare class PostgresPointLedger implements IPointLedger {
     private readonly logger;
     constructor(dataSource: DataSource, options?: PostgresPointLedgerOptions);
     getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
+    /**
+     * Background sweep — marks all expired PENDING locks as EXPIRED in
+     * a single UPDATE. Issuers SHOULD call this periodically (e.g.
+     * every 1-5 minutes via a cron / NestJS `@Interval`) to keep the
+     * lock table from growing unbounded.
+     *
+     * A single sweep amortizes the write cost vs `getBalance` doing a
+     * wide UPDATE on every read. Returns the number of rows transitioned.
+     *
+     * @example
+     * ```ts
+     * import { Interval } from "@nestjs/schedule";
+     *
+     * @Injectable()
+     * export class LockSweepService {
+     *   constructor(private readonly ledger: PostgresPointLedger) {}
+     *
+     *   @Interval(5 * 60 * 1000) // 5 minutes
+     *   async sweep() {
+     *     const swept = await this.ledger.markExpiredLocks();
+     *     this.logger.debug(`expired ${swept} mint locks`);
+     *   }
+     * }
+     * ```
+     */
+    markExpiredLocks(): Promise<number>;
     getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
     getMintLock(lockId: string, userAddress?: Address): Promise<LockedMintRequest | null>;
     /** Raw TypeORM row — escape hatch for callers that need entity fields. */
@@ -94,4 +120,27 @@ declare class PostgresCursorStore implements IIndexerCursorStore {
     forKey(cursorId: string): IIndexerCursorStore;
 }
 
-export { LockedMintEntity, PendingCreditEntity, PostgresCursorStore, PostgresPointLedger, type PostgresPointLedgerOptions };
+/**
+ * Postgres-backed IRedemptionHistoryStore. Append-only — every
+ * `recordRedemption` writes a new row. Reads (`sumRedeemedSince` /
+ * `getLastRedeemedAtUnixSec`) hit the (user, time) composite index.
+ *
+ * Addresses are normalized to checksum form on write and lower-cased
+ * on read so the index works regardless of casing inconsistency. The
+ * entity stores the canonical (checksummed) form.
+ */
+declare class PostgresRedemptionHistoryStore implements IRedemptionHistoryStore {
+    private readonly dataSource;
+    constructor(dataSource: DataSource);
+    sumRedeemedSince(user: Address, sinceUnixSec: number, pointTokenAddress?: Address): Promise<bigint>;
+    getLastRedeemedAtUnixSec(user: Address, pointTokenAddress?: Address): Promise<number | null>;
+    recordRedemption(entry: {
+        user: Address;
+        amountPt: bigint;
+        pointTokenAddress?: Address;
+        unixSec: number;
+        reservationId?: string;
+    }): Promise<void>;
+}
+
+export { LockedMintEntity, PendingCreditEntity, PostgresCursorStore, PostgresPointLedger, type PostgresPointLedgerOptions, PostgresRedemptionHistoryStore };

package/dist/index.js

@@ -248,6 +248,34 @@ LedgerJournalEntity = __decorateClass([
 ], LedgerJournalEntity);
 
 // src/postgresPointLedger.ts
+var RETRIABLE_PG_CODES = /* @__PURE__ */ new Set(["40P01", "40001"]);
+function isRetriablePgError(err) {
+  const e = err;
+  if (!e) return false;
+  if (e.code && RETRIABLE_PG_CODES.has(e.code)) return true;
+  if (e.message && /deadlock detected|could not serialize/i.test(e.message)) {
+    return true;
+  }
+  return false;
+}
+async function withDeadlockRetry(dataSource, fn, maxAttempts = 3) {
+  let attempt = 0;
+  let delayMs = 25;
+  for (; ; ) {
+    attempt++;
+    try {
+      return await dataSource.transaction(fn);
+    } catch (err) {
+      if (attempt >= maxAttempts || !isRetriablePgError(err)) {
+        throw err;
+      }
+      await new Promise(
+        (r) => setTimeout(r, delayMs + Math.floor(Math.random() * delayMs))
+      );
+      delayMs *= 2;
+    }
+  }
+}
 var PostgresPointLedger = class {
   constructor(dataSource, options = {}) {
     this.dataSource = dataSource;
@@ -260,13 +288,47 @@ var PostgresPointLedger = class {
   // ---------------------------------------------------------------------
   async getBalance(userAddress, tokenAddress) {
     const { user, token } = normalize(userAddress, tokenAddress);
-    await this.dataSource.getRepository(LockedMintEntity).createQueryBuilder().update().set({ status: "EXPIRED" }).where("status = :pending", { pending: "PENDING" }).andWhere("expires_at <= :now", { now: /* @__PURE__ */ new Date() }).execute();
-    const balanceRow = await this.dataSource.getRepository(UserBalanceEntity).findOne({ where: { userAddress: user, tokenAddress: token } });
+    const [balanceRow, locked] = await Promise.all([
+      this.dataSource.getRepository(UserBalanceEntity).findOne({ where: { userAddress: user, tokenAddress: token } }),
+      this.sumPendingLocks(user, token)
+    ]);
     const total = balanceRow?.balance ?? 0n;
-    const locked = await this.sumPendingLocks(user, token);
     const available = total - locked;
     return available < 0n ? 0n : available;
   }
+  /**
+   * Background sweep — marks all expired PENDING locks as EXPIRED in
+   * a single UPDATE. Issuers SHOULD call this periodically (e.g.
+   * every 1-5 minutes via a cron / NestJS `@Interval`) to keep the
+   * lock table from growing unbounded.
+   *
+   * A single sweep amortizes the write cost vs `getBalance` doing a
+   * wide UPDATE on every read. Returns the number of rows transitioned.
+   *
+   * @example
+   * ```ts
+   * import { Interval } from "@nestjs/schedule";
+   *
+   * @Injectable()
+   * export class LockSweepService {
+   *   constructor(private readonly ledger: PostgresPointLedger) {}
+   *
+   *   @Interval(5 * 60 * 1000) // 5 minutes
+   *   async sweep() {
+   *     const swept = await this.ledger.markExpiredLocks();
+   *     this.logger.debug(`expired ${swept} mint locks`);
+   *   }
+   * }
+   * ```
+   */
+  async markExpiredLocks() {
+    const result = await this.dataSource.getRepository(LockedMintEntity).createQueryBuilder().update().set({ status: "EXPIRED" }).where("status = :pending", { pending: "PENDING" }).andWhere("expires_at <= :now", { now: /* @__PURE__ */ new Date() }).execute();
+    const swept = result.affected ?? 0;
+    if (swept > 0) {
+      this.logger?.debug?.(`markExpiredLocks: swept ${swept} mint locks`);
+    }
+    return swept;
+  }
   async getLockedRequests(userAddress, tokenAddress) {
     const { user, token } = normalize(userAddress, tokenAddress);
     const rows = await this.dataSource.getRepository(LockedMintEntity).find({
@@ -332,8 +394,8 @@ var PostgresPointLedger = class {
       throw new Error("creditBalance: amount must be positive");
     }
     const { user, token } = normalize(userAddress, tokenAddress);
-    await this.dataSource.transaction(async (tx) => {
-      const existing = await tx.getRepository(UserBalanceEntity).findOne({ where: { userAddress: user, tokenAddress: token } });
+    await withDeadlockRetry(this.dataSource, async (tx) => {
+      const existing = await tx.getRepository(UserBalanceEntity).createQueryBuilder("balance").setLock("pessimistic_write").where("balance.user_address = :user", { user }).andWhere("balance.token_address = :token", { token }).getOne();
       const next = (existing?.balance ?? 0n) + amount;
       await tx.getRepository(UserBalanceEntity).upsert(
         { userAddress: user, tokenAddress: token, balance: next },
@@ -356,8 +418,8 @@ var PostgresPointLedger = class {
       throw new Error("lockForMinting: lockDurationMs must be positive");
     }
     const { user, token } = normalize(userAddress, tokenAddress);
-    return this.dataSource.transaction(async (tx) => {
-      const balanceRow = await tx.getRepository(UserBalanceEntity).findOne({ where: { userAddress: user, tokenAddress: token } });
+    return withDeadlockRetry(this.dataSource, async (tx) => {
+      const balanceRow = await tx.getRepository(UserBalanceEntity).createQueryBuilder("balance").setLock("pessimistic_write").where("balance.user_address = :user", { user }).andWhere("balance.token_address = :token", { token }).getOne();
       const total = balanceRow?.balance ?? 0n;
       const pendingTotal = await tx.getRepository(LockedMintEntity).createQueryBuilder("lock").select("COALESCE(SUM(CAST(lock.amount AS NUMERIC)), 0)", "sum").where("lock.user_address = :user", { user }).andWhere("lock.token_address = :token", { token }).andWhere("lock.status = :pending", { pending: "PENDING" }).andWhere("lock.expires_at > :now", { now: /* @__PURE__ */ new Date() }).getRawOne();
       const locked = pendingTotal ? BigInt(pendingTotal.sum) : 0n;
@@ -391,8 +453,8 @@ var PostgresPointLedger = class {
       throw new Error("deductBalance: amount must be positive");
     }
     const { user, token } = normalize(userAddress, tokenAddress);
-    await this.dataSource.transaction(async (tx) => {
-      const balance = await tx.getRepository(UserBalanceEntity).findOne({ where: { userAddress: user, tokenAddress: token } });
+    await withDeadlockRetry(this.dataSource, async (tx) => {
+      const balance = await tx.getRepository(UserBalanceEntity).createQueryBuilder("balance").setLock("pessimistic_write").where("balance.user_address = :user", { user }).andWhere("balance.token_address = :token", { token }).getOne();
       if (!balance || balance.balance < amount) {
         throw new Error(
           `Cannot deduct ${amount} from balance ${balance?.balance ?? 0n}`
@@ -459,8 +521,8 @@ var PostgresPointLedger = class {
     return row.id;
   }
   async resolveCreditByBurnTx(lockId, txHash) {
-    await this.dataSource.transaction(async (tx) => {
-      const credit = await tx.getRepository(PendingCreditEntity).findOne({ where: { id: lockId } });
+    await withDeadlockRetry(this.dataSource, async (tx) => {
+      const credit = await tx.getRepository(PendingCreditEntity).createQueryBuilder("credit").setLock("pessimistic_write").where("credit.id = :id", { id: lockId }).getOne();
       if (!credit) {
         throw new Error(
           `resolveCreditByBurnTx: unknown pending credit ${lockId}`
@@ -494,7 +556,7 @@ var PostgresPointLedger = class {
         );
         return;
       }
-      const balance = await tx.getRepository(UserBalanceEntity).findOne({ where: { userAddress: user, tokenAddress: token } });
+      const balance = await tx.getRepository(UserBalanceEntity).createQueryBuilder("balance").setLock("pessimistic_write").where("balance.user_address = :user", { user }).andWhere("balance.token_address = :token", { token }).getOne();
       const next = (balance?.balance ?? 0n) + credit.amount;
       await tx.getRepository(UserBalanceEntity).upsert(
         { userAddress: user, tokenAddress: token, balance: next },
@@ -620,13 +682,120 @@ var PostgresCursorStore = class _PostgresCursorStore {
   }
 };
 
+// src/postgresRedemptionHistoryStore.ts
+import { getAddress as getAddress2 } from "viem";
+
+// src/entities/redemption-history.entity.ts
+import {
+  Column as Column6,
+  CreateDateColumn as CreateDateColumn4,
+  Entity as Entity6,
+  Index as Index4,
+  PrimaryGeneratedColumn as PrimaryGeneratedColumn4
+} from "typeorm";
+var RedemptionHistoryEntity = class {
+  id;
+  userAddress;
+  tokenAddress;
+  amountPt;
+  createdAtUnixSec;
+  reservationId;
+  rowCreatedAt;
+};
+__decorateClass([
+  PrimaryGeneratedColumn4("uuid")
+], RedemptionHistoryEntity.prototype, "id", 2);
+__decorateClass([
+  Column6({ name: "user_address", type: "varchar", length: 42 })
+], RedemptionHistoryEntity.prototype, "userAddress", 2);
+__decorateClass([
+  Column6({ name: "token_address", type: "varchar", length: 42, nullable: true })
+], RedemptionHistoryEntity.prototype, "tokenAddress", 2);
+__decorateClass([
+  Column6({
+    name: "amount_pt",
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    transformer: {
+      to: (value) => value.toString(),
+      from: (value) => BigInt(value)
+    }
+  })
+], RedemptionHistoryEntity.prototype, "amountPt", 2);
+__decorateClass([
+  Column6({ name: "created_at_unix_sec", type: "bigint" })
+], RedemptionHistoryEntity.prototype, "createdAtUnixSec", 2);
+__decorateClass([
+  Column6({
+    name: "reservation_id",
+    type: "varchar",
+    length: 64,
+    nullable: true
+  })
+], RedemptionHistoryEntity.prototype, "reservationId", 2);
+__decorateClass([
+  CreateDateColumn4({ name: "row_created_at", type: "timestamptz" })
+], RedemptionHistoryEntity.prototype, "rowCreatedAt", 2);
+RedemptionHistoryEntity = __decorateClass([
+  Entity6({ name: "redemption_history" }),
+  Index4("idx_redemption_history_user_created", [
+    "userAddress",
+    "createdAtUnixSec"
+  ])
+], RedemptionHistoryEntity);
+
+// src/postgresRedemptionHistoryStore.ts
+var PostgresRedemptionHistoryStore = class {
+  constructor(dataSource) {
+    this.dataSource = dataSource;
+  }
+  dataSource;
+  async sumRedeemedSince(user, sinceUnixSec, pointTokenAddress) {
+    const repo = this.dataSource.getRepository(RedemptionHistoryEntity);
+    const qb = repo.createQueryBuilder("rh").select("COALESCE(SUM(rh.amount_pt), 0)", "sum").where("rh.user_address = :user", { user: getAddress2(user) }).andWhere("rh.created_at_unix_sec >= :since", { since: sinceUnixSec });
+    if (pointTokenAddress !== void 0) {
+      qb.andWhere("rh.token_address = :token", {
+        token: getAddress2(pointTokenAddress)
+      });
+    } else {
+    }
+    const row = await qb.getRawOne() ?? { sum: "0" };
+    return BigInt(row.sum ?? "0");
+  }
+  async getLastRedeemedAtUnixSec(user, pointTokenAddress) {
+    const repo = this.dataSource.getRepository(RedemptionHistoryEntity);
+    const qb = repo.createQueryBuilder("rh").select("rh.created_at_unix_sec", "ts").where("rh.user_address = :user", { user: getAddress2(user) }).orderBy("rh.created_at_unix_sec", "DESC").limit(1);
+    if (pointTokenAddress !== void 0) {
+      qb.andWhere("rh.token_address = :token", {
+        token: getAddress2(pointTokenAddress)
+      });
+    }
+    const row = await qb.getRawOne();
+    if (!row || row.ts === null) return null;
+    return Number(row.ts);
+  }
+  async recordRedemption(entry) {
+    const repo = this.dataSource.getRepository(RedemptionHistoryEntity);
+    const row = repo.create({
+      userAddress: getAddress2(entry.user),
+      tokenAddress: entry.pointTokenAddress ? getAddress2(entry.pointTokenAddress) : null,
+      amountPt: entry.amountPt,
+      createdAtUnixSec: String(entry.unixSec),
+      reservationId: entry.reservationId ?? null
+    });
+    await repo.save(row);
+  }
+};
+
 // src/entities/index.ts
 var PAFI_ENTITIES = [
   LockedMintEntity,
   PendingCreditEntity,
   UserBalanceEntity,
   LedgerJournalEntity,
-  IndexerCursorEntity
+  IndexerCursorEntity,
+  RedemptionHistoryEntity
 ];
 
 // src/migrations/1700000000000-InitialSchema.ts
@@ -732,9 +901,42 @@ var InitialSchema1700000000000 = class {
   }
 };
 
+// src/migrations/1746230400001-CreateRedemptionHistory.ts
+var CreateRedemptionHistory1746230400001 = class {
+  name = "CreateRedemptionHistory1746230400001";
+  async up(queryRunner) {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS redemption_history (
+        id                    uuid           PRIMARY KEY DEFAULT gen_random_uuid(),
+        user_address          varchar(42)    NOT NULL,
+        token_address         varchar(42),
+        amount_pt             numeric(78, 0) NOT NULL,
+        created_at_unix_sec   bigint         NOT NULL,
+        reservation_id        varchar(64),
+        row_created_at        timestamptz    NOT NULL DEFAULT NOW(),
+        CONSTRAINT redemption_history_amount_positive CHECK (amount_pt > 0)
+      )
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_redemption_history_user_created
+        ON redemption_history (user_address, created_at_unix_sec DESC)
+    `);
+  }
+  async down(queryRunner) {
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS idx_redemption_history_user_created`
+    );
+    await queryRunner.query(`DROP TABLE IF EXISTS redemption_history`);
+  }
+};
+
 // src/migrations/index.ts
-var PAFI_MIGRATIONS = [InitialSchema1700000000000];
+var PAFI_MIGRATIONS = [
+  InitialSchema1700000000000,
+  CreateRedemptionHistory1746230400001
+];
 export {
+  CreateRedemptionHistory1746230400001,
   IndexerCursorEntity,
   InitialSchema1700000000000,
   LedgerJournalEntity,
@@ -744,6 +946,8 @@ export {
   PendingCreditEntity,
   PostgresCursorStore,
   PostgresPointLedger,
+  PostgresRedemptionHistoryStore,
+  RedemptionHistoryEntity,
   UserBalanceEntity
 };
 //# sourceMappingURL=index.js.map