@inversealtruism/cairn-cli 0.3.1 → 0.3.5

package/dist/cli.js

@@ -5,28 +5,130 @@ import { CAIRN_API, CAIRN_ADDR, CAIRN_TOKEN, CAIRN_RPC, MIN_FEE_PROPOSE, MIN_FEE
 import * as api from "./lib/api.js";
 import * as csd from "./lib/csd.js";
 import { buildCommitment } from "./lib/item.js";
+import { buildGatewayRecord, buildPeerRecord, buildIdentityCommit, buildIdentityReveal } from "@inversealtruism/csd-registry";
+import { canonicalJson } from "@inversealtruism/csd-codec";
+import { cairnxGet, activeCairnxBase, buildTransferRecord, humanToBase, baseToHuman, CAIRNX_DOMAIN, CAIRNX_ANCHOR_FEE, TICKER_RE, NAME_RE } from "./lib/cairnx.js";
+import { randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
 import { c, banner, bannerAnimated, rule, badge, bar, csd as csdFmt, ok, warn, err, key as kdim, pad, spinner, sleep, isTty, anim, clearScreen, cursorHome, san } from "./lib/ui.js";
 const CSD = (n) => Number.isFinite(n) ? Math.round(n * CSD_PER_COIN) : NaN; // CSD → base units
+// ── max-fee sanity guard (UTXO-VALUE-1) ──────────────────────────────────────────────────────
+// A CSD fee is implicit (Σin − Σout) and the chain enforces NO maximum, so a hostile proxy that
+// UNDER-reports the picked UTXO's value would make `csd` compute too-small a change and the
+// difference is silently burned to the miner as fee — the user's own funds, with no on-chain
+// protection. cairn-cli has no codec to recompute the input's REAL value (the wallet's
+// verifyInputValues path), so it applies a proportionate SANITY cap on the fee instead: the fee
+// must be ≤ max(1 CSD absolute, 25% of the tx value). Every honest fee (a 0.01 CSD transfer fee,
+// a 0.25 CSD propose) passes; a typo / hostile-inflated fee is refused. `--max-fee <CSD>` overrides.
+// Returns null if the fee is acceptable, or a human error string to print and abort.
+const MAX_FEE_ABS = 100_000_000; // 1 CSD absolute floor — every honest fee is well under this
+const MAX_FEE_VALUE_FRACTION = 0.25; // …and ≤ 25% of the value moved
+function feeCap(txValue, a) {
+    if (a.flags["max-fee"] !== undefined) {
+        const m = CSD(Number(a.flags["max-fee"]));
+        if (Number.isSafeInteger(m) && m >= 0)
+            return m;
+    }
+    return Math.max(MAX_FEE_ABS, Math.floor(Math.max(0, txValue) * MAX_FEE_VALUE_FRACTION));
+}
+// Guard a value-write before it is built/signed. `txValue` = the value the user means to move
+// (recipients for a send; the fee itself for a fee-only propose/attest). Prints + returns false on abort.
+function feeSanity(fee, txValue, a) {
+    const cap = feeCap(txValue, a);
+    if (fee > cap) {
+        console.log(err(`fee ${csdToCoins(fee)} CSD looks abnormally high (cap ${csdToCoins(cap)} CSD).`) +
+            c.gray(" A proxy under-reporting your input can silently burn the difference as fee. Lower ") + c.cyan("--fee") +
+            c.gray(", or override with ") + c.cyan("--max-fee <CSD>") + c.gray(" if this is intentional."));
+        return false;
+    }
+    return true;
+}
+// Implied-fee transparency for a single-UTXO spend: the on-chain fee a hostile proxy can inflate is
+// (real input − value − change). We can only see the REPORTED input, but we can flag when the
+// reported change is implausibly small for the input (the collapsed-change signature of an
+// under-report). Non-fatal — a warning the user sees before they commit.
+function warnIfChangeCollapsed(inputValue, txValue, fee) {
+    const change = inputValue - txValue - fee;
+    if (change < 0)
+        return; // pickInput already ensures coverage; defensive
+    // a healthy spend leaves change ≫ fee unless the user genuinely picked a tight UTXO; flag the
+    // case where the implied fee dwarfs the change (what an under-reporting proxy produces).
+    if (change > 0 && fee > change * 4) {
+        console.log(warn(`heads up: change (${csdToCoins(change)} CSD) is much smaller than the fee (${csdToCoins(fee)} CSD).`) +
+            c.gray(" If your proxy under-reports this input, extra value is burned as fee — verify with your own node, or use ") + c.cyan("--max-fee") + c.gray("."));
+    }
+}
+// Pick a spendable input from the proxy, INDEPENDENTLY verify its value against CAIRN_RPC
+// (UTXO-VALUE-1 cross-source cure), and ALWAYS display the input/change so the implied fee is
+// visible on EVERY write (not just `send`). `txValue` = value moved to recipients (0 for a fee-
+// only propose/attest); `fee` = the fee. Returns the csd input triple, or null (reason printed).
+// Defense layering: (1) if an independent node is configured we cryptographically catch an
+// under-report and REFUSE; (2) otherwise the value is proxy-trusted and the only backstop is the
+// feeSanity cap + the visible change line — the user is told to set CAIRN_RPC for a real check.
+async function pickAndShow(addr, need, txValue, fee) {
+    const picked = await api.pickInput(addr, need).catch(() => null);
+    if (!picked) {
+        console.log(err("no single confirmed UTXO covers this spend") + c.gray(" — fund this address, or consolidate (a node + `csd … --auto-input` can combine inputs)."));
+        return null;
+    }
+    const [ptxid, pvoutS] = picked.input.split(":");
+    const v = await api.verifyInputValue(addr, ptxid, Number(pvoutS), picked.value).catch(() => ({ checked: false }));
+    if (v.checked && v.ok === false) {
+        if (v.missing)
+            console.log(err("the picked input is NOT in your independent node's UTXO set (CAIRN_RPC).") + c.gray(" The proxy may be misreporting your coins — refusing to spend. Check your node is synced, or unset CAIRN_RPC to override."));
+        else
+            console.log(err(`input value MISMATCH — proxy says ${csdToCoins(picked.value)} CSD, your node says ${csdToCoins(v.value ?? 0)} CSD.`) + c.gray(" A proxy under-reporting your input would burn the difference as fee — refusing to spend."));
+        return null;
+    }
+    const verified = v.checked && v.ok === true;
+    const inputValue = verified ? Number(v.value) : picked.value;
+    const tag = verified ? c.green(" ✓ verified vs your node")
+        : (CAIRN_RPC ? c.gray(" (independent value check unavailable)") : c.gray(" (set CAIRN_RPC to your own node to independently verify this value)"));
+    console.log(`${kdim("input")}   ${csdToCoins(inputValue)} CSD ${c.gray("(one UTXO)")}${tag}   ${kdim("change")} ${csdToCoins(Math.max(0, inputValue - txValue - fee))} CSD ${c.gray("back to you")}`);
+    warnIfChangeCollapsed(inputValue, txValue, fee);
+    return picked.input;
+}
 // Resolve the user's PUBLIC address (to fetch inputs from the proxy). Never reads the key
 // unless we must derive it locally from the user's own csd wallet config (then we cache
-// only the public address). Order: --address → CAIRN_ADDR → cached → derive via csd.
+// only the public address). Order: --address → CAIRN_ADDR (both EXPLICIT user intent for this
+// invocation) → the csd wallet's real change address → cached config.address (LAST, and never
+// above the wallet — see below).
+//
+// F13/R18: the cached config.address is attacker-tamperable (a poisoned
+// ~/.config/cairn-cli/config.json would otherwise redirect `cairn address` output, so a funder
+// piping it pays the attacker). So when csd is available we re-derive the wallet's REAL change
+// address and treat THAT as authoritative; if it disagrees with the cached value we refuse and
+// rewrite the cache. The cache is only used as a fallback when csd can't tell us the truth.
 async function resolveAddr(a) {
-    const flag = a.flags.address ? String(a.flags.address) : (CAIRN_ADDR || loadLocalConfig().address);
-    if (flag && /^0x[0-9a-fA-F]{40}$/.test(flag))
-        return flag;
+    // explicit, per-invocation choice — the user can deliberately target any address
+    const explicit = a.flags.address ? String(a.flags.address) : CAIRN_ADDR;
+    if (explicit && /^0x[0-9a-fA-F]{40}$/.test(explicit))
+        return explicit;
+    const cached = loadLocalConfig().address;
     const cfg = await csd.walletConfig();
-    // Prefer the address csd already exposes (change addr) — avoids re-deriving from the
-    // privkey, which would put the key on the `csd` argv (visible via /proc on a shared host).
+    // Best case: the wallet exposes its change address directly — authoritative AND needs no key
+    // (no argv exposure). The cache is then only an anti-poison cross-check (F13/R18): if a tampered
+    // config disagrees, say so loudly and use the wallet's address.
     if (cfg?.default_change_addr20 && /^0x[0-9a-fA-F]{40}$/.test(String(cfg.default_change_addr20))) {
-        const addr = String(cfg.default_change_addr20);
-        saveLocalConfig({ address: addr });
-        return addr;
+        const real = String(cfg.default_change_addr20);
+        if (cached && cached.toLowerCase() !== real.toLowerCase())
+            console.log(warn(`cached address ${c.cyan(san(cached))} does NOT match your csd wallet ${c.cyan(real)}`) + c.gray(" — using the wallet's address and refreshing the cache (a tampered config can't redirect you)."));
+        saveLocalConfig({ address: real });
+        return real;
     }
+    // No change address configured. Audit H-2: re-deriving from the privkey on EVERY call runs
+    // `csd wallet recover --privkey <KEY>`, putting the key on the argv (readable via /proc on a
+    // shared host). Avoid that — prefer a previously-cached address; only DERIVE when we have
+    // nothing else (then cache it + warn once, and nudge the user to set a change address so the
+    // key is never needed again, which also restores the F13 anti-poison cross-check above).
+    if (cached && /^0x[0-9a-fA-F]{40}$/.test(cached))
+        return cached;
     if (cfg?.default_privkey) {
-        const addr = await csd.deriveAddr(cfg.default_privkey);
-        if (addr) {
-            saveLocalConfig({ address: addr });
-            return addr;
+        const real = await csd.deriveAddr(cfg.default_privkey);
+        if (real && /^0x[0-9a-fA-F]{40}$/.test(real)) {
+            console.log(warn("derived your address from the wallet key once.") + c.gray(" " + csd.keyExposureWarning));
+            saveLocalConfig({ address: real });
+            return real;
         }
     }
     return null;
@@ -36,9 +138,13 @@ async function resolveAddr(a) {
 // proxy ourselves. We do NOT trust csd's own auto-submit: it targets csd's configured node,
 // which may be a different node than the one the Cairn board (and its miner) read — so a tx
 // could sit in the wrong mempool and never get mined into the board's view. Always submit via
-// the proxy (the board's miner-connected node). A repeat that comes back "already present /
-// known" for OUR txid is success (the tx is in that node's mempool); a true double-spend
-// "conflict" is the only ambiguous case, so we confirm via a tx lookup before claiming ok.
+// the proxy (the board's miner-connected node).
+//
+// Success is EVIDENCE-BASED, never message-based: a hostile proxy (or a real double-spend)
+// can return an "already present / conflict" string for a tx that is NOT actually ours, so we
+// never treat any error message as success. A clean submit ack is good; otherwise we ask the
+// node directly whether OUR exact txid is on-chain (api.confirmTxMined), and only claim success
+// when the node confirms it. If we can't confirm, we surface the real node message.
 async function signAndSubmit(csdArgs) {
     const r = await csd.run(csdArgs);
     if (!r.ok)
@@ -54,17 +160,40 @@ async function signAndSubmit(csdArgs) {
     const sub = await api.submitTx(out.tx).catch((e) => ({ ok: false, err: e.message }));
     if (sub.ok)
         return { ok: true, txid: sub.txid || txid };
-    // A benign "already present / mempool conflict" for OUR txid means the tx is already in a
-    // mempool (e.g. csd's own auto-submit reached this same node first, or a re-run) — success.
-    // For a single-key wallet this is safe: only the key owner can produce a conflicting spend
-    // of their own UTXO, so a conflict on our freshly-built tx is our own prior submit, not a
-    // third party. (The narrow exception — two DIFFERENT local spends of one UTXO fired at once
-    // — is on the user.) The node can't be queried for mempool membership (its /tx indexes only
-    // mined txs), so we rely on the matching txid + benign message.
-    if (txid && /already|present|known|in mempool|conflict/i.test(String(sub.err ?? "")))
+    // Submit was NOT acked. Don't trust the error STRING — a forged "already present" can hide a
+    // rejected/conflicting tx. Confirm against the chain: only if the node reports OUR exact txid
+    // as mined is this our own prior submit (a genuine "already in"); otherwise the conflict is a
+    // DIFFERENT spend (a real double-spend / hostile reply) and we surface it as a failure.
+    if (txid && await api.confirmTxMined(txid))
         return { ok: true, txid };
     return { ok: false, error: sub.err || "submit rejected by node", txid };
 }
+// Freshness gate (R12): before building any value tx, consult the proxy's chain-view status so
+// we never sign against a FROZEN or forked tip (the proxy may be failing over to an honest-but-
+// stale or wedged node). Fail CLOSED on a stale tip; fail OPEN (warn only) if the freshness
+// surface is unreachable — that matches the rest of the CLI's 'cannot reach' UX and an old node
+// without /api/rpc/status must still be usable. `--force-stale` lets an operator override.
+async function freshTip(a) {
+    let s;
+    try {
+        s = await api.rpcStatus();
+    }
+    catch {
+        console.log(warn("could not check chain freshness (status surface unreachable) — proceeding"));
+        return true;
+    }
+    const secs = Number(s?.secondsSinceAdvance ?? 0);
+    const threshold = Number(s?.staleSecsThreshold ?? 600);
+    const stale = s?.stale === true || (Number.isFinite(secs) && Number.isFinite(threshold) && threshold > 0 && secs > threshold);
+    if (!stale)
+        return true;
+    if (a.flags["force-stale"]) {
+        console.log(warn(`chain tip looks STALE (${secs}s since last advance) — proceeding anyway (--force-stale)`));
+        return true;
+    }
+    console.log(err(`chain tip looks STALE — last advanced ${secs}s ago (threshold ${threshold}s).`) + c.gray(" The node may be frozen or failing over to a stale view; refusing to build a tx. Retry shortly, or override with ") + c.cyan("--force-stale") + c.gray("."));
+    return false;
+}
 // Guard: a write needs `csd` installed + a configured wallet (or an explicit --address + csd key).
 async function requireCsd() {
     if (!(await csd.available())) {
@@ -100,11 +229,19 @@ function parse(argv) {
     }
     return { _, flags, multi };
 }
-// Do two URLs point at the same host? (used to refuse a "trustless" verify claim when the
-// node RPC and the board API are the same operator). Unparseable → treat as same (safe).
+// Do two URLs point at the same MACHINE? (used to refuse a "trustless" verify claim when the
+// node RPC and the board API are the same operator). Compares hostname only — NOT host — so a
+// same-box node:8789 + board:7777 are correctly judged same-machine (a port difference does not
+// make two endpoints independent), and canonicalizes the loopback aliases (127.0.0.1 / localhost
+// / ::1) so they all compare equal. Unparseable → treat as same (the SAFE default: never claim
+// trustless independence we can't establish).
+function canonHost(h) {
+    const x = h.toLowerCase().replace(/^\[|\]$/g, ""); // strip IPv6 brackets
+    return (x === "localhost" || x === "127.0.0.1" || x === "::1" || x === "0.0.0.0") ? "localhost" : x;
+}
 function sameHost(a, b) {
     try {
-        return new URL(a).host.toLowerCase() === new URL(b).host.toLowerCase();
+        return canonHost(new URL(a).hostname) === canonHost(new URL(b).hostname);
     }
     catch {
         return true;
@@ -268,7 +405,12 @@ async function cmdSetup() {
     banner();
     rule("setup — cairn over your csd wallet");
     const has = await csd.available();
-    console.log(`  ${kdim("csd binary")}  ${has ? ok("found (" + csd.CSD_BIN + ")") : err("not found — install Compute Substrate's csd CLI, or set CAIRN_CSD to its path")}`);
+    // H-1: show the RESOLVED absolute path of the binary that will SIGN, so the user can verify it
+    // (and see the refusal if it was resolved from an untrusted location).
+    const bin = csd.csdPathInfo();
+    console.log(`  ${kdim("csd binary")}  ${has ? ok("found") + c.gray("  " + (bin.path ?? "")) + (bin.explicit ? c.gray("  (CAIRN_CSD)") : c.gray("  (resolved)")) : err(bin.error || "not found — install Compute Substrate's csd CLI, or set CAIRN_CSD to its absolute path")}`);
+    if (bin.warning)
+        console.log(`  ${kdim("")}            ${warn(bin.warning)}`);
     if (!has) {
         console.log(c.gray("\n  cairn signs nothing itself — it drives your csd wallet. Install csd, then re-run ") + c.cyan("cairn setup") + c.gray("."));
         return;
@@ -343,30 +485,61 @@ async function cmdSend(a) {
     for (const o of outs)
         console.log(`${kdim("to")}      ${c.cyan(o.to)} ${c.gray("→ " + csdToCoins(o.value) + " CSD")}`);
     console.log(`${kdim("fee")}     ${csdToCoins(fee)} CSD   ${kdim("total")} ${csdToCoins(total + fee)} CSD`);
+    // max-fee sanity: an absurd fee (typo, or a hostile proxy under-reporting the input → burned
+    // change) is refused BEFORE we build/sign. --dry-run still SHOWS the abnormal-fee warning (so the
+    // user sees it without spending) but never aborts the preview. --max-fee overrides a deliberate fee.
+    const feeOk = feeSanity(fee, total, a);
     if (a.flags["dry-run"]) {
         console.log(c.gray("\n[dry-run] not sent"));
         return;
     }
-    const sp = spinner("fetching input → csd signs → submit");
-    const picked = await api.pickInput(addr, total + fee).catch(() => null);
-    if (!picked) {
-        sp.stop();
-        console.log(err("no single confirmed UTXO covers amount + fee") + c.gray(" — fund this address, or consolidate (a node + `csd … --auto-input` can combine inputs)"));
+    if (!feeOk)
+        return;
+    if (!(await freshTip(a)))
+        return;
+    const input = await pickAndShow(addr, total + fee, total, fee);
+    if (!input)
         return;
-    }
-    sp.stop();
-    // transparency: show the input value + change so a hostile proxy under-reporting the input
-    // (which would silently inflate the burned fee) is visible before we sign. Change goes to
-    // your own address; the proxy can never redirect it.
-    console.log(`${kdim("input")}   ${csdToCoins(picked.value)} CSD ${c.gray("(one UTXO)")}   ${kdim("change")} ${csdToCoins(Math.max(0, picked.value - total - fee))} CSD ${c.gray("back to you")}`);
     const sp2 = spinner("csd signs → submit");
     const args = ["spend"];
     for (const o of outs)
         args.push("--output", `${o.to}:${o.value}`);
-    args.push("--change", addr, "--fee", String(fee), "--input", picked.input);
+    args.push("--change", addr, "--fee", String(fee), "--input", input);
     const r = await signAndSubmit(args);
     sp2.stop();
-    console.log(r.ok ? ok(`sent  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)") : err(r.error || "failed"));
+    if (!r.ok) {
+        console.log(err(r.error || "failed"));
+        return;
+    }
+    console.log(ok(`sent  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)"));
+    await confirmMined(r.txid, "transfer", !!a.flags.wait);
+}
+// Post-submit feedback for value writes (send/support). The txid is already proven submitted by the
+// evidence-based signAndSubmit; mining is a separate ~120s event, so by DEFAULT we DON'T block on it —
+// we report submitted + how to track it (matching token-send). Pass `--wait` to block until OUR exact
+// txid is mined (the old behavior; useful in scripts that chain on confirmation). Non-fatal either way.
+async function confirmMined(txid, label, wait) {
+    if (!wait) {
+        console.log(c.gray(`  ${label} submitted — usually mines within ~2 min; track with `) + c.cyan(`cairn show ${txid.slice(0, 10)}…`));
+        return;
+    }
+    const sp = spinner("waiting for the tx to mine (--wait)");
+    const mined = await api.confirmTxMined(txid).catch(() => false);
+    // H-7: the proxy can string-echo a "mined" reply. Only assert "confirmed on-chain" when an
+    // INDEPENDENT node (CAIRN_RPC) agrees; otherwise soften/flag so the user isn't given a false
+    // settlement guarantee they might release goods against.
+    const indep = mined ? await api.chainTxMined(txid).catch(() => null) : null;
+    sp.stop();
+    if (!mined) {
+        console.log(warn(`${label} submitted — not mined yet; re-check with `) + c.cyan(`cairn show`) + warn(" once a block lands"));
+        return;
+    }
+    if (indep === true)
+        console.log(ok(`${label} confirmed on-chain`) + c.gray("  (verified against your independent node)"));
+    else if (indep === false)
+        console.log(err(`${label}: the proxy reports it mined but your node (CAIRN_RPC) does NOT — treat as UNCONFIRMED.`) + c.gray(" A hostile proxy can forge a 'mined' reply; trust your own node."));
+    else
+        console.log(warn(`${label}: proxy reports mined`) + c.gray("  — set CAIRN_RPC to your own node to confirm independently (a proxy can forge this signal)."));
 }
 async function cmdPropose(a) {
     const domain = String(a.flags.domain ?? "");
@@ -408,19 +581,21 @@ async function cmdPropose(a) {
         console.log(`${kdim("title")}    ${c.white(title)}`);
         console.log(`${kdim("hash")}     ${c.magenta(payloadHash)} ${c.gray("· uri " + uri)}`);
         console.log(`${kdim("fee")}      ${csdToCoins(fee)} CSD   ${kdim("from")} ${c.cyan(addr)}`);
+        feeSanity(fee, fee, a); // show the abnormal-fee warning in the preview (non-aborting on dry-run)
         console.log(c.gray("\n[dry-run] not signed or submitted"));
         return;
     }
-    const sp = spinner("fetching input → csd signs → submit");
-    const picked = await api.pickInput(addr, fee).catch(() => null);
-    if (!picked) {
-        sp.stop();
-        console.log(err("no confirmed UTXO above the fee") + c.gray(" — fund " + addr));
+    if (!feeSanity(fee, fee, a))
+        return;
+    if (!(await freshTip(a)))
+        return;
+    const input = await pickAndShow(addr, fee, 0, fee);
+    if (!input)
         return;
-    }
     const tip = await api.tipHeight().catch(() => 0);
     const days = Math.max(1, parseInt(String(a.flags["expires-days"] ?? 30)) || 30);
-    const r = await signAndSubmit(["propose", "--domain", domain, "--payload-hash", payloadHash, "--uri", uri, "--expires-epoch", String(Math.floor(tip / 30) + days * 24), "--fee", String(fee), "--change", addr, "--input", picked.input]);
+    const sp = spinner("csd signs → submit");
+    const r = await signAndSubmit(["propose", "--domain", domain, "--payload-hash", payloadHash, "--uri", uri, "--expires-epoch", String(Math.floor(tip / 30) + days * 24), "--fee", String(fee), "--change", addr, "--input", input]);
     sp.stop();
     if (!r.ok) {
         console.log(err(r.error || "failed"));
@@ -469,19 +644,27 @@ async function cmdSupport(a) {
     if (a.flags["dry-run"]) {
         console.log(`${kdim("support")}  ${c.cyan(id)}`);
         console.log(`${kdim("fee")}      ${csdToCoins(fee)} CSD ${c.gray("· score " + score + " · confidence " + confidence)}   ${kdim("from")} ${c.cyan(addr)}`);
+        feeSanity(fee, fee, a); // show the abnormal-fee warning in the preview (the attest weight IS the fee)
         console.log(c.gray("\n[dry-run] not signed or submitted"));
         return;
     }
-    const sp = spinner("fetching input → csd signs → submit");
-    const picked = await api.pickInput(addr, fee).catch(() => null);
-    if (!picked) {
-        sp.stop();
-        console.log(err("no confirmed UTXO above the fee") + c.gray(" — fund " + addr));
+    // an attest's fee IS the deliberate weight/stake; only guard against an absurd typo above the cap.
+    if (!feeSanity(fee, fee, a))
         return;
-    }
-    const r = await signAndSubmit(["attest", "--proposal-id", id, "--score", String(score), "--confidence", String(confidence), "--fee", String(fee), "--change", addr, "--input", picked.input]);
+    if (!(await freshTip(a)))
+        return;
+    const input = await pickAndShow(addr, fee, 0, fee);
+    if (!input)
+        return;
+    const sp = spinner("csd signs → submit");
+    const r = await signAndSubmit(["attest", "--proposal-id", id, "--score", String(score), "--confidence", String(confidence), "--fee", String(fee), "--change", addr, "--input", input]);
     sp.stop();
-    console.log(r.ok ? ok(`supported  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)") : err(r.error || "failed"));
+    if (!r.ok) {
+        console.log(err(r.error || "failed"));
+        return;
+    }
+    console.log(ok(`supported  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)"));
+    await confirmMined(r.txid, "support", !!a.flags.wait);
 }
 async function cmdWall(a) {
     if (a._[1] === "place") {
@@ -628,12 +811,19 @@ async function help() {
     console.log(c.bold("  wallet") + c.gray("  (signs with your installed csd wallet — cairn never holds your key)"));
     cmd("setup", "", "check csd + wallet, show your address (alias: doctor)");
     cmd("address", "", "your address + balance (alias: whoami, balance)");
-    cmd("send", "--to <0x…40> --amount <CSD>", "transfer CSD (+ --output <a>:<CSD> ×N, --fee <CSD>, --dry-run)");
+    cmd("send", "--to <0x…40> --amount <CSD>", "transfer CSD (+ --output <a>:<CSD> ×N, --fee <CSD>, --max-fee <CSD>, --dry-run)");
     cmd("propose", "--domain <d> --title <t> --body <b>", "post an item (alias: post; + --fee, --expires-days, --dry-run)");
     cmd("support", "<id> --fee <CSD>", "back an item (+ --score, --confidence, --dry-run)");
+    console.log("");
+    console.log(c.bold("  cairnx") + c.gray("  (tokens + .csd names on the CairnX layer)"));
+    cmd("tokens", "[address]", "token balances + .csd names (default: your address)");
+    cmd("token-info", "<TICKER>", "supply · minted · mint mode · top-10 holders (alias: token)");
+    cmd("token-send", "--ticker T --to 0x…40 --amount <n>", "send tokens (anchors a 0.25 CSD transfer record; --dry-run, --yes)");
+    cmd("names", "[address]", "owned .csd names");
+    cmd("name", "<name>", "one name: owner · lease · open offer");
     console.log(c.gray("\n  lenses (--sort): " + Object.keys(LENS).join(" · ")));
     console.log(c.gray(`  api: ${CAIRN_API}  ·  1 CSD = ${CSD_PER_COIN} base · propose ≥ ${csdToCoins(MIN_FEE_PROPOSE)} · attest ≥ ${csdToCoins(MIN_FEE_ATTEST)} CSD`));
-    console.log(c.gray("  config: CAIRN_API (board) · CAIRN_CSD (csd binary) · CAIRN_ADDR (your addr) · CAIRN_RPC (trustless verify) · CAIRN_TOKEN (operator)"));
+    console.log(c.gray("  config: CAIRN_API (board) · CAIRNX_API (token layer) · CAIRN_CSD (csd binary) · CAIRN_ADDR (your addr) · CAIRN_RPC (trustless verify) · CAIRN_TOKEN (operator)"));
     console.log(c.gray("  display: honors NO_COLOR · --no-color · --no-anim · TERM=dumb (color/animation auto-off when piped)"));
     console.log(c.gray("  writes are signed by your own ") + c.cyan("csd") + c.gray(" wallet (csd wallet new / init); cairn supplies the input + Cairn content. Sealed claims + Sign-in: use the Cairn Wallet."));
 }
@@ -664,7 +854,380 @@ async function main() {
         case "propose":
         case "post": return cmdPropose(a);
         case "support": return cmdSupport(a);
+        case "tokens": return cmdTokens(a);
+        case "token-info":
+        case "token": return cmdTokenInfo(a);
+        case "token-send": return cmdTokenSend(a);
+        case "names": return cmdNames(a);
+        case "name": return cmdName(a);
+        case "gateway": return cmdGateway(a);
+        case "peer": return cmdPeer(a);
+        case "identity": return cmdIdentity(a);
         default: return help();
     }
 }
+// ── L3 registry publish commands (build a signed record → anchor Propose → serve bytes) ──
+// Anchor a built registry record: Propose{domain, payloadHash} signed by the csd wallet,
+// then publish the EXACT canonical bytes to the content origin (self-certified on arrival).
+async function anchorRecord(rec, addr, fee, days, label) {
+    // max-fee sanity: a fixed-floor record anchor should never burn more than the 1 CSD abs cap.
+    if (fee > MAX_FEE_ABS) {
+        console.log(err(`fee ${csdToCoins(fee)} CSD looks abnormally high for a ${label} record (cap ${csdToCoins(MAX_FEE_ABS)} CSD).`) + c.gray(" Lower ") + c.cyan("--fee") + c.gray("."));
+        return false;
+    }
+    const uri = "csd:" + rec.domain.replace(/[^a-z]/gi, "").slice(0, 6) + ":v1:" + rec.payloadHash.slice(2, 14);
+    const input = await pickAndShow(addr, fee, 0, fee);
+    if (!input)
+        return false;
+    const tip = await api.tipHeight().catch(() => 0);
+    const sp = spinner("csd signs → submit");
+    const r = await signAndSubmit(["propose", "--domain", rec.domain, "--payload-hash", rec.payloadHash, "--uri", uri, "--expires-epoch", String(Math.floor(tip / 30) + days * 24), "--fee", String(fee), "--change", addr, "--input", input]);
+    sp.stop();
+    if (!r.ok) {
+        console.log(err(r.error || "failed"));
+        return false;
+    }
+    console.log(ok(`${label} anchored  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)"));
+    const sp2 = spinner("publishing content (waits for the tx to mine)");
+    const done = await api.registerRawContent(canonicalJson(rec.content), r.txid);
+    sp2.stop();
+    console.log(done ? ok("content published — record is now resolvable") : warn("content not published yet — re-run once mined"));
+    return done;
+}
+// Shared setup for the registry commands: require csd, the privkey (to sign the binding
+// locally — never networked), and the address.
+async function registryPrep(a) {
+    if (!(await requireCsd()))
+        return null;
+    const cfg = await csd.walletConfig();
+    const priv = cfg?.default_privkey;
+    if (!priv) {
+        console.log(err("no csd wallet key configured.") + c.gray("  Run ") + c.cyan("csd wallet new"));
+        return null;
+    }
+    const addr = await resolveAddr(a);
+    if (!addr) {
+        console.log(err("could not resolve your address — run ") + c.cyan("cairn setup"));
+        return null;
+    }
+    return { priv, addr };
+}
+async function cmdGateway(a) {
+    if (a._[1] !== "register") {
+        console.log(warn("usage: ") + c.cyan("cairn gateway register --url https://gw/content/0x{hash} [--pin] [--fee 0.25]"));
+        return;
+    }
+    const url = String(a.flags.url ?? "");
+    if (!url.includes("{hash}")) {
+        console.log(err("--url must contain the {hash} template, e.g. https://gw/content/0x{hash}"));
+        return;
+    }
+    const p = await registryPrep(a);
+    if (!p)
+        return;
+    const rec = buildGatewayRecord({ priv: p.priv, url, kind: a.flags.pin ? "pin" : "gateway", address: p.addr });
+    const fee = Math.max(MIN_FEE_PROPOSE, a.flags.fee !== undefined ? CSD(Number(a.flags.fee)) : MIN_FEE_PROPOSE);
+    if (a.flags["dry-run"]) {
+        console.log(`${kdim("domain")} ${c.cyan(rec.domain)}\n${kdim("url")}    ${c.white(url)}\n${kdim("hash")}   ${c.magenta(rec.payloadHash)}`);
+        console.log(c.gray("\n[dry-run] not signed or submitted"));
+        return;
+    }
+    await anchorRecord(rec, p.addr, fee, 10, "gateway");
+}
+async function cmdPeer(a) {
+    if (a._[1] !== "announce") {
+        console.log(warn("usage: ") + c.cyan("cairn peer announce --peer-id <id> --addr /ip4/…/tcp/… [--addr …] [--cap full] [--fee 0.25]"));
+        return;
+    }
+    const peerId = String(a.flags["peer-id"] ?? "");
+    const multiaddrs = (a.multi.addr ?? (a.flags.addr ? [String(a.flags.addr)] : [])).filter(Boolean);
+    if (!peerId || multiaddrs.length === 0) {
+        console.log(err("--peer-id and at least one --addr required"));
+        return;
+    }
+    const p = await registryPrep(a);
+    if (!p)
+        return;
+    const caps = (a.multi.cap ?? (a.flags.cap ? [String(a.flags.cap)] : [])).filter(Boolean);
+    const rec = buildPeerRecord({ priv: p.priv, peer_id: peerId, multiaddrs, caps: caps.length ? caps : undefined, address: p.addr });
+    const fee = Math.max(MIN_FEE_PROPOSE, a.flags.fee !== undefined ? CSD(Number(a.flags.fee)) : MIN_FEE_PROPOSE);
+    if (a.flags["dry-run"]) {
+        console.log(`${kdim("domain")} ${c.cyan(rec.domain)}\n${kdim("peer")}   ${c.white(peerId)}\n${kdim("hash")}   ${c.magenta(rec.payloadHash)}`);
+        console.log(c.gray("\n[dry-run] not signed or submitted"));
+        return;
+    }
+    await anchorRecord(rec, p.addr, fee, 10, "peer");
+}
+async function cmdIdentity(a) {
+    const sub = a._[1];
+    const handle = String(a.flags.handle ?? a._[2] ?? "");
+    if (sub !== "claim" || !handle) {
+        console.log(warn("usage: ") + c.cyan("cairn identity claim <handle> [--salt <hex>] [--commit-only|--reveal] [--fee 0.25]"));
+        console.log(c.gray("  step 1: --commit-only (saves a salt)  ·  step 2 (next epoch): --reveal --salt <hex>"));
+        return;
+    }
+    if (!/^[a-z0-9_.-]{3,32}$/i.test(handle)) {
+        console.log(err("handle must be 3–32 chars [a-z0-9_.-]"));
+        return;
+    }
+    const p = await registryPrep(a);
+    if (!p)
+        return;
+    const fee = Math.max(MIN_FEE_PROPOSE, a.flags.fee !== undefined ? CSD(Number(a.flags.fee)) : MIN_FEE_PROPOSE);
+    if (a.flags.reveal) {
+        const salt = String(a.flags.salt ?? "");
+        if (!/^[0-9a-f]{16,}$/i.test(salt)) {
+            console.log(err("--salt <hex> from your earlier --commit-only step is required to reveal"));
+            return;
+        }
+        const rec = buildIdentityReveal({ priv: p.priv, handle, salt, address: p.addr });
+        if (a.flags["dry-run"]) {
+            console.log(`${kdim("reveal")} ${c.white(handle)} → ${c.cyan(p.addr)}\n${kdim("hash")}   ${c.magenta(rec.payloadHash)}`);
+            console.log(c.gray("\n[dry-run] not signed"));
+            return;
+        }
+        await anchorRecord(rec, p.addr, fee, 90, "identity reveal");
+        return;
+    }
+    // default / --commit-only: step 1
+    const salt = String(a.flags.salt ?? randomBytes(16).toString("hex"));
+    const rec = buildIdentityCommit({ handle, salt, address: p.addr });
+    if (a.flags["dry-run"]) {
+        console.log(`${kdim("commit")} ${c.white(handle)}\n${kdim("salt")}   ${c.magenta(salt)}\n${kdim("hash")}   ${c.magenta(rec.payloadHash)}`);
+        console.log(c.gray("\n[dry-run] not signed"));
+        return;
+    }
+    const okc = await anchorRecord(rec, p.addr, fee, 90, "identity commit");
+    if (okc)
+        console.log(c.gray("\n  save this salt — reveal NEXT epoch (~1h):  ") + c.cyan(`cairn identity claim ${handle} --reveal --salt ${salt}`));
+}
+// ── CairnX: tokens + .csd names (reads via the CairnX state API; the one write —
+//    token-send — anchors a canonical transfer record as a cairnx:v1 Propose) ──
+// Display: base units → human, with thousands grouping. decimals===undefined (a ticker the
+// API doesn't know) falls back to raw base units rather than guessing a scale.
+const group = (s) => s.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+function tokAmt(base, decimals) {
+    if (decimals === undefined)
+        return `${group(String(base))} (base units)`;
+    const [i, f] = baseToHuman(String(base), decimals).split(".");
+    return group(i) + (f ? "." + f : "");
+}
+// The address a CairnX read targets: positional arg → --address/CAIRN_ADDR/csd wallet.
+async function resolveCairnxAddr(a, positional) {
+    if (positional !== undefined) {
+        if (!/^0x[0-9a-fA-F]{40}$/.test(positional)) {
+            console.log(err(`bad address: ${san(positional)}`));
+            return null;
+        }
+        return positional.toLowerCase();
+    }
+    const addr = await resolveAddr(a);
+    if (!addr)
+        console.log(err("no address — pass one (cairn tokens 0x…), or --address, or run ") + c.cyan("cairn setup"));
+    return addr ? addr.toLowerCase() : null;
+}
+// ticker → decimals map from /tokens (best-effort: an unreachable list degrades to raw units).
+async function tokenDecimals() {
+    const list = await cairnxGet("/tokens").catch(() => []);
+    const map = {};
+    for (const t of Array.isArray(list) ? list : [])
+        if (typeof t?.ticker === "string" && Number.isInteger(t?.decimals))
+            map[t.ticker] = t.decimals;
+    return map;
+}
+async function cmdTokens(a) {
+    const addr = await resolveCairnxAddr(a, a._[1]);
+    if (!addr)
+        return;
+    const [acct, dec] = await Promise.all([cairnxGet(`/address/${encodeURIComponent(addr)}`), tokenDecimals()]);
+    if (a.flags.json) {
+        console.log(JSON.stringify(acct, null, 2));
+        return;
+    }
+    banner();
+    rule(`cairnx · ${addr.slice(0, 10)}… · ${String(activeCairnxBase() ?? "").replace(/^https?:\/\//, "")}`);
+    const bals = Object.entries(acct.balances ?? {});
+    if (!bals.length)
+        console.log(c.gray("  no token balances"));
+    for (const [ticker, b] of bals) {
+        const locked = BigInt(String(b.locked ?? "0"));
+        console.log(`  ${c.cyan(pad(san(ticker), 14))} ${c.white(tokAmt(String(b.available ?? "0"), dec[ticker]))}${locked > 0n ? c.gray(` · ${tokAmt(String(b.locked), dec[ticker])} locked in open offers`) : ""}`);
+    }
+    const names = acct.names ?? [];
+    console.log(`\n  ${kdim(".csd names")} ${names.length ? names.map((n) => c.green(san(n))).join(c.gray(" · ")) : c.gray("none")}`);
+}
+async function cmdTokenInfo(a) {
+    const ticker = String(a._[1] ?? "").toUpperCase();
+    if (!TICKER_RE.test(ticker)) {
+        console.log(warn("usage: ") + c.cyan("cairn token-info <TICKER>"));
+        return;
+    }
+    const t = await cairnxGet(`/token/${encodeURIComponent(ticker)}`).catch((e) => { console.log(e.status === 404 ? err(`unknown token ${ticker}`) : err(e.message)); return null; });
+    if (!t)
+        return;
+    banner();
+    rule(`token · ${san(t.ticker)}`);
+    const row = (k, v) => console.log(`  ${kdim(pad(k, 11))} ${v}`);
+    row("name", c.white(san(t.name ?? t.ticker)));
+    row("decimals", c.white(String(t.decimals)));
+    row("supply", `${c.white(tokAmt(String(t.supply), t.decimals))} ${c.gray("max")}`);
+    const minted = BigInt(String(t.minted ?? "0")), supply = BigInt(String(t.supply ?? "0"));
+    row("minted", `${c.white(tokAmt(String(t.minted), t.decimals))}${supply > 0n ? c.gray(` · ${Number((minted * 10000n) / supply) / 100}% of supply`) : ""}`);
+    row("mint", t.mint === "open" ? c.green("open") + c.gray(` · up to ${tokAmt(String(t.mintLimit ?? "0"), t.decimals)} per mint`) : c.gray("issuer-only"));
+    row("deployer", c.gray(san(t.deployer)));
+    row("deployed", c.gray(`height ${Number(t.height)} · id ${san(String(t.deployId ?? "")).slice(0, 22)}…`));
+    // top-10 holders by total (available + locked) — the same reading the explorer shows
+    const holders = Object.entries(t.holders ?? {}).map(([h, b]) => ({ h, total: BigInt(String(b.available ?? "0")) + BigInt(String(b.locked ?? "0")) }))
+        .filter((x) => x.total > 0n).sort((x, y) => (y.total > x.total ? 1 : y.total < x.total ? -1 : 0));
+    console.log(`\n  ${kdim("holders")}    ${c.white(String(holders.length))}${holders.length > 10 ? c.gray(" · top 10") : ""}`);
+    const max = holders[0]?.total ?? 1n;
+    for (const { h, total } of holders.slice(0, 10)) {
+        const pct = minted > 0n ? Number((total * 10000n) / minted) / 100 : 0;
+        console.log(`  ${bar(Number((total * 1000n) / max), 1000)}  ${c.gray(san(h).slice(0, 12) + "…")} ${c.white(tokAmt(total.toString(), t.decimals))} ${c.gray(`· ${pct}%`)}`);
+    }
+}
+// y/N gate for the one CairnX write. Non-interactive runs behave like the CLI's other
+// writes (no prompt — use --dry-run to preview); --yes skips the prompt when interactive.
+async function confirmSend(q) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return true;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ans = await new Promise((res) => rl.question(q, res));
+    rl.close();
+    return /^y(es)?$/i.test(ans.trim());
+}
+async function cmdTokenSend(a) {
+    const ticker = String(a.flags.ticker ?? "").toUpperCase();
+    const to = String(a.flags.to ?? "");
+    const amountStr = String(a.flags.amount ?? "");
+    if (!ticker || !a.flags.to || a.flags.amount === undefined) {
+        console.log(warn("usage: ") + c.cyan("cairn token-send --ticker CAIRN --to 0x…40 --amount 1.5 [--dry-run] [--yes]"));
+        return;
+    }
+    if (!TICKER_RE.test(ticker)) {
+        console.log(err(`bad ticker: ${san(ticker)}`));
+        return;
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(to)) {
+        console.log(err(`bad recipient: ${san(to)}`));
+        return;
+    }
+    // decimals are AUTHORITATIVE from the token's deploy record — never guessed
+    const t = await cairnxGet(`/token/${encodeURIComponent(ticker)}`).catch((e) => { console.log(e.status === 404 ? err(`unknown token ${ticker}`) : err(e.message)); return null; });
+    if (!t)
+        return;
+    let amount;
+    try {
+        amount = humanToBase(amountStr, Number(t.decimals));
+    }
+    catch (e) {
+        console.log(err(e.message));
+        return;
+    }
+    if (amount <= 0n) {
+        console.log(err("amount must be > 0"));
+        return;
+    }
+    const from = await resolveAddr(a);
+    if (!from) {
+        console.log(err("could not resolve your address — pass --address or run ") + c.cyan("cairn setup"));
+        return;
+    }
+    // balance check against the same state the resolver will apply the transfer to
+    const acct = await cairnxGet(`/address/${encodeURIComponent(from.toLowerCase())}`);
+    const avail = BigInt(String(acct.balances?.[ticker]?.available ?? "0"));
+    if (avail < amount) {
+        console.log(err(`insufficient ${ticker}: balance ${tokAmt(avail.toString(), t.decimals)}, tried to send ${tokAmt(amount.toString(), t.decimals)}${BigInt(String(acct.balances?.[ticker]?.locked ?? "0")) > 0n ? ` (${tokAmt(String(acct.balances[ticker].locked), t.decimals)} more is locked in open offers)` : ""}`));
+        return;
+    }
+    let built;
+    try {
+        built = buildTransferRecord({ ticker, to, amount });
+    }
+    catch (e) {
+        console.log(err(e.message));
+        return;
+    }
+    // clear-print exactly what will be anchored before anything signs
+    console.log(`${kdim("send")}    ${c.white(tokAmt(amount.toString(), t.decimals))} ${c.cyan(ticker)} ${c.gray(`(${amount} base units · ${t.decimals} decimals)`)}`);
+    console.log(`${kdim("to")}      ${c.cyan(to.toLowerCase())}`);
+    console.log(`${kdim("from")}    ${c.cyan(from.toLowerCase())} ${c.gray(`· ${ticker} balance ${tokAmt(avail.toString(), t.decimals)}`)}`);
+    console.log(`${kdim("record")}  ${c.white(built.uri)}`);
+    console.log(`${kdim("hash")}    ${c.magenta(built.payloadHash)}`);
+    console.log(`${kdim("anchor")}  ${c.gray(`Propose on ${CAIRNX_DOMAIN} — costs `)}${c.white(csdToCoins(CAIRNX_ANCHOR_FEE) + " CSD")}${c.gray(" (the chain fee; the tokens themselves move by record)")}`);
+    if (a.flags["dry-run"]) {
+        console.log(c.gray("\n[dry-run] not signed or submitted"));
+        return;
+    }
+    if (!(await requireCsd()))
+        return;
+    if (!a.flags.yes && !(await confirmSend(`\nsend ${tokAmt(amount.toString(), t.decimals)} ${ticker} for ${csdToCoins(CAIRNX_ANCHOR_FEE)} CSD? [y/N] `))) {
+        console.log(c.gray("aborted"));
+        return;
+    }
+    if (!(await freshTip(a)))
+        return;
+    const input = await pickAndShow(from, CAIRNX_ANCHOR_FEE, 0, CAIRNX_ANCHOR_FEE);
+    if (!input)
+        return;
+    const tip = await api.tipHeight().catch(() => 0);
+    const sp3 = spinner("csd signs → submit");
+    const r = await signAndSubmit(["propose", "--domain", CAIRNX_DOMAIN, "--payload-hash", built.payloadHash, "--uri", built.uri, "--expires-epoch", String(Math.floor(tip / 30) + 24), "--fee", String(CAIRNX_ANCHOR_FEE), "--change", from, "--input", input]);
+    sp3.stop();
+    console.log(r.ok ? ok(`transfer anchored  ${c.cyan(r.txid)}`) + c.gray("  (tokens move when it mines — check `cairn tokens`)") : err(r.error || "failed"));
+}
+async function cmdNames(a) {
+    const addr = await resolveCairnxAddr(a, a._[1]);
+    if (!addr)
+        return;
+    const acct = await cairnxGet(`/address/${encodeURIComponent(addr)}`);
+    const names = acct.names ?? [];
+    if (a.flags.json) {
+        console.log(JSON.stringify(names, null, 2));
+        return;
+    }
+    banner();
+    rule(`.csd names · ${addr.slice(0, 10)}…`);
+    if (!names.length) {
+        console.log(c.gray("  no names owned — claim one on " + (activeCairnxBase()?.includes("127.0.0.1") ? "the /trade marketplace" : "https://cairn-substrate.com/trade")));
+        return;
+    }
+    for (const n of names)
+        console.log(`  ${c.green(san(n))}`);
+    console.log(c.gray(`\n  ${names.length} name${names.length === 1 ? "" : "s"} · cairn name <name> for detail`));
+}
+async function cmdName(a) {
+    const n = String(a._[1] ?? "").toLowerCase();
+    if (!n || !NAME_RE.test(n)) {
+        console.log(warn("usage: ") + c.cyan("cairn name <name>") + c.gray("  (lowercase, 3–32 chars [a-z0-9-])"));
+        return;
+    }
+    const r = await cairnxGet(`/name/${encodeURIComponent(n)}`).catch((e) => { console.log(e.status === 404 ? err(`unregistered name "${n}"`) + c.gray(" — claimable via commit-reveal on /trade") : err(e.message)); return null; });
+    if (!r)
+        return;
+    banner();
+    rule(`name · ${san(r.name ?? n)}`);
+    const row = (k, v) => console.log(`  ${kdim(pad(k, 10))} ${v}`);
+    row("owner", c.cyan(san(r.owner)));
+    row("claimed", c.gray(`height ${Number(r.height)}${Number(r.effectiveHeight) !== Number(r.height) ? ` · effective ${Number(r.effectiveHeight)}` : ""} · claim ${san(String(r.claimId ?? "")).slice(0, 22)}…`));
+    // lease: the API reports paidThroughEpoch once the v1.5 lease model is live; the ETA is
+    // computed from the chain tip (1 epoch = 30 blocks · 120s target ⇒ ~1h per epoch).
+    if (r.paidThroughEpoch != null) {
+        const tip = await api.tipHeight().catch(() => 0);
+        const blocksLeft = (Number(r.paidThroughEpoch) + 1) * 30 - tip;
+        const eta = !tip ? "" : blocksLeft <= 0 ? " · " + "EXPIRED" : ` · expires in ~${blocksLeft >= 720 ? (blocksLeft / 720).toFixed(1) + " days" : Math.max(1, Math.round(blocksLeft / 30)) + "h"}`;
+        row("lease", `${c.white("paid through epoch " + Number(r.paidThroughEpoch))}${blocksLeft <= 0 && tip ? "  " + err("EXPIRED") : c.gray(eta)}`);
+    }
+    else
+        row("lease", c.gray("— (no lease data from this API)"));
+    if (r.locked)
+        row("locked", c.gray("yes — a sale/transfer is in flight"));
+    if (r.offer) {
+        const want = r.offer.want ?? {};
+        const price = want.value !== undefined ? `${csdToCoins(Number(want.value))} CSD` : `${san(String(want.amount))} ${san(String(want.ticker))}`;
+        row("offer", `${c.green("FOR SALE")} ${c.white("· " + price)} ${c.gray(`· seller ${san(String(r.offer.seller ?? r.owner)).slice(0, 12)}… · offer ${san(String(r.offer.id ?? "")).slice(0, 18)}…${r.offer.taker ? " · reserved for a taker" : ""}`)}`);
+    }
+    else
+        row("offer", c.gray("no open offer"));
+}
 main().catch((e) => { console.error(err(String(e?.message ?? e))); process.exit(1); });