@wopr-network/platform-core 1.65.0 → 1.66.0

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

@@ -8,6 +8,7 @@
  */
 /* biome-ignore-all lint/suspicious/noConsole: standalone entry point */
 import { serve } from "@hono/node-server";
+import { bitcoinPlugin, dogecoinPlugin, evmPlugin, litecoinPlugin, solanaPlugin, tronPlugin, } from "@wopr-network/crypto-plugins";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { migrate } from "drizzle-orm/node-postgres/migrator";
 import pg from "pg";
@@ -21,6 +22,8 @@ import { CoinGeckoOracle } from "./oracle/coingecko.js";
 import { CompositeOracle } from "./oracle/composite.js";
 import { FixedPriceOracle } from "./oracle/fixed.js";
 import { DrizzlePaymentMethodStore } from "./payment-method-store.js";
+import { PluginRegistry } from "./plugin/registry.js";
+import { startPluginWatchers } from "./plugin-watcher-service.js";
 import { startWatchers } from "./watcher-service.js";
 const PORT = Number(process.env.PORT ?? "3100");
 const DATABASE_URL = process.env.DATABASE_URL;
@@ -57,6 +60,15 @@ async function main() {
     }
     const coingecko = new CoinGeckoOracle({ tokenIds: dbTokenIds });
     const oracle = new CompositeOracle(chainlink, coingecko);
+    // Build plugin registry — one plugin per chain family
+    const registry = new PluginRegistry();
+    registry.register(bitcoinPlugin);
+    registry.register(litecoinPlugin);
+    registry.register(dogecoinPlugin);
+    registry.register(evmPlugin);
+    registry.register(tronPlugin);
+    registry.register(solanaPlugin);
+    console.log(`[crypto-key-server] Registered ${registry.list().length} chain plugins:`, registry.list().map((p) => p.pluginId));
     const app = createKeyServerApp({
         db,
         chargeStore,
@@ -64,20 +76,33 @@ async function main() {
         oracle,
         serviceKey: SERVICE_KEY,
         adminToken: ADMIN_TOKEN,
+        registry,
     });
-    // Boot watchers (BTC + EVM) — polls for payments, sends webhooks
+    // Boot plugin-driven watchers — polls for payments, sends webhooks.
+    // Falls back to legacy startWatchers() if USE_LEGACY_WATCHERS=1 is set.
     const cursorStore = new DrizzleWatcherCursorStore(db);
-    const stopWatchers = await startWatchers({
-        db,
-        chargeStore,
-        methodStore,
-        cursorStore,
-        oracle,
-        bitcoindUser: BITCOIND_USER,
-        bitcoindPassword: BITCOIND_PASSWORD,
-        serviceKey: SERVICE_KEY,
-        log: (msg, meta) => console.log(`[watcher] ${msg}`, meta ?? ""),
-    });
+    const useLegacy = process.env.USE_LEGACY_WATCHERS === "1";
+    const stopWatchers = useLegacy
+        ? await startWatchers({
+            db,
+            chargeStore,
+            methodStore,
+            cursorStore,
+            oracle,
+            bitcoindUser: BITCOIND_USER,
+            bitcoindPassword: BITCOIND_PASSWORD,
+            serviceKey: SERVICE_KEY,
+            log: (msg, meta) => console.log(`[watcher] ${msg}`, meta ?? ""),
+        })
+        : await startPluginWatchers({
+            db,
+            chargeStore,
+            methodStore,
+            cursorStore,
+            oracle,
+            registry,
+            log: (msg, meta) => console.log(`[watcher] ${msg}`, meta ?? ""),
+        });
     const server = serve({ fetch: app.fetch, port: PORT });
     console.log(`[crypto-key-server] Listening on :${PORT}`);
     // Graceful shutdown — stop accepting requests, drain watchers, close pool

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

@@ -1,8 +1,18 @@
+/**
+ * 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 { 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";
+import type { PluginRegistry } from "./plugin/registry.js";
 export interface KeyServerDeps {
     db: DrizzleDb;
     chargeStore: ICryptoChargeRepository;
@@ -12,6 +22,8 @@ export interface KeyServerDeps {
     serviceKey?: string;
     /** Bearer token for admin routes. If unset, admin routes are disabled. */
     adminToken?: string;
+    /** Plugin registry for address encoding. Falls back to address-gen.ts when absent. */
+    registry?: PluginRegistry;
 }
 /**
  * Create the Hono app for the crypto key server.

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

@@ -7,6 +7,7 @@
  *
  * ~200 lines of new code wrapping platform-core's existing crypto modules.
  */
+import { HDKey } from "@scure/bip32";
 import { eq, sql } from "drizzle-orm";
 import { Hono } from "hono";
 import { derivedAddresses, pathAllocations, paymentMethods } from "../../db/schema/crypto.js";
@@ -21,7 +22,7 @@ import { AssetNotSupportedError } from "./oracle/types.js";
  * address. The unique constraint on derived_addresses.address prevents reuse.
  * On collision, we skip the index and retry (up to maxRetries).
  */
-async function deriveNextAddress(db, chainId, tenantId) {
+async function deriveNextAddress(db, chainId, tenantId, registry) {
     const maxRetries = 10;
     const dbWithTx = db;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -46,7 +47,23 @@ async function deriveNextAddress(db, chainId, tenantId) {
         catch {
             throw new Error(`Invalid encoding_params JSON for chain ${chainId}: ${method.encodingParams}`);
         }
-        const address = deriveAddress(method.xpub, index, method.addressType, encodingParams);
+        // Plugin-driven encoding: look up the plugin, use its encoder.
+        // Falls back to legacy deriveAddress() when no registry or no matching plugin.
+        let address;
+        const pluginId = method.pluginId ?? (method.watcherType === "utxo" ? "bitcoin" : method.watcherType);
+        const plugin = registry?.get(pluginId ?? "");
+        const encodingKey = method.encoding ?? method.addressType;
+        const encoder = plugin?.encoders[encodingKey];
+        if (encoder) {
+            const master = HDKey.fromExtendedKey(method.xpub);
+            const child = master.deriveChild(0).deriveChild(index);
+            if (!child.publicKey)
+                throw new Error("Failed to derive public key");
+            address = encoder.encode(child.publicKey, encodingParams);
+        }
+        else {
+            address = deriveAddress(method.xpub, index, method.addressType, encodingParams);
+        }
         // Step 2: Record in immutable log. If this address was already derived by a
         // sibling chain (shared xpub), the unique constraint fires and we retry
         // with the next index (which is already incremented above).
@@ -121,7 +138,7 @@ export function createKeyServerApp(deps) {
         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);
+        const result = await deriveNextAddress(deps.db, body.chain, tenantId ?? undefined, deps.registry);
         return c.json(result, 201);
     });
     /** POST /charges — create charge + derive address + start watching */
@@ -131,7 +148,7 @@ export function createKeyServerApp(deps) {
             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 { address, index, chain, token } = await deriveNextAddress(deps.db, body.chain, tenantId, deps.registry);
         // Look up payment method for decimals + oracle config
         const method = await deps.methodStore.getById(body.chain);
         if (!method)

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

@@ -0,0 +1,32 @@
+/**
+ * Plugin-driven watcher service — replaces the hardcoded watcher-service.ts.
+ *
+ * Instead of importing BtcWatcher/EvmWatcher/EthWatcher directly,
+ * this delegates to IChainPlugin.createWatcher() from the plugin registry.
+ * Adding a new chain = register a plugin + INSERT a payment_methods row.
+ *
+ * Payment flow is unchanged:
+ *   plugin.poll() -> PaymentEvent[] -> handlePayment() -> credit + webhook
+ */
+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";
+import type { PluginRegistry } from "./plugin/registry.js";
+export interface PluginWatcherServiceOpts {
+    db: DrizzleDb;
+    chargeStore: ICryptoChargeRepository;
+    methodStore: IPaymentMethodStore;
+    cursorStore: IWatcherCursorStore;
+    oracle: IPriceOracle;
+    registry: PluginRegistry;
+    pollIntervalMs?: number;
+    log?: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Boot plugin-driven watchers for all enabled payment methods.
+ *
+ * Returns a cleanup function that stops all poll timers and watchers.
+ */
+export declare function startPluginWatchers(opts: PluginWatcherServiceOpts): Promise<() => void>;

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

@@ -0,0 +1,113 @@
+/**
+ * Plugin-driven watcher service — replaces the hardcoded watcher-service.ts.
+ *
+ * Instead of importing BtcWatcher/EvmWatcher/EthWatcher directly,
+ * this delegates to IChainPlugin.createWatcher() from the plugin registry.
+ * Adding a new chain = register a plugin + INSERT a payment_methods row.
+ *
+ * Payment flow is unchanged:
+ *   plugin.poll() -> PaymentEvent[] -> handlePayment() -> credit + webhook
+ */
+import { handlePayment } from "./watcher-service.js";
+/** Map legacy watcher_type values to plugin IDs for backward compatibility. */
+const WATCHER_TYPE_TO_PLUGIN = {
+    utxo: "bitcoin",
+    evm: "evm",
+};
+function resolvePlugin(registry, method) {
+    // Prefer explicit plugin_id, fall back to watcher_type mapping
+    const id = method.pluginId ?? WATCHER_TYPE_TO_PLUGIN[method.watcherType];
+    return id ? registry.get(id) : undefined;
+}
+/**
+ * Boot plugin-driven watchers for all enabled payment methods.
+ *
+ * Returns a cleanup function that stops all poll timers and watchers.
+ */
+export async function startPluginWatchers(opts) {
+    const { db, chargeStore, methodStore, cursorStore, oracle, registry } = opts;
+    const pollMs = opts.pollIntervalMs ?? 15_000;
+    const log = opts.log ?? (() => { });
+    const methods = await methodStore.listEnabled();
+    const timers = [];
+    const watchers = [];
+    for (const method of methods) {
+        if (!method.rpcUrl)
+            continue;
+        const plugin = resolvePlugin(registry, method);
+        if (!plugin) {
+            log("No plugin found, skipping method", { id: method.id, chain: method.chain, watcherType: method.watcherType });
+            continue;
+        }
+        const watcher = plugin.createWatcher({
+            rpcUrl: method.rpcUrl,
+            rpcHeaders: JSON.parse(method.rpcHeaders ?? "{}"),
+            oracle,
+            cursorStore,
+            token: method.token,
+            chain: method.chain,
+            contractAddress: method.contractAddress ?? undefined,
+            decimals: method.decimals,
+            confirmations: method.confirmations,
+        });
+        try {
+            await watcher.init();
+        }
+        catch (err) {
+            log("Watcher init failed, skipping", { chain: method.chain, token: method.token, error: String(err) });
+            continue;
+        }
+        // Seed watched addresses from active charges
+        const active = await chargeStore.listActiveDepositAddresses();
+        const addrs = active.filter((a) => a.chain === method.chain && a.token === method.token).map((a) => a.address);
+        watcher.setWatchedAddresses(addrs);
+        watchers.push(watcher);
+        log(`Plugin watcher started (${method.chain}:${method.token})`, {
+            plugin: plugin.pluginId,
+            addresses: addrs.length,
+        });
+        let polling = false;
+        timers.push(setInterval(async () => {
+            if (polling)
+                return;
+            polling = true;
+            try {
+                // Refresh watched addresses each cycle
+                const fresh = await chargeStore.listActiveDepositAddresses();
+                const freshAddrs = fresh
+                    .filter((a) => a.chain === method.chain && a.token === method.token)
+                    .map((a) => a.address);
+                watcher.setWatchedAddresses(freshAddrs);
+                const events = await watcher.poll();
+                for (const ev of events) {
+                    log("Plugin payment", {
+                        chain: ev.chain,
+                        token: ev.token,
+                        to: ev.to,
+                        txHash: ev.txHash,
+                        confirmations: ev.confirmations,
+                    });
+                    await handlePayment(db, chargeStore, ev.to, ev.rawAmount, {
+                        txHash: ev.txHash,
+                        confirmations: ev.confirmations,
+                        confirmationsRequired: ev.confirmationsRequired,
+                        amountReceivedCents: ev.amountUsdCents,
+                    }, log);
+                }
+            }
+            catch (err) {
+                log("Plugin poll error", { chain: method.chain, token: method.token, error: String(err) });
+            }
+            finally {
+                polling = false;
+            }
+        }, pollMs));
+    }
+    log("All plugin watchers started", { count: watchers.length, pollMs });
+    return () => {
+        for (const t of timers)
+            clearInterval(t);
+        for (const w of watchers)
+            w.stop();
+    };
+}

package/docs/superpowers/specs/2026-03-24-crypto-plugin-architecture-design.md

@@ -174,19 +174,32 @@ interface WatcherOpts {
 
 Replaced by `key_rings` unique constraint on `(coin_type, account_index)`.
 
-## Plugin Packages
+## Plugin Monorepo
 
-Each chain is its own npm package:
+Single npm package: `@wopr-network/crypto-plugins`. One version, one CI, one install.
 
-| Package | Curve | Chains |
-|---------|-------|--------|
-| `crypto-plugin-evm` | secp256k1 | ETH, Base, Arbitrum, Polygon, Optimism, Avalanche, BSC |
-| `crypto-plugin-utxo-common` | — | Shared UTXO watcher, bitcoind RPC, sweep logic |
-| `crypto-plugin-bitcoin` | secp256k1 | BTC (depends on utxo-common) |
-| `crypto-plugin-litecoin` | secp256k1 | LTC (depends on utxo-common) |
-| `crypto-plugin-dogecoin` | secp256k1 | DOGE (depends on utxo-common) |
-| `crypto-plugin-tron` | secp256k1 | TRX + TRC-20 (handles T-address ↔ hex conversion internally) |
-| `crypto-plugin-solana` | ed25519 | SOL + SPL tokens |
+```
+crypto-plugins/
+  src/
+    evm/           # ETH, Base, Arbitrum, Polygon, Optimism, Avalanche, BSC
+    bitcoin/       # BTC (uses shared/utxo)
+    litecoin/      # LTC (uses shared/utxo)
+    dogecoin/      # DOGE (uses shared/utxo)
+    tron/          # TRX + TRC-20 (T-address ↔ hex conversion)
+    solana/        # SOL + SPL tokens (Ed25519)
+    shared/        # UTXO common (bitcoind RPC, watcher, sweep), test helpers
+    index.ts       # barrel export of all plugins
+  package.json     # peer dep on @wopr-network/platform-core
+```
+
+| Plugin | Curve | Subpath | Chains |
+|--------|-------|---------|--------|
+| `evm` | secp256k1 | `@wopr-network/crypto-plugins/evm` | ETH + all EVM L1/L2s |
+| `bitcoin` | secp256k1 | `@wopr-network/crypto-plugins/bitcoin` | BTC |
+| `litecoin` | secp256k1 | `@wopr-network/crypto-plugins/litecoin` | LTC |
+| `dogecoin` | secp256k1 | `@wopr-network/crypto-plugins/dogecoin` | DOGE |
+| `tron` | secp256k1 | `@wopr-network/crypto-plugins/tron` | TRX + TRC-20 |
+| `solana` | ed25519 | `@wopr-network/crypto-plugins/solana` | SOL + SPL |
 
 Platform-core exports interfaces as a peer dependency:
 ```
@@ -198,9 +211,9 @@ Platform-core exports interfaces as a peer dependency:
 Explicit imports in the key-server entry point:
 
 ```ts
-import { evmPlugin } from "@wopr-network/crypto-plugin-evm";
-import { bitcoinPlugin } from "@wopr-network/crypto-plugin-bitcoin";
-import { solanaPlugin } from "@wopr-network/crypto-plugin-solana";
+import { evmPlugin } from "@wopr-network/crypto-plugins/evm";
+import { bitcoinPlugin } from "@wopr-network/crypto-plugins/bitcoin";
+import { solanaPlugin } from "@wopr-network/crypto-plugins/solana";
 
 const registry = new PluginRegistry();
 registry.register(evmPlugin);
@@ -245,21 +258,18 @@ No per-chain env vars. RPC URLs and headers come from the chain server.
 
 ## Adding a New Chain
 
-### secp256k1 chain (e.g. XRP)
-1. `npm install @wopr-network/crypto-plugin-xrp`
-2. Add `registry.register(xrpPlugin)` to entry point
-3. Insert `key_ring` row (curve: secp256k1, derivation_mode: on-demand, coin_type: 144)
-4. Insert `payment_method` row (plugin_id: "xrp", encoding: "base58-xrp", key_ring_id: "xrp-main")
-5. Restart
-
-### Ed25519 chain (e.g. Solana)
-1. `npm install @wopr-network/crypto-plugin-solana`
-2. Add `registry.register(solanaPlugin)` to entry point
-3. Insert `key_ring` row (curve: ed25519, derivation_mode: pool, coin_type: 501)
-4. Insert `payment_method` row (plugin_id: "solana", encoding: "base58-solana", key_ring_id: "sol-main")
-5. Replenish pool: `openssl enc ... -d | npx @wopr-network/crypto-sweep replenish --chain solana --count 200`
+### Existing chain type (e.g. XRP — secp256k1)
+1. Add `src/xrp/` to `@wopr-network/crypto-plugins` with encoder + watcher + sweeper
+2. Add subpath export, bump version, publish
+3. Add `registry.register(xrpPlugin)` to key-server entry point
+4. `npm update @wopr-network/crypto-plugins`
+5. Insert `key_ring` row + `payment_method` row in DB
 6. Restart
 
+### New curve (e.g. Solana — Ed25519)
+Same as above, plus:
+- Replenish pool: `openssl enc ... -d | npx @wopr-network/crypto-sweep replenish --chain solana --count 200`
+
 No code changes to platform-core for either path.
 
 ## Client API
@@ -282,19 +292,23 @@ Only change: admin `POST /admin/chains` takes `key_ring_id` + `encoding` + `plug
 - Backfill: create key_ring rows from existing xpub + address_type data, set `key_ring_id` + `encoding` + `plugin_id` on existing payment_methods
 - DB migration 2: drop old columns (`xpub`, `address_type`, `watcher_type`), drop `path_allocations`
 
-### Phase 2 — Extract existing chains into plugins
-- `crypto-plugin-evm` — from current `evm/watcher.ts`, `evm/eth-watcher.ts`
-- `crypto-plugin-utxo-common` + bitcoin/litecoin/dogecoin — from current UTXO watcher code
-- `crypto-plugin-tron` — from current tron code (address conversion handled internally by plugin)
+### Phase 2 — Extract existing chains into `@wopr-network/crypto-plugins` monorepo
+- New repo: `wopr-network/crypto-plugins`
+- `src/evm/` — from current `evm/watcher.ts`, `evm/eth-watcher.ts`
+- `src/shared/utxo/` — shared bitcoind RPC, UTXO watcher, sweep base
+- `src/bitcoin/`, `src/litecoin/`, `src/dogecoin/` — thin configs on shared/utxo
+- `src/tron/` — from current tron code (address conversion internal)
+- `src/shared/test-helpers/` — mock RPC, test fixtures
 - All existing behavior preserved, just restructured
+- One npm package, one version, subpath exports per chain
 
 ### Phase 3 — Unified sweep CLI
-- `@wopr-network/crypto-sweep` — sweep + replenish modes
+- Sweep + replenish modes live in `@wopr-network/crypto-plugins/sweep` (same monorepo, separate entrypoint)
 - Replaces `sweep-stablecoins.ts` and `sweep-tron.ts`
 
 ### Phase 4 — New chains
-- `crypto-plugin-solana` — first Ed25519 chain, proves pool model
-- Then TON, XRP, etc.
+- `src/solana/` in crypto-plugins — first Ed25519 chain, proves pool model
+- Then TON, XRP, etc. — each is a new directory + subpath export + version bump
 
 Each phase is independently deployable. Phase 1+2 is a refactor with no behavior change. Phase 3 replaces scripts. Phase 4 is new functionality.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.65.0",
+  "version": "1.66.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -140,6 +140,7 @@
     "@scure/base": "^2.0.0",
     "@scure/bip32": "^2.0.1",
     "@scure/bip39": "^2.0.1",
+    "@wopr-network/crypto-plugins": "^1.0.1",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.1",
     "postmark": "^4.0.7",

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

@@ -8,6 +8,14 @@
  */
 /* biome-ignore-all lint/suspicious/noConsole: standalone entry point */
 import { serve } from "@hono/node-server";
+import {
+  bitcoinPlugin,
+  dogecoinPlugin,
+  evmPlugin,
+  litecoinPlugin,
+  solanaPlugin,
+  tronPlugin,
+} from "@wopr-network/crypto-plugins";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { migrate } from "drizzle-orm/node-postgres/migrator";
 import pg from "pg";
@@ -21,6 +29,8 @@ import { CoinGeckoOracle } from "./oracle/coingecko.js";
 import { CompositeOracle } from "./oracle/composite.js";
 import { FixedPriceOracle } from "./oracle/fixed.js";
 import { DrizzlePaymentMethodStore } from "./payment-method-store.js";
+import { PluginRegistry } from "./plugin/registry.js";
+import { startPluginWatchers } from "./plugin-watcher-service.js";
 import { startWatchers } from "./watcher-service.js";
 
 const PORT = Number(process.env.PORT ?? "3100");
@@ -64,6 +74,19 @@ async function main(): Promise<void> {
   const coingecko = new CoinGeckoOracle({ tokenIds: dbTokenIds });
   const oracle = new CompositeOracle(chainlink, coingecko);
 
+  // Build plugin registry — one plugin per chain family
+  const registry = new PluginRegistry();
+  registry.register(bitcoinPlugin);
+  registry.register(litecoinPlugin);
+  registry.register(dogecoinPlugin);
+  registry.register(evmPlugin);
+  registry.register(tronPlugin);
+  registry.register(solanaPlugin);
+  console.log(
+    `[crypto-key-server] Registered ${registry.list().length} chain plugins:`,
+    registry.list().map((p) => p.pluginId),
+  );
+
   const app = createKeyServerApp({
     db,
     chargeStore,
@@ -71,21 +94,34 @@ async function main(): Promise<void> {
     oracle,
     serviceKey: SERVICE_KEY,
     adminToken: ADMIN_TOKEN,
+    registry,
   });
 
-  // Boot watchers (BTC + EVM) — polls for payments, sends webhooks
+  // Boot plugin-driven watchers — polls for payments, sends webhooks.
+  // Falls back to legacy startWatchers() if USE_LEGACY_WATCHERS=1 is set.
   const cursorStore = new DrizzleWatcherCursorStore(db);
-  const stopWatchers = await startWatchers({
-    db,
-    chargeStore,
-    methodStore,
-    cursorStore,
-    oracle,
-    bitcoindUser: BITCOIND_USER,
-    bitcoindPassword: BITCOIND_PASSWORD,
-    serviceKey: SERVICE_KEY,
-    log: (msg, meta) => console.log(`[watcher] ${msg}`, meta ?? ""),
-  });
+  const useLegacy = process.env.USE_LEGACY_WATCHERS === "1";
+  const stopWatchers = useLegacy
+    ? await startWatchers({
+        db,
+        chargeStore,
+        methodStore,
+        cursorStore,
+        oracle,
+        bitcoindUser: BITCOIND_USER,
+        bitcoindPassword: BITCOIND_PASSWORD,
+        serviceKey: SERVICE_KEY,
+        log: (msg, meta) => console.log(`[watcher] ${msg}`, meta ?? ""),
+      })
+    : await startPluginWatchers({
+        db,
+        chargeStore,
+        methodStore,
+        cursorStore,
+        oracle,
+        registry,
+        log: (msg, meta) => console.log(`[watcher] ${msg}`, meta ?? ""),
+      });
 
   const server = serve({ fetch: app.fetch, port: PORT });
   console.log(`[crypto-key-server] Listening on :${PORT}`);

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

@@ -7,6 +7,8 @@
  *
  * ~200 lines of new code wrapping platform-core's existing crypto modules.
  */
+
+import { HDKey } from "@scure/bip32";
 import { eq, sql } from "drizzle-orm";
 import { Hono } from "hono";
 import type { DrizzleDb } from "../../db/index.js";
@@ -18,6 +20,7 @@ import { centsToNative } from "./oracle/convert.js";
 import type { IPriceOracle } from "./oracle/types.js";
 import { AssetNotSupportedError } from "./oracle/types.js";
 import type { IPaymentMethodStore } from "./payment-method-store.js";
+import type { PluginRegistry } from "./plugin/registry.js";
 
 export interface KeyServerDeps {
   db: DrizzleDb;
@@ -28,6 +31,8 @@ export interface KeyServerDeps {
   serviceKey?: string;
   /** Bearer token for admin routes. If unset, admin routes are disabled. */
   adminToken?: string;
+  /** Plugin registry for address encoding. Falls back to address-gen.ts when absent. */
+  registry?: PluginRegistry;
 }
 
 /**
@@ -42,6 +47,7 @@ async function deriveNextAddress(
   db: DrizzleDb,
   chainId: string,
   tenantId?: string,
+  registry?: PluginRegistry,
 ): Promise<{ address: string; index: number; chain: string; token: string }> {
   const maxRetries = 10;
   const dbWithTx = db as unknown as { transaction: (fn: (tx: DrizzleDb) => Promise<unknown>) => Promise<unknown> };
@@ -68,7 +74,23 @@ async function deriveNextAddress(
     } catch {
       throw new Error(`Invalid encoding_params JSON for chain ${chainId}: ${method.encodingParams}`);
     }
-    const address = deriveAddress(method.xpub, index, method.addressType, encodingParams);
+
+    // Plugin-driven encoding: look up the plugin, use its encoder.
+    // Falls back to legacy deriveAddress() when no registry or no matching plugin.
+    let address: string;
+    const pluginId = method.pluginId ?? (method.watcherType === "utxo" ? "bitcoin" : method.watcherType);
+    const plugin = registry?.get(pluginId ?? "");
+    const encodingKey = method.encoding ?? method.addressType;
+    const encoder = plugin?.encoders[encodingKey];
+
+    if (encoder) {
+      const master = HDKey.fromExtendedKey(method.xpub);
+      const child = master.deriveChild(0).deriveChild(index);
+      if (!child.publicKey) throw new Error("Failed to derive public key");
+      address = encoder.encode(child.publicKey, encodingParams as Record<string, string | undefined>);
+    } else {
+      address = deriveAddress(method.xpub, index, method.addressType, encodingParams);
+    }
 
     // Step 2: Record in immutable log. If this address was already derived by a
     // sibling chain (shared xpub), the unique constraint fires and we retry
@@ -146,7 +168,7 @@ export function createKeyServerApp(deps: KeyServerDeps): Hono {
     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);
+    const result = await deriveNextAddress(deps.db, body.chain, tenantId ?? undefined, deps.registry);
     return c.json(result, 201);
   });
 
@@ -164,7 +186,7 @@ export function createKeyServerApp(deps: KeyServerDeps): Hono {
     }
 
     const tenantId = c.req.header("X-Tenant-Id") ?? "unknown";
-    const { address, index, chain, token } = await deriveNextAddress(deps.db, body.chain, tenantId);
+    const { address, index, chain, token } = await deriveNextAddress(deps.db, body.chain, tenantId, deps.registry);
 
     // Look up payment method for decimals + oracle config
     const method = await deps.methodStore.getById(body.chain);

package/src/billing/crypto/plugin-watcher-service.ts

@@ -0,0 +1,148 @@
+/**
+ * Plugin-driven watcher service — replaces the hardcoded watcher-service.ts.
+ *
+ * Instead of importing BtcWatcher/EvmWatcher/EthWatcher directly,
+ * this delegates to IChainPlugin.createWatcher() from the plugin registry.
+ * Adding a new chain = register a plugin + INSERT a payment_methods row.
+ *
+ * Payment flow is unchanged:
+ *   plugin.poll() -> PaymentEvent[] -> handlePayment() -> credit + webhook
+ */
+
+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, PaymentMethodRecord } from "./payment-method-store.js";
+import type { IChainPlugin, IChainWatcher } from "./plugin/interfaces.js";
+import type { PluginRegistry } from "./plugin/registry.js";
+import { handlePayment } from "./watcher-service.js";
+
+export interface PluginWatcherServiceOpts {
+  db: DrizzleDb;
+  chargeStore: ICryptoChargeRepository;
+  methodStore: IPaymentMethodStore;
+  cursorStore: IWatcherCursorStore;
+  oracle: IPriceOracle;
+  registry: PluginRegistry;
+  pollIntervalMs?: number;
+  log?: (msg: string, meta?: Record<string, unknown>) => void;
+}
+
+/** Map legacy watcher_type values to plugin IDs for backward compatibility. */
+const WATCHER_TYPE_TO_PLUGIN: Record<string, string> = {
+  utxo: "bitcoin",
+  evm: "evm",
+};
+
+function resolvePlugin(registry: PluginRegistry, method: PaymentMethodRecord): IChainPlugin | undefined {
+  // Prefer explicit plugin_id, fall back to watcher_type mapping
+  const id = method.pluginId ?? WATCHER_TYPE_TO_PLUGIN[method.watcherType];
+  return id ? registry.get(id) : undefined;
+}
+
+/**
+ * Boot plugin-driven watchers for all enabled payment methods.
+ *
+ * Returns a cleanup function that stops all poll timers and watchers.
+ */
+export async function startPluginWatchers(opts: PluginWatcherServiceOpts): Promise<() => void> {
+  const { db, chargeStore, methodStore, cursorStore, oracle, registry } = opts;
+  const pollMs = opts.pollIntervalMs ?? 15_000;
+  const log = opts.log ?? (() => {});
+
+  const methods = await methodStore.listEnabled();
+  const timers: ReturnType<typeof setInterval>[] = [];
+  const watchers: IChainWatcher[] = [];
+
+  for (const method of methods) {
+    if (!method.rpcUrl) continue;
+
+    const plugin = resolvePlugin(registry, method);
+    if (!plugin) {
+      log("No plugin found, skipping method", { id: method.id, chain: method.chain, watcherType: method.watcherType });
+      continue;
+    }
+
+    const watcher = plugin.createWatcher({
+      rpcUrl: method.rpcUrl,
+      rpcHeaders: JSON.parse(method.rpcHeaders ?? "{}"),
+      oracle,
+      cursorStore,
+      token: method.token,
+      chain: method.chain,
+      contractAddress: method.contractAddress ?? undefined,
+      decimals: method.decimals,
+      confirmations: method.confirmations,
+    });
+
+    try {
+      await watcher.init();
+    } catch (err) {
+      log("Watcher init failed, skipping", { chain: method.chain, token: method.token, error: String(err) });
+      continue;
+    }
+
+    // Seed watched addresses from active charges
+    const active = await chargeStore.listActiveDepositAddresses();
+    const addrs = active.filter((a) => a.chain === method.chain && a.token === method.token).map((a) => a.address);
+    watcher.setWatchedAddresses(addrs);
+
+    watchers.push(watcher);
+    log(`Plugin watcher started (${method.chain}:${method.token})`, {
+      plugin: plugin.pluginId,
+      addresses: addrs.length,
+    });
+
+    let polling = false;
+    timers.push(
+      setInterval(async () => {
+        if (polling) return;
+        polling = true;
+        try {
+          // Refresh watched addresses each cycle
+          const fresh = await chargeStore.listActiveDepositAddresses();
+          const freshAddrs = fresh
+            .filter((a) => a.chain === method.chain && a.token === method.token)
+            .map((a) => a.address);
+          watcher.setWatchedAddresses(freshAddrs);
+
+          const events = await watcher.poll();
+          for (const ev of events) {
+            log("Plugin payment", {
+              chain: ev.chain,
+              token: ev.token,
+              to: ev.to,
+              txHash: ev.txHash,
+              confirmations: ev.confirmations,
+            });
+            await handlePayment(
+              db,
+              chargeStore,
+              ev.to,
+              ev.rawAmount,
+              {
+                txHash: ev.txHash,
+                confirmations: ev.confirmations,
+                confirmationsRequired: ev.confirmationsRequired,
+                amountReceivedCents: ev.amountUsdCents,
+              },
+              log,
+            );
+          }
+        } catch (err) {
+          log("Plugin poll error", { chain: method.chain, token: method.token, error: String(err) });
+        } finally {
+          polling = false;
+        }
+      }, pollMs),
+    );
+  }
+
+  log("All plugin watchers started", { count: watchers.length, pollMs });
+
+  return () => {
+    for (const t of timers) clearInterval(t);
+    for (const w of watchers) w.stop();
+  };
+}