@wopr-network/platform-core 1.42.2 → 1.43.0

package/src/billing/crypto/client.ts

@@ -1,86 +1,166 @@
-import type { CryptoBillingConfig } from "./types.js";
+/**
+ * Crypto Key Server client — for products to call the shared service.
+ *
+ * Replaces BTCPayClient. Products set CRYPTO_SERVICE_URL instead of
+ * BTCPAY_API_KEY + BTCPAY_BASE_URL + BTCPAY_STORE_ID.
+ */
+
+export interface CryptoServiceConfig {
+  /** Base URL of the crypto key server (e.g. http://10.120.0.5:3100) */
+  baseUrl: string;
+  /** Service key for auth (reuses gateway service key) */
+  serviceKey?: string;
+  /** Tenant ID header */
+  tenantId?: string;
+}
+
+export interface DeriveAddressResult {
+  address: string;
+  index: number;
+  chain: string;
+  token: string;
+}
 
-export type { CryptoBillingConfig as CryptoConfig };
+export interface CreateChargeResult {
+  chargeId: string;
+  address: string;
+  chain: string;
+  token: string;
+  amountUsd: number;
+  derivationIndex: number;
+  expiresAt: string;
+}
+
+export interface ChargeStatus {
+  chargeId: string;
+  status: string;
+  address: string | null;
+  chain: string | null;
+  token: string | null;
+  amountUsdCents: number;
+  creditedAt: string | null;
+}
+
+export interface ChainInfo {
+  id: string;
+  token: string;
+  chain: string;
+  decimals: number;
+  displayName: string;
+  contractAddress: string | null;
+  confirmations: number;
+}
 
 /**
- * Lightweight BTCPay Server Greenfield API client.
- *
- * Uses plain fetch — zero vendor dependencies.
- * Auth header format: "token <apiKey>" (NOT "Bearer").
+ * Client for the shared crypto key server.
+ * Products use this instead of running local watchers + holding xpubs.
  */
-export class BTCPayClient {
-  constructor(private readonly config: CryptoBillingConfig) {}
+export class CryptoServiceClient {
+  constructor(private readonly config: CryptoServiceConfig) {}
 
   private headers(): Record<string, string> {
-    return {
-      "Content-Type": "application/json",
-      Authorization: `token ${this.config.apiKey}`,
-    };
+    const h: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.config.serviceKey) h.Authorization = `Bearer ${this.config.serviceKey}`;
+    if (this.config.tenantId) h["X-Tenant-Id"] = this.config.tenantId;
+    return h;
   }
 
-  /**
-   * Create an invoice on the BTCPay store.
-   *
-   * Returns the invoice ID and checkout link (URL to redirect the user).
-   */
-  async createInvoice(opts: {
-    amountUsd: number;
-    orderId: string;
-    buyerEmail?: string;
-    redirectURL?: string;
-  }): Promise<{ id: string; checkoutLink: string }> {
-    const url = `${this.config.baseUrl}/api/v1/stores/${this.config.storeId}/invoices`;
-    const body = {
-      amount: String(opts.amountUsd),
-      currency: "USD",
-      metadata: {
-        orderId: opts.orderId,
-        buyerEmail: opts.buyerEmail,
-      },
-      checkout: {
-        speedPolicy: "MediumSpeed",
-        expirationMinutes: 30,
-        ...(opts.redirectURL ? { redirectURL: opts.redirectURL } : {}),
-      },
-    };
-
-    const res = await fetch(url, {
+  /** Derive the next unused address for a chain. */
+  async deriveAddress(chain: string): Promise<DeriveAddressResult> {
+    const res = await fetch(`${this.config.baseUrl}/address`, {
       method: "POST",
       headers: this.headers(),
-      body: JSON.stringify(body),
+      body: JSON.stringify({ chain }),
     });
-
     if (!res.ok) {
       const text = await res.text().catch(() => "");
-      throw new Error(`BTCPay createInvoice failed (${res.status}): ${text}`);
+      throw new Error(`CryptoService deriveAddress failed (${res.status}): ${text}`);
     }
+    return (await res.json()) as DeriveAddressResult;
+  }
 
-    const data = (await res.json()) as { id: string; checkoutLink: string };
-    return { id: data.id, checkoutLink: data.checkoutLink };
+  /** Create a payment charge — derives address, sets expiry, starts watching. */
+  async createCharge(opts: {
+    chain: string;
+    amountUsd: number;
+    callbackUrl?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<CreateChargeResult> {
+    const res = await fetch(`${this.config.baseUrl}/charges`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(opts),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`CryptoService createCharge failed (${res.status}): ${text}`);
+    }
+    return (await res.json()) as CreateChargeResult;
   }
 
-  /** Get invoice status by ID. */
-  async getInvoice(invoiceId: string): Promise<{ id: string; status: string; amount: string; currency: string }> {
-    const url = `${this.config.baseUrl}/api/v1/stores/${this.config.storeId}/invoices/${invoiceId}`;
-    const res = await fetch(url, { headers: this.headers() });
+  /** Check charge status. */
+  async getCharge(chargeId: string): Promise<ChargeStatus> {
+    const res = await fetch(`${this.config.baseUrl}/charges/${encodeURIComponent(chargeId)}`, {
+      headers: this.headers(),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`CryptoService getCharge failed (${res.status}): ${text}`);
+    }
+    return (await res.json()) as ChargeStatus;
+  }
 
+  /** List all enabled payment methods (for checkout UI). */
+  async listChains(): Promise<ChainInfo[]> {
+    const res = await fetch(`${this.config.baseUrl}/chains`, {
+      headers: this.headers(),
+    });
     if (!res.ok) {
       const text = await res.text().catch(() => "");
-      throw new Error(`BTCPay getInvoice failed (${res.status}): ${text}`);
+      throw new Error(`CryptoService listChains failed (${res.status}): ${text}`);
     }
+    return (await res.json()) as ChainInfo[];
+  }
+}
 
-    return (await res.json()) as { id: string; status: string; amount: string; currency: string };
+/**
+ * Load crypto service config from environment.
+ * Returns null if CRYPTO_SERVICE_URL is not set.
+ *
+ * Also supports legacy BTCPay env vars for backwards compat during migration.
+ */
+export function loadCryptoConfig(): CryptoServiceConfig | null {
+  const baseUrl = process.env.CRYPTO_SERVICE_URL;
+  if (baseUrl) {
+    return {
+      baseUrl,
+      serviceKey: process.env.CRYPTO_SERVICE_KEY,
+      tenantId: process.env.TENANT_ID,
+    };
   }
+  return null;
 }
 
+// Legacy type alias for backwards compat
+export type CryptoConfig = CryptoServiceConfig;
+
 /**
- * Load BTCPay config from environment variables.
- * Returns null if any required var is missing.
+ * @deprecated Use CryptoServiceClient instead. BTCPay is replaced by the crypto key server.
+ * Kept for backwards compat — products still import BTCPayClient during migration.
  */
-export function loadCryptoConfig(): CryptoBillingConfig | null {
-  const apiKey = process.env.BTCPAY_API_KEY;
-  const baseUrl = process.env.BTCPAY_BASE_URL;
-  const storeId = process.env.BTCPAY_STORE_ID;
-  if (!apiKey || !baseUrl || !storeId) return null;
-  return { apiKey, baseUrl, storeId };
+export class BTCPayClient {
+  constructor(_config: { apiKey: string; baseUrl: string; storeId: string }) {}
+
+  async createInvoice(_opts: {
+    amountUsd: number;
+    orderId: string;
+    buyerEmail?: string;
+    redirectURL?: string;
+  }): Promise<{ id: string; checkoutLink: string }> {
+    throw new Error("BTCPayClient is deprecated — migrate to CryptoServiceClient");
+  }
+
+  async getInvoice(_invoiceId: string): Promise<{ id: string; status: string; amount: string; currency: string }> {
+    throw new Error("BTCPayClient is deprecated — migrate to CryptoServiceClient");
+  }
 }

package/src/billing/crypto/index.ts

@@ -2,11 +2,20 @@ 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 { CryptoConfig } from "./client.js";
-export { BTCPayClient, loadCryptoConfig } from "./client.js";
+export type {
+  ChainInfo,
+  ChargeStatus,
+  CreateChargeResult,
+  CryptoConfig,
+  CryptoServiceConfig,
+  DeriveAddressResult,
+} from "./client.js";
+export { BTCPayClient, 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 * from "./oracle/index.js";
 export type { IPaymentMethodStore, PaymentMethodRecord } from "./payment-method-store.js";
 export { DrizzlePaymentMethodStore } from "./payment-method-store.js";

package/src/billing/crypto/key-server-entry.ts

@@ -0,0 +1,52 @@
+/**
+ * Standalone entry point for the crypto key server.
+ *
+ * Deploys on the chain server (pay.wopr.bot:3100).
+ * Boots: postgres → migrations → key server routes → watchers → serve.
+ *
+ * Usage: node dist/billing/crypto/key-server-entry.js
+ */
+/* biome-ignore-all lint/suspicious/noConsole: standalone entry point */
+import { serve } from "@hono/node-server";
+import { drizzle } from "drizzle-orm/node-postgres";
+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 { createKeyServerApp } from "./key-server.js";
+import { DrizzlePaymentMethodStore } from "./payment-method-store.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;
+
+if (!DATABASE_URL) {
+  console.error("DATABASE_URL is required");
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const pool = new pg.Pool({ connectionString: DATABASE_URL });
+
+  // Run migrations FIRST, before creating schema-typed db
+  console.log("[crypto-key-server] Running migrations...");
+  await migrate(drizzle(pool), { migrationsFolder: "./drizzle/migrations" });
+
+  // Now create the schema-typed db (columns guaranteed to exist)
+  console.log("[crypto-key-server] Connecting...");
+  const db = drizzle(pool, { schema }) as unknown as import("../../db/index.js").DrizzleDb;
+
+  const chargeStore = new DrizzleCryptoChargeRepository(db);
+  const methodStore = new DrizzlePaymentMethodStore(db);
+
+  const app = createKeyServerApp({ db, chargeStore, methodStore, serviceKey: SERVICE_KEY, adminToken: ADMIN_TOKEN });
+
+  console.log(`[crypto-key-server] Listening on :${PORT}`);
+  serve({ fetch: app.fetch, port: PORT });
+}
+
+main().catch((err) => {
+  console.error("[crypto-key-server] Fatal:", err);
+  process.exit(1);
+});

package/src/billing/crypto/key-server.ts

@@ -0,0 +1,315 @@
+/**
+ * Crypto Key Server — shared address derivation + charge management.
+ *
+ * Deploys on the chain server (pay.wopr.bot) alongside bitcoind.
+ * Products don't run watchers or hold xpubs. They request addresses
+ * and receive webhooks.
+ *
+ * ~200 lines of new code wrapping platform-core's existing crypto modules.
+ */
+import { eq, sql } from "drizzle-orm";
+import { Hono } from "hono";
+import type { DrizzleDb } from "../../db/index.js";
+import { derivedAddresses, pathAllocations, paymentMethods } from "../../db/schema/crypto.js";
+import { deriveAddress, deriveP2pkhAddress } from "./btc/address-gen.js";
+import type { ICryptoChargeRepository } from "./charge-store.js";
+import { deriveDepositAddress } from "./evm/address-gen.js";
+import type { IPaymentMethodStore } from "./payment-method-store.js";
+
+export interface KeyServerDeps {
+  db: DrizzleDb;
+  chargeStore: ICryptoChargeRepository;
+  methodStore: IPaymentMethodStore;
+  /** Bearer token for product API routes. If unset, auth is disabled. */
+  serviceKey?: string;
+  /** Bearer token for admin routes. If unset, admin routes are disabled. */
+  adminToken?: string;
+}
+
+/**
+ * Derive the next unused address for a chain.
+ * Atomically increments next_index and records address in a single transaction.
+ */
+async function deriveNextAddress(
+  db: DrizzleDb,
+  chainId: string,
+  tenantId?: string,
+): Promise<{ address: string; index: number; chain: string; token: string }> {
+  // Wrap in transaction: if the address insert fails, next_index is not consumed.
+  return (db as unknown as { transaction: (fn: (tx: DrizzleDb) => Promise<unknown>) => Promise<unknown> }).transaction(
+    async (tx: DrizzleDb) => {
+      // Atomic increment: UPDATE ... SET next_index = next_index + 1 RETURNING *
+      const [method] = await tx
+        .update(paymentMethods)
+        .set({ nextIndex: sql`${paymentMethods.nextIndex} + 1` })
+        .where(eq(paymentMethods.id, chainId))
+        .returning();
+
+      if (!method) throw new Error(`Chain not found: ${chainId}`);
+      if (!method.xpub) throw new Error(`No xpub configured for chain: ${chainId}`);
+
+      // The index we use is the value BEFORE increment (returned value - 1)
+      const index = method.nextIndex - 1;
+
+      // Route to the right derivation function
+      let address: string;
+      if (method.type === "native" && method.chain === "dogecoin") {
+        address = deriveP2pkhAddress(method.xpub, index, "dogecoin");
+      } else if (method.type === "native" && (method.chain === "bitcoin" || method.chain === "litecoin")) {
+        address = deriveAddress(method.xpub, index, "mainnet", method.chain as "bitcoin" | "litecoin");
+      } else {
+        // EVM (all ERC20 + native ETH) — same derivation
+        address = deriveDepositAddress(method.xpub, index);
+      }
+
+      // Record in immutable log (inside same transaction)
+      await tx.insert(derivedAddresses).values({
+        chainId,
+        derivationIndex: index,
+        address: address.toLowerCase(),
+        tenantId,
+      });
+
+      return { address, index, chain: method.chain, token: method.token };
+    },
+  ) as Promise<{ address: string; index: number; chain: string; token: string }>;
+}
+
+/** Validate Bearer token from Authorization header. */
+function requireAuth(header: string | undefined, expected: string): boolean {
+  if (!expected) return true; // auth disabled
+  return header === `Bearer ${expected}`;
+}
+
+/**
+ * Create the Hono app for the crypto key server.
+ * Mount this on the chain server at the root.
+ */
+export function createKeyServerApp(deps: KeyServerDeps): Hono {
+  const app = new Hono();
+
+  // --- Auth middleware for product routes ---
+  app.use("/address", async (c, next) => {
+    if (deps.serviceKey && !requireAuth(c.req.header("Authorization"), deps.serviceKey)) {
+      return c.json({ error: "Unauthorized" }, 401);
+    }
+    await next();
+  });
+  app.use("/charges/*", async (c, next) => {
+    if (deps.serviceKey && !requireAuth(c.req.header("Authorization"), deps.serviceKey)) {
+      return c.json({ error: "Unauthorized" }, 401);
+    }
+    await next();
+  });
+  app.use("/charges", async (c, next) => {
+    if (deps.serviceKey && !requireAuth(c.req.header("Authorization"), deps.serviceKey)) {
+      return c.json({ error: "Unauthorized" }, 401);
+    }
+    await next();
+  });
+
+  // --- Auth middleware for admin routes ---
+  app.use("/admin/*", async (c, next) => {
+    if (!deps.adminToken) return c.json({ error: "Admin API disabled" }, 403);
+    if (!requireAuth(c.req.header("Authorization"), deps.adminToken)) {
+      return c.json({ error: "Unauthorized" }, 401);
+    }
+    await next();
+  });
+
+  // --- Product API ---
+
+  /** POST /address — derive next unused address */
+  app.post("/address", async (c) => {
+    const body = await c.req.json<{ chain: string }>();
+    if (!body.chain) return c.json({ error: "chain is required" }, 400);
+
+    const tenantId = c.req.header("X-Tenant-Id");
+    const result = await deriveNextAddress(deps.db, body.chain, tenantId ?? undefined);
+    return c.json(result, 201);
+  });
+
+  /** POST /charges — create charge + derive address + start watching */
+  app.post("/charges", async (c) => {
+    const body = await c.req.json<{
+      chain: string;
+      amountUsd: number;
+      callbackUrl?: string;
+      metadata?: Record<string, unknown>;
+    }>();
+
+    if (!body.chain || typeof body.amountUsd !== "number" || !Number.isFinite(body.amountUsd) || body.amountUsd <= 0) {
+      return c.json({ error: "chain is required and amountUsd must be a positive finite number" }, 400);
+    }
+
+    const tenantId = c.req.header("X-Tenant-Id") ?? "unknown";
+    const { address, index, chain, token } = await deriveNextAddress(deps.db, body.chain, tenantId);
+
+    const amountUsdCents = Math.round(body.amountUsd * 100);
+    const referenceId = `${token.toLowerCase()}:${address.toLowerCase()}`;
+
+    await deps.chargeStore.createStablecoinCharge({
+      referenceId,
+      tenantId,
+      amountUsdCents,
+      chain,
+      token,
+      depositAddress: address,
+      derivationIndex: index,
+    });
+
+    return c.json(
+      {
+        chargeId: referenceId,
+        address,
+        chain: body.chain,
+        token,
+        amountUsd: body.amountUsd,
+        derivationIndex: index,
+        expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(), // 30 min
+      },
+      201,
+    );
+  });
+
+  /** GET /charges/:id — check charge status */
+  app.get("/charges/:id", async (c) => {
+    const charge = await deps.chargeStore.getByReferenceId(c.req.param("id"));
+    if (!charge) return c.json({ error: "Charge not found" }, 404);
+
+    return c.json({
+      chargeId: charge.referenceId,
+      status: charge.status,
+      address: charge.depositAddress,
+      chain: charge.chain,
+      token: charge.token,
+      amountUsdCents: charge.amountUsdCents,
+      creditedAt: charge.creditedAt,
+    });
+  });
+
+  /** GET /chains — list enabled payment methods (for checkout UI) */
+  app.get("/chains", async (c) => {
+    const methods = await deps.methodStore.listEnabled();
+    return c.json(
+      methods.map((m) => ({
+        id: m.id,
+        token: m.token,
+        chain: m.chain,
+        decimals: m.decimals,
+        displayName: m.displayName,
+        contractAddress: m.contractAddress,
+        confirmations: m.confirmations,
+      })),
+    );
+  });
+
+  // --- Admin API ---
+
+  /** GET /admin/next-path — which derivation path to use for a coin type */
+  app.get("/admin/next-path", async (c) => {
+    const coinType = Number(c.req.query("coin_type"));
+    if (!Number.isInteger(coinType)) return c.json({ error: "coin_type must be an integer" }, 400);
+
+    // Find all allocations for this coin type
+    const existing = await deps.db.select().from(pathAllocations).where(eq(pathAllocations.coinType, coinType));
+
+    if (existing.length === 0) {
+      return c.json({
+        coin_type: coinType,
+        account_index: 0,
+        path: `m/44'/${coinType}'/0'`,
+        status: "available",
+      });
+    }
+
+    // If already allocated, return info about existing allocation
+    const latest = existing.sort(
+      (a: { accountIndex: number }, b: { accountIndex: number }) => b.accountIndex - a.accountIndex,
+    )[0];
+
+    // Find chains using this coin type's allocations
+    const chainIds = existing.map((a: { chainId: string | null }) => a.chainId).filter(Boolean);
+    return c.json({
+      coin_type: coinType,
+      account_index: latest.accountIndex,
+      path: `m/44'/${coinType}'/${latest.accountIndex}'`,
+      status: "allocated",
+      allocated_to: chainIds,
+      note: "xpub already registered — reuse for new chains with same key type",
+      next_available: {
+        account_index: latest.accountIndex + 1,
+        path: `m/44'/${coinType}'/${latest.accountIndex + 1}'`,
+      },
+    });
+  });
+
+  /** POST /admin/chains — register a new chain with its xpub */
+  app.post("/admin/chains", async (c) => {
+    const body = await c.req.json<{
+      id: string;
+      coin_type: number;
+      account_index: number;
+      network: string;
+      type: string;
+      token: string;
+      chain: string;
+      contract?: string;
+      decimals: number;
+      xpub: string;
+      rpc_url: string;
+      confirmations?: number;
+      display_name?: string;
+      oracle_address?: string;
+    }>();
+
+    if (!body.id || !body.xpub || !body.token) {
+      return c.json({ error: "id, xpub, and token are required" }, 400);
+    }
+
+    // Record the path allocation (idempotent — ignore if already exists)
+    const inserted = (await deps.db
+      .insert(pathAllocations)
+      .values({
+        coinType: body.coin_type,
+        accountIndex: body.account_index,
+        chainId: body.id,
+        xpub: body.xpub,
+      })
+      .onConflictDoNothing()) as { rowCount: number };
+
+    if (inserted.rowCount === 0) {
+      return c.json(
+        { error: "Path allocation already exists", path: `m/44'/${body.coin_type}'/${body.account_index}'` },
+        409,
+      );
+    }
+
+    // Upsert the payment method
+    await deps.methodStore.upsert({
+      id: body.id,
+      type: body.type ?? "native",
+      token: body.token,
+      chain: body.chain ?? body.network,
+      contractAddress: body.contract ?? null,
+      decimals: body.decimals,
+      displayName: body.display_name ?? `${body.token} on ${body.network}`,
+      enabled: true,
+      displayOrder: 0,
+      rpcUrl: body.rpc_url,
+      oracleAddress: body.oracle_address ?? null,
+      xpub: body.xpub,
+      confirmations: body.confirmations ?? 6,
+    });
+
+    return c.json({ id: body.id, path: `m/44'/${body.coin_type}'/${body.account_index}'` }, 201);
+  });
+
+  /** DELETE /admin/chains/:id — soft disable */
+  app.delete("/admin/chains/:id", async (c) => {
+    await deps.methodStore.setEnabled(c.req.param("id"), false);
+    return c.body(null, 204);
+  });
+
+  return app;
+}

package/src/db/schema/crypto.ts

@@ -50,12 +50,16 @@ export const watcherCursors = pgTable("watcher_cursors", {
  * 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.
+ *
+ * nextIndex is an atomic counter for HD derivation — never reuses an index.
+ * Increment via UPDATE ... SET next_index = next_index + 1 RETURNING next_index.
  */
 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"
+  id: text("id").primaryKey(), // "btc", "base-usdc", "arb-usdc", "doge"
+  type: text("type").notNull(), // "erc20", "native", "btc"
+  token: text("token").notNull(), // "USDC", "ETH", "BTC", "DOGE"
+  chain: text("chain").notNull(), // "base", "ethereum", "bitcoin", "arbitrum"
+  network: text("network").notNull().default("mainnet"), // "mainnet", "base", "arbitrum"
   contractAddress: text("contract_address"), // null for native (ETH, BTC)
   decimals: integer("decimals").notNull(),
   displayName: text("display_name").notNull(),
@@ -65,9 +69,46 @@ export const paymentMethods = pgTable("payment_methods", {
   oracleAddress: text("oracle_address"), // Chainlink feed address for price (null = 1:1 stablecoin)
   xpub: text("xpub"), // HD wallet extended public key for deposit address derivation
   confirmations: integer("confirmations").notNull().default(1),
+  nextIndex: integer("next_index").notNull().default(0), // atomic derivation counter, never reuses
   createdAt: text("created_at").notNull().default(sql`(now())`),
 });
 
+/**
+ * BIP-44 path allocation registry — tracks which derivation paths are in use.
+ * The server knows which paths are allocated so you never collide.
+ * The seed phrase never touches the server — only xpubs.
+ */
+export const pathAllocations = pgTable(
+  "path_allocations",
+  {
+    coinType: integer("coin_type").notNull(), // BIP44 coin type (0=BTC, 60=ETH, 3=DOGE, 501=SOL)
+    accountIndex: integer("account_index").notNull(), // m/44'/{coin_type}'/{index}'
+    chainId: text("chain_id").references(() => paymentMethods.id),
+    xpub: text("xpub").notNull(),
+    allocatedAt: text("allocated_at").notNull().default(sql`(now())`),
+  },
+  (table) => [primaryKey({ columns: [table.coinType, table.accountIndex] })],
+);
+
+/**
+ * Every address ever derived — immutable append-only log.
+ * Used for auditing and ensuring no address is ever reused.
+ */
+export const derivedAddresses = pgTable(
+  "derived_addresses",
+  {
+    id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+    chainId: text("chain_id")
+      .notNull()
+      .references(() => paymentMethods.id),
+    derivationIndex: integer("derivation_index").notNull(),
+    address: text("address").notNull().unique(),
+    tenantId: text("tenant_id"),
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+  },
+  (table) => [index("idx_derived_addresses_chain").on(table.chainId)],
+);
+
 /** Processed transaction IDs for watchers without block cursors (e.g. BTC). */
 export const watcherProcessed = pgTable(
   "watcher_processed",