@wopr-network/platform-core 1.48.0 → 1.49.1

package/src/billing/crypto/oracle/composite.ts

@@ -0,0 +1,35 @@
+import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+
+/**
+ * Composite oracle — tries primary (Chainlink on-chain), falls back to secondary (CoinGecko).
+ *
+ * When a feedAddress is provided (from payment_methods.oracle_address), the primary
+ * oracle is used with that address. When no feed exists or the primary fails,
+ * the fallback oracle is consulted.
+ */
+export class CompositeOracle implements IPriceOracle {
+  constructor(
+    private readonly primary: IPriceOracle,
+    private readonly fallback: IPriceOracle,
+  ) {}
+
+  async getPrice(asset: PriceAsset, feedAddress?: `0x${string}`): Promise<PriceResult> {
+    // If a specific feed address is provided, try the primary (Chainlink) first
+    if (feedAddress) {
+      try {
+        return await this.primary.getPrice(asset, feedAddress);
+      } catch {
+        // Primary failed (stale, network error) — fall through to fallback
+      }
+    }
+
+    // Try primary without explicit feed (uses built-in feed map for BTC/ETH)
+    try {
+      return await this.primary.getPrice(asset);
+    } catch {
+      // No feed configured or call failed — use fallback
+    }
+
+    return this.fallback.getPrice(asset);
+  }
+}

package/src/billing/crypto/oracle/convert.ts

@@ -1,38 +1,53 @@
 /**
- * Convert USD cents to native token amount using a price in cents.
+ * Price units: **microdollars** (1 microdollar = $0.000001 = 10^-6 USD).
  *
- * Formula: rawAmount = amountCents × 10^decimals / priceCents
+ * Why not cents? DOGE at $0.094 rounds to 9 cents — 6% error.
+ * Microdollars give 6 decimal places: $0.094147 = 94,147 microdollars.
+ *
+ * Chainlink feeds: 8 decimals → answer / 100 = microdollars.
+ * CoinGecko: Math.round(usd * 1_000_000) = microdollars.
+ * All math is integer bigint — no floating point.
+ */
+
+/** Microdollars per cent. Multiply amountCents by this to get microdollars. */
+const MICROS_PER_CENT = 10_000n;
+
+/**
+ * Convert USD cents to native token amount using a price in microdollars.
+ *
+ * Formula: rawAmount = (amountCents × 10_000) × 10^decimals / priceMicros
  *
  * Examples:
- *   $50 in ETH at $3,500:  centsToNative(5000, 350000, 18) = 14285714285714285n (≈0.01429 ETH)
- *   $50 in BTC at $65,000: centsToNative(5000, 6500000, 8)  = 76923n (76,923 sats ≈ 0.00077 BTC)
+ *   $50 in BTC at $70,315:  centsToNative(5000, 70_315_000_000, 8) = 71,119 sats
+ *   $50 in DOGE at $0.094:  centsToNative(5000, 94_147, 8) = 53,107,898,982 base units (531.08 DOGE)
  *
  * Integer math only. No floating point.
  */
-export function centsToNative(amountCents: number, priceCents: number, decimals: number): bigint {
+export function centsToNative(amountCents: number, priceMicros: number, decimals: number): bigint {
   if (!Number.isInteger(amountCents) || amountCents <= 0) {
     throw new Error(`amountCents must be a positive integer, got ${amountCents}`);
   }
-  if (!Number.isInteger(priceCents) || priceCents <= 0) {
-    throw new Error(`priceCents must be a positive integer, got ${priceCents}`);
+  if (!Number.isInteger(priceMicros) || priceMicros <= 0) {
+    throw new Error(`priceMicros must be a positive integer, got ${priceMicros}`);
   }
   if (!Number.isInteger(decimals) || decimals < 0) {
     throw new Error(`decimals must be a non-negative integer, got ${decimals}`);
   }
-  return (BigInt(amountCents) * 10n ** BigInt(decimals)) / BigInt(priceCents);
+  // Convert amountCents to microdollars to match priceMicros units
+  return (BigInt(amountCents) * MICROS_PER_CENT * 10n ** BigInt(decimals)) / BigInt(priceMicros);
 }
 
 /**
- * Convert native token amount back to USD cents using a price in cents.
+ * Convert native token amount back to USD cents using a price in microdollars.
  *
  * Inverse of centsToNative. Truncates fractional cents.
  *
  * Integer math only.
  */
-export function nativeToCents(rawAmount: bigint, priceCents: number, decimals: number): number {
+export function nativeToCents(rawAmount: bigint, priceMicros: number, decimals: number): number {
   if (rawAmount < 0n) throw new Error("rawAmount must be non-negative");
-  if (!Number.isInteger(priceCents) || priceCents <= 0) {
-    throw new Error(`priceCents must be a positive integer, got ${priceCents}`);
+  if (!Number.isInteger(priceMicros) || priceMicros <= 0) {
+    throw new Error(`priceMicros must be a positive integer, got ${priceMicros}`);
   }
-  return Number((rawAmount * BigInt(priceCents)) / 10n ** BigInt(decimals));
+  return Number((rawAmount * BigInt(priceMicros)) / (MICROS_PER_CENT * 10n ** BigInt(decimals)));
 }

package/src/billing/crypto/oracle/fixed.ts

@@ -2,22 +2,24 @@ import type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
 
 /**
  * Fixed-price oracle for testing and local dev (Anvil, regtest).
- * Returns hardcoded prices — no RPC calls.
+ * Returns hardcoded prices in microdollars — no RPC calls.
  */
 export class FixedPriceOracle implements IPriceOracle {
   private readonly prices: Record<string, number>;
 
   constructor(prices: Partial<Record<PriceAsset, number>> = {}) {
     this.prices = {
-      ETH: 350_000, // $3,500
-      BTC: 6_500_000, // $65,000
+      ETH: 3_500_000_000, // $3,500 in microdollars
+      BTC: 65_000_000_000, // $65,000 in microdollars
+      DOGE: 94_000, // $0.094 in microdollars
+      LTC: 55_000_000, // $55 in microdollars
       ...prices,
     };
   }
 
-  async getPrice(asset: PriceAsset): Promise<PriceResult> {
-    const priceCents = this.prices[asset];
-    if (priceCents === undefined) throw new Error(`No fixed price for ${asset}`);
-    return { priceCents, updatedAt: new Date() };
+  async getPrice(asset: PriceAsset, _feedAddress?: `0x${string}`): Promise<PriceResult> {
+    const priceMicros = this.prices[asset];
+    if (priceMicros === undefined) throw new Error(`No fixed price for ${asset}`);
+    return { priceMicros, updatedAt: new Date() };
   }
 }

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

@@ -1,5 +1,9 @@
 export type { ChainlinkOracleOpts } from "./chainlink.js";
 export { ChainlinkOracle } from "./chainlink.js";
+export type { CoinGeckoOracleOpts } from "./coingecko.js";
+export { CoinGeckoOracle } from "./coingecko.js";
+export { CompositeOracle } from "./composite.js";
 export { centsToNative, nativeToCents } from "./convert.js";
 export { FixedPriceOracle } from "./fixed.js";
 export type { IPriceOracle, PriceAsset, PriceResult } from "./types.js";
+export { AssetNotSupportedError } from "./types.js";

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

@@ -1,15 +1,28 @@
 /** Assets with Chainlink price feeds. */
 export type PriceAsset = string;
 
+/** Thrown when no oracle supports a given asset (not a transient failure). */
+export class AssetNotSupportedError extends Error {
+  constructor(asset: string) {
+    super(`No price oracle supports asset: ${asset}`);
+    this.name = "AssetNotSupportedError";
+  }
+}
+
 /** Result from a price oracle query. */
 export interface PriceResult {
-  /** USD cents per 1 unit of asset (integer). */
-  priceCents: number;
+  /** Microdollars per 1 unit of asset (integer, 10^-6 USD). */
+  priceMicros: number;
   /** When the price was last updated on-chain. */
   updatedAt: Date;
 }
 
 /** Read-only price oracle. */
 export interface IPriceOracle {
-  getPrice(asset: PriceAsset): Promise<PriceResult>;
+  /**
+   * Get the current USD price for an asset.
+   * @param asset — token symbol (e.g. "BTC", "DOGE")
+   * @param feedAddress — optional Chainlink feed address override (from payment_methods.oracle_address)
+   */
+  getPrice(asset: PriceAsset, feedAddress?: `0x${string}`): Promise<PriceResult>;
 }

package/src/billing/crypto/types.ts

@@ -1,6 +1,24 @@
 /** BTCPay Server invoice states (Greenfield API v1). */
 export type CryptoPaymentState = "New" | "Processing" | "Expired" | "Invalid" | "Settled";
 
+/** Charge status for the UI-facing payment lifecycle. */
+export type CryptoChargeStatus = "pending" | "partial" | "confirmed" | "expired" | "failed";
+
+/** Full charge record for UI display — includes partial payment progress and confirmations. */
+export interface CryptoCharge {
+  id: string;
+  tenantId: string;
+  chain: string;
+  status: CryptoChargeStatus;
+  amountExpectedCents: number;
+  amountReceivedCents: number;
+  confirmations: number;
+  confirmationsRequired: number;
+  txHash?: string;
+  credited: boolean;
+  createdAt: Date;
+}
+
 /** Options for creating a crypto payment session. */
 export interface CryptoCheckoutOpts {
   /** Internal tenant ID. */

package/src/billing/crypto/unified-checkout.ts

@@ -1,20 +1,9 @@
-import { Credit } from "../../credits/credit.js";
-import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
-import type { ICryptoChargeRepository } from "./charge-store.js";
-import { deriveDepositAddress } from "./evm/address-gen.js";
-import { centsToNative } from "./oracle/convert.js";
-import type { IPriceOracle } from "./oracle/types.js";
-import type { PaymentMethodRecord } from "./payment-method-store.js";
+import type { CryptoServiceClient } from "./client.js";
 
 export const MIN_CHECKOUT_USD = 10;
 
 export interface UnifiedCheckoutDeps {
-  chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
-  oracle: IPriceOracle;
-  evmXpub: string;
-  btcXpub?: string;
-  /** UTXO network override (auto-detected from node in production). Default: "mainnet". */
-  utxoNetwork?: "mainnet" | "testnet" | "regtest";
+  cryptoService: CryptoServiceClient;
 }
 
 export interface UnifiedCheckoutResult {
@@ -25,187 +14,39 @@ export interface UnifiedCheckoutResult {
   token: string;
   chain: string;
   referenceId: string;
-  /** For volatile assets: price at checkout time (USD cents per unit). */
-  priceCents?: number;
+  /** For volatile assets: price at checkout time (microdollars per unit, 10^-6 USD). */
+  priceMicros?: number;
 }
 
 /**
- * Unified checkout — one entry point for all payment methods.
+ * Unified checkout — delegates to CryptoServiceClient.createCharge().
  *
- * Looks up the method record, routes by type:
- *   - erc20: derives EVM address, computes token amount (1:1 USD for stablecoins)
- *   - native (ETH): derives EVM address, oracle-priced
- *   - native (BTC): derives BTC address, oracle-priced
- *
- * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ * The pay server handles xpub management, address derivation, and charge
+ * creation. This function is a thin wrapper that validates the amount
+ * and maps the response to `UnifiedCheckoutResult`.
  */
 export async function createUnifiedCheckout(
   deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  opts: { tenant: string; amountUsd: number },
+  chain: string,
+  opts: { tenant: string; amountUsd: number; callbackUrl?: string },
 ): Promise<UnifiedCheckoutResult> {
   if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_CHECKOUT_USD) {
     throw new Error(`Minimum payment amount is $${MIN_CHECKOUT_USD}`);
   }
 
-  const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
-
-  if (method.type === "erc20") {
-    return handleErc20(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-  }
-  if (method.type === "native" && method.chain === "base") {
-    return handleNativeEvm(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-  }
-  if (method.type === "native") {
-    return handleNativeUtxo(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
-  }
-
-  throw new Error(`Unsupported payment method type: ${method.type}/${method.token}`);
-}
-
-async function handleErc20(
-  deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  tenant: string,
-  amountUsdCents: number,
-  amountUsd: number,
-): Promise<UnifiedCheckoutResult> {
-  const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
+  const result = await deps.cryptoService.createCharge({
+    chain,
+    amountUsd: opts.amountUsd,
+    callbackUrl: opts.callbackUrl,
+  });
 
   return {
-    depositAddress,
-    displayAmount: `${amountUsd} ${method.token}`,
-    amountUsd,
-    token: method.token,
-    chain: method.chain,
-    referenceId: `erc20:${method.chain}:${depositAddress}`,
+    depositAddress: result.address,
+    displayAmount: result.displayAmount ?? `${opts.amountUsd} ${result.token}`,
+    amountUsd: opts.amountUsd,
+    token: result.token,
+    chain: result.chain,
+    referenceId: result.chargeId,
+    priceMicros: result.priceMicros,
   };
 }
-
-async function handleNativeEvm(
-  deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  tenant: string,
-  amountUsdCents: number,
-  amountUsd: number,
-): Promise<UnifiedCheckoutResult> {
-  const { priceCents } = await deps.oracle.getPrice("ETH");
-  const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
-  const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
-
-  const divisor = BigInt("1000000000000000000");
-  const whole = expectedWei / divisor;
-  const frac = (expectedWei % divisor).toString().padStart(18, "0").slice(0, 6);
-
-  return {
-    depositAddress,
-    displayAmount: `${whole}.${frac} ETH`,
-    amountUsd,
-    token: "ETH",
-    chain: method.chain,
-    referenceId: `${method.type}:${method.chain}:${depositAddress}`,
-    priceCents,
-  };
-}
-
-/**
- * Handle native UTXO coins (BTC, LTC, DOGE, BCH, etc.).
- * Uses the xpub from the payment method record (DB-driven).
- * Derives bech32 addresses for BTC/LTC, Base58 P2PKH for DOGE.
- */
-async function handleNativeUtxo(
-  deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  tenant: string,
-  amountUsdCents: number,
-  amountUsd: number,
-): Promise<UnifiedCheckoutResult> {
-  const xpub = method.xpub ?? deps.btcXpub;
-  if (!xpub) throw new Error(`${method.token} payments not configured (no xpub)`);
-
-  const { priceCents } = await deps.oracle.getPrice(method.token);
-  const rawAmount = centsToNative(amountUsdCents, priceCents, method.decimals);
-
-  const maxRetries = 3;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-
-    // Derive address by chain type
-    let depositAddress: string;
-    if (method.chain === "dogecoin") {
-      depositAddress = deriveP2pkhAddress(xpub, derivationIndex, "dogecoin");
-    } else {
-      depositAddress = deriveAddress(
-        xpub,
-        derivationIndex,
-        deps.utxoNetwork ?? "mainnet",
-        method.chain as "bitcoin" | "litecoin",
-      );
-    }
-
-    const referenceId = `${method.token.toLowerCase()}:${depositAddress}`;
-
-    try {
-      await deps.chargeStore.createStablecoinCharge({
-        referenceId,
-        tenantId: tenant,
-        amountUsdCents,
-        chain: method.chain,
-        token: method.token,
-        depositAddress,
-        derivationIndex,
-      });
-
-      const divisor = 10 ** method.decimals;
-      const displayAmt = (Number(rawAmount) / divisor).toFixed(method.decimals);
-      return {
-        depositAddress,
-        displayAmount: `${displayAmt} ${method.token}`,
-        amountUsd,
-        token: method.token,
-        chain: method.chain,
-        referenceId,
-        priceCents,
-      };
-    } catch (err: unknown) {
-      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;
-    }
-  }
-
-  throw new Error("Failed to claim derivation index after retries");
-}
-
-/** Derive an EVM deposit address and store the charge. Retries on unique conflict. */
-async function deriveAndStore(
-  deps: UnifiedCheckoutDeps,
-  method: PaymentMethodRecord,
-  tenant: string,
-  amountUsdCents: number,
-): Promise<string> {
-  const maxRetries = 3;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
-    const depositAddress = deriveDepositAddress(deps.evmXpub, derivationIndex);
-    const referenceId = `${method.type}:${method.chain}:${depositAddress}`;
-
-    try {
-      await deps.chargeStore.createStablecoinCharge({
-        referenceId,
-        tenantId: tenant,
-        amountUsdCents,
-        chain: method.chain,
-        token: method.token,
-        depositAddress,
-        derivationIndex,
-      });
-      return depositAddress;
-    } catch (err: unknown) {
-      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;
-    }
-  }
-  throw new Error("Failed to claim derivation index after retries");
-}

package/src/billing/crypto/watcher-service.ts

@@ -4,8 +4,8 @@
  * Payment flow:
  *   1. Watcher detects payment → handlePayment()
  *   2. Accumulate native amount (supports partial payments)
- *   3. When totalReceived >= expectedAmount → settle + credit
- *   4. Every payment (partial or full) enqueues a webhook delivery
+ *   3. When totalReceived >= expectedAmount AND confirmations >= required → confirmed + credit
+ *   4. Every payment/confirmation change enqueues a webhook delivery
  *   5. Outbox processor retries failed deliveries with exponential backoff
  *
  * Amount comparison is ALWAYS in native crypto units (sats, wei, token base units).
@@ -23,7 +23,7 @@ import type { EvmChain, EvmPaymentEvent, StablecoinToken } from "./evm/types.js"
 import { createRpcCaller, EvmWatcher } from "./evm/watcher.js";
 import type { IPriceOracle } from "./oracle/types.js";
 import type { IPaymentMethodStore } from "./payment-method-store.js";
-import type { CryptoPaymentState } from "./types.js";
+import type { CryptoChargeStatus } from "./types.js";
 
 const MAX_DELIVERY_ATTEMPTS = 10;
 const BACKOFF_BASE_MS = 5_000;
@@ -131,20 +131,34 @@ async function processDeliveries(
   return delivered;
 }
 
-// --- Payment handling (partial + full) ---
+// --- Payment handling (partial + full + confirmation tracking) ---
+
+export interface PaymentPayload {
+  txHash: string;
+  confirmations: number;
+  confirmationsRequired: number;
+  amountReceivedCents: number;
+  [key: string]: unknown;
+}
 
 /**
  * Handle a payment event. Accumulates partial payments in native units.
- * Settles when totalReceived >= expectedAmount. Fires webhook on every payment.
+ * Fires webhook on every payment/confirmation change with canonical statuses.
  *
- * @param nativeAmount — received amount in native base units (sats for BTC/DOGE, raw token units for ERC20)
+ * 3-phase webhook lifecycle:
+ *   1. Tx first seen -> status: "partial", confirmations: 0
+ *   2. Each new block -> status: "partial", confirmations: current
+ *   3. Threshold reached + full payment -> status: "confirmed"
+ *
+ * @param nativeAmount — received amount in native base units (sats for BTC/DOGE, raw token units for ERC20).
+ *                        Pass "0" for confirmation-only updates (no new payment, just more confirmations).
  */
-async function handlePayment(
+export async function handlePayment(
   db: DrizzleDb,
   chargeStore: ICryptoChargeRepository,
   address: string,
   nativeAmount: string,
-  payload: Record<string, unknown>,
+  payload: PaymentPayload,
   log: (msg: string, meta?: Record<string, unknown>) => void,
 ): Promise<void> {
   const charge = await chargeStore.getByDepositAddress(address);
@@ -156,41 +170,64 @@ async function handlePayment(
     return; // Already fully paid and credited
   }
 
-  // Accumulate: add this payment to the running total
+  const { confirmations, confirmationsRequired, amountReceivedCents, txHash } = payload;
+
+  // Accumulate: add this payment to the running total (if nativeAmount > 0)
   const prevReceived = BigInt(charge.receivedAmount ?? "0");
   const thisPayment = BigInt(nativeAmount);
   const totalReceived = (prevReceived + thisPayment).toString();
   const expected = BigInt(charge.expectedAmount ?? "0");
   const isFull = expected > 0n && BigInt(totalReceived) >= expected;
+  const isConfirmed = isFull && confirmations >= confirmationsRequired;
+
+  // Update received_amount in DB (only when there's a new payment)
+  if (thisPayment > 0n) {
+    await db
+      .update(cryptoCharges)
+      .set({ receivedAmount: totalReceived, filledAmount: totalReceived })
+      .where(eq(cryptoCharges.referenceId, charge.referenceId));
+  }
 
-  // Update received_amount in DB
-  await db
-    .update(cryptoCharges)
-    .set({ receivedAmount: totalReceived, filledAmount: totalReceived })
-    .where(eq(cryptoCharges.referenceId, charge.referenceId));
+  // Determine canonical status
+  const status: CryptoChargeStatus = isConfirmed ? "confirmed" : "partial";
 
-  if (isFull) {
-    const settled: CryptoPaymentState = "Settled";
-    await chargeStore.updateStatus(charge.referenceId, settled, charge.token ?? undefined, totalReceived);
+  // Update progress via new API
+  await chargeStore.updateProgress(charge.referenceId, {
+    status,
+    amountReceivedCents,
+    confirmations,
+    confirmationsRequired,
+    txHash,
+  });
+
+  if (isConfirmed) {
     await chargeStore.markCredited(charge.referenceId);
-    log("Charge settled", { chargeId: charge.referenceId, expected: expected.toString(), received: totalReceived });
+    log("Charge confirmed", {
+      chargeId: charge.referenceId,
+      confirmations,
+      confirmationsRequired,
+    });
   } else {
-    const processing: CryptoPaymentState = "Processing";
-    await chargeStore.updateStatus(charge.referenceId, processing, charge.token ?? undefined, totalReceived);
-    log("Partial payment", { chargeId: charge.referenceId, expected: expected.toString(), received: totalReceived });
+    log("Payment progress", {
+      chargeId: charge.referenceId,
+      confirmations,
+      confirmationsRequired,
+      received: totalReceived,
+    });
   }
 
-  // Webhook on every payment — product shows progress to user
+  // Webhook on every event — product shows confirmation progress to user
   if (charge.callbackUrl) {
     await enqueueWebhook(db, charge.referenceId, charge.callbackUrl, {
       chargeId: charge.referenceId,
       chain: charge.chain,
       address: charge.depositAddress,
-      expectedAmount: expected.toString(),
-      receivedAmount: totalReceived,
-      amountUsdCents: charge.amountUsdCents,
-      status: isFull ? "confirmed" : "partial",
-      ...payload,
+      amountExpectedCents: charge.amountUsdCents,
+      amountReceivedCents,
+      confirmations,
+      confirmationsRequired,
+      txHash,
+      status,
     });
   }
 }
@@ -245,8 +282,14 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
       oracle,
       cursorStore,
       onPayment: async (event: BtcPaymentEvent) => {
-        log("UTXO payment", { chain: method.chain, address: event.address, txid: event.txid, sats: event.amountSats });
-        // Pass native amount (sats) — NOT USD cents
+        log("UTXO payment", {
+          chain: method.chain,
+          address: event.address,
+          txid: event.txid,
+          sats: event.amountSats,
+          confirmations: event.confirmations,
+          confirmationsRequired: event.confirmationsRequired,
+        });
         await handlePayment(
           db,
           chargeStore,
@@ -255,6 +298,8 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
           {
             txHash: event.txid,
             confirmations: event.confirmations,
+            confirmationsRequired: event.confirmationsRequired,
+            amountReceivedCents: event.amountUsdCents,
           },
           log,
         );
@@ -323,8 +368,14 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
       watchedAddresses: chainAddresses,
       cursorStore,
       onPayment: async (event: EvmPaymentEvent) => {
-        log("EVM payment", { chain: event.chain, token: event.token, to: event.to, txHash: event.txHash });
-        // Pass native amount (raw token units) — NOT USD cents
+        log("EVM payment", {
+          chain: event.chain,
+          token: event.token,
+          to: event.to,
+          txHash: event.txHash,
+          confirmations: event.confirmations,
+          confirmationsRequired: event.confirmationsRequired,
+        });
         await handlePayment(
           db,
           chargeStore,
@@ -332,7 +383,9 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
           event.rawAmount,
           {
             txHash: event.txHash,
-            confirmations: method.confirmations,
+            confirmations: event.confirmations,
+            confirmationsRequired: event.confirmationsRequired,
+            amountReceivedCents: event.amountUsdCents,
           },
           log,
         );

package/src/db/schema/crypto.ts

@@ -30,6 +30,14 @@ export const cryptoCharges = pgTable(
     expectedAmount: text("expected_amount"),
     /** Running total of received crypto in native units. Accumulates across partial payments. */
     receivedAmount: text("received_amount"),
+    /** Number of blockchain confirmations observed so far. */
+    confirmations: integer("confirmations").notNull().default(0),
+    /** Required confirmations for settlement (copied from payment method at creation). */
+    confirmationsRequired: integer("confirmations_required").notNull().default(1),
+    /** Blockchain transaction hash for the payment. */
+    txHash: text("tx_hash"),
+    /** Amount received so far in USD cents (integer). Converted from crypto at time of receipt. */
+    amountReceivedCents: integer("amount_received_cents").notNull().default(0),
   },
   (table) => [
     index("idx_crypto_charges_tenant").on(table.tenantId),

package/src/monetization/crypto/__tests__/webhook.test.ts

@@ -164,7 +164,8 @@ describe("handleCryptoWebhook (monetization layer)", () => {
       await handleCryptoWebhook(deps, makePayload({ status: "partial" }));
 
       const charge = await chargeStore.getByReferenceId("chg-test-001");
-      expect(charge?.status).toBe("partial");
+      // DB stores legacy status values; "partial" maps to "Processing" internally
+      expect(charge?.status).toBe("Processing");
     });
 
     it("settles charge when status is confirmed", async () => {