@wopr-network/platform-core 1.43.0 → 1.44.0

package/dist/billing/crypto/__tests__/key-server.test.js

@@ -78,7 +78,21 @@ function mockDeps() {
             },
         ]),
         listAll: vi.fn(),
-        getById: vi.fn(),
+        getById: vi.fn().mockResolvedValue({
+            id: "btc",
+            type: "native",
+            token: "BTC",
+            chain: "bitcoin",
+            decimals: 8,
+            displayName: "Bitcoin",
+            contractAddress: null,
+            confirmations: 6,
+            oracleAddress: "0x64c911996D3c6aC71f9b455B1E8E7266BcbD848F",
+            xpub: null,
+            displayOrder: 0,
+            enabled: true,
+            rpcUrl: null,
+        }),
         listByType: vi.fn(),
         upsert: vi.fn().mockResolvedValue(undefined),
         setEnabled: vi.fn().mockResolvedValue(undefined),
@@ -87,6 +101,7 @@ function mockDeps() {
         db: createMockDb(),
         chargeStore: chargeStore,
         methodStore: methodStore,
+        oracle: { getPrice: vi.fn().mockResolvedValue({ priceCents: 6_500_000, updatedAt: new Date() }) },
     };
 }
 describe("key-server routes", () => {

package/dist/billing/crypto/btc/watcher.d.ts

@@ -12,6 +12,8 @@ export interface BtcWatcherOpts {
     oracle: IPriceOracle;
     /** Required — BTC has no block cursor, so txid dedup must be persisted. */
     cursorStore: IWatcherCursorStore;
+    /** Override chain identity for cursor namespace (default: config.network). Prevents txid collisions across BTC/LTC/DOGE. */
+    chainId?: string;
 }
 export declare class BtcWatcher {
     private readonly rpc;

package/dist/billing/crypto/btc/watcher.js

@@ -13,7 +13,7 @@ export class BtcWatcher {
         this.minConfirmations = opts.config.confirmations;
         this.oracle = opts.oracle;
         this.cursorStore = opts.cursorStore;
-        this.watcherId = `btc:${opts.config.network}`;
+        this.watcherId = `btc:${opts.chainId ?? opts.config.network}`;
     }
     /** Update the set of watched addresses. */
     setWatchedAddresses(addresses) {

package/dist/billing/crypto/charge-store.d.ts

@@ -14,6 +14,9 @@ export interface CryptoChargeRecord {
     token: string | null;
     depositAddress: string | null;
     derivationIndex: number | null;
+    callbackUrl: string | null;
+    expectedAmount: string | null;
+    receivedAmount: string | null;
 }
 export interface CryptoDepositChargeInput {
     referenceId: string;
@@ -23,6 +26,9 @@ export interface CryptoDepositChargeInput {
     token: string;
     depositAddress: string;
     derivationIndex: number;
+    callbackUrl?: string;
+    /** Expected crypto amount in native base units (sats for BTC, base units for ERC20). */
+    expectedAmount?: string;
 }
 export interface ICryptoChargeRepository {
     create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
@@ -42,7 +48,7 @@ export interface ICryptoChargeRepository {
 /**
  * Manages crypto charge records in PostgreSQL.
  *
- * Each charge maps a BTCPay invoice ID to a tenant and tracks
+ * Each charge maps a deposit address to a tenant and tracks
  * the payment lifecycle (New → Processing → Settled/Expired/Invalid).
  *
  * amountUsdCents stores the requested amount in USD cents (integer).

package/dist/billing/crypto/charge-store.js

@@ -3,7 +3,7 @@ import { cryptoCharges } from "../../db/schema/crypto.js";
 /**
  * Manages crypto charge records in PostgreSQL.
  *
- * Each charge maps a BTCPay invoice ID to a tenant and tracks
+ * Each charge maps a deposit address to a tenant and tracks
  * the payment lifecycle (New → Processing → Settled/Expired/Invalid).
  *
  * amountUsdCents stores the requested amount in USD cents (integer).
@@ -46,6 +46,9 @@ export class DrizzleCryptoChargeRepository {
             token: row.token ?? null,
             depositAddress: row.depositAddress ?? null,
             derivationIndex: row.derivationIndex ?? null,
+            callbackUrl: row.callbackUrl ?? null,
+            expectedAmount: row.expectedAmount ?? null,
+            receivedAmount: row.receivedAmount ?? null,
         };
     }
     /** Update charge status and payment details from webhook. */
@@ -89,6 +92,9 @@ export class DrizzleCryptoChargeRepository {
             token: input.token,
             depositAddress: input.depositAddress.toLowerCase(),
             derivationIndex: input.derivationIndex,
+            callbackUrl: input.callbackUrl,
+            expectedAmount: input.expectedAmount,
+            receivedAmount: "0",
         });
     }
     /** Look up a charge by its deposit address. */

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

@@ -75,29 +75,3 @@ export declare class CryptoServiceClient {
  */
 export declare function loadCryptoConfig(): CryptoServiceConfig | null;
 export type CryptoConfig = CryptoServiceConfig;
-/**
- * @deprecated Use CryptoServiceClient instead. BTCPay is replaced by the crypto key server.
- * Kept for backwards compat — products still import BTCPayClient during migration.
- */
-export declare class BTCPayClient {
-    constructor(_config: {
-        apiKey: string;
-        baseUrl: string;
-        storeId: string;
-    });
-    createInvoice(_opts: {
-        amountUsd: number;
-        orderId: string;
-        buyerEmail?: string;
-        redirectURL?: string;
-    }): Promise<{
-        id: string;
-        checkoutLink: string;
-    }>;
-    getInvoice(_invoiceId: string): Promise<{
-        id: string;
-        status: string;
-        amount: string;
-        currency: string;
-    }>;
-}

package/dist/billing/crypto/client.js

@@ -87,16 +87,3 @@ export function loadCryptoConfig() {
     }
     return null;
 }
-/**
- * @deprecated Use CryptoServiceClient instead. BTCPay is replaced by the crypto key server.
- * Kept for backwards compat — products still import BTCPayClient during migration.
- */
-export class BTCPayClient {
-    constructor(_config) { }
-    async createInvoice(_opts) {
-        throw new Error("BTCPayClient is deprecated — migrate to CryptoServiceClient");
-    }
-    async getInvoice(_invoiceId) {
-        throw new Error("BTCPayClient is deprecated — migrate to CryptoServiceClient");
-    }
-}

package/dist/billing/crypto/client.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { BTCPayClient, CryptoServiceClient, loadCryptoConfig } from "./client.js";
+import { CryptoServiceClient, loadCryptoConfig } from "./client.js";
 describe("CryptoServiceClient", () => {
     afterEach(() => vi.restoreAllMocks());
     it("deriveAddress sends POST /address with chain", async () => {
@@ -60,16 +60,6 @@ describe("CryptoServiceClient", () => {
         await expect(client.getCharge("missing")).rejects.toThrow("CryptoService getCharge failed (404)");
     });
 });
-describe("BTCPayClient (deprecated)", () => {
-    it("throws on createInvoice", async () => {
-        const client = new BTCPayClient({ apiKey: "k", baseUrl: "https://example.com", storeId: "s" });
-        await expect(client.createInvoice({ amountUsd: 10, orderId: "o" })).rejects.toThrow("deprecated");
-    });
-    it("throws on getInvoice", async () => {
-        const client = new BTCPayClient({ apiKey: "k", baseUrl: "https://example.com", storeId: "s" });
-        await expect(client.getInvoice("inv-1")).rejects.toThrow("deprecated");
-    });
-});
 describe("loadCryptoConfig", () => {
     beforeEach(() => {
         delete process.env.CRYPTO_SERVICE_URL;

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

@@ -1,20 +1,18 @@
 export * from "./btc/index.js";
 export type { CryptoChargeRecord, CryptoDepositChargeInput, ICryptoChargeRepository } from "./charge-store.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
-export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
 export type { ChainInfo, ChargeStatus, CreateChargeResult, CryptoConfig, CryptoServiceConfig, DeriveAddressResult, } from "./client.js";
-export { BTCPayClient, CryptoServiceClient, loadCryptoConfig } from "./client.js";
+export { CryptoServiceClient, loadCryptoConfig } from "./client.js";
 export type { IWatcherCursorStore } from "./cursor-store.js";
 export { DrizzleWatcherCursorStore } from "./cursor-store.js";
 export * from "./evm/index.js";
 export type { KeyServerDeps } from "./key-server.js";
 export { createKeyServerApp } from "./key-server.js";
+export type { KeyServerWebhookDeps as CryptoWebhookDeps, KeyServerWebhookPayload as CryptoWebhookPayload, KeyServerWebhookResult as CryptoWebhookResult, } from "./key-server-webhook.js";
+export { handleKeyServerWebhook, handleKeyServerWebhook as handleCryptoWebhook } from "./key-server-webhook.js";
 export * from "./oracle/index.js";
 export type { IPaymentMethodStore, PaymentMethodRecord } from "./payment-method-store.js";
 export { DrizzlePaymentMethodStore } from "./payment-method-store.js";
-export type { CryptoBillingConfig, CryptoCheckoutOpts, CryptoPaymentState, CryptoWebhookPayload, CryptoWebhookResult, } from "./types.js";
-export { mapBtcPayEventToStatus } from "./types.js";
+export type { CryptoPaymentState } from "./types.js";
 export type { UnifiedCheckoutDeps, UnifiedCheckoutResult } from "./unified-checkout.js";
-export { createUnifiedCheckout, MIN_CHECKOUT_USD } from "./unified-checkout.js";
-export type { CryptoWebhookDeps } from "./webhook.js";
-export { handleCryptoWebhook, verifyCryptoWebhookSignature } from "./webhook.js";
+export { createUnifiedCheckout, MIN_CHECKOUT_USD as MIN_PAYMENT_USD, MIN_CHECKOUT_USD } from "./unified-checkout.js";

package/dist/billing/crypto/index.js

@@ -1,12 +1,10 @@
 export * from "./btc/index.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
-export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
-export { BTCPayClient, CryptoServiceClient, loadCryptoConfig } from "./client.js";
+export { CryptoServiceClient, loadCryptoConfig } from "./client.js";
 export { DrizzleWatcherCursorStore } from "./cursor-store.js";
 export * from "./evm/index.js";
 export { createKeyServerApp } from "./key-server.js";
+export { handleKeyServerWebhook, handleKeyServerWebhook as handleCryptoWebhook } from "./key-server-webhook.js";
 export * from "./oracle/index.js";
 export { DrizzlePaymentMethodStore } from "./payment-method-store.js";
-export { mapBtcPayEventToStatus } from "./types.js";
-export { createUnifiedCheckout, MIN_CHECKOUT_USD } from "./unified-checkout.js";
-export { handleCryptoWebhook, verifyCryptoWebhookSignature } from "./webhook.js";
+export { createUnifiedCheckout, MIN_CHECKOUT_USD as MIN_PAYMENT_USD, MIN_CHECKOUT_USD } from "./unified-checkout.js";

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

@@ -13,12 +13,20 @@ import { migrate } from "drizzle-orm/node-postgres/migrator";
 import pg from "pg";
 import * as schema from "../../db/schema/index.js";
 import { DrizzleCryptoChargeRepository } from "./charge-store.js";
+import { DrizzleWatcherCursorStore } from "./cursor-store.js";
+import { createRpcCaller } from "./evm/watcher.js";
 import { createKeyServerApp } from "./key-server.js";
+import { ChainlinkOracle } from "./oracle/chainlink.js";
+import { FixedPriceOracle } from "./oracle/fixed.js";
 import { DrizzlePaymentMethodStore } from "./payment-method-store.js";
+import { startWatchers } from "./watcher-service.js";
 const PORT = Number(process.env.PORT ?? "3100");
 const DATABASE_URL = process.env.DATABASE_URL;
 const SERVICE_KEY = process.env.SERVICE_KEY;
 const ADMIN_TOKEN = process.env.ADMIN_TOKEN;
+const BITCOIND_USER = process.env.BITCOIND_USER ?? "btcpay";
+const BITCOIND_PASSWORD = process.env.BITCOIND_PASSWORD ?? "";
+const BASE_RPC_URL = process.env.BASE_RPC_URL ?? "https://mainnet.base.org";
 if (!DATABASE_URL) {
     console.error("DATABASE_URL is required");
     process.exit(1);
@@ -33,9 +41,42 @@ async function main() {
     const db = drizzle(pool, { schema });
     const chargeStore = new DrizzleCryptoChargeRepository(db);
     const methodStore = new DrizzlePaymentMethodStore(db);
-    const app = createKeyServerApp({ db, chargeStore, methodStore, serviceKey: SERVICE_KEY, adminToken: ADMIN_TOKEN });
+    // Chainlink on-chain oracle for volatile assets (BTC, ETH).
+    const oracle = BASE_RPC_URL
+        ? new ChainlinkOracle({ rpcCall: createRpcCaller(BASE_RPC_URL) })
+        : new FixedPriceOracle();
+    const app = createKeyServerApp({
+        db,
+        chargeStore,
+        methodStore,
+        oracle,
+        serviceKey: SERVICE_KEY,
+        adminToken: ADMIN_TOKEN,
+    });
+    // Boot watchers (BTC + EVM) — polls for payments, sends webhooks
+    const cursorStore = new DrizzleWatcherCursorStore(db);
+    const stopWatchers = await startWatchers({
+        db,
+        chargeStore,
+        methodStore,
+        cursorStore,
+        oracle,
+        bitcoindUser: BITCOIND_USER,
+        bitcoindPassword: BITCOIND_PASSWORD,
+        log: (msg, meta) => console.log(`[watcher] ${msg}`, meta ?? ""),
+    });
+    const server = serve({ fetch: app.fetch, port: PORT });
     console.log(`[crypto-key-server] Listening on :${PORT}`);
-    serve({ fetch: app.fetch, port: PORT });
+    // Graceful shutdown — stop accepting requests, drain watchers, close pool
+    const shutdown = async () => {
+        console.log("[crypto-key-server] Shutting down...");
+        stopWatchers();
+        server.close();
+        await pool.end();
+        process.exit(0);
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
 }
 main().catch((err) => {
     console.error("[crypto-key-server] Fatal:", err);

package/dist/billing/crypto/key-server-webhook.d.ts

@@ -0,0 +1,33 @@
+import type { ILedger } from "../../credits/ledger.js";
+import type { IWebhookSeenRepository } from "../webhook-seen-repository.js";
+import type { ICryptoChargeRepository } from "./charge-store.js";
+export interface KeyServerWebhookPayload {
+    chargeId: string;
+    chain: string;
+    address: string;
+    amountUsdCents: number;
+    status: string;
+    txHash?: string;
+    amountReceived?: string;
+    confirmations?: number;
+}
+export interface KeyServerWebhookDeps {
+    chargeStore: ICryptoChargeRepository;
+    creditLedger: ILedger;
+    replayGuard: IWebhookSeenRepository;
+    onCreditsPurchased?: (tenantId: string, ledger: ILedger) => Promise<string[]>;
+}
+export interface KeyServerWebhookResult {
+    handled: boolean;
+    duplicate?: boolean;
+    tenant?: string;
+    creditedCents?: number;
+    reactivatedBots?: string[];
+}
+/**
+ * Process a payment confirmation from the crypto key server.
+ *
+ * Credits the ledger when status is "confirmed".
+ * Idempotency: ledger referenceId + replay guard (same pattern as Stripe handler).
+ */
+export declare function handleKeyServerWebhook(deps: KeyServerWebhookDeps, payload: KeyServerWebhookPayload): Promise<KeyServerWebhookResult>;

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

@@ -0,0 +1,73 @@
+/**
+ * Key Server webhook handler — processes payment confirmations from the
+ * centralized crypto key server.
+ *
+ * Payload shape (from watcher-service.ts):
+ * {
+ *   chargeId: "btc:bc1q...",
+ *   chain: "bitcoin",
+ *   address: "bc1q...",
+ *   amountUsdCents: 5000,
+ *   status: "confirmed",
+ *   txHash: "abc123...",
+ *   amountReceived: "50000 sats",
+ *   confirmations: 6
+ * }
+ *
+ * Replaces handleCryptoWebhook() for products using the key server.
+ */
+import { Credit } from "../../credits/credit.js";
+/**
+ * Process a payment confirmation from the crypto key server.
+ *
+ * Credits the ledger when status is "confirmed".
+ * Idempotency: ledger referenceId + replay guard (same pattern as Stripe handler).
+ */
+export async function handleKeyServerWebhook(deps, payload) {
+    const { chargeStore, creditLedger } = deps;
+    // Replay guard: deduplicate by chargeId
+    const dedupeKey = `ks:${payload.chargeId}`;
+    if (await deps.replayGuard.isDuplicate(dedupeKey, "crypto")) {
+        return { handled: true, duplicate: true };
+    }
+    // Look up the charge to find the tenant + amount
+    const charge = await chargeStore.getByReferenceId(payload.chargeId);
+    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);
+        // 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 };
+        }
+        // Credit the original USD amount requested.
+        // charge.amountUsdCents is integer cents. Credit.fromCents() → nanodollars.
+        await creditLedger.credit(charge.tenantId, Credit.fromCents(charge.amountUsdCents), "purchase", {
+            description: `Crypto payment confirmed (${payload.chain}, tx: ${payload.txHash ?? "unknown"})`,
+            referenceId: creditRef,
+            fundingSource: "crypto",
+        });
+        await chargeStore.markCredited(payload.chargeId);
+        let reactivatedBots;
+        if (deps.onCreditsPurchased) {
+            reactivatedBots = await deps.onCreditsPurchased(charge.tenantId, creditLedger);
+            if (reactivatedBots.length === 0)
+                reactivatedBots = undefined;
+        }
+        await deps.replayGuard.markSeen(dedupeKey, "crypto");
+        return {
+            handled: true,
+            tenant: charge.tenantId,
+            creditedCents: charge.amountUsdCents,
+            reactivatedBots,
+        };
+    }
+    // Non-confirmed status — update status but don't settle or credit
+    await chargeStore.updateStatus(payload.chargeId, payload.status, charge.token ?? undefined, payload.amountReceived);
+    await deps.replayGuard.markSeen(dedupeKey, "crypto");
+    return { handled: true, tenant: charge.tenantId };
+}

package/dist/billing/crypto/key-server.d.ts

@@ -1,11 +1,13 @@
 import { Hono } from "hono";
 import type { DrizzleDb } from "../../db/index.js";
 import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { IPriceOracle } from "./oracle/types.js";
 import type { IPaymentMethodStore } from "./payment-method-store.js";
 export interface KeyServerDeps {
     db: DrizzleDb;
     chargeStore: ICryptoChargeRepository;
     methodStore: IPaymentMethodStore;
+    oracle: IPriceOracle;
     /** Bearer token for product API routes. If unset, auth is disabled. */
     serviceKey?: string;
     /** Bearer token for admin routes. If unset, admin routes are disabled. */

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

@@ -12,6 +12,7 @@ import { Hono } from "hono";
 import { derivedAddresses, pathAllocations, paymentMethods } from "../../db/schema/crypto.js";
 import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
 import { deriveDepositAddress } from "./evm/address-gen.js";
+import { centsToNative } from "./oracle/convert.js";
 /**
  * Derive the next unused address for a chain.
  * Atomically increments next_index and records address in a single transaction.
@@ -111,7 +112,23 @@ export function createKeyServerApp(deps) {
         }
         const tenantId = c.req.header("X-Tenant-Id") ?? "unknown";
         const { address, index, chain, token } = await deriveNextAddress(deps.db, body.chain, tenantId);
+        // Look up payment method for decimals + oracle config
+        const method = await deps.methodStore.getById(body.chain);
+        if (!method)
+            return c.json({ error: `Unknown chain: ${body.chain}` }, 400);
         const amountUsdCents = Math.round(body.amountUsd * 100);
+        // Compute expected crypto amount in native base units.
+        // Price is locked NOW — this is what the user must send.
+        let expectedAmount;
+        if (method.oracleAddress) {
+            // Volatile asset (BTC, ETH, DOGE) — oracle-priced
+            const { priceCents } = await deps.oracle.getPrice(token);
+            expectedAmount = centsToNative(amountUsdCents, priceCents, method.decimals);
+        }
+        else {
+            // Stablecoin (1:1 USD) — e.g. $50 USDC = 50_000_000 base units (6 decimals)
+            expectedAmount = (BigInt(amountUsdCents) * 10n ** BigInt(method.decimals)) / 100n;
+        }
         const referenceId = `${token.toLowerCase()}:${address.toLowerCase()}`;
         await deps.chargeStore.createStablecoinCharge({
             referenceId,
@@ -121,13 +138,20 @@ export function createKeyServerApp(deps) {
             token,
             depositAddress: address,
             derivationIndex: index,
+            callbackUrl: body.callbackUrl,
+            expectedAmount: expectedAmount.toString(),
         });
+        // Format display amount for the client
+        const divisor = 10 ** method.decimals;
+        const displayAmount = `${(Number(expectedAmount) / divisor).toFixed(Math.min(method.decimals, 8))} ${token}`;
         return c.json({
             chargeId: referenceId,
             address,
-            chain: body.chain,
+            chain,
             token,
             amountUsd: body.amountUsd,
+            expectedAmount: expectedAmount.toString(),
+            displayAmount,
             derivationIndex: index,
             expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(), // 30 min
         }, 201);

package/dist/billing/crypto/watcher-service.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 type { DrizzleDb } from "../../db/index.js";
+import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { IWatcherCursorStore } from "./cursor-store.js";
+import type { IPriceOracle } from "./oracle/types.js";
+import type { IPaymentMethodStore } from "./payment-method-store.js";
+export interface WatcherServiceOpts {
+    db: DrizzleDb;
+    chargeStore: ICryptoChargeRepository;
+    methodStore: IPaymentMethodStore;
+    cursorStore: IWatcherCursorStore;
+    oracle: IPriceOracle;
+    bitcoindUser?: string;
+    bitcoindPassword?: string;
+    pollIntervalMs?: number;
+    deliveryIntervalMs?: number;
+    log?: (msg: string, meta?: Record<string, unknown>) => void;
+    /** Allowed callback URL prefixes. Default: ["https://"] — enforces HTTPS. */
+    allowedCallbackPrefixes?: string[];
+}
+export declare function startWatchers(opts: WatcherServiceOpts): Promise<() => void>;