@pafi-dev/issuer 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -18,6 +18,12 @@ interface LockedMintRequest {
     lockId: string;
     userAddress: Address;
     amount: bigint;
+    /**
+     * Which PointToken this lock belongs to. Added in 0.2.0 for multi-token
+     * issuer support. Optional for backward compat with 0.1.x ledgers —
+     * single-token consumers can ignore it.
+     */
+    tokenAddress?: Address;
     /** Lifecycle status */
     status: MintingStatus;
     /** When the lock was created (epoch ms) */
@@ -33,20 +39,28 @@ interface LockedMintRequest {
  *
  * Issuers replace the in-memory default with their own database-backed
  * implementation (Postgres, Redis, etc.).
+ *
+ * **Multi-token support (0.2.0):**
+ * Every mutating method accepts an optional `tokenAddress` parameter so
+ * balances can be scoped per `(user, token)`. Single-token issuers can
+ * ignore the parameter entirely — legacy 0.1.x implementations remain
+ * compatible. Multi-token issuers must persist + query balances keyed by
+ * `(userAddress, tokenAddress)`.
  */
 interface IPointLedger {
     /** Get a user's available off-chain point balance (excluding locked). */
-    getBalance(userAddress: Address): Promise<bigint>;
+    getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
     /**
      * Lock an amount for a pending mint request. Locked amounts are reserved
      * but not yet deducted; they protect against double-spend during the
      * EIP-712 validity window.
      *
      * @param lockDurationMs how long the lock should be held before auto-expiry
+     * @param tokenAddress which PointToken this lock is for (0.2.0+)
      * @returns lockId — opaque handle used by `releaseLock` / `updateMintStatus`
      * @throws if the user's available balance is below `amount`
      */
-    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number): Promise<string>;
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
     /** Release a previously created lock (e.g. on tx failure / cancel). */
     releaseLock(lockId: string): Promise<void>;
     /**
@@ -54,11 +68,11 @@ interface IPointLedger {
      * mint has been observed by the indexer. Should also resolve any matching
      * lock so the funds aren't double-counted.
      */
-    deductBalance(userAddress: Address, amount: bigint, txHash: Hex): Promise<void>;
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
     /** Credit points to a user's balance (e.g. from merchant activity). */
-    creditBalance(userAddress: Address, amount: bigint, reason: string): Promise<void>;
+    creditBalance(userAddress: Address, amount: bigint, reason: string, tokenAddress?: Address): Promise<void>;
     /** List currently-pending locked mint requests for a user. */
-    getLockedRequests(userAddress: Address): Promise<LockedMintRequest[]>;
+    getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
     /**
      * Transition a lock to a new lifecycle status. The on-chain tx hash is
      * supplied when the status is `MINTED`.
@@ -75,6 +89,10 @@ interface IPointLedger {
  * Concurrency model: single-process, single-threaded (Node.js event loop).
  * The lock check + insert is atomic within a tick because no awaits sit
  * between balance read and lock write.
+ *
+ * **Multi-token (0.2.0):** Balances are keyed by `(user, token)`. If callers
+ * omit `tokenAddress`, the literal string "default" is used — that keeps
+ * single-token usage working exactly like 0.1.x.
  */
 declare class MemoryPointLedger implements IPointLedger {
     private balances;
@@ -84,12 +102,12 @@ declare class MemoryPointLedger implements IPointLedger {
     constructor(opts?: {
         now?: () => number;
     });
-    getBalance(userAddress: Address): Promise<bigint>;
-    getLockedRequests(userAddress: Address): Promise<LockedMintRequest[]>;
-    creditBalance(userAddress: Address, amount: bigint, _reason: string): Promise<void>;
-    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number): Promise<string>;
+    getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
+    getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
+    creditBalance(userAddress: Address, amount: bigint, _reason: string, tokenAddress?: Address): Promise<void>;
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
     releaseLock(lockId: string): Promise<void>;
-    deductBalance(userAddress: Address, amount: bigint, txHash: Hex): Promise<void>;
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
     updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
     /**
      * Auto-expire any PENDING lock past its expiry. Called lazily on every
@@ -927,6 +945,25 @@ interface ApiUserRequest {
 interface ApiUserResponse {
     mintRequestNonce: bigint;
     receiverConsentNonce: bigint;
+    /**
+     * Off-chain point balance from the issuer's ledger (excludes PENDING locks).
+     * This is what the user can claim into on-chain PT via `/claim`.
+     */
+    offChainBalance: bigint;
+    /**
+     * On-chain ERC-20 balance from `PointToken.balanceOf(user)`.
+     * Points the user has already claimed but hasn't swapped or redeemed.
+     */
+    onChainBalance: bigint;
+    /**
+     * Sum of off-chain + on-chain balance. FE renders this as a single
+     * "your points" number, per the unified-balance UX spec.
+     */
+    totalBalance: bigint;
+    /**
+     * @deprecated use `offChainBalance` instead. Kept for backward compatibility
+     * — will be removed in 0.2.0.
+     */
     balance: bigint;
     isMinter: boolean;
 }
@@ -983,7 +1020,16 @@ interface IssuerApiHandlersConfig {
     ledger: IPointLedger;
     /** Used by `handleUser` to read on-chain nonces and minter status. */
     provider: PublicClient;
-    pointTokenAddress: Address;
+    /**
+     * Legacy single-token config. Prefer `pointTokenAddresses` for multi-token
+     * issuers (0.2.0+).
+     */
+    pointTokenAddress?: Address;
+    /**
+     * All supported PointToken addresses. Handlers accept any address in this
+     * list; others are rejected with "unsupported pointToken".
+     */
+    pointTokenAddresses?: Address[];
     chainId: number;
     contracts: ApiConfigResponse["contracts"];
     /** Required by `handleGasFee`; omit to disable the endpoint. */
@@ -1008,7 +1054,15 @@ declare class IssuerApiHandlers {
     private readonly gateway;
     private readonly ledger;
     private readonly provider;
-    private readonly pointTokenAddress;
+    /**
+     * Set of supported PointToken addresses (checksum-normalized). Handlers
+     * validate the request's `pointTokenAddress` against this set.
+     */
+    private readonly supportedTokens;
+    /** First supported token — used as default when a handler doesn't
+     * receive a `pointTokenAddress` in the request (shouldn't happen in
+     * practice, but keeps type-narrowing happy). */
+    private readonly defaultToken;
     private readonly chainId;
     private readonly contracts;
     private readonly feeManager?;
@@ -1199,11 +1253,24 @@ declare function createSubgraphNativeUsdtQuoter(config: SubgraphNativeUsdtQuoter
  * falls back to the in-memory dev defaults — that makes the happy path
  * a single-call wire-up while still letting production issuers plug in
  * their own ledger, session store, policy engine, and KMS signer.
+ *
+ * **Multi-token (0.2.0):** Pass `pointTokenAddresses: Address[]` to
+ * support multiple PointTokens under a single issuer backend. Legacy
+ * `pointTokenAddress: Address` still works for single-token deployments.
+ * When both are provided, `pointTokenAddresses` takes precedence.
  */
 interface IssuerServiceConfig {
     chainId: number;
-    /** Address of the deployed PointToken (one per issuer instance). */
-    pointTokenAddress: Address;
+    /**
+     * Address of the deployed PointToken. Legacy single-token shortcut;
+     * prefer `pointTokenAddresses` for multi-token issuers.
+     */
+    pointTokenAddress?: Address;
+    /**
+     * All PointToken addresses this issuer supports. Takes precedence over
+     * `pointTokenAddress`. Factory creates one `PointIndexer` per address.
+     */
+    pointTokenAddresses?: Address[];
     /** Address of the deployed Relay contract. */
     relayAddress: Address;
     /**
@@ -1276,6 +1343,16 @@ interface IssuerService {
     relayService: RelayService;
     feeManager: FeeManager | undefined;
     gateway: MintingGateway;
+    /**
+     * All indexers keyed by PointToken address. For multi-token issuers there
+     * is one per configured token. Single-token issuers will find one entry.
+     */
+    indexers: Map<Address, PointIndexer>;
+    /**
+     * First indexer. Kept for backward compat with 0.1.x callers that
+     * expected `service.indexer` to be a single instance.
+     * @deprecated use `indexers.get(tokenAddress)` for multi-token.
+     */
     indexer: PointIndexer;
     handlers: IssuerApiHandlers;
 }
@@ -1293,7 +1370,7 @@ interface IssuerService {
  *  - `indexer.autoStart` → false
  *
  * Throws synchronously if any required field (`signer`, `provider`,
- * `operatorWallet`, `auth.jwtSecret`, `pointTokenAddress`, …) is missing.
+ * `operatorWallet`, `auth.jwtSecret`, at least one point token) is missing.
  */
 declare function createIssuerService(config: IssuerServiceConfig): IssuerService;
 

package/dist/index.d.ts

@@ -18,6 +18,12 @@ interface LockedMintRequest {
     lockId: string;
     userAddress: Address;
     amount: bigint;
+    /**
+     * Which PointToken this lock belongs to. Added in 0.2.0 for multi-token
+     * issuer support. Optional for backward compat with 0.1.x ledgers —
+     * single-token consumers can ignore it.
+     */
+    tokenAddress?: Address;
     /** Lifecycle status */
     status: MintingStatus;
     /** When the lock was created (epoch ms) */
@@ -33,20 +39,28 @@ interface LockedMintRequest {
  *
  * Issuers replace the in-memory default with their own database-backed
  * implementation (Postgres, Redis, etc.).
+ *
+ * **Multi-token support (0.2.0):**
+ * Every mutating method accepts an optional `tokenAddress` parameter so
+ * balances can be scoped per `(user, token)`. Single-token issuers can
+ * ignore the parameter entirely — legacy 0.1.x implementations remain
+ * compatible. Multi-token issuers must persist + query balances keyed by
+ * `(userAddress, tokenAddress)`.
  */
 interface IPointLedger {
     /** Get a user's available off-chain point balance (excluding locked). */
-    getBalance(userAddress: Address): Promise<bigint>;
+    getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
     /**
      * Lock an amount for a pending mint request. Locked amounts are reserved
      * but not yet deducted; they protect against double-spend during the
      * EIP-712 validity window.
      *
      * @param lockDurationMs how long the lock should be held before auto-expiry
+     * @param tokenAddress which PointToken this lock is for (0.2.0+)
      * @returns lockId — opaque handle used by `releaseLock` / `updateMintStatus`
      * @throws if the user's available balance is below `amount`
      */
-    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number): Promise<string>;
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
     /** Release a previously created lock (e.g. on tx failure / cancel). */
     releaseLock(lockId: string): Promise<void>;
     /**
@@ -54,11 +68,11 @@ interface IPointLedger {
      * mint has been observed by the indexer. Should also resolve any matching
      * lock so the funds aren't double-counted.
      */
-    deductBalance(userAddress: Address, amount: bigint, txHash: Hex): Promise<void>;
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
     /** Credit points to a user's balance (e.g. from merchant activity). */
-    creditBalance(userAddress: Address, amount: bigint, reason: string): Promise<void>;
+    creditBalance(userAddress: Address, amount: bigint, reason: string, tokenAddress?: Address): Promise<void>;
     /** List currently-pending locked mint requests for a user. */
-    getLockedRequests(userAddress: Address): Promise<LockedMintRequest[]>;
+    getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
     /**
      * Transition a lock to a new lifecycle status. The on-chain tx hash is
      * supplied when the status is `MINTED`.
@@ -75,6 +89,10 @@ interface IPointLedger {
  * Concurrency model: single-process, single-threaded (Node.js event loop).
  * The lock check + insert is atomic within a tick because no awaits sit
  * between balance read and lock write.
+ *
+ * **Multi-token (0.2.0):** Balances are keyed by `(user, token)`. If callers
+ * omit `tokenAddress`, the literal string "default" is used — that keeps
+ * single-token usage working exactly like 0.1.x.
  */
 declare class MemoryPointLedger implements IPointLedger {
     private balances;
@@ -84,12 +102,12 @@ declare class MemoryPointLedger implements IPointLedger {
     constructor(opts?: {
         now?: () => number;
     });
-    getBalance(userAddress: Address): Promise<bigint>;
-    getLockedRequests(userAddress: Address): Promise<LockedMintRequest[]>;
-    creditBalance(userAddress: Address, amount: bigint, _reason: string): Promise<void>;
-    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number): Promise<string>;
+    getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
+    getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
+    creditBalance(userAddress: Address, amount: bigint, _reason: string, tokenAddress?: Address): Promise<void>;
+    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
     releaseLock(lockId: string): Promise<void>;
-    deductBalance(userAddress: Address, amount: bigint, txHash: Hex): Promise<void>;
+    deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
     updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
     /**
      * Auto-expire any PENDING lock past its expiry. Called lazily on every
@@ -927,6 +945,25 @@ interface ApiUserRequest {
 interface ApiUserResponse {
     mintRequestNonce: bigint;
     receiverConsentNonce: bigint;
+    /**
+     * Off-chain point balance from the issuer's ledger (excludes PENDING locks).
+     * This is what the user can claim into on-chain PT via `/claim`.
+     */
+    offChainBalance: bigint;
+    /**
+     * On-chain ERC-20 balance from `PointToken.balanceOf(user)`.
+     * Points the user has already claimed but hasn't swapped or redeemed.
+     */
+    onChainBalance: bigint;
+    /**
+     * Sum of off-chain + on-chain balance. FE renders this as a single
+     * "your points" number, per the unified-balance UX spec.
+     */
+    totalBalance: bigint;
+    /**
+     * @deprecated use `offChainBalance` instead. Kept for backward compatibility
+     * — will be removed in 0.2.0.
+     */
     balance: bigint;
     isMinter: boolean;
 }
@@ -983,7 +1020,16 @@ interface IssuerApiHandlersConfig {
     ledger: IPointLedger;
     /** Used by `handleUser` to read on-chain nonces and minter status. */
     provider: PublicClient;
-    pointTokenAddress: Address;
+    /**
+     * Legacy single-token config. Prefer `pointTokenAddresses` for multi-token
+     * issuers (0.2.0+).
+     */
+    pointTokenAddress?: Address;
+    /**
+     * All supported PointToken addresses. Handlers accept any address in this
+     * list; others are rejected with "unsupported pointToken".
+     */
+    pointTokenAddresses?: Address[];
     chainId: number;
     contracts: ApiConfigResponse["contracts"];
     /** Required by `handleGasFee`; omit to disable the endpoint. */
@@ -1008,7 +1054,15 @@ declare class IssuerApiHandlers {
     private readonly gateway;
     private readonly ledger;
     private readonly provider;
-    private readonly pointTokenAddress;
+    /**
+     * Set of supported PointToken addresses (checksum-normalized). Handlers
+     * validate the request's `pointTokenAddress` against this set.
+     */
+    private readonly supportedTokens;
+    /** First supported token — used as default when a handler doesn't
+     * receive a `pointTokenAddress` in the request (shouldn't happen in
+     * practice, but keeps type-narrowing happy). */
+    private readonly defaultToken;
     private readonly chainId;
     private readonly contracts;
     private readonly feeManager?;
@@ -1199,11 +1253,24 @@ declare function createSubgraphNativeUsdtQuoter(config: SubgraphNativeUsdtQuoter
  * falls back to the in-memory dev defaults — that makes the happy path
  * a single-call wire-up while still letting production issuers plug in
  * their own ledger, session store, policy engine, and KMS signer.
+ *
+ * **Multi-token (0.2.0):** Pass `pointTokenAddresses: Address[]` to
+ * support multiple PointTokens under a single issuer backend. Legacy
+ * `pointTokenAddress: Address` still works for single-token deployments.
+ * When both are provided, `pointTokenAddresses` takes precedence.
  */
 interface IssuerServiceConfig {
     chainId: number;
-    /** Address of the deployed PointToken (one per issuer instance). */
-    pointTokenAddress: Address;
+    /**
+     * Address of the deployed PointToken. Legacy single-token shortcut;
+     * prefer `pointTokenAddresses` for multi-token issuers.
+     */
+    pointTokenAddress?: Address;
+    /**
+     * All PointToken addresses this issuer supports. Takes precedence over
+     * `pointTokenAddress`. Factory creates one `PointIndexer` per address.
+     */
+    pointTokenAddresses?: Address[];
     /** Address of the deployed Relay contract. */
     relayAddress: Address;
     /**
@@ -1276,6 +1343,16 @@ interface IssuerService {
     relayService: RelayService;
     feeManager: FeeManager | undefined;
     gateway: MintingGateway;
+    /**
+     * All indexers keyed by PointToken address. For multi-token issuers there
+     * is one per configured token. Single-token issuers will find one entry.
+     */
+    indexers: Map<Address, PointIndexer>;
+    /**
+     * First indexer. Kept for backward compat with 0.1.x callers that
+     * expected `service.indexer` to be a single instance.
+     * @deprecated use `indexers.get(tokenAddress)` for multi-token.
+     */
     indexer: PointIndexer;
     handlers: IssuerApiHandlers;
 }
@@ -1293,7 +1370,7 @@ interface IssuerService {
  *  - `indexer.autoStart` → false
  *
  * Throws synchronously if any required field (`signer`, `provider`,
- * `operatorWallet`, `auth.jwtSecret`, `pointTokenAddress`, …) is missing.
+ * `operatorWallet`, `auth.jwtSecret`, at least one point token) is missing.
  */
 declare function createIssuerService(config: IssuerServiceConfig): IssuerService;