@wopr-network/platform-core 1.21.0 → 1.22.0

package/dist/billing/crypto/btc/settler.js

@@ -16,7 +16,7 @@ export async function settleBtcPayment(deps, event) {
     const { chargeStore, creditLedger } = deps;
     const charge = await chargeStore.getByDepositAddress(event.address);
     if (!charge) {
-        return { handled: false, status: "Settled" };
+        return { handled: false, status: "Invalid" };
     }
     await chargeStore.updateStatus(charge.referenceId, "Settled");
     // Charge-level idempotency

package/dist/billing/crypto/btc/watcher.d.ts

@@ -1,3 +1,4 @@
+import type { IPriceOracle } from "../oracle/types.js";
 import type { BitcoindConfig, BtcPaymentEvent } from "./types.js";
 type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;
 export interface BtcWatcherOpts {
@@ -6,15 +7,16 @@ export interface BtcWatcherOpts {
     /** Addresses to watch (must be imported into bitcoind wallet first). */
     watchedAddresses: string[];
     onPayment: (event: BtcPaymentEvent) => void | Promise<void>;
-    /** Current BTC/USD price for conversion. */
-    getBtcPrice: () => Promise<number>;
+    /** Price oracle for BTC/USD conversion. */
+    oracle: IPriceOracle;
 }
 export declare class BtcWatcher {
     private readonly rpc;
     private readonly addresses;
     private readonly onPayment;
     private readonly minConfirmations;
-    private readonly getBtcPrice;
+    private readonly oracle;
+    private readonly processedTxids;
     constructor(opts: BtcWatcherOpts);
     /** Update the set of watched addresses. */
     setWatchedAddresses(addresses: string[]): void;

package/dist/billing/crypto/btc/watcher.js

@@ -1,17 +1,16 @@
-/** Track which txids we've already processed to avoid double-crediting. */
-const processedTxids = new Set();
 export class BtcWatcher {
     rpc;
     addresses;
     onPayment;
     minConfirmations;
-    getBtcPrice;
+    oracle;
+    processedTxids = new Set();
     constructor(opts) {
         this.rpc = opts.rpcCall;
         this.addresses = new Set(opts.watchedAddresses);
         this.onPayment = opts.onPayment;
         this.minConfirmations = opts.config.confirmations;
-        this.getBtcPrice = opts.getBtcPrice;
+        this.oracle = opts.oracle;
     }
     /** Update the set of watched addresses. */
     setWatchedAddresses(addresses) {
@@ -33,21 +32,21 @@ export class BtcWatcher {
             false, // include_empty
             true, // include_watchonly
         ]));
-        const btcPrice = await this.getBtcPrice();
+        const { priceCents } = await this.oracle.getPrice("BTC");
         for (const entry of received) {
             if (!this.addresses.has(entry.address))
                 continue;
             for (const txid of entry.txids) {
-                if (processedTxids.has(txid))
+                if (this.processedTxids.has(txid))
                     continue;
-                processedTxids.add(txid);
                 // Get transaction details for the exact amount sent to this address
                 const tx = (await this.rpc("gettransaction", [txid, true]));
                 const detail = tx.details.find((d) => d.address === entry.address && d.category === "receive");
                 if (!detail)
                     continue;
                 const amountSats = Math.round(detail.amount * 100_000_000);
-                const amountUsdCents = Math.round(detail.amount * btcPrice * 100);
+                // priceCents is cents per 1 BTC. detail.amount is in BTC.
+                const amountUsdCents = Math.round((amountSats * priceCents) / 100_000_000);
                 const event = {
                     address: entry.address,
                     txid,
@@ -56,6 +55,8 @@ export class BtcWatcher {
                     confirmations: tx.confirmations,
                 };
                 await this.onPayment(event);
+                // Add AFTER successful onPayment to avoid skipping on failure
+                this.processedTxids.add(txid);
             }
         }
     }

package/dist/billing/crypto/evm/__tests__/eth-checkout.test.d.ts

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

package/dist/billing/crypto/evm/__tests__/eth-checkout.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from "vitest";
+import { createEthCheckout, MIN_ETH_USD } from "../eth-checkout.js";
+const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceCents: 350_000, updatedAt: new Date() }) };
+function makeDeps(derivationIndex = 0) {
+    return {
+        chargeStore: {
+            getNextDerivationIndex: vi.fn().mockResolvedValue(derivationIndex),
+            createStablecoinCharge: vi.fn().mockResolvedValue(undefined),
+        },
+        oracle: mockOracle,
+        xpub: "xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8",
+    };
+}
+describe("createEthCheckout", () => {
+    it("creates checkout with oracle-derived expected wei", async () => {
+        const deps = makeDeps();
+        const result = await createEthCheckout(deps, { tenant: "t1", amountUsd: 50, chain: "base" });
+        expect(result.amountUsd).toBe(50);
+        expect(result.priceCents).toBe(350_000);
+        expect(result.chain).toBe("base");
+        // $50 = 5000 cents. 5000 × 10^18 / 350000 = 14285714285714285n
+        expect(result.expectedWei).toBe("14285714285714285");
+        expect(result.depositAddress).toMatch(/^0x/);
+        expect(result.referenceId).toMatch(/^eth:base:0x/);
+    });
+    it("rejects amount below minimum", async () => {
+        const deps = makeDeps();
+        await expect(createEthCheckout(deps, { tenant: "t1", amountUsd: 5, chain: "base" })).rejects.toThrow(`Minimum payment amount is $${MIN_ETH_USD}`);
+    });
+    it("retries on unique constraint violation", async () => {
+        const deps = makeDeps();
+        deps.chargeStore.createStablecoinCharge
+            .mockRejectedValueOnce(Object.assign(new Error("unique_violation"), { code: "23505" }))
+            .mockResolvedValueOnce(undefined);
+        deps.chargeStore.getNextDerivationIndex.mockResolvedValueOnce(0).mockResolvedValueOnce(1);
+        const result = await createEthCheckout(deps, { tenant: "t1", amountUsd: 50, chain: "base" });
+        expect(result.depositAddress).toMatch(/^0x/);
+        expect(deps.chargeStore.createStablecoinCharge).toHaveBeenCalledTimes(2);
+    });
+    it("stores amountUsdCents as integer cents", async () => {
+        const deps = makeDeps();
+        await createEthCheckout(deps, { tenant: "t1", amountUsd: 50, chain: "base" });
+        const call = deps.chargeStore.createStablecoinCharge.mock.calls[0][0];
+        expect(call.amountUsdCents).toBe(5000);
+        expect(Number.isInteger(call.amountUsdCents)).toBe(true);
+        expect(call.token).toBe("ETH");
+        expect(call.chain).toBe("base");
+    });
+});

package/dist/billing/crypto/evm/__tests__/eth-settler.test.d.ts

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

package/dist/billing/crypto/evm/__tests__/eth-settler.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from "vitest";
+import { settleEthPayment } from "../eth-settler.js";
+function makeEvent(overrides = {}) {
+    return {
+        chain: "base",
+        from: "0xsender",
+        to: "0xdeposit",
+        valueWei: "14285714285714285",
+        amountUsdCents: 5000,
+        txHash: "0xabc123",
+        blockNumber: 100,
+        ...overrides,
+    };
+}
+function makeDeps(charge = null) {
+    return {
+        chargeStore: {
+            getByDepositAddress: vi.fn().mockResolvedValue(charge
+                ? {
+                    referenceId: "eth:base:0xdeposit",
+                    tenantId: "t1",
+                    amountUsdCents: charge.amountUsdCents,
+                    creditedAt: charge.creditedAt,
+                }
+                : null),
+            updateStatus: vi.fn().mockResolvedValue(undefined),
+            markCredited: vi.fn().mockResolvedValue(undefined),
+        },
+        creditLedger: {
+            credit: vi.fn().mockResolvedValue(undefined),
+            hasReferenceId: vi.fn().mockResolvedValue(false),
+        },
+    };
+}
+describe("settleEthPayment", () => {
+    it("returns Invalid for unknown deposit address", async () => {
+        const deps = makeDeps(null);
+        const result = await settleEthPayment(deps, makeEvent());
+        expect(result.handled).toBe(false);
+        expect(result.status).toBe("Invalid");
+    });
+    it("credits ledger for valid payment", async () => {
+        const deps = makeDeps({ amountUsdCents: 5000, creditedAt: null });
+        const result = await settleEthPayment(deps, makeEvent());
+        expect(result.handled).toBe(true);
+        expect(result.creditedCents).toBe(5000);
+        expect(deps.creditLedger.credit).toHaveBeenCalledOnce();
+        expect(deps.chargeStore.markCredited).toHaveBeenCalledOnce();
+    });
+    it("skips already-credited charge (charge-level idempotency)", async () => {
+        const deps = makeDeps({ amountUsdCents: 5000, creditedAt: "2026-01-01" });
+        const result = await settleEthPayment(deps, makeEvent());
+        expect(result.handled).toBe(true);
+        expect(result.creditedCents).toBe(0);
+        expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+    });
+    it("skips duplicate transfer (transfer-level idempotency)", async () => {
+        const deps = makeDeps({ amountUsdCents: 5000, creditedAt: null });
+        deps.creditLedger.hasReferenceId.mockResolvedValue(true);
+        const result = await settleEthPayment(deps, makeEvent());
+        expect(result.creditedCents).toBe(0);
+        expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+    });
+    it("rejects underpayment", async () => {
+        const deps = makeDeps({ amountUsdCents: 10000, creditedAt: null });
+        const result = await settleEthPayment(deps, makeEvent({ amountUsdCents: 5000 }));
+        expect(result.creditedCents).toBe(0);
+        expect(deps.creditLedger.credit).not.toHaveBeenCalled();
+    });
+    it("credits charge amount, not transfer amount (overpayment safe)", async () => {
+        const deps = makeDeps({ amountUsdCents: 5000, creditedAt: null });
+        const result = await settleEthPayment(deps, makeEvent({ amountUsdCents: 10000 }));
+        expect(result.creditedCents).toBe(5000);
+    });
+    it("uses correct creditRef format", async () => {
+        const deps = makeDeps({ amountUsdCents: 5000, creditedAt: null });
+        await settleEthPayment(deps, makeEvent({ chain: "base", txHash: "0xdef" }));
+        expect(deps.creditLedger.hasReferenceId).toHaveBeenCalledWith("eth:base:0xdef");
+    });
+});

package/dist/billing/crypto/evm/__tests__/eth-watcher.test.d.ts

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

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

@@ -0,0 +1,134 @@
+import { describe, expect, it, vi } from "vitest";
+import { EthWatcher } from "../eth-watcher.js";
+function makeRpc(responses) {
+    return vi.fn(async (method) => responses[method]);
+}
+const mockOracle = { getPrice: vi.fn().mockResolvedValue({ priceCents: 350_000, updatedAt: new Date() }) };
+describe("EthWatcher", () => {
+    it("detects native ETH transfer to watched address", async () => {
+        const onPayment = vi.fn();
+        const rpc = makeRpc({
+            eth_blockNumber: "0xb",
+            eth_getBlockByNumber: {
+                transactions: [
+                    {
+                        hash: "0xabc",
+                        from: "0xsender",
+                        to: "0xdeposit",
+                        value: "0xDE0B6B3A7640000", // 1 ETH = 10^18 wei
+                        blockNumber: "0xa",
+                    },
+                ],
+            },
+        });
+        const watcher = new EthWatcher({
+            chain: "base",
+            rpcCall: rpc,
+            oracle: mockOracle,
+            fromBlock: 10,
+            onPayment,
+            watchedAddresses: ["0xDeposit"],
+        });
+        await watcher.poll();
+        expect(onPayment).toHaveBeenCalledOnce();
+        const event = onPayment.mock.calls[0][0];
+        expect(event.to).toBe("0xdeposit");
+        expect(event.valueWei).toBe("1000000000000000000");
+        expect(event.amountUsdCents).toBe(350_000); // 1 ETH × $3,500
+        expect(event.txHash).toBe("0xabc");
+    });
+    it("skips transactions not to watched addresses", async () => {
+        const onPayment = vi.fn();
+        const rpc = makeRpc({
+            eth_blockNumber: "0xb",
+            eth_getBlockByNumber: {
+                transactions: [{ hash: "0xabc", from: "0xa", to: "0xother", value: "0xDE0B6B3A7640000", blockNumber: "0xa" }],
+            },
+        });
+        const watcher = new EthWatcher({
+            chain: "base",
+            rpcCall: rpc,
+            oracle: mockOracle,
+            fromBlock: 10,
+            onPayment,
+            watchedAddresses: ["0xDeposit"],
+        });
+        await watcher.poll();
+        expect(onPayment).not.toHaveBeenCalled();
+    });
+    it("skips zero-value transactions", async () => {
+        const onPayment = vi.fn();
+        const rpc = makeRpc({
+            eth_blockNumber: "0xb",
+            eth_getBlockByNumber: {
+                transactions: [{ hash: "0xabc", from: "0xa", to: "0xdeposit", value: "0x0", blockNumber: "0xa" }],
+            },
+        });
+        const watcher = new EthWatcher({
+            chain: "base",
+            rpcCall: rpc,
+            oracle: mockOracle,
+            fromBlock: 10,
+            onPayment,
+            watchedAddresses: ["0xDeposit"],
+        });
+        await watcher.poll();
+        expect(onPayment).not.toHaveBeenCalled();
+    });
+    it("does not double-process same txid", async () => {
+        const onPayment = vi.fn();
+        const rpc = makeRpc({
+            eth_blockNumber: "0xb",
+            eth_getBlockByNumber: {
+                transactions: [{ hash: "0xabc", from: "0xa", to: "0xdeposit", value: "0xDE0B6B3A7640000", blockNumber: "0xa" }],
+            },
+        });
+        const watcher = new EthWatcher({
+            chain: "base",
+            rpcCall: rpc,
+            oracle: mockOracle,
+            fromBlock: 10,
+            onPayment,
+            watchedAddresses: ["0xDeposit"],
+        });
+        await watcher.poll();
+        // Reset cursor to re-scan same block
+        await watcher.poll();
+        expect(onPayment).toHaveBeenCalledOnce();
+    });
+    it("skips poll when no watched addresses", async () => {
+        const onPayment = vi.fn();
+        const rpc = vi.fn();
+        const watcher = new EthWatcher({
+            chain: "base",
+            rpcCall: rpc,
+            oracle: mockOracle,
+            fromBlock: 10,
+            onPayment,
+            watchedAddresses: [],
+        });
+        await watcher.poll();
+        expect(rpc).not.toHaveBeenCalled();
+    });
+    it("does not mark txid as processed if onPayment throws", async () => {
+        const onPayment = vi.fn().mockRejectedValueOnce(new Error("db fail")).mockResolvedValueOnce(undefined);
+        const rpc = makeRpc({
+            eth_blockNumber: "0xb",
+            eth_getBlockByNumber: {
+                transactions: [{ hash: "0xabc", from: "0xa", to: "0xdeposit", value: "0xDE0B6B3A7640000", blockNumber: "0xa" }],
+            },
+        });
+        const watcher = new EthWatcher({
+            chain: "base",
+            rpcCall: rpc,
+            oracle: mockOracle,
+            fromBlock: 10,
+            onPayment,
+            watchedAddresses: ["0xDeposit"],
+        });
+        await expect(watcher.poll()).rejects.toThrow("db fail");
+        // Retry — should process the same tx again since it wasn't marked
+        await watcher.poll();
+        expect(onPayment).toHaveBeenCalledTimes(2);
+    });
+});

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

@@ -0,0 +1,34 @@
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import type { IPriceOracle } from "../oracle/types.js";
+import type { EvmChain } from "./types.js";
+export declare const MIN_ETH_USD = 10;
+export interface EthCheckoutDeps {
+    chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
+    oracle: IPriceOracle;
+    xpub: string;
+}
+export interface EthCheckoutOpts {
+    tenant: string;
+    amountUsd: number;
+    chain: EvmChain;
+}
+export interface EthCheckoutResult {
+    depositAddress: `0x${string}`;
+    amountUsd: number;
+    /** Expected ETH amount in wei (BigInt as string). */
+    expectedWei: string;
+    /** ETH price in USD cents at checkout time. */
+    priceCents: number;
+    chain: EvmChain;
+    referenceId: string;
+}
+/**
+ * Create an ETH checkout — derive deposit address, lock price, store charge.
+ *
+ * Uses the oracle to get live ETH/USD price and compute the expected
+ * deposit amount in wei. The charge stores amountUsdCents (not wei) —
+ * settlement always credits the USD amount, not the ETH value.
+ *
+ * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ */
+export declare function createEthCheckout(deps: EthCheckoutDeps, opts: EthCheckoutOpts): Promise<EthCheckoutResult>;

package/dist/billing/crypto/evm/eth-checkout.js

@@ -0,0 +1,53 @@
+import { Credit } from "../../../credits/credit.js";
+import { centsToNative } from "../oracle/convert.js";
+import { deriveDepositAddress } from "./address-gen.js";
+export const MIN_ETH_USD = 10;
+/**
+ * Create an ETH checkout — derive deposit address, lock price, store charge.
+ *
+ * Uses the oracle to get live ETH/USD price and compute the expected
+ * deposit amount in wei. The charge stores amountUsdCents (not wei) —
+ * settlement always credits the USD amount, not the ETH value.
+ *
+ * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ */
+export async function createEthCheckout(deps, opts) {
+    if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_ETH_USD) {
+        throw new Error(`Minimum payment amount is $${MIN_ETH_USD}`);
+    }
+    const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
+    const { priceCents } = await deps.oracle.getPrice("ETH");
+    const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
+    const maxRetries = 3;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+        const depositAddress = deriveDepositAddress(deps.xpub, derivationIndex);
+        const referenceId = `eth:${opts.chain}:${depositAddress}`;
+        try {
+            await deps.chargeStore.createStablecoinCharge({
+                referenceId,
+                tenantId: opts.tenant,
+                amountUsdCents,
+                chain: opts.chain,
+                token: "ETH",
+                depositAddress,
+                derivationIndex,
+            });
+            return {
+                depositAddress,
+                amountUsd: opts.amountUsd,
+                expectedWei: expectedWei.toString(),
+                priceCents,
+                chain: opts.chain,
+                referenceId,
+            };
+        }
+        catch (err) {
+            const code = err.code;
+            const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
+            if (!isConflict || attempt === maxRetries)
+                throw err;
+        }
+    }
+    throw new Error("Failed to claim derivation index after retries");
+}

package/dist/billing/crypto/evm/eth-settler.d.ts

@@ -0,0 +1,23 @@
+import type { ILedger } from "../../../credits/ledger.js";
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import type { CryptoWebhookResult } from "../types.js";
+import type { EthPaymentEvent } from "./eth-watcher.js";
+export interface EthSettlerDeps {
+    chargeStore: Pick<ICryptoChargeRepository, "getByDepositAddress" | "updateStatus" | "markCredited">;
+    creditLedger: Pick<ILedger, "credit" | "hasReferenceId">;
+    onCreditsPurchased?: (tenantId: string, ledger: ILedger) => Promise<string[]>;
+}
+/**
+ * Settle a native ETH payment — look up charge by deposit address, credit ledger.
+ *
+ * Same idempotency pattern as EVM stablecoin and BTC settlers:
+ *   1. Charge-level: charge.creditedAt != null → skip
+ *   2. Transfer-level: creditLedger.hasReferenceId → skip (atomic)
+ *   3. Advisory: chargeStore.markCredited
+ *
+ * Credits the CHARGE amount (not the ETH value) for overpayment safety.
+ *
+ * CRITICAL: charge.amountUsdCents is in USD cents (integer).
+ * Credit.fromCents() converts cents → nanodollars for the ledger.
+ */
+export declare function settleEthPayment(deps: EthSettlerDeps, event: EthPaymentEvent): Promise<CryptoWebhookResult>;

package/dist/billing/crypto/evm/eth-settler.js

@@ -0,0 +1,52 @@
+import { Credit } from "../../../credits/credit.js";
+/**
+ * Settle a native ETH payment — look up charge by deposit address, credit ledger.
+ *
+ * Same idempotency pattern as EVM stablecoin and BTC settlers:
+ *   1. Charge-level: charge.creditedAt != null → skip
+ *   2. Transfer-level: creditLedger.hasReferenceId → skip (atomic)
+ *   3. Advisory: chargeStore.markCredited
+ *
+ * Credits the CHARGE amount (not the ETH value) for overpayment safety.
+ *
+ * CRITICAL: charge.amountUsdCents is in USD cents (integer).
+ * Credit.fromCents() converts cents → nanodollars for the ledger.
+ */
+export async function settleEthPayment(deps, event) {
+    const { chargeStore, creditLedger } = deps;
+    const charge = await chargeStore.getByDepositAddress(event.to.toLowerCase());
+    if (!charge) {
+        return { handled: false, status: "Invalid" };
+    }
+    await chargeStore.updateStatus(charge.referenceId, "Settled");
+    if (charge.creditedAt != null) {
+        return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+    }
+    const creditRef = `eth:${event.chain}:${event.txHash}`;
+    if (await creditLedger.hasReferenceId(creditRef)) {
+        return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+    }
+    if (event.amountUsdCents < charge.amountUsdCents) {
+        return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+    }
+    const creditCents = charge.amountUsdCents;
+    await creditLedger.credit(charge.tenantId, Credit.fromCents(creditCents), "purchase", {
+        description: `ETH credit purchase (${event.chain}, tx: ${event.txHash})`,
+        referenceId: creditRef,
+        fundingSource: "crypto",
+    });
+    await chargeStore.markCredited(charge.referenceId);
+    let reactivatedBots;
+    if (deps.onCreditsPurchased) {
+        reactivatedBots = await deps.onCreditsPurchased(charge.tenantId, creditLedger);
+        if (reactivatedBots.length === 0)
+            reactivatedBots = undefined;
+    }
+    return {
+        handled: true,
+        status: "Settled",
+        tenant: charge.tenantId,
+        creditedCents: creditCents,
+        reactivatedBots,
+    };
+}

package/dist/billing/crypto/evm/eth-watcher.d.ts

@@ -0,0 +1,53 @@
+import type { IPriceOracle } from "../oracle/types.js";
+import type { EvmChain } from "./types.js";
+type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;
+/** Event emitted when a native ETH deposit is detected and confirmed. */
+export interface EthPaymentEvent {
+    readonly chain: EvmChain;
+    readonly from: string;
+    readonly to: string;
+    /** Raw value in wei (BigInt as string for serialization). */
+    readonly valueWei: string;
+    /** USD cents equivalent at detection time (integer). */
+    readonly amountUsdCents: number;
+    readonly txHash: string;
+    readonly blockNumber: number;
+}
+export interface EthWatcherOpts {
+    chain: EvmChain;
+    rpcCall: RpcCall;
+    oracle: IPriceOracle;
+    fromBlock: number;
+    onPayment: (event: EthPaymentEvent) => void | Promise<void>;
+    watchedAddresses?: string[];
+}
+/**
+ * Native ETH transfer watcher.
+ *
+ * Unlike the ERC-20 EvmWatcher which uses eth_getLogs for Transfer events,
+ * this scans blocks for transactions where `to` matches a watched deposit
+ * address and `value > 0`.
+ *
+ * Uses the price oracle to convert wei → USD cents at detection time.
+ */
+export declare class EthWatcher {
+    private _cursor;
+    private readonly chain;
+    private readonly rpc;
+    private readonly oracle;
+    private readonly onPayment;
+    private readonly confirmations;
+    private _watchedAddresses;
+    private readonly processedTxids;
+    constructor(opts: EthWatcherOpts);
+    setWatchedAddresses(addresses: string[]): void;
+    get cursor(): number;
+    /**
+     * Poll for new native ETH transfers to watched addresses.
+     *
+     * Scans each confirmed block's transactions. Only processes txs
+     * where `to` is in the watched set and `value > 0`.
+     */
+    poll(): Promise<void>;
+}
+export {};

package/dist/billing/crypto/evm/eth-watcher.js

@@ -0,0 +1,83 @@
+import { nativeToCents } from "../oracle/convert.js";
+import { getChainConfig } from "./config.js";
+/**
+ * Native ETH transfer watcher.
+ *
+ * Unlike the ERC-20 EvmWatcher which uses eth_getLogs for Transfer events,
+ * this scans blocks for transactions where `to` matches a watched deposit
+ * address and `value > 0`.
+ *
+ * Uses the price oracle to convert wei → USD cents at detection time.
+ */
+export class EthWatcher {
+    _cursor;
+    chain;
+    rpc;
+    oracle;
+    onPayment;
+    confirmations;
+    _watchedAddresses;
+    processedTxids = new Set();
+    constructor(opts) {
+        this.chain = opts.chain;
+        this.rpc = opts.rpcCall;
+        this.oracle = opts.oracle;
+        this._cursor = opts.fromBlock;
+        this.onPayment = opts.onPayment;
+        this.confirmations = getChainConfig(opts.chain).confirmations;
+        this._watchedAddresses = new Set((opts.watchedAddresses ?? []).map((a) => a.toLowerCase()));
+    }
+    setWatchedAddresses(addresses) {
+        this._watchedAddresses = new Set(addresses.map((a) => a.toLowerCase()));
+    }
+    get cursor() {
+        return this._cursor;
+    }
+    /**
+     * Poll for new native ETH transfers to watched addresses.
+     *
+     * Scans each confirmed block's transactions. Only processes txs
+     * where `to` is in the watched set and `value > 0`.
+     */
+    async poll() {
+        if (this._watchedAddresses.size === 0)
+            return;
+        const latestHex = (await this.rpc("eth_blockNumber", []));
+        const latest = Number.parseInt(latestHex, 16);
+        const confirmed = latest - this.confirmations;
+        if (confirmed < this._cursor)
+            return;
+        const { priceCents } = await this.oracle.getPrice("ETH");
+        for (let blockNum = this._cursor; blockNum <= confirmed; blockNum++) {
+            const block = (await this.rpc("eth_getBlockByNumber", [`0x${blockNum.toString(16)}`, true]));
+            if (!block)
+                continue;
+            for (const tx of block.transactions) {
+                if (!tx.to)
+                    continue;
+                const to = tx.to.toLowerCase();
+                if (!this._watchedAddresses.has(to))
+                    continue;
+                const valueWei = BigInt(tx.value);
+                if (valueWei === 0n)
+                    continue;
+                if (this.processedTxids.has(tx.hash))
+                    continue;
+                const amountUsdCents = nativeToCents(valueWei, priceCents, 18);
+                const event = {
+                    chain: this.chain,
+                    from: tx.from.toLowerCase(),
+                    to,
+                    valueWei: valueWei.toString(),
+                    amountUsdCents,
+                    txHash: tx.hash,
+                    blockNumber: blockNum,
+                };
+                await this.onPayment(event);
+                // Add to processed AFTER successful onPayment to avoid skipping on failure
+                this.processedTxids.add(tx.hash);
+            }
+        }
+        this._cursor = confirmed + 1;
+    }
+}