@wopr-network/platform-core 1.15.0 → 1.16.0

package/drizzle/migrations/0005_stablecoin_columns.sql

@@ -0,0 +1,7 @@
+ALTER TABLE "crypto_charges" ADD COLUMN "chain" text;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "token" text;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "deposit_address" text;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "derivation_index" integer;--> statement-breakpoint
+CREATE INDEX "idx_crypto_charges_deposit_address" ON "crypto_charges" USING btree ("deposit_address");--> statement-breakpoint
+CREATE UNIQUE INDEX "uq_crypto_charges_deposit_address" ON "crypto_charges" ("deposit_address") WHERE "deposit_address" IS NOT NULL;--> statement-breakpoint
+CREATE UNIQUE INDEX "uq_crypto_charges_derivation_index" ON "crypto_charges" ("derivation_index") WHERE "derivation_index" IS NOT NULL;

package/drizzle/migrations/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1741968000000,
       "tag": "0004_crypto_charges",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1742054400000,
+      "tag": "0005_stablecoin_columns",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -128,7 +128,10 @@
   },
   "packageManager": "pnpm@10.31.0",
   "dependencies": {
+    "@scure/base": "^2.0.0",
+    "@scure/bip32": "^2.0.1",
     "js-yaml": "^4.1.1",
+    "viem": "^2.47.4",
     "yaml": "^2.8.2"
   }
 }

package/src/billing/crypto/charge-store.test.ts

@@ -78,4 +78,65 @@ describe("CryptoChargeRepository", () => {
     await store.markCredited("inv-006");
     expect(await store.isCredited("inv-006")).toBe(true);
   });
+
+  describe("stablecoin charges", () => {
+    it("creates a stablecoin charge with chain/token/address", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "sc:base:usdc:0x123",
+        tenantId: "tenant-1",
+        amountUsdCents: 1000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xabc123",
+        derivationIndex: 42,
+      });
+      const charge = await store.getByReferenceId("sc:base:usdc:0x123");
+      expect(charge).not.toBeNull();
+      expect(charge?.chain).toBe("base");
+      expect(charge?.token).toBe("USDC");
+      expect(charge?.depositAddress).toBe("0xabc123");
+      expect(charge?.derivationIndex).toBe(42);
+      expect(charge?.amountUsdCents).toBe(1000);
+    });
+
+    it("looks up charge by deposit address", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "sc:base:usdc:0x456",
+        tenantId: "tenant-2",
+        amountUsdCents: 5000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xdef456",
+        derivationIndex: 43,
+      });
+      const charge = await store.getByDepositAddress("0xdef456");
+      expect(charge).not.toBeNull();
+      expect(charge?.tenantId).toBe("tenant-2");
+      expect(charge?.amountUsdCents).toBe(5000);
+    });
+
+    it("returns null for unknown deposit address", async () => {
+      const charge = await store.getByDepositAddress("0xnonexistent");
+      expect(charge).toBeNull();
+    });
+
+    it("gets next derivation index (0 when empty)", async () => {
+      const idx = await store.getNextDerivationIndex();
+      expect(idx).toBe(0);
+    });
+
+    it("gets next derivation index (max + 1)", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "sc:idx-test",
+        tenantId: "t",
+        amountUsdCents: 100,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xidxtest",
+        derivationIndex: 5,
+      });
+      const idx = await store.getNextDerivationIndex();
+      expect(idx).toBe(6);
+    });
+  });
 });

package/src/billing/crypto/charge-store.ts

@@ -13,6 +13,20 @@ export interface CryptoChargeRecord {
   creditedAt: string | null;
   createdAt: string;
   updatedAt: string;
+  chain: string | null;
+  token: string | null;
+  depositAddress: string | null;
+  derivationIndex: number | null;
+}
+
+export interface StablecoinChargeInput {
+  referenceId: string;
+  tenantId: string;
+  amountUsdCents: number;
+  chain: string;
+  token: string;
+  depositAddress: string;
+  derivationIndex: number;
 }
 
 export interface ICryptoChargeRepository {
@@ -26,6 +40,9 @@ export interface ICryptoChargeRepository {
   ): Promise<void>;
   markCredited(referenceId: string): Promise<void>;
   isCredited(referenceId: string): Promise<boolean>;
+  createStablecoinCharge(input: StablecoinChargeInput): Promise<void>;
+  getByDepositAddress(address: string): Promise<CryptoChargeRecord | null>;
+  getNextDerivationIndex(): Promise<number>;
 }
 
 /**
@@ -55,6 +72,10 @@ export class DrizzleCryptoChargeRepository implements ICryptoChargeRepository {
   async getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null> {
     const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.referenceId, referenceId)))[0];
     if (!row) return null;
+    return this.toRecord(row);
+  }
+
+  private toRecord(row: typeof cryptoCharges.$inferSelect): CryptoChargeRecord {
     return {
       referenceId: row.referenceId,
       tenantId: row.tenantId,
@@ -65,6 +86,10 @@ export class DrizzleCryptoChargeRepository implements ICryptoChargeRepository {
       creditedAt: row.creditedAt ?? null,
       createdAt: row.createdAt,
       updatedAt: row.updatedAt,
+      chain: row.chain ?? null,
+      token: row.token ?? null,
+      depositAddress: row.depositAddress ?? null,
+      derivationIndex: row.derivationIndex ?? null,
     };
   }
 
@@ -107,6 +132,35 @@ export class DrizzleCryptoChargeRepository implements ICryptoChargeRepository {
     )[0];
     return row?.creditedAt != null;
   }
+
+  /** Create a stablecoin charge with chain/token/deposit address. */
+  async createStablecoinCharge(input: StablecoinChargeInput): Promise<void> {
+    await this.db.insert(cryptoCharges).values({
+      referenceId: input.referenceId,
+      tenantId: input.tenantId,
+      amountUsdCents: input.amountUsdCents,
+      status: "New",
+      chain: input.chain,
+      token: input.token,
+      depositAddress: input.depositAddress,
+      derivationIndex: input.derivationIndex,
+    });
+  }
+
+  /** Look up a charge by its deposit address. */
+  async getByDepositAddress(address: string): Promise<CryptoChargeRecord | null> {
+    const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.depositAddress, address)))[0];
+    if (!row) return null;
+    return this.toRecord(row);
+  }
+
+  /** Get the next available HD derivation index (max + 1, or 0 if empty). */
+  async getNextDerivationIndex(): Promise<number> {
+    const result = await this.db
+      .select({ maxIdx: sql<number>`coalesce(max(${cryptoCharges.derivationIndex}), -1)` })
+      .from(cryptoCharges);
+    return (result[0]?.maxIdx ?? -1) + 1;
+  }
 }
 
 export { DrizzleCryptoChargeRepository as CryptoChargeRepository };

package/src/billing/crypto/evm/__tests__/address-gen.test.ts

@@ -0,0 +1,63 @@
+import { HDKey } from "@scure/bip32";
+import { describe, expect, it } from "vitest";
+import { deriveDepositAddress, isValidXpub } from "../address-gen.js";
+
+// Generate a test xpub deterministically
+function makeTestXpub(): string {
+  const seed = new Uint8Array(32);
+  seed[0] = 1; // deterministic seed
+  const master = HDKey.fromMasterSeed(seed);
+  // Derive to m/44'/60'/0' (Ethereum BIP-44 path)
+  const account = master.derive("m/44'/60'/0'");
+  return account.publicExtendedKey;
+}
+
+const TEST_XPUB = makeTestXpub();
+
+describe("deriveDepositAddress", () => {
+  it("derives a valid Ethereum address", () => {
+    const addr = deriveDepositAddress(TEST_XPUB, 0);
+    expect(addr).toMatch(/^0x[0-9a-fA-F]{40}$/);
+  });
+
+  it("derives different addresses for different indices", () => {
+    const addr0 = deriveDepositAddress(TEST_XPUB, 0);
+    const addr1 = deriveDepositAddress(TEST_XPUB, 1);
+    expect(addr0).not.toBe(addr1);
+  });
+
+  it("is deterministic — same xpub + index = same address", () => {
+    const a = deriveDepositAddress(TEST_XPUB, 42);
+    const b = deriveDepositAddress(TEST_XPUB, 42);
+    expect(a).toBe(b);
+  });
+
+  it("returns checksummed address", () => {
+    const addr = deriveDepositAddress(TEST_XPUB, 0);
+    // Must be a valid 0x-prefixed address
+    expect(addr).toMatch(/^0x[0-9a-fA-F]{40}$/);
+    // viem's publicKeyToAddress always returns EIP-55 checksummed
+    // Verify it's not all-lowercase (checksummed addresses have mixed case)
+    const hexPart = addr.slice(2);
+    const hasUpperCase = hexPart !== hexPart.toLowerCase();
+    const hasLowerCase = hexPart !== hexPart.toUpperCase();
+    // At least one of these should be true for a checksummed address
+    // (unless the address happens to be all digits, which is extremely rare)
+    expect(hasUpperCase || !hexPart.match(/[a-f]/i)).toBe(true);
+    expect(hasLowerCase || !hexPart.match(/[a-f]/i)).toBe(true);
+  });
+});
+
+describe("isValidXpub", () => {
+  it("accepts valid xpub", () => {
+    expect(isValidXpub(TEST_XPUB)).toBe(true);
+  });
+
+  it("rejects garbage", () => {
+    expect(isValidXpub("not-an-xpub")).toBe(false);
+  });
+
+  it("rejects empty string", () => {
+    expect(isValidXpub("")).toBe(false);
+  });
+});

package/src/billing/crypto/evm/__tests__/checkout.test.ts

@@ -0,0 +1,83 @@
+import { HDKey } from "@scure/bip32";
+import { describe, expect, it, vi } from "vitest";
+import { createStablecoinCheckout } from "../checkout.js";
+
+function makeTestXpub(): string {
+  const seed = new Uint8Array(32);
+  seed[0] = 1;
+  const master = HDKey.fromMasterSeed(seed);
+  return master.derive("m/44'/60'/0'").publicExtendedKey;
+}
+
+const TEST_XPUB = makeTestXpub();
+
+describe("createStablecoinCheckout", () => {
+  it("derives address and creates charge", async () => {
+    const mockChargeStore = {
+      getNextDerivationIndex: vi.fn().mockResolvedValue(42),
+      createStablecoinCharge: vi.fn().mockResolvedValue(undefined),
+    };
+
+    const result = await createStablecoinCheckout(
+      { chargeStore: mockChargeStore as never, xpub: TEST_XPUB },
+      { tenant: "t1", amountUsd: 10, chain: "base", token: "USDC" },
+    );
+
+    expect(result.depositAddress).toMatch(/^0x[0-9a-fA-F]{40}$/);
+    expect(result.amountRaw).toBe("10000000"); // 10 USDC = 10 * 10^6
+    expect(result.chain).toBe("base");
+    expect(result.token).toBe("USDC");
+    expect(mockChargeStore.createStablecoinCharge).toHaveBeenCalledOnce();
+
+    // Verify charge was created with integer cents, not floating point
+    const chargeInput = mockChargeStore.createStablecoinCharge.mock.calls[0][0];
+    expect(chargeInput.amountUsdCents).toBe(1000); // $10 = 1000 cents
+    expect(Number.isInteger(chargeInput.amountUsdCents)).toBe(true);
+  });
+
+  it("rejects below minimum", async () => {
+    const mockChargeStore = {
+      getNextDerivationIndex: vi.fn().mockResolvedValue(0),
+      createStablecoinCharge: vi.fn().mockResolvedValue(undefined),
+    };
+
+    await expect(
+      createStablecoinCheckout(
+        { chargeStore: mockChargeStore as never, xpub: TEST_XPUB },
+        { tenant: "t1", amountUsd: 5, chain: "base", token: "USDC" },
+      ),
+    ).rejects.toThrow("Minimum");
+  });
+
+  it("stores deposit address in lowercase", async () => {
+    const mockChargeStore = {
+      getNextDerivationIndex: vi.fn().mockResolvedValue(0),
+      createStablecoinCharge: vi.fn().mockResolvedValue(undefined),
+    };
+
+    await createStablecoinCheckout(
+      { chargeStore: mockChargeStore as never, xpub: TEST_XPUB },
+      { tenant: "t1", amountUsd: 10, chain: "base", token: "USDC" },
+    );
+
+    const chargeInput = mockChargeStore.createStablecoinCharge.mock.calls[0][0];
+    expect(chargeInput.depositAddress).toBe(chargeInput.depositAddress.toLowerCase());
+  });
+
+  it("converts $25 correctly to raw USDC amount", async () => {
+    const mockChargeStore = {
+      getNextDerivationIndex: vi.fn().mockResolvedValue(0),
+      createStablecoinCharge: vi.fn().mockResolvedValue(undefined),
+    };
+
+    const result = await createStablecoinCheckout(
+      { chargeStore: mockChargeStore as never, xpub: TEST_XPUB },
+      { tenant: "t1", amountUsd: 25, chain: "base", token: "USDC" },
+    );
+
+    expect(result.amountRaw).toBe("25000000"); // 25 * 10^6
+
+    const chargeInput = mockChargeStore.createStablecoinCharge.mock.calls[0][0];
+    expect(chargeInput.amountUsdCents).toBe(2500);
+  });
+});

package/src/billing/crypto/evm/__tests__/config.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { centsFromTokenAmount, getChainConfig, getTokenConfig, tokenAmountFromCents } from "../config.js";
+
+describe("getChainConfig", () => {
+  it("returns Base config", () => {
+    const cfg = getChainConfig("base");
+    expect(cfg.chainId).toBe(8453);
+    expect(cfg.confirmations).toBe(1);
+    expect(cfg.blockTimeMs).toBe(2000);
+  });
+
+  it("throws on unknown chain", () => {
+    // biome-ignore lint/suspicious/noExplicitAny: testing invalid input
+    expect(() => getChainConfig("solana" as any)).toThrow("Unsupported chain");
+  });
+});
+
+describe("getTokenConfig", () => {
+  it("returns USDC on Base", () => {
+    const cfg = getTokenConfig("USDC", "base");
+    expect(cfg.decimals).toBe(6);
+    expect(cfg.contractAddress).toMatch(/^0x/);
+    expect(cfg.contractAddress).toBe("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+  });
+
+  it("throws on unsupported token/chain combo", () => {
+    // biome-ignore lint/suspicious/noExplicitAny: testing invalid input
+    expect(() => getTokenConfig("USDC" as any, "ethereum" as any)).toThrow("Unsupported token");
+  });
+});
+
+describe("tokenAmountFromCents", () => {
+  it("converts 1000 cents ($10) to USDC raw amount (6 decimals)", () => {
+    expect(tokenAmountFromCents(1000, 6)).toBe(10_000_000n);
+  });
+
+  it("converts 100 cents ($1) to DAI raw amount (18 decimals)", () => {
+    expect(tokenAmountFromCents(100, 18)).toBe(1_000_000_000_000_000_000n);
+  });
+
+  it("converts 1 cent to USDC", () => {
+    expect(tokenAmountFromCents(1, 6)).toBe(10_000n);
+  });
+
+  it("rejects non-integer cents", () => {
+    expect(() => tokenAmountFromCents(10.5, 6)).toThrow("integer");
+  });
+});
+
+describe("centsFromTokenAmount", () => {
+  it("converts 10 USDC raw to 1000 cents", () => {
+    expect(centsFromTokenAmount(10_000_000n, 6)).toBe(1000);
+  });
+
+  it("converts 1 DAI raw to 100 cents", () => {
+    expect(centsFromTokenAmount(1_000_000_000_000_000_000n, 18)).toBe(100);
+  });
+
+  it("truncates fractional cents", () => {
+    // 0.005 USDC = 5000 raw units = 0.5 cents -> truncates to 0
+    expect(centsFromTokenAmount(5000n, 6)).toBe(0);
+  });
+});

package/src/billing/crypto/evm/__tests__/settler.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, it, vi } from "vitest";
+import { settleEvmPayment } from "../settler.js";
+import type { EvmPaymentEvent } from "../types.js";
+
+const mockEvent: EvmPaymentEvent = {
+  chain: "base",
+  token: "USDC",
+  from: "0xsender",
+  to: "0xdeposit",
+  rawAmount: "10000000", // 10 USDC
+  amountUsdCents: 1000,
+  txHash: "0xtx123",
+  blockNumber: 100,
+  logIndex: 0,
+};
+
+describe("settleEvmPayment", () => {
+  it("credits ledger when charge found and not yet credited", async () => {
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "sc:base:usdc:abc",
+          tenantId: "tenant-1",
+          amountUsdCents: 1000,
+          status: "New",
+          creditedAt: null,
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn().mockResolvedValue(undefined),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false),
+        credit: vi.fn().mockResolvedValue({}),
+      },
+      onCreditsPurchased: vi.fn().mockResolvedValue([]),
+    };
+
+    const result = await settleEvmPayment(deps as never, mockEvent);
+
+    expect(result.handled).toBe(true);
+    expect(result.creditedCents).toBe(1000);
+    expect(deps.creditLedger.credit).toHaveBeenCalledOnce();
+    expect(deps.chargeStore.markCredited).toHaveBeenCalledOnce();
+
+    // Verify Credit.fromCents was used (credit is called with a Credit object, not raw cents)
+    const creditArg = deps.creditLedger.credit.mock.calls[0][1];
+    expect(creditArg.toCentsRounded()).toBe(1000);
+  });
+
+  it("skips crediting when already credited (idempotent)", async () => {
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "sc:base:usdc:abc",
+          tenantId: "tenant-1",
+          amountUsdCents: 1000,
+          status: "Settled",
+          creditedAt: "2026-01-01",
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn().mockResolvedValue(undefined),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(true),
+        credit: vi.fn().mockResolvedValue({}),
+      },
+    };
+
+    const result = await settleEvmPayment(deps as never, mockEvent);
+
+    expect(result.handled).toBe(true);
+    expect(result.creditedCents).toBe(0);
+    expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+  });
+
+  it("returns handled:false when no charge found for deposit address", async () => {
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue(null),
+        updateStatus: vi.fn(),
+        markCredited: vi.fn(),
+      },
+      creditLedger: { hasReferenceId: vi.fn(), credit: vi.fn() },
+    };
+
+    const result = await settleEvmPayment(deps as never, mockEvent);
+    expect(result.handled).toBe(false);
+  });
+
+  it("credits the charge amount, not the transfer amount (overpayment safe)", async () => {
+    const overpaidEvent = { ...mockEvent, amountUsdCents: 2000 }; // sent $20
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "sc:x",
+          tenantId: "t",
+          amountUsdCents: 1000, // charge was for $10
+          status: "New",
+          creditedAt: null,
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn().mockResolvedValue(undefined),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false),
+        credit: vi.fn().mockResolvedValue({}),
+      },
+      onCreditsPurchased: vi.fn().mockResolvedValue([]),
+    };
+
+    const result = await settleEvmPayment(deps as never, overpaidEvent);
+    expect(result.creditedCents).toBe(1000); // charge amount, NOT transfer amount
+  });
+
+  it("rejects underpayment — does not credit if transfer < charge", async () => {
+    const underpaidEvent = { ...mockEvent, amountUsdCents: 500 }; // sent $5
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "sc:x",
+          tenantId: "t",
+          amountUsdCents: 1000, // charge was for $10
+          status: "New",
+          creditedAt: null,
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn().mockResolvedValue(undefined),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false),
+        credit: vi.fn().mockResolvedValue({}),
+      },
+    };
+
+    const result = await settleEvmPayment(deps as never, underpaidEvent);
+    expect(result.creditedCents).toBe(0);
+    expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+  });
+
+  it("uses correct ledger referenceId format", async () => {
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "sc:ref",
+          tenantId: "t",
+          amountUsdCents: 500,
+          status: "New",
+          creditedAt: null,
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn().mockResolvedValue(undefined),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false),
+        credit: vi.fn().mockResolvedValue({}),
+      },
+      onCreditsPurchased: vi.fn().mockResolvedValue([]),
+    };
+
+    await settleEvmPayment(deps as never, mockEvent);
+
+    const creditOpts = deps.creditLedger.credit.mock.calls[0][3];
+    expect(creditOpts.referenceId).toBe("evm:base:0xtx123:0");
+    expect(creditOpts.fundingSource).toBe("crypto");
+  });
+
+  it("calls onCreditsPurchased when provided", async () => {
+    const onPurchased = vi.fn().mockResolvedValue(["bot-1", "bot-2"]);
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "sc:ref",
+          tenantId: "t",
+          amountUsdCents: 500,
+          status: "New",
+          creditedAt: null,
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn().mockResolvedValue(undefined),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false),
+        credit: vi.fn().mockResolvedValue({}),
+      },
+      onCreditsPurchased: onPurchased,
+    };
+
+    const result = await settleEvmPayment(deps as never, mockEvent);
+    expect(onPurchased).toHaveBeenCalledOnce();
+    expect(result.reactivatedBots).toEqual(["bot-1", "bot-2"]);
+  });
+
+  it("rejects second transfer to already-credited charge (no double-credit)", async () => {
+    const secondTxEvent = { ...mockEvent, txHash: "0xsecondtx", logIndex: 0 };
+    const deps = {
+      chargeStore: {
+        getByDepositAddress: vi.fn().mockResolvedValue({
+          referenceId: "sc:base:usdc:abc",
+          tenantId: "tenant-1",
+          amountUsdCents: 1000,
+          status: "Settled",
+          creditedAt: "2026-01-01T00:00:00Z", // already credited by first tx
+        }),
+        updateStatus: vi.fn().mockResolvedValue(undefined),
+        markCredited: vi.fn().mockResolvedValue(undefined),
+      },
+      creditLedger: {
+        hasReferenceId: vi.fn().mockResolvedValue(false), // new txHash, so this returns false
+        credit: vi.fn().mockResolvedValue({}),
+      },
+    };
+
+    const result = await settleEvmPayment(deps as never, secondTxEvent);
+    expect(result.handled).toBe(true);
+    expect(result.creditedCents).toBe(0);
+    expect(deps.creditLedger.credit).not.toHaveBeenCalled(); // must NOT double-credit
+  });
+});