@wopr-network/platform-core 1.48.0 → 1.49.0

package/dist/billing/crypto/key-server-webhook.js

@@ -1,32 +1,76 @@
 /**
- * Key Server webhook handler — processes payment confirmations from the
+ * Key Server webhook handler — processes payment events from the
  * centralized crypto key server.
  *
+ * Called on EVERY status update (not just terminal):
+ *   - "partial" / "Processing" → update progress, no credit
+ *   - "confirmed" / "Settled" → update progress + credit ledger
+ *   - "expired" / "failed" → update progress, no credit
+ *
  * Payload shape (from watcher-service.ts):
  * {
  *   chargeId: "btc:bc1q...",
  *   chain: "bitcoin",
  *   address: "bc1q...",
- *   amountUsdCents: 5000,
+ *   amountReceivedCents: 5000,
  *   status: "confirmed",
  *   txHash: "abc123...",
  *   amountReceived: "50000 sats",
- *   confirmations: 6
+ *   confirmations: 6,
+ *   confirmationsRequired: 6
  * }
  *
  * Replaces handleCryptoWebhook() for products using the key server.
  */
 import { Credit } from "../../credits/credit.js";
 /**
- * Process a payment confirmation from the crypto key server.
+ * Map legacy/watcher status strings to canonical CryptoChargeStatus.
+ * Accepts both old BTCPay-style ("Settled", "Processing") and new canonical ("confirmed", "partial").
+ */
+export function normalizeStatus(raw) {
+    switch (raw) {
+        case "confirmed":
+        case "Settled":
+        case "InvoiceSettled":
+            return "confirmed";
+        case "partial":
+        case "Processing":
+        case "InvoiceProcessing":
+        case "InvoiceReceivedPayment":
+            return "partial";
+        case "expired":
+        case "Expired":
+        case "InvoiceExpired":
+            return "expired";
+        case "failed":
+        case "Invalid":
+        case "InvoiceInvalid":
+            return "failed";
+        case "pending":
+        case "New":
+        case "InvoiceCreated":
+            return "pending";
+        default:
+            return "pending";
+    }
+}
+/**
+ * Process a payment webhook from the crypto key server.
  *
- * Credits the ledger when status is "confirmed".
- * Idempotency: ledger referenceId + replay guard (same pattern as Stripe handler).
+ * Idempotency: deduplicate by chargeId + status + confirmations so that
+ * multiple progress updates (0→1→2→...→6 confirmations) each get through,
+ * but exact duplicates are rejected.
  */
 export async function handleKeyServerWebhook(deps, payload) {
     const { chargeStore, creditLedger } = deps;
-    // Replay guard: deduplicate by chargeId
-    const dedupeKey = `ks:${payload.chargeId}`;
+    const status = normalizeStatus(payload.status);
+    const confirmations = payload.confirmations ?? 0;
+    const confirmationsRequired = payload.confirmationsRequired ?? 1;
+    // Support deprecated amountUsdCents field as fallback
+    const amountReceivedCents = payload.amountReceivedCents ?? payload.amountUsdCents ?? 0;
+    // Replay guard: deduplicate by chargeId + status + confirmations
+    // This allows multiple progress updates for the same charge
+    const dedupeKey = `ks:${payload.chargeId}:${status}:${confirmations}`;
     if (await deps.replayGuard.isDuplicate(dedupeKey, "crypto")) {
         return { handled: true, duplicate: true };
     }
@@ -35,14 +79,29 @@ export async function handleKeyServerWebhook(deps, payload) {
     if (!charge) {
         return { handled: false };
     }
-    if (payload.status === "confirmed") {
-        // Only settle when payment is confirmed
-        await chargeStore.updateStatus(payload.chargeId, "Settled", charge.token ?? undefined, payload.amountReceived);
+    // Always update progress on every webhook
+    await chargeStore.updateProgress(payload.chargeId, {
+        status,
+        amountReceivedCents,
+        confirmations,
+        confirmationsRequired,
+        txHash: payload.txHash,
+    });
+    // Also call deprecated updateStatus for backward compat with downstream consumers
+    const legacyStatusMap = {
+        pending: "New",
+        partial: "Processing",
+        confirmed: "Settled",
+        expired: "Expired",
+        failed: "Invalid",
+    };
+    await chargeStore.updateStatus(payload.chargeId, legacyStatusMap[status], charge.token ?? undefined, payload.amountReceived);
+    if (status === "confirmed") {
         // Idempotency: check ledger referenceId (atomic, same as BTCPay handler)
         const creditRef = `crypto:${payload.chargeId}`;
         if (await creditLedger.hasReferenceId(creditRef)) {
             await deps.replayGuard.markSeen(dedupeKey, "crypto");
-            return { handled: true, duplicate: true, tenant: charge.tenantId };
+            return { handled: true, duplicate: true, tenant: charge.tenantId, status, confirmations, confirmationsRequired };
         }
         // Credit the original USD amount requested.
         // charge.amountUsdCents is integer cents. Credit.fromCents() → nanodollars.
@@ -64,10 +123,12 @@ export async function handleKeyServerWebhook(deps, payload) {
             tenant: charge.tenantId,
             creditedCents: charge.amountUsdCents,
             reactivatedBots,
+            status,
+            confirmations,
+            confirmationsRequired,
         };
     }
-    // Non-confirmed status — update status but don't settle or credit
-    await chargeStore.updateStatus(payload.chargeId, payload.status, charge.token ?? undefined, payload.amountReceived);
+    // Non-confirmed status — progress already updated above, no credit
     await deps.replayGuard.markSeen(dedupeKey, "crypto");
-    return { handled: true, tenant: charge.tenantId };
+    return { handled: true, tenant: charge.tenantId, status, confirmations, confirmationsRequired };
 }

package/dist/billing/crypto/types.d.ts

@@ -1,5 +1,21 @@
 /** 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/dist/billing/crypto/unified-checkout.d.ts

@@ -1,14 +1,7 @@
-import type { ICryptoChargeRepository } from "./charge-store.js";
-import type { IPriceOracle } from "./oracle/types.js";
-import type { PaymentMethodRecord } from "./payment-method-store.js";
+import type { CryptoServiceClient } from "./client.js";
 export declare 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 {
     depositAddress: string;
@@ -22,16 +15,14 @@ export interface UnifiedCheckoutResult {
     priceCents?: 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 declare function createUnifiedCheckout(deps: UnifiedCheckoutDeps, method: PaymentMethodRecord, opts: {
+export declare function createUnifiedCheckout(deps: UnifiedCheckoutDeps, chain: string, opts: {
     tenant: string;
     amountUsd: number;
+    callbackUrl?: string;
 }): Promise<UnifiedCheckoutResult>;

package/dist/billing/crypto/unified-checkout.js

@@ -1,141 +1,27 @@
-import { Credit } from "../../credits/credit.js";
-import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
-import { deriveDepositAddress } from "./evm/address-gen.js";
-import { centsToNative } from "./oracle/convert.js";
 export const MIN_CHECKOUT_USD = 10;
 /**
- * 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, method, opts) {
+export async function createUnifiedCheckout(deps, chain, opts) {
     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, method, tenant, amountUsdCents, amountUsd) {
-    const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
-    return {
-        depositAddress,
-        displayAmount: `${amountUsd} ${method.token}`,
-        amountUsd,
-        token: method.token,
-        chain: method.chain,
-        referenceId: `erc20:${method.chain}:${depositAddress}`,
-    };
-}
-async function handleNativeEvm(deps, method, tenant, amountUsdCents, amountUsd) {
-    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);
+    const result = await deps.cryptoService.createCharge({
+        chain,
+        amountUsd: opts.amountUsd,
+        callbackUrl: opts.callbackUrl,
+    });
     return {
-        depositAddress,
-        displayAmount: `${whole}.${frac} ETH`,
-        amountUsd,
-        token: "ETH",
-        chain: method.chain,
-        referenceId: `${method.type}:${method.chain}:${depositAddress}`,
-        priceCents,
+        depositAddress: result.address,
+        displayAmount: result.displayAmount ?? `${opts.amountUsd} ${result.token}`,
+        amountUsd: opts.amountUsd,
+        token: result.token,
+        chain: result.chain,
+        referenceId: result.chargeId,
+        priceCents: result.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, method, tenant, amountUsdCents, amountUsd) {
-    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;
-        if (method.chain === "dogecoin") {
-            depositAddress = deriveP2pkhAddress(xpub, derivationIndex, "dogecoin");
-        }
-        else {
-            depositAddress = deriveAddress(xpub, derivationIndex, deps.utxoNetwork ?? "mainnet", method.chain);
-        }
-        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) {
-            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");
-}
-/** Derive an EVM deposit address and store the charge. Retries on unique conflict. */
-async function deriveAndStore(deps, method, tenant, amountUsdCents) {
-    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) {
-            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/watcher-service.d.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).
@@ -30,4 +30,24 @@ export interface WatcherServiceOpts {
     /** Allowed callback URL prefixes. Default: ["https://"] — enforces HTTPS. */
     allowedCallbackPrefixes?: string[];
 }
+export interface PaymentPayload {
+    txHash: string;
+    confirmations: number;
+    confirmationsRequired: number;
+    amountReceivedCents: number;
+    [key: string]: unknown;
+}
+/**
+ * Handle a payment event. Accumulates partial payments in native units.
+ * Fires webhook on every payment/confirmation change with canonical statuses.
+ *
+ * 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).
+ */
+export declare function handlePayment(db: DrizzleDb, chargeStore: ICryptoChargeRepository, address: string, nativeAmount: string, payload: PaymentPayload, log: (msg: string, meta?: Record<string, unknown>) => void): Promise<void>;
 export declare function startWatchers(opts: WatcherServiceOpts): Promise<() => void>;

package/dist/billing/crypto/watcher-service.js

@@ -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).
@@ -90,14 +90,19 @@ async function processDeliveries(db, allowedPrefixes, log) {
     }
     return delivered;
 }
-// --- Payment handling (partial + full) ---
 /**
  * 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(db, chargeStore, address, nativeAmount, payload, log) {
+export async function handlePayment(db, chargeStore, address, nativeAmount, payload, log) {
     const charge = await chargeStore.getByDepositAddress(address);
     if (!charge) {
         log("Payment to unknown address", { address });
@@ -106,39 +111,59 @@ async function handlePayment(db, chargeStore, address, nativeAmount, payload, lo
     if (charge.creditedAt) {
         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;
-    // Update received_amount in DB
-    await db
-        .update(cryptoCharges)
-        .set({ receivedAmount: totalReceived, filledAmount: totalReceived })
-        .where(eq(cryptoCharges.referenceId, charge.referenceId));
-    if (isFull) {
-        const settled = "Settled";
-        await chargeStore.updateStatus(charge.referenceId, settled, charge.token ?? undefined, totalReceived);
+    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));
+    }
+    // Determine canonical status
+    const status = isConfirmed ? "confirmed" : "partial";
+    // 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 = "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,
         });
     }
 }
@@ -181,11 +206,19 @@ export async function startWatchers(opts) {
             oracle,
             cursorStore,
             onPayment: async (event) => {
-                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, event.address, String(event.amountSats), {
                     txHash: event.txid,
                     confirmations: event.confirmations,
+                    confirmationsRequired: event.confirmationsRequired,
+                    amountReceivedCents: event.amountUsdCents,
                 }, log);
             },
         });
@@ -247,11 +280,19 @@ export async function startWatchers(opts) {
             watchedAddresses: chainAddresses,
             cursorStore,
             onPayment: async (event) => {
-                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, event.to, event.rawAmount, {
                     txHash: event.txHash,
-                    confirmations: method.confirmations,
+                    confirmations: event.confirmations,
+                    confirmationsRequired: event.confirmationsRequired,
+                    amountReceivedCents: event.amountUsdCents,
                 }, log);
             },
         });

package/dist/db/schema/crypto.d.ts

@@ -282,6 +282,74 @@ export declare const cryptoCharges: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        confirmations: import("drizzle-orm/pg-core").PgColumn<{
+            name: "confirmations";
+            tableName: "crypto_charges";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        confirmationsRequired: import("drizzle-orm/pg-core").PgColumn<{
+            name: "confirmations_required";
+            tableName: "crypto_charges";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        txHash: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tx_hash";
+            tableName: "crypto_charges";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        amountReceivedCents: import("drizzle-orm/pg-core").PgColumn<{
+            name: "amount_received_cents";
+            tableName: "crypto_charges";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
     };
     dialect: "pg";
 }>;

package/dist/db/schema/crypto.js

@@ -27,6 +27,14 @@ export const cryptoCharges = pgTable("crypto_charges", {
     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),
     index("idx_crypto_charges_status").on(table.status),

package/dist/monetization/crypto/__tests__/webhook.test.js

@@ -120,7 +120,8 @@ describe("handleCryptoWebhook (monetization layer)", () => {
         it("updates charge status on every webhook call", async () => {
             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 () => {
             await handleCryptoWebhook(deps, makePayload({ status: "confirmed" }));

package/drizzle/migrations/0016_charge_progress_columns.sql

@@ -0,0 +1,4 @@
+ALTER TABLE "crypto_charges" ADD COLUMN "confirmations" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "confirmations_required" integer DEFAULT 1 NOT NULL;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "tx_hash" text;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "amount_received_cents" integer DEFAULT 0 NOT NULL;