@wopr-network/platform-core 1.64.0 → 1.65.0

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/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.
@@ -89,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())`),
 });
 
@@ -161,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)],
+);