@wopr-network/crypto-plugins 1.0.1

package/src/shared/utxo/rpc.ts

@@ -0,0 +1,80 @@
+import type { RpcCall } from "./types.js";
+
+interface RpcConfig {
+	rpcUrl: string;
+	rpcUser: string;
+	rpcPassword: string;
+}
+
+/**
+ * Parse RPC credentials from a URL with embedded basic auth.
+ * e.g. "http://user:pass@host:8332" -> { rpcUrl: "http://host:8332", rpcUser: "user", rpcPassword: "pass" }
+ * If no auth in URL, returns the URL as-is with empty credentials.
+ */
+export function parseRpcUrl(url: string): RpcConfig {
+	try {
+		const parsed = new URL(url);
+		if (parsed.username) {
+			const rpcUser = decodeURIComponent(parsed.username);
+			const rpcPassword = decodeURIComponent(parsed.password);
+			parsed.username = "";
+			parsed.password = "";
+			return { rpcUrl: parsed.toString().replace(/\/$/, ""), rpcUser, rpcPassword };
+		}
+	} catch {
+		// Not a valid URL with auth, return as-is
+	}
+	return { rpcUrl: url, rpcUser: "", rpcPassword: "" };
+}
+
+/**
+ * Create a JSON-RPC caller for a bitcoind-compatible node (BTC, LTC, DOGE).
+ * Uses basic auth and JSON-RPC 1.0 protocol.
+ */
+export function createBitcoindRpc(rpcUrl: string, rpcUser: string, rpcPassword: string): RpcCall {
+	let id = 0;
+	const auth = btoa(`${rpcUser}:${rpcPassword}`);
+	return async (method: string, params: unknown[]): Promise<unknown> => {
+		const res = await fetch(rpcUrl, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Basic ${auth}`,
+			},
+			body: JSON.stringify({ jsonrpc: "1.0", id: ++id, method, params }),
+		});
+		if (!res.ok) throw new Error(`RPC ${method} failed: ${res.status}`);
+		const data = (await res.json()) as { result?: unknown; error?: { message: string } };
+		if (data.error) throw new Error(`RPC ${method}: ${data.error.message}`);
+		return data.result;
+	};
+}
+
+/**
+ * Create a bitcoind-compatible RPC caller from WatcherOpts-style config.
+ * Parses rpcUrl for embedded credentials, falls back to rpcHeaders Authorization.
+ */
+export function createRpcFromOpts(rpcUrl: string, rpcHeaders: Record<string, string>): RpcCall {
+	// Try parsing credentials from URL
+	const parsed = parseRpcUrl(rpcUrl);
+	if (parsed.rpcUser) {
+		return createBitcoindRpc(parsed.rpcUrl, parsed.rpcUser, parsed.rpcPassword);
+	}
+
+	// Fall back to rpcHeaders (may contain Authorization header)
+	let id = 0;
+	return async (method: string, params: unknown[]): Promise<unknown> => {
+		const res = await fetch(rpcUrl, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...rpcHeaders,
+			},
+			body: JSON.stringify({ jsonrpc: "1.0", id: ++id, method, params }),
+		});
+		if (!res.ok) throw new Error(`RPC ${method} failed: ${res.status}`);
+		const data = (await res.json()) as { result?: unknown; error?: { message: string } };
+		if (data.error) throw new Error(`RPC ${method}: ${data.error.message}`);
+		return data.result;
+	};
+}

package/src/shared/utxo/types.ts

@@ -0,0 +1,43 @@
+/** Configuration for a bitcoind-compatible JSON-RPC node (BTC, LTC, DOGE). */
+export interface UtxoNodeConfig {
+	readonly rpcUrl: string;
+	readonly rpcUser: string;
+	readonly rpcPassword: string;
+	readonly network: "mainnet" | "testnet" | "regtest";
+	readonly confirmations: number;
+}
+
+/** A single "received by address" entry from listreceivedbyaddress. */
+export interface ReceivedByAddress {
+	address: string;
+	amount: number;
+	confirmations: number;
+	txids: string[];
+}
+
+/** Transaction detail from gettransaction. */
+export interface TxDetail {
+	address: string;
+	amount: number;
+	category: string;
+}
+
+/** Response from gettransaction RPC call. */
+export interface GetTransactionResponse {
+	details: TxDetail[];
+	confirmations: number;
+}
+
+/** Descriptor info response from getdescriptorinfo. */
+export interface DescriptorInfo {
+	descriptor: string;
+}
+
+/** Result of importdescriptors RPC call. */
+export interface ImportDescriptorResult {
+	success: boolean;
+	error?: { message: string };
+}
+
+/** JSON-RPC call signature for bitcoind-compatible nodes. */
+export type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;

package/src/shared/utxo/watcher.ts

@@ -0,0 +1,195 @@
+import type {
+	IChainWatcher,
+	IPriceOracle,
+	IWatcherCursorStore,
+	PaymentEvent,
+	WatcherOpts,
+} from "@wopr-network/platform-core/crypto-plugin";
+
+import type {
+	DescriptorInfo,
+	GetTransactionResponse,
+	ImportDescriptorResult,
+	ReceivedByAddress,
+	RpcCall,
+} from "./types.js";
+
+/**
+ * Convert raw native units to USD cents using microdollar pricing.
+ *
+ * priceMicros = microdollars (10^-6 USD) per 1 whole coin.
+ * rawAmount is in the smallest unit (sats for BTC, litoshis for LTC, etc).
+ * decimals = number of decimal places (8 for BTC/LTC/DOGE).
+ *
+ * Formula: (rawAmount * priceMicros) / (10_000 * 10^decimals)
+ *   where 10_000 converts microdollars to cents (1 cent = 10,000 microdollars).
+ */
+function nativeToCents(rawAmount: bigint, priceMicros: number, decimals: number): number {
+	if (rawAmount < 0n) throw new Error("rawAmount must be non-negative");
+	if (!Number.isInteger(priceMicros) || priceMicros <= 0) {
+		throw new Error(`priceMicros must be a positive integer, got ${priceMicros}`);
+	}
+	const MICROS_PER_CENT = 10_000n;
+	return Number((rawAmount * BigInt(priceMicros)) / (MICROS_PER_CENT * 10n ** BigInt(decimals)));
+}
+
+export interface UtxoWatcherConfig {
+	/** JSON-RPC call function for the node. */
+	rpc: RpcCall;
+	/** Chain identifier for the price oracle (e.g. "BTC", "LTC", "DOGE"). */
+	token: string;
+	/** Chain name for PaymentEvent (e.g. "bitcoin", "litecoin", "dogecoin"). */
+	chain: string;
+	/** Number of decimal places for this chain's native unit (8 for BTC/LTC/DOGE). */
+	decimals: number;
+	/** Required confirmations before marking fully processed. */
+	confirmations: number;
+	/** Price oracle for USD conversion. */
+	oracle: IPriceOracle;
+	/** Cursor store for dedup and confirmation tracking. */
+	cursorStore: IWatcherCursorStore;
+}
+
+/**
+ * Generic UTXO chain watcher that works with any bitcoind-compatible node.
+ * Polls listreceivedbyaddress for payments and tracks confirmations.
+ *
+ * Reusable for BTC, LTC, and DOGE.
+ */
+export class UtxoWatcher implements IChainWatcher {
+	private readonly rpc: RpcCall;
+	private readonly addresses: Set<string> = new Set();
+	private readonly token: string;
+	private readonly chain: string;
+	private readonly decimals: number;
+	private readonly minConfirmations: number;
+	private readonly oracle: IPriceOracle;
+	private readonly cursorStore: IWatcherCursorStore;
+	private readonly watcherId: string;
+	private cursor = 0;
+	private stopped = false;
+
+	constructor(config: UtxoWatcherConfig) {
+		this.rpc = config.rpc;
+		this.token = config.token;
+		this.chain = config.chain;
+		this.decimals = config.decimals;
+		this.minConfirmations = config.confirmations;
+		this.oracle = config.oracle;
+		this.cursorStore = config.cursorStore;
+		this.watcherId = `${config.chain}:${config.token}`;
+	}
+
+	async init(): Promise<void> {
+		// Load persisted cursor (block height not used for UTXO, but kept for interface compat)
+		const saved = await this.cursorStore.get(this.watcherId);
+		if (saved !== null) this.cursor = saved;
+	}
+
+	setWatchedAddresses(addresses: string[]): void {
+		this.addresses.clear();
+		for (const a of addresses) this.addresses.add(a);
+	}
+
+	getCursor(): number {
+		return this.cursor;
+	}
+
+	stop(): void {
+		this.stopped = true;
+	}
+
+	/**
+	 * Import an address into the node's wallet (watch-only).
+	 * Uses importdescriptors (modern) with fallback to importaddress (legacy).
+	 */
+	async importAddress(address: string): Promise<void> {
+		try {
+			const info = (await this.rpc("getdescriptorinfo", [`addr(${address})`])) as DescriptorInfo;
+			const result = (await this.rpc("importdescriptors", [
+				[{ desc: info.descriptor, timestamp: 0 }],
+			])) as ImportDescriptorResult[];
+			if (result[0] && !result[0].success) {
+				throw new Error(result[0].error?.message ?? "importdescriptors failed");
+			}
+		} catch {
+			// Fallback: legacy importaddress
+			await this.rpc("importaddress", [address, "", false]);
+		}
+		this.addresses.add(address);
+	}
+
+	/**
+	 * Poll for payments to watched addresses.
+	 * Returns PaymentEvent[] for each new or updated confirmation.
+	 */
+	async poll(): Promise<PaymentEvent[]> {
+		if (this.stopped || this.addresses.size === 0) return [];
+
+		const events: PaymentEvent[] = [];
+
+		// Poll with minconf=0 to see unconfirmed txs
+		const received = (await this.rpc("listreceivedbyaddress", [
+			0, // minconf=0: see ALL txs including unconfirmed
+			false, // include_empty
+			true, // include_watchonly
+		])) as ReceivedByAddress[];
+
+		const { priceMicros } = await this.oracle.getPrice(this.token);
+
+		for (const entry of received) {
+			if (!this.addresses.has(entry.address)) continue;
+
+			for (const txid of entry.txids) {
+				// Skip fully-processed txids
+				const confirmCount = await this.cursorStore.getConfirmationCount(this.watcherId, txid);
+
+				// Get transaction details for the exact amount
+				const tx = (await this.rpc("gettransaction", [txid, true])) as GetTransactionResponse;
+
+				const detail = tx.details.find((d) => d.address === entry.address && d.category === "receive");
+				if (!detail) continue;
+
+				// Check if confirmations have increased since last seen
+				if (confirmCount !== null && tx.confirmations <= confirmCount) continue;
+
+				// Skip if already at or past threshold on a previous poll
+				if (confirmCount !== null && confirmCount >= this.minConfirmations) continue;
+
+				const rawAmount = BigInt(Math.round(detail.amount * 10 ** this.decimals));
+				const amountUsdCents = nativeToCents(rawAmount, priceMicros, this.decimals);
+
+				events.push({
+					chain: this.chain,
+					token: this.token,
+					from: "", // UTXO chains don't have a single sender
+					to: entry.address,
+					rawAmount: rawAmount.toString(),
+					amountUsdCents,
+					txHash: txid,
+					blockNumber: 0, // UTXO chains use txid-based tracking, not block numbers
+					confirmations: tx.confirmations,
+					confirmationsRequired: this.minConfirmations,
+				});
+
+				// Persist confirmation count
+				await this.cursorStore.saveConfirmationCount(this.watcherId, txid, tx.confirmations);
+			}
+		}
+
+		return events;
+	}
+}
+
+/** Create a UtxoWatcher from the standard WatcherOpts interface. */
+export function createUtxoWatcher(opts: WatcherOpts, rpc: RpcCall): IChainWatcher {
+	return new UtxoWatcher({
+		rpc,
+		token: opts.token,
+		chain: opts.chain,
+		decimals: opts.decimals,
+		confirmations: opts.confirmations,
+		oracle: opts.oracle,
+		cursorStore: opts.cursorStore,
+	});
+}

package/src/solana/encoder.ts

@@ -0,0 +1,72 @@
+import type { EncodingParams, IAddressEncoder } from "@wopr-network/platform-core/crypto-plugin";
+
+/** Base58 alphabet used by Bitcoin/Solana. */
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+/**
+ * Encode a Uint8Array as a Base58 string (Bitcoin/Solana alphabet).
+ *
+ * This is a standalone implementation — no external dependency needed.
+ */
+export function base58Encode(bytes: Uint8Array): string {
+	// Count leading zeros
+	let zeros = 0;
+	for (let i = 0; i < bytes.length && bytes[i] === 0; i++) {
+		zeros++;
+	}
+
+	// Convert to base58
+	// Allocate enough space in big-endian base58 representation
+	const size = Math.ceil((bytes.length * 138) / 100) + 1;
+	const b58 = new Uint8Array(size);
+
+	for (let i = zeros; i < bytes.length; i++) {
+		let carry = bytes[i];
+		for (let j = size - 1; j >= 0; j--) {
+			carry += 256 * b58[j];
+			b58[j] = carry % 58;
+			carry = Math.floor(carry / 58);
+		}
+	}
+
+	// Skip leading zeros in base58 result
+	let start = 0;
+	while (start < size && b58[start] === 0) {
+		start++;
+	}
+
+	// Build string: leading '1's for zero bytes + base58 digits
+	let result = "";
+	for (let i = 0; i < zeros; i++) {
+		result += ALPHABET[0];
+	}
+	for (let i = start; i < size; i++) {
+		result += ALPHABET[b58[i]];
+	}
+
+	return result;
+}
+
+/**
+ * Derive a Solana address from a raw 32-byte Ed25519 public key.
+ *
+ * Solana addresses are simply the Base58 encoding of the raw public key.
+ * No hashing, no version byte, no checksum.
+ */
+function encodeSolana(pubkey: Uint8Array): string {
+	if (pubkey.length !== 32) {
+		throw new Error(`Solana address requires 32-byte Ed25519 public key, got ${pubkey.length} bytes`);
+	}
+	return base58Encode(pubkey);
+}
+
+/** Solana address encoder implementing IAddressEncoder. */
+export class SolanaAddressEncoder implements IAddressEncoder {
+	encode(publicKey: Uint8Array, _params: EncodingParams): string {
+		return encodeSolana(publicKey);
+	}
+
+	encodingType(): string {
+		return "base58-solana";
+	}
+}

package/src/solana/index.ts

@@ -0,0 +1,36 @@
+import type { IChainPlugin, SweeperOpts, WatcherOpts } from "@wopr-network/platform-core/crypto-plugin";
+import { SolanaAddressEncoder } from "./encoder.js";
+import { SolanaSweeper } from "./sweeper.js";
+import { SolanaWatcher } from "./watcher.js";
+
+export { base58Encode, SolanaAddressEncoder } from "./encoder.js";
+export { SolanaSweeper } from "./sweeper.js";
+export type { SignatureInfo, SolanaRpcCall, SolanaTransaction, TokenBalance, TransactionMeta } from "./types.js";
+export { createSolanaRpcCaller, SolanaWatcher } from "./watcher.js";
+
+const encoder = new SolanaAddressEncoder();
+
+/**
+ * Solana chain plugin.
+ *
+ * Supports native SOL watching and SPL token watching (e.g. USDC).
+ * Uses Ed25519 curve for key derivation. Addresses are Base58-encoded
+ * raw 32-byte public keys (no hashing, no checksum).
+ *
+ * The watcher detects incoming transfers by scanning transaction history
+ * for each watched address via getSignaturesForAddress + getTransaction.
+ */
+export const solanaPlugin: IChainPlugin = {
+	pluginId: "solana",
+	supportedCurve: "ed25519",
+	encoders: {
+		"base58-solana": encoder,
+	},
+	createWatcher(opts: WatcherOpts) {
+		return new SolanaWatcher(opts);
+	},
+	createSweeper(opts: SweeperOpts) {
+		return new SolanaSweeper(opts);
+	},
+	version: 1,
+};

package/src/solana/sweeper.ts

@@ -0,0 +1,196 @@
+import type {
+	DepositInfo,
+	ISweepStrategy,
+	KeyPair,
+	SweeperOpts,
+	SweepResult,
+} from "@wopr-network/platform-core/crypto-plugin";
+import type { SolanaRpcCall } from "./types.js";
+import { createSolanaRpcCaller } from "./watcher.js";
+
+/** Transaction fee estimate (in lamports). */
+const TX_FEE = 5_000n;
+
+/**
+ * Solana sweep strategy.
+ *
+ * Scans deposit addresses for SOL balances and SPL token balances,
+ * then creates transfer transactions to sweep funds to the treasury.
+ */
+export class SolanaSweeper implements ISweepStrategy {
+	private readonly rpc: SolanaRpcCall;
+	private readonly token: string;
+	private readonly chain: string;
+	private readonly contractAddress?: string;
+	private readonly decimals: number;
+
+	constructor(opts: SweeperOpts) {
+		this.rpc = createSolanaRpcCaller(opts.rpcUrl, opts.rpcHeaders);
+		this.token = opts.token;
+		this.chain = opts.chain;
+		this.contractAddress = opts.contractAddress;
+		this.decimals = opts.decimals;
+	}
+
+	/**
+	 * Scan deposit addresses for balances.
+	 *
+	 * For each key:
+	 *   - Check native SOL balance via getBalance
+	 *   - Check SPL token balances via getTokenAccountsByOwner
+	 */
+	async scan(keys: KeyPair[], _treasury: string): Promise<DepositInfo[]> {
+		const results: DepositInfo[] = [];
+
+		for (const key of keys) {
+			const balance = (await this.rpc("getBalance", [key.address])) as { value: number };
+			const nativeBalance = BigInt(balance.value);
+
+			const tokenBalances: Array<{ token: string; balance: bigint; decimals: number }> = [];
+
+			if (this.contractAddress) {
+				const tokenAccounts = (await this.rpc("getTokenAccountsByOwner", [
+					key.address,
+					{ mint: this.contractAddress },
+					{ encoding: "jsonParsed" },
+				])) as {
+					value: Array<{
+						account: {
+							data: {
+								parsed: {
+									info: {
+										tokenAmount: { amount: string; decimals: number };
+										mint: string;
+									};
+								};
+							};
+						};
+					}>;
+				};
+
+				for (const ta of tokenAccounts.value) {
+					const info = ta.account.data.parsed.info;
+					const bal = BigInt(info.tokenAmount.amount);
+					if (bal > 0n) {
+						tokenBalances.push({
+							token: info.mint,
+							balance: bal,
+							decimals: info.tokenAmount.decimals,
+						});
+					}
+				}
+			}
+
+			if (nativeBalance > 0n || tokenBalances.length > 0) {
+				results.push({
+					index: key.index,
+					address: key.address,
+					nativeBalance,
+					tokenBalances,
+				});
+			}
+		}
+
+		return results;
+	}
+
+	/**
+	 * Sweep funds from deposit addresses to treasury.
+	 *
+	 * For native SOL: transfers balance minus fee.
+	 * For SPL tokens: transfers full token balance using token transfer instruction.
+	 *
+	 * In dry-run mode, returns what would be swept without broadcasting.
+	 */
+	async sweep(keys: KeyPair[], treasury: string, dryRun: boolean): Promise<SweepResult[]> {
+		const deposits = await this.scan(keys, treasury);
+		const results: SweepResult[] = [];
+
+		for (const deposit of deposits) {
+			const key = keys.find((k) => k.index === deposit.index);
+			if (!key) continue;
+
+			// Sweep SPL tokens first
+			for (const tb of deposit.tokenBalances) {
+				if (dryRun) {
+					results.push({
+						index: deposit.index,
+						address: deposit.address,
+						token: tb.token,
+						amount: tb.balance.toString(),
+						txHash: "dry-run",
+					});
+					continue;
+				}
+
+				// In production, this would build and sign an SPL token transfer transaction
+				// using @solana/web3.js. For now, placeholder for the transaction submission.
+				const txHash = await this.submitSplTransfer(key, treasury, tb.token, tb.balance);
+				results.push({
+					index: deposit.index,
+					address: deposit.address,
+					token: tb.token,
+					amount: tb.balance.toString(),
+					txHash,
+				});
+			}
+
+			// Sweep native SOL (leave enough for rent + fee if token accounts exist)
+			const sweepableNative = deposit.nativeBalance - TX_FEE;
+			if (sweepableNative > 0n) {
+				if (dryRun) {
+					results.push({
+						index: deposit.index,
+						address: deposit.address,
+						token: "SOL",
+						amount: sweepableNative.toString(),
+						txHash: "dry-run",
+					});
+					continue;
+				}
+
+				const txHash = await this.submitSolTransfer(key, treasury, sweepableNative);
+				results.push({
+					index: deposit.index,
+					address: deposit.address,
+					token: "SOL",
+					amount: sweepableNative.toString(),
+					txHash,
+				});
+			}
+		}
+
+		return results;
+	}
+
+	/**
+	 * Submit a native SOL transfer.
+	 *
+	 * Builds a SystemProgram.transfer instruction, signs with the deposit keypair,
+	 * and submits via sendTransaction.
+	 */
+	private async submitSolTransfer(key: KeyPair, treasury: string, lamports: bigint): Promise<string> {
+		// Get recent blockhash
+		const blockhashResult = (await this.rpc("getLatestBlockhash", [{ commitment: "finalized" }])) as {
+			value: { blockhash: string; lastValidBlockHeight: number };
+		};
+
+		// In production, build + sign the transaction using @solana/web3.js or manual serialization.
+		// For Phase 1, we use a simplified approach:
+		throw new Error(
+			`SOL transfer not yet implemented — would send ${lamports} lamports from ${key.address} to ${treasury} with blockhash ${blockhashResult.value.blockhash}`,
+		);
+	}
+
+	/**
+	 * Submit an SPL token transfer.
+	 *
+	 * Builds a TokenProgram.transfer instruction for the given mint,
+	 * signs with the deposit keypair, and submits via sendTransaction.
+	 */
+	private async submitSplTransfer(key: KeyPair, treasury: string, mint: string, amount: bigint): Promise<string> {
+		throw new Error(
+			`SPL transfer not yet implemented — would send ${amount} of ${mint} from ${key.address} to ${treasury}`,
+		);
+	}
+}

package/src/solana/types.ts

@@ -0,0 +1,52 @@
+/** JSON-RPC call function signature. */
+export type SolanaRpcCall = (method: string, params: unknown[]) => Promise<unknown>;
+
+/** Solana signature info from getSignaturesForAddress. */
+export interface SignatureInfo {
+	signature: string;
+	slot: number;
+	err: unknown | null;
+	memo: string | null;
+	blockTime: number | null;
+	confirmationStatus: "processed" | "confirmed" | "finalized" | null;
+}
+
+/** Solana transaction metadata. */
+export interface TransactionMeta {
+	err: unknown | null;
+	fee: number;
+	preBalances: number[];
+	postBalances: number[];
+	preTokenBalances?: TokenBalance[];
+	postTokenBalances?: TokenBalance[];
+}
+
+/** SPL token balance entry in transaction metadata. */
+export interface TokenBalance {
+	accountIndex: number;
+	mint: string;
+	uiTokenAmount: {
+		amount: string;
+		decimals: number;
+		uiAmountString: string;
+	};
+	owner?: string;
+}
+
+/** Parsed Solana transaction from getTransaction. */
+export interface SolanaTransaction {
+	slot: number;
+	blockTime: number | null;
+	meta: TransactionMeta | null;
+	transaction: {
+		message: {
+			accountKeys: string[];
+			instructions: Array<{
+				programIdIndex: number;
+				accounts: number[];
+				data: string;
+			}>;
+		};
+		signatures: string[];
+	};
+}