@wopr-network/platform-core 1.64.0 → 1.66.0

package/drizzle/migrations/0024_backfill_key_rings.sql

@@ -0,0 +1,75 @@
+-- Create key rings from existing payment method xpubs
+-- Each unique (coin_type via path_allocations) gets a key ring
+
+-- EVM chains (coin type 60)
+INSERT INTO "key_rings" ("id", "curve", "derivation_scheme", "derivation_mode", "key_material", "coin_type", "account_index")
+SELECT DISTINCT 'evm-main', 'secp256k1', 'bip32', 'on-demand',
+  json_build_object('xpub', pm.xpub)::text,
+  pa.coin_type, pa.account_index
+FROM path_allocations pa
+JOIN payment_methods pm ON pm.id = pa.chain_id
+WHERE pa.coin_type = 60
+LIMIT 1
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+
+-- BTC (coin type 0)
+INSERT INTO "key_rings" ("id", "curve", "derivation_scheme", "derivation_mode", "key_material", "coin_type", "account_index")
+SELECT DISTINCT 'btc-main', 'secp256k1', 'bip32', 'on-demand',
+  json_build_object('xpub', pm.xpub)::text,
+  pa.coin_type, pa.account_index
+FROM path_allocations pa
+JOIN payment_methods pm ON pm.id = pa.chain_id
+WHERE pa.coin_type = 0
+LIMIT 1
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+
+-- LTC (coin type 2)
+INSERT INTO "key_rings" ("id", "curve", "derivation_scheme", "derivation_mode", "key_material", "coin_type", "account_index")
+SELECT DISTINCT 'ltc-main', 'secp256k1', 'bip32', 'on-demand',
+  json_build_object('xpub', pm.xpub)::text,
+  pa.coin_type, pa.account_index
+FROM path_allocations pa
+JOIN payment_methods pm ON pm.id = pa.chain_id
+WHERE pa.coin_type = 2
+LIMIT 1
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+
+-- DOGE (coin type 3)
+INSERT INTO "key_rings" ("id", "curve", "derivation_scheme", "derivation_mode", "key_material", "coin_type", "account_index")
+SELECT DISTINCT 'doge-main', 'secp256k1', 'bip32', 'on-demand',
+  json_build_object('xpub', pm.xpub)::text,
+  pa.coin_type, pa.account_index
+FROM path_allocations pa
+JOIN payment_methods pm ON pm.id = pa.chain_id
+WHERE pa.coin_type = 3
+LIMIT 1
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+
+-- TRON (coin type 195)
+INSERT INTO "key_rings" ("id", "curve", "derivation_scheme", "derivation_mode", "key_material", "coin_type", "account_index")
+SELECT DISTINCT 'tron-main', 'secp256k1', 'bip32', 'on-demand',
+  json_build_object('xpub', pm.xpub)::text,
+  pa.coin_type, pa.account_index
+FROM path_allocations pa
+JOIN payment_methods pm ON pm.id = pa.chain_id
+WHERE pa.coin_type = 195
+LIMIT 1
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+
+-- Backfill payment_methods with key_ring_id, encoding, plugin_id
+UPDATE payment_methods SET
+  key_ring_id = CASE
+    WHEN chain IN ('arbitrum','avalanche','base','base-sepolia','bsc','optimism','polygon','sepolia') THEN 'evm-main'
+    WHEN chain = 'bitcoin' THEN 'btc-main'
+    WHEN chain = 'litecoin' THEN 'ltc-main'
+    WHEN chain = 'dogecoin' THEN 'doge-main'
+    WHEN chain = 'tron' THEN 'tron-main'
+  END,
+  encoding = address_type,
+  plugin_id = watcher_type
+WHERE key_ring_id IS NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.64.0",
+  "version": "1.66.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,6 +72,10 @@
     "./api/routes/verify-email": "./dist/api/routes/verify-email.js",
     "./api/routes/ws-auth": "./dist/api/routes/ws-auth.js",
     "./trpc": "./dist/trpc/index.js",
+    "./crypto-plugin": {
+      "import": "./dist/billing/crypto/plugin/index.js",
+      "types": "./dist/billing/crypto/plugin/index.d.ts"
+    },
     "./*": "./dist/*.js"
   },
   "scripts": {
@@ -136,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/index.ts

@@ -33,6 +33,15 @@ export {
 export * from "./oracle/index.js";
 export type { IPaymentMethodStore, PaymentMethodRecord } from "./payment-method-store.js";
 export { DrizzlePaymentMethodStore } from "./payment-method-store.js";
+export type {
+  IAddressEncoder,
+  IChainPlugin,
+  IChainWatcher,
+  ICurveDeriver,
+  ISweepStrategy,
+  PaymentEvent,
+} from "./plugin/index.js";
+export { PluginRegistry } from "./plugin/index.js";
 export type { CryptoCharge, CryptoChargeStatus, CryptoPaymentState } from "./types.js";
 export type { UnifiedCheckoutDeps, UnifiedCheckoutResult } from "./unified-checkout.js";
 export { createUnifiedCheckout, MIN_CHECKOUT_USD as MIN_PAYMENT_USD, MIN_CHECKOUT_USD } from "./unified-checkout.js";

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);
@@ -364,6 +386,9 @@ export function createKeyServerApp(deps: KeyServerDeps): Hono {
       watcherType: body.watcher_type ?? "evm",
       oracleAssetId: body.oracle_asset_id ?? null,
       confirmations: body.confirmations ?? 6,
+      keyRingId: null,
+      encoding: null,
+      pluginId: null,
     });
 
     // Record the path allocation (idempotent — ignore if already exists)

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

@@ -22,6 +22,9 @@ export interface PaymentMethodRecord {
   watcherType: string;
   oracleAssetId: string | null;
   confirmations: number;
+  keyRingId: string | null;
+  encoding: string | null;
+  pluginId: string | null;
 }
 
 export interface IPaymentMethodStore {
@@ -98,6 +101,9 @@ export class DrizzlePaymentMethodStore implements IPaymentMethodStore {
         watcherType: method.watcherType,
         oracleAssetId: method.oracleAssetId,
         confirmations: method.confirmations,
+        keyRingId: method.keyRingId,
+        encoding: method.encoding,
+        pluginId: method.pluginId,
       })
       .onConflictDoUpdate({
         target: paymentMethods.id,
@@ -119,6 +125,9 @@ export class DrizzlePaymentMethodStore implements IPaymentMethodStore {
           watcherType: method.watcherType,
           oracleAssetId: method.oracleAssetId,
           confirmations: method.confirmations,
+          keyRingId: method.keyRingId,
+          encoding: method.encoding,
+          pluginId: method.pluginId,
         },
       });
   }
@@ -164,5 +173,8 @@ function toRecord(row: typeof paymentMethods.$inferSelect): PaymentMethodRecord
     watcherType: row.watcherType,
     oracleAssetId: row.oracleAssetId,
     confirmations: row.confirmations,
+    keyRingId: row.keyRingId,
+    encoding: row.encoding,
+    pluginId: row.pluginId,
   };
 }

package/src/billing/crypto/plugin/__tests__/integration.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import type { IChainPlugin, PaymentEvent, WatcherOpts } from "../interfaces.js";
+import { PluginRegistry } from "../registry.js";
+
+describe("plugin integration — registry → watcher → events", () => {
+  it("full lifecycle: register → create watcher → poll → events", async () => {
+    const mockEvent: PaymentEvent = {
+      chain: "test",
+      token: "TEST",
+      from: "0xsender",
+      to: "0xreceiver",
+      rawAmount: "1000",
+      amountUsdCents: 100,
+      txHash: "0xhash",
+      blockNumber: 42,
+      confirmations: 6,
+      confirmationsRequired: 6,
+    };
+
+    const plugin: IChainPlugin = {
+      pluginId: "test",
+      supportedCurve: "secp256k1",
+      encoders: {},
+      createWatcher: (_opts: WatcherOpts) => ({
+        init: async () => {},
+        poll: async () => [mockEvent],
+        setWatchedAddresses: () => {},
+        getCursor: () => 42,
+        stop: () => {},
+      }),
+      createSweeper: () => ({ scan: async () => [], sweep: async () => [] }),
+      version: 1,
+    };
+
+    const registry = new PluginRegistry();
+    registry.register(plugin);
+
+    const resolved = registry.getOrThrow("test");
+    const watcher = resolved.createWatcher({
+      rpcUrl: "http://localhost:8545",
+      rpcHeaders: {},
+      oracle: {
+        getPrice: async () => ({ priceMicros: 3500_000000 }),
+      },
+      cursorStore: {
+        get: async () => null,
+        save: async () => {},
+        getConfirmationCount: async () => null,
+        saveConfirmationCount: async () => {},
+      },
+      token: "TEST",
+      chain: "test",
+      decimals: 18,
+      confirmations: 6,
+    });
+
+    await watcher.init();
+    const events = await watcher.poll();
+    expect(events).toHaveLength(1);
+    expect(events[0].txHash).toBe("0xhash");
+    expect(watcher.getCursor()).toBe(42);
+    watcher.stop();
+  });
+});

package/src/billing/crypto/plugin/__tests__/interfaces.test.ts

@@ -0,0 +1,51 @@
+// src/billing/crypto/plugin/__tests__/interfaces.test.ts
+import { describe, expect, it } from "vitest";
+import type { EncodingParams, IAddressEncoder, IChainWatcher, ICurveDeriver, PaymentEvent } from "../interfaces.js";
+
+describe("plugin interfaces — type contracts", () => {
+  it("PaymentEvent has required fields", () => {
+    const event: PaymentEvent = {
+      chain: "ethereum",
+      token: "ETH",
+      from: "0xabc",
+      to: "0xdef",
+      rawAmount: "1000000000000000000",
+      amountUsdCents: 350000,
+      txHash: "0x123",
+      blockNumber: 100,
+      confirmations: 6,
+      confirmationsRequired: 6,
+    };
+    expect(event.chain).toBe("ethereum");
+    expect(event.amountUsdCents).toBe(350000);
+  });
+
+  it("ICurveDeriver contract is satisfiable", () => {
+    const deriver: ICurveDeriver = {
+      derivePublicKey: (_chain: number, _index: number) => new Uint8Array(33),
+      getCurve: () => "secp256k1",
+    };
+    expect(deriver.getCurve()).toBe("secp256k1");
+    expect(deriver.derivePublicKey(0, 0)).toBeInstanceOf(Uint8Array);
+  });
+
+  it("IAddressEncoder contract is satisfiable", () => {
+    const encoder: IAddressEncoder = {
+      encode: (_pk: Uint8Array, _params: EncodingParams) => "bc1qtest",
+      encodingType: () => "bech32",
+    };
+    expect(encoder.encodingType()).toBe("bech32");
+    expect(encoder.encode(new Uint8Array(33), { hrp: "bc" })).toBe("bc1qtest");
+  });
+
+  it("IChainWatcher contract is satisfiable", () => {
+    const watcher: IChainWatcher = {
+      init: async () => {},
+      poll: async () => [],
+      setWatchedAddresses: () => {},
+      getCursor: () => 0,
+      stop: () => {},
+    };
+    expect(watcher.getCursor()).toBe(0);
+  });
+});

package/src/billing/crypto/plugin/__tests__/registry.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import type { IChainPlugin } from "../interfaces.js";
+import { PluginRegistry } from "../registry.js";
+
+function mockPlugin(id: string, curve: "secp256k1" | "ed25519" = "secp256k1"): IChainPlugin {
+  return {
+    pluginId: id,
+    supportedCurve: curve,
+    encoders: {},
+    createWatcher: () => ({
+      init: async () => {},
+      poll: async () => [],
+      setWatchedAddresses: () => {},
+      getCursor: () => 0,
+      stop: () => {},
+    }),
+    createSweeper: () => ({ scan: async () => [], sweep: async () => [] }),
+    version: 1,
+  };
+}
+
+describe("PluginRegistry", () => {
+  it("registers and retrieves a plugin", () => {
+    const reg = new PluginRegistry();
+    reg.register(mockPlugin("evm"));
+    expect(reg.get("evm")).toBeDefined();
+    expect(reg.get("evm")?.pluginId).toBe("evm");
+  });
+
+  it("throws on duplicate registration", () => {
+    const reg = new PluginRegistry();
+    reg.register(mockPlugin("evm"));
+    expect(() => reg.register(mockPlugin("evm"))).toThrow("already registered");
+  });
+
+  it("returns undefined for unknown plugin", () => {
+    const reg = new PluginRegistry();
+    expect(reg.get("unknown")).toBeUndefined();
+  });
+
+  it("lists all registered plugins", () => {
+    const reg = new PluginRegistry();
+    reg.register(mockPlugin("evm"));
+    reg.register(mockPlugin("solana", "ed25519"));
+    expect(reg.list()).toHaveLength(2);
+    expect(
+      reg
+        .list()
+        .map((p) => p.pluginId)
+        .sort(),
+    ).toEqual(["evm", "solana"]);
+  });
+
+  it("getOrThrow throws for unknown plugin", () => {
+    const reg = new PluginRegistry();
+    expect(() => reg.getOrThrow("nope")).toThrow("not registered");
+  });
+});

package/src/billing/crypto/plugin/index.ts

@@ -0,0 +1,17 @@
+export type {
+  DepositInfo,
+  EncodingParams,
+  IAddressEncoder,
+  IChainPlugin,
+  IChainWatcher,
+  ICurveDeriver,
+  IPriceOracle,
+  ISweepStrategy,
+  IWatcherCursorStore,
+  KeyPair,
+  PaymentEvent,
+  SweeperOpts,
+  SweepResult,
+  WatcherOpts,
+} from "./interfaces.js";
+export { PluginRegistry } from "./registry.js";

package/src/billing/crypto/plugin/interfaces.ts

@@ -0,0 +1,106 @@
+// src/billing/crypto/plugin/interfaces.ts
+
+export interface PaymentEvent {
+  chain: string;
+  token: string;
+  from: string;
+  to: string;
+  rawAmount: string;
+  amountUsdCents: number;
+  txHash: string;
+  blockNumber: number;
+  confirmations: number;
+  confirmationsRequired: number;
+}
+
+export interface ICurveDeriver {
+  derivePublicKey(chainIndex: number, addressIndex: number): Uint8Array;
+  getCurve(): "secp256k1" | "ed25519";
+}
+
+export interface EncodingParams {
+  hrp?: string;
+  version?: string;
+  [key: string]: string | undefined;
+}
+
+export interface IAddressEncoder {
+  encode(publicKey: Uint8Array, params: EncodingParams): string;
+  encodingType(): string;
+}
+
+export interface KeyPair {
+  privateKey: Uint8Array;
+  publicKey: Uint8Array;
+  address: string;
+  index: number;
+}
+
+export interface DepositInfo {
+  index: number;
+  address: string;
+  nativeBalance: bigint;
+  tokenBalances: Array<{ token: string; balance: bigint; decimals: number }>;
+}
+
+export interface SweepResult {
+  index: number;
+  address: string;
+  token: string;
+  amount: string;
+  txHash: string;
+}
+
+export interface ISweepStrategy {
+  scan(keys: KeyPair[], treasury: string): Promise<DepositInfo[]>;
+  sweep(keys: KeyPair[], treasury: string, dryRun: boolean): Promise<SweepResult[]>;
+}
+
+export interface IPriceOracle {
+  getPrice(token: string, feedAddress?: string): Promise<{ priceMicros: number }>;
+}
+
+export interface IWatcherCursorStore {
+  get(watcherId: string): Promise<number | null>;
+  save(watcherId: string, cursor: number): Promise<void>;
+  getConfirmationCount(watcherId: string, txKey: string): Promise<number | null>;
+  saveConfirmationCount(watcherId: string, txKey: string, count: number): Promise<void>;
+}
+
+export interface WatcherOpts {
+  rpcUrl: string;
+  rpcHeaders: Record<string, string>;
+  oracle: IPriceOracle;
+  cursorStore: IWatcherCursorStore;
+  token: string;
+  chain: string;
+  contractAddress?: string;
+  decimals: number;
+  confirmations: number;
+}
+
+export interface SweeperOpts {
+  rpcUrl: string;
+  rpcHeaders: Record<string, string>;
+  token: string;
+  chain: string;
+  contractAddress?: string;
+  decimals: number;
+}
+
+export interface IChainWatcher {
+  init(): Promise<void>;
+  poll(): Promise<PaymentEvent[]>;
+  setWatchedAddresses(addresses: string[]): void;
+  getCursor(): number;
+  stop(): void;
+}
+
+export interface IChainPlugin {
+  pluginId: string;
+  supportedCurve: "secp256k1" | "ed25519";
+  encoders: Record<string, IAddressEncoder>;
+  createWatcher(opts: WatcherOpts): IChainWatcher;
+  createSweeper(opts: SweeperOpts): ISweepStrategy;
+  version: number;
+}

package/src/billing/crypto/plugin/registry.ts

@@ -0,0 +1,26 @@
+import type { IChainPlugin } from "./interfaces.js";
+
+export class PluginRegistry {
+  private plugins = new Map<string, IChainPlugin>();
+
+  register(plugin: IChainPlugin): void {
+    if (this.plugins.has(plugin.pluginId)) {
+      throw new Error(`Plugin "${plugin.pluginId}" is already registered`);
+    }
+    this.plugins.set(plugin.pluginId, plugin);
+  }
+
+  get(pluginId: string): IChainPlugin | undefined {
+    return this.plugins.get(pluginId);
+  }
+
+  getOrThrow(pluginId: string): IChainPlugin {
+    const plugin = this.plugins.get(pluginId);
+    if (!plugin) throw new Error(`Plugin "${pluginId}" is not registered`);
+    return plugin;
+  }
+
+  list(): IChainPlugin[] {
+    return [...this.plugins.values()];
+  }
+}