@wopr-network/platform-core 1.63.2 → 1.65.0

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

@@ -14,6 +14,7 @@ export interface PaymentMethodRecord {
   displayOrder: number;
   iconUrl: string | null;
   rpcUrl: string | null;
+  rpcHeaders: string;
   oracleAddress: string | null;
   xpub: string | null;
   addressType: string;
@@ -21,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 {
@@ -89,6 +93,7 @@ export class DrizzlePaymentMethodStore implements IPaymentMethodStore {
         displayOrder: method.displayOrder,
         iconUrl: method.iconUrl,
         rpcUrl: method.rpcUrl,
+        rpcHeaders: method.rpcHeaders ?? "{}",
         oracleAddress: method.oracleAddress,
         xpub: method.xpub,
         addressType: method.addressType,
@@ -96,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,
@@ -117,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,
         },
       });
   }
@@ -154,6 +165,7 @@ function toRecord(row: typeof paymentMethods.$inferSelect): PaymentMethodRecord
     displayOrder: row.displayOrder,
     iconUrl: row.iconUrl,
     rpcUrl: row.rpcUrl,
+    rpcHeaders: row.rpcHeaders ?? "{}",
     oracleAddress: row.oracleAddress,
     xpub: row.xpub,
     addressType: row.addressType,
@@ -161,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()];
+  }
+}

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

@@ -364,7 +364,7 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
   // Only applies to chains routed through the EVM watcher but storing non-hex addresses.
   // UTXO chains (DOGE p2pkh) never enter this path — they use the UTXO watcher.
   const isTronMethod = (method: { addressType: string; chain: string }): boolean =>
-    method.addressType === "p2pkh" && method.chain === "tron";
+    (method.addressType === "p2pkh" || method.addressType === "keccak-b58check") && method.chain === "tron";
   const toWatcherAddr = (addr: string, method: { addressType: string; chain: string }): string =>
     isTronMethod(method) && isTronAddress(addr) ? tronToHex(addr) : addr;
   const fromWatcherAddr = (addr: string, method: { addressType: string; chain: string }): string =>
@@ -373,7 +373,7 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
   for (const method of nativeEvmMethods) {
     if (!method.rpcUrl) continue;
 
-    const rpcCall = createRpcCaller(method.rpcUrl);
+    const rpcCall = createRpcCaller(method.rpcUrl, JSON.parse(method.rpcHeaders ?? "{}"));
     let latestBlock: number;
     try {
       const latestHex = (await rpcCall("eth_blockNumber", [])) as string;
@@ -452,7 +452,7 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
   for (const method of erc20Methods) {
     if (!method.rpcUrl || !method.contractAddress) continue;
 
-    const rpcCall = createRpcCaller(method.rpcUrl);
+    const rpcCall = createRpcCaller(method.rpcUrl, JSON.parse(method.rpcHeaders ?? "{}"));
     let latestBlock: number;
     try {
       const latestHex = (await rpcCall("eth_blockNumber", [])) as string;
@@ -471,7 +471,7 @@ export async function startWatchers(opts: WatcherServiceOpts): Promise<() => voi
       rpcCall,
       fromBlock: latestBlock,
       watchedAddresses: chainAddresses.map((a) => toWatcherAddr(a, method)),
-      contractAddress: method.contractAddress,
+      contractAddress: toWatcherAddr(method.contractAddress, method),
       decimals: method.decimals,
       confirmations: method.confirmations,
       cursorStore,

package/src/db/schema/crypto.ts

@@ -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.
@@ -80,6 +80,7 @@ export const paymentMethods = pgTable("payment_methods", {
   displayOrder: integer("display_order").notNull().default(0),
   iconUrl: text("icon_url"),
   rpcUrl: text("rpc_url"), // chain node RPC endpoint
+  rpcHeaders: text("rpc_headers").notNull().default("{}"), // JSON: extra headers for RPC calls (e.g. {"TRON-PRO-API-KEY":"xxx"})
   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
   addressType: text("address_type").notNull().default("evm"), // "bech32" (BTC/LTC), "p2pkh" (DOGE/TRX), "evm" (ETH/ERC20)
@@ -88,6 +89,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())`),
 });
 
@@ -160,3 +164,42 @@ export const watcherProcessed = pgTable(
   },
   (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)],
+);