@wopr-network/platform-core 1.43.0 → 1.44.0

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

@@ -0,0 +1,295 @@
+/**
+ * Watcher Service — boots chain watchers and sends webhook callbacks.
+ *
+ * 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
+ *   5. Outbox processor retries failed deliveries with exponential backoff
+ *
+ * Amount comparison is ALWAYS in native crypto units (sats, wei, token base units).
+ * The exchange rate is locked at charge creation — no live price comparison.
+ */
+import { and, eq, isNull, lte, or } from "drizzle-orm";
+import { cryptoCharges, webhookDeliveries } from "../../db/schema/crypto.js";
+import { BtcWatcher, createBitcoindRpc } from "./btc/watcher.js";
+import { createRpcCaller, EvmWatcher } from "./evm/watcher.js";
+const MAX_DELIVERY_ATTEMPTS = 10;
+const BACKOFF_BASE_MS = 5_000;
+// --- SSRF validation ---
+function isValidCallbackUrl(url, allowedPrefixes) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+            return false;
+        const host = parsed.hostname;
+        if (host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host === "::1")
+            return false;
+        if (host.startsWith("10.") || host.startsWith("192.168.") || host.startsWith("169.254."))
+            return false;
+        return allowedPrefixes.some((prefix) => url.startsWith(prefix));
+    }
+    catch {
+        return false;
+    }
+}
+// --- Webhook outbox ---
+async function enqueueWebhook(db, chargeId, callbackUrl, payload) {
+    await db.insert(webhookDeliveries).values({
+        chargeId,
+        callbackUrl,
+        payload: JSON.stringify(payload),
+    });
+}
+async function processDeliveries(db, allowedPrefixes, log) {
+    const now = new Date().toISOString();
+    const pending = await db
+        .select()
+        .from(webhookDeliveries)
+        .where(and(eq(webhookDeliveries.status, "pending"), or(isNull(webhookDeliveries.nextRetryAt), lte(webhookDeliveries.nextRetryAt, now))))
+        .limit(50);
+    let delivered = 0;
+    for (const row of pending) {
+        if (!isValidCallbackUrl(row.callbackUrl, allowedPrefixes)) {
+            await db
+                .update(webhookDeliveries)
+                .set({ status: "failed", lastError: "Invalid callbackUrl (SSRF blocked)" })
+                .where(eq(webhookDeliveries.id, row.id));
+            continue;
+        }
+        try {
+            const res = await fetch(row.callbackUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: row.payload,
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            await db.update(webhookDeliveries).set({ status: "delivered" }).where(eq(webhookDeliveries.id, row.id));
+            delivered++;
+        }
+        catch (err) {
+            const attempts = row.attempts + 1;
+            if (attempts >= MAX_DELIVERY_ATTEMPTS) {
+                await db
+                    .update(webhookDeliveries)
+                    .set({ status: "failed", attempts, lastError: String(err) })
+                    .where(eq(webhookDeliveries.id, row.id));
+                log("Webhook permanently failed", { chargeId: row.chargeId, attempts });
+            }
+            else {
+                const backoffMs = BACKOFF_BASE_MS * 2 ** (attempts - 1);
+                const nextRetry = new Date(Date.now() + backoffMs).toISOString();
+                await db
+                    .update(webhookDeliveries)
+                    .set({ attempts, nextRetryAt: nextRetry, lastError: String(err) })
+                    .where(eq(webhookDeliveries.id, row.id));
+            }
+        }
+    }
+    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.
+ *
+ * @param nativeAmount — received amount in native base units (sats for BTC/DOGE, raw token units for ERC20)
+ */
+async function handlePayment(db, chargeStore, address, nativeAmount, payload, log) {
+    const charge = await chargeStore.getByDepositAddress(address);
+    if (!charge) {
+        log("Payment to unknown address", { address });
+        return;
+    }
+    if (charge.creditedAt) {
+        return; // Already fully paid and credited
+    }
+    // Accumulate: add this payment to the running total
+    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);
+        await chargeStore.markCredited(charge.referenceId);
+        log("Charge settled", { chargeId: charge.referenceId, expected: expected.toString(), received: totalReceived });
+    }
+    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 });
+    }
+    // Webhook on every payment — product shows 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,
+        });
+    }
+}
+// --- Watcher boot ---
+export async function startWatchers(opts) {
+    const { db, chargeStore, methodStore, cursorStore, oracle } = opts;
+    const pollMs = opts.pollIntervalMs ?? 15_000;
+    const deliveryMs = opts.deliveryIntervalMs ?? 10_000;
+    const log = opts.log ?? (() => { });
+    const allowedPrefixes = opts.allowedCallbackPrefixes ?? ["https://"];
+    const timers = [];
+    const methods = await methodStore.listEnabled();
+    const utxoMethods = methods.filter((m) => m.type === "native" && (m.chain === "bitcoin" || m.chain === "litecoin" || m.chain === "dogecoin"));
+    const evmMethods = methods.filter((m) => m.type === "erc20" ||
+        (m.type === "native" && m.chain !== "bitcoin" && m.chain !== "litecoin" && m.chain !== "dogecoin"));
+    // --- UTXO Watchers (BTC, LTC, DOGE) ---
+    for (const method of utxoMethods) {
+        if (!method.rpcUrl)
+            continue;
+        const rpcCall = createBitcoindRpc({
+            rpcUrl: method.rpcUrl,
+            rpcUser: opts.bitcoindUser ?? "btcpay",
+            rpcPassword: opts.bitcoindPassword ?? "",
+            network: "mainnet",
+            confirmations: method.confirmations,
+        });
+        const activeAddresses = await chargeStore.listActiveDepositAddresses();
+        const chainAddresses = activeAddresses.filter((a) => a.chain === method.chain).map((a) => a.address);
+        const watcher = new BtcWatcher({
+            config: {
+                rpcUrl: method.rpcUrl,
+                rpcUser: opts.bitcoindUser ?? "btcpay",
+                rpcPassword: opts.bitcoindPassword ?? "",
+                network: "mainnet",
+                confirmations: method.confirmations,
+            },
+            chainId: method.chain,
+            rpcCall,
+            watchedAddresses: chainAddresses,
+            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
+                await handlePayment(db, chargeStore, event.address, String(event.amountSats), {
+                    txHash: event.txid,
+                    confirmations: event.confirmations,
+                }, log);
+            },
+        });
+        const importedAddresses = new Set();
+        for (const addr of chainAddresses) {
+            try {
+                await watcher.importAddress(addr);
+                importedAddresses.add(addr);
+            }
+            catch {
+                log("Failed to import address", { chain: method.chain, address: addr });
+            }
+        }
+        log(`UTXO watcher started (${method.chain})`, { addresses: importedAddresses.size });
+        let utxoPolling = false;
+        timers.push(setInterval(async () => {
+            if (utxoPolling)
+                return; // Prevent overlapping polls
+            utxoPolling = true;
+            try {
+                const fresh = await chargeStore.listActiveDepositAddresses();
+                const freshChain = fresh.filter((a) => a.chain === method.chain).map((a) => a.address);
+                for (const addr of freshChain) {
+                    if (!importedAddresses.has(addr)) {
+                        try {
+                            await watcher.importAddress(addr);
+                            importedAddresses.add(addr);
+                        }
+                        catch {
+                            log("Failed to import new address (will retry)", { chain: method.chain, address: addr });
+                        }
+                    }
+                }
+                watcher.setWatchedAddresses(freshChain);
+                await watcher.poll();
+            }
+            catch (err) {
+                log("UTXO poll error", { chain: method.chain, error: String(err) });
+            }
+            finally {
+                utxoPolling = false;
+            }
+        }, pollMs));
+    }
+    // --- EVM Watchers ---
+    for (const method of evmMethods) {
+        if (!method.rpcUrl || !method.contractAddress)
+            continue;
+        const rpcCall = createRpcCaller(method.rpcUrl);
+        const latestHex = (await rpcCall("eth_blockNumber", []));
+        const latestBlock = Number.parseInt(latestHex, 16);
+        const activeAddresses = await chargeStore.listActiveDepositAddresses();
+        const chainAddresses = activeAddresses.filter((a) => a.chain === method.chain).map((a) => a.address);
+        const watcher = new EvmWatcher({
+            chain: method.chain,
+            token: method.token,
+            rpcCall,
+            fromBlock: latestBlock,
+            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
+                await handlePayment(db, chargeStore, event.to, event.rawAmount, {
+                    txHash: event.txHash,
+                    confirmations: method.confirmations,
+                }, log);
+            },
+        });
+        await watcher.init();
+        log(`EVM watcher started (${method.chain}:${method.token})`, { addresses: chainAddresses.length });
+        let evmPolling = false;
+        timers.push(setInterval(async () => {
+            if (evmPolling)
+                return; // Prevent overlapping polls
+            evmPolling = true;
+            try {
+                const fresh = await chargeStore.listActiveDepositAddresses();
+                const freshChain = fresh.filter((a) => a.chain === method.chain).map((a) => a.address);
+                watcher.setWatchedAddresses(freshChain);
+                await watcher.poll();
+            }
+            catch (err) {
+                log("EVM poll error", { chain: method.chain, token: method.token, error: String(err) });
+            }
+            finally {
+                evmPolling = false;
+            }
+        }, pollMs));
+    }
+    // --- Webhook delivery outbox processor ---
+    timers.push(setInterval(async () => {
+        try {
+            const count = await processDeliveries(db, allowedPrefixes, log);
+            if (count > 0)
+                log("Webhooks delivered", { count });
+        }
+        catch (err) {
+            log("Delivery loop error", { error: String(err) });
+        }
+    }, deliveryMs));
+    log("All watchers started", { utxo: utxoMethods.length, evm: evmMethods.length, pollMs, deliveryMs });
+    return () => {
+        for (const t of timers)
+            clearInterval(t);
+    };
+}

package/dist/billing/index.js

@@ -1,4 +1,4 @@
-// Crypto (BTCPay Server)
+// Crypto (key server — native BTC/EVM watchers)
 export * from "./crypto/index.js";
 export { DrizzleWebhookSeenRepository } from "./drizzle-webhook-seen-repository.js";
 export { PaymentMethodOwnershipError } from "./payment-processor.js";

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

@@ -1,6 +1,6 @@
 /**
- * Crypto payment charges — tracks the lifecycle of each BTCPay invoice.
- * reference_id is the BTCPay invoice ID.
+ * Crypto payment charges — tracks the lifecycle of each payment.
+ * reference_id is the charge ID (e.g. "btc:bc1q...").
  *
  * amountUsdCents stores the requested amount in USD cents (integer).
  * This is NOT nanodollars — Credit.fromCents() handles the conversion
@@ -231,6 +231,57 @@ export declare const cryptoCharges: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        callbackUrl: import("drizzle-orm/pg-core").PgColumn<{
+            name: "callback_url";
+            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;
+        }, {}, {}>;
+        expectedAmount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "expected_amount";
+            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;
+        }, {}, {}>;
+        receivedAmount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "received_amount";
+            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;
+        }, {}, {}>;
     };
     dialect: "pg";
 }>;
@@ -680,6 +731,170 @@ export declare const pathAllocations: import("drizzle-orm/pg-core").PgTableWithC
     };
     dialect: "pg";
 }>;
+/**
+ * Webhook delivery outbox — durable retry for payment callbacks.
+ * Inserted when a payment is confirmed. Retried until the receiver ACKs.
+ */
+export declare const webhookDeliveries: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "webhook_deliveries";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "webhook_deliveries";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: "always";
+            generated: undefined;
+        }, {}, {}>;
+        chargeId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "charge_id";
+            tableName: "webhook_deliveries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        callbackUrl: import("drizzle-orm/pg-core").PgColumn<{
+            name: "callback_url";
+            tableName: "webhook_deliveries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        payload: import("drizzle-orm/pg-core").PgColumn<{
+            name: "payload";
+            tableName: "webhook_deliveries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "webhook_deliveries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempts: import("drizzle-orm/pg-core").PgColumn<{
+            name: "attempts";
+            tableName: "webhook_deliveries";
+            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;
+        }, {}, {}>;
+        nextRetryAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "next_retry_at";
+            tableName: "webhook_deliveries";
+            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;
+        }, {}, {}>;
+        lastError: import("drizzle-orm/pg-core").PgColumn<{
+            name: "last_error";
+            tableName: "webhook_deliveries";
+            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;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "webhook_deliveries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 /**
  * Every address ever derived — immutable append-only log.
  * Used for auditing and ensuring no address is ever reused.

package/dist/db/schema/crypto.js

@@ -1,8 +1,8 @@
 import { sql } from "drizzle-orm";
 import { boolean, index, integer, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
 /**
- * Crypto payment charges — tracks the lifecycle of each BTCPay invoice.
- * reference_id is the BTCPay invoice ID.
+ * Crypto payment charges — tracks the lifecycle of each payment.
+ * reference_id is the charge ID (e.g. "btc:bc1q...").
  *
  * amountUsdCents stores the requested amount in USD cents (integer).
  * This is NOT nanodollars — Credit.fromCents() handles the conversion
@@ -22,6 +22,11 @@ export const cryptoCharges = pgTable("crypto_charges", {
     token: text("token"),
     depositAddress: text("deposit_address"),
     derivationIndex: integer("derivation_index"),
+    callbackUrl: text("callback_url"),
+    /** Expected crypto amount in native units (e.g. "76923" sats, "50000000" USDC base units). Locked at creation. */
+    expectedAmount: text("expected_amount"),
+    /** Running total of received crypto in native units. Accumulates across partial payments. */
+    receivedAmount: text("received_amount"),
 }, (table) => [
     index("idx_crypto_charges_tenant").on(table.tenantId),
     index("idx_crypto_charges_status").on(table.status),
@@ -77,6 +82,24 @@ export const pathAllocations = pgTable("path_allocations", {
     xpub: text("xpub").notNull(),
     allocatedAt: text("allocated_at").notNull().default(sql `(now())`),
 }, (table) => [primaryKey({ columns: [table.coinType, table.accountIndex] })]);
+/**
+ * Webhook delivery outbox — durable retry for payment callbacks.
+ * Inserted when a payment is confirmed. Retried until the receiver ACKs.
+ */
+export const webhookDeliveries = pgTable("webhook_deliveries", {
+    id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+    chargeId: text("charge_id").notNull(),
+    callbackUrl: text("callback_url").notNull(),
+    payload: text("payload").notNull(), // JSON stringified
+    status: text("status").notNull().default("pending"), // pending, delivered, failed
+    attempts: integer("attempts").notNull().default(0),
+    nextRetryAt: text("next_retry_at"),
+    lastError: text("last_error"),
+    createdAt: text("created_at").notNull().default(sql `(now())`),
+}, (table) => [
+    index("idx_webhook_deliveries_status").on(table.status),
+    index("idx_webhook_deliveries_charge").on(table.chargeId),
+]);
 /**
  * Every address ever derived — immutable append-only log.
  * Used for auditing and ensuring no address is ever reused.