@wopr-network/platform-core 1.19.0 → 1.20.0

package/src/billing/crypto/btc/settler.ts

@@ -0,0 +1,74 @@
+import { Credit } from "../../../credits/credit.js";
+import type { ILedger } from "../../../credits/ledger.js";
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import type { CryptoWebhookResult } from "../types.js";
+import type { BtcPaymentEvent } from "./types.js";
+
+export interface BtcSettlerDeps {
+  chargeStore: Pick<ICryptoChargeRepository, "getByDepositAddress" | "updateStatus" | "markCredited">;
+  creditLedger: Pick<ILedger, "credit" | "hasReferenceId">;
+  onCreditsPurchased?: (tenantId: string, ledger: ILedger) => Promise<string[]>;
+}
+
+/**
+ * Settle a BTC payment — look up charge by deposit address, credit ledger.
+ *
+ * Same idempotency pattern as EVM settler and BTCPay webhook handler:
+ *   1. Charge-level: check creditedAt (prevents second tx double-credit)
+ *   2. Transfer-level: creditLedger.hasReferenceId (atomic)
+ *   3. Advisory: chargeStore.markCredited
+ *
+ * Credits the CHARGE amount (not the BTC amount) for consistency.
+ *
+ * CRITICAL: charge.amountUsdCents is in USD cents (integer).
+ * Credit.fromCents() converts cents → nanodollars for the ledger.
+ */
+export async function settleBtcPayment(deps: BtcSettlerDeps, event: BtcPaymentEvent): Promise<CryptoWebhookResult> {
+  const { chargeStore, creditLedger } = deps;
+
+  const charge = await chargeStore.getByDepositAddress(event.address);
+  if (!charge) {
+    return { handled: false, status: "Settled" };
+  }
+
+  await chargeStore.updateStatus(charge.referenceId, "Settled");
+
+  // Charge-level idempotency
+  if (charge.creditedAt != null) {
+    return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+  }
+
+  // Transfer-level idempotency
+  const creditRef = `btc:${event.txid}`;
+  if (await creditLedger.hasReferenceId(creditRef)) {
+    return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+  }
+
+  // Underpayment check
+  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: `BTC credit purchase (txid: ${event.txid})`,
+    referenceId: creditRef,
+    fundingSource: "crypto",
+  });
+
+  await chargeStore.markCredited(charge.referenceId);
+
+  let reactivatedBots: string[] | undefined;
+  if (deps.onCreditsPurchased) {
+    reactivatedBots = await deps.onCreditsPurchased(charge.tenantId, creditLedger as ILedger);
+    if (reactivatedBots.length === 0) reactivatedBots = undefined;
+  }
+
+  return {
+    handled: true,
+    status: "Settled",
+    tenant: charge.tenantId,
+    creditedCents: creditCents,
+    reactivatedBots,
+  };
+}

package/src/billing/crypto/btc/types.ts

@@ -0,0 +1,25 @@
+/** BTC payment event emitted when a deposit is confirmed. */
+export interface BtcPaymentEvent {
+  readonly address: string;
+  readonly txid: string;
+  /** Amount in satoshis (integer). */
+  readonly amountSats: number;
+  /** USD cents equivalent (integer). */
+  readonly amountUsdCents: number;
+  readonly confirmations: number;
+}
+
+/** Options for creating a BTC checkout. */
+export interface BtcCheckoutOpts {
+  tenant: string;
+  amountUsd: number;
+}
+
+/** Bitcoind RPC configuration. */
+export interface BitcoindConfig {
+  readonly rpcUrl: string;
+  readonly rpcUser: string;
+  readonly rpcPassword: string;
+  readonly network: "mainnet" | "testnet" | "regtest";
+  readonly confirmations: number;
+}

package/src/billing/crypto/btc/watcher.ts

@@ -0,0 +1,115 @@
+import type { BitcoindConfig, BtcPaymentEvent } from "./types.js";
+
+type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;
+
+export interface BtcWatcherOpts {
+  config: BitcoindConfig;
+  rpcCall: RpcCall;
+  /** 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>;
+}
+
+interface ReceivedByAddress {
+  address: string;
+  amount: number;
+  confirmations: number;
+  txids: string[];
+}
+
+/** Track which txids we've already processed to avoid double-crediting. */
+const processedTxids = new Set<string>();
+
+export class BtcWatcher {
+  private readonly rpc: RpcCall;
+  private readonly addresses: Set<string>;
+  private readonly onPayment: BtcWatcherOpts["onPayment"];
+  private readonly minConfirmations: number;
+  private readonly getBtcPrice: () => Promise<number>;
+
+  constructor(opts: BtcWatcherOpts) {
+    this.rpc = opts.rpcCall;
+    this.addresses = new Set(opts.watchedAddresses);
+    this.onPayment = opts.onPayment;
+    this.minConfirmations = opts.config.confirmations;
+    this.getBtcPrice = opts.getBtcPrice;
+  }
+
+  /** Update the set of watched addresses. */
+  setWatchedAddresses(addresses: string[]): void {
+    this.addresses.clear();
+    for (const a of addresses) this.addresses.add(a);
+  }
+
+  /** Import an address into bitcoind's wallet (watch-only, no rescan). */
+  async importAddress(address: string): Promise<void> {
+    await this.rpc("importaddress", [address, "", false]);
+    this.addresses.add(address);
+  }
+
+  /** Poll for confirmed payments to watched addresses. */
+  async poll(): Promise<void> {
+    if (this.addresses.size === 0) return;
+
+    const received = (await this.rpc("listreceivedbyaddress", [
+      this.minConfirmations,
+      false, // include_empty
+      true, // include_watchonly
+    ])) as ReceivedByAddress[];
+
+    const btcPrice = await this.getBtcPrice();
+
+    for (const entry of received) {
+      if (!this.addresses.has(entry.address)) continue;
+
+      for (const txid of entry.txids) {
+        if (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])) as {
+          details: Array<{ address: string; amount: number; category: string }>;
+          confirmations: number;
+        };
+
+        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);
+
+        const event: BtcPaymentEvent = {
+          address: entry.address,
+          txid,
+          amountSats,
+          amountUsdCents,
+          confirmations: tx.confirmations,
+        };
+
+        await this.onPayment(event);
+      }
+    }
+  }
+}
+
+/** Create a bitcoind JSON-RPC caller with basic auth. */
+export function createBitcoindRpc(config: BitcoindConfig): RpcCall {
+  let id = 0;
+  const auth = btoa(`${config.rpcUser}:${config.rpcPassword}`);
+  return async (method: string, params: unknown[]): Promise<unknown> => {
+    const res = await fetch(config.rpcUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${auth}`,
+      },
+      body: JSON.stringify({ jsonrpc: "1.0", id: ++id, method, params }),
+    });
+    if (!res.ok) throw new Error(`bitcoind ${method} failed: ${res.status}`);
+    const data = (await res.json()) as { result?: unknown; error?: { message: string } };
+    if (data.error) throw new Error(`bitcoind ${method}: ${data.error.message}`);
+    return data.result;
+  };
+}

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

@@ -19,7 +19,7 @@ export interface CryptoChargeRecord {
   derivationIndex: number | null;
 }
 
-export interface StablecoinChargeInput {
+export interface CryptoDepositChargeInput {
   referenceId: string;
   tenantId: string;
   amountUsdCents: number;
@@ -40,7 +40,7 @@ export interface ICryptoChargeRepository {
   ): Promise<void>;
   markCredited(referenceId: string): Promise<void>;
   isCredited(referenceId: string): Promise<boolean>;
-  createStablecoinCharge(input: StablecoinChargeInput): Promise<void>;
+  createStablecoinCharge(input: CryptoDepositChargeInput): Promise<void>;
   getByDepositAddress(address: string): Promise<CryptoChargeRecord | null>;
   getNextDerivationIndex(): Promise<number>;
 }
@@ -134,7 +134,7 @@ export class DrizzleCryptoChargeRepository implements ICryptoChargeRepository {
   }
 
   /** Create a stablecoin charge with chain/token/deposit address. */
-  async createStablecoinCharge(input: StablecoinChargeInput): Promise<void> {
+  async createStablecoinCharge(input: CryptoDepositChargeInput): Promise<void> {
     await this.db.insert(cryptoCharges).values({
       referenceId: input.referenceId,
       tenantId: input.tenantId,

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

@@ -9,6 +9,24 @@ describe("getChainConfig", () => {
     expect(cfg.blockTimeMs).toBe(2000);
   });
 
+  it("returns Ethereum config", () => {
+    const cfg = getChainConfig("ethereum");
+    expect(cfg.chainId).toBe(1);
+    expect(cfg.confirmations).toBe(12);
+  });
+
+  it("returns Arbitrum config", () => {
+    const cfg = getChainConfig("arbitrum");
+    expect(cfg.chainId).toBe(42161);
+    expect(cfg.confirmations).toBe(1);
+  });
+
+  it("returns Polygon config", () => {
+    const cfg = getChainConfig("polygon");
+    expect(cfg.chainId).toBe(137);
+    expect(cfg.confirmations).toBe(32);
+  });
+
   it("throws on unknown chain", () => {
     // biome-ignore lint/suspicious/noExplicitAny: testing invalid input
     expect(() => getChainConfig("solana" as any)).toThrow("Unsupported chain");
@@ -35,9 +53,40 @@ describe("getTokenConfig", () => {
     expect(cfg.contractAddress).toBe("0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb");
   });
 
-  it("throws on unsupported token/chain combo", () => {
+  it("returns USDC on Ethereum", () => {
+    const cfg = getTokenConfig("USDC", "ethereum");
+    expect(cfg.decimals).toBe(6);
+    expect(cfg.contractAddress).toBe("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");
+  });
+
+  it("returns USDT on Ethereum", () => {
+    const cfg = getTokenConfig("USDT", "ethereum");
+    expect(cfg.decimals).toBe(6);
+  });
+
+  it("returns DAI on Ethereum", () => {
+    const cfg = getTokenConfig("DAI", "ethereum");
+    expect(cfg.decimals).toBe(18);
+  });
+
+  it("returns USDC on Arbitrum", () => {
+    const cfg = getTokenConfig("USDC", "arbitrum");
+    expect(cfg.chain).toBe("arbitrum");
+    expect(cfg.decimals).toBe(6);
+  });
+
+  it("returns USDT on Polygon", () => {
+    const cfg = getTokenConfig("USDT", "polygon");
+    expect(cfg.decimals).toBe(6);
+  });
+
+  it("throws on DAI:polygon (not supported)", () => {
+    expect(() => getTokenConfig("DAI", "polygon")).toThrow("Unsupported token");
+  });
+
+  it("throws on unsupported chain", () => {
     // biome-ignore lint/suspicious/noExplicitAny: testing invalid input
-    expect(() => getTokenConfig("USDC" as any, "ethereum" as any)).toThrow("Unsupported token");
+    expect(() => getTokenConfig("USDC" as any, "solana" as any)).toThrow("Unsupported token");
   });
 });
 

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

@@ -20,17 +20,19 @@ function mockTransferLog(to: string, amount: bigint, blockNumber: number) {
 
 describe("EvmWatcher", () => {
   it("parses Transfer log into EvmPaymentEvent", async () => {
+    const toAddr = `0x${"cc".repeat(20)}`;
     const events: { amountUsdCents: number; to: string }[] = [];
     const mockRpc = vi
       .fn()
-      .mockResolvedValueOnce(`0x${(102).toString(16)}`) // eth_blockNumber: block 102
-      .mockResolvedValueOnce([mockTransferLog(`0x${"cc".repeat(20)}`, 10_000_000n, 99)]); // eth_getLogs
+      .mockResolvedValueOnce(`0x${(102).toString(16)}`)
+      .mockResolvedValueOnce([mockTransferLog(toAddr, 10_000_000n, 99)]);
 
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 99,
+      watchedAddresses: [toAddr],
       onPayment: (evt) => {
         events.push(evt);
       },
@@ -39,21 +41,22 @@ describe("EvmWatcher", () => {
     await watcher.poll();
 
     expect(events).toHaveLength(1);
-    expect(events[0].amountUsdCents).toBe(1000); // 10 USDC = $10 = 1000 cents
+    expect(events[0].amountUsdCents).toBe(1000);
     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
+      .mockResolvedValueOnce(`0x${(200).toString(16)}`)
+      .mockResolvedValueOnce([]);
 
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 100,
+      watchedAddresses: ["0xdeadbeef"],
       onPayment: vi.fn(),
     });
 
@@ -63,15 +66,14 @@ describe("EvmWatcher", () => {
 
   it("skips blocks not yet confirmed", async () => {
     const events: unknown[] = [];
-    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`); // current block: 50
+    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`);
 
-    // 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,
+      watchedAddresses: ["0xdeadbeef"],
       onPayment: (evt) => {
         events.push(evt);
       },
@@ -79,25 +81,24 @@ describe("EvmWatcher", () => {
 
     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 addr1 = `0x${"aa".repeat(20)}`;
+    const addr2 = `0x${"bb".repeat(20)}`;
     const events: { amountUsdCents: number }[] = [];
     const mockRpc = vi
       .fn()
-      .mockResolvedValueOnce(`0x${(110).toString(16)}`) // block 110
-      .mockResolvedValueOnce([
-        mockTransferLog(`0x${"aa".repeat(20)}`, 5_000_000n, 105), // $5
-        mockTransferLog(`0x${"bb".repeat(20)}`, 20_000_000n, 107), // $20
-      ]);
+      .mockResolvedValueOnce(`0x${(110).toString(16)}`)
+      .mockResolvedValueOnce([mockTransferLog(addr1, 5_000_000n, 105), mockTransferLog(addr2, 20_000_000n, 107)]);
 
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 100,
+      watchedAddresses: [addr1, addr2],
       onPayment: (evt) => {
         events.push(evt);
       },
@@ -111,18 +112,34 @@ describe("EvmWatcher", () => {
   });
 
   it("does nothing when no new blocks", async () => {
-    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(99).toString(16)}`); // block 99, confirmed = 98
+    const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(99).toString(16)}`);
 
     const watcher = new EvmWatcher({
       chain: "base",
       token: "USDC",
       rpcCall: mockRpc,
       fromBlock: 100,
+      watchedAddresses: ["0xdeadbeef"],
       onPayment: vi.fn(),
     });
 
     await watcher.poll();
-    expect(watcher.cursor).toBe(100); // unchanged
-    expect(mockRpc).toHaveBeenCalledTimes(1); // only eth_blockNumber
+    expect(watcher.cursor).toBe(100);
+    expect(mockRpc).toHaveBeenCalledTimes(1);
+  });
+
+  it("early-returns when no watched addresses are set", async () => {
+    const mockRpc = vi.fn();
+
+    const watcher = new EvmWatcher({
+      chain: "base",
+      token: "USDC",
+      rpcCall: mockRpc,
+      fromBlock: 0,
+      onPayment: vi.fn(),
+    });
+
+    await watcher.poll();
+    expect(mockRpc).not.toHaveBeenCalled(); // no RPC calls at all
   });
 });

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

@@ -72,8 +72,10 @@ export async function createStablecoinCheckout(
     } catch (err: unknown) {
       // Unique constraint violation = another checkout claimed this index concurrently.
       // Retry with the next available index.
-      const msg = err instanceof Error ? err.message : "";
-      const isConflict = msg.includes("unique") || msg.includes("duplicate") || msg.includes("23505");
+      // PostgreSQL error code 23505 = unique_violation.
+      // Check structured code first, fall back to message for other drivers.
+      const code = (err as { code?: string }).code;
+      const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
       if (!isConflict || attempt === maxRetries) throw err;
     }
   }

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

@@ -8,9 +8,31 @@ const CHAINS: Record<EvmChain, ChainConfig> = {
     blockTimeMs: 2000,
     chainId: 8453,
   },
+  ethereum: {
+    chain: "ethereum",
+    rpcUrl: process.env.EVM_RPC_ETHEREUM ?? "http://geth:8545",
+    confirmations: 12,
+    blockTimeMs: 12000,
+    chainId: 1,
+  },
+  arbitrum: {
+    chain: "arbitrum",
+    rpcUrl: process.env.EVM_RPC_ARBITRUM ?? "http://nitro:8547",
+    confirmations: 1,
+    blockTimeMs: 250,
+    chainId: 42161,
+  },
+  polygon: {
+    chain: "polygon",
+    rpcUrl: process.env.EVM_RPC_POLYGON ?? "http://bor:8545",
+    confirmations: 32,
+    blockTimeMs: 2000,
+    chainId: 137,
+  },
 };
 
 const TOKENS: Partial<Record<`${StablecoinToken}:${EvmChain}`, TokenConfig>> = {
+  // --- Base ---
   "USDC:base": {
     token: "USDC",
     chain: "base",
@@ -29,6 +51,57 @@ const TOKENS: Partial<Record<`${StablecoinToken}:${EvmChain}`, TokenConfig>> = {
     contractAddress: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
     decimals: 18,
   },
+  // --- Ethereum ---
+  "USDC:ethereum": {
+    token: "USDC",
+    chain: "ethereum",
+    contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    decimals: 6,
+  },
+  "USDT:ethereum": {
+    token: "USDT",
+    chain: "ethereum",
+    contractAddress: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+    decimals: 6,
+  },
+  "DAI:ethereum": {
+    token: "DAI",
+    chain: "ethereum",
+    contractAddress: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+    decimals: 18,
+  },
+  // --- Arbitrum ---
+  "USDC:arbitrum": {
+    token: "USDC",
+    chain: "arbitrum",
+    contractAddress: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    decimals: 6,
+  },
+  "USDT:arbitrum": {
+    token: "USDT",
+    chain: "arbitrum",
+    contractAddress: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+    decimals: 6,
+  },
+  "DAI:arbitrum": {
+    token: "DAI",
+    chain: "arbitrum",
+    contractAddress: "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1",
+    decimals: 18,
+  },
+  // --- Polygon ---
+  "USDC:polygon": {
+    token: "USDC",
+    chain: "polygon",
+    contractAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    decimals: 6,
+  },
+  "USDT:polygon": {
+    token: "USDT",
+    chain: "polygon",
+    contractAddress: "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
+    decimals: 6,
+  },
 };
 
 export function getChainConfig(chain: EvmChain): ChainConfig {

package/src/billing/crypto/evm/types.ts

@@ -1,5 +1,5 @@
 /** Supported EVM chains. */
-export type EvmChain = "base";
+export type EvmChain = "base" | "ethereum" | "arbitrum" | "polygon";
 
 /** Supported stablecoin tokens. */
 export type StablecoinToken = "USDC" | "USDT" | "DAI";

package/src/billing/crypto/evm/watcher.ts

@@ -61,6 +61,8 @@ export class EvmWatcher {
 
   /** Poll for new Transfer events. Call on an interval. */
   async poll(): Promise<void> {
+    if (this._watchedAddresses.length === 0) return; // nothing to watch
+
     const latestHex = (await this.rpc("eth_blockNumber", [])) as string;
     const latest = Number.parseInt(latestHex, 16);
     const confirmed = latest - this.confirmations;

package/src/billing/crypto/index.ts

@@ -1,4 +1,5 @@
-export type { CryptoChargeRecord, ICryptoChargeRepository, StablecoinChargeInput } from "./charge-store.js";
+export * from "./btc/index.js";
+export type { CryptoChargeRecord, CryptoDepositChargeInput, ICryptoChargeRepository } from "./charge-store.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
 export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
 export type { CryptoConfig } from "./client.js";

package/src/db/schema/crypto.ts

@@ -31,7 +31,7 @@ export const cryptoCharges = pgTable(
     index("idx_crypto_charges_status").on(table.status),
     index("idx_crypto_charges_created").on(table.createdAt),
     index("idx_crypto_charges_deposit_address").on(table.depositAddress),
-    // uniqueIndex would be ideal but drizzle pgTable helper doesn't support it inline.
+    // Unique indexes use WHERE IS NOT NULL partial indexes (declared in migration SQL).
     // Enforced via migration: CREATE UNIQUE INDEX.
   ],
 );