dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/data/src/coin-target.js

@@ -0,0 +1,82 @@
+// @dexterm/data — "paste a CA or a coin link anywhere" (task-1401, building on the task-1388 GO-TO parser). Shared by
+// the CLI (go-to prompt, analyst chat, the screener `/` line, --mint) and the MCP server (a link passed as `mint`).
+//
+// parseMintTarget (task-1388) pulls a base58 mint out of a bare address or a dexscreener / pump.fun / solscan URL.
+// parseCoinTarget adds what the other inputs need: WHICH site the link came from (a dexscreener.com/solana/<addr>
+// link usually names the POOL, so it is resolved to its coin before the token screen opens) and the REST of the
+// text, so "is <CA> a rug?" in the analyst chat opens the coin and asks the question about it.
+// Pure and total: never throws, only ever returns a validated base58 string.
+/** A full base58 Solana mint: 32–44 chars, no 0/O/I/l. Same shape `--mint` validates. */
+export const MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+/**
+ * task-1388: turn a pasted/typed go-to target into a mint, or null when there is none. Accepts a bare base58
+ * mint, or a dexscreener / pump.fun / solscan URL (or any text) by pulling the first base58 run of mint length.
+ * Base58 excludes 0, O, I and l, so splitting on every non-base58 character also splits on them and on the URL
+ * punctuation (/, :, ., ?, =, &), leaving each path/query segment as its own token; a real mint is never cut.
+ */
+export function parseMintTarget(raw) {
+    const s = raw.trim();
+    if (!s)
+        return null;
+    if (MINT_RE.test(s))
+        return s;
+    for (const tok of s.split(/[^1-9A-HJ-NP-Za-km-z]+/))
+        if (MINT_RE.test(tok))
+            return tok;
+    return null;
+}
+const HOSTS = [
+    [/(^|\.)dexscreener\.com$/, 'dexscreener'],
+    [/(^|\.)pump\.fun$/, 'pumpfun'],
+    [/(^|\.)solscan\.io$/, 'solscan'],
+    [/(^|\.)birdeye\.so$/, 'birdeye'],
+];
+const URLISH = /^(?:https?:\/\/)?(?:www\.)?([a-z0-9-]+(?:\.[a-z0-9-]+)+)(\/\S*)$/i;
+/**
+ * Find the first coin address in free text: a link with an address in its path (its host decides `via`), else a
+ * bare base58 address word. `rest` is the remaining text. Null when the text names no address.
+ */
+export function parseCoinTarget(raw) {
+    const s = String(raw ?? '').trim().slice(0, 800);
+    if (!s)
+        return null;
+    const words = s.split(/\s+/);
+    const restWithout = (i) => words.filter((_, k) => k !== i).join(' ').trim();
+    for (let i = 0; i < words.length; i++) {
+        const m = URLISH.exec(words[i]);
+        if (!m)
+            continue;
+        const address = parseMintTarget(m[2]);
+        if (!address)
+            continue;
+        const host = m[1].toLowerCase();
+        return { address, via: HOSTS.find(([re]) => re.test(host))?.[1] ?? 'link', rest: restWithout(i) };
+    }
+    for (let i = 0; i < words.length; i++) {
+        // a bare address, allowing surrounding punctuation ("<CA>?", "(CA)", "CA,")
+        const core = words[i].replace(/^[^1-9A-HJ-NP-Za-km-z]+|[^1-9A-HJ-NP-Za-km-z]+$/g, '');
+        if (MINT_RE.test(core))
+            return { address: core, via: 'address', rest: restWithout(i) };
+    }
+    return null;
+}
+/** True when the text left after the address asks nothing ("", "open", "check this", "?"): just open the coin. */
+export function isBareOpen(rest) {
+    return /^(?:(?:open|go|to|show|me|check|look|at|this|that|one|the|ca|token|coin|pls|please|here|it)\b|[\s?.!:,;\-–—])*$/i.test(rest.trim());
+}
+/**
+ * Resolve a target to the coin's mint. A dexscreener link's address is looked up as a pair first (one keyless
+ * request through the limiter); when DexScreener has no such pair, or the lookup fails (offline, a replay without
+ * it), the address is used as the mint. Every other target is already a mint.
+ */
+export async function resolveCoinTarget(t, dl) {
+    if (t.via !== 'dexscreener' || !dl)
+        return { mint: t.address, fromPair: false };
+    try {
+        const coin = await dl.dexscreener.pairCoin(t.address);
+        if (coin && MINT_RE.test(coin))
+            return { mint: coin, fromPair: coin !== t.address };
+    }
+    catch { /* fall through: treat the address as the mint */ }
+    return { mint: t.address, fromPair: false };
+}

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

@@ -0,0 +1,137 @@
+// Helius credit meter (task-1298; inventory 2026-10-06 §0.1, §5). The Free plan has 1M credits a
+// month (docs/helius/pricing.md). We budget it per day (1M / 30), count every request we send and
+// expose three levels: `ok`, `warn` at 50 % of the day, `degraded` at 90 % (the data layer then
+// switches Helius off for the day and the keyless sources take over). A hard per-run cap bounds
+// what one dexterm process can spend however long it runs. Day totals persist in the SQLite cache
+// so restarts keep counting; the meter never sees, stores or prints the key.
+import { systemClock } from "./clock.js";
+export const HELIUS_MONTHLY_CREDITS = 1_000_000;
+export const HELIUS_DAILY_BUDGET = Math.floor(HELIUS_MONTHLY_CREDITS / 30); // 33,333
+/** Default hard cap per process run (credits). */
+export const DEFAULT_RUN_CAP = 5_000;
+export const WARN_PCT = 0.5;
+export const DEGRADE_PCT = 0.9;
+/**
+ * Credits per request by JSON-RPC method (docs/helius/pricing.md: standard RPC calls 1 credit,
+ * DAS / getProgramAccounts-class and Parsed Events 10). Unknown methods are charged 10 to be safe.
+ */
+export const RPC_CREDIT_COST = {
+    getAccountInfo: 1,
+    getMultipleAccounts: 1,
+    getTokenLargestAccounts: 1,
+    getTokenSupply: 1,
+    getSlot: 1,
+    getAsset: 10,
+    getTokenAccounts: 10,
+    getTransactionsForAddress: 10,
+};
+export const UNKNOWN_METHOD_COST = 10;
+/** WebSocket traffic: 2 credits per 0.1 MB (inventory §0.1), i.e. 20 credits per MB. */
+export const WS_CREDITS_PER_MB = 20;
+const NS = 'meter';
+const DAY_TTL_MS = 2 * 86_400_000;
+export class CreditMeter {
+    clock;
+    cache;
+    dayBudget;
+    runCap;
+    warnPct;
+    degradePct;
+    onLevel;
+    session = 0;
+    requests = 0;
+    bytes = 0;
+    lastLevel = 'ok';
+    dayKey = '';
+    dayTotal = 0;
+    constructor(opts = {}) {
+        this.clock = opts.clock ?? systemClock;
+        this.cache = opts.cache;
+        this.dayBudget = opts.dayBudget ?? HELIUS_DAILY_BUDGET;
+        this.runCap = opts.runCap ?? DEFAULT_RUN_CAP;
+        this.warnPct = opts.warnPct ?? WARN_PCT;
+        this.degradePct = opts.degradePct ?? DEGRADE_PCT;
+        this.onLevel = opts.onLevel;
+        this.roll();
+    }
+    /** YYYY-MM-DD in UTC for the clock's now (the plan's month is UTC-ish; a day boundary is good enough). */
+    static dayKeyFor(ms) {
+        return new Date(ms).toISOString().slice(0, 10);
+    }
+    roll() {
+        const key = CreditMeter.dayKeyFor(this.clock.now());
+        if (key === this.dayKey)
+            return;
+        this.dayKey = key;
+        const hit = this.cache?.get(NS, `helius:day:${key}`);
+        this.dayTotal = hit && typeof hit.value === 'number' ? hit.value : 0;
+    }
+    /** Credits a JSON-RPC method costs. */
+    static costOf(method) {
+        if (!method)
+            return UNKNOWN_METHOD_COST;
+        return RPC_CREDIT_COST[method] ?? UNKNOWN_METHOD_COST;
+    }
+    /** True while another request may be sent (below 90 % of the day and below the run cap). */
+    allow() {
+        this.roll();
+        return this.level() !== 'degraded';
+    }
+    /** Charge one request. Returns the new level. */
+    charge(credits) {
+        this.roll();
+        const c = Math.max(0, credits);
+        this.session += c;
+        this.requests += 1;
+        this.dayTotal += c;
+        this.cache?.set(NS, `helius:day:${this.dayKey}`, this.dayTotal, { ttlMs: DAY_TTL_MS, source: 'helius' });
+        return this.emit();
+    }
+    /** Charge streamed WebSocket bytes at the documented rate. */
+    chargeBytes(bytes) {
+        this.roll();
+        this.bytes += bytes;
+        return this.charge((bytes / 1_048_576) * WS_CREDITS_PER_MB);
+    }
+    level() {
+        if (this.session >= this.runCap)
+            return 'degraded';
+        const pct = this.dayBudget > 0 ? this.dayTotal / this.dayBudget : 0;
+        if (pct >= this.degradePct)
+            return 'degraded';
+        if (pct >= this.warnPct)
+            return 'warn';
+        return 'ok';
+    }
+    status() {
+        this.roll();
+        return {
+            level: this.level(),
+            session: Math.round(this.session * 100) / 100,
+            day: Math.round(this.dayTotal * 100) / 100,
+            dayBudget: this.dayBudget,
+            dayPct: this.dayBudget > 0 ? this.dayTotal / this.dayBudget : 0,
+            runCap: this.runCap,
+            runCapHit: this.session >= this.runCap,
+            requests: this.requests,
+            bytesStreamed: this.bytes,
+            dayKey: this.dayKey,
+        };
+    }
+    /** Header-sized summary: `helius 1.2K/33K credits · run 12`. */
+    label() {
+        const s = this.status();
+        const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(n >= 10_000 ? 0 : 1)}K` : String(Math.round(n)));
+        const pct = Math.round(s.dayPct * 100);
+        const tail = s.runCapHit ? ' · run cap' : s.level === 'degraded' ? ' · off' : s.level === 'warn' ? ' · warn' : '';
+        return `helius ${k(s.day)}/${k(s.dayBudget)} (${pct}%) · run ${k(s.session)}${tail}`;
+    }
+    emit() {
+        const level = this.level();
+        if (level !== this.lastLevel) {
+            this.lastLevel = level;
+            this.onLevel?.(level, this.status());
+        }
+        return level;
+    }
+}

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

@@ -0,0 +1,97 @@
+// Token-detail data (SPEC §4.3, D-06): candles, on-chain authorities, top-20
+// holders and the RugCheck summary, each cached with its SPEC §3.4 TTL and
+// stale-while-revalidate, so the detail screen and the MCP tools share one
+// set of requests.
+import { TTL } from "./cache.js";
+const NS = { mint: 'rpc:mint', holders: 'rpc:holders', rug: 'rugcheck', pools: 'gt:pools', goplus: 'goplus', trades: 'gt:trades' };
+/** Pools for a mint change rarely; one lookup per hour per mint. */
+const POOLS_TTL = 3_600_000;
+/** The trades tape shares GeckoTerminal's 10/min bucket with the candles: refresh at most every 20 s per pool. */
+export const TRADES_TTL = 20_000;
+export class TokenDetail {
+    cache;
+    gecko;
+    /** RPC pool: rotates across keyed + keyless endpoints with health scoring and 429 backoff (task-1309). */
+    pool;
+    /** Keyless holder aggregate (Jupiter) used when no RPC endpoint can serve the ranked list. */
+    holdersAggregate;
+    rug;
+    goplus;
+    candleStore;
+    constructor(deps) {
+        this.cache = deps.cache;
+        this.gecko = deps.gecko;
+        this.pool = deps.pool;
+        this.holdersAggregate = deps.holdersAggregate ?? null;
+        this.rug = deps.rugcheck;
+        this.goplus = deps.goplus ?? null;
+        this.candleStore = deps.candles;
+    }
+    /** Candles for a pool (pass DexScreener's `pair.pairAddress` to avoid a pool lookup). */
+    candles(pool, interval, req) {
+        return this.candleStore.get(pool, interval, req);
+    }
+    /** Most liquid GeckoTerminal pool for a mint (one request per hour per mint). */
+    async topPool(mint) {
+        const r = await this.cache.fetch(NS.pools, mint, () => this.gecko.tokenPools(mint), { ttlMs: POOLS_TTL, source: 'geckoterminal' });
+        return r.value[0] ?? null;
+    }
+    /** Mint/freeze authority truth from chain (TTL audit, 10 min). RPC pool: keyed endpoints first, keyless public RPC rotation behind them. */
+    mintInfo(mint) {
+        return this.cache.fetch(NS.mint, mint, () => this.pool.mintInfo(mint), { ttlMs: TTL.audit, source: this.pool.primary.source });
+    }
+    /**
+     * Top-20 holders (TTL holders, 60 s); reuses the cached mint info for supply/decimals. The RPC pool
+     * rotates across every endpoint; the result's `source` says which answered. When no endpoint can serve
+     * the ranked list (keyless: getTokenLargestAccounts is throttled/blocked everywhere), fall back to the
+     * Jupiter aggregate (`aggregateOnly`: holder count + top-10 share, empty list). Only when that also fails
+     * does the RPC error propagate, so the caller shows "unavailable".
+     */
+    async holders(mint) {
+        return this.cache.fetch(NS.holders, mint, async () => {
+            const info = (await this.mintInfo(mint)).value;
+            try {
+                return await this.pool.topHolders(mint, { info });
+            }
+            catch (rpcErr) {
+                const agg = await this.aggregateHolders(mint, info).catch(() => null);
+                if (agg)
+                    return agg;
+                throw rpcErr;
+            }
+        }, { ttlMs: TTL.holders, source: this.pool.primary.source });
+    }
+    /** Build an aggregate-only TopHolders from the keyless Jupiter holder data; null when unavailable. */
+    async aggregateHolders(mint, info) {
+        if (!this.holdersAggregate)
+            return null;
+        const a = await this.holdersAggregate(mint);
+        if (!a || (a.holderCount === null && a.top10Pct === null))
+            return null;
+        return {
+            mint,
+            holders: [],
+            top10Pct: a.top10Pct,
+            supply: info.supply,
+            decimals: info.decimals,
+            source: a.source,
+            fetchedAt: a.fetchedAt,
+            aggregateOnly: true,
+            holderCount: a.holderCount,
+        };
+    }
+    rugcheck(mint) {
+        return this.cache.fetch(NS.rug, mint, () => this.rug.summary(mint), { ttlMs: TTL.rugcheck, source: 'rugcheck' });
+    }
+    /** GoPlus second opinion (TTL rugcheck, 10 min). Throws when the adapter is not configured. */
+    security(mint) {
+        const gp = this.goplus;
+        if (!gp)
+            throw new Error('goplus adapter not configured');
+        return this.cache.fetch(NS.goplus, mint, () => gp.tokenSecurity(mint), { ttlMs: TTL.rugcheck, source: 'goplus' });
+    }
+    /** Recent trades of the token's pool from GeckoTerminal (best keyless tape), newest first, 20 s TTL. */
+    trades(pool, mint) {
+        return this.cache.fetch(NS.trades, `${pool}:${mint ?? ''}`, async () => (await this.gecko.trades(pool, { mint })).trades, { ttlMs: TRADES_TTL, source: 'geckoterminal' });
+    }
+}

package/dist/packages/data/src/fast-lane.js

@@ -0,0 +1,321 @@
+// Fast lane: real-time on-chain price for the few tokens the user is actually looking at (SPEC §3.9,
+// task-1312). A token's lane is a property of attention: the open token, the watchlist and fresh pump
+// launches are priced by push (accountSubscribe on their pump.fun bonding-curve account, price computed
+// on-chain, sub-second); everything else stays on the slow (poll) lane. This coordinator owns:
+//   - the fast set (capped — see FAST_LANE_CAP) and each mint's resolved PriceAccount,
+//   - one shared SolanaWsClient multiplexing every subscription on one connection,
+//   - an initial seed (one batched getMultipleAccounts through the RPC pool) so a price shows at once,
+//   - endpoint failover (keyed Helius-ws first, keyless public RPC ws as the fallback) and graceful
+//     degradation to the slow lane when no stream is available or the Helius credit budget is spent,
+//   - honest lane/badge state: laneFor()/badgeFor() report POLL whenever the stream is not actually
+//     delivering that token (down, not pump.fun, migrated, or over the cap).
+//
+// Price USD comes from an injected SOL/USD getter (the slow lane already fetches it); the on-chain decode
+// only yields SOL. Never logs an endpoint URL (may carry a key).
+import { systemClock } from "./clock.js";
+import { decodeBondingCurve } from "./sources/pump-curve.js";
+import { isPumpMint, pumpBondingCurve } from "./sources/pda.js";
+import { SolanaWsClient } from "./sources/solana-ws.js";
+/**
+ * Max simultaneous fast-lane subscriptions. Chosen for the free tier: one shared WS connection
+ * multiplexes them (SPEC §3.9.4), each subscription only fires on an account change (cheap), the Helius
+ * credit meter bounds total spend regardless, and the keyless public RPC WS has tight undocumented
+ * limits — so a conservative cap of 24 comfortably covers the open token + a 5–20 watchlist + a few
+ * fresh launches. Tokens past the cap simply stay on the slow lane (honest POLL badge), never dropped.
+ */
+export const FAST_LANE_CAP = 24;
+/** How long after the last push a token is still considered "streaming" for the LIVE badge. */
+export const LIVE_FRESHNESS_MS = 90_000;
+/** Rotate to the next endpoint after this many consecutive WS failures. */
+const ROTATE_AFTER_FAILURES = 3;
+export class FastLane {
+    opts;
+    clock;
+    cap;
+    tracked = new Map();
+    byAccount = new Map(); // price account -> mint
+    endpoints;
+    epIndex = 0;
+    ws = null;
+    started = false;
+    switching = false;
+    lastError = null;
+    constructor(opts) {
+        if (opts.endpoints.length === 0)
+            throw new Error('FastLane needs at least one WS endpoint');
+        this.opts = opts;
+        this.clock = opts.clock ?? systemClock;
+        this.cap = opts.cap ?? FAST_LANE_CAP;
+        this.endpoints = opts.endpoints;
+    }
+    get endpoint() {
+        return this.endpoints[this.epIndex];
+    }
+    /** Attach the stream and subscribe whatever is already tracked. Idempotent. */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.openWs();
+    }
+    stop() {
+        this.started = false;
+        this.ws?.stop();
+        this.ws = null;
+        this.emit();
+    }
+    openWs() {
+        const ep = this.endpoint;
+        const meter = ep.keyed ? this.opts.credits ?? null : null;
+        this.ws = new SolanaWsClient({
+            url: ep.url,
+            source: ep.source,
+            clock: this.clock,
+            health: this.opts.health,
+            ws: this.opts.ws,
+            onAccount: (u) => this.onAccount(u),
+            onBytes: meter ? (b) => { meter.chargeBytes(b); this.maybeDegrade(); } : undefined,
+            onStatus: (s) => this.onWsStatus(s),
+        });
+        this.ws.start();
+        // (Re)subscribe everything already tracked on the new socket.
+        this.ws.setAccounts([...this.byAccount.keys()]);
+        // Seed an initial price for everything tracked (so a value shows before the first push).
+        void this.seed([...this.tracked.keys()]);
+        this.emit();
+    }
+    onWsStatus(s) {
+        if (this.switching || s.state === 'stopped')
+            return; // ignore events we caused while swapping endpoints
+        if (s.lastError)
+            this.lastError = s.lastError;
+        // Endpoint keeps failing: fail over to the next one (keyed → public keyless).
+        if (s.failures >= ROTATE_AFTER_FAILURES && this.endpoints.length > 1)
+            this.rotate('repeated ws failures');
+        this.emit();
+    }
+    /** Swap to `index`, preserving the desired subscription set. Reentrancy-guarded (openWs/stop emit). */
+    switchTo(index) {
+        if (index === this.epIndex || index < 0 || index >= this.endpoints.length)
+            return;
+        this.switching = true;
+        try {
+            this.epIndex = index;
+            this.ws?.stop();
+            this.ws = null;
+            if (this.started)
+                this.openWs();
+        }
+        finally {
+            this.switching = false;
+        }
+        this.emit();
+    }
+    /** Switch to the next endpoint, preserving the desired subscription set. */
+    rotate(_reason) {
+        if (this.endpoints.length <= 1)
+            return;
+        this.switchTo((this.epIndex + 1) % this.endpoints.length);
+    }
+    /** On Helius credit exhaustion, drop to the first keyless endpoint so the lane keeps streaming free. */
+    maybeDegrade() {
+        const credits = this.opts.credits;
+        if (this.switching || !credits || !this.endpoint.keyed)
+            return;
+        if (credits.level() !== 'degraded')
+            return;
+        const keyless = this.endpoints.findIndex((e) => !e.keyed);
+        if (keyless >= 0)
+            this.switchTo(keyless);
+    }
+    /**
+     * Resolve a mint's on-chain pricing account. A known bonding-curve (from a PumpPortal Create event) is
+     * used directly; otherwise a pump.fun mint's curve is derived as a PDA. Non-pump mints are `unknown`
+     * and stay on the slow lane.
+     */
+    resolvePriceAccount(mint, curveHint) {
+        if (curveHint)
+            return { mint, kind: 'pump-curve', curve: curveHint };
+        if (isPumpMint(mint)) {
+            try {
+                return { mint, kind: 'pump-curve', curve: pumpBondingCurve(mint) };
+            }
+            catch {
+                return { mint, kind: 'unknown' };
+            }
+        }
+        return { mint, kind: 'unknown' };
+    }
+    /**
+     * Add a mint to the fast set. Returns true when it was promoted to the fast lane (streamable and within
+     * the cap), false when it must stay on the slow lane. Idempotent for an already-tracked mint.
+     */
+    track(mint, curveHint) {
+        const existing = this.tracked.get(mint);
+        if (existing)
+            return existing.priceAccount.kind !== 'unknown' && !existing.migrated;
+        const priceAccount = this.resolvePriceAccount(mint, curveHint);
+        if (priceAccount.kind === 'unknown' || !priceAccount.curve)
+            return false;
+        if (this.tracked.size >= this.cap)
+            return false; // over the cap: stay slow, never drop
+        const t = { mint, priceAccount, lastTickAt: null, lastPrice: null, migrated: false };
+        this.tracked.set(mint, t);
+        this.byAccount.set(priceAccount.curve, mint);
+        this.ws?.subscribe(priceAccount.curve);
+        if (this.started)
+            void this.seed([mint]);
+        this.emit();
+        return true;
+    }
+    untrack(mint) {
+        const t = this.tracked.get(mint);
+        if (!t)
+            return;
+        this.tracked.delete(mint);
+        if (t.priceAccount.curve) {
+            this.byAccount.delete(t.priceAccount.curve);
+            this.ws?.unsubscribe(t.priceAccount.curve);
+        }
+        this.emit();
+    }
+    /**
+     * Replace the fast set wholesale (open token + watchlist + fresh launches). `curveHints` carries known
+     * curves (e.g. from Create events) so no PDA derivation is needed. Order matters when over the cap:
+     * earlier mints win (callers pass the open token first).
+     */
+    setTracked(mints, curveHints) {
+        const next = [...mints];
+        const nextSet = new Set(next);
+        for (const mint of [...this.tracked.keys()])
+            if (!nextSet.has(mint))
+                this.untrack(mint);
+        for (const mint of next)
+            this.track(mint, curveHints?.get(mint) ?? null);
+    }
+    /** Seed first prices for `mints` via one batched getMultipleAccounts (through the pool). Best-effort. */
+    async seed(mints) {
+        const curves = [];
+        for (const m of mints) {
+            const t = this.tracked.get(m);
+            if (t?.priceAccount.curve)
+                curves.push(t.priceAccount.curve);
+        }
+        if (curves.length === 0)
+            return;
+        let data;
+        try {
+            ({ data } = await this.opts.rpcPool.accountsRaw(curves, 'processed'));
+        }
+        catch {
+            return; // the first push will supply a price
+        }
+        for (const [account, base64] of data) {
+            if (base64)
+                this.ingest(account, null, base64, this.clock.now(), true);
+        }
+    }
+    onAccount(u) {
+        this.ingest(u.account, u.slot, u.base64, u.receivedAt, false);
+    }
+    /** Decode a curve account to a PricePoint and emit it. `seed` marks the initial (non-push) value. */
+    ingest(account, slot, base64, t, seed) {
+        const mint = this.byAccount.get(account);
+        if (!mint)
+            return;
+        const tracked = this.tracked.get(mint);
+        if (!tracked)
+            return;
+        const curve = decodeBondingCurve(base64);
+        if (!curve || curve.priceSol == null)
+            return;
+        if (curve.complete) {
+            // Migrated to a DEX pool: the bonding-curve price is stale. Demote to the slow lane honestly;
+            // AMM-pool on-chain pricing is a later card (SPEC §3.9.4).
+            tracked.migrated = true;
+            this.emit();
+            return;
+        }
+        const solUsd = this.opts.solUsd();
+        const point = {
+            mint,
+            priceSol: curve.priceSol,
+            priceUsd: solUsd != null && Number.isFinite(solUsd) ? curve.priceSol * solUsd : null,
+            slot,
+            t,
+            source: 'onchain-curve',
+            lane: 'fast',
+        };
+        tracked.lastPrice = point;
+        if (!seed)
+            tracked.lastTickAt = t;
+        this.opts.onPrice?.(point);
+        if (!seed)
+            this.emit();
+    }
+    /** The lane a mint is on right now (honest): fast only when its curve is actually streaming. */
+    laneFor(mint) {
+        return this.isLive(mint) ? 'fast' : 'slow';
+    }
+    /** Honest per-row/panel badge: LIVE when a fresh on-chain push is flowing, else POLL. */
+    badgeFor(mint) {
+        return this.isLive(mint) ? 'LIVE' : 'POLL';
+    }
+    isLive(mint) {
+        const t = this.tracked.get(mint);
+        if (!t || t.migrated || t.priceAccount.kind === 'unknown' || !t.priceAccount.curve)
+            return false;
+        if (!this.ws || this.ws.getStatus().state !== 'open')
+            return false;
+        // Keyed stream with the credit budget spent is not actually delivering: POLL.
+        if (this.endpoint.keyed && this.opts.credits && this.opts.credits.level() === 'degraded')
+            return false;
+        // This specific curve must have a live server subscription (its own ack received).
+        if (!this.ws.isActive(t.priceAccount.curve))
+            return false;
+        // LIVE means a real on-chain push arrived recently; a seed-only or stale value is honestly POLL.
+        return t.lastTickAt != null && this.clock.now() - t.lastTickAt <= LIVE_FRESHNESS_MS;
+    }
+    /** Last fast-lane price for a mint, or null. */
+    price(mint) {
+        return this.tracked.get(mint)?.lastPrice ?? null;
+    }
+    /**
+     * Last fast-lane USD price, recomputed from the stored on-chain SOL price and the *current* SOL/USD —
+     * so a tick that arrived before SOL/USD was known still shows a USD value once the rate lands. Null
+     * when there is no tick yet or no SOL/USD.
+     */
+    priceUsd(mint) {
+        const last = this.tracked.get(mint)?.lastPrice;
+        if (!last)
+            return null;
+        const s = this.opts.solUsd();
+        if (s != null && Number.isFinite(s))
+            return last.priceSol * s;
+        return last.priceUsd;
+    }
+    isTracked(mint) {
+        return this.tracked.has(mint);
+    }
+    status() {
+        const ws = this.ws?.getStatus();
+        let live = 0;
+        for (const m of this.tracked.keys())
+            if (this.isLive(m))
+                live++;
+        return {
+            active: this.started && !!this.ws,
+            endpoint: this.endpoint.label,
+            keyed: this.endpoint.keyed,
+            wsState: ws?.state ?? 'idle',
+            subscriptions: ws?.active ?? 0,
+            tracked: this.tracked.size,
+            live,
+            failures: ws?.failures ?? 0,
+            lastError: this.lastError,
+        };
+    }
+    emit() {
+        this.opts.onStatus?.(this.status());
+    }
+}