@wopr-network/platform-core 1.14.8 → 1.16.0

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

@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from "vitest";
+import { EvmWatcher } from "../watcher.js";
+
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+
+function mockTransferLog(to: string, amount: bigint, blockNumber: number) {
+  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: { 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
+
+    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: unknown[] = [];
+    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: { 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
+      ]);
+
+    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/src/billing/crypto/evm/address-gen.ts

@@ -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: string, index: number): `0x${string}` {
+  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("")}` as `0x${string}`;
+  return publicKeyToAddress(hexPubKey);
+}
+
+/** Validate that a string is an xpub (not xprv). */
+export function isValidXpub(key: string): boolean {
+  if (!key.startsWith("xpub")) return false;
+  try {
+    HDKey.fromExtendedKey(key);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,82 @@
+import { Credit } from "../../../credits/credit.js";
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import { deriveDepositAddress } from "./address-gen.js";
+import { getTokenConfig, tokenAmountFromCents } from "./config.js";
+import type { StablecoinCheckoutOpts } from "./types.js";
+
+export 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 async function createStablecoinCheckout(
+  deps: StablecoinCheckoutDeps,
+  opts: StablecoinCheckoutOpts,
+): Promise<StablecoinCheckoutResult> {
+  if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_STABLECOIN_USD) {
+    throw new Error(`Minimum payment amount is $${MIN_STABLECOIN_USD}`);
+  }
+
+  const tokenCfg = getTokenConfig(opts.token, opts.chain);
+
+  // Convert dollars to integer cents via Credit (no floating point in billing path).
+  const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
+  const rawAmount = tokenAmountFromCents(amountUsdCents, tokenCfg.decimals);
+
+  const maxRetries = 3;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+    const depositAddress = deriveDepositAddress(deps.xpub, derivationIndex);
+    const referenceId = `sc:${opts.chain}:${opts.token.toLowerCase()}:${depositAddress.toLowerCase()}`;
+
+    try {
+      await deps.chargeStore.createStablecoinCharge({
+        referenceId,
+        tenantId: opts.tenant,
+        amountUsdCents,
+        chain: opts.chain,
+        token: opts.token,
+        depositAddress: depositAddress.toLowerCase(),
+        derivationIndex,
+      });
+
+      return {
+        depositAddress,
+        amountRaw: rawAmount.toString(),
+        amountUsd: opts.amountUsd,
+        chain: opts.chain,
+        token: opts.token,
+        referenceId,
+      };
+    } 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");
+      if (!isConflict || attempt === maxRetries) throw err;
+    }
+  }
+
+  throw new Error("Failed to claim derivation index after retries");
+}

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

@@ -0,0 +1,50 @@
+import type { ChainConfig, EvmChain, StablecoinToken, TokenConfig } from "./types.js";
+
+const CHAINS: Record<EvmChain, ChainConfig> = {
+  base: {
+    chain: "base",
+    rpcUrl: process.env.EVM_RPC_BASE ?? "http://op-geth:8545",
+    confirmations: 1,
+    blockTimeMs: 2000,
+    chainId: 8453,
+  },
+};
+
+const TOKENS: Record<`${StablecoinToken}:${EvmChain}`, TokenConfig> = {
+  "USDC:base": {
+    token: "USDC",
+    chain: "base",
+    contractAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    decimals: 6,
+  },
+};
+
+export function getChainConfig(chain: EvmChain): ChainConfig {
+  const cfg = CHAINS[chain];
+  if (!cfg) throw new Error(`Unsupported chain: ${chain}`);
+  return cfg;
+}
+
+export function getTokenConfig(token: StablecoinToken, chain: EvmChain): TokenConfig {
+  const key = `${token}:${chain}` as const;
+  const cfg = TOKENS[key];
+  if (!cfg) throw new Error(`Unsupported token ${token} on ${chain}`);
+  return cfg;
+}
+
+/**
+ * Convert USD cents (integer) to token raw amount (BigInt).
+ * Stablecoins are 1:1 USD. Integer math only.
+ */
+export function tokenAmountFromCents(cents: number, decimals: number): bigint {
+  if (!Number.isInteger(cents)) throw new Error("cents must be an integer");
+  return (BigInt(cents) * 10n ** BigInt(decimals)) / 100n;
+}
+
+/**
+ * Convert token raw amount (BigInt) to USD cents (integer).
+ * Truncates fractional cents.
+ */
+export function centsFromTokenAmount(rawAmount: bigint, decimals: number): number {
+  return Number((rawAmount * 100n) / 10n ** BigInt(decimals));
+}

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

@@ -0,0 +1,16 @@
+export { deriveDepositAddress, isValidXpub } from "./address-gen.js";
+export type { StablecoinCheckoutDeps, StablecoinCheckoutResult } from "./checkout.js";
+export { createStablecoinCheckout, MIN_STABLECOIN_USD } from "./checkout.js";
+export { centsFromTokenAmount, getChainConfig, getTokenConfig, tokenAmountFromCents } from "./config.js";
+export type { EvmSettlerDeps } from "./settler.js";
+export { settleEvmPayment } from "./settler.js";
+export type {
+  ChainConfig,
+  EvmChain,
+  EvmPaymentEvent,
+  StablecoinCheckoutOpts,
+  StablecoinToken,
+  TokenConfig,
+} from "./types.js";
+export type { EvmWatcherOpts } from "./watcher.js";
+export { createRpcCaller, EvmWatcher } from "./watcher.js";

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

@@ -0,0 +1,79 @@
+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 { EvmPaymentEvent } from "./types.js";
+
+export interface EvmSettlerDeps {
+  chargeStore: Pick<ICryptoChargeRepository, "getByDepositAddress" | "updateStatus" | "markCredited">;
+  creditLedger: Pick<ILedger, "credit" | "hasReferenceId">;
+  onCreditsPurchased?: (tenantId: string, ledger: ILedger) => Promise<string[]>;
+}
+
+/**
+ * Settle an EVM payment event — look up charge by deposit address, credit ledger.
+ *
+ * Same idempotency pattern as handleCryptoWebhook():
+ *   Primary: creditLedger.hasReferenceId() — atomic in ledger transaction
+ *   Secondary: chargeStore.markCredited() — advisory
+ *
+ * Credits the CHARGE amount (not the transfer amount) for overpayment safety.
+ *
+ * CRITICAL: charge.amountUsdCents is in USD cents (integer).
+ * Credit.fromCents() converts cents → nanodollars for the ledger.
+ * Never pass raw cents to the ledger — always go through Credit.fromCents().
+ */
+export async function settleEvmPayment(deps: EvmSettlerDeps, event: EvmPaymentEvent): Promise<CryptoWebhookResult> {
+  const { chargeStore, creditLedger } = deps;
+
+  const charge = await chargeStore.getByDepositAddress(event.to.toLowerCase());
+  if (!charge) {
+    return { handled: false, status: "Settled" };
+  }
+
+  // Update charge status to Settled.
+  await chargeStore.updateStatus(charge.referenceId, "Settled");
+
+  // Charge-level idempotency: if this charge was already credited (by any transfer),
+  // reject. Prevents double-credit when a user sends two transactions to the same address.
+  if (charge.creditedAt != null) {
+    return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+  }
+
+  // Transfer-level idempotency: if this specific tx was already processed, skip.
+  const creditRef = `evm:${event.chain}:${event.txHash}:${event.logIndex}`;
+  if (await creditLedger.hasReferenceId(creditRef)) {
+    return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+  }
+
+  // Reject underpayment — transfer must cover the charge amount.
+  if (event.amountUsdCents < charge.amountUsdCents) {
+    return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+  }
+
+  // Credit the CHARGE amount (NOT the transfer amount — overpayment stays in wallet).
+  // charge.amountUsdCents is in USD cents (integer).
+  // Credit.fromCents() converts to nanodollars for the ledger.
+  const creditCents = charge.amountUsdCents;
+  await creditLedger.credit(charge.tenantId, Credit.fromCents(creditCents), "purchase", {
+    description: `Stablecoin credit purchase (${event.token} on ${event.chain}, tx: ${event.txHash})`,
+    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/evm/types.ts

@@ -0,0 +1,45 @@
+/** Supported EVM chains. */
+export type EvmChain = "base";
+
+/** Supported stablecoin tokens. */
+export type StablecoinToken = "USDC";
+
+/** Chain configuration. */
+export interface ChainConfig {
+  readonly chain: EvmChain;
+  readonly rpcUrl: string;
+  readonly confirmations: number;
+  readonly blockTimeMs: number;
+  readonly chainId: number;
+}
+
+/** Token configuration on a specific chain. */
+export interface TokenConfig {
+  readonly token: StablecoinToken;
+  readonly chain: EvmChain;
+  readonly contractAddress: `0x${string}`;
+  readonly decimals: number;
+}
+
+/** Event emitted when a Transfer is detected and confirmed. */
+export interface EvmPaymentEvent {
+  readonly chain: EvmChain;
+  readonly token: StablecoinToken;
+  readonly from: string;
+  readonly to: string;
+  /** Raw token amount (BigInt as string for serialization). */
+  readonly rawAmount: string;
+  /** USD cents equivalent (integer). */
+  readonly amountUsdCents: number;
+  readonly txHash: string;
+  readonly blockNumber: number;
+  readonly logIndex: number;
+}
+
+/** Options for creating a stablecoin checkout. */
+export interface StablecoinCheckoutOpts {
+  tenant: string;
+  amountUsd: number;
+  chain: EvmChain;
+  token: StablecoinToken;
+}

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

@@ -0,0 +1,126 @@
+import { centsFromTokenAmount, getChainConfig, getTokenConfig } from "./config.js";
+import type { EvmChain, EvmPaymentEvent, StablecoinToken } from "./types.js";
+
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+
+type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;
+
+export interface EvmWatcherOpts {
+  chain: EvmChain;
+  token: StablecoinToken;
+  rpcCall: RpcCall;
+  fromBlock: number;
+  onPayment: (event: EvmPaymentEvent) => void | Promise<void>;
+  /** Active deposit addresses to watch. Filters eth_getLogs by topic[2] (to address). */
+  watchedAddresses?: string[];
+}
+
+interface RpcLog {
+  address: string;
+  topics: string[];
+  data: string;
+  blockNumber: string;
+  transactionHash: string;
+  logIndex: string;
+}
+
+export class EvmWatcher {
+  private _cursor: number;
+  private readonly chain: EvmChain;
+  private readonly token: StablecoinToken;
+  private readonly rpc: RpcCall;
+  private readonly onPayment: EvmWatcherOpts["onPayment"];
+  private readonly confirmations: number;
+  private readonly contractAddress: string;
+  private readonly decimals: number;
+  private _watchedAddresses: string[];
+
+  constructor(opts: EvmWatcherOpts) {
+    this.chain = opts.chain;
+    this.token = opts.token;
+    this.rpc = opts.rpcCall;
+    this._cursor = opts.fromBlock;
+    this.onPayment = opts.onPayment;
+    this._watchedAddresses = (opts.watchedAddresses ?? []).map((a) => a.toLowerCase());
+
+    const chainCfg = getChainConfig(opts.chain);
+    const tokenCfg = getTokenConfig(opts.token, opts.chain);
+    this.confirmations = chainCfg.confirmations;
+    this.contractAddress = tokenCfg.contractAddress.toLowerCase();
+    this.decimals = tokenCfg.decimals;
+  }
+
+  /** Update the set of watched deposit addresses (e.g. after a new checkout). */
+  setWatchedAddresses(addresses: string[]): void {
+    this._watchedAddresses = addresses.map((a) => a.toLowerCase());
+  }
+
+  get cursor(): number {
+    return this._cursor;
+  }
+
+  /** Poll for new Transfer events. Call on an interval. */
+  async poll(): Promise<void> {
+    const latestHex = (await this.rpc("eth_blockNumber", [])) as string;
+    const latest = Number.parseInt(latestHex, 16);
+    const confirmed = latest - this.confirmations;
+
+    if (confirmed < this._cursor) return;
+
+    // Filter by topic[2] (to address) when watched addresses are set.
+    // This avoids fetching ALL USDC transfers on the chain (millions/day on Base).
+    // topic[2] values are 32-byte zero-padded: 0x000000000000000000000000<address>
+    const toFilter =
+      this._watchedAddresses.length > 0
+        ? this._watchedAddresses.map((a) => `0x000000000000000000000000${a.slice(2)}`)
+        : null;
+
+    const logs = (await this.rpc("eth_getLogs", [
+      {
+        address: this.contractAddress,
+        topics: [TRANSFER_TOPIC, null, toFilter],
+        fromBlock: `0x${this._cursor.toString(16)}`,
+        toBlock: `0x${confirmed.toString(16)}`,
+      },
+    ])) as RpcLog[];
+
+    for (const log of logs) {
+      const to = `0x${log.topics[2].slice(26)}`.toLowerCase();
+      const from = `0x${log.topics[1].slice(26)}`.toLowerCase();
+      const rawAmount = BigInt(log.data);
+      const amountUsdCents = centsFromTokenAmount(rawAmount, this.decimals);
+
+      const event: EvmPaymentEvent = {
+        chain: this.chain,
+        token: this.token,
+        from,
+        to,
+        rawAmount: rawAmount.toString(),
+        amountUsdCents,
+        txHash: log.transactionHash,
+        blockNumber: Number.parseInt(log.blockNumber, 16),
+        logIndex: Number.parseInt(log.logIndex, 16),
+      };
+
+      await this.onPayment(event);
+    }
+
+    this._cursor = confirmed + 1;
+  }
+}
+
+/** Create an RPC caller for a given URL (plain JSON-RPC over fetch). */
+export function createRpcCaller(rpcUrl: string): RpcCall {
+  let id = 0;
+  return async (method: string, params: unknown[]): Promise<unknown> => {
+    const res = await fetch(rpcUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params }),
+    });
+    if (!res.ok) throw new Error(`RPC ${method} failed: ${res.status}`);
+    const data = (await res.json()) as { result?: unknown; error?: { message: string } };
+    if (data.error) throw new Error(`RPC ${method} error: ${data.error.message}`);
+    return data.result;
+  };
+}

package/src/billing/crypto/index.ts

@@ -0,0 +1,16 @@
+export type { CryptoChargeRecord, ICryptoChargeRepository, StablecoinChargeInput } 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";
+export { BTCPayClient, loadCryptoConfig } from "./client.js";
+export * from "./evm/index.js";
+export type {
+  CryptoBillingConfig,
+  CryptoCheckoutOpts,
+  CryptoPaymentState,
+  CryptoWebhookPayload,
+  CryptoWebhookResult,
+} from "./types.js";
+export { mapBtcPayEventToStatus } from "./types.js";
+export type { CryptoWebhookDeps } from "./webhook.js";
+export { handleCryptoWebhook, verifyCryptoWebhookSignature } from "./webhook.js";

package/src/billing/crypto/types.ts

@@ -0,0 +1,83 @@
+/** BTCPay Server invoice states (Greenfield API v1). */
+export type CryptoPaymentState = "New" | "Processing" | "Expired" | "Invalid" | "Settled";
+
+/** Options for creating a crypto payment session. */
+export interface CryptoCheckoutOpts {
+  /** Internal tenant ID. */
+  tenant: string;
+  /** Amount in USD (minimum $10). */
+  amountUsd: number;
+}
+
+/** Webhook payload received from BTCPay Server (InvoiceSettled event). */
+export interface CryptoWebhookPayload {
+  /** BTCPay delivery ID (for deduplication). */
+  deliveryId: string;
+  /** Webhook ID. */
+  webhookId: string;
+  /** Original delivery ID (same as deliveryId on first delivery). */
+  originalDeliveryId: string;
+  /** Whether this is a redelivery. */
+  isRedelivery: boolean;
+  /** Event type (e.g. "InvoiceSettled", "InvoiceProcessing", "InvoiceExpired"). */
+  type: string;
+  /** Unix timestamp. */
+  timestamp: number;
+  /** BTCPay store ID. */
+  storeId: string;
+  /** BTCPay invoice ID. */
+  invoiceId: string;
+  /** Invoice metadata (echoed from creation). */
+  metadata: Record<string, unknown>;
+  /** Whether admin manually marked as settled (InvoiceSettled only). */
+  manuallyMarked?: boolean;
+  /** Whether customer overpaid (InvoiceSettled only). */
+  overPaid?: boolean;
+  /** Whether invoice was partially paid (InvoiceExpired only). */
+  partiallyPaid?: boolean;
+}
+
+/** Configuration for BTCPay Server integration. */
+export interface CryptoBillingConfig {
+  /** BTCPay API key (from Account > API keys). */
+  apiKey: string;
+  /** BTCPay Server base URL. */
+  baseUrl: string;
+  /** BTCPay store ID. */
+  storeId: string;
+}
+
+/** Result of processing a crypto webhook event. */
+export interface CryptoWebhookResult {
+  handled: boolean;
+  status: string;
+  tenant?: string;
+  creditedCents?: number;
+  reactivatedBots?: string[];
+  duplicate?: boolean;
+}
+
+/**
+ * Map BTCPay webhook event type string to a CryptoPaymentState.
+ *
+ * Shared between the core (billing) and consumer (monetization) webhook handlers.
+ * Throws on unrecognized event types to surface integration errors early.
+ */
+export function mapBtcPayEventToStatus(eventType: string): CryptoPaymentState {
+  switch (eventType) {
+    case "InvoiceCreated":
+      return "New";
+    case "InvoiceReceivedPayment":
+    case "InvoiceProcessing":
+      return "Processing";
+    case "InvoiceSettled":
+    case "InvoicePaymentSettled":
+      return "Settled";
+    case "InvoiceExpired":
+      return "Expired";
+    case "InvoiceInvalid":
+      return "Invalid";
+    default:
+      throw new Error(`Unknown BTCPay event type: ${eventType}`);
+  }
+}