dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/trade/sol-usd.js

@@ -0,0 +1,86 @@
+// dexterm T1 — the SOL/USD price the signer prices a trade with (task-1310 round 2, HIGH #2).
+//
+// The USD caps are only as good as the SOL/USD number behind them: a stale or absurd price (say
+// $0.0001) makes a 100 SOL trade look like a cent. The executor therefore never takes a bare number.
+// It takes timestamped SAMPLES from named sources and resolves them here, refusing when:
+//   * a sample is older than MAX_AGE_MS (60 s) or dated in the future;
+//   * a price is outside the plausibility band [MIN_PLAUSIBLE_USD, MAX_PLAUSIBLE_USD] ($1–$10,000);
+//   * on MAINNET, fewer than two INDEPENDENT non-Jupiter sources agree within AGREE_PCT (3%). Jupiter
+//     is the swap vendor, so its price API is not an independent check of a Jupiter route and can
+//     never be the only source.
+// The resolved price is the HIGHEST of the agreeing sources: that over-states the notional slightly,
+// which is the conservative direction for a cap. Pure; no I/O.
+export const SOL_USD_MAX_AGE_MS = 60_000;
+export const SOL_USD_MIN_PLAUSIBLE = 1;
+export const SOL_USD_MAX_PLAUSIBLE = 10_000;
+export const SOL_USD_AGREE_PCT = 3;
+/** Sources that are the swap vendor itself (or a re-export of it) and so count as dependent. */
+export const SOL_USD_DEPENDENT_SOURCES = new Set(['jupiter', 'jupiter-swap', 'jupiter-price', 'jup']);
+function isSample(x) {
+    if (x === null || typeof x !== 'object')
+        return false;
+    const s = x;
+    return typeof s.price === 'number' && typeof s.fetchedAt === 'number' && typeof s.source === 'string';
+}
+function dependent(source) {
+    const s = source.toLowerCase();
+    return SOL_USD_DEPENDENT_SOURCES.has(s) || s.startsWith('jupiter') || s.startsWith('jup-');
+}
+/**
+ * Resolve a SOL/USD price from samples. `input` may be a single sample, an array, or anything else
+ * (a bare number, null, undefined) — anything that is not a well-formed sample is ignored, so a legacy
+ * `() => 150` feed yields NO price and a mainnet trade is refused ('no-usd-value').
+ */
+export function resolveSolUsd(input, now, network) {
+    const raw = Array.isArray(input) ? input : input === null || input === undefined ? [] : [input];
+    const rejected = [];
+    const fresh = new Map(); // one sample per source (the freshest)
+    for (const x of raw) {
+        if (!isSample(x)) {
+            rejected.push('malformed sample');
+            continue;
+        }
+        const src = x.source.trim().toLowerCase();
+        if (src.length === 0) {
+            rejected.push('unnamed source');
+            continue;
+        }
+        if (!Number.isFinite(x.price) || x.price < SOL_USD_MIN_PLAUSIBLE || x.price > SOL_USD_MAX_PLAUSIBLE) {
+            rejected.push(`${src}: implausible $${x.price}`);
+            continue;
+        }
+        if (!Number.isFinite(x.fetchedAt) || x.fetchedAt > now + 5_000) {
+            rejected.push(`${src}: bad timestamp`);
+            continue;
+        }
+        const age = now - x.fetchedAt;
+        if (age > SOL_USD_MAX_AGE_MS) {
+            rejected.push(`${src}: stale (${Math.round(age / 1000)} s)`);
+            continue;
+        }
+        const prev = fresh.get(src);
+        if (!prev || x.fetchedAt > prev.fetchedAt)
+            fresh.set(src, { price: x.price, fetchedAt: x.fetchedAt, source: src });
+    }
+    const valid = [...fresh.values()];
+    const why = rejected.length > 0 ? ` (${rejected.join('; ')})` : '';
+    if (network !== 'mainnet') {
+        // Devnet funds have no USD value; one fresh plausible sample from anyone is enough for display.
+        if (valid.length === 0)
+            return { price: null, reason: `no fresh SOL/USD sample${why}` };
+        const best = valid.reduce((a, b) => (b.price > a.price ? b : a));
+        return { price: best.price, sources: [best.source] };
+    }
+    const independent = valid.filter((s) => !dependent(s.source));
+    if (independent.length < 2) {
+        const have = independent.length === 1 ? `only ${independent[0].source}` : valid.length > 0 ? 'only the swap vendor' : 'none';
+        return { price: null, reason: `mainnet needs two independent non-Jupiter SOL/USD sources; have ${have}${why}` };
+    }
+    const lo = Math.min(...independent.map((s) => s.price));
+    const hi = Math.max(...independent.map((s) => s.price));
+    const spreadPct = ((hi - lo) / lo) * 100;
+    if (spreadPct > SOL_USD_AGREE_PCT) {
+        return { price: null, reason: `SOL/USD sources disagree by ${spreadPct.toFixed(1)}% (${independent.map((s) => `${s.source} $${s.price}`).join(', ')})` };
+    }
+    return { price: hi, sources: independent.map((s) => s.source) };
+}

package/dist/packages/data/src/trade/swap-build.js

@@ -0,0 +1,108 @@
+// dexterm T1 — Jupiter keyless SWAP BUILD (SPEC §6.1 step 2). Separate file from the T0 quote-only
+// `sources/jupiter-swap.ts` ON PURPOSE: that file is provably unable to reach a signable transaction
+// (the verifier key-scan relies on it), so the tx-building step lives here, clearly T1-gated.
+//
+// Flow: GET /swap/v1/quote (keyless, raw) -> POST /swap/v1/swap { quoteResponse, userPublicKey } ->
+// a base64 VersionedTransaction. dexterm does NOT sign it; it hands the bytes to the wallet bridge.
+//
+// IMPORTANT (design constraint): Jupiter's quote/swap liquidity is
+// MAINNET-only — there is no Jupiter devnet. So a Jupiter swap plan is a MAINNET plan. With the
+// default devnet caps the signer refuses to sign it (mainnet-not-enabled): the default experience is
+// a read-only plan + simulation (SPEC §6.10 "mainnet read-only quotes/sims, confirm disabled").
+// Enabling a real swap needs --mainnet + the USD caps. The devnet signer/bridge plumbing is proven
+// separately with a wallet self-transfer (scripts/phantom-devnet.md). No key ever enters dexterm.
+import { JUP_SWAP_HOSTS, JupiterHosts } from "../sources/jupiter-swap.js";
+const BUILD = { source: 'jupiter-swap', bucket: 'jupiter' };
+/**
+ * task-1368: a raw quote fetched this recently for the SAME request is reused instead of re-fetched. The LIVE
+ * ticket's preview (`quote` through the signer), the signer's own re-quote at ⏎ and the build then cost the
+ * per-IP keyless budget two calls, not three, and are paced by ONE limiter (the signer's). The executor still
+ * binds whatever quote it gets to the order (mints, mode, exact amount) and simulates the built transaction.
+ */
+export const QUOTE_REUSE_MS = 15_000;
+export class JupiterSwapBuild {
+    http;
+    hosts;
+    /** The last raw quote per request key, for QUOTE_REUSE_MS. One entry per distinct order is plenty. */
+    recent = new Map();
+    constructor(http, hosts = JUP_SWAP_HOSTS, retry = {}) {
+        this.http = http;
+        this.hosts = new JupiterHosts(hosts, { clock: http.clock, bucketPausedMs: () => http.pausedFor(BUILD.bucket), sourceUnavailableMs: () => http.unavailableFor(BUILD.source), ...retry });
+    }
+    get host() { return this.hosts.host; }
+    /**
+     * Fetch the RAW quote object (needed verbatim by /swap). Keyless, read-only. A quote for the same request
+     * fetched within QUOTE_REUSE_MS is returned again (`fresh: false` forces a network quote).
+     */
+    async quoteRaw(req, signal, opts = {}) {
+        if (!(req.amount > 0n))
+            throw new Error('quote amount must be a positive integer of base units');
+        if (req.inputMint === req.outputMint)
+            throw new Error('quote needs two different mints');
+        const params = new URLSearchParams({
+            inputMint: req.inputMint,
+            outputMint: req.outputMint,
+            amount: req.amount.toString(),
+            slippageBps: String(Math.max(0, Math.round(req.slippageBps))),
+            swapMode: req.mode ?? 'ExactIn',
+        });
+        const key = params.toString();
+        const reuseMs = opts.reuseMs ?? QUOTE_REUSE_MS;
+        const now = this.http.clock.now();
+        const hit = this.recent.get(key);
+        if (hit && reuseMs > 0 && now - hit.at <= reuseMs)
+            return hit.raw;
+        const r = await this.getJson(`/swap/v1/quote?${key}`, signal);
+        if (!r || typeof r !== 'object' || r.inAmount === undefined || r.outAmount === undefined) {
+            throw new Error('empty or malformed quote');
+        }
+        this.recent.clear();
+        this.recent.set(key, { raw: r, at: this.http.clock.now() });
+        return r;
+    }
+    /** Age in ms of the reusable quote for this request, or null when none is held. */
+    quoteAge(req) {
+        const key = new URLSearchParams({
+            inputMint: req.inputMint, outputMint: req.outputMint, amount: req.amount.toString(),
+            slippageBps: String(Math.max(0, Math.round(req.slippageBps))), swapMode: req.mode ?? 'ExactIn',
+        }).toString();
+        const hit = this.recent.get(key);
+        return hit ? this.http.clock.now() - hit.at : null;
+    }
+    /**
+     * Build an unsigned swap transaction for `userPublicKey` from a raw quote. KEYLESS. The returned
+     * bytes are an unsigned VersionedTransaction; dexterm never signs — the wallet bridge does.
+     */
+    async buildSwap(args) {
+        if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(args.userPublicKey))
+            throw new Error('buildSwap needs a base58 public key');
+        const body = {
+            quoteResponse: args.quote,
+            userPublicKey: args.userPublicKey,
+            wrapAndUnwrapSol: true,
+            dynamicComputeUnitLimit: true,
+            // Jupiter managed landing / priority-fee defaults; dexterm never sets a fee it cannot cap.
+        };
+        const r = await this.postJson(`/swap/v1/swap`, body, args.signal);
+        const tx = r?.swapTransaction;
+        if (typeof tx !== 'string' || tx.length === 0)
+            throw new Error('swap build returned no transaction');
+        if (!/^[A-Za-z0-9+/=]+$/.test(tx))
+            throw new Error('swap transaction is not base64');
+        return {
+            swapTransactionBase64: tx,
+            lastValidBlockHeight: typeof r.lastValidBlockHeight === 'number' ? r.lastValidBlockHeight : null,
+            prioritizationFeeLamports: typeof r.prioritizationFeeLamports === 'number' ? r.prioritizationFeeLamports : null,
+            quote: args.quote,
+        };
+    }
+    /** task-1368: 401/403 → sticky failover; 429/5xx/transport → alternate host + bounded retry (JupiterHosts). */
+    async getJson(path, signal) {
+        const r = await this.hosts.run((host) => this.http.getJson(`${host}${path}`, BUILD, undefined, signal), signal);
+        return r.data;
+    }
+    async postJson(path, body, signal) {
+        const r = await this.hosts.run((host) => this.http.postJson(`${host}${path}`, body, BUILD, undefined, signal), signal);
+        return r.data;
+    }
+}

package/dist/packages/data/src/trade/token-delta.js

@@ -0,0 +1,201 @@
+// dexterm T1/T2 — task-1337: the TOKEN-BALANCE DIFF (the round-3 verifier's "recommended next hardening").
+//
+// The static policy fixes WHICH instructions a transaction may carry and binds the one Jupiter route to the
+// plan (amounts, the wallet's own token accounts, no fee). What it cannot see is what the route DOES once
+// it runs: a legit-looking route instruction whose `route_plan` names crafted pool accounts could, if the
+// on-chain program ever let it, move tokens out of one of the wallet's OTHER token accounts. The SOL-delta
+// check would not notice (only the fee leaves the wallet in SOL). This module is the backstop: simulate
+// with the wallet's token accounts in `accounts[]` and refuse when any of them lost tokens the plan does
+// not spend.
+//
+//   buy  (SOL → token): NO token account of the wallet may decrease.
+//   sell (token → SOL): ONLY the wallet's token accounts for the ORDER mint may decrease, by at most the
+//                       order amount in total. Everything else must not decrease.
+//   wrapped SOL:        the wallet's WSOL accounts ARE watched (task-1337 F2). A swap funds, syncs and
+//                       closes a wrapped-SOL account back to the wallet, so WSOL leaving the wallet is
+//                       SOL-value out — not a free pass. `checkTokenDeltas` tallies how much wrapped SOL
+//                       left (`wsolLost`); the executor bounds `solOut + wsolLost` against the plan's SOL
+//                       leg (`checkWsolBound`), so a route that drains a PRE-EXISTING WSOL account is
+//                       caught by the SOL-value budget instead of being ignored.
+//
+// One simulation can carry only so many token accounts (`MAX_TOKEN_WATCH`). A referenced account is NEVER
+// dropped to fit that cap (task-1337 F3): `buildTokenWatch` keeps every referenced account and bounds only
+// the unreferenced tail, and the executor refuses outright (`referencedOverCap`) when the transaction
+// references more wallet token accounts than one simulation can hold.
+//
+// Pure: no I/O here. The executor fetches the pre-state (getTokenAccountsByOwner / getMultipleAccounts),
+// resolves address-lookup tables so "referenced by the transaction" is exact for v0 messages, asks the
+// simulation for the post-state and hands both to `checkTokenDeltas`. Unknowable = refuse (fail closed).
+import { base58 } from "../sources/solana-rpc.js";
+import { WSOL_MINT } from "./tx-decode.js";
+/** SPL Token / Token-2022 account base layout: mint[0..32] owner[32..64] amount u64 LE [64..72] state[108]. */
+export const TOKEN_ACCOUNT_LEN = 165;
+/** Parse an SPL token account (both programs share the 165-byte base layout; Token-2022 may append extensions). */
+export function parseTokenAccount(data) {
+    if (!data || data.length < TOKEN_ACCOUNT_LEN)
+        return null;
+    if (data[108] === 0)
+        return null; // AccountState::Uninitialized
+    return { mint: base58(data.subarray(0, 32)), owner: base58(data.subarray(32, 64)), amount: data.readBigUInt64LE(64) };
+}
+/** Address-lookup-table account layout: 56-byte LookupTableMeta, then 32-byte addresses. */
+export const LOOKUP_TABLE_META_LEN = 56;
+export function parseLookupTable(data) {
+    if (!data || data.length < LOOKUP_TABLE_META_LEN)
+        return null;
+    const body = data.subarray(LOOKUP_TABLE_META_LEN);
+    if (body.length % 32 !== 0)
+        return null;
+    const out = [];
+    for (let i = 0; i < body.length; i += 32)
+        out.push(base58(body.subarray(i, i + 32)));
+    return out;
+}
+/**
+ * Every account a transaction can touch: its static keys plus the lookup-table entries it loads.
+ * `tables` maps a table address → its parsed address list. A table the caller could not read, or an
+ * index past the table's end, makes the set UNKNOWABLE → null (the executor refuses, fail closed).
+ */
+export function referencedAccounts(tx, tables) {
+    const out = new Set(tx.staticKeys);
+    for (const l of tx.lookups) {
+        const t = tables.get(l.table);
+        if (!t)
+            return null;
+        for (const i of [...l.writable, ...l.readonly]) {
+            if (i < 0 || i >= t.length)
+                return null;
+            out.add(t[i]);
+        }
+    }
+    return out;
+}
+/** Build the watch list from the wallet's token accounts (pre-state) and the transaction's account set. */
+export function buildTokenWatch(user, accounts, referenced, opts = {}) {
+    const seen = new Set();
+    const all = [];
+    for (const a of accounts) {
+        if (seen.has(a.pubkey))
+            continue;
+        const st = parseTokenAccount(a.data);
+        if (!st || st.owner !== user)
+            continue;
+        seen.add(a.pubkey);
+        // task-1337 F2: wrapped SOL is watched too (its loss is SOL-value out, bounded by checkWsolBound).
+        all.push({ address: a.pubkey, mint: st.mint, pre: st.amount, referenced: referenced.has(a.pubkey), isWsol: st.mint === WSOL_MINT });
+    }
+    // task-1337 F3: a referenced account can be touched by the transaction, so it must NEVER be dropped to
+    // fit the cap. Keep every referenced account; bound only the unreferenced tail (largest balances first).
+    // When referenced accounts alone exceed the cap the list exceeds it on purpose and the executor refuses
+    // (see `referencedOverCap`) — truncating them here would hide a drain of a dropped account.
+    const max = opts.max ?? MAX_TOKEN_WATCH;
+    const ref = all.filter((w) => w.referenced).sort(byBalance);
+    const unref = all.filter((w) => !w.referenced).sort(byBalance);
+    return [...ref, ...unref.slice(0, Math.max(0, max - ref.length))];
+}
+function byBalance(x, y) { return y.pre > x.pre ? 1 : y.pre < x.pre ? -1 : 0; }
+/** How many token accounts ride along in one simulateTransaction `accounts[]` (plus the wallet itself). */
+export const MAX_TOKEN_WATCH = 48;
+/**
+ * task-1337 F3: does the transaction reference MORE of the wallet's own token accounts than one simulation
+ * can carry? If so the watch list cannot cover them all and the executor must refuse (fail closed) rather
+ * than silently drop referenced accounts. Counts only referenced accounts (the unreferenced tail is
+ * bounded safely by `buildTokenWatch`).
+ */
+export function referencedOverCap(watch, max = MAX_TOKEN_WATCH) {
+    let n = 0;
+    for (const w of watch)
+        if (w.referenced)
+            n++;
+    return n > max;
+}
+/**
+ * The decision. `post` maps a watched address → its post-simulation balance, or null when the node
+ * returned no account for it (closed, or — for an account the transaction never references — simply
+ * not loaded: such an account cannot have changed, so it keeps its pre-balance). An account the
+ * transaction DOES reference and that comes back null was closed: a positive pre-balance then counts
+ * as fully drained. A watched account missing from `post` entirely (the node sent no data) is
+ * unknowable → refused when it held anything.
+ */
+export function checkTokenDeltas(side, orderMint, amountRaw, watch, post) {
+    let spent = 0n;
+    let wsolLost = 0n;
+    let checked = 0;
+    for (const w of watch) {
+        if (post === null || !post.has(w.address)) {
+            if (w.pre > 0n)
+                return { ok: false, reason: 'token-delta-unknown', message: `the simulation did not report the post-balance of the wallet's ${short(w.mint)} token account ${short(w.address)}` };
+            continue;
+        }
+        checked++;
+        const raw = post.get(w.address) ?? null;
+        const after = raw === null ? (w.referenced ? 0n : w.pre) : raw;
+        if (w.isWsol) {
+            // task-1337 F2: wrapped SOL is SOL-value, not a token holding. A legit wrap/sync/close returns it to
+            // the wallet as native SOL. Only tally what left; the combined SOL-value bound lives in the executor
+            // (checkWsolBound), where the plan's SOL leg and the native SOL delta are known.
+            if (after < w.pre)
+                wsolLost += w.pre - after;
+            continue;
+        }
+        if (after >= w.pre)
+            continue;
+        const lost = w.pre - after;
+        if (side === 'sell' && w.mint === orderMint) {
+            spent += lost;
+            if (spent > amountRaw)
+                return { ok: false, reason: 'token-delta', message: `the simulation spends ${spent} base units of ${short(orderMint)} but the order is ${amountRaw}` };
+            continue;
+        }
+        return { ok: false, reason: 'token-delta', message: `the simulation moves ${lost} base units of ${short(w.mint)} out of the wallet's token account ${short(w.address)}, which this ${side} does not spend` };
+    }
+    return { ok: true, spent, wsolLost, checked };
+}
+/**
+ * task-1337 F2: pre-existing wrapped SOL that leaves the wallet is SOL-value out and must fit the plan.
+ *   buy:  native SOL out + wrapped SOL consumed may be at most the planned SOL leg plus the fee allowance
+ *         (wrapping is fungible, so the two are one budget). A null native delta with WSOL gone is
+ *         unmeasurable → refuse.
+ *   sell: a sell RECEIVES SOL, so its own WSOL accounts must not shrink by more than fee dust — the
+ *         incoming proceeds must never mask a drain, so the native delta is not credited here.
+ * `wsolLost <= 0` is the overwhelmingly common case (no pre-existing WSOL touched) → pass cheaply.
+ */
+export function checkWsolBound(side, solOut, wsolLost, solLegLamports, allowanceLamports) {
+    if (wsolLost <= 0n)
+        return { ok: true };
+    if (side === 'buy') {
+        if (solOut === null)
+            return { ok: false, reason: 'wsol-drain', message: `the simulation removes ${wsolLost} lamports of pre-existing wrapped SOL but the native SOL delta is unknown` };
+        const out = solOut + wsolLost;
+        const limit = solLegLamports + allowanceLamports;
+        if (out > limit)
+            return { ok: false, reason: 'wsol-drain', message: `the simulation removes ${wsolLost} lamports of wrapped SOL plus ${solOut} native lamports (${out} total) but the plan's SOL leg is ${solLegLamports} (+${allowanceLamports} allowance)` };
+        return { ok: true };
+    }
+    if (wsolLost > allowanceLamports)
+        return { ok: false, reason: 'wsol-drain', message: `a sell removes ${wsolLost} lamports of pre-existing wrapped SOL from the wallet, beyond the ${allowanceLamports}-lamport fee allowance` };
+    return { ok: true };
+}
+/** Post-simulation balances for the watched accounts from `simulate(..., { accounts: [user, ...watch] })`. */
+export function postBalances(watch, accountsData, offset) {
+    if (accountsData === null)
+        return null;
+    const out = new Map();
+    for (let i = 0; i < watch.length; i++) {
+        const d = accountsData[offset + i];
+        if (d === undefined)
+            return null; // the node answered for fewer accounts than asked → unknowable
+        out.set(watch[i].address, d === null ? null : (parseTokenAccount(d)?.amount ?? 0n));
+    }
+    return out;
+}
+/** Refresh the pre-balances of an existing watch list from fresh account snapshots (the confirm step). */
+export function refreshWatch(watch, infos) {
+    if (infos.length !== watch.length)
+        return null;
+    return watch.map((w, i) => {
+        const st = parseTokenAccount(infos[i]?.data);
+        return { ...w, pre: st ? st.amount : 0n };
+    });
+}
+function short(k) { return k.length > 12 ? `${k.slice(0, 4)}…${k.slice(-4)}` : k; }