dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/trade/copy/stats.js

@@ -0,0 +1,120 @@
+// task-1360 Tier 1 — PnL, win rate and early-entry score for a followed wallet (research/wallet-intel design
+// §4.3), computed from decoded trades only. Every number is sample-bounded and says so: realised PnL is FIFO by
+// token amount over the trades we have, in SOL (exact) with a USD view at the rate given; win rate is hidden under
+// n < 10 closed positions; the early-entry score needs launch-window buyer ranks (a token's bubble-map scan) and is
+// `—` with the reason otherwise. Airdrops / transfers-in are cost 0 and flagged; transfers-out remove tokens and
+// their cost without touching realised PnL (a wallet move is not a loss). Nothing here is a recommendation.
+export const WIN_RATE_MIN_N = 10;
+function closedNow(p) {
+    return p.peakRaw > 0n && p.tokensRaw * 100n <= p.peakRaw;
+}
+/** FIFO positions per mint over trades sorted oldest first. */
+export function positionsOf(trades) {
+    const lots = new Map();
+    const pos = new Map();
+    const sorted = [...trades].sort((a, b) => a.slot - b.slot || a.sig.localeCompare(b.sig));
+    for (const tr of sorted) {
+        const delta = BigInt(tr.tokenDelta);
+        let p = pos.get(tr.mint);
+        if (!p) {
+            p = { mint: tr.mint, tokensRaw: 0n, peakRaw: 0n, costSol: 0, realisedSol: 0, buys: 0, sells: 0, transfers: 0, flagged: false, closed: false, firstT: tr.t, lastT: tr.t };
+            pos.set(tr.mint, p);
+        }
+        const L = lots.get(tr.mint) ?? [];
+        lots.set(tr.mint, L);
+        p.lastT = tr.t;
+        if (delta > 0n) {
+            // a buy with a SOL leg carries cost; a token-swap leg or an airdrop is cost 0 and flagged
+            const cost = tr.side === 'buy' && tr.solDelta !== null ? Math.abs(tr.solDelta) : 0;
+            const flagged = cost === 0;
+            L.push({ tokensRaw: delta, costSol: cost, flagged });
+            p.tokensRaw += delta;
+            p.costSol += cost;
+            if (flagged)
+                p.flagged = true;
+            if (tr.side === 'buy')
+                p.buys += 1;
+            else
+                p.transfers += 1;
+            if (p.tokensRaw > p.peakRaw)
+                p.peakRaw = p.tokensRaw;
+        }
+        else {
+            let need = -delta;
+            let costOut = 0;
+            while (need > 0n && L.length) {
+                const lot = L[0];
+                if (lot.tokensRaw <= need) {
+                    need -= lot.tokensRaw;
+                    costOut += lot.costSol;
+                    L.shift();
+                }
+                else {
+                    const frac = Number(need) / Number(lot.tokensRaw);
+                    const c = lot.costSol * frac;
+                    costOut += c;
+                    lot.costSol -= c;
+                    lot.tokensRaw -= need;
+                    need = 0n;
+                }
+            }
+            const removed = -delta - need; // tokens we actually had lots for (history may start mid-position)
+            p.tokensRaw -= removed;
+            if (p.tokensRaw < 0n)
+                p.tokensRaw = 0n;
+            p.costSol = Math.max(0, p.costSol - costOut);
+            if (tr.side === 'sell' && tr.solDelta !== null) {
+                p.realisedSol += tr.solDelta - costOut;
+                p.sells += 1;
+            }
+            else if (tr.side === 'sell') {
+                p.sells += 1;
+                p.flagged = true;
+            } // token-swap leg: proceeds unknown, cost released
+            else
+                p.transfers += 1; // transfer-out: cost released, no PnL
+        }
+        p.closed = closedNow(p);
+    }
+    return [...pos.values()].sort((a, b) => b.lastT - a.lastT);
+}
+/** Early-entry score = median over tokens of (1 − rank / buyers); null without ranks (design §4.3). */
+export function earlyEntryScore(inputs) {
+    const xs = inputs.filter((e) => e.buyers > 0 && e.rank >= 0 && e.rank < e.buyers).map((e) => 1 - e.rank / e.buyers).sort((a, b) => a - b);
+    if (!xs.length)
+        return { score: null, n: 0, note: 'needs launch-window buyer ranks (scan the token: M) · no 3× filter yet' };
+    const mid = Math.floor(xs.length / 2);
+    const score = xs.length % 2 ? xs[mid] : (xs[mid - 1] + xs[mid]) / 2;
+    return { score: Math.round(score * 1000) / 1000, n: xs.length, note: `median over ${xs.length} scanned launch window${xs.length === 1 ? '' : 's'} · no 3× filter yet` };
+}
+export function walletStats(wallet, trades, opts = {}) {
+    const positions = positionsOf(trades);
+    const closed = positions.filter((p) => p.closed);
+    const wins = closed.filter((p) => p.realisedSol > 0).length;
+    const realisedSol = positions.reduce((s, p) => s + p.realisedSol, 0);
+    const solUsd = typeof opts.solUsd === 'number' && opts.solUsd > 0 ? opts.solUsd : null;
+    const ts = trades.map((t) => t.t).filter((t) => t > 0);
+    const winRate = closed.length >= WIN_RATE_MIN_N ? wins / closed.length : null;
+    const txs = opts.txs ?? new Set(trades.map((t) => t.sig)).size;
+    return {
+        wallet,
+        trades: trades.length,
+        buys: trades.filter((t) => t.side === 'buy').length,
+        sells: trades.filter((t) => t.side === 'sell').length,
+        transfers: trades.filter((t) => t.side === 'transfer').length,
+        mints: positions.length,
+        realisedSol: Math.round(realisedSol * 1e6) / 1e6,
+        realisedUsd: solUsd === null ? null : Math.round(realisedSol * solUsd * 100) / 100,
+        solUsdAt: solUsd,
+        closed: closed.length,
+        wins,
+        winRate: winRate === null ? null : Math.round(winRate * 1000) / 1000,
+        winRateNote: closed.length >= WIN_RATE_MIN_N ? `${wins}/${closed.length} closed` : `hidden under n=${WIN_RATE_MIN_N} (${wins}/${closed.length} closed so far)`,
+        open: positions.length - closed.length,
+        earlyEntry: earlyEntryScore(opts.earlyEntry ?? []),
+        positions,
+        firstT: ts.length ? Math.min(...ts) : null,
+        lastT: ts.length ? Math.max(...ts) : null,
+        sample: { txs, complete: !!opts.complete, note: opts.complete ? `all ${txs} txs` : `last ${txs} txs only · older history not fetched` },
+    };
+}

package/dist/packages/data/src/trade/copy/tracker.js

@@ -0,0 +1,158 @@
+// task-1360 Tier 1 — the WALLET TRACKER: polls each followed wallet's recent history (Helius
+// `getTransactionsForAddress`, newest first, 10 credits a call; the limiter and credit meter own the budget),
+// decodes new transactions into trades, keeps per-wallet trades + stats, and raises an ALERT for every new buy or
+// sell. The first page of a wallet is a BACKFILL (history is not news: no alerts); only transactions that appear
+// after that are alerted. Keyless the tracker is honestly unavailable with the free-key fix; a failed poll is a
+// visible degraded state, never silence. Read-only: it never trades, never signs, never proposes by itself —
+// stages 2 and 3 consume its alerts through their own gates.
+import { systemClock } from "../../clock.js";
+import { KEY_FIX } from "../../intel/scan.js";
+import { decodeWalletTrades } from "./trades.js";
+import { walletStats } from "./stats.js";
+export const TRACKER_DEFAULTS = { pollMs: 15_000, pageLimit: 25, backfillLimit: 100, keep: 500 };
+export class WalletTracker {
+    follows;
+    history;
+    clock;
+    solUsd;
+    pollMs;
+    pageLimit;
+    backfillLimit;
+    keep;
+    onAlert;
+    onChange;
+    available;
+    earlyEntry;
+    wallets = new Map();
+    alertLog = [];
+    polls = 0;
+    lastPollAt = null;
+    lastError = null;
+    running = null;
+    inflight = null;
+    n = 0;
+    constructor(opts) {
+        this.follows = opts.follows;
+        this.history = opts.history;
+        this.clock = opts.clock ?? systemClock;
+        this.solUsd = opts.solUsd ?? (() => null);
+        this.pollMs = opts.pollMs ?? TRACKER_DEFAULTS.pollMs;
+        this.pageLimit = opts.pageLimit ?? TRACKER_DEFAULTS.pageLimit;
+        this.backfillLimit = opts.backfillLimit ?? TRACKER_DEFAULTS.backfillLimit;
+        this.keep = opts.keep ?? TRACKER_DEFAULTS.keep;
+        this.onAlert = opts.onAlert ?? (() => { });
+        this.onChange = opts.onChange ?? (() => { });
+        this.available = opts.available ?? (() => ({ ok: true }));
+        this.earlyEntry = opts.earlyEntry ?? (() => undefined);
+    }
+    status() {
+        const wallets = this.follows.list().length;
+        const base = { polls: this.polls, lastPollAt: this.lastPollAt, wallets, alerts: this.alertLog.length };
+        if (!this.history)
+            return { state: 'unavailable', why: `following wallets needs a ${KEY_FIX}`, ...base };
+        const av = this.available();
+        if (!av.ok)
+            return { state: 'paused', why: av.why, ...base };
+        if (this.lastError)
+            return { state: 'degraded', why: this.lastError, ...base };
+        if (this.polls === 0)
+            return { state: 'idle', why: wallets ? 'first poll pending' : 'no wallets followed', ...base };
+        return { state: 'ok', why: null, ...base };
+    }
+    trades(addr) { return [...(this.wallets.get(addr)?.trades ?? [])].reverse(); }
+    alerts(limit = 50) { return this.alertLog.slice(-limit).reverse(); }
+    stats(addr) {
+        const w = this.wallets.get(addr);
+        return walletStats(addr, w?.trades ?? [], { solUsd: this.solUsd(), txs: w?.txs ?? 0, complete: w?.complete ?? false, earlyEntry: this.earlyEntry(addr) });
+    }
+    /** Per-wallet poll error (shown on the row), null when the last poll was clean. */
+    walletError(addr) { return this.wallets.get(addr)?.error ?? null; }
+    /** One pass over the follow list. Serialised: a second call while one runs returns the same promise. */
+    pollOnce() {
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.run().finally(() => { this.inflight = null; });
+        return this.inflight;
+    }
+    async run() {
+        const out = [];
+        if (!this.history)
+            return out;
+        const av = this.available();
+        if (!av.ok)
+            return out;
+        const live = new Set(this.follows.list().map((f) => f.addr));
+        for (const addr of [...this.wallets.keys()])
+            if (!live.has(addr))
+                this.wallets.delete(addr);
+        let anyError = null;
+        for (const f of this.follows.list()) {
+            let w = this.wallets.get(f.addr);
+            if (!w) {
+                w = { primed: false, seen: new Set(), trades: [], txs: 0, complete: false, lastSlot: 0, error: null };
+                this.wallets.set(f.addr, w);
+            }
+            try {
+                const page = await this.history.transactions(f.addr, { limit: w.primed ? this.pageLimit : this.backfillLimit, sortOrder: 'desc' });
+                const fresh = page.data.filter((tx) => { const s = tx.transaction?.signatures?.[0]; return !!s && !w.seen.has(s); });
+                for (const tx of fresh)
+                    w.seen.add(tx.transaction.signatures[0]);
+                w.txs += fresh.length;
+                const trades = decodeWalletTrades(fresh, f.addr, { solUsd: this.solUsd(), fetchedAt: page.fetchedAt });
+                if (!w.primed) {
+                    w.primed = true;
+                    w.complete = page.paginationToken === null;
+                }
+                else {
+                    const now = this.clock.now();
+                    for (const tr of trades) {
+                        if (tr.side === 'transfer')
+                            continue;
+                        const a = { id: `copy_${++this.n}`, t: now, wallet: f.addr, name: f.name, trade: tr, lagMs: tr.tKnown ? Math.max(0, now - tr.t) : null };
+                        this.alertLog.push(a);
+                        out.push(a);
+                    }
+                }
+                if (trades.length) {
+                    w.trades.push(...trades);
+                    w.trades.sort((a, b) => a.slot - b.slot || a.sig.localeCompare(b.sig));
+                    if (w.trades.length > this.keep)
+                        w.trades.splice(0, w.trades.length - this.keep);
+                    w.lastSlot = w.trades[w.trades.length - 1].slot;
+                }
+                w.error = null;
+            }
+            catch (e) {
+                w.error = e instanceof Error ? e.message : String(e);
+                anyError = `${f.addr.slice(0, 4)}…: ${w.error}`;
+            }
+        }
+        if (this.alertLog.length > 500)
+            this.alertLog.splice(0, this.alertLog.length - 500);
+        this.polls += 1;
+        this.lastPollAt = this.clock.now();
+        this.lastError = anyError;
+        for (const a of out)
+            this.onAlert(a);
+        this.onChange();
+        return out;
+    }
+    /** Poll on an interval until stop(). Never throws out of the loop; errors show in status(). */
+    start() {
+        if (this.running || !this.history)
+            return;
+        const ctl = new AbortController();
+        this.running = ctl;
+        void (async () => {
+            while (!ctl.signal.aborted) {
+                try {
+                    await this.pollOnce();
+                }
+                catch { /* reported via status() */ }
+                await this.clock.sleep(this.pollMs, ctl.signal);
+            }
+        })();
+    }
+    stop() { this.running?.abort(); this.running = null; }
+    get isRunning() { return this.running !== null; }
+}

package/dist/packages/data/src/trade/copy/trades.js

@@ -0,0 +1,87 @@
+// task-1360 Tier 1 — decode a followed wallet's swaps from its own transaction history (RawTx = the slim
+// jsonParsed shape the wallet-intel rules already use; raw transactions are never stored).
+//
+// Per transaction the wallet's net token delta per mint (pre/post token balances for accounts it owns) and its
+// net lamports delta (pre/post balances; fees and tips included) are read. One mint moved: tokens up and SOL
+// down = BUY, tokens down and SOL up = SELL, tokens moved with no SOL leg = TRANSFER (airdrop / wallet move,
+// flagged). Two or more mints moved (token→token) = both legs listed as a 'token-swap' with no SOL split, so
+// nothing is priced that cannot be priced. Wrapped SOL is the swap's own plumbing and is never a "mint" here.
+import { accountKeys } from "../../intel/rules.js";
+import { WSOL_MINT } from "../tx-decode.js";
+/** A SOL move below this is a fee/tip only, not a trade leg (0.0002 SOL). */
+export const SOL_LEG_MIN_LAMPORTS = 200_000;
+/** The wallet's net token delta per mint in one tx (raw base units), WSOL excluded. */
+export function tokenDeltasForOwner(tx, owner) {
+    const pre = new Map();
+    const post = new Map();
+    for (const b of tx.meta?.preTokenBalances ?? [])
+        if (b.owner === owner && b.mint !== WSOL_MINT)
+            pre.set(b.accountIndex, { mint: b.mint, amt: BigInt(b.uiTokenAmount.amount) });
+    for (const b of tx.meta?.postTokenBalances ?? [])
+        if (b.owner === owner && b.mint !== WSOL_MINT)
+            post.set(b.accountIndex, { mint: b.mint, amt: BigInt(b.uiTokenAmount.amount) });
+    const out = new Map();
+    for (const i of new Set([...pre.keys(), ...post.keys()])) {
+        const mint = post.get(i)?.mint ?? pre.get(i).mint;
+        const d = (post.get(i)?.amt ?? 0n) - (pre.get(i)?.amt ?? 0n);
+        if (d !== 0n)
+            out.set(mint, (out.get(mint) ?? 0n) + d);
+    }
+    return out;
+}
+/** The wallet's net lamports delta in one tx (fee included); 0 when the wallet is not an account key. */
+export function lamportsDeltaFor(tx, owner) {
+    const keys = accountKeys(tx);
+    const i = keys.findIndex((k) => k.pubkey === owner);
+    if (i < 0)
+        return 0;
+    const pre = tx.meta?.preBalances ?? [], post = tx.meta?.postBalances ?? [];
+    return (post[i] ?? 0) - (pre[i] ?? 0);
+}
+/** Decode one transaction into the wallet's trades (0, 1 or several legs). Pure; never throws on odd input. */
+export function decodeTx(tx, wallet, opts = {}) {
+    const sig = tx.transaction?.signatures?.[0] ?? '';
+    const deltas = tokenDeltasForOwner(tx, wallet);
+    if (deltas.size === 0)
+        return [];
+    const lamports = lamportsDeltaFor(tx, wallet);
+    const tKnown = typeof tx.blockTime === 'number' && tx.blockTime > 0;
+    const t = tKnown ? tx.blockTime * 1000 : (opts.fetchedAt ?? 0);
+    const solUsd = typeof opts.solUsd === 'number' && opts.solUsd > 0 ? opts.solUsd : null;
+    const out = [];
+    const multi = deltas.size > 1;
+    for (const [mint, delta] of deltas) {
+        const solLeg = !multi && Math.abs(lamports) >= SOL_LEG_MIN_LAMPORTS;
+        let side;
+        let note = null;
+        if (multi) {
+            side = delta > 0n ? 'buy' : 'sell';
+            note = 'token-swap';
+        }
+        else if (delta > 0n && solLeg && lamports < 0)
+            side = 'buy';
+        else if (delta < 0n && solLeg && lamports > 0)
+            side = 'sell';
+        else if (solLeg) {
+            side = 'transfer';
+            note = 'lp-like';
+        } // tokens AND SOL moved the same way: LP add/remove or a payout, not a swap
+        else {
+            side = 'transfer';
+            if (delta > 0n)
+                note = 'airdrop';
+        }
+        const solDelta = !multi && side !== 'transfer' ? lamports / 1e9 : null;
+        const usd = solDelta !== null && solUsd !== null ? Math.abs(solDelta) * solUsd : null;
+        out.push({ wallet, sig, slot: tx.slot, t, tKnown, mint, side, tokenDelta: delta.toString(), lamportsDelta: lamports, solDelta, usd, solUsdAt: solDelta !== null ? solUsd : null, note });
+    }
+    return out;
+}
+/** Decode a history page (any order) into trades sorted oldest first. */
+export function decodeWalletTrades(txs, wallet, opts = {}) {
+    const out = [];
+    for (const tx of txs)
+        out.push(...decodeTx(tx, wallet, opts));
+    out.sort((a, b) => a.slot - b.slot || a.sig.localeCompare(b.sig));
+    return out;
+}

package/dist/packages/data/src/trade/copy/types.js

@@ -0,0 +1,6 @@
+// task-1360 — COPY TRADING (staged) shared types. Personal tool for the user's OWN wallet only: no custody, no
+// third parties, no fees, no hosted/pooled copy, no curated leader lists (product decision 2026-10-06; ROADMAP legal
+// flags; research/wallet-intel design §6). Stage 1 = follow a wallet + alerts, stage 2 = one-key mirror PROPOSAL,
+// stage 3 = capped auto-mirror inside an armed copy mandate. Nothing in this module signs, holds a key, or reaches
+// mainnet: it decodes public history, keeps local notes, and hands PROPOSALS to the plan engine.
+export {};