@wopr-network/platform-core 1.14.8 → 1.16.0

package/src/billing/crypto/client.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { BTCPayClient, loadCryptoConfig } from "./client.js";
+
+describe("BTCPayClient", () => {
+  it("createInvoice sends correct request and returns id + checkoutLink", async () => {
+    const mockResponse = { id: "inv-001", checkoutLink: "https://btcpay.example.com/i/inv-001" };
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+    const client = new BTCPayClient({
+      apiKey: "test-key",
+      baseUrl: "https://btcpay.example.com",
+      storeId: "store-abc",
+    });
+
+    const result = await client.createInvoice({
+      amountUsd: 25,
+      orderId: "order-123",
+      buyerEmail: "test@example.com",
+    });
+
+    expect(result.id).toBe("inv-001");
+    expect(result.checkoutLink).toBe("https://btcpay.example.com/i/inv-001");
+
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const [url, opts] = fetchSpy.mock.calls[0];
+    expect(url).toBe("https://btcpay.example.com/api/v1/stores/store-abc/invoices");
+    expect(opts?.method).toBe("POST");
+
+    const headers = opts?.headers as Record<string, string>;
+    expect(headers.Authorization).toBe("token test-key");
+    expect(headers["Content-Type"]).toBe("application/json");
+
+    const body = JSON.parse(opts?.body as string);
+    expect(body.amount).toBe("25");
+    expect(body.currency).toBe("USD");
+    expect(body.metadata.orderId).toBe("order-123");
+    expect(body.metadata.buyerEmail).toBe("test@example.com");
+    expect(body.checkout.speedPolicy).toBe("MediumSpeed");
+
+    fetchSpy.mockRestore();
+  });
+
+  it("createInvoice includes redirectURL when provided", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ id: "inv-002", checkoutLink: "https://btcpay.example.com/i/inv-002" }), {
+        status: 200,
+      }),
+    );
+
+    const client = new BTCPayClient({ apiKey: "k", baseUrl: "https://btcpay.example.com", storeId: "s" });
+    await client.createInvoice({ amountUsd: 10, orderId: "o", redirectURL: "https://app.example.com/success" });
+
+    const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+    expect(body.checkout.redirectURL).toBe("https://app.example.com/success");
+
+    fetchSpy.mockRestore();
+  });
+
+  it("createInvoice throws on non-ok response", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("Unauthorized", { status: 401 }));
+
+    const client = new BTCPayClient({ apiKey: "bad-key", baseUrl: "https://btcpay.example.com", storeId: "s" });
+    await expect(client.createInvoice({ amountUsd: 10, orderId: "o" })).rejects.toThrow(
+      "BTCPay createInvoice failed (401)",
+    );
+
+    fetchSpy.mockRestore();
+  });
+
+  it("getInvoice sends correct request", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ id: "inv-001", status: "Settled", amount: "25", currency: "USD" }), {
+        status: 200,
+      }),
+    );
+
+    const client = new BTCPayClient({ apiKey: "k", baseUrl: "https://btcpay.example.com", storeId: "store-abc" });
+    const result = await client.getInvoice("inv-001");
+
+    expect(result.status).toBe("Settled");
+    expect(fetchSpy.mock.calls[0][0]).toBe("https://btcpay.example.com/api/v1/stores/store-abc/invoices/inv-001");
+
+    fetchSpy.mockRestore();
+  });
+});
+
+describe("loadCryptoConfig", () => {
+  beforeEach(() => {
+    delete process.env.BTCPAY_API_KEY;
+    delete process.env.BTCPAY_BASE_URL;
+    delete process.env.BTCPAY_STORE_ID;
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("returns null when BTCPAY_API_KEY is missing", () => {
+    vi.stubEnv("BTCPAY_BASE_URL", "https://btcpay.test");
+    vi.stubEnv("BTCPAY_STORE_ID", "store-1");
+    expect(loadCryptoConfig()).toBeNull();
+  });
+
+  it("returns null when BTCPAY_BASE_URL is missing", () => {
+    vi.stubEnv("BTCPAY_API_KEY", "test-key");
+    vi.stubEnv("BTCPAY_STORE_ID", "store-1");
+    expect(loadCryptoConfig()).toBeNull();
+  });
+
+  it("returns null when BTCPAY_STORE_ID is missing", () => {
+    vi.stubEnv("BTCPAY_API_KEY", "test-key");
+    vi.stubEnv("BTCPAY_BASE_URL", "https://btcpay.test");
+    expect(loadCryptoConfig()).toBeNull();
+  });
+
+  it("returns config when all env vars are set", () => {
+    vi.stubEnv("BTCPAY_API_KEY", "test-key");
+    vi.stubEnv("BTCPAY_BASE_URL", "https://btcpay.test");
+    vi.stubEnv("BTCPAY_STORE_ID", "store-1");
+    expect(loadCryptoConfig()).toEqual({
+      apiKey: "test-key",
+      baseUrl: "https://btcpay.test",
+      storeId: "store-1",
+    });
+  });
+
+  it("returns null when all env vars are missing", () => {
+    expect(loadCryptoConfig()).toBeNull();
+  });
+});

package/src/billing/crypto/client.ts

@@ -0,0 +1,86 @@
+import type { CryptoBillingConfig } from "./types.js";
+
+export type { CryptoBillingConfig as CryptoConfig };
+
+/**
+ * Lightweight BTCPay Server Greenfield API client.
+ *
+ * Uses plain fetch — zero vendor dependencies.
+ * Auth header format: "token <apiKey>" (NOT "Bearer").
+ */
+export class BTCPayClient {
+  constructor(private readonly config: CryptoBillingConfig) {}
+
+  private headers(): Record<string, string> {
+    return {
+      "Content-Type": "application/json",
+      Authorization: `token ${this.config.apiKey}`,
+    };
+  }
+
+  /**
+   * Create an invoice on the BTCPay store.
+   *
+   * Returns the invoice ID and checkout link (URL to redirect the user).
+   */
+  async createInvoice(opts: {
+    amountUsd: number;
+    orderId: string;
+    buyerEmail?: string;
+    redirectURL?: string;
+  }): Promise<{ id: string; checkoutLink: string }> {
+    const url = `${this.config.baseUrl}/api/v1/stores/${this.config.storeId}/invoices`;
+    const body = {
+      amount: String(opts.amountUsd),
+      currency: "USD",
+      metadata: {
+        orderId: opts.orderId,
+        buyerEmail: opts.buyerEmail,
+      },
+      checkout: {
+        speedPolicy: "MediumSpeed",
+        expirationMinutes: 30,
+        ...(opts.redirectURL ? { redirectURL: opts.redirectURL } : {}),
+      },
+    };
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`BTCPay createInvoice failed (${res.status}): ${text}`);
+    }
+
+    const data = (await res.json()) as { id: string; checkoutLink: string };
+    return { id: data.id, checkoutLink: data.checkoutLink };
+  }
+
+  /** Get invoice status by ID. */
+  async getInvoice(invoiceId: string): Promise<{ id: string; status: string; amount: string; currency: string }> {
+    const url = `${this.config.baseUrl}/api/v1/stores/${this.config.storeId}/invoices/${invoiceId}`;
+    const res = await fetch(url, { headers: this.headers() });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`BTCPay getInvoice failed (${res.status}): ${text}`);
+    }
+
+    return (await res.json()) as { id: string; status: string; amount: string; currency: string };
+  }
+}
+
+/**
+ * Load BTCPay config from environment variables.
+ * Returns null if any required var is missing.
+ */
+export function loadCryptoConfig(): CryptoBillingConfig | null {
+  const apiKey = process.env.BTCPAY_API_KEY;
+  const baseUrl = process.env.BTCPAY_BASE_URL;
+  const storeId = process.env.BTCPAY_STORE_ID;
+  if (!apiKey || !baseUrl || !storeId) return null;
+  return { apiKey, baseUrl, storeId };
+}

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
+  });
+});