@wopr-network/platform-core 1.15.0 → 1.16.0

package/dist/billing/crypto/charge-store.d.ts

@@ -10,6 +10,19 @@ 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 {
     create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
@@ -17,6 +30,9 @@ export interface ICryptoChargeRepository {
     updateStatus(referenceId: string, status: CryptoPaymentState, currency?: string, filledAmount?: string): 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>;
 }
 /**
  * Manages crypto charge records in PostgreSQL.
@@ -35,11 +51,18 @@ export declare class DrizzleCryptoChargeRepository implements ICryptoChargeRepos
     create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
     /** Get a charge by reference ID. Returns null if not found. */
     getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null>;
+    private toRecord;
     /** Update charge status and payment details from webhook. */
     updateStatus(referenceId: string, status: CryptoPaymentState, currency?: string, filledAmount?: string): Promise<void>;
     /** Mark a charge as credited (idempotency flag). */
     markCredited(referenceId: string): Promise<void>;
     /** Check if a charge has already been credited (for idempotency). */
     isCredited(referenceId: string): Promise<boolean>;
+    /** Create a stablecoin charge with chain/token/deposit address. */
+    createStablecoinCharge(input: StablecoinChargeInput): Promise<void>;
+    /** Look up a charge by its deposit address. */
+    getByDepositAddress(address: string): Promise<CryptoChargeRecord | null>;
+    /** Get the next available HD derivation index (max + 1, or 0 if empty). */
+    getNextDerivationIndex(): Promise<number>;
 }
 export { DrizzleCryptoChargeRepository as CryptoChargeRepository };

package/dist/billing/crypto/charge-store.js

@@ -29,6 +29,9 @@ export class DrizzleCryptoChargeRepository {
         const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.referenceId, referenceId)))[0];
         if (!row)
             return null;
+        return this.toRecord(row);
+    }
+    toRecord(row) {
         return {
             referenceId: row.referenceId,
             tenantId: row.tenantId,
@@ -39,6 +42,10 @@ export class DrizzleCryptoChargeRepository {
             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,
         };
     }
     /** Update charge status and payment details from webhook. */
@@ -71,5 +78,32 @@ export class DrizzleCryptoChargeRepository {
             .where(eq(cryptoCharges.referenceId, referenceId)))[0];
         return row?.creditedAt != null;
     }
+    /** Create a stablecoin charge with chain/token/deposit address. */
+    async createStablecoinCharge(input) {
+        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) {
+        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() {
+        const result = await this.db
+            .select({ maxIdx: sql `coalesce(max(${cryptoCharges.derivationIndex}), -1)` })
+            .from(cryptoCharges);
+        return (result[0]?.maxIdx ?? -1) + 1;
+    }
 }
 export { DrizzleCryptoChargeRepository as CryptoChargeRepository };

package/dist/billing/crypto/charge-store.test.js

@@ -61,4 +61,60 @@ 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/dist/billing/crypto/evm/__tests__/address-gen.test.d.ts

@@ -0,0 +1 @@
+export {};

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.d.ts

@@ -0,0 +1 @@
+export {};

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.d.ts

@@ -0,0 +1 @@
+export {};

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.d.ts

@@ -0,0 +1 @@
+export {};

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.d.ts

@@ -0,0 +1 @@
+export {};

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;