@wopr-network/platform-core 1.64.0 → 1.66.0

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/dist/db/schema/crypto.d.ts

@@ -784,6 +784,57 @@ export declare const paymentMethods: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        keyRingId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "key_ring_id";
+            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;
+        }, {}, {}>;
+        encoding: import("drizzle-orm/pg-core").PgColumn<{
+            name: "encoding";
+            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;
+        }, {}, {}>;
+        pluginId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "plugin_id";
+            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;
+        }, {}, {}>;
         createdAt: import("drizzle-orm/pg-core").PgColumn<{
             name: "created_at";
             tableName: "payment_methods";
@@ -1237,3 +1288,280 @@ export declare const watcherProcessed: import("drizzle-orm/pg-core").PgTableWith
     };
     dialect: "pg";
 }>;
+/**
+ * Key rings — decouples key material (xpub/seed) from payment methods.
+ * Each key ring maps to a BIP-44 coin type + account index.
+ */
+export declare const keyRings: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "key_rings";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "key_rings";
+            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;
+        }, {}, {}>;
+        curve: import("drizzle-orm/pg-core").PgColumn<{
+            name: "curve";
+            tableName: "key_rings";
+            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;
+        }, {}, {}>;
+        derivationScheme: import("drizzle-orm/pg-core").PgColumn<{
+            name: "derivation_scheme";
+            tableName: "key_rings";
+            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;
+        }, {}, {}>;
+        derivationMode: import("drizzle-orm/pg-core").PgColumn<{
+            name: "derivation_mode";
+            tableName: "key_rings";
+            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;
+        }, {}, {}>;
+        keyMaterial: import("drizzle-orm/pg-core").PgColumn<{
+            name: "key_material";
+            tableName: "key_rings";
+            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;
+        }, {}, {}>;
+        coinType: import("drizzle-orm/pg-core").PgColumn<{
+            name: "coin_type";
+            tableName: "key_rings";
+            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;
+        }, {}, {}>;
+        accountIndex: import("drizzle-orm/pg-core").PgColumn<{
+            name: "account_index";
+            tableName: "key_rings";
+            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: "key_rings";
+            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";
+}>;
+/**
+ * Pre-derived address pool — for Ed25519 chains that need offline derivation.
+ * Addresses are derived in batches and assigned on demand.
+ */
+export declare const addressPool: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "address_pool";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "address_pool";
+            dataType: "number";
+            columnType: "PgSerial";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        keyRingId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "key_ring_id";
+            tableName: "address_pool";
+            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;
+        }, {}, {}>;
+        derivationIndex: import("drizzle-orm/pg-core").PgColumn<{
+            name: "derivation_index";
+            tableName: "address_pool";
+            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;
+        }, {}, {}>;
+        publicKey: import("drizzle-orm/pg-core").PgColumn<{
+            name: "public_key";
+            tableName: "address_pool";
+            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;
+        }, {}, {}>;
+        address: import("drizzle-orm/pg-core").PgColumn<{
+            name: "address";
+            tableName: "address_pool";
+            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;
+        }, {}, {}>;
+        assignedTo: import("drizzle-orm/pg-core").PgColumn<{
+            name: "assigned_to";
+            tableName: "address_pool";
+            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;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "address_pool";
+            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";
+}>;

package/dist/db/schema/crypto.js

@@ -1,5 +1,5 @@
 import { sql } from "drizzle-orm";
-import { boolean, index, integer, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
+import { boolean, index, integer, pgTable, primaryKey, serial, text, uniqueIndex } from "drizzle-orm/pg-core";
 /**
  * Crypto payment charges — tracks the lifecycle of each payment.
  * reference_id is the charge ID (e.g. "btc:bc1q...").
@@ -82,6 +82,9 @@ export const paymentMethods = pgTable("payment_methods", {
     oracleAssetId: text("oracle_asset_id"), // CoinGecko slug (e.g. "bitcoin", "tron"). Null = stablecoin (1:1 USD) or use token symbol fallback.
     confirmations: integer("confirmations").notNull().default(1),
     nextIndex: integer("next_index").notNull().default(0), // atomic derivation counter, never reuses
+    keyRingId: text("key_ring_id"), // FK to key_rings.id (nullable during migration)
+    encoding: text("encoding"), // address encoding override (e.g. "bech32", "p2pkh", "evm")
+    pluginId: text("plugin_id"), // plugin identifier (e.g. "evm", "utxo", "solana")
     createdAt: text("created_at").notNull().default(sql `(now())`),
 });
 /**
@@ -134,3 +137,32 @@ export const watcherProcessed = pgTable("watcher_processed", {
     txId: text("tx_id").notNull(),
     processedAt: text("processed_at").notNull().default(sql `(now())`),
 }, (table) => [primaryKey({ columns: [table.watcherId, table.txId] })]);
+/**
+ * Key rings — decouples key material (xpub/seed) from payment methods.
+ * Each key ring maps to a BIP-44 coin type + account index.
+ */
+export const keyRings = pgTable("key_rings", {
+    id: text("id").primaryKey(),
+    curve: text("curve").notNull(), // "secp256k1" | "ed25519"
+    derivationScheme: text("derivation_scheme").notNull(), // "bip32" | "slip10" | "ed25519-hd"
+    derivationMode: text("derivation_mode").notNull().default("on-demand"), // "on-demand" | "pre-derived"
+    keyMaterial: text("key_material").notNull().default("{}"), // JSON: { xpub: "..." }
+    coinType: integer("coin_type").notNull(), // BIP-44 coin type
+    accountIndex: integer("account_index").notNull().default(0),
+    createdAt: text("created_at").notNull().default(sql `(now())`),
+}, (table) => [uniqueIndex("key_rings_path_unique").on(table.coinType, table.accountIndex)]);
+/**
+ * Pre-derived address pool — for Ed25519 chains that need offline derivation.
+ * Addresses are derived in batches and assigned on demand.
+ */
+export const addressPool = pgTable("address_pool", {
+    id: serial("id").primaryKey(),
+    keyRingId: text("key_ring_id")
+        .notNull()
+        .references(() => keyRings.id),
+    derivationIndex: integer("derivation_index").notNull(),
+    publicKey: text("public_key").notNull(),
+    address: text("address").notNull(),
+    assignedTo: text("assigned_to"), // charge reference or tenant ID
+    createdAt: text("created_at").notNull().default(sql `(now())`),
+}, (table) => [uniqueIndex("address_pool_ring_index").on(table.keyRingId, table.derivationIndex)]);

package/dist/db/schema/snapshots.d.ts

@@ -92,7 +92,7 @@ export declare const snapshots: import("drizzle-orm/pg-core").PgTableWithColumns
             tableName: "snapshots";
             dataType: "string";
             columnType: "PgText";
-            data: "nightly" | "on-demand" | "pre-restore";
+            data: "on-demand" | "nightly" | "pre-restore";
             driverParam: string;
             notNull: true;
             hasDefault: true;

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/drizzle/migrations/0023_key_rings_table.sql

@@ -0,0 +1,35 @@
+-- Key rings: decouples key material from payment methods
+CREATE TABLE IF NOT EXISTS "key_rings" (
+  "id" text PRIMARY KEY,
+  "curve" text NOT NULL,
+  "derivation_scheme" text NOT NULL,
+  "derivation_mode" text NOT NULL DEFAULT 'on-demand',
+  "key_material" text NOT NULL DEFAULT '{}',
+  "coin_type" integer NOT NULL,
+  "account_index" integer NOT NULL DEFAULT 0,
+  "created_at" text NOT NULL DEFAULT (now())
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "key_rings_path_unique" ON "key_rings" ("coin_type", "account_index");
+--> statement-breakpoint
+
+-- Pre-derived address pool (for Ed25519 chains)
+CREATE TABLE IF NOT EXISTS "address_pool" (
+  "id" serial PRIMARY KEY,
+  "key_ring_id" text NOT NULL REFERENCES "key_rings"("id"),
+  "derivation_index" integer NOT NULL,
+  "public_key" text NOT NULL,
+  "address" text NOT NULL,
+  "assigned_to" text,
+  "created_at" text NOT NULL DEFAULT (now())
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "address_pool_ring_index" ON "address_pool" ("key_ring_id", "derivation_index");
+--> statement-breakpoint
+
+-- Add new columns to payment_methods
+ALTER TABLE "payment_methods" ADD COLUMN IF NOT EXISTS "key_ring_id" text REFERENCES "key_rings"("id");
+--> statement-breakpoint
+ALTER TABLE "payment_methods" ADD COLUMN IF NOT EXISTS "encoding" text;
+--> statement-breakpoint
+ALTER TABLE "payment_methods" ADD COLUMN IF NOT EXISTS "plugin_id" text;