@pafi-dev/issuer-postgres 0.1.2 → 0.3.0

package/README.md

@@ -10,10 +10,9 @@ schema from the reference issuer.
 
 > **Server-only.** Pulls in TypeORM (peer-dep). Do not bundle into a browser app.
 
-> **Compatible with `@pafi-dev/issuer@0.6.x`.** Schema baseline includes
+> **Compatible with `@pafi-dev/issuer`.** Schema baseline includes
 > `user_op_hash` columns + indexes for the mobile prepare/submit
-> bundler-receipt fallback. No migration needed when bumping issuer
-> SDK within the 0.6 line.
+> bundler-receipt fallback.
 
 ---
 
@@ -70,6 +69,11 @@ import {
       entities: [...PAFI_ENTITIES /*, ...yourCustomEntities */],
       migrations: [...PAFI_MIGRATIONS /*, ...yourCustomMigrations */],
       migrationsRun: true,
+      // Required — some shipped migrations use `CREATE INDEX
+      // CONCURRENTLY` which cannot run inside a transaction.
+      // The default "all" mode wraps every migration in one tx
+      // and rejects per-migration `transaction = false` opt-outs.
+      migrationsTransactionMode: "each",
     }),
   ],
   providers: [
@@ -178,6 +182,173 @@ extending without breaking the schema is straightforward.
 
 ---
 
+## Production deployment checklist
+
+Recommended Postgres + TypeORM config for an issuer running real-money
+balances.
+
+### 1. Connection pool sizing
+
+TypeORM defaults inherit from `pg`'s defaults (`max: 10`, no idle
+timeout) which silently throttles under load. Tune via
+`DataSourceOptions.extra`:
+
+```ts
+const dataSource = new DataSource({
+  type: "postgres",
+  url: process.env.DATABASE_URL,
+  entities: [...PAFI_ENTITIES, ...yourEntities],
+  migrations: [...PAFI_MIGRATIONS],
+  extra: {
+    // Per-pod pool max — total = max × pod count. Stay under
+    // Postgres's `max_connections` (default 100; raise via
+    // `ALTER SYSTEM SET max_connections = 200` if needed).
+    max: 20,
+    // Drop idle connections after 30s — frees slots for other pods
+    // and avoids hitting per-connection memory bloat.
+    idleTimeoutMillis: 30_000,
+    // Connection acquisition deadline — fail fast instead of
+    // queueing requests indefinitely under back-pressure.
+    connectionTimeoutMillis: 5_000,
+    // Per-statement deadline (also see "statement_timeout" below).
+    // 30s is a generous cap for read queries; tighten to 5s in
+    // production once you've measured tail latencies.
+    statement_timeout: 30_000,
+  },
+});
+```
+
+### 2. Server-side timeouts
+
+Set at the database role level (run once during issuer onboarding):
+
+```sql
+-- Per-statement deadline — backstop against runaway queries holding
+-- a connection indefinitely. 30s is conservative; tune lower once
+-- you've measured your p99.
+ALTER ROLE issuer_app SET statement_timeout = '30s';
+
+-- Auto-rollback transactions that idle without sending another query.
+-- Critical pairing with FOR UPDATE: a stale transaction holds row
+-- locks, blocking concurrent claim/redeem. 60s is safe; aggressive
+-- shops set 10s.
+ALTER ROLE issuer_app SET idle_in_transaction_session_timeout = '60s';
+
+-- Lock acquisition deadline — fail fast on deadlock-adjacent waits
+-- instead of waiting for Postgres's default deadlock_timeout (1s)
+-- followed by automatic retry.
+ALTER ROLE issuer_app SET lock_timeout = '10s';
+```
+
+### 3. Expired lock sweep
+
+`getBalance` is a pure read (does not transition expired locks
+itself). Schedule `markExpiredLocks()` periodically to keep the
+`locked_mint_requests` table from growing unbounded:
+
+```ts
+import { Interval } from "@nestjs/schedule";
+
+@Injectable()
+export class LockSweepService {
+  private readonly logger = new Logger(LockSweepService.name);
+
+  constructor(@Inject("PAFI_LEDGER") private readonly ledger: PostgresPointLedger) {}
+
+  // Every 5 minutes — cheap UPDATE, single round trip.
+  @Interval(5 * 60 * 1000)
+  async sweep() {
+    try {
+      const swept = await this.ledger.markExpiredLocks();
+      if (swept > 0) this.logger.debug(`expired ${swept} mint locks`);
+    } catch (err) {
+      this.logger.error("lock sweep failed", err);
+    }
+  }
+}
+```
+
+Also wire `markExpiredCredits()` (PendingCredit equivalent) the same way.
+
+### 4. Required indexes
+
+Shipped migrations (`InitialSchema` + `AddLockedMintCompositeIndexes`)
+create these indexes on `locked_mint_requests`. Verify after migration:
+
+```sql
+SELECT indexname, indexdef
+FROM pg_indexes
+WHERE tablename = 'locked_mint_requests'
+ORDER BY indexname;
+```
+
+Expected output:
+
+```sql
+-- Hot path: sumPendingLocks (during getBalance + lockForMinting)
+CREATE INDEX "IDX_locked_mint_user_token_status_expires"
+  ON locked_mint_requests (user_address, token_address, status, expires_at);
+
+-- Hot path: PointIndexer.pickMatchingLock + deductBalance findOne
+CREATE INDEX "IDX_locked_mint_user_token_amount_status"
+  ON locked_mint_requests (user_address, token_address, amount, status);
+
+-- Sweep path: markExpiredLocks UPDATE (partial — only PENDING rows)
+CREATE INDEX "IDX_locked_mint_pending_expires"
+  ON locked_mint_requests (expires_at) WHERE status = 'PENDING';
+
+-- Bundler-receipt fallback in statusHandlers
+CREATE INDEX "IDX_locked_mint_user_op_hash"
+  ON locked_mint_requests (user_op_hash);
+```
+
+Plus the partial unique index on `ledger_journal` that enforces
+indexer idempotency (`MINT_CONFIRMED`, `BURN_FOR_CREDIT`):
+
+```sql
+CREATE UNIQUE INDEX "UQ_ledger_journal_user_tx_reason"
+  ON ledger_journal (user_address, tx_hash, reason)
+  WHERE tx_hash IS NOT NULL;
+```
+
+### 5. Monitoring queries
+
+Surface key health metrics to your APM (Datadog / Grafana / Sentry):
+
+```sql
+-- Outstanding PENDING locks per token (alert if > N)
+SELECT token_address, COUNT(*) AS pending_count, SUM(amount::numeric) AS total_locked
+FROM locked_mint_requests
+WHERE status = 'PENDING' AND expires_at > NOW()
+GROUP BY token_address;
+
+-- Pool saturation
+SELECT count(*), state FROM pg_stat_activity
+WHERE datname = current_database()
+GROUP BY state;
+
+-- Long-running locks (potential deadlock indicator)
+SELECT pid, now() - xact_start AS duration, state, query
+FROM pg_stat_activity
+WHERE state IN ('active','idle in transaction')
+  AND now() - xact_start > interval '10 seconds'
+ORDER BY duration DESC;
+```
+
+### 6. Backup + recovery
+
+Ledger is the source of truth for off-chain points balance. Configure:
+
+- Continuous WAL archiving (`pg_basebackup` + `archive_command`)
+- Daily logical dumps (`pg_dump --format=custom`) retained 30+ days
+- Point-in-time recovery validated quarterly via dry-run restore
+
+Loss of `user_balances` rows = customer rebate liability proportional
+to historic mints. Treat backup verification as a security control,
+not an operational nice-to-have.
+
+---
+
 ## License
 
 Apache-2.0

package/dist/entities/index.cjs

@@ -33,6 +33,7 @@ __export(entities_exports, {
   LockedMintEntity: () => LockedMintEntity,
   PAFI_ENTITIES: () => PAFI_ENTITIES,
   PendingCreditEntity: () => PendingCreditEntity,
+  RedemptionHistoryEntity: () => RedemptionHistoryEntity,
   UserBalanceEntity: () => UserBalanceEntity
 });
 module.exports = __toCommonJS(entities_exports);
@@ -98,7 +99,22 @@ __decorateClass([
 ], LockedMintEntity.prototype, "userOpHash", 2);
 LockedMintEntity = __decorateClass([
   (0, import_typeorm.Entity)({ name: "locked_mint_requests" }),
-  (0, import_typeorm.Index)(["userAddress", "status"])
+  (0, import_typeorm.Index)("IDX_locked_mint_user_token_status_expires", [
+    "userAddress",
+    "tokenAddress",
+    "status",
+    "expiresAt"
+  ]),
+  (0, import_typeorm.Index)("IDX_locked_mint_user_token_amount_status", [
+    "userAddress",
+    "tokenAddress",
+    "amount",
+    "status"
+  ]),
+  (0, import_typeorm.Index)("IDX_locked_mint_pending_expires", ["expiresAt"], {
+    where: `"status" = 'PENDING'`
+  }),
+  (0, import_typeorm.Index)("IDX_locked_mint_user_op_hash", ["userOpHash"])
 ], LockedMintEntity);
 
 // src/entities/pending-credit.entity.ts
@@ -251,7 +267,15 @@ __decorateClass([
 ], LedgerJournalEntity.prototype, "createdAt", 2);
 LedgerJournalEntity = __decorateClass([
   (0, import_typeorm4.Entity)({ name: "ledger_journal" }),
-  (0, import_typeorm4.Index)(["userAddress", "createdAt"])
+  (0, import_typeorm4.Index)(["userAddress", "createdAt"]),
+  (0, import_typeorm4.Index)(
+    "UQ_ledger_journal_user_token_tx_reason",
+    ["userAddress", "tokenAddress", "txHash", "reason"],
+    {
+      unique: true,
+      where: '"tx_hash" IS NOT NULL'
+    }
+  )
 ], LedgerJournalEntity);
 
 // src/entities/indexer-cursor.entity.ts
@@ -283,13 +307,68 @@ IndexerCursorEntity = __decorateClass([
   (0, import_typeorm5.Entity)({ name: "indexer_cursors" })
 ], IndexerCursorEntity);
 
+// src/entities/redemption-history.entity.ts
+var import_typeorm6 = require("typeorm");
+var RedemptionHistoryEntity = class {
+  id;
+  userAddress;
+  tokenAddress;
+  amountPt;
+  createdAtUnixSec;
+  reservationId;
+  rowCreatedAt;
+};
+__decorateClass([
+  (0, import_typeorm6.PrimaryGeneratedColumn)("uuid")
+], RedemptionHistoryEntity.prototype, "id", 2);
+__decorateClass([
+  (0, import_typeorm6.Column)({ name: "user_address", type: "varchar", length: 42 })
+], RedemptionHistoryEntity.prototype, "userAddress", 2);
+__decorateClass([
+  (0, import_typeorm6.Column)({ name: "token_address", type: "varchar", length: 42, nullable: true })
+], RedemptionHistoryEntity.prototype, "tokenAddress", 2);
+__decorateClass([
+  (0, import_typeorm6.Column)({
+    name: "amount_pt",
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    transformer: {
+      to: (value) => value.toString(),
+      from: (value) => BigInt(value)
+    }
+  })
+], RedemptionHistoryEntity.prototype, "amountPt", 2);
+__decorateClass([
+  (0, import_typeorm6.Column)({ name: "created_at_unix_sec", type: "bigint" })
+], RedemptionHistoryEntity.prototype, "createdAtUnixSec", 2);
+__decorateClass([
+  (0, import_typeorm6.Column)({
+    name: "reservation_id",
+    type: "varchar",
+    length: 64,
+    nullable: true
+  })
+], RedemptionHistoryEntity.prototype, "reservationId", 2);
+__decorateClass([
+  (0, import_typeorm6.CreateDateColumn)({ name: "row_created_at", type: "timestamptz" })
+], RedemptionHistoryEntity.prototype, "rowCreatedAt", 2);
+RedemptionHistoryEntity = __decorateClass([
+  (0, import_typeorm6.Entity)({ name: "redemption_history" }),
+  (0, import_typeorm6.Index)("idx_redemption_history_user_created", [
+    "userAddress",
+    "createdAtUnixSec"
+  ])
+], RedemptionHistoryEntity);
+
 // src/entities/index.ts
 var PAFI_ENTITIES = [
   LockedMintEntity,
   PendingCreditEntity,
   UserBalanceEntity,
   LedgerJournalEntity,
-  IndexerCursorEntity
+  IndexerCursorEntity,
+  RedemptionHistoryEntity
 ];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -298,6 +377,7 @@ var PAFI_ENTITIES = [
   LockedMintEntity,
   PAFI_ENTITIES,
   PendingCreditEntity,
+  RedemptionHistoryEntity,
   UserBalanceEntity
 });
 //# sourceMappingURL=index.cjs.map

package/dist/entities/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/entities/index.ts","../../src/entities/locked-mint.entity.ts","../../src/entities/pending-credit.entity.ts","../../src/entities/user-balance.entity.ts","../../src/entities/ledger-journal.entity.ts","../../src/entities/indexer-cursor.entity.ts"],"sourcesContent":["export { LockedMintEntity } from \"./locked-mint.entity\";\nexport {\n  PendingCreditEntity,\n  type PendingCreditStatus,\n} from \"./pending-credit.entity\";\nexport { UserBalanceEntity } from \"./user-balance.entity\";\nexport { LedgerJournalEntity } from \"./ledger-journal.entity\";\nexport { IndexerCursorEntity } from \"./indexer-cursor.entity\";\n\nimport { LockedMintEntity } from \"./locked-mint.entity\";\nimport { PendingCreditEntity } from \"./pending-credit.entity\";\nimport { UserBalanceEntity } from \"./user-balance.entity\";\nimport { LedgerJournalEntity } from \"./ledger-journal.entity\";\nimport { IndexerCursorEntity } from \"./indexer-cursor.entity\";\n\n/**\n * All entities in one array — drop into TypeORM's `entities` config or\n * NestJS's `TypeOrmModule.forFeature(PAFI_ENTITIES)`.\n */\nexport const PAFI_ENTITIES = [\n  LockedMintEntity,\n  PendingCreditEntity,\n  UserBalanceEntity,\n  LedgerJournalEntity,\n  IndexerCursorEntity,\n] as const;\n","import {\n  Column,\n  CreateDateColumn,\n  Entity,\n  Index,\n  PrimaryGeneratedColumn,\n} from \"typeorm\";\nimport type { MintingStatus } from \"@pafi-dev/issuer\";\n\n/**\n * A reservation against a user's off-chain balance.\n *\n * Lifecycle:\n *   PENDING ── PointIndexer matches Mint event ──▶ MINTED\n *      │\n *      ├── deadline elapsed ────────────────────▶ EXPIRED\n *      │\n *      └── tx reverted ─────────────────────────▶ FAILED\n *\n * The `(userAddress, status)` composite index keeps the \"sum all\n * PENDING locks\" hot path of `lockForMinting()` fast under load.\n */\n@Entity({ name: \"locked_mint_requests\" })\n@Index([\"userAddress\", \"status\"])\nexport class LockedMintEntity {\n  @PrimaryGeneratedColumn(\"uuid\")\n  id!: string;\n\n  @Column({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @Column({ name: \"token_address\", type: \"varchar\", length: 42 })\n  tokenAddress!: string;\n\n  @Column({\n    name: \"amount\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  amount!: bigint;\n\n  @Column({\n    name: \"status\",\n    type: \"varchar\",\n    length: 16,\n    default: \"PENDING\",\n  })\n  status!: MintingStatus;\n\n  @CreateDateColumn({ name: \"created_at\" })\n  createdAt!: Date;\n\n  @Column({ name: \"expires_at\", type: \"timestamp with time zone\" })\n  expiresAt!: Date;\n\n  @Column({ name: \"tx_hash\", type: \"varchar\", length: 66, nullable: true })\n  txHash?: string | null;\n\n  /**\n   * ERC-4337 userOpHash returned by the bundler at /claim/submit.\n   * Bound to the lock so `/claim/status` can fall back to the bundler\n   * receipt — required when multiple PENDING locks share the same\n   * `amount` (PointIndexer matches by amount and can pick the wrong\n   * sibling lock).\n   */\n  @Column({\n    name: \"user_op_hash\",\n    type: \"varchar\",\n    length: 66,\n    nullable: true,\n  })\n  userOpHash?: string | null;\n}\n","import {\n  Column,\n  CreateDateColumn,\n  Entity,\n  Index,\n  PrimaryGeneratedColumn,\n} from \"typeorm\";\n\nexport type PendingCreditStatus = \"PENDING\" | \"RESOLVED\" | \"EXPIRED\";\n\n/**\n * Reverse flow — user burns on-chain PT, `BurnIndexer` observes\n * `Transfer(user → 0x0)`, the credit is settled to the off-chain ledger.\n *\n * Lifecycle:\n *   PENDING ── Burn tx observed by indexer ──▶ RESOLVED\n *      │\n *      └── deadline elapsed ────────────────▶ EXPIRED\n *\n * The credit is reserved BEFORE the UserOp is submitted so the\n * indexer can correlate `(user, amount, token)` back to the off-chain\n * row when the burn lands.\n */\n@Entity({ name: \"pending_credits\" })\n@Index([\"userAddress\", \"status\"])\n@Index([\"txHash\"])\nexport class PendingCreditEntity {\n  @PrimaryGeneratedColumn(\"uuid\")\n  id!: string;\n\n  @Column({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @Column({ name: \"token_address\", type: \"varchar\", length: 42 })\n  tokenAddress!: string;\n\n  @Column({\n    name: \"amount\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  amount!: bigint;\n\n  @Column({\n    name: \"status\",\n    type: \"varchar\",\n    length: 16,\n    default: \"PENDING\",\n  })\n  status!: PendingCreditStatus;\n\n  /** On-chain burn tx that settled this credit. Null until indexer resolves. */\n  @Column({ name: \"tx_hash\", type: \"varchar\", length: 66, nullable: true })\n  txHash?: string | null;\n\n  /** ERC-4337 userOpHash bound at /redeem/submit. See `LockedMintEntity`. */\n  @Column({\n    name: \"user_op_hash\",\n    type: \"varchar\",\n    length: 66,\n    nullable: true,\n  })\n  userOpHash?: string | null;\n\n  @CreateDateColumn({ name: \"created_at\" })\n  createdAt!: Date;\n\n  @Column({ name: \"expires_at\", type: \"timestamp with time zone\" })\n  expiresAt!: Date;\n\n  @Column({\n    name: \"resolved_at\",\n    type: \"timestamp with time zone\",\n    nullable: true,\n  })\n  resolvedAt?: Date | null;\n}\n","import { Column, Entity, PrimaryColumn, UpdateDateColumn } from \"typeorm\";\n\n/**\n * Off-chain point balance per `(userAddress, tokenAddress)`.\n *\n * `balance` is the **total** owned; pending reservations live in\n * `LockedMintEntity`. Available balance = total − sum(PENDING locks)\n * — `getBalance` in `PostgresPointLedger` does this subtraction\n * inside a transaction so reads are race-free.\n *\n * All amounts are `numeric(78, 0)` for full bigint precision (uint256\n * fits in 78 decimal digits). TypeORM transforms bigint ↔ string at\n * the boundary; in JS/TS code we always deal with `bigint`.\n */\n@Entity({ name: \"user_balances\" })\nexport class UserBalanceEntity {\n  @PrimaryColumn({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @PrimaryColumn({ name: \"token_address\", type: \"varchar\", length: 42 })\n  tokenAddress!: string;\n\n  @Column({\n    name: \"balance\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    default: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  balance!: bigint;\n\n  @UpdateDateColumn({ name: \"updated_at\" })\n  updatedAt!: Date;\n}\n","import {\n  Column,\n  CreateDateColumn,\n  Entity,\n  Index,\n  PrimaryGeneratedColumn,\n} from \"typeorm\";\n\n/**\n * Append-only audit trail for every balance mutation. Used for\n * reconciliation, customer support, and regulatory reporting.\n *\n * Sign convention:\n *   - positive `delta` — credit (merchant award, refund, manual top-up)\n *   - negative `delta` — debit (mint confirmation against the off-chain\n *     balance; `txHash` references the on-chain Mint event)\n */\n@Entity({ name: \"ledger_journal\" })\n@Index([\"userAddress\", \"createdAt\"])\nexport class LedgerJournalEntity {\n  @PrimaryGeneratedColumn(\"uuid\")\n  id!: string;\n\n  @Column({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @Column({ name: \"token_address\", type: \"varchar\", length: 42 })\n  tokenAddress!: string;\n\n  @Column({\n    name: \"delta\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  delta!: bigint;\n\n  @Column({ name: \"reason\", type: \"varchar\", length: 128 })\n  reason!: string;\n\n  @Column({ name: \"tx_hash\", type: \"varchar\", length: 66, nullable: true })\n  txHash?: string | null;\n\n  @CreateDateColumn({ name: \"created_at\" })\n  createdAt!: Date;\n}\n","import { Column, Entity, PrimaryColumn, UpdateDateColumn } from \"typeorm\";\n\n/**\n * Persistent cursor for `PointIndexer` / `BurnIndexer`. Multiple rows\n * coexist keyed by `id` (e.g. `default` for the mint indexer,\n * `burn:0x...` for each per-token burn indexer).\n *\n * Stores the **next** block to scan, not the last processed one.\n * Indexer reads on startup and resumes from there.\n */\n@Entity({ name: \"indexer_cursors\" })\nexport class IndexerCursorEntity {\n  @PrimaryColumn({ type: \"varchar\", length: 64 })\n  id!: string;\n\n  @Column({\n    name: \"next_block\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  nextBlock!: bigint;\n\n  @UpdateDateColumn({ name: \"updated_at\" })\n  updatedAt!: Date;\n}\n"],"mappings":"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","names":["import_typeorm","import_typeorm","import_typeorm","import_typeorm"]}
+{"version":3,"sources":["../../src/entities/index.ts","../../src/entities/locked-mint.entity.ts","../../src/entities/pending-credit.entity.ts","../../src/entities/user-balance.entity.ts","../../src/entities/ledger-journal.entity.ts","../../src/entities/indexer-cursor.entity.ts","../../src/entities/redemption-history.entity.ts"],"sourcesContent":["export { LockedMintEntity } from \"./locked-mint.entity\";\nexport {\n  PendingCreditEntity,\n  type PendingCreditStatus,\n} from \"./pending-credit.entity\";\nexport { UserBalanceEntity } from \"./user-balance.entity\";\nexport { LedgerJournalEntity } from \"./ledger-journal.entity\";\nexport { IndexerCursorEntity } from \"./indexer-cursor.entity\";\nexport { RedemptionHistoryEntity } from \"./redemption-history.entity\";\n\nimport { LockedMintEntity } from \"./locked-mint.entity\";\nimport { PendingCreditEntity } from \"./pending-credit.entity\";\nimport { UserBalanceEntity } from \"./user-balance.entity\";\nimport { LedgerJournalEntity } from \"./ledger-journal.entity\";\nimport { IndexerCursorEntity } from \"./indexer-cursor.entity\";\nimport { RedemptionHistoryEntity } from \"./redemption-history.entity\";\n\n/**\n * All entities in one array — drop into TypeORM's `entities` config or\n * NestJS's `TypeOrmModule.forFeature(PAFI_ENTITIES)`.\n */\nexport const PAFI_ENTITIES = [\n  LockedMintEntity,\n  PendingCreditEntity,\n  UserBalanceEntity,\n  LedgerJournalEntity,\n  IndexerCursorEntity,\n  RedemptionHistoryEntity,\n] as const;\n","import {\n  Column,\n  CreateDateColumn,\n  Entity,\n  Index,\n  PrimaryGeneratedColumn,\n} from \"typeorm\";\nimport type { MintingStatus } from \"@pafi-dev/issuer\";\n\n/**\n * A reservation against a user's off-chain balance.\n *\n * Lifecycle:\n *   PENDING ── PointIndexer matches Mint event ──▶ MINTED\n *      │\n *      ├── deadline elapsed ────────────────────▶ EXPIRED\n *      │\n *      └── tx reverted ─────────────────────────▶ FAILED\n *\n * Index policy — the three composite indexes below mirror the three\n * query shapes the SDK runs against this table. They are the source\n * of truth for the schema; the migrations create indexes with the\n * exact same names so `synchronize: false` deployments do not drift.\n *\n *   IDX_locked_mint_user_token_status_expires\n *     Hot path: `sumPendingLocks` inside `getBalance` + `lockForMinting`.\n *     4-col covering index — `expires_at` in the range scan instead\n *     of post-filtered from the heap.\n *\n *   IDX_locked_mint_user_token_amount_status\n *     Hot path: `PointIndexer.pickMatchingLock` + the lock-resolution\n *     `findOne` inside `deductBalance`. `amount` is the\n *     selectivity-critical predicate.\n *\n *   IDX_locked_mint_pending_expires\n *     Sweep path: `markExpiredLocks` UPDATE. Partial\n *     `WHERE status = 'PENDING'` keeps the index small — only the\n *     rows the sweep can touch live in the index.\n *\n *   IDX_locked_mint_user_op_hash\n *     Bundler-receipt fallback in `statusHandlers` — point lookup\n *     by userOpHash.\n */\n@Entity({ name: \"locked_mint_requests\" })\n@Index(\"IDX_locked_mint_user_token_status_expires\", [\n  \"userAddress\",\n  \"tokenAddress\",\n  \"status\",\n  \"expiresAt\",\n])\n@Index(\"IDX_locked_mint_user_token_amount_status\", [\n  \"userAddress\",\n  \"tokenAddress\",\n  \"amount\",\n  \"status\",\n])\n@Index(\"IDX_locked_mint_pending_expires\", [\"expiresAt\"], {\n  where: \"\\\"status\\\" = 'PENDING'\",\n})\n@Index(\"IDX_locked_mint_user_op_hash\", [\"userOpHash\"])\nexport class LockedMintEntity {\n  @PrimaryGeneratedColumn(\"uuid\")\n  id!: string;\n\n  @Column({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @Column({ name: \"token_address\", type: \"varchar\", length: 42 })\n  tokenAddress!: string;\n\n  @Column({\n    name: \"amount\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  amount!: bigint;\n\n  @Column({\n    name: \"status\",\n    type: \"varchar\",\n    length: 16,\n    default: \"PENDING\",\n  })\n  status!: MintingStatus;\n\n  @CreateDateColumn({ name: \"created_at\" })\n  createdAt!: Date;\n\n  @Column({ name: \"expires_at\", type: \"timestamp with time zone\" })\n  expiresAt!: Date;\n\n  @Column({ name: \"tx_hash\", type: \"varchar\", length: 66, nullable: true })\n  txHash?: string | null;\n\n  /**\n   * ERC-4337 userOpHash returned by the bundler at /claim/submit.\n   * Bound to the lock so `/claim/status` can fall back to the bundler\n   * receipt — required when multiple PENDING locks share the same\n   * `amount` (PointIndexer matches by amount and can pick the wrong\n   * sibling lock).\n   */\n  @Column({\n    name: \"user_op_hash\",\n    type: \"varchar\",\n    length: 66,\n    nullable: true,\n  })\n  userOpHash?: string | null;\n}\n","import {\n  Column,\n  CreateDateColumn,\n  Entity,\n  Index,\n  PrimaryGeneratedColumn,\n} from \"typeorm\";\n\nexport type PendingCreditStatus = \"PENDING\" | \"RESOLVED\" | \"EXPIRED\";\n\n/**\n * Reverse flow — user burns on-chain PT, `BurnIndexer` observes\n * `Transfer(user → 0x0)`, the credit is settled to the off-chain ledger.\n *\n * Lifecycle:\n *   PENDING ── Burn tx observed by indexer ──▶ RESOLVED\n *      │\n *      └── deadline elapsed ────────────────▶ EXPIRED\n *\n * The credit is reserved BEFORE the UserOp is submitted so the\n * indexer can correlate `(user, amount, token)` back to the off-chain\n * row when the burn lands.\n */\n@Entity({ name: \"pending_credits\" })\n@Index([\"userAddress\", \"status\"])\n@Index([\"txHash\"])\nexport class PendingCreditEntity {\n  @PrimaryGeneratedColumn(\"uuid\")\n  id!: string;\n\n  @Column({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @Column({ name: \"token_address\", type: \"varchar\", length: 42 })\n  tokenAddress!: string;\n\n  @Column({\n    name: \"amount\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  amount!: bigint;\n\n  @Column({\n    name: \"status\",\n    type: \"varchar\",\n    length: 16,\n    default: \"PENDING\",\n  })\n  status!: PendingCreditStatus;\n\n  /** On-chain burn tx that settled this credit. Null until indexer resolves. */\n  @Column({ name: \"tx_hash\", type: \"varchar\", length: 66, nullable: true })\n  txHash?: string | null;\n\n  /** ERC-4337 userOpHash bound at /redeem/submit. See `LockedMintEntity`. */\n  @Column({\n    name: \"user_op_hash\",\n    type: \"varchar\",\n    length: 66,\n    nullable: true,\n  })\n  userOpHash?: string | null;\n\n  @CreateDateColumn({ name: \"created_at\" })\n  createdAt!: Date;\n\n  @Column({ name: \"expires_at\", type: \"timestamp with time zone\" })\n  expiresAt!: Date;\n\n  @Column({\n    name: \"resolved_at\",\n    type: \"timestamp with time zone\",\n    nullable: true,\n  })\n  resolvedAt?: Date | null;\n}\n","import { Column, Entity, PrimaryColumn, UpdateDateColumn } from \"typeorm\";\n\n/**\n * Off-chain point balance per `(userAddress, tokenAddress)`.\n *\n * `balance` is the **total** owned; pending reservations live in\n * `LockedMintEntity`. Available balance = total − sum(PENDING locks)\n * — `getBalance` in `PostgresPointLedger` does this subtraction\n * inside a transaction so reads are race-free.\n *\n * All amounts are `numeric(78, 0)` for full bigint precision (uint256\n * fits in 78 decimal digits). TypeORM transforms bigint ↔ string at\n * the boundary; in JS/TS code we always deal with `bigint`.\n */\n@Entity({ name: \"user_balances\" })\nexport class UserBalanceEntity {\n  @PrimaryColumn({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @PrimaryColumn({ name: \"token_address\", type: \"varchar\", length: 42 })\n  tokenAddress!: string;\n\n  @Column({\n    name: \"balance\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    default: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  balance!: bigint;\n\n  @UpdateDateColumn({ name: \"updated_at\" })\n  updatedAt!: Date;\n}\n","import {\n  Column,\n  CreateDateColumn,\n  Entity,\n  Index,\n  PrimaryGeneratedColumn,\n} from \"typeorm\";\n\n/**\n * Append-only audit trail for every balance mutation. Used for\n * reconciliation, customer support, and regulatory reporting.\n *\n * Sign convention:\n *   - positive `delta` — credit (merchant award, refund, manual top-up)\n *   - negative `delta` — debit (mint confirmation against the off-chain\n *     balance; `txHash` references the on-chain Mint event)\n *\n * Idempotency invariant: for any indexer-driven reason (e.g.\n * `MINT_CONFIRMED`, `BURN_FOR_CREDIT`) the tuple\n * `(user_address, token_address, tx_hash, reason)` is unique. Enforced\n * by a partial unique index that only fires when `tx_hash IS NOT NULL`,\n * so off-chain reasons (e.g. `AIRDROP`) without a tx hash are\n * unaffected. Last-line defense against double-deduct / double-credit\n * when the indexer replays an event (reorg, restart, duplicate pod).\n *\n * The `token_address` column is part of the tuple to prevent the\n * audit PACI5-7 collapse: a single transaction that mints two\n * different PointTokens for the same user (batched EIP-7702 claim or\n * Pimlico bundler grouping two single-mint UserOps into one bundle)\n * would otherwise have its second debit silently shadowed by the\n * first token's journal row, while `PointIndexer.finalize` still\n * flipped the second lock to MINTED — silent off-chain debit miss.\n */\n@Entity({ name: \"ledger_journal\" })\n@Index([\"userAddress\", \"createdAt\"])\n@Index(\n  \"UQ_ledger_journal_user_token_tx_reason\",\n  [\"userAddress\", \"tokenAddress\", \"txHash\", \"reason\"],\n  {\n    unique: true,\n    where: '\"tx_hash\" IS NOT NULL',\n  },\n)\nexport class LedgerJournalEntity {\n  @PrimaryGeneratedColumn(\"uuid\")\n  id!: string;\n\n  @Column({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @Column({ name: \"token_address\", type: \"varchar\", length: 42 })\n  tokenAddress!: string;\n\n  @Column({\n    name: \"delta\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  delta!: bigint;\n\n  @Column({ name: \"reason\", type: \"varchar\", length: 128 })\n  reason!: string;\n\n  @Column({ name: \"tx_hash\", type: \"varchar\", length: 66, nullable: true })\n  txHash?: string | null;\n\n  @CreateDateColumn({ name: \"created_at\" })\n  createdAt!: Date;\n}\n","import { Column, Entity, PrimaryColumn, UpdateDateColumn } from \"typeorm\";\n\n/**\n * Persistent cursor for `PointIndexer` / `BurnIndexer`. Multiple rows\n * coexist keyed by `id` (e.g. `default` for the mint indexer,\n * `burn:0x...` for each per-token burn indexer).\n *\n * Stores the **next** block to scan, not the last processed one.\n * Indexer reads on startup and resumes from there.\n */\n@Entity({ name: \"indexer_cursors\" })\nexport class IndexerCursorEntity {\n  @PrimaryColumn({ type: \"varchar\", length: 64 })\n  id!: string;\n\n  @Column({\n    name: \"next_block\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  nextBlock!: bigint;\n\n  @UpdateDateColumn({ name: \"updated_at\" })\n  updatedAt!: Date;\n}\n","import {\n  Column,\n  CreateDateColumn,\n  Entity,\n  Index,\n  PrimaryGeneratedColumn,\n} from \"typeorm\";\n\n/**\n * Per-user redemption history row. One row per successful initiate\n * (call to `RedemptionService.recordSuccessfulInitiate`).\n *\n * `sumRedeemedSince` does a SUM(amount) WHERE created_at >= :since\n * which uses the (user_address, created_at) composite index. We do\n * NOT prune old rows automatically — they're cheap and useful for\n * audit. Issuers can add a periodic VACUUM/partition policy if the\n * table grows past ~100M rows.\n *\n * Amounts are `numeric(78, 0)` for full bigint precision.\n */\n@Entity({ name: \"redemption_history\" })\n@Index(\"idx_redemption_history_user_created\", [\n  \"userAddress\",\n  \"createdAtUnixSec\",\n])\nexport class RedemptionHistoryEntity {\n  @PrimaryGeneratedColumn(\"uuid\")\n  id!: string;\n\n  @Column({ name: \"user_address\", type: \"varchar\", length: 42 })\n  userAddress!: string;\n\n  @Column({ name: \"token_address\", type: \"varchar\", length: 42, nullable: true })\n  tokenAddress!: string | null;\n\n  @Column({\n    name: \"amount_pt\",\n    type: \"numeric\",\n    precision: 78,\n    scale: 0,\n    transformer: {\n      to: (value: bigint) => value.toString(),\n      from: (value: string) => BigInt(value),\n    },\n  })\n  amountPt!: bigint;\n\n  /**\n   * Caller-controlled timestamp (unix seconds). Stored as integer, not\n   * timestamptz, because the evaluator works in unix seconds and we want\n   * the same time domain on read + write — no surprise tz conversions.\n   */\n  @Column({ name: \"created_at_unix_sec\", type: \"bigint\" })\n  createdAtUnixSec!: string;\n\n  /**\n   * Optional pointer back to the burn-flow reservation (PendingCredit.id).\n   * Lets ops trace a redemption-history row to the underlying lock.\n   */\n  @Column({\n    name: \"reservation_id\",\n    type: \"varchar\",\n    length: 64,\n    nullable: true,\n  })\n  reservationId!: string | null;\n\n  @CreateDateColumn({ name: \"row_created_at\", type: \"timestamptz\" })\n  rowCreatedAt!: Date;\n}\n"],"mappings":"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","names":["import_typeorm","import_typeorm","import_typeorm","import_typeorm","import_typeorm"]}

package/dist/entities/index.d.cts

@@ -10,8 +10,29 @@ import { MintingStatus } from '@pafi-dev/issuer';
  *      │
  *      └── tx reverted ─────────────────────────▶ FAILED
  *
- * The `(userAddress, status)` composite index keeps the "sum all
- * PENDING locks" hot path of `lockForMinting()` fast under load.
+ * Index policy — the three composite indexes below mirror the three
+ * query shapes the SDK runs against this table. They are the source
+ * of truth for the schema; the migrations create indexes with the
+ * exact same names so `synchronize: false` deployments do not drift.
+ *
+ *   IDX_locked_mint_user_token_status_expires
+ *     Hot path: `sumPendingLocks` inside `getBalance` + `lockForMinting`.
+ *     4-col covering index — `expires_at` in the range scan instead
+ *     of post-filtered from the heap.
+ *
+ *   IDX_locked_mint_user_token_amount_status
+ *     Hot path: `PointIndexer.pickMatchingLock` + the lock-resolution
+ *     `findOne` inside `deductBalance`. `amount` is the
+ *     selectivity-critical predicate.
+ *
+ *   IDX_locked_mint_pending_expires
+ *     Sweep path: `markExpiredLocks` UPDATE. Partial
+ *     `WHERE status = 'PENDING'` keeps the index small — only the
+ *     rows the sweep can touch live in the index.
+ *
+ *   IDX_locked_mint_user_op_hash
+ *     Bundler-receipt fallback in `statusHandlers` — point lookup
+ *     by userOpHash.
  */
 declare class LockedMintEntity {
     id: string;
@@ -88,6 +109,22 @@ declare class UserBalanceEntity {
  *   - positive `delta` — credit (merchant award, refund, manual top-up)
  *   - negative `delta` — debit (mint confirmation against the off-chain
  *     balance; `txHash` references the on-chain Mint event)
+ *
+ * Idempotency invariant: for any indexer-driven reason (e.g.
+ * `MINT_CONFIRMED`, `BURN_FOR_CREDIT`) the tuple
+ * `(user_address, token_address, tx_hash, reason)` is unique. Enforced
+ * by a partial unique index that only fires when `tx_hash IS NOT NULL`,
+ * so off-chain reasons (e.g. `AIRDROP`) without a tx hash are
+ * unaffected. Last-line defense against double-deduct / double-credit
+ * when the indexer replays an event (reorg, restart, duplicate pod).
+ *
+ * The `token_address` column is part of the tuple to prevent the
+ * audit PACI5-7 collapse: a single transaction that mints two
+ * different PointTokens for the same user (batched EIP-7702 claim or
+ * Pimlico bundler grouping two single-mint UserOps into one bundle)
+ * would otherwise have its second debit silently shadowed by the
+ * first token's journal row, while `PointIndexer.finalize` still
+ * flipped the second lock to MINTED — silent off-chain debit miss.
  */
 declare class LedgerJournalEntity {
     id: string;
@@ -113,10 +150,41 @@ declare class IndexerCursorEntity {
     updatedAt: Date;
 }
 
+/**
+ * Per-user redemption history row. One row per successful initiate
+ * (call to `RedemptionService.recordSuccessfulInitiate`).
+ *
+ * `sumRedeemedSince` does a SUM(amount) WHERE created_at >= :since
+ * which uses the (user_address, created_at) composite index. We do
+ * NOT prune old rows automatically — they're cheap and useful for
+ * audit. Issuers can add a periodic VACUUM/partition policy if the
+ * table grows past ~100M rows.
+ *
+ * Amounts are `numeric(78, 0)` for full bigint precision.
+ */
+declare class RedemptionHistoryEntity {
+    id: string;
+    userAddress: string;
+    tokenAddress: string | null;
+    amountPt: bigint;
+    /**
+     * Caller-controlled timestamp (unix seconds). Stored as integer, not
+     * timestamptz, because the evaluator works in unix seconds and we want
+     * the same time domain on read + write — no surprise tz conversions.
+     */
+    createdAtUnixSec: string;
+    /**
+     * Optional pointer back to the burn-flow reservation (PendingCredit.id).
+     * Lets ops trace a redemption-history row to the underlying lock.
+     */
+    reservationId: string | null;
+    rowCreatedAt: Date;
+}
+
 /**
  * All entities in one array — drop into TypeORM's `entities` config or
  * NestJS's `TypeOrmModule.forFeature(PAFI_ENTITIES)`.
  */
-declare const PAFI_ENTITIES: readonly [typeof LockedMintEntity, typeof PendingCreditEntity, typeof UserBalanceEntity, typeof LedgerJournalEntity, typeof IndexerCursorEntity];
+declare const PAFI_ENTITIES: readonly [typeof LockedMintEntity, typeof PendingCreditEntity, typeof UserBalanceEntity, typeof LedgerJournalEntity, typeof IndexerCursorEntity, typeof RedemptionHistoryEntity];
 
-export { IndexerCursorEntity, LedgerJournalEntity, LockedMintEntity, PAFI_ENTITIES, PendingCreditEntity, type PendingCreditStatus, UserBalanceEntity };
+export { IndexerCursorEntity, LedgerJournalEntity, LockedMintEntity, PAFI_ENTITIES, PendingCreditEntity, type PendingCreditStatus, RedemptionHistoryEntity, UserBalanceEntity };

package/dist/entities/index.d.ts

@@ -10,8 +10,29 @@ import { MintingStatus } from '@pafi-dev/issuer';
  *      │
  *      └── tx reverted ─────────────────────────▶ FAILED
  *
- * The `(userAddress, status)` composite index keeps the "sum all
- * PENDING locks" hot path of `lockForMinting()` fast under load.
+ * Index policy — the three composite indexes below mirror the three
+ * query shapes the SDK runs against this table. They are the source
+ * of truth for the schema; the migrations create indexes with the
+ * exact same names so `synchronize: false` deployments do not drift.
+ *
+ *   IDX_locked_mint_user_token_status_expires
+ *     Hot path: `sumPendingLocks` inside `getBalance` + `lockForMinting`.
+ *     4-col covering index — `expires_at` in the range scan instead
+ *     of post-filtered from the heap.
+ *
+ *   IDX_locked_mint_user_token_amount_status
+ *     Hot path: `PointIndexer.pickMatchingLock` + the lock-resolution
+ *     `findOne` inside `deductBalance`. `amount` is the
+ *     selectivity-critical predicate.
+ *
+ *   IDX_locked_mint_pending_expires
+ *     Sweep path: `markExpiredLocks` UPDATE. Partial
+ *     `WHERE status = 'PENDING'` keeps the index small — only the
+ *     rows the sweep can touch live in the index.
+ *
+ *   IDX_locked_mint_user_op_hash
+ *     Bundler-receipt fallback in `statusHandlers` — point lookup
+ *     by userOpHash.
  */
 declare class LockedMintEntity {
     id: string;
@@ -88,6 +109,22 @@ declare class UserBalanceEntity {
  *   - positive `delta` — credit (merchant award, refund, manual top-up)
  *   - negative `delta` — debit (mint confirmation against the off-chain
  *     balance; `txHash` references the on-chain Mint event)
+ *
+ * Idempotency invariant: for any indexer-driven reason (e.g.
+ * `MINT_CONFIRMED`, `BURN_FOR_CREDIT`) the tuple
+ * `(user_address, token_address, tx_hash, reason)` is unique. Enforced
+ * by a partial unique index that only fires when `tx_hash IS NOT NULL`,
+ * so off-chain reasons (e.g. `AIRDROP`) without a tx hash are
+ * unaffected. Last-line defense against double-deduct / double-credit
+ * when the indexer replays an event (reorg, restart, duplicate pod).
+ *
+ * The `token_address` column is part of the tuple to prevent the
+ * audit PACI5-7 collapse: a single transaction that mints two
+ * different PointTokens for the same user (batched EIP-7702 claim or
+ * Pimlico bundler grouping two single-mint UserOps into one bundle)
+ * would otherwise have its second debit silently shadowed by the
+ * first token's journal row, while `PointIndexer.finalize` still
+ * flipped the second lock to MINTED — silent off-chain debit miss.
  */
 declare class LedgerJournalEntity {
     id: string;
@@ -113,10 +150,41 @@ declare class IndexerCursorEntity {
     updatedAt: Date;
 }
 
+/**
+ * Per-user redemption history row. One row per successful initiate
+ * (call to `RedemptionService.recordSuccessfulInitiate`).
+ *
+ * `sumRedeemedSince` does a SUM(amount) WHERE created_at >= :since
+ * which uses the (user_address, created_at) composite index. We do
+ * NOT prune old rows automatically — they're cheap and useful for
+ * audit. Issuers can add a periodic VACUUM/partition policy if the
+ * table grows past ~100M rows.
+ *
+ * Amounts are `numeric(78, 0)` for full bigint precision.
+ */
+declare class RedemptionHistoryEntity {
+    id: string;
+    userAddress: string;
+    tokenAddress: string | null;
+    amountPt: bigint;
+    /**
+     * Caller-controlled timestamp (unix seconds). Stored as integer, not
+     * timestamptz, because the evaluator works in unix seconds and we want
+     * the same time domain on read + write — no surprise tz conversions.
+     */
+    createdAtUnixSec: string;
+    /**
+     * Optional pointer back to the burn-flow reservation (PendingCredit.id).
+     * Lets ops trace a redemption-history row to the underlying lock.
+     */
+    reservationId: string | null;
+    rowCreatedAt: Date;
+}
+
 /**
  * All entities in one array — drop into TypeORM's `entities` config or
  * NestJS's `TypeOrmModule.forFeature(PAFI_ENTITIES)`.
  */
-declare const PAFI_ENTITIES: readonly [typeof LockedMintEntity, typeof PendingCreditEntity, typeof UserBalanceEntity, typeof LedgerJournalEntity, typeof IndexerCursorEntity];
+declare const PAFI_ENTITIES: readonly [typeof LockedMintEntity, typeof PendingCreditEntity, typeof UserBalanceEntity, typeof LedgerJournalEntity, typeof IndexerCursorEntity, typeof RedemptionHistoryEntity];
 
-export { IndexerCursorEntity, LedgerJournalEntity, LockedMintEntity, PAFI_ENTITIES, PendingCreditEntity, type PendingCreditStatus, UserBalanceEntity };
+export { IndexerCursorEntity, LedgerJournalEntity, LockedMintEntity, PAFI_ENTITIES, PendingCreditEntity, type PendingCreditStatus, RedemptionHistoryEntity, UserBalanceEntity };