@wopr-network/platform-core 1.25.0 → 1.26.0

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

@@ -8,7 +8,11 @@ export type { IWatcherCursorStore } from "./cursor-store.js";
 export { DrizzleWatcherCursorStore } from "./cursor-store.js";
 export * from "./evm/index.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 { 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";

package/dist/billing/crypto/index.js

@@ -5,5 +5,7 @@ export { BTCPayClient, loadCryptoConfig } from "./client.js";
 export { DrizzleWatcherCursorStore } from "./cursor-store.js";
 export * from "./evm/index.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";

package/dist/billing/crypto/payment-method-store.d.ts

@@ -0,0 +1,38 @@
+import type { PlatformDb } from "../../db/index.js";
+export interface PaymentMethodRecord {
+    id: string;
+    type: string;
+    token: string;
+    chain: string;
+    contractAddress: string | null;
+    decimals: number;
+    displayName: string;
+    enabled: boolean;
+    displayOrder: number;
+    rpcUrl: string | null;
+    confirmations: number;
+}
+export interface IPaymentMethodStore {
+    /** List all enabled payment methods, ordered by displayOrder. */
+    listEnabled(): Promise<PaymentMethodRecord[]>;
+    /** List all payment methods (including disabled). */
+    listAll(): Promise<PaymentMethodRecord[]>;
+    /** Get a specific payment method by id. */
+    getById(id: string): Promise<PaymentMethodRecord | null>;
+    /** Get enabled methods by type (stablecoin, eth, btc). */
+    listByType(type: string): Promise<PaymentMethodRecord[]>;
+    /** Upsert a payment method (admin). */
+    upsert(method: PaymentMethodRecord): Promise<void>;
+    /** Enable or disable a payment method (admin). */
+    setEnabled(id: string, enabled: boolean): Promise<void>;
+}
+export declare class DrizzlePaymentMethodStore implements IPaymentMethodStore {
+    private readonly db;
+    constructor(db: PlatformDb);
+    listEnabled(): Promise<PaymentMethodRecord[]>;
+    listAll(): Promise<PaymentMethodRecord[]>;
+    getById(id: string): Promise<PaymentMethodRecord | null>;
+    listByType(type: string): Promise<PaymentMethodRecord[]>;
+    upsert(method: PaymentMethodRecord): Promise<void>;
+    setEnabled(id: string, enabled: boolean): Promise<void>;
+}

package/dist/billing/crypto/payment-method-store.js

@@ -0,0 +1,82 @@
+import { and, eq } from "drizzle-orm";
+import { paymentMethods } from "../../db/schema/crypto.js";
+export class DrizzlePaymentMethodStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async listEnabled() {
+        const rows = await this.db
+            .select()
+            .from(paymentMethods)
+            .where(eq(paymentMethods.enabled, true))
+            .orderBy(paymentMethods.displayOrder);
+        return rows.map(toRecord);
+    }
+    async listAll() {
+        const rows = await this.db.select().from(paymentMethods).orderBy(paymentMethods.displayOrder);
+        return rows.map(toRecord);
+    }
+    async getById(id) {
+        const row = (await this.db.select().from(paymentMethods).where(eq(paymentMethods.id, id)))[0];
+        return row ? toRecord(row) : null;
+    }
+    async listByType(type) {
+        const rows = await this.db
+            .select()
+            .from(paymentMethods)
+            .where(and(eq(paymentMethods.type, type), eq(paymentMethods.enabled, true)))
+            .orderBy(paymentMethods.displayOrder);
+        return rows.map(toRecord);
+    }
+    async upsert(method) {
+        await this.db
+            .insert(paymentMethods)
+            .values({
+            id: method.id,
+            type: method.type,
+            token: method.token,
+            chain: method.chain,
+            contractAddress: method.contractAddress,
+            decimals: method.decimals,
+            displayName: method.displayName,
+            enabled: method.enabled,
+            displayOrder: method.displayOrder,
+            rpcUrl: method.rpcUrl,
+            confirmations: method.confirmations,
+        })
+            .onConflictDoUpdate({
+            target: paymentMethods.id,
+            set: {
+                type: method.type,
+                token: method.token,
+                chain: method.chain,
+                contractAddress: method.contractAddress,
+                decimals: method.decimals,
+                displayName: method.displayName,
+                enabled: method.enabled,
+                displayOrder: method.displayOrder,
+                rpcUrl: method.rpcUrl,
+                confirmations: method.confirmations,
+            },
+        });
+    }
+    async setEnabled(id, enabled) {
+        await this.db.update(paymentMethods).set({ enabled }).where(eq(paymentMethods.id, id));
+    }
+}
+function toRecord(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        token: row.token,
+        chain: row.chain,
+        contractAddress: row.contractAddress,
+        decimals: row.decimals,
+        displayName: row.displayName,
+        enabled: row.enabled,
+        displayOrder: row.displayOrder,
+        rpcUrl: row.rpcUrl,
+        confirmations: row.confirmations,
+    };
+}

package/dist/billing/crypto/unified-checkout.d.ts

@@ -0,0 +1,35 @@
+import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { IPriceOracle } from "./oracle/types.js";
+import type { PaymentMethodRecord } from "./payment-method-store.js";
+export declare const MIN_CHECKOUT_USD = 10;
+export interface UnifiedCheckoutDeps {
+    chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
+    oracle: IPriceOracle;
+    evmXpub: string;
+    btcXpub?: string;
+}
+export interface UnifiedCheckoutResult {
+    depositAddress: string;
+    /** Human-readable amount to send (e.g. "50 USDC", "0.014285 ETH"). */
+    displayAmount: string;
+    amountUsd: number;
+    token: string;
+    chain: string;
+    referenceId: string;
+    /** For volatile assets: price at checkout time (USD cents per unit). */
+    priceCents?: number;
+}
+/**
+ * Unified checkout — one entry point for all payment methods.
+ *
+ * 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().
+ */
+export declare function createUnifiedCheckout(deps: UnifiedCheckoutDeps, method: PaymentMethodRecord, opts: {
+    tenant: string;
+    amountUsd: number;
+}): Promise<UnifiedCheckoutResult>;

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

@@ -0,0 +1,128 @@
+import { Credit } from "../../credits/credit.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.
+ *
+ * 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().
+ */
+export async function createUnifiedCheckout(deps, method, 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.token === "ETH") {
+        return handleNativeEth(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
+    }
+    if (method.token === "BTC") {
+        return handleNativeBtc(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 handleNativeEth(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);
+    return {
+        depositAddress,
+        displayAmount: `${whole}.${frac} ETH`,
+        amountUsd,
+        token: "ETH",
+        chain: method.chain,
+        referenceId: `eth:${method.chain}:${depositAddress}`,
+        priceCents,
+    };
+}
+async function handleNativeBtc(deps, _method, tenant, amountUsdCents, amountUsd) {
+    const { priceCents } = await deps.oracle.getPrice("BTC");
+    const expectedSats = centsToNative(amountUsdCents, priceCents, 8);
+    // BTC address derivation uses btcXpub — import from btc module
+    const { deriveBtcAddress } = await import("./btc/address-gen.js");
+    if (!deps.btcXpub)
+        throw new Error("BTC payments not configured (no BTC_XPUB)");
+    const maxRetries = 3;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+        const depositAddress = deriveBtcAddress(deps.btcXpub, derivationIndex, "mainnet");
+        const referenceId = `btc:${depositAddress}`;
+        try {
+            await deps.chargeStore.createStablecoinCharge({
+                referenceId,
+                tenantId: tenant,
+                amountUsdCents,
+                chain: "bitcoin",
+                token: "BTC",
+                depositAddress,
+                derivationIndex,
+            });
+            const btcAmount = Number(expectedSats) / 100_000_000;
+            return {
+                depositAddress,
+                displayAmount: `${btcAmount.toFixed(8)} BTC`,
+                amountUsd,
+                token: "BTC",
+                chain: "bitcoin",
+                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/db/schema/crypto.d.ts

@@ -296,6 +296,222 @@ export declare const watcherCursors: import("drizzle-orm/pg-core").PgTableWithCo
     };
     dialect: "pg";
 }>;
+/**
+ * Payment method registry — runtime-configurable tokens/chains.
+ * Admin inserts a row to enable a new payment method. No deploy needed.
+ * Contract addresses are immutable on-chain but configurable here.
+ */
+export declare const paymentMethods: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "payment_methods";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "payment_methods";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        type: import("drizzle-orm/pg-core").PgColumn<{
+            name: "type";
+            tableName: "payment_methods";
+            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;
+        }, {}, {}>;
+        token: import("drizzle-orm/pg-core").PgColumn<{
+            name: "token";
+            tableName: "payment_methods";
+            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;
+        }, {}, {}>;
+        chain: import("drizzle-orm/pg-core").PgColumn<{
+            name: "chain";
+            tableName: "payment_methods";
+            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;
+        }, {}, {}>;
+        contractAddress: import("drizzle-orm/pg-core").PgColumn<{
+            name: "contract_address";
+            tableName: "payment_methods";
+            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;
+        }, {}, {}>;
+        decimals: import("drizzle-orm/pg-core").PgColumn<{
+            name: "decimals";
+            tableName: "payment_methods";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        displayName: import("drizzle-orm/pg-core").PgColumn<{
+            name: "display_name";
+            tableName: "payment_methods";
+            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;
+        }, {}, {}>;
+        enabled: import("drizzle-orm/pg-core").PgColumn<{
+            name: "enabled";
+            tableName: "payment_methods";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        displayOrder: import("drizzle-orm/pg-core").PgColumn<{
+            name: "display_order";
+            tableName: "payment_methods";
+            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;
+        }, {}, {}>;
+        rpcUrl: import("drizzle-orm/pg-core").PgColumn<{
+            name: "rpc_url";
+            tableName: "payment_methods";
+            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;
+        }, {}, {}>;
+        confirmations: import("drizzle-orm/pg-core").PgColumn<{
+            name: "confirmations";
+            tableName: "payment_methods";
+            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;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "payment_methods";
+            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";
+}>;
 /** Processed transaction IDs for watchers without block cursors (e.g. BTC). */
 export declare const watcherProcessed: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "watcher_processed";

package/dist/db/schema/crypto.js

@@ -1,5 +1,5 @@
 import { sql } from "drizzle-orm";
-import { index, integer, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
+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.
@@ -39,6 +39,25 @@ export const watcherCursors = pgTable("watcher_cursors", {
     cursorBlock: integer("cursor_block").notNull(),
     updatedAt: text("updated_at").notNull().default(sql `(now())`),
 });
+/**
+ * Payment method registry — runtime-configurable tokens/chains.
+ * Admin inserts a row to enable a new payment method. No deploy needed.
+ * Contract addresses are immutable on-chain but configurable here.
+ */
+export const paymentMethods = pgTable("payment_methods", {
+    id: text("id").primaryKey(), // "USDC:base", "ETH:base", "BTC:mainnet"
+    type: text("type").notNull(), // "stablecoin", "eth", "btc"
+    token: text("token").notNull(), // "USDC", "ETH", "BTC"
+    chain: text("chain").notNull(), // "base", "ethereum", "bitcoin"
+    contractAddress: text("contract_address"), // null for native (ETH, BTC)
+    decimals: integer("decimals").notNull(),
+    displayName: text("display_name").notNull(),
+    enabled: boolean("enabled").notNull().default(true),
+    displayOrder: integer("display_order").notNull().default(0),
+    rpcUrl: text("rpc_url"), // override per-chain RPC (null = use default)
+    confirmations: integer("confirmations").notNull().default(1),
+    createdAt: text("created_at").notNull().default(sql `(now())`),
+});
 /** Processed transaction IDs for watchers without block cursors (e.g. BTC). */
 export const watcherProcessed = pgTable("watcher_processed", {
     watcherId: text("watcher_id").notNull(),

package/drizzle/migrations/0008_payment_methods.sql

@@ -0,0 +1,22 @@
+CREATE TABLE IF NOT EXISTS "payment_methods" (
+  "id" text PRIMARY KEY NOT NULL,
+  "type" text NOT NULL,
+  "token" text NOT NULL,
+  "chain" text NOT NULL,
+  "contract_address" text,
+  "decimals" integer NOT NULL,
+  "display_name" text NOT NULL,
+  "enabled" boolean NOT NULL DEFAULT true,
+  "display_order" integer NOT NULL DEFAULT 0,
+  "rpc_url" text,
+  "confirmations" integer NOT NULL DEFAULT 1,
+  "created_at" text DEFAULT (now()) NOT NULL
+);
+--> statement-breakpoint
+INSERT INTO "payment_methods" ("id", "type", "token", "chain", "contract_address", "decimals", "display_name", "display_order", "confirmations") VALUES
+  ('USDC:base', 'erc20', 'USDC', 'base', '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', 6, 'USDC on Base', 0, 1),
+  ('USDT:base', 'erc20', 'USDT', 'base', '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', 6, 'USDT on Base', 1, 1),
+  ('DAI:base', 'erc20', 'DAI', 'base', '0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb', 18, 'DAI on Base', 2, 1),
+  ('ETH:base', 'native', 'ETH', 'base', NULL, 18, 'ETH on Base', 3, 1),
+  ('BTC:mainnet', 'native', 'BTC', 'bitcoin', NULL, 8, 'Bitcoin', 10, 3)
+ON CONFLICT ("id") DO NOTHING;

package/drizzle/migrations/meta/_journal.json

@@ -57,6 +57,13 @@
       "when": 1742227200000,
       "tag": "0007_watcher_cursors",
       "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1742313600000,
+      "tag": "0008_payment_methods",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/billing/crypto/index.ts

@@ -8,6 +8,8 @@ export type { IWatcherCursorStore } from "./cursor-store.js";
 export { DrizzleWatcherCursorStore } from "./cursor-store.js";
 export * from "./evm/index.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,
@@ -16,5 +18,7 @@ export type {
   CryptoWebhookResult,
 } from "./types.js";
 export { mapBtcPayEventToStatus } 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";

package/src/billing/crypto/payment-method-store.ts

@@ -0,0 +1,117 @@
+import { and, eq } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { paymentMethods } from "../../db/schema/crypto.js";
+
+export interface PaymentMethodRecord {
+  id: string;
+  type: string;
+  token: string;
+  chain: string;
+  contractAddress: string | null;
+  decimals: number;
+  displayName: string;
+  enabled: boolean;
+  displayOrder: number;
+  rpcUrl: string | null;
+  confirmations: number;
+}
+
+export interface IPaymentMethodStore {
+  /** List all enabled payment methods, ordered by displayOrder. */
+  listEnabled(): Promise<PaymentMethodRecord[]>;
+  /** List all payment methods (including disabled). */
+  listAll(): Promise<PaymentMethodRecord[]>;
+  /** Get a specific payment method by id. */
+  getById(id: string): Promise<PaymentMethodRecord | null>;
+  /** Get enabled methods by type (stablecoin, eth, btc). */
+  listByType(type: string): Promise<PaymentMethodRecord[]>;
+  /** Upsert a payment method (admin). */
+  upsert(method: PaymentMethodRecord): Promise<void>;
+  /** Enable or disable a payment method (admin). */
+  setEnabled(id: string, enabled: boolean): Promise<void>;
+}
+
+export class DrizzlePaymentMethodStore implements IPaymentMethodStore {
+  constructor(private readonly db: PlatformDb) {}
+
+  async listEnabled(): Promise<PaymentMethodRecord[]> {
+    const rows = await this.db
+      .select()
+      .from(paymentMethods)
+      .where(eq(paymentMethods.enabled, true))
+      .orderBy(paymentMethods.displayOrder);
+    return rows.map(toRecord);
+  }
+
+  async listAll(): Promise<PaymentMethodRecord[]> {
+    const rows = await this.db.select().from(paymentMethods).orderBy(paymentMethods.displayOrder);
+    return rows.map(toRecord);
+  }
+
+  async getById(id: string): Promise<PaymentMethodRecord | null> {
+    const row = (await this.db.select().from(paymentMethods).where(eq(paymentMethods.id, id)))[0];
+    return row ? toRecord(row) : null;
+  }
+
+  async listByType(type: string): Promise<PaymentMethodRecord[]> {
+    const rows = await this.db
+      .select()
+      .from(paymentMethods)
+      .where(and(eq(paymentMethods.type, type), eq(paymentMethods.enabled, true)))
+      .orderBy(paymentMethods.displayOrder);
+    return rows.map(toRecord);
+  }
+
+  async upsert(method: PaymentMethodRecord): Promise<void> {
+    await this.db
+      .insert(paymentMethods)
+      .values({
+        id: method.id,
+        type: method.type,
+        token: method.token,
+        chain: method.chain,
+        contractAddress: method.contractAddress,
+        decimals: method.decimals,
+        displayName: method.displayName,
+        enabled: method.enabled,
+        displayOrder: method.displayOrder,
+        rpcUrl: method.rpcUrl,
+        confirmations: method.confirmations,
+      })
+      .onConflictDoUpdate({
+        target: paymentMethods.id,
+        set: {
+          type: method.type,
+          token: method.token,
+          chain: method.chain,
+          contractAddress: method.contractAddress,
+          decimals: method.decimals,
+          displayName: method.displayName,
+          enabled: method.enabled,
+          displayOrder: method.displayOrder,
+          rpcUrl: method.rpcUrl,
+          confirmations: method.confirmations,
+        },
+      });
+  }
+
+  async setEnabled(id: string, enabled: boolean): Promise<void> {
+    await this.db.update(paymentMethods).set({ enabled }).where(eq(paymentMethods.id, id));
+  }
+}
+
+function toRecord(row: typeof paymentMethods.$inferSelect): PaymentMethodRecord {
+  return {
+    id: row.id,
+    type: row.type,
+    token: row.token,
+    chain: row.chain,
+    contractAddress: row.contractAddress,
+    decimals: row.decimals,
+    displayName: row.displayName,
+    enabled: row.enabled,
+    displayOrder: row.displayOrder,
+    rpcUrl: row.rpcUrl,
+    confirmations: row.confirmations,
+  };
+}

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

@@ -0,0 +1,190 @@
+import { Credit } from "../../credits/credit.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";
+
+export const MIN_CHECKOUT_USD = 10;
+
+export interface UnifiedCheckoutDeps {
+  chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
+  oracle: IPriceOracle;
+  evmXpub: string;
+  btcXpub?: string;
+}
+
+export interface UnifiedCheckoutResult {
+  depositAddress: string;
+  /** Human-readable amount to send (e.g. "50 USDC", "0.014285 ETH"). */
+  displayAmount: string;
+  amountUsd: number;
+  token: string;
+  chain: string;
+  referenceId: string;
+  /** For volatile assets: price at checkout time (USD cents per unit). */
+  priceCents?: number;
+}
+
+/**
+ * Unified checkout — one entry point for all payment methods.
+ *
+ * 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().
+ */
+export async function createUnifiedCheckout(
+  deps: UnifiedCheckoutDeps,
+  method: PaymentMethodRecord,
+  opts: { tenant: string; amountUsd: number },
+): 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.token === "ETH") {
+    return handleNativeEth(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
+  }
+  if (method.token === "BTC") {
+    return handleNativeBtc(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);
+
+  return {
+    depositAddress,
+    displayAmount: `${amountUsd} ${method.token}`,
+    amountUsd,
+    token: method.token,
+    chain: method.chain,
+    referenceId: `erc20:${method.chain}:${depositAddress}`,
+  };
+}
+
+async function handleNativeEth(
+  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: `eth:${method.chain}:${depositAddress}`,
+    priceCents,
+  };
+}
+
+async function handleNativeBtc(
+  deps: UnifiedCheckoutDeps,
+  _method: PaymentMethodRecord,
+  tenant: string,
+  amountUsdCents: number,
+  amountUsd: number,
+): Promise<UnifiedCheckoutResult> {
+  const { priceCents } = await deps.oracle.getPrice("BTC");
+  const expectedSats = centsToNative(amountUsdCents, priceCents, 8);
+
+  // BTC address derivation uses btcXpub — import from btc module
+  const { deriveBtcAddress } = await import("./btc/address-gen.js");
+  if (!deps.btcXpub) throw new Error("BTC payments not configured (no BTC_XPUB)");
+
+  const maxRetries = 3;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+    const depositAddress = deriveBtcAddress(deps.btcXpub, derivationIndex, "mainnet");
+    const referenceId = `btc:${depositAddress}`;
+
+    try {
+      await deps.chargeStore.createStablecoinCharge({
+        referenceId,
+        tenantId: tenant,
+        amountUsdCents,
+        chain: "bitcoin",
+        token: "BTC",
+        depositAddress,
+        derivationIndex,
+      });
+
+      const btcAmount = Number(expectedSats) / 100_000_000;
+      return {
+        depositAddress,
+        displayAmount: `${btcAmount.toFixed(8)} BTC`,
+        amountUsd,
+        token: "BTC",
+        chain: "bitcoin",
+        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/db/schema/crypto.ts

@@ -1,5 +1,5 @@
 import { sql } from "drizzle-orm";
-import { index, integer, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
+import { boolean, index, integer, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
 
 /**
  * Crypto payment charges — tracks the lifecycle of each BTCPay invoice.
@@ -46,6 +46,26 @@ export const watcherCursors = pgTable("watcher_cursors", {
   updatedAt: text("updated_at").notNull().default(sql`(now())`),
 });
 
+/**
+ * Payment method registry — runtime-configurable tokens/chains.
+ * Admin inserts a row to enable a new payment method. No deploy needed.
+ * Contract addresses are immutable on-chain but configurable here.
+ */
+export const paymentMethods = pgTable("payment_methods", {
+  id: text("id").primaryKey(), // "USDC:base", "ETH:base", "BTC:mainnet"
+  type: text("type").notNull(), // "stablecoin", "eth", "btc"
+  token: text("token").notNull(), // "USDC", "ETH", "BTC"
+  chain: text("chain").notNull(), // "base", "ethereum", "bitcoin"
+  contractAddress: text("contract_address"), // null for native (ETH, BTC)
+  decimals: integer("decimals").notNull(),
+  displayName: text("display_name").notNull(),
+  enabled: boolean("enabled").notNull().default(true),
+  displayOrder: integer("display_order").notNull().default(0),
+  rpcUrl: text("rpc_url"), // override per-chain RPC (null = use default)
+  confirmations: integer("confirmations").notNull().default(1),
+  createdAt: text("created_at").notNull().default(sql`(now())`),
+});
+
 /** Processed transaction IDs for watchers without block cursors (e.g. BTC). */
 export const watcherProcessed = pgTable(
   "watcher_processed",