@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/commands/wallet-storage-ops.js

@@ -0,0 +1,215 @@
+// `nmts wallet storage split|merge|transfer` — reshaping the storage resources the wallet holds,
+// and handing one over. ⛔ EACH SIGNS. The storage-control half a terminal can do: the browser's
+// rules (`shared/lib/storage-control/plan.ts`, copied byte-for-byte) say what the contract allows;
+// the dry run is the final judge; the review comes before the signature; `--yes` is the answer.
+//
+// ⛔ THE ORDER IS THE SAFETY, as in `wallet-send.ts`: ① the resources are READ from the chain and
+//    the named ones must be this wallet's ② the rules judge the request and say why not ③ the
+//    exact transaction is dry-run for its fee, and a refusal there is printed and ends the run
+//    ④ the review ⑤ without `--yes` that is the end ⑥ the wallet unlock is held against the fee —
+//    scope `storage` for cutting and joining, scope `all` for handing over ⑦ only then the signature.
+//
+// ⛔ HANDING OVER MOVES NO FILE. The owner's sentence for the browser holds here: what goes is size
+//    and remaining time; a file's bytes are sealed with keys the NMTS key derives and stay
+//    unreadable to whoever receives the resource. It cannot be undone and NMTS cannot recall it.
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { canFuse, statusOf } from "../shared/lib/storage-control/plan.js";
+import { explorerTxUrl } from "../shared/lib/wallet/activity.js";
+import { isValidSuiAddress } from "../shared/lib/wallet/send-rules.js";
+import { storageOpsReads } from "../storage-control-chain.js";
+import { coinAmount, walletAddress } from "../wallet.js";
+import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
+import { formatBytes } from "./wallet-storage.js";
+const FUSE_WHY = {
+    same: "those are the same resource.",
+    differentSize: "their periods differ and so do their sizes — the contract joins sizes only over an identical period, and periods only at an identical size.",
+    differentPeriod: "their periods differ.",
+    notAdjacent: "their sizes are equal but their periods do not touch — one has to end where the other starts.",
+};
+export async function walletStorageOps(op, rest, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const resolved = await requireAccountCode();
+    const address = await walletAddress(resolved.code);
+    const stored = resolved.source === "file" || resolved.source === "file-locked" ? readCredentialsFile() : null;
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    const reads = (options.storageReads ?? storageOpsReads)(network);
+    // ① The resources, and which epoch it is.
+    let read;
+    try {
+        read = await reads.readStorage(address);
+    }
+    catch (error) {
+        throw new NmtsError("The storage resources could not be read from the chain.", {
+            exitCode: 1,
+            nextStep: `Nothing was signed. Cause: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    const held = (id) => {
+        const found = read.items.find((r) => r.objectId === id);
+        if (found === undefined) {
+            throw new NmtsError(`This wallet holds no free storage resource ${id}.`, {
+                exitCode: 4,
+                nextStep: `\`${BINARY_NAME} wallet storage\` lists the ones it holds. A resource bound inside a file is not free.`,
+            });
+        }
+        return found;
+    };
+    // ② The request, judged.
+    const { shape, action, lines, command } = plan(op, rest, options, held);
+    const walrusPackageId = await reads.walrusPackageId();
+    // ③ The dry run: the fee, or the contract's own refusal.
+    const verdict = await reads.dryRun(shape, address);
+    if (verdict.refusal !== null) {
+        throw new NmtsError(`The chain would refuse this: ${verdict.refusal}`, {
+            exitCode: 4,
+            nextStep: "Nothing was signed and no fee was spent.",
+        });
+    }
+    const feeMist = verdict.feeMist;
+    const facts = { op, network, address, shape, feeSui: feeMist === null ? null : coinAmount(feeMist), currentEpoch: read.currentEpoch };
+    // ④ The review.
+    if (!options.json) {
+        say(`Would ${lines.what}`);
+        for (const l of lines.detail)
+            say(`  ${l}`);
+        say(feeMist === null
+            ? `  Chain fee (SUI): could not be measured just now; it is charged with the signature.`
+            : `  Chain fee about ${facts.feeSui} SUI, measured by a dry run just now.`);
+        if (op === "transfer") {
+            say(`  ⛔ No file goes with it. What goes is size and remaining time; the files stay sealed with this`);
+            say(`     account's keys. It cannot be undone, and NMTS cannot recall it. Check the address once more.`);
+        }
+    }
+    // ⑤ Without --yes, that is the end.
+    if (options.dryRun === true || options.yes !== true) {
+        if (options.json) {
+            say(JSON.stringify({ ...facts, signed: false, dryRun: options.dryRun === true }));
+            return options.dryRun === true ? 0 : 4;
+        }
+        say(``);
+        if (options.dryRun === true) {
+            say(`  Nothing was signed. Run the same command with --yes to do it.`);
+            return 0;
+        }
+        throw new NmtsError(`Nothing was signed: this needs --yes.`, {
+            exitCode: 4,
+            nextStep: `Read the review above, then: \`${command} --yes\``,
+        });
+    }
+    // ⑥ The unlock, held against the fee. ⑦ The signature.
+    const spend = { walFrost: 0n, suiMist: feeMist ?? 0n };
+    requireWalletGrant(action, spend, new Date(options.now ?? Date.now()));
+    const sign = options.signStorage ?? (await import("../wallet-sign.js")).signStorageOp;
+    const digest = await sign({ network, code: resolved.code, shape, walrusPackageId });
+    recordWalletSpend(spend);
+    if (options.json) {
+        say(JSON.stringify({ ...facts, signed: true, digest, explorerUrl: explorerTxUrl(digest, network) }));
+        return 0;
+    }
+    say(``);
+    say(`  Done. Transaction ${digest}`);
+    say(`  ${explorerTxUrl(digest, network)}`);
+    say(`  \`${BINARY_NAME} wallet storage\` lists what the wallet holds now.`);
+    return 0;
+}
+/** The shape one request is, the unlock action it needs, and the review's words. */
+function plan(op, rest, options, held) {
+    const [a, b] = rest;
+    const resource = (r) => `${formatBytes(r.sizeBytes)} · epoch ${r.startEpoch} to ${r.endEpoch} (${r.objectId})`;
+    if (op === "split") {
+        if (a === undefined)
+            throw usage("split <resource id> --size <bytes> | --epochs <n>");
+        const r = held(a);
+        if (options.size !== undefined && options.epochs !== undefined)
+            throw usage("split takes --size OR --epochs, not both");
+        if (options.size !== undefined) {
+            const keep = parseBytes(options.size);
+            if (keep <= 0 || keep >= r.sizeBytes) {
+                throw new NmtsError(`--size must be above 0 and below the resource's ${formatBytes(r.sizeBytes)}.`, { exitCode: 2 });
+            }
+            return {
+                shape: { kind: "splitSize", objectId: a, keepBytes: keep },
+                action: "reshape",
+                lines: {
+                    what: `cut ${resource(r)} by size.`,
+                    detail: [`It keeps ${formatBytes(keep)}; a new resource of ${formatBytes(r.sizeBytes - keep)} over the same period appears in this wallet.`],
+                },
+                command: `${BINARY_NAME} wallet storage split ${a} --size ${options.size}`,
+            };
+        }
+        if (options.epochs !== undefined) {
+            const n = Number(options.epochs);
+            const span = r.endEpoch - r.startEpoch;
+            if (!Number.isSafeInteger(n) || n <= 0 || n >= span) {
+                throw new NmtsError(`--epochs must be a whole number above 0 and below the resource's ${span} epochs.`, { exitCode: 2 });
+            }
+            const at = r.startEpoch + n;
+            return {
+                shape: { kind: "splitEpoch", objectId: a, splitEpoch: at },
+                action: "reshape",
+                lines: {
+                    what: `cut ${resource(r)} by period.`,
+                    detail: [`It keeps epoch ${r.startEpoch} to ${at}; a new resource of the same size over epoch ${at} to ${r.endEpoch} appears in this wallet.`],
+                },
+                command: `${BINARY_NAME} wallet storage split ${a} --epochs ${options.epochs}`,
+            };
+        }
+        throw usage("split <resource id> --size <bytes> | --epochs <n>");
+    }
+    if (op === "merge") {
+        if (a === undefined || b === undefined)
+            throw usage("merge <resource id> <resource id>");
+        const first = held(a);
+        const second = held(b);
+        const verdict = canFuse(first, second);
+        if (!verdict.can) {
+            throw new NmtsError(`These two cannot be joined: ${FUSE_WHY[verdict.why]}`, {
+                exitCode: 4,
+                nextStep: `Nothing was signed. \`${BINARY_NAME} wallet storage\` shows each one's size and period.`,
+            });
+        }
+        return {
+            shape: { kind: "fuse", first: a, second: b, how: verdict.kind },
+            action: "reshape",
+            lines: {
+                what: `join ${resource(second)} into ${resource(first)}.`,
+                detail: [
+                    verdict.kind === "amount"
+                        ? `Same period, so the sizes add: the first becomes ${formatBytes(first.sizeBytes + second.sizeBytes)} and the second is gone.`
+                        : `Same size and touching periods, so the periods join: the first spans epoch ${Math.min(first.startEpoch, second.startEpoch)} to ${Math.max(first.endEpoch, second.endEpoch)} and the second is gone.`,
+                ],
+            },
+            command: `${BINARY_NAME} wallet storage merge ${a} ${b}`,
+        };
+    }
+    if (a === undefined || b === undefined)
+        throw usage("transfer <resource id> <address>");
+    const r = held(a);
+    if (!isValidSuiAddress(b)) {
+        throw new NmtsError("That is not a Sui address: it is 0x followed by 64 hexadecimal characters.", { exitCode: 2 });
+    }
+    return {
+        shape: { kind: "transfer", objectId: a, to: b },
+        action: "give",
+        lines: { what: `hand ${resource(r)} to ${b}.`, detail: [`Afterwards this wallet no longer holds it.`] },
+        command: `${BINARY_NAME} wallet storage transfer ${a} ${b}`,
+    };
+}
+function usage(form) {
+    return new NmtsError(`\`${BINARY_NAME} wallet storage ${form}\``, { exitCode: 2 });
+}
+/** "500MiB", "1GiB", "4096" — bytes, in binary units, the way the listing prints them. */
+export function parseBytes(text) {
+    const m = /^(\d+(?:\.\d+)?)\s*(B|KiB|MiB|GiB|TiB)?$/i.exec(text.trim());
+    if (m === null || m[1] === undefined)
+        throw new NmtsError("--size is a number of bytes, or one with KiB, MiB or GiB.", { exitCode: 2 });
+    const unit = (m[2] ?? "B").toLowerCase();
+    const scale = { b: 1, kib: 1024, mib: 1024 ** 2, gib: 1024 ** 3, tib: 1024 ** 4 }[unit] ?? 1;
+    return Math.floor(Number(m[1]) * scale);
+}

package/dist/commands/wallet-storage.d.ts

@@ -0,0 +1,18 @@
+import { type Network } from "../network.ts";
+import type { StorageResource } from "../shared/lib/storage-control/chain.ts";
+/** What the chain said: the resources, and which epoch it is (null when the clock could not be read). */
+export interface StorageRead {
+    items: readonly StorageResource[];
+    currentEpoch: number | null;
+}
+export interface WalletStorageOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /** ⚠ A SEAM, NOT AN OPTION — no flag reaches it. Rejects when the chain could not be read. */
+    readStorage?: (network: Network, address: string) => Promise<StorageRead>;
+}
+export declare function walletStorage(options?: WalletStorageOptions): Promise<number>;
+/** Bytes for a person: binary units, two decimals, whole bytes below a KiB. */
+export declare function formatBytes(bytes: number): string;

package/dist/commands/wallet-storage.js

@@ -0,0 +1,95 @@
+// `nmts wallet storage` — the storage resources the wallet holds: size × time, bought and not
+// bound inside a file.
+//
+// ⛔ IT READS. What the storage network sells is size and time, not a file; deleting a file from the
+//    network returns the remaining time to this wallet, and that is what is listed. Splitting,
+//    fusing and spending a resource need a signature and are not here.
+//
+// ⛔ "NONE" AND "COULD NOT READ" ARE DIFFERENT SENTENCES — holding no resource is normal; failing to
+//    read is a reason to look again. The reader (`shared/lib/storage-control/chain.ts`, the
+//    browser's own, copied byte-for-byte) throws rather than answering an empty list.
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { statusOf, totalUsableBytes, usableFirst } from "../shared/lib/storage-control/plan.js";
+import { walletAddress } from "../wallet.js";
+export async function walletStorage(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const resolved = await requireAccountCode();
+    const address = await walletAddress(resolved.code);
+    const stored = resolved.source === "file" || resolved.source === "file-locked" ? readCredentialsFile() : null;
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    const read = options.readStorage ??
+        (async (net, addr) => (await import("../wallet-storage-chain.js")).readWalletStorage(net, addr));
+    let got;
+    try {
+        got = await read(network, address);
+    }
+    catch (error) {
+        throw new NmtsError("The storage resources could not be read from the chain.", {
+            exitCode: 1,
+            nextStep: `That is not the same as holding none. \`${BINARY_NAME} env\` says which network was asked. ` +
+                `Cause: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    const epoch = got.currentEpoch;
+    const items = epoch === null ? [...got.items] : usableFirst(got.items, epoch);
+    if (options.json) {
+        say(JSON.stringify({
+            address,
+            network,
+            currentEpoch: epoch,
+            usableBytes: epoch === null ? null : totalUsableBytes(items, epoch),
+            resources: items.map((r) => ({
+                objectId: r.objectId,
+                sizeBytes: r.sizeBytes,
+                startEpoch: r.startEpoch,
+                endEpoch: r.endEpoch,
+                status: epoch === null ? null : statusOf(r, epoch),
+            })),
+        }));
+        return 0;
+    }
+    say(`Address  ${address}`);
+    say(`Network  ${network}`);
+    say(``);
+    if (items.length === 0) {
+        say(`  This wallet holds no free storage resource. Anything bound inside a file is not listed here.`);
+    }
+    else {
+        if (epoch !== null)
+            say(`  ${formatBytes(totalUsableBytes(items, epoch))} usable now, in ${items.length} resource${items.length === 1 ? "" : "s"}.`);
+        for (const r of items) {
+            const status = epoch === null ? "" : `  ${statusWord(statusOf(r, epoch))}`;
+            say(`  ${formatBytes(r.sizeBytes).padStart(11)} · epoch ${r.startEpoch} to ${r.endEpoch}${status}`);
+            say(`    ${r.objectId}`);
+        }
+    }
+    say(``);
+    say(`  What the storage network sells is size and time, not a file. Deleting a file from the`);
+    say(`  network returns its remaining time to this wallet, and that is what is listed. Sizes are`);
+    say(`  what a resource holds after the network's encoding, not file sizes. Nothing here signs.`);
+    if (epoch === null)
+        say(`  The current epoch could not be read, so no line says whether a resource can be used yet.`);
+    return 0;
+}
+function statusWord(status) {
+    return status === "usable" ? "usable now" : status === "notYet" ? "not started" : "ended";
+}
+/** Bytes for a person: binary units, two decimals, whole bytes below a KiB. */
+export function formatBytes(bytes) {
+    const units = ["KiB", "MiB", "GiB", "TiB"];
+    let value = bytes;
+    let unit = "B";
+    for (const next of units) {
+        if (value < 1024)
+            break;
+        value /= 1024;
+        unit = next;
+    }
+    return unit === "B" ? `${bytes} B` : `${value.toFixed(2)} ${unit}`;
+}

package/dist/commands/wallet-swap.d.ts

@@ -0,0 +1,32 @@
+import { type Network } from "../network.ts";
+import { type SwapReads } from "../wallet-swap-chain.ts";
+import type { SignSwap } from "../wallet-sign.ts";
+/** What the site's price route says, when it says anything. Null = no reference price just now. */
+export interface MarketPrices {
+    suiUsd: number | null;
+    walUsd: number | null;
+}
+export interface WalletSwapOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    yes?: boolean;
+    dryRun?: boolean;
+    feeCap?: string | undefined;
+    /** `--to`: the coin to receive. Only ever the other coin; said so a typo cannot flip the trade. */
+    to?: string | undefined;
+    /** `--venue`: deepbook or bluefin. Without it, both are quoted and the run stops. */
+    venue?: string | undefined;
+    /** `--slippage-bps`: whole bps, clamped to the browser's range. Default 50. */
+    slippageBps?: string | undefined;
+    /** `--accept-extremes`: go on past the extremes gate. A person's act — refused outside mode off. */
+    acceptExtremes?: boolean;
+    now?: number;
+    /** ⚠ SEAMS, NOT OPTIONS — no flag reaches them. */
+    readChain?: (network: Network) => SwapReads | Promise<SwapReads>;
+    readPrices?: (server: string) => Promise<MarketPrices | null>;
+    sign?: SignSwap;
+}
+export declare function asMarketPrices(value: unknown): MarketPrices | null;
+export declare function walletSwap(operands: readonly string[], options?: WalletSwapOptions): Promise<number>;

package/dist/commands/wallet-swap.js

@@ -0,0 +1,287 @@
+// `nmts wallet swap <SUI|WAL> <amount|max>` — turn one coin into the other, from the wallet this
+// NMTS key derives, on the venue the person names. ⛔ SIGNS AND SPENDS.
+//
+// ⛔ THE ORDER IS THE SAFETY. ① both balances are READ, and an unread one stops the run ② the
+//    amount and the slippage are judged by the browser's own rules (`shared/lib/wallet/swap-rules.ts`,
+//    copied byte-for-byte) ③ the venue's quote is read from the chain — on mainnet BOTH venues when
+//    none was named, printed side by side, and the run stops there: neither is a default and nobody
+//    recommends one ④ the exact swap is dry-run for its fee ⑤ the quote is compared with the site's
+//    reference price when one can be read, and said to be uncompared when none can ⑥ the review is
+//    printed ⑦ anything outside the ordinary bands — slippage, fee cap, market distance — is refused;
+//    only a person, in mode off, may say `--accept-extremes` ⑧ without `--yes` that is the end ⑨ the
+//    wallet agreement is held against the amount and the fee, scope `all` ⑩ only then the signature.
+//
+// ⛔ NOT ON THE MCP SURFACE. A model can ask a person to run this; it cannot run it through a tool call.
+import { request } from "../api.js";
+import { currentMode } from "../autonomy.js";
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { explorerTxUrl } from "../shared/lib/wallet/activity.js";
+import { clampGasBudgetMist, parseTokenAmountToBaseUnits, SUI_GAS_RESERVE_MIST } from "../shared/lib/wallet/send-rules.js";
+import { clampSlippageBps, impliedRate, marketRate, maxSwappableSuiMist, minOutFromQuote, priceDeviationBps, SLIPPAGE_BPS_DEFAULT, SLIPPAGE_BPS_MAX, SLIPPAGE_BPS_MIN, swapExtremes, } from "../shared/lib/wallet/swap-rules.js";
+import { coinAmount, walletAddress } from "../wallet.js";
+import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
+import { railsFor } from "../wallet-swap-chain.js";
+const EXTREME_WORDS = {
+    lowSlippage: "the slippage is below 10 bps: the smallest price movement fails the swap, and the chain fee is spent for nothing",
+    highSlippage: "the slippage is above 200 bps: a thin order book may keep that much of what goes in",
+    lowFee: "the fee cap is under 1.2 times the measured fee: the swap may fail for want of gas, and that gas is gone",
+    highFee: "the fee cap is over ten times the measured fee and over 0.05 SUI",
+    deviation: "the quote is more than 3% from the site's reference price: the book may be thin or moved",
+};
+function coinOf(raw, what) {
+    const up = (raw ?? "").toUpperCase();
+    if (up === "SUI" || up === "WAL")
+        return up;
+    throw new NmtsError(`Say which coin ${what}: SUI or WAL.`, {
+        exitCode: 2,
+        nextStep: `\`${BINARY_NAME} wallet swap <SUI|WAL> <amount|max> --venue deepbook|bluefin\``,
+    });
+}
+function pct(bps) {
+    return `${(bps / 100).toFixed(2).replace(/0+$/, "").replace(/\.$/, "")}%`;
+}
+export function asMarketPrices(value) {
+    if (!isRecord(value) || value["unavailable"] === true)
+        return null;
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null);
+    return { suiUsd: num(value["suiUsd"]), walUsd: num(value["walUsd"]) };
+}
+function venueName(venue) {
+    return venue === "deepbook" ? "DeepBook" : venue === "bluefin" ? "Bluefin" : "the official Walrus testnet exchange";
+}
+function quoteLine(q, outCoin, inCoin) {
+    const fee = q.feeRateBps === null ? "venue fee could not be measured" : `venue fee about ${pct(q.feeRateBps)}`;
+    const left = q.leftoverInUnits > 0n ? ` (${coinAmount(q.leftoverInUnits)} ${inCoin} would come back unused)` : "";
+    return `${q.venue.padEnd(9)} ${coinAmount(q.outUnits)} ${outCoin} — ${fee}${left}`;
+}
+export async function walletSwap(operands, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const [coinRaw, amountRaw] = operands;
+    const coinIn = coinOf(coinRaw, "goes in");
+    const coinOut = coinIn === "SUI" ? "WAL" : "SUI";
+    if (options.to !== undefined && coinOf(options.to, "comes out") !== coinOut) {
+        throw new NmtsError(`${coinIn} can only be swapped for ${coinOut}.`, { exitCode: 2, nextStep: `Drop --to, or say --to ${coinOut}.` });
+    }
+    const direction = coinIn === "SUI" ? "SUI_TO_WAL" : "WAL_TO_SUI";
+    if (amountRaw === undefined) {
+        throw new NmtsError("Say how much.", { exitCode: 2, nextStep: `\`${BINARY_NAME} wallet swap ${coinIn} <amount|max>\` — "max" swaps everything that can be swapped.` });
+    }
+    const resolved = await requireAccountCode();
+    const address = await walletAddress(resolved.code);
+    const stored = resolved.source === "file" || resolved.source === "file-locked" ? readCredentialsFile() : null;
+    const server = resolveServer(options.server ?? stored?.server);
+    const network = resolveNetwork(server, options.network ?? stored?.network);
+    const rails = railsFor(network);
+    const reads = await (options.readChain ?? (async (net) => (await import("../wallet-swap-chain.js")).swapReads(net)))(network);
+    // ① The balances — read, and refused as unread rather than treated as zero.
+    const purse = await reads.readWallet(address);
+    if (!purse.sui.read || !purse.wal.read) {
+        const which = [!purse.sui.read ? `SUI: ${purse.sui.why}` : null, !purse.wal.read ? `WAL: ${purse.wal.why}` : null].filter((w) => w !== null);
+        throw new NmtsError("A balance could not be read, so this tool cannot tell what can be swapped.", {
+            exitCode: 1,
+            nextStep: `Nothing was signed. That is not an empty wallet — ${which.join("; ")}.`,
+        });
+    }
+    const sui = purse.sui.baseUnits;
+    const wal = purse.wal.baseUnits;
+    // ② The numbers — the browser's rules, unchanged. The gas kept back is the cap the person set,
+    //    or the same reserve `wallet send` keeps when none was set.
+    const gasBudgetMist = options.feeCap === undefined ? undefined : clampGasBudgetMist(parseTokenAmountToBaseUnits(options.feeCap) ?? 0n);
+    const keptForGas = gasBudgetMist ?? SUI_GAS_RESERVE_MIST;
+    const maxIn = direction === "SUI_TO_WAL" ? maxSwappableSuiMist(sui, keptForGas) : wal;
+    const amountInUnits = amountRaw.toLowerCase() === "max" ? maxIn : parseTokenAmountToBaseUnits(amountRaw);
+    if (amountInUnits === null || amountInUnits <= 0n) {
+        throw new NmtsError("The amount must be a number above zero, with at most nine decimals.", { exitCode: 2 });
+    }
+    if (amountInUnits > maxIn || (direction === "WAL_TO_SUI" && sui < keptForGas)) {
+        throw new NmtsError(direction === "WAL_TO_SUI" && sui < keptForGas
+            ? "A WAL swap pays its fee in SUI, and the wallet holds less SUI than is kept back for that."
+            : "The wallet does not hold that much.", {
+            exitCode: 4,
+            nextStep: `Nothing was signed. The wallet holds ${coinAmount(sui)} SUI and ${coinAmount(wal)} WAL; the most that can go in is ${coinAmount(maxIn)} ${coinIn} (SUI keeps ${coinAmount(keptForGas)} back for the fee).`,
+        });
+    }
+    let slippageBps = SLIPPAGE_BPS_DEFAULT;
+    if (options.slippageBps !== undefined) {
+        if (!/^\d+$/.test(options.slippageBps.trim())) {
+            throw new NmtsError(`--slippage-bps must be a whole number of bps, ${SLIPPAGE_BPS_MIN} to ${SLIPPAGE_BPS_MAX} (1 bps = 0.01%).`, { exitCode: 2 });
+        }
+        slippageBps = clampSlippageBps(Number(options.slippageBps));
+    }
+    // ③ The venue and its quote. Testnet has one facility and no choice; mainnet has two and no default.
+    let venue;
+    let quote;
+    let bluefin;
+    let exchange;
+    if (rails[0] === "exchange") {
+        if (options.venue !== undefined)
+            throw new NmtsError(`On testnet the only rail is ${venueName("exchange")}; --venue does not apply.`, { exitCode: 2 });
+        if (direction === "WAL_TO_SUI")
+            throw new NmtsError(`${venueName("exchange")} only turns SUI into WAL.`, { exitCode: 2 });
+        if (options.slippageBps !== undefined)
+            throw new NmtsError("The testnet facility takes no minimum; --slippage-bps does not apply.", { exitCode: 2 });
+        venue = "exchange";
+        exchange = await reads.readExchange().catch((error) => {
+            throw new NmtsError("The testnet exchange could not be read, so what it would give is unknown.", { exitCode: 1, nextStep: `Nothing was signed. ${error instanceof Error ? error.message : String(error)}` });
+        });
+        // The facility's rate is a fraction read off its object; there is no fee to measure and no lot to leave over.
+        quote = { outUnits: (amountInUnits * exchange.rateWal) / exchange.rateSui, feeRateBps: null, leftoverInUnits: 0n };
+    }
+    else {
+        if (options.venue !== undefined && options.venue !== "deepbook" && options.venue !== "bluefin") {
+            throw new NmtsError("--venue must be deepbook or bluefin.", { exitCode: 2 });
+        }
+        const wanted = options.venue === undefined ? ["deepbook", "bluefin"] : [options.venue];
+        const answers = await Promise.all(wanted.map(async (v) => {
+            try {
+                const binding = v === "bluefin" ? await reads.resolveBluefin() : null;
+                return { venue: v, quote: await reads.quote(v, direction, amountInUnits, binding), why: null, binding };
+            }
+            catch (error) {
+                return { venue: v, quote: null, why: error instanceof Error ? error.message : String(error), binding: null };
+            }
+        }));
+        if (options.venue === undefined) {
+            const lines = answers.map((a) => (a.quote === null ? `${a.venue.padEnd(9)} did not answer — ${a.why}` : quoteLine(a.quote, coinOut, coinIn)));
+            if (options.json) {
+                say(JSON.stringify({ direction, amountInUnits: amountInUnits.toString(), network, quotes: answers.map((a) => (a.quote === null ? { venue: a.venue, answered: false, why: a.why } : { venue: a.venue, answered: true, outUnits: a.quote.outUnits.toString(), feeRateBps: a.quote.feeRateBps, leftoverInUnits: a.quote.leftoverInUnits.toString() })), signed: false }));
+                return 4;
+            }
+            say(`Quotes for ${coinAmount(amountInUnits)} ${coinIn} → ${coinOut}, read from the ${network} chain just now`);
+            for (const line of lines)
+                say(`  ${line}`);
+            say(``);
+            throw new NmtsError("Neither venue is a default, and this tool recommends neither. Choose one.", {
+                exitCode: 4,
+                nextStep: `Nothing was signed. Run it again with --venue deepbook or --venue bluefin. Any other exchange may be used instead.`,
+            });
+        }
+        const only = answers[0];
+        if (only === undefined || only.quote === null) {
+            throw new NmtsError(`${venueName(wanted[0] ?? "deepbook")} did not answer just now.`, { exitCode: 1, nextStep: `Nothing was signed. ${only?.why ?? ""}`.trim() });
+        }
+        venue = only.venue;
+        quote = only.quote;
+        bluefin = only.binding ?? undefined;
+    }
+    if (quote.outUnits <= 0n) {
+        throw new NmtsError(`${venueName(venue)} would give nothing for ${coinAmount(amountInUnits)} ${coinIn}: the amount is below one lot, or the book is empty.`, { exitCode: 4, nextStep: "Nothing was signed." });
+    }
+    const minOutUnits = venue === "exchange" ? 0n : minOutFromQuote(quote.outUnits, slippageBps);
+    const shape = { venue, direction, amountInUnits, minOutUnits, gasBudgetMist, bluefin, exchange };
+    // ④ The fee of this exact swap. ⑤ The market check, said as unknown when it is.
+    const feeMist = await reads.estimateFee(shape, address);
+    const prices = await (options.readPrices ?? (async (base) => asMarketPrices(await request(base, "/api/prices").catch(() => null))))(server).catch(() => null);
+    const market = marketRate(direction, prices?.suiUsd, prices?.walUsd);
+    const implied = impliedRate(quote.outUnits, amountInUnits);
+    const deviationBps = market !== null && implied !== null ? priceDeviationBps(implied, market) : null;
+    const extremes = venue === "exchange" ? [] : swapExtremes({ slippageBps, budgetMist: gasBudgetMist ?? null, estimateMist: feeMist, deviationBps });
+    const suiAfter = sui - (direction === "SUI_TO_WAL" ? amountInUnits - quote.leftoverInUnits : -quote.outUnits) - (feeMist ?? 0n);
+    const walAfter = wal - (direction === "WAL_TO_SUI" ? amountInUnits - quote.leftoverInUnits : -quote.outUnits);
+    const facts = {
+        from: address,
+        venue,
+        direction,
+        amountInUnits: amountInUnits.toString(),
+        amountIn: coinAmount(amountInUnits),
+        coinIn,
+        coinOut,
+        quotedOutUnits: quote.outUnits.toString(),
+        quotedOut: coinAmount(quote.outUnits),
+        minOutUnits: minOutUnits.toString(),
+        minOut: coinAmount(minOutUnits),
+        slippageBps: venue === "exchange" ? null : slippageBps,
+        venueFeeBps: quote.feeRateBps,
+        leftoverInUnits: quote.leftoverInUnits.toString(),
+        feeMist: feeMist === null ? null : feeMist.toString(),
+        feeSui: feeMist === null ? null : coinAmount(feeMist),
+        feeCapMist: gasBudgetMist === undefined ? null : gasBudgetMist.toString(),
+        deviationBps: deviationBps === null ? null : Math.round(deviationBps * 100) / 100,
+        extremes,
+        network,
+        suiAfter: coinAmount(suiAfter < 0n ? 0n : suiAfter),
+        walAfter: coinAmount(walAfter < 0n ? 0n : walAfter),
+    };
+    // ⑥ The review, every time.
+    if (!options.json) {
+        say(`Swapping ${facts.amountIn} ${coinIn} for ${coinOut} on ${venueName(venue)}`);
+        say(`  from      ${address}`);
+        say(`  Quoted    ${facts.quotedOut} ${coinOut} — the chain's answer just now, not a promise${quote.leftoverInUnits > 0n ? `; ${coinAmount(quote.leftoverInUnits)} ${coinIn} would come back unused` : ""}`);
+        if (venue === "exchange")
+            say(`  Rate      ${exchange?.rateWal} WAL per ${exchange?.rateSui} SUI, read off the facility; it takes no minimum`);
+        else
+            say(`  At least  ${facts.minOut} ${coinOut}, or the swap fails on chain — slippage ${slippageBps} bps (${pct(slippageBps)})`);
+        say(quote.feeRateBps === null ? `  Venue fee: could not be measured from the quote just now` : `  Venue fee about ${pct(quote.feeRateBps)} of what goes in, measured from the quote`);
+        say(feeMist === null ? `  Chain fee (SUI): could not be measured just now; it is charged with the signature` : `  Chain fee about ${facts.feeSui} SUI, measured by a dry run just now — the amount charged is fixed when it executes`);
+        if (gasBudgetMist !== undefined)
+            say(`  Fee cap   ${coinAmount(gasBudgetMist)} SUI — only up to this is used; the rest stays`);
+        say(deviationBps === null ? `  Market    no reference price could be read just now, so the quote was not compared with the market` : `  Market    ${pct(deviationBps)} from the site's reference price (1 ${coinIn} ≈ ${market?.toFixed(4)} ${coinOut})`);
+        say(`  Afterwards, if the chain gives exactly the quote: about ${facts.suiAfter} SUI and ${facts.walAfter} WAL`);
+        say(``);
+        say(`  NMTS is not a party to this trade and takes nothing from it. Any other exchange may be used instead.`);
+        if (extremes.length > 0) {
+            say(``);
+            say(`  ⛔ Outside the ordinary bands:`);
+            for (const e of extremes)
+                say(`     · ${EXTREME_WORDS[e]}`);
+        }
+    }
+    // ⑦ The extremes gate: refused, unless a person said so.
+    if (extremes.length > 0 && options.dryRun !== true) {
+        if (options.acceptExtremes !== true) {
+            if (options.json) {
+                say(JSON.stringify({ ...facts, signed: false, refused: "extremes" }));
+                return 4;
+            }
+            throw new NmtsError("Nothing was signed: this swap is outside the ordinary bands.", {
+                exitCode: 4,
+                nextStep: `Choose again (--slippage-bps 50, a different --fee-cap, the other venue, or later), or — as a person — add --accept-extremes to go on anyway.`,
+            });
+        }
+        const mode = currentMode();
+        if (mode === "auto-low" || mode === "auto-high") {
+            throw new NmtsError("Going past the extremes gate is a person's act.", { exitCode: 5, nextStep: `Nothing was signed. --accept-extremes is refused in mode auto and with --skip-permissions.` });
+        }
+    }
+    // ⑧ Without --yes, that is the end.
+    if (options.dryRun === true || options.yes !== true) {
+        if (options.json) {
+            say(JSON.stringify({ ...facts, signed: false, dryRun: options.dryRun === true }));
+            return options.dryRun === true ? 0 : 4;
+        }
+        say(``);
+        if (options.dryRun === true) {
+            say(`  Nothing was signed. Run the same command with --yes to swap.`);
+            return 0;
+        }
+        throw new NmtsError("Nothing was signed: swapping needs --yes.", {
+            exitCode: 4,
+            nextStep: `Read the review above, then run the same command with --yes. The quote will be read again; the chain gives what it gives, never less than the minimum.`,
+        });
+    }
+    // ⑨ The agreement — scope `all`, the amount and the fee held against its ceiling.
+    const spend = {
+        walFrost: direction === "WAL_TO_SUI" ? amountInUnits : 0n,
+        suiMist: (direction === "SUI_TO_WAL" ? amountInUnits : 0n) + (feeMist ?? 0n),
+    };
+    requireWalletGrant("exchange", spend, new Date(options.now ?? Date.now()));
+    // ⑩ The signature.
+    const sign = options.sign ?? (await import("../wallet-sign.js")).signSwap;
+    const digest = await sign({ network, code: resolved.code, shape });
+    recordWalletSpend(spend);
+    if (options.json) {
+        say(JSON.stringify({ ...facts, signed: true, digest, explorerUrl: explorerTxUrl(digest, network) }));
+        return 0;
+    }
+    say(``);
+    say(`  Swapped. Transaction ${digest}`);
+    say(`  ${explorerTxUrl(digest, network)}`);
+    say(`  What arrived is what the chain gave — at least the minimum above. \`${BINARY_NAME} wallet\` shows both balances now.`);
+    return 0;
+}