@pafi-dev/issuer-postgres 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# @pafi-dev/issuer-postgres
+
+[![npm](https://img.shields.io/npm/v/@pafi-dev/issuer-postgres)](https://www.npmjs.com/package/@pafi-dev/issuer-postgres)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Postgres-backed `IPointLedger` implementation for `@pafi-dev/issuer`.
+TypeORM entities, migrations, and a fully-baked `PostgresPointLedger`
+service issuers can drop in directly — no need to reverse-engineer the
+schema from the reference issuer.
+
+> **Server-only.** Pulls in TypeORM (peer-dep). Do not bundle into a browser app.
+
+---
+
+## Why this exists
+
+Every issuer needs the same ledger schema:
+
+- `user_balances` (per `(user, token)`)
+- `locked_mint_requests` (PENDING reservations during mint)
+- `pending_credits` (reverse flow — burn → off-chain credit)
+- `ledger_journal` (append-only audit trail)
+- `indexer_cursors` (block cursors for `PointIndexer` / `BurnIndexer`)
+
+Plus the same race-safe transactions, expired-lock sweeps,
+multi-token guards, and `userOpHash` binding for bundler-receipt
+fallback. This package ships all of it.
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.0
+- `typeorm` ^0.3.0 (peer)
+- `viem` ^2.0.0 (peer, transitively via `@pafi-dev/issuer`)
+- Postgres 13+ (for `gen_random_uuid()` / `pgcrypto`)
+
+---
+
+## Installation
+
+```bash
+pnpm add @pafi-dev/issuer-postgres @pafi-dev/issuer typeorm viem
+```
+
+---
+
+## Quick start (NestJS)
+
+```ts
+import { TypeOrmModule } from "@nestjs/typeorm";
+import {
+  PostgresPointLedger,
+  PostgresCursorStore,
+  PAFI_ENTITIES,
+  PAFI_MIGRATIONS,
+} from "@pafi-dev/issuer-postgres";
+
+@Module({
+  imports: [
+    TypeOrmModule.forRoot({
+      type: "postgres",
+      url: process.env.DATABASE_URL,
+      entities: [...PAFI_ENTITIES /*, ...yourCustomEntities */],
+      migrations: [...PAFI_MIGRATIONS /*, ...yourCustomMigrations */],
+      migrationsRun: true,
+    }),
+  ],
+  providers: [
+    {
+      provide: "POINT_LEDGER",
+      useFactory: (dataSource: DataSource) =>
+        new PostgresPointLedger(dataSource, { logger: console }),
+      inject: [DataSource],
+    },
+    {
+      provide: "INDEXER_CURSOR_STORE",
+      useFactory: (dataSource: DataSource) =>
+        new PostgresCursorStore(dataSource),
+      inject: [DataSource],
+    },
+  ],
+})
+export class LedgerModule {}
+```
+
+Then wire `POINT_LEDGER` into `createIssuerService({ ledger, ... })`
+from `@pafi-dev/issuer`.
+
+---
+
+## What you get
+
+### `PostgresPointLedger`
+
+Implements every method on `IPointLedger` from `@pafi-dev/issuer`:
+
+- **Reads** — `getBalance`, `getLockedRequests`, `getMintLock`,
+  `getPendingCredit`, `listUserTransactions`
+- **Writes** — `lockForMinting`, `releaseLock`, `deductBalance`,
+  `creditBalance`, `updateMintStatus`
+- **Reverse flow** — `reservePendingCredit`, `resolveCreditByBurnTx`,
+  `findPendingCreditLockId`
+- **Mobile flow** — `bindMintUserOpHash`, `bindCreditUserOpHash`
+  (bundler-receipt fallback against `PointIndexer`'s amount race)
+
+All mutating methods run inside a TypeORM `transaction()` so balance
++ lock + journal updates land atomically.
+
+### `PostgresCursorStore`
+
+Implements `IIndexerCursorStore`. Default key is `"default"` for the
+primary mint indexer. Use `.forKey(id)` to derive sibling stores for
+the burn indexer or per-token shards:
+
+```ts
+const mintCursor = new PostgresCursorStore(dataSource);
+const burnCursor = mintCursor.forKey(`burn:${pointTokenAddress.toLowerCase()}`);
+```
+
+### Entities + migrations
+
+Drop into your TypeORM config:
+
+```ts
+import { PAFI_ENTITIES, PAFI_MIGRATIONS } from "@pafi-dev/issuer-postgres";
+
+new DataSource({
+  entities: [...PAFI_ENTITIES, ...yourCustomEntities],
+  migrations: [...PAFI_MIGRATIONS, ...yourCustomMigrations],
+});
+```
+
+`InitialSchema1700000000000` is one consolidated migration covering
+all five tables + indexes (including the `user_op_hash` columns and
+the bundler-fallback indexes). For schema changes after this baseline,
+generate a follow-up migration in your own repo — never edit shipped
+migrations in place.
+
+---
+
+## Multi-token
+
+Every mutating method requires `tokenAddress`. There is no "default
+token" bucket — single-token issuers pass the same address every
+call. The package throws if you forget, with a clear error message:
+
+```
+PostgresPointLedger: tokenAddress is required on every call (multi-token ledger)
+```
+
+Balances are keyed by composite `(userAddress, tokenAddress)` PK.
+
+---
+
+## Issuer-specific extensions
+
+Don't subclass `PostgresPointLedger`. Instead:
+
+1. Add your tables in your own repo (`campaign_rules`,
+   `kyc_status`, etc.) with their own TypeORM entities and a follow-up
+   migration.
+2. Wrap or compose `PostgresPointLedger` if you need to layer business
+   rules on top of `creditBalance` / `lockForMinting`.
+3. For audit fields specific to your issuer (e.g. partner_id,
+   campaign_id), extend `LedgerJournalEntity` via inheritance in your
+   own entity, register it in your `entities[]`, and add a migration
+   that ALTERs the column.
+
+The shipped entities use TypeORM Discriminator-friendly defaults —
+extending without breaking the schema is straightforward.
+
+---
+
+## License
+
+Apache-2.0

package/dist/entities/index.cjs

@@ -0,0 +1,303 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/entities/index.ts
+var entities_exports = {};
+__export(entities_exports, {
+  IndexerCursorEntity: () => IndexerCursorEntity,
+  LedgerJournalEntity: () => LedgerJournalEntity,
+  LockedMintEntity: () => LockedMintEntity,
+  PAFI_ENTITIES: () => PAFI_ENTITIES,
+  PendingCreditEntity: () => PendingCreditEntity,
+  UserBalanceEntity: () => UserBalanceEntity
+});
+module.exports = __toCommonJS(entities_exports);
+
+// src/entities/locked-mint.entity.ts
+var import_typeorm = require("typeorm");
+var LockedMintEntity = class {
+  id;
+  userAddress;
+  tokenAddress;
+  amount;
+  status;
+  createdAt;
+  expiresAt;
+  txHash;
+  userOpHash;
+};
+__decorateClass([
+  (0, import_typeorm.PrimaryGeneratedColumn)("uuid")
+], LockedMintEntity.prototype, "id", 2);
+__decorateClass([
+  (0, import_typeorm.Column)({ name: "user_address", type: "varchar", length: 42 })
+], LockedMintEntity.prototype, "userAddress", 2);
+__decorateClass([
+  (0, import_typeorm.Column)({ name: "token_address", type: "varchar", length: 42 })
+], LockedMintEntity.prototype, "tokenAddress", 2);
+__decorateClass([
+  (0, import_typeorm.Column)({
+    name: "amount",
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    transformer: {
+      to: (value) => value.toString(),
+      from: (value) => BigInt(value)
+    }
+  })
+], LockedMintEntity.prototype, "amount", 2);
+__decorateClass([
+  (0, import_typeorm.Column)({
+    name: "status",
+    type: "varchar",
+    length: 16,
+    default: "PENDING"
+  })
+], LockedMintEntity.prototype, "status", 2);
+__decorateClass([
+  (0, import_typeorm.CreateDateColumn)({ name: "created_at" })
+], LockedMintEntity.prototype, "createdAt", 2);
+__decorateClass([
+  (0, import_typeorm.Column)({ name: "expires_at", type: "timestamp with time zone" })
+], LockedMintEntity.prototype, "expiresAt", 2);
+__decorateClass([
+  (0, import_typeorm.Column)({ name: "tx_hash", type: "varchar", length: 66, nullable: true })
+], LockedMintEntity.prototype, "txHash", 2);
+__decorateClass([
+  (0, import_typeorm.Column)({
+    name: "user_op_hash",
+    type: "varchar",
+    length: 66,
+    nullable: true
+  })
+], LockedMintEntity.prototype, "userOpHash", 2);
+LockedMintEntity = __decorateClass([
+  (0, import_typeorm.Entity)({ name: "locked_mint_requests" }),
+  (0, import_typeorm.Index)(["userAddress", "status"])
+], LockedMintEntity);
+
+// src/entities/pending-credit.entity.ts
+var import_typeorm2 = require("typeorm");
+var PendingCreditEntity = class {
+  id;
+  userAddress;
+  tokenAddress;
+  amount;
+  status;
+  txHash;
+  userOpHash;
+  createdAt;
+  expiresAt;
+  resolvedAt;
+};
+__decorateClass([
+  (0, import_typeorm2.PrimaryGeneratedColumn)("uuid")
+], PendingCreditEntity.prototype, "id", 2);
+__decorateClass([
+  (0, import_typeorm2.Column)({ name: "user_address", type: "varchar", length: 42 })
+], PendingCreditEntity.prototype, "userAddress", 2);
+__decorateClass([
+  (0, import_typeorm2.Column)({ name: "token_address", type: "varchar", length: 42 })
+], PendingCreditEntity.prototype, "tokenAddress", 2);
+__decorateClass([
+  (0, import_typeorm2.Column)({
+    name: "amount",
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    transformer: {
+      to: (value) => value.toString(),
+      from: (value) => BigInt(value)
+    }
+  })
+], PendingCreditEntity.prototype, "amount", 2);
+__decorateClass([
+  (0, import_typeorm2.Column)({
+    name: "status",
+    type: "varchar",
+    length: 16,
+    default: "PENDING"
+  })
+], PendingCreditEntity.prototype, "status", 2);
+__decorateClass([
+  (0, import_typeorm2.Column)({ name: "tx_hash", type: "varchar", length: 66, nullable: true })
+], PendingCreditEntity.prototype, "txHash", 2);
+__decorateClass([
+  (0, import_typeorm2.Column)({
+    name: "user_op_hash",
+    type: "varchar",
+    length: 66,
+    nullable: true
+  })
+], PendingCreditEntity.prototype, "userOpHash", 2);
+__decorateClass([
+  (0, import_typeorm2.CreateDateColumn)({ name: "created_at" })
+], PendingCreditEntity.prototype, "createdAt", 2);
+__decorateClass([
+  (0, import_typeorm2.Column)({ name: "expires_at", type: "timestamp with time zone" })
+], PendingCreditEntity.prototype, "expiresAt", 2);
+__decorateClass([
+  (0, import_typeorm2.Column)({
+    name: "resolved_at",
+    type: "timestamp with time zone",
+    nullable: true
+  })
+], PendingCreditEntity.prototype, "resolvedAt", 2);
+PendingCreditEntity = __decorateClass([
+  (0, import_typeorm2.Entity)({ name: "pending_credits" }),
+  (0, import_typeorm2.Index)(["userAddress", "status"]),
+  (0, import_typeorm2.Index)(["txHash"])
+], PendingCreditEntity);
+
+// src/entities/user-balance.entity.ts
+var import_typeorm3 = require("typeorm");
+var UserBalanceEntity = class {
+  userAddress;
+  tokenAddress;
+  balance;
+  updatedAt;
+};
+__decorateClass([
+  (0, import_typeorm3.PrimaryColumn)({ name: "user_address", type: "varchar", length: 42 })
+], UserBalanceEntity.prototype, "userAddress", 2);
+__decorateClass([
+  (0, import_typeorm3.PrimaryColumn)({ name: "token_address", type: "varchar", length: 42 })
+], UserBalanceEntity.prototype, "tokenAddress", 2);
+__decorateClass([
+  (0, import_typeorm3.Column)({
+    name: "balance",
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    default: 0,
+    transformer: {
+      to: (value) => value.toString(),
+      from: (value) => BigInt(value)
+    }
+  })
+], UserBalanceEntity.prototype, "balance", 2);
+__decorateClass([
+  (0, import_typeorm3.UpdateDateColumn)({ name: "updated_at" })
+], UserBalanceEntity.prototype, "updatedAt", 2);
+UserBalanceEntity = __decorateClass([
+  (0, import_typeorm3.Entity)({ name: "user_balances" })
+], UserBalanceEntity);
+
+// src/entities/ledger-journal.entity.ts
+var import_typeorm4 = require("typeorm");
+var LedgerJournalEntity = class {
+  id;
+  userAddress;
+  tokenAddress;
+  delta;
+  reason;
+  txHash;
+  createdAt;
+};
+__decorateClass([
+  (0, import_typeorm4.PrimaryGeneratedColumn)("uuid")
+], LedgerJournalEntity.prototype, "id", 2);
+__decorateClass([
+  (0, import_typeorm4.Column)({ name: "user_address", type: "varchar", length: 42 })
+], LedgerJournalEntity.prototype, "userAddress", 2);
+__decorateClass([
+  (0, import_typeorm4.Column)({ name: "token_address", type: "varchar", length: 42 })
+], LedgerJournalEntity.prototype, "tokenAddress", 2);
+__decorateClass([
+  (0, import_typeorm4.Column)({
+    name: "delta",
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    transformer: {
+      to: (value) => value.toString(),
+      from: (value) => BigInt(value)
+    }
+  })
+], LedgerJournalEntity.prototype, "delta", 2);
+__decorateClass([
+  (0, import_typeorm4.Column)({ name: "reason", type: "varchar", length: 128 })
+], LedgerJournalEntity.prototype, "reason", 2);
+__decorateClass([
+  (0, import_typeorm4.Column)({ name: "tx_hash", type: "varchar", length: 66, nullable: true })
+], LedgerJournalEntity.prototype, "txHash", 2);
+__decorateClass([
+  (0, import_typeorm4.CreateDateColumn)({ name: "created_at" })
+], LedgerJournalEntity.prototype, "createdAt", 2);
+LedgerJournalEntity = __decorateClass([
+  (0, import_typeorm4.Entity)({ name: "ledger_journal" }),
+  (0, import_typeorm4.Index)(["userAddress", "createdAt"])
+], LedgerJournalEntity);
+
+// src/entities/indexer-cursor.entity.ts
+var import_typeorm5 = require("typeorm");
+var IndexerCursorEntity = class {
+  id;
+  nextBlock;
+  updatedAt;
+};
+__decorateClass([
+  (0, import_typeorm5.PrimaryColumn)({ type: "varchar", length: 64 })
+], IndexerCursorEntity.prototype, "id", 2);
+__decorateClass([
+  (0, import_typeorm5.Column)({
+    name: "next_block",
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    transformer: {
+      to: (value) => value.toString(),
+      from: (value) => BigInt(value)
+    }
+  })
+], IndexerCursorEntity.prototype, "nextBlock", 2);
+__decorateClass([
+  (0, import_typeorm5.UpdateDateColumn)({ name: "updated_at" })
+], IndexerCursorEntity.prototype, "updatedAt", 2);
+IndexerCursorEntity = __decorateClass([
+  (0, import_typeorm5.Entity)({ name: "indexer_cursors" })
+], IndexerCursorEntity);
+
+// src/entities/index.ts
+var PAFI_ENTITIES = [
+  LockedMintEntity,
+  PendingCreditEntity,
+  UserBalanceEntity,
+  LedgerJournalEntity,
+  IndexerCursorEntity
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IndexerCursorEntity,
+  LedgerJournalEntity,
+  LockedMintEntity,
+  PAFI_ENTITIES,
+  PendingCreditEntity,
+  UserBalanceEntity
+});
+//# sourceMappingURL=index.cjs.map

package/dist/entities/index.cjs.map

@@ -0,0 +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"]}

package/dist/entities/index.d.cts

@@ -0,0 +1,122 @@
+import { MintingStatus } from '@pafi-dev/issuer';
+
+/**
+ * A reservation against a user's off-chain balance.
+ *
+ * Lifecycle:
+ *   PENDING ── PointIndexer matches Mint event ──▶ MINTED
+ *      │
+ *      ├── deadline elapsed ────────────────────▶ EXPIRED
+ *      │
+ *      └── tx reverted ─────────────────────────▶ FAILED
+ *
+ * The `(userAddress, status)` composite index keeps the "sum all
+ * PENDING locks" hot path of `lockForMinting()` fast under load.
+ */
+declare class LockedMintEntity {
+    id: string;
+    userAddress: string;
+    tokenAddress: string;
+    amount: bigint;
+    status: MintingStatus;
+    createdAt: Date;
+    expiresAt: Date;
+    txHash?: string | null;
+    /**
+     * ERC-4337 userOpHash returned by the bundler at /claim/submit.
+     * Bound to the lock so `/claim/status` can fall back to the bundler
+     * receipt — required when multiple PENDING locks share the same
+     * `amount` (PointIndexer matches by amount and can pick the wrong
+     * sibling lock).
+     */
+    userOpHash?: string | null;
+}
+
+type PendingCreditStatus = "PENDING" | "RESOLVED" | "EXPIRED";
+/**
+ * Reverse flow — user burns on-chain PT, `BurnIndexer` observes
+ * `Transfer(user → 0x0)`, the credit is settled to the off-chain ledger.
+ *
+ * Lifecycle:
+ *   PENDING ── Burn tx observed by indexer ──▶ RESOLVED
+ *      │
+ *      └── deadline elapsed ────────────────▶ EXPIRED
+ *
+ * The credit is reserved BEFORE the UserOp is submitted so the
+ * indexer can correlate `(user, amount, token)` back to the off-chain
+ * row when the burn lands.
+ */
+declare class PendingCreditEntity {
+    id: string;
+    userAddress: string;
+    tokenAddress: string;
+    amount: bigint;
+    status: PendingCreditStatus;
+    /** On-chain burn tx that settled this credit. Null until indexer resolves. */
+    txHash?: string | null;
+    /** ERC-4337 userOpHash bound at /redeem/submit. See `LockedMintEntity`. */
+    userOpHash?: string | null;
+    createdAt: Date;
+    expiresAt: Date;
+    resolvedAt?: Date | null;
+}
+
+/**
+ * Off-chain point balance per `(userAddress, tokenAddress)`.
+ *
+ * `balance` is the **total** owned; pending reservations live in
+ * `LockedMintEntity`. Available balance = total − sum(PENDING locks)
+ * — `getBalance` in `PostgresPointLedger` does this subtraction
+ * inside a transaction so reads are race-free.
+ *
+ * All amounts are `numeric(78, 0)` for full bigint precision (uint256
+ * fits in 78 decimal digits). TypeORM transforms bigint ↔ string at
+ * the boundary; in JS/TS code we always deal with `bigint`.
+ */
+declare class UserBalanceEntity {
+    userAddress: string;
+    tokenAddress: string;
+    balance: bigint;
+    updatedAt: Date;
+}
+
+/**
+ * Append-only audit trail for every balance mutation. Used for
+ * reconciliation, customer support, and regulatory reporting.
+ *
+ * Sign convention:
+ *   - 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)
+ */
+declare class LedgerJournalEntity {
+    id: string;
+    userAddress: string;
+    tokenAddress: string;
+    delta: bigint;
+    reason: string;
+    txHash?: string | null;
+    createdAt: Date;
+}
+
+/**
+ * Persistent cursor for `PointIndexer` / `BurnIndexer`. Multiple rows
+ * coexist keyed by `id` (e.g. `default` for the mint indexer,
+ * `burn:0x...` for each per-token burn indexer).
+ *
+ * Stores the **next** block to scan, not the last processed one.
+ * Indexer reads on startup and resumes from there.
+ */
+declare class IndexerCursorEntity {
+    id: string;
+    nextBlock: bigint;
+    updatedAt: 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];
+
+export { IndexerCursorEntity, LedgerJournalEntity, LockedMintEntity, PAFI_ENTITIES, PendingCreditEntity, type PendingCreditStatus, UserBalanceEntity };