dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/trade/plans/plan.js

@@ -0,0 +1,179 @@
+// task-1355 — ORDER PLAN schema, validation, canonical hash, read-back (SPEC §6.13.1).
+//
+// A plan is a PROPOSAL until a confirmation proof arms it. Voice, Claude, popups and batch builders can
+// only produce the input shape below; nothing here carries an `armed`/`status`/`caps` field from the
+// proposer — those are stripped, never trusted. Amounts are USD (entry) and fractions of the ORIGINAL
+// filled position (exits). Market-cap triggers are stored WITH the supply snapshot they were proposed
+// against, so the read-back can say "300k = $0.0003 at 1.00B supply" and a later supply change is visible.
+//
+// No signing, no wallet, no network. `node:crypto` is used only for the SHA-256 plan hash.
+// Ported from the task-1292 reference simulation (research/task-1292/sim/plan.mjs), typed and frozen.
+import { createHash } from 'node:crypto';
+const MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+export const PLAN_SCHEMA_VERSION = 1;
+/** Which fields are "material": a change to any of them changes the hash and voids every confirmation. */
+export const MATERIAL_FIELDS = [
+    'v', 'mint', 'decimals', 'side', 'sizeUsd', 'entry', 'exits', 'moonBagFraction', 'stop',
+    'slippageBps', 'maxPriceImpactPct', 'supplyAtProposal', 'expiresAt', 'chunkUsd',
+];
+export class PlanError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'PlanError';
+        this.reason = reason;
+    }
+}
+function num(x, name, { min = 0, max = Infinity, integer = false } = {}) {
+    if (typeof x !== 'number' || !Number.isFinite(x))
+        throw new PlanError('bad-request', `${name} must be a finite number`);
+    if (x < min || x > max)
+        throw new PlanError('bad-request', `${name} must be in [${min}, ${max}]`);
+    if (integer && !Number.isInteger(x))
+        throw new PlanError('bad-request', `${name} must be an integer`);
+    return x;
+}
+function trigger(t, name) {
+    if (t === null || typeof t !== 'object')
+        throw new PlanError('bad-request', `${name} must be an object`);
+    const kind = t.kind;
+    if (kind === 'immediate')
+        return { kind: 'immediate' };
+    if (kind !== 'mc-below' && kind !== 'mc-above' && kind !== 'price-below' && kind !== 'price-above') {
+        throw new PlanError('bad-request', `${name}.kind unknown`);
+    }
+    return { kind, value: num(t.value, `${name}.value`, { min: 1e-12 }) };
+}
+/** Sanitize untrusted display text (token symbol / name): printable ASCII, short. Never used in policy. */
+export function displayText(s, max = 16) {
+    return typeof s === 'string' ? s.replace(/[^\x20-\x7e]/g, '?').slice(0, max) : '';
+}
+/**
+ * Validate an untrusted proposal input and return a frozen plan (status 'proposed'). `ctx` is what the
+ * TUI knows and the proposer does not control: the supply snapshot, the clock, and the provenance.
+ */
+export function proposePlan(input, ctx) {
+    if (input === null || typeof input !== 'object')
+        throw new PlanError('bad-request', 'plan must be an object');
+    const x = input;
+    if (typeof x.mint !== 'string' || !MINT_RE.test(x.mint))
+        throw new PlanError('bad-request', 'mint must be a base58 address');
+    const side = x.side === 'sell' ? 'sell' : x.side === 'buy' ? 'buy' : null;
+    if (!side)
+        throw new PlanError('bad-request', 'side must be buy or sell');
+    const decimals = num(x.decimals, 'decimals', { min: 0, max: 18, integer: true });
+    const sizeUsd = num(x.sizeUsd, 'sizeUsd', { min: 0.01, max: 1e7 });
+    const entry = trigger(x.entry ?? { kind: 'immediate' }, 'entry');
+    const exitsIn = Array.isArray(x.exits) ? x.exits : [];
+    if (exitsIn.length > 8)
+        throw new PlanError('bad-request', 'at most 8 exit legs');
+    let sum = 0;
+    const cleanExits = exitsIn.map((e, i) => {
+        const at = trigger(e?.at, `exits[${i}].at`);
+        if (at.kind !== 'mc-above' && at.kind !== 'price-above')
+            throw new PlanError('bad-request', `exits[${i}] must be an above-trigger (take profit)`);
+        const fraction = num(e?.fraction, `exits[${i}].fraction`, { min: 0.01, max: 1 });
+        sum += fraction;
+        return { at, fraction };
+    });
+    // exits must be ascending so the ladder is unambiguous ("sell half at 600k, a quarter at 1.2M")
+    for (let i = 1; i < cleanExits.length; i++) {
+        const cur = cleanExits[i].at;
+        const prev = cleanExits[i - 1].at;
+        const curVal = cur.kind === 'immediate' ? 0 : cur.value;
+        const prevVal = prev.kind === 'immediate' ? 0 : prev.value;
+        if (curVal <= prevVal)
+            throw new PlanError('bad-request', 'exit legs must be ascending');
+    }
+    if (sum > 1 + 1e-9)
+        throw new PlanError('bad-request', 'exit fractions sum above 100%');
+    const moonBagFraction = Math.round((1 - sum) * 1e6) / 1e6;
+    const stop = x.stop == null ? null : trigger(x.stop, 'stop');
+    if (stop && stop.kind !== 'mc-below' && stop.kind !== 'price-below')
+        throw new PlanError('bad-request', 'stop must be a below-trigger');
+    if (stop && entry.kind === 'mc-below' && stop.kind === 'mc-below' && stop.value >= entry.value)
+        throw new PlanError('bad-request', 'stop must be below the entry');
+    const slippageBps = num(x.slippageBps ?? 300, 'slippageBps', { min: 0, max: 1000, integer: true });
+    const maxPriceImpactPct = num(x.maxPriceImpactPct ?? 3, 'maxPriceImpactPct', { min: 0.01, max: 3 });
+    const ttlMs = num(x.ttlMs ?? 4 * 3600_000, 'ttlMs', { min: 10_000, max: 7 * 86_400_000, integer: true });
+    const chunkUsd = x.chunkUsd == null ? null : num(x.chunkUsd, 'chunkUsd', { min: 1 });
+    if (typeof ctx?.supply !== 'number' || !(ctx.supply > 0))
+        throw new PlanError('bad-request', 'ctx.supply (token supply snapshot) is required');
+    if (!ctx.clock)
+        throw new PlanError('bad-request', 'ctx.clock is required');
+    const createdAt = ctx.clock.now();
+    const plan = {
+        v: PLAN_SCHEMA_VERSION,
+        id: ctx.id ?? `plan_${createdAt.toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+        mint: x.mint, symbol: displayText(x.symbol) || x.mint.slice(0, 4), decimals, side, sizeUsd,
+        entry, exits: cleanExits, moonBagFraction, stop, slippageBps, maxPriceImpactPct,
+        supplyAtProposal: ctx.supply, chunkUsd,
+        createdAt, expiresAt: createdAt + ttlMs,
+        // provenance (NOT material; the proposer cannot influence policy through it)
+        source: { by: ctx.by ?? 'user', ref: typeof ctx.ref === 'string' ? ctx.ref.slice(0, 80) : null, batchId: ctx.batchId ?? null },
+        status: 'proposed',
+        hash: '',
+    };
+    plan.hash = planHash(plan);
+    return Object.freeze(plan);
+}
+/** Canonical JSON of the material fields only (sorted keys, fixed order). */
+export function canonicalPlan(plan) {
+    const pick = {};
+    const rec = plan;
+    for (const k of MATERIAL_FIELDS)
+        pick[k] = rec[k] === undefined ? null : rec[k];
+    return JSON.stringify(pick, (_k, v) => (v && typeof v === 'object' && !Array.isArray(v))
+        ? Object.fromEntries(Object.keys(v).sort().map((kk) => [kk, v[kk]]))
+        : v);
+}
+export function planHash(plan) {
+    return createHash('sha256').update(canonicalPlan(plan)).digest('hex');
+}
+/** Return a NEW plan with a material field changed (a mutated plan is a different plan: new hash, new status). */
+export function amendPlan(plan, patch, ctx) {
+    const input = {
+        mint: plan.mint, symbol: plan.symbol, decimals: plan.decimals, side: plan.side, sizeUsd: plan.sizeUsd,
+        entry: plan.entry, exits: plan.exits, stop: plan.stop, slippageBps: plan.slippageBps,
+        maxPriceImpactPct: plan.maxPriceImpactPct, ttlMs: plan.expiresAt - plan.createdAt, chunkUsd: plan.chunkUsd,
+        ...patch,
+    };
+    return proposePlan(input, {
+        supply: plan.supplyAtProposal, clock: ctx.clock,
+        by: ctx.by ?? plan.source.by, ref: ctx.ref ?? plan.source.ref, batchId: plan.source.batchId,
+    });
+}
+export function fmtUsd(n) {
+    if (n >= 1e9)
+        return `$${(n / 1e9).toFixed(2)}B`;
+    if (n >= 1e6)
+        return `$${(n / 1e6).toFixed(2)}M`;
+    if (n >= 1e3)
+        return `$${(n / 1e3).toFixed(0)}k`;
+    return `$${n.toFixed(2)}`;
+}
+/** The price a market-cap trigger means at the proposal's supply snapshot. */
+export function priceForMc(mcUsd, supply) { return mcUsd / supply; }
+function describeTrigger(t, supply) {
+    switch (t.kind) {
+        case 'immediate': return 'now';
+        case 'mc-below': return `if market cap dips to ${fmtUsd(t.value)} (price $${priceForMc(t.value, supply).toPrecision(3)} at ${(supply / 1e9).toFixed(2)}B supply)`;
+        case 'mc-above': return `at ${fmtUsd(t.value)} market cap`;
+        case 'price-below': return `if price dips to $${t.value}`;
+        case 'price-above': return `at $${t.value}`;
+        default: return '?';
+    }
+}
+/** The spoken/rendered read-back. The challenge code is appended by the confirm gate, not here. */
+export function readBack(plan) {
+    const s = plan.supplyAtProposal;
+    const parts = [`${plan.side === 'buy' ? 'Buy' : 'Sell'} ${fmtUsd(plan.sizeUsd)} of ${plan.symbol} (mint ${plan.mint.slice(0, 4)}…${plan.mint.slice(-4)}) ${describeTrigger(plan.entry, s)}`];
+    for (const e of plan.exits)
+        parts.push(`sell ${Math.round(e.fraction * 100)}% ${describeTrigger(e.at, s)}`);
+    if (plan.moonBagFraction > 0)
+        parts.push(`keep ${Math.round(plan.moonBagFraction * 100)}% as a moon bag`);
+    if (plan.stop)
+        parts.push(`stop ${describeTrigger(plan.stop, s).replace(/^if /, '')}`);
+    parts.push(`slippage ${(plan.slippageBps / 100).toFixed(1)}%`, `expires in ${Math.round((plan.expiresAt - plan.createdAt) / 60_000)} min`);
+    return parts.join('; ') + '.';
+}

package/dist/packages/data/src/trade/plans/service.js

@@ -0,0 +1,168 @@
+// task-1355 — PlanService: the app-facing facade over the plan engine.
+//
+// Owns the engine + hash-chained journal (persisted to ~/.dexterm/plans.journal) + the paper fire path +
+// the confirm gate + the gate-off settings. It adds persistence (recover on load), untrusted-string
+// parsing for typed commands (`mc-below:300k`, `mc-above:600k:50%`), and list/describe views the CLI,
+// TUI and popup render. It adds NO new way to arm or sign: arming still requires a signer-issued
+// keypress/Phantom gesture proof routed through the engine; voice/agents can only propose.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { systemClock } from "../../clock.js";
+import { Journal } from "./journal.js";
+import { ConfirmGate, Settings, HOLD_MS } from "./confirm.js";
+import { PlanEngine } from "./engine.js";
+import { PaperPlanExecutor } from "./executor-paper.js";
+import { ConfirmError } from "./confirm.js";
+import { PolicyRefusal } from "./engine.js";
+import { readBack, fmtUsd, PlanError } from "./plan.js";
+/** Where the plan/mandate journal (audit log + recovery source) lives, shared by every dexterm process. */
+export function defaultPlansJournalPath(env = process.env) {
+    const home = env.DEXTERM_HOME && env.DEXTERM_HOME.length ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+    return join(home, 'plans.journal');
+}
+/** Parse a memecoin-style amount: 300k / 1.2m / 2b / 600000. */
+export function parseAmount(s) {
+    const m = /^\s*\$?([0-9]*\.?[0-9]+)\s*([kmb])?\s*$/i.exec(s);
+    if (!m)
+        throw new PlanError('bad-request', `cannot parse amount "${s}"`);
+    const mult = m[2] ? { k: 1e3, m: 1e6, b: 1e9 }[m[2].toLowerCase()] : 1;
+    return Number(m[1]) * mult;
+}
+/** Parse a trigger spec: `immediate` | `mc-below:300k` | `price-above:0.0005`. */
+export function parseTrigger(s) {
+    const t = s.trim();
+    if (t === 'immediate' || t === 'now')
+        return { kind: 'immediate' };
+    const m = /^(mc-below|mc-above|price-below|price-above):(.+)$/.exec(t);
+    if (!m)
+        throw new PlanError('bad-request', `cannot parse trigger "${s}" (expected kind:value, e.g. mc-below:300k)`);
+    return { kind: m[1], value: parseAmount(m[2]) };
+}
+/** Parse an exit spec: `mc-above:600k:0.5` or `mc-above:600k:50%`. */
+export function parseExit(s) {
+    const parts = s.split(':');
+    if (parts.length < 3)
+        throw new PlanError('bad-request', `cannot parse exit "${s}" (expected kind:value:fraction, e.g. mc-above:600k:50%)`);
+    const fracStr = parts[parts.length - 1].trim();
+    const at = parseTrigger(parts.slice(0, -1).join(':'));
+    const fraction = fracStr.endsWith('%') ? Number(fracStr.slice(0, -1)) / 100 : Number(fracStr);
+    if (!(fraction > 0 && fraction <= 1))
+        throw new PlanError('bad-request', `exit fraction "${fracStr}" must be in (0, 1] or a percent`);
+    return { at, fraction };
+}
+export class PlanService {
+    clock;
+    journal;
+    settings;
+    gate;
+    engine;
+    paper;
+    constructor(opts = {}) {
+        this.clock = opts.clock ?? systemClock;
+        const path = opts.journalPath ?? null;
+        this.journal = new Journal({ path, clock: this.clock });
+        this.settings = new Settings(this.clock, this.journal);
+        this.gate = new ConfirmGate({ clock: this.clock, journal: this.journal, settings: this.settings, rng: opts.rng });
+        this.paper = opts.executor ?? new PaperPlanExecutor({ clock: this.clock, solUsd: opts.solUsd });
+        const deps = { clock: this.clock, journal: this.journal, executor: this.paper, gate: this.gate, safety: opts.safety, priceMaxAgeMs: opts.priceMaxAgeMs, debounceTicks: opts.debounceTicks };
+        // Recover from an existing journal (replay + settle in-flight) or start fresh. The fire path always starts
+        // PAPER (task-1363): live is a per-run keypress opt-in, never recovered from the journal.
+        this.engine = path && existsSync(path) ? PlanEngine.recover(deps) : new PlanEngine(deps);
+    }
+    /** The executor the engine fires through right now (paper by default; the live adapter after useLive). */
+    get executor() { return this.engine.executor; }
+    /** 'paper' unless a live executor is installed. Surfaces that cannot prove 'paper' must render LIVE. */
+    mode() { return this.engine.executor.kind === 'live' ? 'live' : 'paper'; }
+    // ── the fire path (task-1363). Switching to LIVE is a physical keypress on the plans screen (never voice,
+    // an agent, a pipe or the popup): the gesture is required here AND the signer only fills from a fast wallet
+    // that was itself created by a TTY keypress. A switch while plans are armed/filled would strand their legs on
+    // the other executor's ledger, so both directions refuse until those plans are cancelled or finished. ──
+    useLive(executor, gesture) {
+        if (gesture?.gesture !== 'keypress')
+            throw new ConfirmError('live-needs-keypress', 'switching plan fills to LIVE needs a physical keypress');
+        if (executor.kind !== 'live')
+            throw new PlanError('bad-request', 'useLive needs a live executor');
+        const open = this.engine.openPlans();
+        if (open.length)
+            throw new PolicyRefusal('open-plans', `cancel or finish ${open.length} open plan(s) before switching the fire path`);
+        this.engine.replaceExecutor(executor);
+        this.journal.append('settings.executor', { data: { kind: 'live', network: 'devnet', by: 'keypress', label: executor.describe?.() ?? 'live' } });
+    }
+    usePaper() {
+        if (this.engine.executor === this.paper)
+            return;
+        const open = this.engine.openPlans();
+        if (open.length)
+            throw new PolicyRefusal('open-plans', `cancel or finish ${open.length} open plan(s) before switching the fire path`);
+        this.engine.replaceExecutor(this.paper);
+        this.journal.append('settings.executor', { data: { kind: 'paper' } });
+    }
+    // ── proposals (voice/claude/user/batch all land here; a proposal is inert until armed) ──
+    propose(input, ctx) {
+        return this.engine.propose(input, { supply: ctx.supply, by: ctx.by ?? 'user', ref: ctx.ref ?? null });
+    }
+    readBack(planId) { const p = this.engine.plan(planId); if (!p)
+        throw new PlanError('unknown-plan', 'no such plan'); return readBack(p); }
+    // ── arming (keypress/Phantom only; the CLI/TUI must supply a real gesture) ──
+    challenge(planId, tier = 'keypress') { return this.engine.challenge(planId, tier); }
+    confirm(challengeId, evidence) { return this.engine.confirm(challengeId, evidence); }
+    armPlan(planId, proof, mandateId) { return this.engine.armPlan(planId, proof, mandateId); }
+    cancelPlan(planId, reason = 'user') { return this.engine.cancelPlan(planId, reason); }
+    /** Arm a plan from a physical keypress gesture the host already captured (hold >= HOLD_MS). */
+    armPlanByKeypress(planId, mandateId, holdMs = HOLD_MS + 50) {
+        const ch = this.challenge(planId, 'keypress');
+        const proof = this.confirm(ch.id, { kind: 'keypress', holdMs });
+        return this.armPlan(planId, proof, mandateId);
+    }
+    // ── mandates (drafted by anyone; armed by keypress/Phantom only) ──
+    draftMandate(input) { return this.engine.draftMandate(input); }
+    armMandateByKeypress(mandateId, gesture = 'keypress') {
+        return this.engine.armMandate(mandateId, this.engine.issueMandateProof(mandateId, gesture));
+    }
+    revokeMandate(mandateId, reason = 'user') { this.engine.revokeMandate(mandateId, reason); }
+    // ── kill switch ──
+    panic(reason = 'panic key') { this.engine.panic(reason); }
+    // ── the "less safe" hands-free opt-in (Tier 4). The keypress gate is ON by default: voice/agents can only
+    // ever leave an inert proposal, and arming is a physical gesture. Turning the gate OFF enables hands-free
+    // (spoken) confirmation; it is accepted ONLY by a real keypress on the risk popup, journaled, auto-expires
+    // in 24h (RISK_ACCEPT_TTL_MS), and is reversible at any time. These thin methods keep every surface off the
+    // Settings object so the keypress-only rule lives in exactly one place. ──
+    riskStatus() {
+        const r = this.settings.risk;
+        return { gateOff: this.settings.gateOff, acceptedAt: r?.acceptedAt ?? null, expiresAt: r?.expiresAt ?? null, active: this.settings.handsFreeAllowed(this.clock.now()) };
+    }
+    acceptRisk(gesture) { this.settings.acceptRiskPopup(gesture); }
+    restoreGate() { this.settings.restoreGate(); }
+    // ── ticks (untrusted price hints; the engine re-confirms via its own quote) ──
+    tick(t) { this.engine.tick(t); }
+    // ── views ──
+    listPlans() {
+        return [...this.engine.recs.values()].map((r) => ({
+            id: r.plan.id, mint: r.plan.mint, symbol: r.plan.symbol, side: r.plan.side, sizeUsd: r.plan.sizeUsd,
+            status: r.status, mandateId: r.mandateId, tier: r.tier, readBack: readBack(r.plan), paused: r.paused !== null,
+        }));
+    }
+    listMandates() {
+        return [...this.engine.mandates.values()].map((x) => {
+            const L = this.engine.ledger(x.m.id);
+            return {
+                id: x.m.id, status: x.m.status, wallet: x.m.wallet, totalUsd: x.m.budget.totalUsd, perTradeUsd: x.m.budget.perTradeUsd,
+                perCoinUsd: x.m.budget.perCoinUsd, maxTier: x.m.maxTier, reservedUsd: L.reservedUsd, spentUsd: L.spentUsd,
+                realizedUsd: L.realizedUsd, lossUsd: L.lossUsd, expiresAt: x.m.expiresAt,
+            };
+        });
+    }
+    // ── audit log ──
+    verifyJournal() { return this.journal.verify(); }
+    exportJournal() { return this.journal.events.map((e) => JSON.stringify(e)).join('\n'); }
+    summary(planId) { return this.engine.summary(planId); }
+    position(planId) { return this.engine.position(planId); }
+    ledger(mandateId) { return this.engine.ledger(mandateId); }
+}
+/** One-line label for a plan status (CLI/TUI). */
+export function planStatusLabel(row) {
+    const tier = row.tier ? ` · ${row.tier}` : '';
+    const paused = row.paused ? ' · PAUSED' : '';
+    return `${row.symbol} ${fmtUsd(row.sizeUsd)} ${row.side} — ${row.status}${tier}${paused}`;
+}

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

@@ -0,0 +1,6 @@
+// task-1355 — shared types for the order-plan + mandate engine (SPEC §6.13).
+//
+// These are the money-safe object shapes. Material plan fields are hashed (SHA-256 over canonical
+// JSON); any change to a material field is a new plan with a new hash and voids every outstanding
+// confirmation. Display/provenance fields are never read by policy.
+export {};

package/dist/packages/data/src/trade/rpc-exec.js

@@ -0,0 +1,229 @@
+// dexterm T1 — the ONLY place that can submit a transaction (SPEC §6.1 steps 2/5). Kept out of the
+// read-only `sources/solana-rpc.ts` (which refuses non-read methods) so the broadcast path is small,
+// explicit and auditable. It simulates against the user's RPC, submits an already-signed transaction
+// (dexterm never signs), and confirms it. It holds no keys.
+//
+// DEVNET is the default RPC. Mainnet is only used when the caps allow it (--mainnet).
+import { systemClock } from "../clock.js";
+export const DEVNET_RPC = 'https://api.devnet.solana.com';
+export const MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
+/**
+ * Hostnames that are devnet/testnet by construction. EXACT matches only (round 2, re-verify MEDIUM #5):
+ * the old substring test took `https://mainnet.helius-rpc.com/?api-key=devnet-team-key` for devnet and
+ * dropped every USD cap. Any other host — mainnet, a vendor URL, localhost, an unparseable string — is
+ * classified MAINNET so the caps apply by default. A deployment that really runs a private devnet can
+ * say so explicitly via `TradeRpc({ network: 'devnet' })`.
+ */
+export const DEVNET_HOSTS = new Set([
+    'api.devnet.solana.com',
+    'api.testnet.solana.com',
+    'devnet.helius-rpc.com',
+]);
+/**
+ * DEFECT 4 / round 2: classify a trade from the RPC endpoint it will actually talk to, NOT from a
+ * free-text "network" label and NOT from a substring. The URL is PARSED and only an exact known
+ * devnet/testnet hostname is devnet. Everything else (including an empty or malformed URL) is mainnet.
+ */
+export function rpcNetwork(url, explicit) {
+    if (explicit === 'devnet' || explicit === 'mainnet')
+        return explicit;
+    if (typeof url !== 'string' || url.length === 0)
+        return 'mainnet';
+    let host;
+    try {
+        const u = new URL(url);
+        if (u.protocol !== 'https:' && u.protocol !== 'http:' && u.protocol !== 'wss:' && u.protocol !== 'ws:')
+            return 'mainnet';
+        host = u.hostname.toLowerCase();
+    }
+    catch {
+        return 'mainnet';
+    }
+    return DEVNET_HOSTS.has(host) ? 'devnet' : 'mainnet';
+}
+/**
+ * Only these JSON-RPC methods are reachable; `simulateTransaction` is the gate before any submit.
+ * task-1337 adds the two READ methods the token-balance diff needs (the wallet's token accounts before
+ * the trade, and address-lookup-table contents); still nothing that moves funds besides `sendTransaction`.
+ */
+const ALLOWED = new Set(['simulateTransaction', 'sendTransaction', 'getLatestBlockhash', 'getSignatureStatuses', 'getBalance', 'getMultipleAccounts', 'getTokenAccountsByOwner', 'requestAirdrop']);
+/** The node's `[base64, 'base64']` (or a bare base64 string) account data → bytes; null when absent/odd. */
+export function decodeAccountData(data) {
+    const s = Array.isArray(data) ? data[0] : data;
+    if (typeof s !== 'string')
+        return null;
+    if (Array.isArray(data) && data[1] !== undefined && data[1] !== 'base64')
+        return null;
+    return Buffer.from(s, 'base64');
+}
+/**
+ * The node ANSWERED with a JSON-RPC error. For `sendTransaction` this is a DEFINITE pre-broadcast
+ * rejection (preflight failure, bad blockhash, malformed tx): nothing reached the network, so the
+ * executor may refund the daily reservation. Any other failure (timeout, reset, 5xx) is a transport
+ * error whose outcome is UNKNOWN and must not be refunded (round 2, re-verify MEDIUM #4).
+ */
+export class RpcRejectedError extends Error {
+    method;
+    code;
+    data;
+    constructor(method, message, code, data) {
+        super(`rpc ${method}: ${message}`);
+        this.name = 'RpcRejectedError';
+        this.method = method;
+        this.code = code;
+        this.data = data;
+    }
+}
+export class TradeRpc {
+    http;
+    url;
+    /** The classified network of `url` (or the explicit config). The executor caps by THIS. */
+    network;
+    meta = { source: 'solana-rpc', bucket: 'solana-rpc' };
+    clock;
+    constructor(http, opts = {}) {
+        this.http = http;
+        this.url = opts.url ?? DEVNET_RPC;
+        this.network = rpcNetwork(this.url, opts.network ?? null);
+        this.clock = opts.clock ?? systemClock;
+    }
+    async call(method, params) {
+        if (!ALLOWED.has(method))
+            throw new Error(`refusing RPC method ${method}`);
+        const r = await this.http.postJson(this.url, { jsonrpc: '2.0', id: 1, method, params }, this.meta);
+        if (r.data.error)
+            throw new RpcRejectedError(method, r.data.error.message ?? 'error', typeof r.data.error.code === 'number' ? r.data.error.code : null, r.data.error.data);
+        if (r.data.result === undefined)
+            throw new Error(`rpc ${method}: no result`);
+        return r.data.result;
+    }
+    /**
+     * Simulate a (possibly unsigned) base64 transaction with `replaceRecentBlockhash` + `sigVerify:false`
+     * so the plan can be checked before the user signs. A non-null `err` means the trade must be refused.
+     * `opts.accounts` asks the node for the POST-simulation state of those addresses (their lamports are
+     * what the executor compares against the pre-balance to learn how much SOL the tx really moves).
+     */
+    async simulate(txBase64, opts = {}) {
+        const cfg = { encoding: 'base64', replaceRecentBlockhash: true, sigVerify: false, commitment: 'confirmed' };
+        const want = opts.accounts ?? [];
+        if (want.length > 0)
+            cfg.accounts = { encoding: 'base64', addresses: want };
+        const res = await this.call('simulateTransaction', [txBase64, cfg]);
+        const v = res.value;
+        let accounts = null;
+        let accountsData = null;
+        if (want.length > 0) {
+            accounts = want.map((_, i) => {
+                const a = v.accounts?.[i];
+                return a && typeof a.lamports === 'number' && Number.isFinite(a.lamports) ? BigInt(Math.trunc(a.lamports)) : null;
+            });
+            if (Array.isArray(v.accounts))
+                accountsData = want.map((_, i) => decodeAccountData(v.accounts?.[i]?.data));
+        }
+        return { ok: v.err === null || v.err === undefined, err: v.err ?? null, logs: v.logs ?? null, unitsConsumed: typeof v.unitsConsumed === 'number' ? v.unitsConsumed : null, accounts, accountsData };
+    }
+    /**
+     * task-1363: devnet faucet (`requestAirdrop`) for the capped fast wallet — refused by classification on any
+     * non-devnet endpoint (mainnet nodes reject it anyway). Returns the airdrop signature.
+     */
+    async airdrop(pubkey, lamports) {
+        if (this.network !== 'devnet')
+            throw new Error('requestAirdrop runs only against a devnet RPC endpoint');
+        if (!(lamports > 0n))
+            throw new Error('airdrop needs a positive lamport amount');
+        return this.call('requestAirdrop', [pubkey, Number(lamports)]);
+    }
+    /** Lamport balance of an account (read-only `getBalance`). Used for the pre-simulation balance. */
+    async balance(pubkey) {
+        const res = await this.call('getBalance', [pubkey, { commitment: 'confirmed' }]);
+        if (typeof res.value !== 'number' || !Number.isFinite(res.value))
+            throw new Error('rpc getBalance: bad value');
+        return BigInt(Math.trunc(res.value));
+    }
+    /**
+     * task-1337: read-only snapshots of several accounts (`getMultipleAccounts`, base64). null per entry
+     * when the account does not exist. Used for the token-account PRE-balances the simulation diff
+     * compares against, and to read address-lookup tables so every account a v0 transaction can touch is
+     * known. Throws on a malformed answer (the executor fails closed).
+     */
+    async accountsInfo(pubkeys) {
+        if (pubkeys.length === 0)
+            return [];
+        const out = [];
+        for (let i = 0; i < pubkeys.length; i += 100) { // the node caps one call at 100 accounts
+            const chunk = pubkeys.slice(i, i + 100);
+            const res = await this.call('getMultipleAccounts', [chunk, { encoding: 'base64', commitment: 'confirmed' }]);
+            if (!Array.isArray(res.value) || res.value.length !== chunk.length)
+                throw new Error('rpc getMultipleAccounts: bad value');
+            for (const a of res.value) {
+                if (a === null) {
+                    out.push(null);
+                    continue;
+                }
+                const data = decodeAccountData(a.data);
+                if (typeof a.lamports !== 'number' || typeof a.owner !== 'string' || data === null)
+                    throw new Error('rpc getMultipleAccounts: malformed account');
+                out.push({ lamports: BigInt(Math.trunc(a.lamports)), owner: a.owner, data });
+            }
+        }
+        return out;
+    }
+    /**
+     * task-1337: every token account `owner` holds under `programId` (`getTokenAccountsByOwner`, base64).
+     * These are the accounts a hostile route could drain; the executor watches their balances through the
+     * simulation. Throws on a malformed answer (fail closed).
+     */
+    async tokenAccountsByOwner(owner, programId) {
+        const res = await this.call('getTokenAccountsByOwner', [owner, { programId }, { encoding: 'base64', commitment: 'confirmed' }]);
+        if (!Array.isArray(res.value))
+            throw new Error('rpc getTokenAccountsByOwner: bad value');
+        return res.value.map((e) => {
+            const data = decodeAccountData(e.account?.data);
+            if (typeof e.pubkey !== 'string' || data === null)
+                throw new Error('rpc getTokenAccountsByOwner: malformed entry');
+            return { pubkey: e.pubkey, data };
+        });
+    }
+    /** A recent blockhash for a transaction dexterm builds itself (the devnet probe). Read-only. */
+    async latestBlockhash() {
+        const res = await this.call('getLatestBlockhash', [{ commitment: 'confirmed' }]);
+        const v = res.value;
+        if (!v || typeof v.blockhash !== 'string' || !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(v.blockhash))
+            throw new Error('rpc getLatestBlockhash: bad value');
+        return { blockhash: v.blockhash, lastValidBlockHeight: typeof v.lastValidBlockHeight === 'number' ? v.lastValidBlockHeight : 0 };
+    }
+    /** Broadcast an already-signed base64 transaction. Returns the signature. */
+    async submit(signedTxBase64) {
+        return this.call('sendTransaction', [signedTxBase64, { encoding: 'base64', skipPreflight: false, maxRetries: 3, preflightCommitment: 'confirmed' }]);
+    }
+    /**
+     * One status lookup for a signature we already know (from the signed bytes). Returns null when the
+     * node has not seen it. Used after a transport error on submit to learn whether the send landed.
+     */
+    async signatureStatus(signature) {
+        const res = await this.call('getSignatureStatuses', [[signature], { searchTransactionHistory: true }]);
+        const st = res.value?.[0];
+        if (!st)
+            return null;
+        return { confirmationStatus: st.confirmationStatus ?? null, err: st.err ?? null, slot: st.slot ?? null };
+    }
+    /** Poll signature status until confirmed/finalized, a chain error, or the bound elapses. */
+    async confirm(signature, opts = {}) {
+        const deadline = this.clock.now() + (opts.timeoutMs ?? 60_000);
+        const interval = opts.intervalMs ?? 2_000;
+        for (;;) {
+            const res = await this.call('getSignatureStatuses', [[signature], { searchTransactionHistory: false }]);
+            const st = res.value[0];
+            if (st) {
+                if (st.err)
+                    return { signature, confirmed: false, err: st.err, slot: st.slot ?? null };
+                if (st.confirmationStatus === 'confirmed' || st.confirmationStatus === 'finalized') {
+                    return { signature, confirmed: true, err: null, slot: st.slot ?? null };
+                }
+            }
+            if (this.clock.now() >= deadline)
+                return { signature, confirmed: false, err: 'confirmation timed out', slot: null };
+            await this.clock.sleep(interval);
+        }
+    }
+}