@wopr-network/platform-core 1.39.0 → 1.39.2

package/dist/billing/crypto/btc/address-gen.js

@@ -56,7 +56,7 @@ function base58encode(data) {
     for (const byte of data) {
         if (byte !== 0)
             break;
-        encoded = "1" + encoded;
+        encoded = `1${encoded}`;
     }
     return encoded;
 }

package/dist/credits/credit-expiry-cron.test.js

@@ -81,4 +81,29 @@ describe("runCreditExpiryCron", () => {
         const balanceAfterSecond = await ledger.balance("tenant-1");
         expect(balanceAfterSecond.toCents()).toBe(balanceAfterFirst.toCents());
     });
+    it("does not return unknown entry type even with expiresAt metadata", async () => {
+        // Simulate a hypothetical new entry type that has expiresAt in metadata.
+        // With the old denylist approach, this would be incorrectly returned.
+        // With the allowlist, it must be excluded.
+        const entry = await ledger.post({
+            entryType: "marketplace_fee",
+            tenantId: "tenant-1",
+            description: "Hypothetical new debit type with expiresAt",
+            metadata: { expiresAt: "2026-01-10T00:00:00Z" },
+            lines: [
+                { accountCode: "2000:tenant-1", amount: Credit.fromCents(100), side: "debit" },
+                { accountCode: "4000", amount: Credit.fromCents(100), side: "credit" },
+            ],
+        });
+        // Give tenant a balance first so it's not filtered by zero-balance
+        await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", {
+            description: "Top-up",
+        });
+        const expired = await ledger.expiredCredits("2026-01-15T00:00:00Z");
+        const ids = expired.map((e) => e.entryId);
+        expect(ids).not.toContain(entry.id);
+        // Full cron should also not touch it
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result.processed).toBe(0);
+    });
 });

package/dist/credits/ledger.d.ts

@@ -99,6 +99,12 @@ export interface DebitOpts {
 export declare const CREDIT_TYPE_ACCOUNT: Record<CreditType, string>;
 /** Maps debit (money-out) types to the credit-side account code. */
 export declare const DEBIT_TYPE_ACCOUNT: Record<DebitType, string>;
+/**
+ * Entry types eligible for credit expiry (allowlist).
+ * Only journal entries with these types can be returned by expiredCredits().
+ * Derived from CreditType — if you add a new CreditType, add it here too.
+ */
+export declare const EXPIRABLE_CREDIT_TYPES: readonly ["signup_grant", "admin_grant", "purchase", "bounty", "referral", "promo", "community_dividend", "affiliate_bonus", "affiliate_match", "correction"];
 export interface SystemAccount {
     code: string;
     name: string;

package/dist/credits/ledger.js

@@ -54,6 +54,23 @@ export const DEBIT_TYPE_ACCOUNT = {
     refund: "1000", // CR cash (money out)
     correction: "5070", // CR expense:correction
 };
+/**
+ * Entry types eligible for credit expiry (allowlist).
+ * Only journal entries with these types can be returned by expiredCredits().
+ * Derived from CreditType — if you add a new CreditType, add it here too.
+ */
+export const EXPIRABLE_CREDIT_TYPES = [
+    "signup_grant",
+    "admin_grant",
+    "purchase",
+    "bounty",
+    "referral",
+    "promo",
+    "community_dividend",
+    "affiliate_bonus",
+    "affiliate_match",
+    "correction",
+];
 export const SYSTEM_ACCOUNTS = [
     // Assets
     { code: "1000", name: "Cash", type: "asset", normalSide: "debit" },
@@ -182,8 +199,11 @@ export class DrizzleLedger {
             });
             // Phase 1: resolve all account IDs with row locks so concurrent transactions
             // are serialized before any balance check or update.
+            // Sort by accountCode to establish a consistent global lock ordering and
+            // prevent deadlocks when concurrent transactions lock overlapping accounts.
+            const sortedLines = [...input.lines].sort((a, b) => a.accountCode < b.accountCode ? -1 : a.accountCode > b.accountCode ? 1 : 0);
             const resolvedLines = [];
-            for (const line of input.lines) {
+            for (const line of sortedLines) {
                 let accountId;
                 if (line.accountCode.startsWith("2000:")) {
                     accountId = await this.ensureTenantAccountLocked(tx, line.accountCode.slice(5));
@@ -476,7 +496,7 @@ export class DrizzleLedger {
 				)`,
         })
             .from(journalEntries)
-            .where(and(isNotNull(sql `${journalEntries.metadata}->>'expiresAt'`), sql `(${journalEntries.metadata}->>'expiresAt') <= ${now}`, sql `${journalEntries.entryType} NOT IN ('credit_expiry', 'bot_runtime', 'adapter_usage', 'addon', 'refund')`));
+            .where(and(isNotNull(sql `${journalEntries.metadata}->>'expiresAt'`), sql `(${journalEntries.metadata}->>'expiresAt') <= ${now}`, sql `${journalEntries.entryType} IN (${sql.join(EXPIRABLE_CREDIT_TYPES.map((t) => sql `${t}`), sql `, `)})`));
         const result = [];
         for (const row of rows) {
             if (!row.amount)

package/dist/credits/ledger.test.js

@@ -111,6 +111,27 @@ describe("DrizzleLedger", () => {
             });
             expect(entry.lines).toHaveLength(3);
         });
+        it("acquires locks in consistent order regardless of input line order", async () => {
+            // Post a 3-line entry with accounts in descending order.
+            // If lock ordering works, this should succeed without deadlock
+            // even when concurrent transactions use a different line order.
+            const entry = await ledger.post({
+                entryType: "correction",
+                tenantId: "t1",
+                lines: [
+                    { accountCode: "5070", amount: Credit.fromCents(500), side: "debit" },
+                    { accountCode: "2000:t1", amount: Credit.fromCents(200), side: "credit" },
+                    { accountCode: "1000", amount: Credit.fromCents(300), side: "credit" },
+                ],
+            });
+            // Entry should succeed and contain all 3 lines
+            expect(entry.lines).toHaveLength(3);
+            // Verify balances are correct (lock order doesn't affect correctness)
+            const cashBal = await ledger.accountBalance("1000");
+            expect(cashBal.toCentsRounded()).toBe(-300); // credit side on debit-normal = negative
+            const tb = await ledger.trialBalance();
+            expect(tb.balanced).toBe(true);
+        });
     });
     // -----------------------------------------------------------------------
     // credit() — convenience
@@ -342,6 +363,61 @@ describe("DrizzleLedger", () => {
         });
     });
     // -----------------------------------------------------------------------
+    // expiredCredits()
+    // -----------------------------------------------------------------------
+    describe("expiredCredits()", () => {
+        it("returns entries with expirable types whose expiresAt has passed", async () => {
+            // Post a signup_grant (in EXPIRABLE_CREDIT_TYPES) with an expiresAt in the past
+            await ledger.credit("t1", Credit.fromCents(100), "signup_grant", {
+                expiresAt: "2020-01-01T00:00:00Z",
+            });
+            const expired = await ledger.expiredCredits(new Date().toISOString());
+            expect(expired).toHaveLength(1);
+            expect(expired[0].tenantId).toBe("t1");
+            expect(expired[0].amount.toCentsRounded()).toBe(100);
+        });
+        it("excludes entries whose type is not in EXPIRABLE_CREDIT_TYPES", async () => {
+            // Post a credit-side entry on the liability account with an unknown entry type
+            // so the liability credit line is present (the subquery finds an amount) but
+            // the allowlist filter must exclude it.
+            await ledger.post({
+                entryType: "marketplace_fee", // NOT in EXPIRABLE_CREDIT_TYPES
+                tenantId: "t1",
+                metadata: { expiresAt: "2020-01-01T00:00:00Z" },
+                lines: [
+                    { accountCode: "1000", amount: Credit.fromCents(100), side: "debit" },
+                    { accountCode: "2000:t1", amount: Credit.fromCents(100), side: "credit" },
+                ],
+            });
+            const expired = await ledger.expiredCredits(new Date().toISOString());
+            expect(expired).toHaveLength(0);
+        });
+        it("excludes entries whose expiresAt is in the future", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+                expiresAt: "2099-01-01T00:00:00Z",
+            });
+            const expired = await ledger.expiredCredits(new Date().toISOString());
+            expect(expired).toHaveLength(0);
+        });
+        it("excludes entries already clawed back (idempotency)", async () => {
+            const entry = await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+                expiresAt: "2020-01-01T00:00:00Z",
+            });
+            // Simulate a prior expiry entry by posting with the expiry referenceId
+            await ledger.post({
+                entryType: "credit_expiry",
+                tenantId: "t1",
+                referenceId: `expiry:${entry.id}`,
+                lines: [
+                    { accountCode: "2000:t1", amount: Credit.fromCents(100), side: "debit" },
+                    { accountCode: "4060", amount: Credit.fromCents(100), side: "credit" },
+                ],
+            });
+            const expired = await ledger.expiredCredits(new Date().toISOString());
+            expect(expired).toHaveLength(0);
+        });
+    });
+    // -----------------------------------------------------------------------
     // memberUsage()
     // -----------------------------------------------------------------------
     describe("memberUsage()", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.39.0",
+  "version": "1.39.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/billing/crypto/btc/address-gen.ts

@@ -71,7 +71,7 @@ function base58encode(data: Uint8Array): string {
   }
   for (const byte of data) {
     if (byte !== 0) break;
-    encoded = "1" + encoded;
+    encoded = `1${encoded}`;
   }
   return encoded;
 }

package/src/credits/credit-expiry-cron.test.ts

@@ -103,4 +103,33 @@ describe("runCreditExpiryCron", () => {
     const balanceAfterSecond = await ledger.balance("tenant-1");
     expect(balanceAfterSecond.toCents()).toBe(balanceAfterFirst.toCents());
   });
+
+  it("does not return unknown entry type even with expiresAt metadata", async () => {
+    // Simulate a hypothetical new entry type that has expiresAt in metadata.
+    // With the old denylist approach, this would be incorrectly returned.
+    // With the allowlist, it must be excluded.
+    const entry = await ledger.post({
+      entryType: "marketplace_fee",
+      tenantId: "tenant-1",
+      description: "Hypothetical new debit type with expiresAt",
+      metadata: { expiresAt: "2026-01-10T00:00:00Z" },
+      lines: [
+        { accountCode: "2000:tenant-1", amount: Credit.fromCents(100), side: "debit" },
+        { accountCode: "4000", amount: Credit.fromCents(100), side: "credit" },
+      ],
+    });
+
+    // Give tenant a balance first so it's not filtered by zero-balance
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", {
+      description: "Top-up",
+    });
+
+    const expired = await ledger.expiredCredits("2026-01-15T00:00:00Z");
+    const ids = expired.map((e) => e.entryId);
+    expect(ids).not.toContain(entry.id);
+
+    // Full cron should also not touch it
+    const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+    expect(result.processed).toBe(0);
+  });
 });

package/src/credits/ledger.test.ts

@@ -139,6 +139,31 @@ describe("DrizzleLedger", () => {
 
       expect(entry.lines).toHaveLength(3);
     });
+
+    it("acquires locks in consistent order regardless of input line order", async () => {
+      // Post a 3-line entry with accounts in descending order.
+      // If lock ordering works, this should succeed without deadlock
+      // even when concurrent transactions use a different line order.
+      const entry = await ledger.post({
+        entryType: "correction",
+        tenantId: "t1",
+        lines: [
+          { accountCode: "5070", amount: Credit.fromCents(500), side: "debit" },
+          { accountCode: "2000:t1", amount: Credit.fromCents(200), side: "credit" },
+          { accountCode: "1000", amount: Credit.fromCents(300), side: "credit" },
+        ],
+      });
+
+      // Entry should succeed and contain all 3 lines
+      expect(entry.lines).toHaveLength(3);
+
+      // Verify balances are correct (lock order doesn't affect correctness)
+      const cashBal = await ledger.accountBalance("1000");
+      expect(cashBal.toCentsRounded()).toBe(-300); // credit side on debit-normal = negative
+
+      const tb = await ledger.trialBalance();
+      expect(tb.balanced).toBe(true);
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -424,6 +449,71 @@ describe("DrizzleLedger", () => {
     });
   });
 
+  // -----------------------------------------------------------------------
+  // expiredCredits()
+  // -----------------------------------------------------------------------
+
+  describe("expiredCredits()", () => {
+    it("returns entries with expirable types whose expiresAt has passed", async () => {
+      // Post a signup_grant (in EXPIRABLE_CREDIT_TYPES) with an expiresAt in the past
+      await ledger.credit("t1", Credit.fromCents(100), "signup_grant", {
+        expiresAt: "2020-01-01T00:00:00Z",
+      });
+
+      const expired = await ledger.expiredCredits(new Date().toISOString());
+      expect(expired).toHaveLength(1);
+      expect(expired[0].tenantId).toBe("t1");
+      expect(expired[0].amount.toCentsRounded()).toBe(100);
+    });
+
+    it("excludes entries whose type is not in EXPIRABLE_CREDIT_TYPES", async () => {
+      // Post a credit-side entry on the liability account with an unknown entry type
+      // so the liability credit line is present (the subquery finds an amount) but
+      // the allowlist filter must exclude it.
+      await ledger.post({
+        entryType: "marketplace_fee", // NOT in EXPIRABLE_CREDIT_TYPES
+        tenantId: "t1",
+        metadata: { expiresAt: "2020-01-01T00:00:00Z" },
+        lines: [
+          { accountCode: "1000", amount: Credit.fromCents(100), side: "debit" },
+          { accountCode: "2000:t1", amount: Credit.fromCents(100), side: "credit" },
+        ],
+      });
+
+      const expired = await ledger.expiredCredits(new Date().toISOString());
+      expect(expired).toHaveLength(0);
+    });
+
+    it("excludes entries whose expiresAt is in the future", async () => {
+      await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+        expiresAt: "2099-01-01T00:00:00Z",
+      });
+
+      const expired = await ledger.expiredCredits(new Date().toISOString());
+      expect(expired).toHaveLength(0);
+    });
+
+    it("excludes entries already clawed back (idempotency)", async () => {
+      const entry = await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+        expiresAt: "2020-01-01T00:00:00Z",
+      });
+
+      // Simulate a prior expiry entry by posting with the expiry referenceId
+      await ledger.post({
+        entryType: "credit_expiry",
+        tenantId: "t1",
+        referenceId: `expiry:${entry.id}`,
+        lines: [
+          { accountCode: "2000:t1", amount: Credit.fromCents(100), side: "debit" },
+          { accountCode: "4060", amount: Credit.fromCents(100), side: "credit" },
+        ],
+      });
+
+      const expired = await ledger.expiredCredits(new Date().toISOString());
+      expect(expired).toHaveLength(0);
+    });
+  });
+
   // -----------------------------------------------------------------------
   // memberUsage()
   // -----------------------------------------------------------------------

package/src/credits/ledger.ts

@@ -172,6 +172,24 @@ export const DEBIT_TYPE_ACCOUNT: Record<DebitType, string> = {
   correction: "5070", // CR expense:correction
 };
 
+/**
+ * Entry types eligible for credit expiry (allowlist).
+ * Only journal entries with these types can be returned by expiredCredits().
+ * Derived from CreditType — if you add a new CreditType, add it here too.
+ */
+export const EXPIRABLE_CREDIT_TYPES = [
+  "signup_grant",
+  "admin_grant",
+  "purchase",
+  "bounty",
+  "referral",
+  "promo",
+  "community_dividend",
+  "affiliate_bonus",
+  "affiliate_match",
+  "correction",
+] as const satisfies readonly CreditType[];
+
 // ---------------------------------------------------------------------------
 // System account seeds
 // ---------------------------------------------------------------------------
@@ -387,8 +405,13 @@ export class DrizzleLedger implements ILedger {
 
       // Phase 1: resolve all account IDs with row locks so concurrent transactions
       // are serialized before any balance check or update.
+      // Sort by accountCode to establish a consistent global lock ordering and
+      // prevent deadlocks when concurrent transactions lock overlapping accounts.
+      const sortedLines = [...input.lines].sort((a, b) =>
+        a.accountCode < b.accountCode ? -1 : a.accountCode > b.accountCode ? 1 : 0,
+      );
       const resolvedLines: Array<JournalLine & { accountId: string }> = [];
-      for (const line of input.lines) {
+      for (const line of sortedLines) {
         let accountId: string;
         if (line.accountCode.startsWith("2000:")) {
           accountId = await this.ensureTenantAccountLocked(tx, line.accountCode.slice(5));
@@ -745,7 +768,10 @@ export class DrizzleLedger implements ILedger {
         and(
           isNotNull(sql`${journalEntries.metadata}->>'expiresAt'`),
           sql`(${journalEntries.metadata}->>'expiresAt') <= ${now}`,
-          sql`${journalEntries.entryType} NOT IN ('credit_expiry', 'bot_runtime', 'adapter_usage', 'addon', 'refund')`,
+          sql`${journalEntries.entryType} IN (${sql.join(
+            EXPIRABLE_CREDIT_TYPES.map((t) => sql`${t}`),
+            sql`, `,
+          )})`,
         ),
       );