dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/paper.js

@@ -0,0 +1,331 @@
+// Paper trading (task-1310 T0, SPEC §6.0/§6.1/§6.10). A SIMULATED wallet priced from live keyless
+// Jupiter quotes. Nothing here signs, holds a key, or sends a transaction — there is a hard boundary
+// (the TradeExecutor interface) behind which a real signing executor can later be plugged, and this
+// file imports NO wallet/signing/crypto library of any kind (invariant SPEC §6.0, acceptance (d)).
+//
+// What this module owns:
+//   - pure ticket/fill/PnL math (computeFill, buildQuoteRequest, position maths) — unit-tested;
+//   - TradeExecutor: the one method the UI ever calls (execute an armed order against a fresh quote);
+//   - PaperExecutor: the T0 implementation that books the fill into a local SQLite wallet;
+//   - PaperWallet: the node:sqlite store (same DB file as the cache/watchlist; one --db controls all).
+//
+// Fills are computed from the quote amounts at confirm time (SPEC §6.1 step 6: book from the fill,
+// never from a stale on-screen quote). A small fixed SOL fee is modelled and clearly labelled as a
+// SIMULATION; no real network/priority fee is ever paid.
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { systemClock } from "./clock.js";
+/** Wrapped SOL: the quote's SOL leg for both sides (buy = SOL→token, sell = token→SOL). */
+export const SOL_MINT = 'So11111111111111111111111111111111111111112';
+export const LAMPORTS_PER_SOL = 1000000000n;
+/** Default starting balance for a fresh paper wallet (SPEC: configurable, default 10 SOL). */
+export const DEFAULT_START_LAMPORTS = 10n * LAMPORTS_PER_SOL;
+/** Simulated fixed SOL fee per fill (one base signature fee). Clearly a simulation; never paid. */
+export const DEFAULT_SIM_FEE_LAMPORTS = 5000n;
+// --------------------------------------------------------------------------- pure conversions
+export function lamportsToSol(l) {
+    return Number(l) / 1e9;
+}
+export function solToLamports(sol) {
+    if (!Number.isFinite(sol) || sol < 0)
+        return 0n;
+    return BigInt(Math.round(sol * 1e9));
+}
+export function rawToTokens(raw, decimals) {
+    return Number(raw) / 10 ** decimals;
+}
+export function tokensToRaw(tokens, decimals) {
+    if (!Number.isFinite(tokens) || tokens < 0)
+        return 0n;
+    // Round in float then to bigint; paper amounts never need sub-unit exactness.
+    return BigInt(Math.round(tokens * 10 ** decimals));
+}
+/** The keyless quote request for an order: SOL↔token with the right side and ExactIn amount. */
+export function buildQuoteRequest(order) {
+    return order.side === 'buy'
+        ? { inputMint: SOL_MINT, outputMint: order.mint, amount: order.amountRaw, slippageBps: order.slippageBps, mode: 'ExactIn' }
+        : { inputMint: order.mint, outputMint: SOL_MINT, amount: order.amountRaw, slippageBps: order.slippageBps, mode: 'ExactIn' };
+}
+/** True when a quote actually matches the order (same side/mint/amount) — a guard before booking. */
+export function quoteMatchesOrder(order, q) {
+    const req = buildQuoteRequest(order);
+    return q.inputMint === req.inputMint && q.outputMint === req.outputMint && q.inAmount === req.amount;
+}
+/**
+ * Compute the fill a quote would produce for an order, with the simulated fee applied. Pure: no
+ * wallet, no persistence, no validation — the executor validates balance before applying this.
+ */
+export function computeFill(order, q, now, feeLamports = DEFAULT_SIM_FEE_LAMPORTS) {
+    const buy = order.side === 'buy';
+    const gross = buy ? q.inAmount : q.outAmount; // SOL leg (lamports)
+    const tokenAbs = buy ? q.outAmount : q.inAmount; // token leg (raw base units)
+    const solDelta = buy ? -(gross + feeLamports) : gross - feeLamports;
+    const tokenDelta = buy ? tokenAbs : -tokenAbs;
+    const tokensWhole = rawToTokens(tokenAbs, order.decimals);
+    const priceSol = tokensWhole > 0 ? lamportsToSol(gross) / tokensWhole : 0;
+    const priceUsd = q.usdValue !== null && tokensWhole > 0 ? q.usdValue / tokensWhole : null;
+    return {
+        t: now,
+        mint: order.mint,
+        symbol: order.symbol,
+        side: order.side,
+        decimals: order.decimals,
+        solDelta,
+        tokenDelta,
+        grossLamports: gross,
+        feeLamports,
+        priceSol,
+        priceUsd,
+        priceImpactPct: q.priceImpactPct,
+        slippageBps: q.slippageBps,
+        route: q.route,
+        realizedLamports: 0n, // set by the executor for sells, once the cost basis is known
+        paper: true,
+    };
+}
+export function emptyPosition(mint, symbol, decimals, now) {
+    return { mint, symbol, decimals, tokensRaw: 0n, costLamports: 0n, realizedLamports: 0n, updatedAt: now };
+}
+/** Apply a buy fill to a position: add tokens, add the SOL spent (incl. fee) to the cost basis. */
+export function applyBuy(pos, fill) {
+    return {
+        ...pos,
+        tokensRaw: pos.tokensRaw + fill.tokenDelta,
+        costLamports: pos.costLamports + (-fill.solDelta), // solDelta is negative on a buy
+        updatedAt: fill.t,
+    };
+}
+/**
+ * Apply a sell fill to a position: remove tokens, remove the proportional cost basis, and book the
+ * realized PnL (net proceeds − cost removed). Returns the new position and the realized lamports.
+ */
+export function applySell(pos, fill) {
+    const sold = -fill.tokenDelta; // positive raw amount sold
+    const have = pos.tokensRaw;
+    const soldClamped = sold > have ? have : sold;
+    const costRemoved = have > 0n ? (pos.costLamports * soldClamped) / have : 0n;
+    const proceeds = fill.solDelta; // positive net lamports in
+    const realized = proceeds - costRemoved;
+    const tokensRaw = have - soldClamped;
+    const costLamports = tokensRaw === 0n ? 0n : pos.costLamports - costRemoved;
+    return {
+        pos: { ...pos, tokensRaw, costLamports, realizedLamports: pos.realizedLamports + realized, updatedAt: fill.t },
+        realizedLamports: realized,
+    };
+}
+/**
+ * PnL for a position given a current price in SOL per whole token (null when no live price).
+ * Pure: the positions screen feeds the live mark and renders the result.
+ */
+export function positionPnl(pos, priceSolPerToken) {
+    const tokensWhole = rawToTokens(pos.tokensRaw, pos.decimals);
+    const costSol = lamportsToSol(pos.costLamports);
+    const realizedSol = lamportsToSol(pos.realizedLamports);
+    const avgEntrySol = tokensWhole > 0 ? costSol / tokensWhole : null;
+    if (priceSolPerToken === null || !Number.isFinite(priceSolPerToken)) {
+        return { valueSol: 0, costSol, unrealizedSol: null, unrealizedPct: null, realizedSol, avgEntrySol };
+    }
+    const valueSol = tokensWhole * priceSolPerToken;
+    const unrealizedSol = valueSol - costSol;
+    const unrealizedPct = costSol > 0 ? unrealizedSol / costSol : null;
+    return { valueSol, costSol, unrealizedSol, unrealizedPct, realizedSol, avgEntrySol };
+}
+// --------------------------------------------------------------------------- executor boundary
+/** Raised when an order cannot be filled against the simulated wallet. */
+export class InsufficientFundsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InsufficientFundsError';
+    }
+}
+/** The T0 paper executor: validates against the simulated wallet, books the fill, records history. */
+export class PaperExecutor {
+    kind = 'paper';
+    wallet;
+    clock;
+    feeLamports;
+    constructor(wallet, opts = {}) {
+        this.wallet = wallet;
+        this.clock = opts.clock ?? systemClock;
+        this.feeLamports = opts.feeLamports ?? DEFAULT_SIM_FEE_LAMPORTS;
+    }
+    previewFill(order, quote) {
+        return computeFill(order, quote, this.clock.now(), this.feeLamports);
+    }
+    execute(order, quote) {
+        if (!quoteMatchesOrder(order, quote)) {
+            return Promise.reject(new Error('quote does not match the order (mint/side/amount changed) — re-quote and confirm again'));
+        }
+        const fill = computeFill(order, quote, this.clock.now(), this.feeLamports);
+        try {
+            const rec = this.wallet.book(order, fill);
+            return Promise.resolve(rec);
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+    }
+}
+/**
+ * The simulated wallet, persisted in node:sqlite (same file as the cache and watchlist, so one
+ * `--db` controls everything). A single-row balance, one row per position, and an append-only
+ * trade log. Booking a fill (balance + position + history) runs in one SQL transaction.
+ */
+export class PaperWallet {
+    db;
+    clock;
+    constructor(opts = {}) {
+        const path = opts.path ?? ':memory:';
+        if (path !== ':memory:')
+            mkdirSync(dirname(path), { recursive: true });
+        this.db = new DatabaseSync(path);
+        this.clock = opts.clock ?? systemClock;
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      CREATE TABLE IF NOT EXISTS paper_wallet (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        balance_lamports TEXT NOT NULL,
+        start_lamports TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS paper_positions (
+        mint TEXT PRIMARY KEY, symbol TEXT NOT NULL, decimals INTEGER NOT NULL,
+        tokens_raw TEXT NOT NULL, cost_lamports TEXT NOT NULL, realized_lamports TEXT NOT NULL DEFAULT '0',
+        updated_at INTEGER NOT NULL
+      ) WITHOUT ROWID;
+      CREATE TABLE IF NOT EXISTS paper_trades (
+        id INTEGER PRIMARY KEY AUTOINCREMENT, t INTEGER NOT NULL, mint TEXT NOT NULL, symbol TEXT NOT NULL,
+        side TEXT NOT NULL, decimals INTEGER NOT NULL, sol_delta TEXT NOT NULL, token_delta TEXT NOT NULL,
+        gross_lamports TEXT NOT NULL, fee_lamports TEXT NOT NULL, price_sol REAL NOT NULL, price_usd REAL,
+        price_impact_pct REAL, slippage_bps INTEGER NOT NULL, route TEXT NOT NULL DEFAULT '', realized_lamports TEXT NOT NULL DEFAULT '0'
+      );
+      CREATE INDEX IF NOT EXISTS paper_trades_mint ON paper_trades(mint, id);
+    `);
+        const start = opts.startLamports ?? DEFAULT_START_LAMPORTS;
+        this.db
+            .prepare('INSERT OR IGNORE INTO paper_wallet (id, balance_lamports, start_lamports, created_at) VALUES (1, ?, ?, ?)')
+            .run(start.toString(), start.toString(), this.clock.now());
+    }
+    summary() {
+        const row = this.db.prepare('SELECT balance_lamports, start_lamports, created_at FROM paper_wallet WHERE id = 1').get();
+        return { balanceLamports: BigInt(String(row.balance_lamports)), startLamports: BigInt(String(row.start_lamports)), createdAt: Number(row.created_at) };
+    }
+    balance() {
+        return this.summary().balanceLamports;
+    }
+    /** Reset the wallet to a fresh starting balance and clear positions + history (opt-in). */
+    reset(startLamports = DEFAULT_START_LAMPORTS) {
+        this.db.exec('BEGIN');
+        try {
+            this.db.prepare('DELETE FROM paper_positions').run();
+            this.db.prepare('DELETE FROM paper_trades').run();
+            this.db.prepare('UPDATE paper_wallet SET balance_lamports = ?, start_lamports = ?, created_at = ? WHERE id = 1')
+                .run(startLamports.toString(), startLamports.toString(), this.clock.now());
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    position(mint) {
+        const row = this.db.prepare('SELECT mint, symbol, decimals, tokens_raw, cost_lamports, realized_lamports, updated_at FROM paper_positions WHERE mint = ?').get(mint);
+        return row ? rowToPosition(row) : undefined;
+    }
+    /** Open positions (non-zero balance) plus any mint with realized PnL, newest activity first. */
+    positions() {
+        const rows = this.db.prepare('SELECT mint, symbol, decimals, tokens_raw, cost_lamports, realized_lamports, updated_at FROM paper_positions ORDER BY updated_at DESC').all();
+        return rows.map(rowToPosition);
+    }
+    trades(limit = 100) {
+        const rows = this.db.prepare('SELECT * FROM paper_trades ORDER BY id DESC LIMIT ?').all(limit);
+        return rows.map(rowToTrade);
+    }
+    /**
+     * Book a fill: validate funds, update the balance and position, append the trade — one SQL
+     * transaction. Throws InsufficientFundsError when the simulated wallet cannot cover the order.
+     */
+    book(order, fill) {
+        const balance = this.balance();
+        if (order.side === 'buy') {
+            const need = fill.grossLamports + fill.feeLamports;
+            if (balance < need)
+                throw new InsufficientFundsError(`insufficient paper balance: need ${lamportsToSol(need).toFixed(4)} SOL, have ${lamportsToSol(balance).toFixed(4)} SOL`);
+        }
+        else {
+            const have = this.position(order.mint)?.tokensRaw ?? 0n;
+            const sold = -fill.tokenDelta;
+            if (have < sold)
+                throw new InsufficientFundsError(`insufficient ${order.symbol} to sell: have ${rawToTokens(have, order.decimals)}, selling ${rawToTokens(sold, order.decimals)}`);
+        }
+        const existing = this.position(order.mint) ?? emptyPosition(order.mint, order.symbol, order.decimals, fill.t);
+        let realized = 0n;
+        let next;
+        if (order.side === 'buy') {
+            next = applyBuy(existing, fill);
+        }
+        else {
+            const r = applySell(existing, fill);
+            next = r.pos;
+            realized = r.realizedLamports;
+        }
+        const booked = { ...fill, realizedLamports: realized };
+        this.db.exec('BEGIN');
+        try {
+            this.db.prepare('UPDATE paper_wallet SET balance_lamports = ? WHERE id = 1').run((balance + booked.solDelta).toString());
+            this.db
+                .prepare(`INSERT INTO paper_positions (mint, symbol, decimals, tokens_raw, cost_lamports, realized_lamports, updated_at)
+                  VALUES (?, ?, ?, ?, ?, ?, ?)
+                  ON CONFLICT(mint) DO UPDATE SET symbol = excluded.symbol, decimals = excluded.decimals,
+                    tokens_raw = excluded.tokens_raw, cost_lamports = excluded.cost_lamports,
+                    realized_lamports = excluded.realized_lamports, updated_at = excluded.updated_at`)
+                .run(next.mint, next.symbol, next.decimals, next.tokensRaw.toString(), next.costLamports.toString(), next.realizedLamports.toString(), next.updatedAt);
+            const res = this.db
+                .prepare(`INSERT INTO paper_trades (t, mint, symbol, side, decimals, sol_delta, token_delta, gross_lamports, fee_lamports, price_sol, price_usd, price_impact_pct, slippage_bps, route, realized_lamports)
+                  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(booked.t, booked.mint, booked.symbol, booked.side, booked.decimals, booked.solDelta.toString(), booked.tokenDelta.toString(), booked.grossLamports.toString(), booked.feeLamports.toString(), booked.priceSol, booked.priceUsd, booked.priceImpactPct, booked.slippageBps, booked.route.join(' → '), booked.realizedLamports.toString());
+            this.db.exec('COMMIT');
+            return { ...booked, id: Number(res.lastInsertRowid) };
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    close() {
+        this.db.close();
+    }
+}
+function rowToPosition(r) {
+    return {
+        mint: String(r.mint),
+        symbol: String(r.symbol),
+        decimals: Number(r.decimals),
+        tokensRaw: BigInt(String(r.tokens_raw)),
+        costLamports: BigInt(String(r.cost_lamports)),
+        realizedLamports: BigInt(String(r.realized_lamports ?? '0')),
+        updatedAt: Number(r.updated_at),
+    };
+}
+function rowToTrade(r) {
+    return {
+        id: Number(r.id),
+        t: Number(r.t),
+        mint: String(r.mint),
+        symbol: String(r.symbol),
+        side: r.side === 'sell' ? 'sell' : 'buy',
+        decimals: Number(r.decimals),
+        solDelta: BigInt(String(r.sol_delta)),
+        tokenDelta: BigInt(String(r.token_delta)),
+        grossLamports: BigInt(String(r.gross_lamports)),
+        feeLamports: BigInt(String(r.fee_lamports)),
+        priceSol: Number(r.price_sol),
+        priceUsd: r.price_usd === null || r.price_usd === undefined ? null : Number(r.price_usd),
+        priceImpactPct: r.price_impact_pct === null || r.price_impact_pct === undefined ? null : Number(r.price_impact_pct),
+        slippageBps: Number(r.slippage_bps),
+        route: String(r.route ?? '').length ? String(r.route).split(' → ') : [],
+        realizedLamports: BigInt(String(r.realized_lamports ?? '0')),
+        paper: true,
+    };
+}

package/dist/packages/data/src/rpc-config.js

@@ -0,0 +1,126 @@
+// RPC endpoint resolution (task-1298). The Helius key lives ONLY at ~/.dexterm/helius.key
+// (mode 600, outside every repo). It is read here, in code, and the URL is built in memory.
+// Nothing in this module logs, returns for display, or writes the key; `redactSecrets()`
+// strips `api-key=<value>` from any string that might reach a log, an error, a recording
+// or the screen, and every URL-bearing message in the data layer goes through it.
+//
+//   DEXTERM_RPC_URL   wins when set (any read-only JSON-RPC endpoint)
+//   ~/.dexterm/helius.key   -> https://mainnet.helius-rpc.com/?api-key=<key>
+//   otherwise         the public mainnet RPC (heavily throttled: holders usually unavailable)
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { SOLANA_PUBLIC_RPC } from "./sources/solana-rpc.js";
+export const HELIUS_RPC_HOST = 'mainnet.helius-rpc.com';
+export const HELIUS_KEY_FILE = join('.dexterm', 'helius.key');
+/**
+ * Keyless public Solana RPCs added to the pool alongside the default endpoint (task-1309). These answer
+ * `getAccountInfo` (mint/freeze authorities) without a key, so the authorities panel keeps working even
+ * when the official endpoint is throttling. None of them reliably serve `getTokenLargestAccounts`
+ * (the ranked holder list) keyless — that needs a free key — so the holders panel falls back to the
+ * Jupiter aggregate (count + top-10 share). Probed live 2026-10-07; see the task-1309 handoff.
+ */
+export const PUBLIC_RPC_POOL = [
+    { url: SOLANA_PUBLIC_RPC, label: 'api.mainnet-beta.solana.com (public)', basis: 'official public RPC; getTokenLargestAccounts throttled per-IP' },
+    { url: 'https://solana-rpc.publicnode.com', label: 'solana-rpc.publicnode.com (public)', basis: 'PublicNode keyless; serves getAccountInfo, blocks getTokenLargestAccounts' },
+];
+/**
+ * What a free (user-supplied, no-card) key adds for each keyed capability, and how to get it in ~2 minutes.
+ * Shown next to any "needs key" cell so the gap is honest and actionable (task-1309). No key is ever shipped.
+ */
+export const FREE_KEY_GUIDANCE = {
+    'top-holders': {
+        adds: 'the ranked top-20 holder list with owner wallets (keyless you still get holder count + top-10 % via Jupiter)',
+        how: 'free Helius key → ~/.dexterm/helius.key, or any free RPC URL in DEXTERM_RPC_URL (Alchemy/QuickNode/Ankr free tier)',
+    },
+    forensics: {
+        adds: 'snipers, bundled-buy %, and creator dev-history (prior launches / rugs)',
+        how: 'free Helius key (1M credits/mo, no card) → ~/.dexterm/helius.key',
+    },
+    'dev-history': {
+        adds: "the creator's prior launches and rug record",
+        how: 'free Helius key → ~/.dexterm/helius.key (Jupiter also gives a partial dev flag keyless)',
+    },
+    'live-tape': {
+        adds: 'richer, wallet-labelled trade flow (keyless you get the GeckoTerminal tape)',
+        how: 'free Helius key → ~/.dexterm/helius.key',
+    },
+};
+/** The public mainnet RPC WebSocket (keyless), for the fast lane's accountSubscribe fallback. */
+export const SOLANA_PUBLIC_RPC_WS = 'wss://api.mainnet-beta.solana.com';
+/**
+ * WebSocket URL for an RPC HTTP endpoint (http→ws, https→wss), preserving any `?api-key=` query so the
+ * same key authenticates the stream. Never log the result (it may carry a key); pass through redactSecrets.
+ * Returns null when the URL is unparseable.
+ */
+export function wsUrlFor(httpUrl) {
+    try {
+        const u = new URL(httpUrl);
+        u.protocol = u.protocol === 'https:' ? 'wss:' : u.protocol === 'http:' ? 'ws:' : u.protocol;
+        return u.toString();
+    }
+    catch {
+        return null;
+    }
+}
+/** Extra user-supplied free RPC endpoints, from DEXTERM_RPC_URLS (comma-separated, read-only). */
+export function extraRpcUrls(env = process.env) {
+    return (env.DEXTERM_RPC_URLS ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && isLikelyUrl(s));
+}
+function isLikelyUrl(s) {
+    try {
+        const u = new URL(s);
+        return u.protocol === 'https:' || u.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the RPC endpoint. Never throws: a missing or unreadable key file means the public RPC. */
+export function resolveRpcUrl(opts = {}) {
+    const env = opts.env ?? process.env;
+    const fromEnv = env.DEXTERM_RPC_URL?.trim();
+    if (fromEnv) {
+        let provider = 'custom';
+        try {
+            if (new URL(fromEnv).hostname === HELIUS_RPC_HOST)
+                provider = 'helius';
+        }
+        catch { /* keep custom */ }
+        return { url: fromEnv, provider, basis: 'env DEXTERM_RPC_URL', fallbackUrl: SOLANA_PUBLIC_RPC };
+    }
+    const path = join(opts.home ?? homedir(), HELIUS_KEY_FILE);
+    let key = '';
+    try {
+        key = (opts.readFile ?? ((p) => readFileSync(p, 'utf8')))(path).trim();
+    }
+    catch {
+        key = '';
+    }
+    if (key && isPlausibleKey(key)) {
+        return { url: `https://${HELIUS_RPC_HOST}/?api-key=${encodeURIComponent(key)}`, provider: 'helius', basis: '~/.dexterm/helius.key', fallbackUrl: SOLANA_PUBLIC_RPC };
+    }
+    return { url: SOLANA_PUBLIC_RPC, provider: 'public', basis: 'public mainnet (no key)', fallbackUrl: null };
+}
+/** A key is one token of URL-safe characters; anything else (a pasted sentence, a blank file) is ignored. */
+export function isPlausibleKey(key) {
+    return /^[A-Za-z0-9._~-]{8,128}$/.test(key);
+}
+const API_KEY_RE = /([?&](?:api[-_]?key|apikey|key|token)=)[^&\s"'<>]*/gi;
+/** Replace the value of any `api-key=` style query parameter with `REDACTED`. Safe on any string. */
+export function redactSecrets(text) {
+    return text.replace(API_KEY_RE, '$1REDACTED');
+}
+/** True when `text` still carries an api-key value other than the REDACTED marker (self-check before writing files). */
+export function containsSecret(text) {
+    API_KEY_RE.lastIndex = 0;
+    for (const m of text.matchAll(API_KEY_RE)) {
+        const value = m[0].slice(m[1].length);
+        if (value && value !== 'REDACTED')
+            return true;
+    }
+    return false;
+}

package/dist/packages/data/src/rpc-pool.js

@@ -0,0 +1,166 @@
+// RPC pool with rotation, per-endpoint health scoring and 429/Retry-After backoff (task-1309).
+//
+// Why a pool: a single public RPC is throttled hard (getTokenLargestAccounts 429s per IP), and a
+// user may supply several free endpoints (Helius / Alchemy / QuickNode / Ankr free tiers, each with
+// its own quota tied to their own key and IP). The pool spreads reads across every endpoint it has,
+// prefers the healthiest, and when one 429s it is paused (honouring Retry-After) while the others keep
+// serving. Each endpoint has its own rate-limit bucket so one endpoint's pause never stalls the rest.
+//
+// FREE-FOREVER: the pool works with zero endpoints configured beyond the keyless public RPC. Adding a
+// free key only adds endpoints (more quota, and the methods the public RPC blocks, e.g. the ranked
+// holder list); it never gates a feature. Endpoint URLs may carry a key: never log one — redactSecrets().
+import { systemClock } from "./clock.js";
+import { HttpError } from "./http.js";
+import { SolanaRpc } from "./sources/solana-rpc.js";
+import { redactSecrets } from "./rpc-config.js";
+/** Default bucket config for a pool endpoint when the spec does not give one. */
+const DEFAULT_RPM = 30;
+const DEFAULT_BURST = 1;
+/** Pool-level pause after a 429 with no Retry-After; doubles per consecutive 429, capped. */
+const BASE_429_PAUSE_MS = 2_000;
+const MAX_429_PAUSE_MS = 120_000;
+/** Pool-level cooldown after a non-429 failure (network/5xx), so rotation moves on without hammering. */
+const ERROR_COOLDOWN_MS = 3_000;
+const MAX_ERROR_COOLDOWN_MS = 30_000;
+/** Thrown when every endpoint in the pool is paused or exhausted and none could serve the call. */
+export class RpcPoolExhaustedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RpcPoolExhaustedError';
+    }
+}
+export class RpcPool {
+    endpoints;
+    clock;
+    constructor(http, limiter, specs, opts = {}) {
+        this.clock = opts.clock ?? systemClock;
+        if (specs.length === 0)
+            throw new Error('RpcPool needs at least one endpoint');
+        this.endpoints = specs.map((spec, i) => {
+            const bucket = spec.bucket ?? bucketFor(spec.url);
+            limiter.ensureBucket(bucket, { rpm: spec.rpm ?? DEFAULT_RPM, burst: spec.burst ?? DEFAULT_BURST, basis: spec.basis });
+            return {
+                spec,
+                rpc: new SolanaRpc(http, { url: spec.url, source: spec.source, bucket }),
+                priority: i,
+                consecutiveFailures: 0,
+                okCount: 0,
+                errorCount: 0,
+                lastLatencyMs: null,
+                pausedUntil: 0,
+                lastError: null,
+            };
+        });
+    }
+    get size() {
+        return this.endpoints.length;
+    }
+    /** True when at least one endpoint carries a user key (unlocks the ranked holder list etc.). */
+    get hasKeyed() {
+        return this.endpoints.some((e) => e.spec.keyed);
+    }
+    /** The first endpoint's adapter — the "primary" for callers that still expect a single SolanaRpc. */
+    get primary() {
+        return this.endpoints[0].rpc;
+    }
+    /**
+     * Run `fn` against endpoints in health order, failing over on error. A 429 pauses that endpoint
+     * (Retry-After when the server sent one, else a doubling backoff) and moves to the next. The last
+     * error propagates when every currently-available endpoint has failed.
+     */
+    async run(fn, label = 'rpc') {
+        const now = this.clock.now();
+        const order = this.order(now);
+        const available = order.filter((e) => e.pausedUntil <= now);
+        const tryList = available.length > 0 ? available : order.slice(0, 1); // all paused: still try the soonest
+        let lastError = new RpcPoolExhaustedError(`${label}: no RPC endpoint available`);
+        for (const e of tryList) {
+            const t0 = this.clock.now();
+            try {
+                const value = await fn(e.rpc);
+                e.okCount++;
+                e.consecutiveFailures = 0;
+                e.pausedUntil = 0;
+                e.lastError = null;
+                e.lastLatencyMs = this.clock.now() - t0;
+                return value;
+            }
+            catch (err) {
+                lastError = err;
+                this.penalize(e, err);
+            }
+        }
+        throw lastError;
+    }
+    mintInfo(mint) {
+        return this.run((rpc) => rpc.mintInfo(mint), 'mintInfo');
+    }
+    topHolders(mint, opts = {}) {
+        return this.run((rpc) => rpc.topHolders(mint, opts), 'topHolders');
+    }
+    /** Raw base64 account data through the pool (rotation + failover). Fast-lane price seeding. */
+    accountsRaw(accounts, commitment = 'processed') {
+        return this.run((rpc) => rpc.accountsRaw(accounts, commitment), 'accountsRaw');
+    }
+    /** Account meta (owner program / existence) through the pool (task-1340 wallet intel). */
+    accountMeta(accounts, commitment = 'confirmed') {
+        return this.run((rpc) => rpc.accountMeta(accounts, commitment), 'accountMeta');
+    }
+    /** The first endpoint whose source is `helius` (the keyed history endpoint), or null. Its URL carries the key: never print it. */
+    get heliusUrl() {
+        return this.endpoints.find((e) => e.spec.source === 'helius')?.spec.url ?? null;
+    }
+    status() {
+        const now = this.clock.now();
+        return this.endpoints.map((e) => ({
+            label: e.spec.label,
+            source: e.spec.source,
+            keyed: !!e.spec.keyed,
+            okCount: e.okCount,
+            errorCount: e.errorCount,
+            consecutiveFailures: e.consecutiveFailures,
+            lastLatencyMs: e.lastLatencyMs,
+            pausedUntil: e.pausedUntil > now ? e.pausedUntil : 0,
+            available: e.pausedUntil <= now,
+            lastError: e.lastError,
+        }));
+    }
+    /** Available endpoints first, then fewest consecutive failures, then declared priority, then latency. */
+    order(now) {
+        return [...this.endpoints].sort((a, b) => {
+            const aAvail = a.pausedUntil <= now ? 0 : 1;
+            const bAvail = b.pausedUntil <= now ? 0 : 1;
+            if (aAvail !== bAvail)
+                return aAvail - bAvail;
+            if (a.consecutiveFailures !== b.consecutiveFailures)
+                return a.consecutiveFailures - b.consecutiveFailures;
+            if (a.priority !== b.priority)
+                return a.priority - b.priority;
+            return (a.lastLatencyMs ?? 0) - (b.lastLatencyMs ?? 0);
+        });
+    }
+    penalize(e, err) {
+        e.errorCount++;
+        e.consecutiveFailures++;
+        e.lastError = redactSecrets(err instanceof Error ? err.message : String(err));
+        const now = this.clock.now();
+        const rateLimited = err instanceof HttpError && (err.status === 429 || err.status === 503);
+        if (rateLimited) {
+            const backoff = Math.min(BASE_429_PAUSE_MS * 2 ** (e.consecutiveFailures - 1), MAX_429_PAUSE_MS);
+            const retry = err instanceof HttpError ? err.retryAfterMs : undefined;
+            e.pausedUntil = now + Math.max(backoff, retry ?? 0);
+        }
+        else {
+            e.pausedUntil = now + Math.min(ERROR_COOLDOWN_MS * e.consecutiveFailures, MAX_ERROR_COOLDOWN_MS);
+        }
+    }
+}
+/** Per-host bucket name for an endpoint, derived from the hostname (never the key). */
+export function bucketFor(url) {
+    try {
+        return `rpc:${new URL(url).hostname}`;
+    }
+    catch {
+        return 'rpc:unknown';
+    }
+}