@wopr-network/platform-core 1.14.8 → 1.16.0

package/dist/billing/crypto/client.test.js

@@ -0,0 +1,100 @@
+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;
+        expect(headers.Authorization).toBe("token test-key");
+        expect(headers["Content-Type"]).toBe("application/json");
+        const body = JSON.parse(opts?.body);
+        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);
+        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/dist/billing/crypto/evm/__tests__/address-gen.test.js

@@ -0,0 +1,54 @@
+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() {
+    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/dist/billing/crypto/evm/__tests__/checkout.test.js

@@ -0,0 +1,54 @@
+import { HDKey } from "@scure/bip32";
+import { describe, expect, it, vi } from "vitest";
+import { createStablecoinCheckout } from "../checkout.js";
+function makeTestXpub() {
+    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, 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, 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, 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, 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/dist/billing/crypto/evm/__tests__/config.test.js

@@ -0,0 +1,52 @@
+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")).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", "ethereum")).toThrow("Unsupported token");
+    });
+});
+describe("tokenAmountFromCents", () => {
+    it("converts 1000 cents ($10) to USDC raw amount (6 decimals)", () => {
+        expect(tokenAmountFromCents(1000, 6)).toBe(10000000n);
+    });
+    it("converts 100 cents ($1) to DAI raw amount (18 decimals)", () => {
+        expect(tokenAmountFromCents(100, 18)).toBe(1000000000000000000n);
+    });
+    it("converts 1 cent to USDC", () => {
+        expect(tokenAmountFromCents(1, 6)).toBe(10000n);
+    });
+    it("rejects non-integer cents", () => {
+        expect(() => tokenAmountFromCents(10.5, 6)).toThrow("integer");
+    });
+});
+describe("centsFromTokenAmount", () => {
+    it("converts 10 USDC raw to 1000 cents", () => {
+        expect(centsFromTokenAmount(10000000n, 6)).toBe(1000);
+    });
+    it("converts 1 DAI raw to 100 cents", () => {
+        expect(centsFromTokenAmount(1000000000000000000n, 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/dist/billing/crypto/evm/__tests__/settler.test.js

@@ -0,0 +1,196 @@
+import { describe, expect, it, vi } from "vitest";
+import { settleEvmPayment } from "../settler.js";
+const mockEvent = {
+    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, 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, 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, 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, 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, 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, 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, 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, secondTxEvent);
+        expect(result.handled).toBe(true);
+        expect(result.creditedCents).toBe(0);
+        expect(deps.creditLedger.credit).not.toHaveBeenCalled(); // must NOT double-credit
+    });
+});

package/dist/billing/crypto/evm/__tests__/watcher.test.js

@@ -0,0 +1,109 @@
+import { describe, expect, it, vi } from "vitest";
+import { EvmWatcher } from "../watcher.js";
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+function mockTransferLog(to, amount, blockNumber) {
+    return {
+        address: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+        topics: [
+            TRANSFER_TOPIC,
+            `0x${"00".repeat(12)}${"ab".repeat(20)}`, // from (padded)
+            `0x${"00".repeat(12)}${to.slice(2).toLowerCase()}`, // to (padded)
+        ],
+        data: `0x${amount.toString(16).padStart(64, "0")}`,
+        blockNumber: `0x${blockNumber.toString(16)}`,
+        transactionHash: `0x${"ff".repeat(32)}`,
+        logIndex: "0x0",
+    };
+}
+describe("EvmWatcher", () => {
+    it("parses Transfer log into EvmPaymentEvent", async () => {
+        const events = [];
+        const mockRpc = vi
+            .fn()
+            .mockResolvedValueOnce(`0x${(102).toString(16)}`) // eth_blockNumber: block 102
+            .mockResolvedValueOnce([mockTransferLog(`0x${"cc".repeat(20)}`, 10000000n, 99)]); // eth_getLogs
+        const watcher = new EvmWatcher({
+            chain: "base",
+            token: "USDC",
+            rpcCall: mockRpc,
+            fromBlock: 99,
+            onPayment: (evt) => {
+                events.push(evt);
+            },
+        });
+        await watcher.poll();
+        expect(events).toHaveLength(1);
+        expect(events[0].amountUsdCents).toBe(1000); // 10 USDC = $10 = 1000 cents
+        expect(events[0].to).toMatch(/^0x/);
+    });
+    it("advances cursor after processing", async () => {
+        const mockRpc = vi
+            .fn()
+            .mockResolvedValueOnce(`0x${(200).toString(16)}`) // block 200
+            .mockResolvedValueOnce([]); // no logs
+        const watcher = new EvmWatcher({
+            chain: "base",
+            token: "USDC",
+            rpcCall: mockRpc,
+            fromBlock: 100,
+            onPayment: vi.fn(),
+        });
+        await watcher.poll();
+        expect(watcher.cursor).toBeGreaterThan(100);
+    });
+    it("skips blocks not yet confirmed", async () => {
+        const events = [];
+        const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`); // current block: 50
+        // Base needs 1 confirmation, so confirmed = 50 - 1 = 49
+        // cursor starts at 50, so confirmed (49) < cursor (50) → no poll
+        const watcher = new EvmWatcher({
+            chain: "base",
+            token: "USDC",
+            rpcCall: mockRpc,
+            fromBlock: 50,
+            onPayment: (evt) => {
+                events.push(evt);
+            },
+        });
+        await watcher.poll();
+        expect(events).toHaveLength(0);
+        // eth_getLogs should not even be called
+        expect(mockRpc).toHaveBeenCalledTimes(1);
+    });
+    it("processes multiple logs in one poll", async () => {
+        const events = [];
+        const mockRpc = vi
+            .fn()
+            .mockResolvedValueOnce(`0x${(110).toString(16)}`) // block 110
+            .mockResolvedValueOnce([
+            mockTransferLog(`0x${"aa".repeat(20)}`, 5000000n, 105), // $5
+            mockTransferLog(`0x${"bb".repeat(20)}`, 20000000n, 107), // $20
+        ]);
+        const watcher = new EvmWatcher({
+            chain: "base",
+            token: "USDC",
+            rpcCall: mockRpc,
+            fromBlock: 100,
+            onPayment: (evt) => {
+                events.push(evt);
+            },
+        });
+        await watcher.poll();
+        expect(events).toHaveLength(2);
+        expect(events[0].amountUsdCents).toBe(500);
+        expect(events[1].amountUsdCents).toBe(2000);
+    });
+    it("does nothing when no new blocks", async () => {
+        const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(99).toString(16)}`); // block 99, confirmed = 98
+        const watcher = new EvmWatcher({
+            chain: "base",
+            token: "USDC",
+            rpcCall: mockRpc,
+            fromBlock: 100,
+            onPayment: vi.fn(),
+        });
+        await watcher.poll();
+        expect(watcher.cursor).toBe(100); // unchanged
+        expect(mockRpc).toHaveBeenCalledTimes(1); // only eth_blockNumber
+    });
+});

package/dist/billing/crypto/evm/address-gen.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Derive a deposit address from an xpub at a given BIP-44 index.
+ * Path: xpub / 0 / index (external chain / address index).
+ * Returns a checksummed Ethereum address. No private keys involved.
+ */
+export declare function deriveDepositAddress(xpub: string, index: number): `0x${string}`;
+/** Validate that a string is an xpub (not xprv). */
+export declare function isValidXpub(key: string): boolean;

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

@@ -0,0 +1,29 @@
+import { HDKey } from "@scure/bip32";
+import { publicKeyToAddress } from "viem/accounts";
+/**
+ * Derive a deposit address from an xpub at a given BIP-44 index.
+ * Path: xpub / 0 / index (external chain / address index).
+ * Returns a checksummed Ethereum address. No private keys involved.
+ */
+export function deriveDepositAddress(xpub, index) {
+    if (!Number.isInteger(index) || index < 0)
+        throw new Error(`Invalid derivation index: ${index}`);
+    const master = HDKey.fromExtendedKey(xpub);
+    const child = master.deriveChild(0).deriveChild(index);
+    if (!child.publicKey)
+        throw new Error("Failed to derive public key");
+    const hexPubKey = `0x${Array.from(child.publicKey, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+    return publicKeyToAddress(hexPubKey);
+}
+/** Validate that a string is an xpub (not xprv). */
+export function isValidXpub(key) {
+    if (!key.startsWith("xpub"))
+        return false;
+    try {
+        HDKey.fromExtendedKey(key);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/billing/crypto/evm/checkout.d.ts

@@ -0,0 +1,26 @@
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import type { StablecoinCheckoutOpts } from "./types.js";
+export declare const MIN_STABLECOIN_USD = 10;
+export interface StablecoinCheckoutDeps {
+    chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
+    xpub: string;
+}
+export interface StablecoinCheckoutResult {
+    depositAddress: string;
+    amountRaw: string;
+    amountUsd: number;
+    chain: string;
+    token: string;
+    referenceId: string;
+}
+/**
+ * Create a stablecoin checkout — derive a unique deposit address, store the charge.
+ *
+ * Race safety: the unique constraint on derivation_index prevents two concurrent
+ * checkouts from claiming the same index. On conflict, we retry with the next index.
+ *
+ * CRITICAL: amountUsd is converted to integer cents via Credit.fromDollars().toCentsRounded().
+ * The charge store holds USD cents (integer). Credit.fromCents() handles the
+ * cents → nanodollars conversion when crediting the ledger in the settler.
+ */
+export declare function createStablecoinCheckout(deps: StablecoinCheckoutDeps, opts: StablecoinCheckoutOpts): Promise<StablecoinCheckoutResult>;