dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/sources/pda.js

@@ -0,0 +1,113 @@
+// Program-derived-address helpers (task-1312). The fast lane needs the pump.fun bonding-curve account
+// for a mint so it can accountSubscribe to it, but a Create event is not always on hand (an opened or
+// watchlisted token the user did not see launch). The curve is a PDA of the mint, so we derive it with
+// no @solana/web3.js dependency: base58 decode, the ed25519 on-curve test (TweetNaCl `unpackneg`, the
+// same check @solana/web3.js uses), and findProgramAddress. Validated against live-harvested mint→curve
+// pairs (task-1283 watchlist.json) in the unit tests, including bumps 255/254/253 so the off-curve path
+// is exercised.
+import { createHash } from 'node:crypto';
+import { base58 } from "./solana-rpc.js";
+const B58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const B58_MAP = {};
+for (let i = 0; i < B58_ALPHABET.length; i++)
+    B58_MAP[B58_ALPHABET[i]] = i;
+/** Base58 (Bitcoin alphabet) decode to bytes. Throws on an invalid character. */
+export function base58Decode(s) {
+    const bytes = [0];
+    for (const c of s) {
+        const carryStart = B58_MAP[c];
+        if (carryStart === undefined)
+            throw new Error(`invalid base58 character ${JSON.stringify(c)}`);
+        let carry = carryStart;
+        for (let j = 0; j < bytes.length; j++) {
+            carry += bytes[j] * 58;
+            bytes[j] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    // A value of zero leaves the seed digit [0] behind; drop it so leading '1's map to exactly one zero
+    // byte each (the System program `111…1` must decode to 32 zero bytes, not 33 — task-1310 round 2).
+    if (bytes.length === 1 && bytes[0] === 0)
+        bytes.length = 0;
+    for (let k = 0; k < s.length && s[k] === '1'; k++)
+        bytes.push(0);
+    return Uint8Array.from(bytes.reverse());
+}
+// ---- ed25519 field math for the on-curve test ----
+const P = (1n << 255n) - 19n;
+const D = 37095705934669439343138083508754565189542113879843219016388785533085940283555n;
+function mod(a) {
+    a %= P;
+    return a < 0n ? a + P : a;
+}
+function pow(a, e) {
+    let r = 1n;
+    a = mod(a);
+    while (e > 0n) {
+        if (e & 1n)
+            r = mod(r * a);
+        a = mod(a * a);
+        e >>= 1n;
+    }
+    return r;
+}
+const SQRT_M1 = pow(2n, (P - 1n) / 4n); // sqrt(-1) mod p
+/**
+ * True when the 32-byte value is a valid ed25519 point (i.e. ON the curve). A program-derived address
+ * must be OFF the curve. Ported from TweetNaCl's `unpackneg`: recover x from y and check v·x² == ±u.
+ */
+export function isOnCurve(bytes) {
+    if (bytes.length !== 32)
+        return false;
+    let y = 0n;
+    for (let i = 31; i >= 0; i--)
+        y = (y << 8n) | BigInt(bytes[i]);
+    y &= (1n << 255n) - 1n; // drop the sign bit
+    const y2 = mod(y * y);
+    const u = mod(y2 - 1n);
+    const v = mod(D * y2 + 1n);
+    const v3 = mod(v * v * v);
+    const v7 = mod(v3 * v3 * v);
+    let x = mod(u * v3 * pow(mod(u * v7), (P - 5n) / 8n));
+    const vx2 = mod(v * x * x);
+    if (vx2 === u)
+        return true;
+    if (vx2 === mod(-u)) {
+        x = mod(x * SQRT_M1);
+        return mod(v * x * x) === u;
+    }
+    return false;
+}
+const PDA_MARKER = Buffer.from('ProgramDerivedAddress');
+/**
+ * Deterministic findProgramAddress: the highest bump (255→0) whose sha256(seeds‖bump‖program‖marker)
+ * is off the curve. Throws if none is found (cryptographically ~impossible).
+ */
+export function findProgramAddress(seeds, programId) {
+    for (let bump = 255; bump >= 0; bump--) {
+        const h = createHash('sha256');
+        for (const s of seeds)
+            h.update(Buffer.from(s));
+        h.update(Buffer.from([bump]));
+        h.update(Buffer.from(programId));
+        h.update(PDA_MARKER);
+        const hash = h.digest();
+        if (!isOnCurve(hash))
+            return { address: base58(hash), bump };
+    }
+    throw new Error('unable to find a program address bump');
+}
+export const PUMP_PROGRAM_ID = '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P';
+const PUMP_CURVE_SEED = Buffer.from('bonding-curve');
+/** The pump.fun bonding-curve account for a mint (PDA of ["bonding-curve", mint] under the pump program). */
+export function pumpBondingCurve(mint) {
+    return findProgramAddress([PUMP_CURVE_SEED, base58Decode(mint)], base58Decode(PUMP_PROGRAM_ID)).address;
+}
+/** pump.fun mints are minted with a `pump` suffix; a cheap keyless hint for "this is streamable on a curve". */
+export function isPumpMint(mint) {
+    return /pump$/.test(mint);
+}

package/dist/packages/data/src/sources/pump-curve.js

@@ -0,0 +1,58 @@
+// pump.fun bonding-curve price, computed from on-chain account state only — no aggregator (SPEC §3.9,
+// task-1312; ported from the task-1283 spike's pump-curve.mjs and validated live there against
+// PumpPortal's marketCapSol, 28 SOL ✓).
+//
+// The bonding-curve account (owned by program 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P) is an Anchor
+// account. Layout (little-endian), confirmed against pump.fun's published IDL:
+//   [0..8)   8-byte account discriminator
+//   [8..16)  virtualTokenReserves  u64   (token base units, 6 decimals)
+//   [16..24) virtualSolReserves    u64   (lamports, 9 decimals)
+//   [24..32) realTokenReserves     u64
+//   [32..40) realSolReserves       u64
+//   [40..48) tokenTotalSupply      u64
+//   [48]     complete              u8  (1 once migrated to a DEX pool)
+//   [49..81) creator               pubkey (present on curves created after the 2025 creator-fee upgrade)
+//
+// Spot price of 1 token in SOL on the constant-product curve = virtualSol / virtualToken, adjusted for
+// the 9-vs-6 decimal gap. Virtual reserves are the pricing reserves (they include the initial virtual
+// offset). Multiply by SOL/USD for a USD tick. Decode is < 1 ms and allocation-light.
+export const PUMP_PROGRAM = '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P';
+const SOL_DECIMALS = 9;
+const TOKEN_DECIMALS = 6;
+/** Base discriminator (8) + five u64 (40) + complete (1). */
+const CURVE_MIN_LEN = 49;
+/** Decode a base64 bonding-curve account into reserves + derived spot price. Returns null on junk. */
+export function decodeBondingCurve(base64) {
+    let buf;
+    try {
+        buf = Buffer.from(base64, 'base64');
+    }
+    catch {
+        return null;
+    }
+    if (buf.length < CURVE_MIN_LEN)
+        return null;
+    const virtualTokenReserves = buf.readBigUInt64LE(8);
+    const virtualSolReserves = buf.readBigUInt64LE(16);
+    const realTokenReserves = buf.readBigUInt64LE(24);
+    const realSolReserves = buf.readBigUInt64LE(32);
+    const tokenTotalSupply = buf.readBigUInt64LE(40);
+    const complete = buf.readUInt8(48) === 1;
+    const vSol = Number(virtualSolReserves) / 10 ** SOL_DECIMALS;
+    const vToken = Number(virtualTokenReserves) / 10 ** TOKEN_DECIMALS;
+    const priceSol = vToken > 0 ? vSol / vToken : null;
+    return { virtualTokenReserves, virtualSolReserves, realTokenReserves, realSolReserves, tokenTotalSupply, complete, vSol, vToken, priceSol };
+}
+/** Full-dilution market cap in SOL from a decoded curve (totalSupply is 6-decimal base units). */
+export function marketCapSol(curve) {
+    if (!curve || curve.priceSol == null)
+        return null;
+    const supply = Number(curve.tokenTotalSupply) / 10 ** TOKEN_DECIMALS;
+    return curve.priceSol * supply;
+}
+/** Price one token in USD from a decoded curve and a SOL/USD rate (null when either is missing). */
+export function curvePriceUsd(curve, solUsd) {
+    if (!curve || curve.priceSol == null || solUsd == null || !Number.isFinite(solUsd))
+        return null;
+    return curve.priceSol * solUsd;
+}

package/dist/packages/data/src/sources/pumpportal.js

@@ -0,0 +1,247 @@
+// PumpPortal real-time data stream (SPEC §3.1 S7; inventory 2026-10-06 §1b). Keyless, read-only.
+//   wss://pumpportal.fun/api/data
+//   -> { method: 'subscribeNewToken' }   creates: { signature, mint, traderPublicKey, txType: 'create',
+//        initialBuy, solAmount, bondingCurveKey, vTokensInBondingCurve, vSolInBondingCurve, marketCapSol,
+//        name, symbol, uri, is_mayhem_mode, pool }
+//   -> { method: 'subscribeMigration' }  migrations (shape varies; we keep mint + signature + pool)
+// One connection per client (their rule). Measured 2026-10-06: connect 116 ms, first message 139 ms,
+// ~15 creates/min, ~3 migrations/min. The trade streams are paid and never subscribed here.
+//
+// The client reconnects with exponential backoff (1 s doubling to 30 s), reports every message / error
+// to the health registry under `pumpportal`, can record the session into a FixtureStore stream, and the
+// same event path replays a recording (tests, --replay) with the original timing or instantly.
+import { systemClock } from "../clock.js";
+import { numOrNull } from "../util.js";
+export const PUMPPORTAL_WS = 'wss://pumpportal.fun/api/data';
+/** pump.fun Global config (docs/pump-fun/docs-overview.md): the curve starts with these virtual/real reserves. */
+export const PUMP_INITIAL_VIRTUAL_TOKENS = 1_073_000_000; // UI units (6 decimals)
+export const PUMP_INITIAL_REAL_TOKENS = 793_100_000;
+export const PUMP_INITIAL_VIRTUAL_SOL = 30;
+/**
+ * Curve completion estimate from the virtual token reserves: real tokens left = vTokens − (virtual − real
+ * initial offset); complete when none are left. Returns 0..100, or null when the reserves are missing.
+ */
+export function bondingProgress(vTokens) {
+    if (vTokens === null || !Number.isFinite(vTokens))
+        return null;
+    const offset = PUMP_INITIAL_VIRTUAL_TOKENS - PUMP_INITIAL_REAL_TOKENS; // 279.9M never sold on the curve
+    const realLeft = vTokens - offset;
+    const pct = (1 - realLeft / PUMP_INITIAL_REAL_TOKENS) * 100;
+    return Math.max(0, Math.min(100, Math.round(pct * 10) / 10));
+}
+function launchpadFor(pool, mint) {
+    const p = (pool ?? '').toLowerCase();
+    if (p.includes('bonk'))
+        return 'bonk';
+    if (p.includes('pump') || mint.endsWith('pump'))
+        return 'pump.fun';
+    return 'unknown';
+}
+export function createFromRaw(raw, receivedAt) {
+    if (!raw.mint || typeof raw.mint !== 'string')
+        return null;
+    const vToken = numOrNull(raw.vTokensInBondingCurve);
+    return {
+        source: 'pumpportal',
+        fetchedAt: receivedAt,
+        mint: raw.mint,
+        creator: typeof raw.traderPublicKey === 'string' ? raw.traderPublicKey : '',
+        launchpad: launchpadFor(raw.pool, raw.mint),
+        name: typeof raw.name === 'string' ? raw.name : '',
+        symbol: typeof raw.symbol === 'string' ? raw.symbol : '',
+        uri: typeof raw.uri === 'string' && raw.uri ? raw.uri : null,
+        signature: typeof raw.signature === 'string' ? raw.signature : null,
+        initialBuyTokens: numOrNull(raw.initialBuy),
+        initialBuySol: numOrNull(raw.solAmount),
+        vSol: numOrNull(raw.vSolInBondingCurve),
+        vToken,
+        marketCapSol: numOrNull(raw.marketCapSol),
+        bondingCurve: typeof raw.bondingCurveKey === 'string' ? raw.bondingCurveKey : null,
+        pool: typeof raw.pool === 'string' ? raw.pool : null,
+        bondingPct: bondingProgress(vToken),
+        receivedAt,
+    };
+}
+/** Classify one text frame. Never throws: junk is `other`. */
+export function parsePumpMessage(text, receivedAt) {
+    let j;
+    try {
+        j = JSON.parse(text);
+    }
+    catch {
+        return { kind: 'other', receivedAt };
+    }
+    if (!j || typeof j !== 'object')
+        return { kind: 'other', receivedAt };
+    const o = j;
+    if (typeof o.message === 'string' && !o.mint)
+        return { kind: 'info', message: o.message, receivedAt };
+    if (o.txType === 'create' || (o.mint && (o.name !== undefined || o.vTokensInBondingCurve !== undefined))) {
+        const create = createFromRaw(o, receivedAt);
+        return create ? { kind: 'create', create, receivedAt } : { kind: 'other', receivedAt };
+    }
+    if (o.txType === 'migrate' || o.txType === 'migration' || /migrat/i.test(text.slice(0, 200))) {
+        return { kind: 'migrate', mint: typeof o.mint === 'string' ? o.mint : null, signature: typeof o.signature === 'string' ? o.signature : null, pool: typeof o.pool === 'string' ? o.pool : null, receivedAt };
+    }
+    return { kind: 'other', receivedAt };
+}
+export const PUMP_FREE_METHODS = ['subscribeNewToken', 'subscribeMigration'];
+export class PumpPortalClient {
+    url;
+    make;
+    clock;
+    health;
+    opts;
+    ws = null;
+    status = { state: 'idle', attempts: 0, failures: 0, messages: 0, creates: 0, migrations: 0, bytes: 0, connectedAt: null, lastMessageAt: null, lastError: null, nextRetryMs: null };
+    stopped = false;
+    startedAt = 0;
+    /** Aborts a pending reconnect-backoff sleep so stop() never leaves a timer holding the loop (task-1311). */
+    retryAbort = null;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.url = opts.url ?? PUMPPORTAL_WS;
+        this.clock = opts.clock ?? systemClock;
+        this.health = opts.health;
+        const g = globalThis;
+        this.make = opts.ws ?? ((url) => {
+            if (!g.WebSocket)
+                throw new Error('WebSocket is not available in this runtime (Node 22+ required)');
+            return new g.WebSocket(url);
+        });
+        for (const m of opts.subscriptions ?? PUMP_FREE_METHODS) {
+            if (!PUMP_FREE_METHODS.includes(m))
+                throw new Error(`refusing paid PumpPortal method ${m}`);
+        }
+    }
+    getStatus() {
+        return { ...this.status };
+    }
+    start() {
+        if (this.status.state !== 'idle' && this.status.state !== 'stopped')
+            return;
+        this.stopped = false;
+        this.startedAt = this.clock.now();
+        if (this.opts.record)
+            this.opts.record.startedAt = new Date(this.startedAt).toISOString();
+        void this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        this.retryAbort?.abort(); // cancel a pending backoff sleep so the process can exit at once (task-1311)
+        this.set({ state: 'stopped', nextRetryMs: null });
+        const ws = this.ws;
+        this.ws = null;
+        try {
+            ws?.close(1000, 'dexterm stop');
+        }
+        catch { /* already closed */ }
+    }
+    set(patch) {
+        this.status = { ...this.status, ...patch };
+        this.opts.onStatus?.(this.getStatus());
+    }
+    async connect() {
+        if (this.stopped)
+            return;
+        this.set({ state: this.status.attempts === 0 ? 'connecting' : 'reconnecting', attempts: this.status.attempts + 1, nextRetryMs: null });
+        let ws;
+        try {
+            ws = this.make(this.url);
+        }
+        catch (err) {
+            this.fail(err instanceof Error ? err.message : String(err));
+            return this.retry();
+        }
+        this.ws = ws;
+        let opened = false;
+        ws.addEventListener('open', () => {
+            if (this.ws !== ws)
+                return;
+            opened = true;
+            this.set({ state: 'open', failures: 0, connectedAt: this.clock.now(), lastError: null });
+            for (const method of this.opts.subscriptions ?? PUMP_FREE_METHODS) {
+                const text = JSON.stringify({ method });
+                try {
+                    ws.send(text);
+                }
+                catch { /* close handler will retry */ }
+                this.opts.record?.sent.push(text);
+            }
+        });
+        ws.addEventListener('message', (ev) => {
+            if (this.ws !== ws)
+                return;
+            const text = typeof ev.data === 'string' ? ev.data : ev.data instanceof ArrayBuffer ? Buffer.from(ev.data).toString('utf8') : String(ev.data ?? '');
+            this.handle(text);
+        });
+        ws.addEventListener('error', (ev) => {
+            if (this.ws !== ws)
+                return;
+            const msg = ev.message ?? 'websocket error';
+            this.set({ lastError: msg });
+        });
+        ws.addEventListener('close', (ev) => {
+            if (this.ws !== ws)
+                return;
+            this.ws = null;
+            if (this.stopped)
+                return;
+            const reason = `closed ${ev.code ?? '?'}${ev.reason ? ` ${ev.reason}` : ''}${opened ? '' : ' before open'}`;
+            this.fail(reason);
+            void this.retry();
+        });
+    }
+    fail(message) {
+        this.health?.record('pumpportal', { ok: false, error: message });
+        this.set({ failures: this.status.failures + 1, lastError: message });
+    }
+    async retry() {
+        if (this.stopped)
+            return;
+        const base = this.opts.baseBackoffMs ?? 1_000;
+        const max = this.opts.maxBackoffMs ?? 30_000;
+        const wait = Math.min(max, base * 2 ** Math.max(0, this.status.failures - 1));
+        this.set({ state: 'reconnecting', nextRetryMs: wait });
+        this.retryAbort = new AbortController();
+        await this.clock.sleep(wait, this.retryAbort.signal);
+        if (this.stopped)
+            return; // stop() fired during the backoff: do not reconnect
+        await this.connect();
+    }
+    /** Parse one frame, record it, report health, emit. Shared by live and replay. */
+    handle(text, receivedAt = this.clock.now()) {
+        const ev = parsePumpMessage(text, receivedAt);
+        const bytes = Buffer.byteLength(text, 'utf8');
+        this.opts.record?.messages.push({ tMs: Math.max(0, receivedAt - this.startedAt), text });
+        this.set({
+            messages: this.status.messages + 1,
+            bytes: this.status.bytes + bytes,
+            lastMessageAt: receivedAt,
+            creates: this.status.creates + (ev.kind === 'create' ? 1 : 0),
+            migrations: this.status.migrations + (ev.kind === 'migrate' ? 1 : 0),
+        });
+        if (ev.kind === 'create' || ev.kind === 'migrate')
+            this.health?.record('pumpportal', { ok: true, latencyMs: 0 });
+        this.opts.onEvent?.(ev);
+        return ev;
+    }
+    /**
+     * Replay a recorded session through the same handler. `speed` 1 keeps the recorded gaps (on the
+     * client's clock), 0 delivers everything at once. Resolves when the last message was delivered.
+     */
+    async replay(rec, speed = 0) {
+        this.startedAt = this.clock.now();
+        this.set({ state: 'open', connectedAt: this.startedAt, attempts: 1 });
+        let last = 0;
+        for (const m of rec.messages) {
+            if (this.stopped)
+                break;
+            if (speed > 0 && m.tMs > last)
+                await this.clock.sleep((m.tMs - last) / speed);
+            last = m.tMs;
+            this.handle(m.text, this.clock.now());
+        }
+        return rec.messages.length;
+    }
+}

package/dist/packages/data/src/sources/rugcheck.js

@@ -0,0 +1,71 @@
+// RugCheck adapter (SPEC §3.1 S5). Keyless, read-only, summary endpoint only
+// (the full report may need a JWT; we never send one).
+//   GET https://api.rugcheck.xyz/v1/tokens/{mint}/report/summary
+//       -> { tokenProgram, tokenType, risks: [{ name, value, description, score, level }],
+//            score, score_normalised, lpLockedPct }
+// Limits are undocumented (community: ~20 full reports/day/IP); the bucket is a
+// conservative guess and results are cached 10 min (TTL.rugcheck).
+// `name`/`description`/`value` are third-party text: firewall before any model sees them (CL-06).
+import { num, numOrNull } from "../util.js";
+export const RUGCHECK_BASE = 'https://api.rugcheck.xyz/v1';
+const META = { source: 'rugcheck', bucket: 'rugcheck' };
+const LEVEL_RANK = { danger: 0, warn: 1, info: 2, unknown: 3 };
+function level(v) {
+    return v === 'danger' || v === 'warn' || v === 'info' ? v : 'unknown';
+}
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+export function normalizeRugSummary(mint, raw, fetchedAt) {
+    const risks = (raw.risks ?? [])
+        .filter((r) => typeof r?.name === 'string' && r.name !== '')
+        .map((r) => ({ name: r.name, level: level(r.level), score: num(r.score), value: str(r.value), description: str(r.description) }))
+        .sort((a, b) => LEVEL_RANK[a.level] - LEVEL_RANK[b.level] || b.score - a.score);
+    return {
+        mint,
+        score: numOrNull(raw.score),
+        scoreNormalised: numOrNull(raw.score_normalised),
+        lpLockedPct: numOrNull(raw.lpLockedPct),
+        tokenProgram: str(raw.tokenProgram),
+        tokenType: str(raw.tokenType),
+        risks,
+        source: 'rugcheck',
+        fetchedAt,
+    };
+}
+/** The Audit fields RugCheck owns (SPEC §3.3/§3.6): LP locked, risk names, score. */
+export function auditPatchFromRug(s) {
+    return { lpLockedPct: s.lpLockedPct, rugRisks: s.risks.map((r) => r.name), rugScore: s.scoreNormalised ?? s.score };
+}
+export function normalizeNewToken(raw, fetchedAt) {
+    if (!raw || typeof raw.mint !== 'string' || !raw.mint)
+        return null;
+    const auth = (v) => (v === undefined ? null : typeof v === 'string' && v !== '' ? true : false);
+    const created = typeof raw.createAt === 'string' ? Date.parse(raw.createAt) : NaN;
+    return {
+        mint: raw.mint,
+        symbol: typeof raw.symbol === 'string' ? raw.symbol : '',
+        creator: str(raw.creator),
+        mintAuthority: auth(raw.mintAuthority),
+        freezeAuthority: auth(raw.freezeAuthority),
+        program: str(raw.program),
+        decimals: numOrNull(raw.decimals),
+        createdAt: Number.isFinite(created) ? created : null,
+        source: 'rugcheck',
+        fetchedAt,
+    };
+}
+export class RugCheck {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async summary(mint) {
+        const r = await this.http.getJson(`${RUGCHECK_BASE}/tokens/${encodeURIComponent(mint)}/report/summary`, META);
+        return normalizeRugSummary(mint, r.data ?? {}, r.fetchedAt);
+    }
+    /** Newest mints RugCheck has indexed (≈10 rows, 103 ms measured): creator and authority cross-check for new pairs. */
+    async newTokens() {
+        const r = await this.http.getJson(`${RUGCHECK_BASE}/stats/new_tokens`, META);
+        const list = Array.isArray(r.data) ? r.data : Array.isArray(r.data?.tokens) ? r.data.tokens : [];
+        return list.map((t) => normalizeNewToken(t, r.fetchedAt)).filter((t) => t !== null);
+    }
+}