@inversealtruism/cairn-cli 0.2.0 → 0.3.2

package/README.md

@@ -1,11 +1,14 @@
 # cairn-cli
 
-A command-line client for a Cairn signal board on Compute Substrate. Browse what the community is
-backing, and with a token, propose or support items, all from your terminal.
+A command-line client for **Compute Substrate / Cairn** — browse the board, and **send CSD,
+propose, attest, and place stones on the Wall** straight from your terminal.
 
-Cairn is a fee-weighted "paid attention" board: people spend CSD to surface what should be built,
-fixed, or funded. `cairn-cli` is a thin HTTP client for a Cairn instance. Browsing needs no `csd`
-binary and no key files.
+For the people who'd rather not put a key in a browser extension: **cairn-cli never holds your
+key.** Reads are plain HTTP. For writes it drives your **own installed `csd` wallet** — `csd`
+signs with your key (CSD_SIG_V1), and cairn-cli adds the Cairn layer on top: it computes the
+canonical payload hash, fetches a spendable input from the Cairn proxy (so you don't need a
+synced local node), registers your off-chain content, and gives you the board / wall / network
+views the raw `csd` CLI doesn't have. Browsing needs no `csd` binary and no keys.
 
 ## Install
 
@@ -49,32 +52,55 @@ cairn leaderboard            # top builders by reputation
 cairn ls --json              # machine-readable output
 ```
 
-Posting needs a token from the board operator:
+## Wallet (transacting — uses your own `csd` wallet)
+
+One-time: install Compute Substrate's `csd` CLI and create/import your key.
 
 ```bash
-export CAIRN_TOKEN=…         # the instance's write token
-cairn propose --domain csd:features --title "Wallet GUI" --body "A graphical wallet…" --link https://…
-cairn support <id> --fee 5000000 --score 90 --confidence 80
+csd wallet new                          # or: csd wallet init --privkey <your key>
+cairn setup                             # checks csd + wallet, shows your address + balance
 ```
 
+Then transact — cairn-cli builds the request, `csd` signs with your key, and the tx is submitted
+through the Cairn proxy (no local node required):
+
+```bash
+cairn address                           # your address + balance (alias: whoami, balance)
+cairn send --to 0x… --amount 1.5        # transfer CSD (--output 0x…:0.5 ×N for many, --fee <CSD>)
+cairn propose --domain csd:features --title "Wallet GUI" --body "…" --link https://…
+cairn support <id> --fee 0.1 --score 90 --confidence 80
+cairn wall place "gm, Compute Substrate"
+```
+
+Fees and amounts are in **CSD** (e.g. `--amount 1.5`, `--fee 0.05`). Minimums: 0.25 CSD to propose,
+0.05 CSD to attest. Support is a paid demand signal, not a payment to the author; fees go to miners.
+
 ## Configuration (environment variables)
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `CAIRN_API` | `https://cairn-substrate.com` | the board to talk to (use your own, e.g. `http://127.0.0.1:7777`) |
-| `CAIRN_TOKEN` | – | required only to post (propose or support) |
-| `CAIRN_RPC` | – | optional csd node RPC; enables fully trustless `verify` by recomputing the hash and confirming the one on-chain |
+| `CAIRN_API` | `https://cairn-substrate.com` | the board / proxy to talk to (use your own, e.g. `http://127.0.0.1:7777`) |
+| `CAIRN_CSD` | `csd` | path to your installed `csd` binary (signs your transactions) |
+| `CAIRN_ADDR` | – | your public addr20; skips deriving it from the csd wallet |
+| `CAIRN_RPC` | – | optional csd node RPC; enables fully trustless `verify` (recompute the hash + confirm on-chain) |
+| `CAIRN_TOKEN` | – | board-operator write token (operator convenience; normal users sign with `csd` instead) |
 
 ## How it works
 
-- `browse`, `show`, `recent`, and `watch` read the board's public API.
+- `browse`, `show`, `recent`, `watch`, `wall`, `network`, `quests` read the board's public API.
 - `verify` fetches an item, recomputes `sha256(canonical content)` locally, and if `CAIRN_RPC` is set,
   confirms that hash is the one committed on-chain. You trust the math, not the server.
-- `propose` and `support` post through the instance, which records the item and submits the on-chain
-  proposal or attestation. Fees go to miners. Support is a paid demand signal, not a payment to the
-  author.
-
-Fees are in base units (1 CSD = 1e8). Minimums are 0.25 CSD to propose and 0.05 CSD to attest.
+- `send` / `propose` / `support` / `wall place`: cairn-cli fetches a spendable input from the Cairn
+  proxy, hands it to **your** `csd` (which signs with your wallet key — for these commands the key
+  stays inside `csd` and never enters the cairn-cli process), then submits the signed transaction
+  through the proxy and (for proposals) registers the off-chain content. Sealed claims and
+  Sign-in-with-CSD live in the Cairn Wallet.
+- **L3 registry commands** (`gateway register`, `peer announce`, `identity claim`) are the one
+  exception: they sign a registry *binding* with `@inversealtruism/csd-registry`, so cairn-cli reads
+  your private key from `csd wallet config` and signs **in-process** (the key is never networked — only
+  the signed canonical content is published). Because these load key material into the Node process,
+  the `csd-registry` / `csd-codec` dependencies are **pinned to exact versions** (no caret ranges) to
+  shrink the supply-chain surface. If you only ever `send`/`propose`/`support`, your key never leaves `csd`.
 
 ## License
 

package/dist/cli.js

@@ -1,10 +1,86 @@
 #!/usr/bin/env node
 // cairn — command-line client for a Cairn signal board on Compute Substrate.
 // Reads are public; posting needs CAIRN_TOKEN. Config via env: CAIRN_API, CAIRN_TOKEN, CAIRN_RPC.
-import { CAIRN_API, MIN_FEE_PROPOSE, MIN_FEE_ATTEST, CSD_PER_COIN, csdToCoins } from "./lib/config.js";
+import { CAIRN_API, CAIRN_ADDR, CAIRN_TOKEN, CAIRN_RPC, MIN_FEE_PROPOSE, MIN_FEE_ATTEST, CSD_PER_COIN, csdToCoins, loadLocalConfig, saveLocalConfig } from "./lib/config.js";
 import * as api from "./lib/api.js";
+import * as csd from "./lib/csd.js";
 import { buildCommitment } from "./lib/item.js";
-import { c, banner, bannerAnimated, rule, badge, bar, csd as csdFmt, ok, warn, err, key as kdim, pad, spinner, sleep, isTty, clearScreen } from "./lib/ui.js";
+import { buildGatewayRecord, buildPeerRecord, buildIdentityCommit, buildIdentityReveal } from "@inversealtruism/csd-registry";
+import { canonicalJson } from "@inversealtruism/csd-codec";
+import { randomBytes } from "node:crypto";
+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
+// 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.
+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;
+    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).
+    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;
+    }
+    if (cfg?.default_privkey) {
+        const addr = await csd.deriveAddr(cfg.default_privkey);
+        if (addr) {
+            saveLocalConfig({ address: addr });
+            return addr;
+        }
+    }
+    return null;
+}
+// Run a csd build/sign command (easy-path propose/attest/spend — they sign with the user's
+// wallet CONFIG key, so we pass no key) and submit the resulting signed tx through the Cairn
+// 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.
+async function signAndSubmit(csdArgs) {
+    const r = await csd.run(csdArgs);
+    if (!r.ok)
+        return { ok: false, error: (r.stderr || r.stdout || "csd failed").trim().split("\n").slice(-1)[0] };
+    let out = null;
+    try {
+        out = JSON.parse(r.stdout);
+    }
+    catch { /* unexpected */ }
+    if (!out?.tx)
+        return { ok: false, error: "csd produced no signed transaction" };
+    const txid = out.txid;
+    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 ?? "")))
+        return { ok: true, txid };
+    return { ok: false, error: sub.err || "submit rejected by node", txid };
+}
+// Guard: a write needs `csd` installed + a configured wallet (or an explicit --address + csd key).
+async function requireCsd() {
+    if (!(await csd.available())) {
+        console.log(err("`csd` not found.") + c.gray("  Install the Compute Substrate CLI, then ") + c.cyan("csd wallet new") + c.gray(" / ") + c.cyan("csd wallet init --privkey <key>") + c.gray(". Or set CAIRN_CSD to its path."));
+        return false;
+    }
+    const cfg = await csd.walletConfig();
+    if (!cfg?.default_privkey) {
+        console.log(err("no csd wallet key configured.") + c.gray("  Run ") + c.cyan("csd wallet new") + c.gray(" then ") + c.cyan("csd wallet init --privkey <key>") + c.gray(" — cairn signs with your csd wallet."));
+        return false;
+    }
+    return true;
+}
 function parse(argv) {
     const _ = [];
     const flags = {};
@@ -27,6 +103,16 @@ 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).
+function sameHost(a, b) {
+    try {
+        return new URL(a).host.toLowerCase() === new URL(b).host.toLowerCase();
+    }
+    catch {
+        return true;
+    }
+}
 const age = (sec) => {
     if (!sec)
         return "—";
@@ -50,9 +136,9 @@ function printRows(items, sort = "totalWeight") {
         const lens = !["totalWeight", "supporterCount"].includes(sort) && r[sort] != null
             ? c.gray(" · " + (sort === "createdHeight" ? "h" + r[sort] : csdFmt(r[sort]) + " " + sort)) : "";
         console.log("");
-        console.log(`  ${c.magenta(c.bold("#" + (i + 1)))}  ${c.white(c.bold(r.title))}  ${badge(r.source)}${r.sealed ? "  " + c.gray(r.revealed ? "🔓 revealed" : "🔒 sealed") : ""}`);
-        console.log(`      ${bar(r[sort] || r.totalWeight, max)}  ${csdFmt(r.totalWeight)} ${c.gray("·")} ${c.green(String(r.supporterCount))} ${c.gray("supporters · score " + r.avgScore + " · " + age(r.createdTime) + " ago")}${lens}`);
-        console.log(c.gray(`      ${r.domain} · id ${String(r.id).slice(0, 22)}…`));
+        console.log(`  ${c.magenta(c.bold("#" + (i + 1)))}  ${c.white(c.bold(san(r.title)))}  ${badge(r.source)}${r.sealed ? "  " + c.gray(r.revealed ? "🔓 revealed" : "🔒 sealed") : ""}`);
+        console.log(`      ${bar(r[sort] || r.totalWeight, max)}  ${csdFmt(r.totalWeight)} ${c.gray("·")} ${c.green(String(r.supporterCount))} ${c.gray("supporters · score " + Number(r.avgScore) + " · " + age(r.createdTime) + " ago")}${lens}`);
+        console.log(c.gray(`      ${san(r.domain)} · id ${san(String(r.id).slice(0, 22))}…`));
     });
 }
 async function cmdList(a) {
@@ -78,16 +164,34 @@ async function cmdWatch(a) {
         printRows((await api.apiBoard(domain, window)).items);
         return;
     }
-    process.stdout.write("\x1b[?25l");
-    process.on("SIGINT", () => { process.stdout.write("\x1b[?25h\n"); process.exit(0); });
+    const PERIOD = 5; // seconds between refreshes
+    const PULSE = ["◐", "◓", "◑", "◒"]; // a spinning "live" mark in the footer
+    process.stdout.write("\x1b[?25l"); // hide cursor
+    const restore = () => process.stdout.write("\x1b[?25h\n");
+    process.on("SIGINT", () => { restore(); process.exit(0); });
+    clearScreen();
+    let first = true;
     for (;;) {
         const r = await api.apiBoard(domain, window).catch(() => ({ items: [] }));
-        clearScreen();
+        // first paint clears the screen; subsequent paints repaint from home (no black flash)
+        if (first) {
+            clearScreen();
+            first = false;
+        }
+        else
+            cursorHome();
         banner();
         rule(`watch · ${domain} · ${window} · ${new Date().toLocaleTimeString()}`);
         printRows(r.items);
-        console.log(c.gray("\n  ") + c.green("●") + c.gray(" live · refreshes every 5s · Ctrl+C to exit"));
-        await sleep(5000);
+        process.stdout.write("\n"); // reserve the footer line, then redraw it in place each second
+        // animated footer: a phosphor pulse + a "next refresh" countdown (single line, \r-redrawn)
+        for (let s = PERIOD; s > 0; s--) {
+            const mark = c.green(PULSE[(PERIOD - s) % PULSE.length]);
+            process.stdout.write(`\r\x1b[K  ${mark} ${c.gray("live · " + (r.items?.length ?? 0) + " items · next refresh in " + s + "s · Ctrl+C to exit")}`);
+            await sleep(anim ? 1000 : PERIOD * 1000);
+            if (!anim)
+                break;
+        }
     }
 }
 async function cmdRecent() {
@@ -96,7 +200,7 @@ async function cmdRecent() {
     rule("recent activity");
     for (const ev of r.activity ?? []) {
         const verb = ev.type === "support" ? c.green("◈ supported") : c.cyan("✎ proposed ");
-        console.log(`  ${verb} ${c.white(String(ev.item).slice(0, 42))} ${c.gray("· " + age(ev.time) + " ago · " + (ev.amount / 1e8) + " CSD")}`);
+        console.log(`  ${verb} ${c.white(san(String(ev.item).slice(0, 42)))} ${c.gray("· " + age(ev.time) + " ago · " + (Number(ev.amount) / 1e8) + " CSD")}`);
     }
 }
 async function cmdShow(a) {
@@ -111,15 +215,15 @@ async function cmdShow(a) {
         return;
     }
     const it = r.item;
-    rule(it.title);
-    console.log(`  ${badge(it.source)}  ${c.gray("·")}  ${c.cyan(it.domain)}`);
-    console.log(`\n  ${c.white(it.body)}\n`);
+    rule(san(it.title));
+    console.log(`  ${badge(it.source)}  ${c.gray("·")}  ${c.cyan(san(it.domain))}`);
+    console.log(`\n  ${c.white(san(it.body))}\n`);
     if (it.links?.length)
-        console.log(`  ${kdim("links")}     ${it.links.map((l) => c.cyan(l)).join(", ")}`);
-    const total = (r.supports ?? []).reduce((x, s) => x + s.weight, 0);
+        console.log(`  ${kdim("links")}     ${it.links.map((l) => c.cyan(san(l))).join(", ")}`);
+    const total = (r.supports ?? []).reduce((x, s) => x + Number(s.weight), 0);
     console.log(`  ${kdim("support")}   ${csdFmt(total)} ${c.gray("from")} ${c.green(String(new Set((r.supports ?? []).map((s) => s.attester)).size))} ${c.gray("supporters")}`);
-    console.log(`  ${kdim("proposer")}  ${c.gray(it.proposerHandle || it.proposer)}`);
-    console.log(`  ${kdim("hash")}      ${c.magenta(it.payloadHash)}`);
+    console.log(`  ${kdim("proposer")}  ${c.gray(san(it.proposerHandle || it.proposer))}`);
+    console.log(`  ${kdim("hash")}      ${c.magenta(san(it.payloadHash))}`);
     console.log(`  ${kdim("integrity")} ${r.integrityOk ? ok("content matches commitment") : err("MISMATCH")}`);
 }
 async function cmdVerify(a) {
@@ -136,21 +240,136 @@ async function cmdVerify(a) {
         return;
     }
     const it = r.item;
+    // Hash the RAW server-reported content (never san()'d — we must hash the exact bytes).
     const { payloadHash } = buildCommitment({ v: 1, domain: it.domain, title: it.title, body: it.body, links: it.links ?? [] });
-    const chain = await api.chainProposal(it.id);
+    // Only consult the chain RPC for a well-formed id (the server echoes it.id back; an
+    // attacker-shaped id must not be spliced into the RPC URL — see api.chainProposal).
+    const chain = /^0x[0-9a-fA-F]{64}$/.test(String(it.id ?? "")) ? await api.chainProposal(it.id) : null;
     sp.stop();
     console.log(`${kdim("recomputed")}  ${c.magenta(payloadHash)}`);
-    console.log(`${kdim("reported")}    ${c.magenta(it.payloadHash)}`);
+    console.log(`${kdim("reported")}    ${c.magenta(san(it.payloadHash))}`);
     const contentOk = payloadHash.toLowerCase() === String(it.payloadHash).toLowerCase();
     if (chain?.payload_hash) {
-        console.log(`${kdim("on-chain")}    ${c.magenta(chain.payload_hash)}`);
-        console.log(contentOk && String(chain.payload_hash).toLowerCase() === payloadHash.toLowerCase()
-            ? ok("VERIFIED — content matches the on-chain commitment (trustless, via CAIRN_RPC)")
-            : err("MISMATCH"));
+        // "trustless" only holds if CAIRN_RPC is an INDEPENDENT node — if it's the same host as
+        // the board API, the same operator controls both answers, so don't claim trustlessness.
+        const independent = !sameHost(CAIRN_RPC, CAIRN_API);
+        const chainOk = contentOk && String(chain.payload_hash).toLowerCase() === payloadHash.toLowerCase();
+        console.log(`${kdim("on-chain")}    ${c.magenta(san(chain.payload_hash))}`);
+        if (chainOk)
+            console.log(independent
+                ? ok("VERIFIED — content matches the on-chain commitment (trustless, via an independent CAIRN_RPC)")
+                : ok("content matches the commitment reported by this RPC") + c.gray("  ⚠ CAIRN_RPC shares a host with CAIRN_API — point it at an independent node for a trustless check"));
+        else
+            console.log(err("MISMATCH"));
     }
     else {
-        console.log(contentOk ? ok("content matches the reported commitment") + c.gray("  (set CAIRN_RPC to also check the chain directly)") : err("content does NOT match the reported hash"));
+        console.log(contentOk ? ok("content matches the reported commitment") + c.gray("  (set CAIRN_RPC to an independent node to also check the chain directly)") : err("content does NOT match the reported hash"));
+    }
+}
+// ── wallet (on top of the user's installed `csd` — cairn never holds the key) ──
+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")}`);
+    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;
+    }
+    const cfg = await csd.walletConfig();
+    console.log(`  ${kdim("csd wallet")}  ${cfg?.default_privkey ? ok("key configured") : warn("no key — run ") + c.cyan("csd wallet new") + c.gray(" then ") + c.cyan("csd wallet init --privkey <key>")}`);
+    const addr = await resolveAddr(a0());
+    if (addr) {
+        console.log(`  ${kdim("address")}     ${c.cyan(addr)}`);
+        const b = await api.confirmedBalance(addr).catch(() => null);
+        if (b)
+            console.log(`  ${kdim("balance")}     ${c.white(csdToCoins(b.balance))} CSD ${c.gray("(" + b.utxos + " utxos)")}`);
     }
+    console.log(`  ${kdim("api")}         ${c.gray(CAIRN_API)}`);
+    if (has && cfg?.default_privkey)
+        console.log(c.gray("\n  ready: ") + c.cyan("cairn send · cairn propose · cairn support · cairn wall place"));
+}
+const a0 = () => ({ _: [], flags: {}, multi: {} });
+async function cmdAddress(a) {
+    const addr = await resolveAddr(a);
+    if (!addr) {
+        console.log(err("no address — run ") + c.cyan("cairn setup") + err(" (needs a configured csd wallet) or pass --address"));
+        return;
+    }
+    if (!isTty) {
+        console.log(addr);
+        return;
+    }
+    banner();
+    rule("your address");
+    console.log(`  ${kdim("address")}  ${c.cyan(addr)}`);
+    const b = await api.confirmedBalance(addr).catch(() => null);
+    if (b)
+        console.log(`  ${kdim("balance")}  ${c.white(csdToCoins(b.balance))} CSD ${c.gray("(" + b.utxos + " utxos)")}`);
+}
+async function cmdBalance(a) { return cmdAddress(a); }
+function gatherOutputs(a) {
+    const outs = [];
+    for (const spec of (a.multi.output ?? [])) {
+        const i = String(spec).lastIndexOf(":");
+        if (i < 0)
+            return `bad --output (want <addr>:<CSD>): ${spec}`;
+        outs.push({ to: String(spec).slice(0, i), value: CSD(Number(String(spec).slice(i + 1))) });
+    }
+    if (a.flags.to !== undefined || a.flags.amount !== undefined)
+        outs.push({ to: String(a.flags.to ?? ""), value: CSD(Number(a.flags.amount ?? 0)) });
+    for (const o of outs) {
+        if (!/^0x[0-9a-fA-F]{40}$/.test(o.to))
+            return `bad recipient: ${o.to}`;
+        if (!(o.value > 0) || !Number.isSafeInteger(o.value))
+            return `bad amount for ${o.to}`;
+    }
+    return outs.length ? outs : "no outputs";
+}
+async function cmdSend(a) {
+    const outs = gatherOutputs(a);
+    if (typeof outs === "string") {
+        console.log(outs === "no outputs" ? warn("usage: ") + c.cyan("cairn send --to <0x…40> --amount <CSD> [--fee <CSD>]") + c.gray("  (repeat --output <a>:<CSD> for many)") : err(outs));
+        return;
+    }
+    if (!(await requireCsd()))
+        return;
+    const addr = await resolveAddr(a);
+    if (!addr) {
+        console.log(err("could not resolve your address — pass --address or run ") + c.cyan("cairn setup"));
+        return;
+    }
+    const feeCsd = a.flags.fee !== undefined ? Number(a.flags.fee) : 0.01;
+    const fee = (Number.isFinite(feeCsd) && feeCsd >= 0) ? CSD(feeCsd) : 1_000_000;
+    const total = outs.reduce((s, o) => s + o.value, 0);
+    console.log(`${kdim("from")}    ${c.cyan(addr)}`);
+    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`);
+    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)"));
+        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);
+    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"));
 }
 async function cmdPropose(a) {
     const domain = String(a.flags.domain ?? "");
@@ -158,60 +377,152 @@ async function cmdPropose(a) {
     const body = String(a.flags.body ?? "");
     const links = a.multi.link ?? [];
     if (!domain || !title) {
-        console.log(warn("usage: ") + c.cyan("cairn propose --domain csd:features --title <t> --body <b> [--link <url>] [--fee <base>]"));
+        console.log(warn("usage: ") + c.cyan("cairn propose --domain csd:features --title <t> --body <b> [--link <url>] [--fee <CSD>] [--expires-days N]"));
         return;
     }
-    const fee = Number(a.flags.fee ?? MIN_FEE_PROPOSE);
-    const sp = spinner("posting to Cairn");
-    try {
-        const r = await api.apiPropose({ domain, title, body, links, fee: Number.isFinite(fee) && fee >= MIN_FEE_PROPOSE ? Math.floor(fee) : MIN_FEE_PROPOSE });
-        sp.stop();
-        console.log(r.ok ? ok(`proposed  ${c.cyan(r.id)}`) : err(r.error || "failed"));
+    const feeCsd = a.flags.fee !== undefined ? Number(a.flags.fee) : 0.25;
+    const fee = Math.max(MIN_FEE_PROPOSE, Number.isFinite(feeCsd) ? CSD(feeCsd) : MIN_FEE_PROPOSE);
+    // operator-token path stays available for the instance operator
+    if (CAIRN_TOKEN && !(await csd.available())) {
+        const sp = spinner("posting via operator token");
+        try {
+            const r = await api.apiPropose({ domain, title, body, links, fee });
+            sp.stop();
+            console.log(r.ok ? ok(`proposed  ${c.cyan(r.id)}`) + c.gray("  (operator)") : err(r.error || "failed"));
+        }
+        catch (e) {
+            sp.stop();
+            console.log(err(e.message));
+        }
+        return;
     }
-    catch (e) {
+    if (!(await requireCsd()))
+        return;
+    const addr = await resolveAddr(a);
+    if (!addr) {
+        console.log(err("could not resolve your address — pass --address or run ") + c.cyan("cairn setup"));
+        return;
+    }
+    const content = { v: 1, domain, title, body, links };
+    const { payloadHash } = buildCommitment(content);
+    const uri = "cairn:v1:" + payloadHash.slice(2, 14);
+    if (a.flags["dry-run"]) {
+        console.log(`${kdim("domain")}   ${c.cyan(domain)}`);
+        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)}`);
+        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(e.message));
+        console.log(err("no confirmed UTXO above the fee") + c.gray(" — fund " + addr));
+        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]);
+    sp.stop();
+    if (!r.ok) {
+        console.log(err(r.error || "failed"));
+        return;
+    }
+    console.log(ok(`proposed  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)"));
+    const sp2 = spinner("registering content (waits for the tx to mine)");
+    const done = await api.registerContent({ domain, title, body, links }, r.txid);
+    sp2.stop();
+    console.log(done ? ok("content registered — visible on the board") : warn("content not registered yet — re-run once mined"));
 }
 async function cmdSupport(a) {
     const id = a._[1];
     if (!id) {
-        console.log(warn("usage: ") + c.cyan("cairn support <id> --fee <base> [--score 0-100] [--confidence 0-100]"));
+        console.log(warn("usage: ") + c.cyan("cairn support <id> --fee <CSD> [--score 0-100] [--confidence 0-100]"));
         return;
     }
-    const fee = Number(a.flags.fee ?? MIN_FEE_ATTEST);
-    const sp = spinner("posting support to Cairn");
-    try {
-        const r = await api.apiSupport({ id, fee: Number.isFinite(fee) && fee >= MIN_FEE_ATTEST ? Math.floor(fee) : MIN_FEE_ATTEST, score: Number(a.flags.score ?? 75), confidence: Number(a.flags.confidence ?? 60) });
-        sp.stop();
-        console.log(r.ok ? ok(`supported  ${c.cyan(r.id)}`) : err(r.error || "failed"));
+    if (!/^0x[0-9a-fA-F]{64}$/.test(id)) {
+        console.log(err("proposal id must be 0x…64-hex"));
+        return;
     }
-    catch (e) {
+    const feeCsd = a.flags.fee !== undefined ? Number(a.flags.fee) : 0.05;
+    const fee = Math.max(MIN_FEE_ATTEST, Number.isFinite(feeCsd) ? CSD(feeCsd) : MIN_FEE_ATTEST);
+    const score = Math.max(0, Math.min(100, parseInt(String(a.flags.score ?? 75)) || 0));
+    const confidence = Math.max(0, Math.min(100, parseInt(String(a.flags.confidence ?? 60)) || 0));
+    if (CAIRN_TOKEN && !(await csd.available())) {
+        const sp = spinner("posting via operator token");
+        try {
+            const r = await api.apiSupport({ id, fee, score, confidence });
+            sp.stop();
+            console.log(r.ok ? ok(`supported  ${c.cyan(r.id)}`) + c.gray("  (operator)") : err(r.error || "failed"));
+        }
+        catch (e) {
+            sp.stop();
+            console.log(err(e.message));
+        }
+        return;
+    }
+    if (!(await requireCsd()))
+        return;
+    const addr = await resolveAddr(a);
+    if (!addr) {
+        console.log(err("could not resolve your address — pass --address or run ") + c.cyan("cairn setup"));
+        return;
+    }
+    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)}`);
+        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(e.message));
+        console.log(err("no confirmed UTXO above the fee") + c.gray(" — fund " + addr));
+        return;
     }
+    const r = await signAndSubmit(["attest", "--proposal-id", id, "--score", String(score), "--confidence", String(confidence), "--fee", String(fee), "--change", addr, "--input", picked.input]);
+    sp.stop();
+    console.log(r.ok ? ok(`supported  ${c.cyan(r.txid)}`) + c.gray("  (signed by your csd wallet)") : err(r.error || "failed"));
+}
+async function cmdWall(a) {
+    if (a._[1] === "place") {
+        const msg = a._.slice(2).join(" ").trim() || String(a.flags.message ?? "").trim();
+        if (!msg) {
+            console.log(warn("usage: ") + c.cyan('cairn wall place "<message>" [--fee <CSD>] [--dry-run]'));
+            return;
+        }
+        // forward the write-relevant flags (fee, address, dry-run) through to the propose path
+        const fwd = { domain: "cairn:wall", title: msg };
+        for (const k of ["fee", "address", "dry-run"])
+            if (a.flags[k] !== undefined)
+                fwd[k] = a.flags[k];
+        return cmdPropose({ _: ["propose"], flags: fwd, multi: {} });
+    }
+    return cmdWallView();
 }
 async function cmdDomains() {
     const r = await api.apiDomains();
     banner();
     rule("categories");
     for (const dom of r.domains ?? [])
-        console.log(`  ${c.cyan(pad(dom.key, 20))} ${c.white(dom.title)} ${c.gray(dom.count != null ? "(" + dom.count + ")" : "")}`);
+        console.log(`  ${c.cyan(pad(san(dom.key), 20))} ${c.white(san(dom.title))} ${c.gray(dom.count != null ? "(" + Number(dom.count) + ")" : "")}`);
     // open domains: anyone can create one by proposing into it (cairn ls <domain> works for any).
     const disc = r.discovered ?? [];
     if (disc.length) {
         console.log(c.gray("\n  open domains (created by proposing into them):"));
         for (const d of disc)
-            console.log(`  ${c.cyan(pad(d.key, 20))} ${c.gray((d.count != null ? d.count + " items" : "") + (d.totalWeight ? " · " + csdToCoins(d.totalWeight) + " CSD" : ""))}`);
+            console.log(`  ${c.cyan(pad(san(d.key), 20))} ${c.gray((d.count != null ? Number(d.count) + " items" : "") + (d.totalWeight ? " · " + csdToCoins(d.totalWeight) + " CSD" : ""))}`);
     }
 }
-async function cmdWall() {
+async function cmdWallView() {
     const r = await api.apiWall();
     const stones = r.stones ?? [];
     banner();
     rule(`the wall · ${r.totals?.stones ?? 0} stones · ${r.totals?.boosts ?? 0} boosts · epoch ${r.epoch ?? "?"}`);
     if (r.king)
-        console.log(`  ${c.green("★ KING")}  ${c.white(c.bold(r.king.message))}  ${csdFmt(r.king.weight)} ${c.gray("· " + r.king.boosts + " boosts")}`);
+        console.log(`  ${c.green("★ KING")}  ${c.white(c.bold(san(r.king.message)))}  ${csdFmt(r.king.weight)} ${c.gray("· " + Number(r.king.boosts) + " boosts")}`);
     if (!stones.length) {
         console.log(c.gray("\n  no stones yet — place one with the Cairn Wallet, or:"));
         console.log(c.green("  cairn propose --domain cairn:wall --title '<message>'"));
@@ -220,8 +531,8 @@ async function cmdWall() {
     const max = stones[0]?.weight || 1;
     stones.slice(0, 25).forEach((s, i) => {
         console.log("");
-        console.log(`  ${c.magenta(c.bold("#" + (i + 1)))}  ${c.white(c.bold(s.message))}${i === 0 ? "  " + c.green("★") : ""}`);
-        console.log(`      ${bar(s.weight, max)}  ${csdFmt(s.weight)} ${c.gray("·")} ${c.green(String(s.boosts))} ${c.gray("boosts · " + age(s.ts) + " ago")}${(s.tags && s.tags.length) ? c.gray("  #" + s.tags.join(" #")) : ""}`);
+        console.log(`  ${c.magenta(c.bold("#" + (i + 1)))}  ${c.white(c.bold(san(s.message)))}${i === 0 ? "  " + c.green("★") : ""}`);
+        console.log(`      ${bar(s.weight, max)}  ${csdFmt(s.weight)} ${c.gray("·")} ${c.green(String(s.boosts))} ${c.gray("boosts · " + age(s.ts) + " ago")}${(s.tags && s.tags.length) ? c.gray("  #" + s.tags.map((t) => san(t)).join(" #")) : ""}`);
     });
 }
 async function cmdNetwork() {
@@ -258,14 +569,14 @@ async function cmdProfile(a) {
     }
     const p = r.profile || {}, rep = r.reputation || {};
     banner();
-    rule(`profile · ${p.handle || addr}`);
+    rule(`profile · ${san(p.handle || addr)}`);
     if (p.handle)
-        console.log(`  ${kdim(pad("handle", 13))} ${c.white(p.handle)}`);
+        console.log(`  ${kdim(pad("handle", 13))} ${c.white(san(p.handle))}`);
     if (p.bio)
-        console.log(`  ${kdim(pad("bio", 13))} ${c.gray(p.bio)}`);
+        console.log(`  ${kdim(pad("bio", 13))} ${c.gray(san(p.bio))}`);
     if (p.github)
-        console.log(`  ${kdim(pad("github", 13))} ${c.cyan(p.github)} ${p.githubVerified ? ok("verified") : c.gray("(unverified)")}`);
-    console.log(`  ${kdim(pad("address", 13))} ${c.gray(p.addr || addr)}`);
+        console.log(`  ${kdim(pad("github", 13))} ${c.cyan(san(p.github))} ${p.githubVerified ? ok("verified") : c.gray("(unverified)")}`);
+    console.log(`  ${kdim(pad("address", 13))} ${c.gray(san(p.addr || addr))}`);
     console.log(`  ${kdim(pad("trust", 13))} ${c.white((rep.trust ?? 0).toFixed(2))}`);
     console.log(`  ${kdim(pad("work", 13))} ${c.green(String(rep.proposed ?? 0))} proposed ${c.gray("·")} ${c.green(String(rep.shipped ?? 0))} shipped ${c.gray("·")} ${c.green(String(rep.acceptedWork ?? 0))} accepted ${c.gray("·")} ${c.green(String(rep.reviews ?? 0))} reviews`);
 }
@@ -279,7 +590,7 @@ async function cmdLeaderboard() {
         return;
     }
     lb.slice(0, 25).forEach((e, i) => {
-        console.log(`  ${c.magenta(c.bold(pad("#" + (i + 1), 4)))} ${c.white(pad(e.handle || e.addr, 26))} ${c.gray("trust")} ${c.white((e.trust ?? 0).toFixed(2))} ${c.gray("· " + (e.shipped ?? e.acceptedWork ?? 0) + " shipped · " + (e.proposed ?? 0) + " proposed")}`);
+        console.log(`  ${c.magenta(c.bold(pad("#" + (i + 1), 4)))} ${c.white(pad(san(e.handle || e.addr), 26))} ${c.gray("trust")} ${c.white((Number(e.trust) || 0).toFixed(2))} ${c.gray("· " + Number(e.shipped ?? e.acceptedWork ?? 0) + " shipped · " + Number(e.proposed ?? 0) + " proposed")}`);
     });
 }
 async function cmdQuests() {
@@ -294,9 +605,9 @@ async function cmdQuests() {
     qs.slice(0, 25).forEach((q, i) => {
         const reward = q.quest?.reward?.build ? csdToCoins(q.quest.reward.build) + " CSD" : "—";
         console.log("");
-        console.log(`  ${c.magenta(c.bold("#" + (i + 1)))} ${c.white(c.bold(q.title))} ${c.gray("· " + (q.status || "?"))}`);
-        console.log(`      ${c.gray("reward " + reward + " · demand " + csdFmt(q.demandWeight || 0) + " · " + (q.demandSupporters || 0) + " backers")}`);
-        console.log(c.gray(`      id ${String(q.id).slice(0, 22)}…`));
+        console.log(`  ${c.magenta(c.bold("#" + (i + 1)))} ${c.white(c.bold(san(q.title)))} ${c.gray("· " + san(q.status || "?"))}`);
+        console.log(`      ${c.gray("reward " + reward + " · demand " + csdFmt(q.demandWeight || 0) + " · " + Number(q.demandSupporters || 0) + " backers")}`);
+        console.log(c.gray(`      id ${san(String(q.id).slice(0, 22))}…`));
     });
 }
 async function help() {
@@ -315,13 +626,19 @@ async function help() {
     cmd("quests", "", "open quests");
     cmd("profile", "<addr>", "identity + reputation");
     cmd("leaderboard", "", "top builders by reputation");
-    cmd("propose", "--domain <d> --title <t> --body <b>", "post an item (needs CAIRN_TOKEN)");
-    cmd("support", "<id> --fee <base>", "back an item (needs CAIRN_TOKEN)");
+    cmd("wall place", '"<message>"', "place a stone on the Wall (a cairn:wall proposal)");
+    console.log("");
+    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("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(c.gray("\n  lenses (--sort): " + Object.keys(LENS).join(" · ")));
-    console.log(c.gray(`  api: ${CAIRN_API}  ·  1 CSD = ${CSD_PER_COIN} base · propose ≥ ${MIN_FEE_PROPOSE} · attest ≥ ${MIN_FEE_ATTEST}`));
-    console.log(c.gray("  config: CAIRN_API (board url) · CAIRN_TOKEN (instance write token, to post) · CAIRN_RPC (trustless verify)"));
+    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("  display: honors NO_COLOR · --no-color · --no-anim · TERM=dumb (color/animation auto-off when piped)"));
-    console.log(c.gray("  keyless non-custodial posting + sealed claims: use the Cairn Wallet (browser extension)."));
+    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."));
 }
 async function main() {
     const a = parse(process.argv.slice(2));
@@ -334,16 +651,159 @@ async function main() {
         case "recent": return cmdRecent();
         case "show": return cmdShow(a);
         case "verify": return cmdVerify(a);
-        case "wall": return cmdWall();
+        case "wall": return cmdWall(a);
         case "network":
         case "stats": return cmdNetwork();
         case "quests": return cmdQuests();
         case "profile": return cmdProfile(a);
         case "leaderboard":
         case "lb": return cmdLeaderboard();
-        case "propose": return cmdPropose(a);
+        case "setup":
+        case "doctor": return cmdSetup();
+        case "address":
+        case "whoami": return cmdAddress(a);
+        case "balance": return cmdBalance(a);
+        case "send": return cmdSend(a);
+        case "propose":
+        case "post": return cmdPropose(a);
         case "support": return cmdSupport(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) {
+    const uri = "csd:" + rec.domain.replace(/[^a-z]/gi, "").slice(0, 6) + ":v1:" + rec.payloadHash.slice(2, 14);
+    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));
+        return false;
+    }
+    const tip = await api.tipHeight().catch(() => 0);
+    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", picked.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}`));
+}
 main().catch((e) => { console.error(err(String(e?.message ?? e))); process.exit(1); });

package/dist/lib/api.js

@@ -19,6 +19,10 @@ function writeReq(path, body) {
         throw new Error("posting needs a token — set CAIRN_TOKEN (the operator's write token)");
     return req(path, {
         method: "POST",
+        // never follow a redirect on a write: undici keeps custom headers across cross-origin
+        // 30x, so a hostile/MITM'd CAIRN_API could otherwise bounce the x-cairn-token to an
+        // attacker host. Fail closed instead.
+        redirect: "error",
         headers: { "content-type": "application/json", "x-cairn-token": CAIRN_TOKEN },
         body: JSON.stringify(body),
     });
@@ -36,12 +40,73 @@ export const apiLeaderboard = () => req("/api/leaderboard");
 export const apiQuests = () => req("/api/quests");
 export const apiPropose = (body) => writeReq("/api/propose", body);
 export const apiSupport = (body) => writeReq("/api/support", body);
+// ── proxy bridge: lets a node-less user transact via `csd`. We fetch a spendable input
+//    + the chain tip from the Cairn instance's public /api/rpc/* proxy, hand the input to
+//    `csd … --input`, and submit through `--rpc-url <CAIRN_API>/api/rpc`. ──
+export const rpcBase = () => `${CAIRN_API}/api/rpc`;
+// One confirmed, mature, non-coinbase UTXO worth > minValue (smallest sufficient) for addr,
+// as the csd input triple "<txid>:<vout>:<value>" — or null.
+// One confirmed, mature, non-coinbase UTXO worth > minValue (smallest sufficient) for addr.
+// Returns { input: "<txid>:<vout>:<value>", value } — value is the proxy-reported amount the
+// caller surfaces so the user sees the true implied fee (a hostile proxy under-reporting it
+// only inflates the fee it burns to the miner; it can never redirect funds — change goes to
+// the user's own --change addr). txid/vout are format-validated so a malformed value can't
+// produce a junk (rejected) tx.
+const HEX64 = /^0x?[0-9a-fA-F]{64}$/;
+export async function pickInput(addr, minValue) {
+    const j = await req(`/api/rpc/utxos-all/${encodeURIComponent(addr)}`);
+    const ok = (x) => Number(x.confirmations ?? 0) >= 1 &&
+        Number.isSafeInteger(Number(x.value)) && Number(x.value) > minValue &&
+        Number.isInteger(Number(x.vout)) && Number(x.vout) >= 0 &&
+        typeof x.txid === "string" && HEX64.test(x.txid) &&
+        !x.coinbase;
+    const cand = (j.utxos ?? []).filter(ok).sort((a, b) => Number(a.value) - Number(b.value));
+    const x = cand[0] ?? (j.utxos ?? []).find(ok);
+    return x ? { input: `${x.txid}:${Number(x.vout)}:${Number(x.value)}`, value: Number(x.value) } : null;
+}
+export async function confirmedBalance(addr) {
+    const j = await req(`/api/rpc/utxos-all/${encodeURIComponent(addr)}`);
+    return { balance: Number(j.confirmed_balance ?? 0), utxos: (j.utxos ?? []).length };
+}
+export async function tipHeight() { return Number((await req("/api/rpc/tip")).height ?? 0); }
+// Submit a node-JSON tx through the proxy (for `csd spend`, which builds+signs but doesn't
+// reliably submit to a proxy URL). Returns the node's response.
+export async function submitTx(txNodeJson) { return req("/api/rpc/tx/submit", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ tx: txNodeJson }) }); }
+// Register a proposal's off-chain content (self-certifying; accepted once mined + hash-matched).
+export async function registerContent(content, txid, attempts = 20) {
+    for (let i = 0; i < attempts; i++) {
+        try {
+            const r = await req("/api/content", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...content, txid }) });
+            if (r.ok)
+                return true;
+        }
+        catch { /* keep trying while it mines */ }
+        await new Promise((res) => setTimeout(res, 8000));
+    }
+    return false;
+}
+// Register an L3 registry record's EXACT canonical bytes (origin serves them verbatim;
+// accepted only if sha256(bytes) == the on-chain payload_hash). Retries while it mines.
+export async function registerRawContent(bytes, txid, attempts = 20) {
+    for (let i = 0; i < attempts; i++) {
+        try {
+            const r = await req("/api/content", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ bytes, txid }) });
+            if (r.ok)
+                return true;
+        }
+        catch { /* keep trying while it mines */ }
+        await new Promise((res) => setTimeout(res, 8000));
+    }
+    return false;
+}
 // optional: query a raw csd node RPC (for trustless verify)
 export async function chainProposal(id) {
     if (!CAIRN_RPC)
         return null;
+    if (!/^0x[0-9a-fA-F]{64}$/.test(id))
+        return null; // never splice an unshaped id into the URL
     try {
-        const r = await fetch(`${CAIRN_RPC}/proposal/${id}`, { signal: AbortSignal.timeout(6000) });
+        const r = await fetch(`${CAIRN_RPC}/proposal/${encodeURIComponent(id)}`, { redirect: "error", signal: AbortSignal.timeout(6000) });
         if (!r.ok)
             return null;
         const j = await r.json();

package/dist/lib/config.js

@@ -1,10 +1,30 @@
 // cairn-cli configuration (env-overridable).
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 export const CAIRN_API = (process.env.CAIRN_API ?? "https://cairn-substrate.com").replace(/\/+$/, "");
-export const CAIRN_TOKEN = process.env.CAIRN_TOKEN ?? ""; // required only for posting
+export const CAIRN_TOKEN = process.env.CAIRN_TOKEN ?? ""; // optional operator write token (falls back to local csd wallet)
 export const CAIRN_RPC = process.env.CAIRN_RPC ?? ""; // optional: a csd node RPC, enables trustless verify
+export const CAIRN_CSD = process.env.CAIRN_CSD ?? "csd"; // the user's installed `csd` binary (signs with their wallet)
+export const CAIRN_ADDR = process.env.CAIRN_ADDR ?? ""; // optional: your public addr20 (skips deriving it from csd)
 export const CSD_PER_COIN = 100_000_000;
 export const MIN_FEE_PROPOSE = 25_000_000; // 0.25 CSD
 export const MIN_FEE_ATTEST = 5_000_000; // 0.05 CSD
 export function csdToCoins(base) {
     return (base / CSD_PER_COIN).toLocaleString(undefined, { maximumFractionDigits: 4 });
 }
+// small local config: caches ONLY the user's public address (never a key).
+const CFG_PATH = process.env.CAIRN_CLI_CONFIG ?? join(homedir(), ".config", "cairn-cli", "config.json");
+export function loadLocalConfig() { try {
+    return JSON.parse(readFileSync(CFG_PATH, "utf8"));
+}
+catch {
+    return {};
+} }
+export function saveLocalConfig(patch) {
+    try {
+        mkdirSync(dirname(CFG_PATH), { recursive: true });
+        writeFileSync(CFG_PATH, JSON.stringify({ ...loadLocalConfig(), ...patch }, null, 2) + "\n");
+    }
+    catch { /* best-effort */ }
+}

package/dist/lib/csd.js

@@ -0,0 +1,41 @@
+// Thin wrapper around the user's INSTALLED `csd` CLI. cairn-cli never holds a private
+// key: for any write it shells out to `csd`, which signs with the user's own csd wallet
+// config key (CSD_SIG_V1). We only orchestrate — supply the input (fetched from the Cairn
+// proxy, so no local node is required) + the Cairn payload — and `csd` does the signing
+// and submit. Binary resolution: CAIRN_CSD env → `csd` on PATH → the substrate default.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const pexec = promisify(execFile);
+export const CSD_BIN = process.env.CAIRN_CSD || "csd";
+function extractTxid(s) {
+    const m = s.match(/txid["':\s]+0x([0-9a-fA-F]{64})/) || s.match(/0x[0-9a-fA-F]{64}/);
+    return m ? (m[1] ? "0x" + m[1] : m[0]) : undefined;
+}
+export async function run(args) {
+    try {
+        const { stdout, stderr } = await pexec(CSD_BIN, args, { timeout: 30000 });
+        return { ok: true, stdout, stderr, txid: extractTxid(stdout + stderr) };
+    }
+    catch (e) {
+        const out = (e.stdout ?? "") + (e.stderr ?? "");
+        return { ok: false, stdout: e.stdout ?? "", stderr: e.stderr ?? String(e.message ?? e), txid: extractTxid(out) };
+    }
+}
+// Is `csd` installed + runnable?
+export async function available() { try {
+    await pexec(CSD_BIN, ["--version"], { timeout: 5000 });
+    return true;
+}
+catch {
+    return false;
+} }
+// The user's csd wallet config (default_privkey / default_rpc_url / …). null if csd absent.
+export async function walletConfig() { const r = await run(["wallet", "config"]); if (!r.ok)
+    return null; try {
+    return JSON.parse(r.stdout);
+}
+catch {
+    return null;
+} }
+// Derive the public addr20 from a privkey via `csd wallet recover` (local; key never networked).
+export async function deriveAddr(priv) { const r = await run(["wallet", "recover", "--privkey", priv]); const m = r.stdout.match(/addr20:\s*(0x[0-9a-fA-F]{40})/i); return m ? m[1] : null; }

package/dist/lib/ui.js

@@ -66,6 +66,13 @@ export function bar(value, max, width = 16) {
 export function csd(base) {
     return c.green(`${(base / 1e8).toLocaleString(undefined, { maximumFractionDigits: 4 })}`) + c.gray(" CSD");
 }
+// Strip C0/C1 control chars (incl. ESC) from UNTRUSTED strings before printing them to a
+// TTY, so a hostile server/chain field (title, body, message, handle, bio, domain, id…)
+// can't inject ANSI/OSC escapes to spoof output — e.g. cursor-up + repaint to overwrite a
+// "✗ MISMATCH" verdict with "✓ VERIFIED", rewrite the window title, or hijack the terminal.
+// Display-only: NEVER apply to bytes that get hashed/verified (it would change the hash).
+const CTRL = new RegExp("[\\u0000-\\u001f\\u007f-\\u009f]", "g");
+export function san(s) { return String(s ?? "").replace(CTRL, ""); }
 export function ok(s) { return c.green("✓ ") + s; }
 export function warn(s) { return c.gray("⚠ ") + s; }
 export function err(s) { return c.red("✗ ") + s; }
@@ -76,16 +83,27 @@ export function pad(s, n) {
 }
 export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export const isTty = TTY;
+export const anim = ANIM;
 // Phosphor braille spinner for network/async work. Writes to STDERR (clig.dev: keep
 // stdout clean for piping) and is a no-op when output isn't an interactive terminal.
+// After ~1.5s it shows an elapsed counter so a slow node read doesn't look hung;
+// stop() prints a clean ✓ (or a caller-supplied final line) on stdout.
 export function spinner(label) {
     if (!ANIM)
         return { stop: (final) => { if (final)
-                console.log(final); } };
+                console.log(final); }, update: () => { } };
     const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-    let i = 0;
-    const t = setInterval(() => process.stderr.write(`\r${c.green(frames[i++ % frames.length])} ${c.gray(label)} `), 80);
+    let i = 0, lbl = label;
+    const t0 = Date.now();
+    const paint = () => {
+        const el = (Date.now() - t0) / 1000;
+        const tail = el >= 1.5 ? c.faint(` ${el.toFixed(0)}s`) : "";
+        process.stderr.write(`\r\x1b[K${c.green(frames[i++ % frames.length])} ${c.gray(lbl)}${tail} `);
+    };
+    const t = setInterval(paint, 80);
+    paint();
     return {
+        update: (l) => { lbl = l; },
         stop: (final) => {
             clearInterval(t);
             process.stderr.write("\r\x1b[K");
@@ -94,28 +112,58 @@ export function spinner(label) {
         },
     };
 }
-// Fast decode-reveal of the CAIRN wordmark: scramble glyphs resolve L→R into white
-// letters with a green cursor — the site's "boot" feel. ~360ms, and only on an
-// interactive TTY (static banner otherwise, so help piped to a file isn't garbage).
+// Type a line out character-by-character to stdout — the site's boot typewriter, in the
+// terminal. Falls back to an instant write when animation is off. ~`cps` chars/sec.
+export async function typeOut(text, cps = 220) {
+    if (!ANIM) {
+        process.stdout.write(text + "\n");
+        return;
+    }
+    const step = Math.max(4, Math.round(1000 / cps));
+    for (let i = 1; i <= text.length; i++) {
+        process.stdout.write(`\r\x1b[K${text.slice(0, i)}${c.green("▋")}`);
+        await sleep(step);
+    }
+    process.stdout.write(`\r\x1b[K${text}\n`);
+}
+// Decode-reveal of the CAIRN wordmark: each glyph scrambles a few times then locks to a
+// bright-white letter, resolving left→right behind a green cursor — the site's "boot"
+// feel. ~420ms cap, interactive TTY only (static banner otherwise, so `help` piped to a
+// file isn't escape-code garbage). Followed by a typed strap-line + rule.
 export async function bannerAnimated() {
     if (!ANIM) {
         banner();
         return;
     }
     const word = "CAIRN";
-    const pool = "▖▗▘▙▚▛▜▝▞▟01#%/\\<>=".split("");
+    const pool = "▖▗▘▙▚▛▜▝▞▟01#%/\\<>=$".split("");
     const rnd = () => pool[Math.floor(Math.random() * pool.length)];
+    const HOLD = 3; // scramble frames each not-yet-locked glyph shows before the head passes it
     for (let step = 0; step <= word.length; step++) {
-        let s = "";
-        for (let i = 0; i < word.length; i++)
-            s += i < step ? c.white(c.bold(word[i])) : c.green(rnd());
-        process.stdout.write(`\r  ${c.gray("▓▒░")} ${s} ${c.green("▋")}  ${c.gray("· " + TAG)}   `);
-        await sleep(60);
+        for (let f = 0; f < (step < word.length ? HOLD : 1); f++) {
+            let s = "";
+            for (let i = 0; i < word.length; i++) {
+                if (i < step)
+                    s += c.white(c.bold(word[i]));
+                else if (i === step)
+                    s += c.green(c.bold(rnd())); // the glyph currently resolving
+                else
+                    s += c.faint(rnd());
+            }
+            process.stdout.write(`\r\x1b[K  ${c.gray("▓▒░")} ${s} ${c.green("▋")}  ${c.faint("· " + TAG)}`);
+            await sleep(26);
+        }
     }
-    process.stdout.write(`\r  ${c.gray("▓▒░")} ${c.white(c.bold(word))} ${c.green("▮")}  ${c.gray("· " + TAG)}\n`);
+    process.stdout.write(`\r\x1b[K  ${c.gray("▓▒░")} ${c.white(c.bold(word))} ${c.green("▮")}  ${c.gray("· " + TAG)}\n`);
     rule();
 }
 export function clearScreen() {
     if (TTY)
         process.stdout.write("\x1b[2J\x1b[H");
 }
+// Move the cursor home and clear from there to the end of screen — repaints in place
+// without the full-screen black flash `clearScreen` causes. Used by `watch`.
+export function cursorHome() {
+    if (TTY)
+        process.stdout.write("\x1b[H\x1b[0J");
+}

package/package.json

@@ -1,25 +1,47 @@
 {
   "name": "@inversealtruism/cairn-cli",
-  "version": "0.2.0",
-  "description": "Command-line client for a Cairn signal board on Compute Substrate — browse, propose, and back what to build.",
+  "version": "0.3.2",
+  "description": "CLI for Compute Substrate / Cairn — browse the board/wall/network, and send CSD, propose, attest, and place stones non-custodially by driving your own installed `csd` wallet (cairn never holds your key; works node-less via the Cairn proxy).",
   "type": "module",
-  "bin": { "cairn": "dist/cli.js" },
-  "files": ["dist", "README.md"],
-  "engines": { "node": ">=20" },
-  "repository": { "type": "git", "url": "git+https://github.com/InverseAltruism/cairn-cli.git" },
+  "bin": {
+    "cairn": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InverseAltruism/cairn-cli.git"
+  },
   "homepage": "https://cairn-substrate.com",
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "tsc",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc",
     "dev": "tsx src/cli.ts",
-    "test": "tsc && node test/e2e.mjs",
-    "prepare": "tsc"
+    "test": "npm run build && node test/security.mjs && node test/e2e.mjs",
+    "prepare": "npm run clean && tsc",
+    "prepublishOnly": "npm run clean && tsc"
   },
-  "keywords": ["cairn", "compute-substrate", "cli"],
+  "keywords": [
+    "cairn",
+    "compute-substrate",
+    "cli"
+  ],
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "@inversealtruism/csd-codec": "0.1.3",
+    "@inversealtruism/csd-registry": "0.1.3"
   }
 }