@needmoretruth/nmts-cli 0.17.2 → 0.34.2

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

@@ -0,0 +1,26 @@
+import { type Network } from "../network.ts";
+import type { SendReads } from "../wallet-send-chain.ts";
+import type { SignTransfer } from "../wallet-sign.ts";
+/** What `GET /api/donation` says. */
+export interface DonationConfig {
+    devAddress: string;
+    sendEnabled: boolean;
+    walEnabled: boolean;
+}
+export interface WalletDonateOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    yes?: boolean;
+    dryRun?: boolean;
+    feeCap?: string | undefined;
+    /** ⚠ SEAMS, NOT OPTIONS — no flag reaches them. */
+    readDonation?: (server: string) => Promise<DonationConfig>;
+    readChain?: (network: Network) => SendReads | Promise<SendReads>;
+    sign?: SignTransfer;
+}
+/** The four facts and the promise, as the screens say them, in the order a person reads them. */
+export declare const GIFT_NOTICES: readonly string[];
+export declare function asDonationConfig(value: unknown): DonationConfig;
+export declare function walletDonate(operands: readonly string[], options?: WalletDonateOptions): Promise<number>;

package/dist/commands/wallet-donate.js

@@ -0,0 +1,163 @@
+// `nmts wallet donate <SUI|WAL> <amount>` — a voluntary gift to the developer, from the wallet this
+// NMTS key derives. A HIGH act (2026-09-06): the `donate` unlock opens it, and every run
+// still needs `--yes` — the tier gate in main.ts holds the door; this file holds the sending.
+//
+// ⛔ THE WALLET AGREEMENT DOES NOT REACH A GIFT. A gift is neither covered by that agreement nor
+//    counted against its ceiling: the agreement is what lets a PROGRAM sign for storage; a gift is
+//    approved on the run that sends it, under the `donate` unlock the person gave.
+//
+// ⛔ WHERE THE ADDRESS COMES FROM. The server publishes it at `GET /api/donation`, the same value the
+//    wallet screen's card is built from. It is read on every run and never written down here — an
+//    address baked into this tool would go on receiving gifts after the owner changed it.
+//
+// ⛔ WHAT IS SAID BEFORE SIGNING, every time: the four facts (voluntary · nothing in return ·
+//    non-refundable · cannot be undone) and the one the terms promise — no record is kept, the
+//    transaction id is the only proof (terms 11.5).
+import { request } from "../api.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 { THANKS_EN, THANKS_KO } from "../standing-tip.js";
+import { explorerTxUrl } from "../shared/lib/wallet/activity.js";
+import { clampGasBudgetMist, isValidSuiAddress, parseTokenAmountToBaseUnits, validateSendForm, } from "../shared/lib/wallet/send-rules.js";
+import { coinAmount, walCoinType, walletAddress } from "../wallet.js";
+/** The four facts and the promise, as the screens say them, in the order a person reads them. */
+export const GIFT_NOTICES = [
+    "This is a voluntary gift. Nothing is provided in return, it is non-refundable, and it cannot be undone once sent.",
+    "We keep no record of who sent what. If you ever need to ask about this gift, keep the transaction id shown after sending — it is the only proof.",
+];
+export function asDonationConfig(value) {
+    if (!isRecord(value))
+        throw new NmtsError("The server's donation answer is not the shape this version reads.", { exitCode: 1 });
+    const devAddress = value["devAddress"];
+    return {
+        devAddress: typeof devAddress === "string" ? devAddress : "",
+        sendEnabled: value["sendEnabled"] === true,
+        walEnabled: value["walEnabled"] === true,
+    };
+}
+function coinOf(raw) {
+    const up = (raw ?? "").toUpperCase();
+    if (up === "SUI" || up === "WAL")
+        return up;
+    throw new NmtsError("Say which coin: SUI or WAL.", {
+        exitCode: 2,
+        nextStep: `\`${BINARY_NAME} wallet donate <SUI|WAL> <amount> --yes\``,
+    });
+}
+export async function walletDonate(operands, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const [coinRaw, amountRaw] = operands;
+    const coin = coinOf(coinRaw);
+    if (amountRaw === undefined) {
+        throw new NmtsError("Say how much.", { exitCode: 2, nextStep: `\`${BINARY_NAME} wallet donate ${coin} <amount> --yes\`` });
+    }
+    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 config = await (options.readDonation ?? (async (base) => asDonationConfig(await request(base, "/api/donation"))))(server);
+    if (!config.sendEnabled || !isValidSuiAddress(config.devAddress)) {
+        throw new NmtsError("Gifts are not open right now.", {
+            exitCode: 4,
+            nextStep: "Nothing was signed. The donation card in the browser says the same when it is off.",
+        });
+    }
+    if (coin === "WAL" && !config.walEnabled) {
+        throw new NmtsError("Gifts in WAL are not open right now; SUI is.", { exitCode: 4, nextStep: "Nothing was signed." });
+    }
+    const reads = await (options.readChain ?? (async (net) => (await import("../wallet-send-chain.js")).sendReads(net)))(network);
+    const purse = await reads.readWallet(address);
+    if (!purse.sui.read || !purse.wal.read) {
+        throw new NmtsError("A balance could not be read, so this tool cannot tell whether the wallet can give this.", {
+            exitCode: 1,
+            nextStep: "Nothing was signed. That is not an empty wallet.",
+        });
+    }
+    const verdict = validateSendForm({
+        coin,
+        amountInput: amountRaw,
+        addressInput: config.devAddress,
+        suiBalance: purse.sui.baseUnits,
+        walBalance: purse.wal.baseUnits,
+    });
+    if (!verdict.ok) {
+        const why = verdict.error === "invalidAmount"
+            ? "The amount must be a number above zero, with at most nine decimals."
+            : verdict.error === "noGasForWal"
+                ? "A WAL gift pays its fee in SUI, and the wallet holds less SUI than the reserve kept for that."
+                : verdict.error === "invalidAddress"
+                    ? "The published address is not a Sui address; nothing was sent."
+                    : "The wallet does not hold that much.";
+        throw new NmtsError(why, {
+            exitCode: verdict.error === "invalidAmount" ? 2 : 4,
+            nextStep: `Nothing was signed. The wallet holds ${coinAmount(purse.sui.baseUnits)} SUI and ${coinAmount(purse.wal.baseUnits)} WAL.`,
+        });
+    }
+    const gasBudgetMist = options.feeCap === undefined ? undefined : clampGasBudgetMist(parseTokenAmountToBaseUnits(options.feeCap) ?? 0n);
+    const shape = {
+        coin,
+        amountBaseUnits: verdict.amountBaseUnits,
+        destination: verdict.address,
+        walType: walCoinType(network),
+        gasBudgetMist,
+    };
+    const feeMist = await reads.estimateFee(shape, address);
+    const facts = {
+        to: shape.destination,
+        coin,
+        amountBaseUnits: shape.amountBaseUnits.toString(),
+        amount: coinAmount(shape.amountBaseUnits),
+        feeMist: feeMist === null ? null : feeMist.toString(),
+        feeSui: feeMist === null ? null : coinAmount(feeMist),
+        network,
+    };
+    if (!options.json) {
+        say(`Gift of ${facts.amount} ${coin} to the developer`);
+        say(`  ${shape.destination}`);
+        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.`);
+        say(``);
+        for (const line of GIFT_NOTICES)
+            say(`  ${line}`);
+    }
+    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 send it.`);
+            return 0;
+        }
+        throw new NmtsError("Nothing was signed: a gift needs --yes, every time.", {
+            exitCode: 4,
+            nextStep: `Read the lines above, then: \`${BINARY_NAME} wallet donate ${coin} ${amountRaw} --yes\``,
+        });
+    }
+    const sign = options.sign ?? (await import("../wallet-sign.js")).signTransfer;
+    const digest = await sign({ network, code: resolved.code, shape });
+    if (options.json) {
+        say(JSON.stringify({ ...facts, signed: true, digest, explorerUrl: explorerTxUrl(digest, network) }));
+        return 0;
+    }
+    say(``);
+    say(`  Thank you — your gift was sent. Transaction ${digest}`);
+    say(`  ${explorerTxUrl(digest, network)}`);
+    say(`  Keep that id: no record of this gift exists anywhere else.`);
+    // ⛔ THE OWNER'S OWN THANKS, IN BOTH LANGUAGES, after every gift whatever its size — the same two
+    //    sentences the browser shows and the standing tip prints, held in one place so they cannot
+    //    drift apart.
+    say(``);
+    say(`  ${THANKS_EN}`);
+    say(`  ${THANKS_KO}`);
+    say(`  To be listed by name on nmts.me/hall: ${BINARY_NAME} wallet hall --name <name>`);
+    return 0;
+}

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

@@ -0,0 +1,35 @@
+import type { SignMessage } from "../wallet-sign.ts";
+export interface WalletHallOptions {
+    server?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /** `--name`: be listed under this. `--remove`: go back to a shortened address. */
+    name?: string | undefined;
+    remove?: boolean;
+    /** ⚠ A SEAM, NOT AN OPTION — no flag reaches it. It exists so a test never signs for real. */
+    sign?: SignMessage;
+}
+/** One row of the hall, as this tool needs it. Amounts are base units, exactly as they arrived. */
+export interface HallEntry {
+    rank: number;
+    label: string;
+    wal: bigint;
+    sui: bigint;
+}
+export interface Hall {
+    developerLabel: string;
+    developerAddress: string;
+    /** The day the SUI/WAL comparison rate was measured, as the server states it. */
+    measuredOn: string;
+    entries: HallEntry[];
+}
+/**
+ * The bytes both sides sign and check, spelled once.
+ *
+ * ⛔ EXPORTED SO A TEST CAN HOLD IT. What makes this right is not that it looks right but that the
+ *    server builds the same four lines; a test that rebuilt them from this function would only
+ *    prove the function agrees with itself, so the test writes the four lines out by hand.
+ */
+export declare function hallMessage(address: string, name: string | null, issuedAt: string): string;
+export declare function asHall(value: unknown): Hall;
+export declare function walletHall(options?: WalletHallOptions): Promise<number>;

package/dist/commands/wallet-hall.js

@@ -0,0 +1,214 @@
+// `nmts wallet hall` — who has sent the developer a gift, and the one way to be named in that list.
+//
+// ⛔ THE LIST IS READ OFF A PUBLIC CHAIN, NOT OUT OF AN ACCOUNT. Every gift is a transfer anybody
+//    can see on an explorer; the server only groups them by the address that sent them. So reading
+//    the hall asks for no NMTS key and signs nothing, and there is no "hide me" — what can be
+//    taken off is the NAME, which puts the entry back to a shortened address.
+//
+// ⛔ A NAME IS PUBLISHED, AND THAT IS WHY IT IS SIGNED. The proof that an address is yours is a
+//    signature by that address, so `--name` signs a short message with the wallet this NMTS
+//    key derives (`wallet-sign.ts`) and sends the signature. No session, no API key, no account
+//    id goes with it — the server is told an address, a name and a signature, and nothing else.
+//
+// ⛔ THE MESSAGE IS BUILT IN ONE PLACE, `hallMessage` BELOW, because the server rebuilds the same
+//    bytes from the fields it was sent and compares. A space added on either side makes every
+//    signature invalid, and the failure would read as a rejected signature rather than as a typo.
+import { request, ServerError, HttpError } from "../api.js";
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile } from "../credentials.js";
+import { NmtsError } from "../errors.js";
+import { isRecord } from "../guards.js";
+import { BINARY_NAME, HOME_URL } from "../product.js";
+import { resolveServer } from "../server.js";
+import { coinAmount, walletAddress } from "../wallet.js";
+/** How many rows a terminal gets. The page at the site carries the rest. */
+const SHOWN = 10;
+/**
+ * The bytes both sides sign and check, spelled once.
+ *
+ * ⛔ EXPORTED SO A TEST CAN HOLD IT. What makes this right is not that it looks right but that the
+ *    server builds the same four lines; a test that rebuilt them from this function would only
+ *    prove the function agrees with itself, so the test writes the four lines out by hand.
+ */
+export function hallMessage(address, name, issuedAt) {
+    return `NMTS hall of fame\naddress: ${address}\nname: ${name ?? "(none)"}\nat: ${issuedAt}`;
+}
+/** Base units as the server sends them: a decimal string, because a JSON number would round it. */
+function baseUnits(value, field) {
+    if (typeof value === "string" && /^[0-9]+$/u.test(value))
+        return BigInt(value);
+    throw new NmtsError(`The server's hall answer carries a ${field} this version cannot read.`, { exitCode: 1 });
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+export function asHall(value) {
+    if (!isRecord(value))
+        throw new NmtsError("The server's hall answer is not the shape this version reads.", { exitCode: 1 });
+    const developer = value["developer"];
+    const rate = value["referenceRate"];
+    const rows = value["entries"];
+    const entries = [];
+    for (const row of Array.isArray(rows) ? rows : []) {
+        if (!isRecord(row))
+            continue;
+        const rank = row["rank"];
+        entries.push({
+            rank: typeof rank === "number" ? rank : entries.length + 1,
+            label: text(row["label"]),
+            wal: baseUnits(row["wal"], "WAL amount"),
+            sui: baseUnits(row["sui"], "SUI amount"),
+        });
+    }
+    return {
+        developerLabel: isRecord(developer) ? text(developer["label"]) : "",
+        developerAddress: isRecord(developer) ? text(developer["address"]) : "",
+        measuredOn: isRecord(rate) ? text(rate["measuredOn"]) : "",
+        entries,
+    };
+}
+/**
+ * What the server refused, in one sentence a person or an agent can act on.
+ *
+ * ⛔ BY CODE, NEVER BY MESSAGE. The server's own words may be rewritten any day; the codes are the
+ *    contract. A code this version does not know falls through to the server's own sentence rather
+ *    than to a guess.
+ */
+const REFUSALS = {
+    gift_not_found: {
+        line: "Your gift is not in the list yet. It appears within an hour; try again then.",
+        exitCode: 4,
+        nextStep: "Nothing was published. The gift itself is on the chain either way.",
+    },
+    name_invalid: {
+        line: "A name is 1 to 24 characters, no links, not an address.",
+        exitCode: 2,
+        nextStep: "Nothing was published. Choose another name and run the same command again.",
+    },
+    listing_stale: {
+        line: "A newer listing request exists; try again.",
+        exitCode: 4,
+        nextStep: "Nothing was published. Something else set this address's name after this run started.",
+    },
+    signature_invalid: {
+        line: "The server did not accept the signature.",
+        exitCode: 1,
+        nextStep: `Nothing was published. \`${BINARY_NAME} wallet address\` shows the wallet this run signs as.`,
+    },
+};
+/** The server the sealed sign-in points at, when there is one this run can read. */
+function storedServer() {
+    try {
+        return readCredentialsFile()?.server;
+    }
+    catch {
+        // A sign-in file this run cannot open is no reason to refuse a public listing: the default
+        // server answers it. Every command that actually needs that file still reports what is wrong.
+        return undefined;
+    }
+}
+export async function walletHall(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const server = resolveServer(options.server ?? storedServer());
+    if (options.name !== undefined && options.remove === true) {
+        throw new NmtsError("Say one of --name and --remove, not both.", {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} wallet hall --name <name>\` lists a name; \`--remove\` takes it off.`,
+        });
+    }
+    if (options.name === undefined && options.remove !== true)
+        return await show(server, say, options);
+    return await setName(server, say, options);
+}
+/** `nmts wallet hall` — the developer, the top rows, and where the rest of them are. */
+async function show(server, say, options) {
+    const answer = await readHall(server);
+    if (!answer.mounted) {
+        if (options.json === true)
+            say(JSON.stringify({ entries: [] }));
+        else
+            say(`No gift has arrived yet.`);
+        return 0;
+    }
+    if (options.json === true) {
+        say(JSON.stringify(answer.body));
+        return 0;
+    }
+    const hall = asHall(answer.body);
+    say(`Hall of fame — everyone who sent the developer a gift`);
+    say(`  ${hall.developerLabel} — builds NMTS`);
+    say(`  ${hall.developerAddress}`);
+    say(``);
+    if (hall.entries.length === 0) {
+        say(`  No gift has arrived yet.`);
+        return 0;
+    }
+    const shown = hall.entries.slice(0, SHOWN).map((row) => ({ ...row, walText: coinAmount(row.wal), suiText: coinAmount(row.sui) }));
+    // ⛔ THE AMOUNTS ARE RIGHT-ALIGNED AND NEVER SHORTENED. `coinAmount` prints the exact value, so
+    //    the columns are as wide as the widest row rather than rounded to fit.
+    const label = Math.max(...shown.map((row) => row.label.length));
+    const wal = Math.max(...shown.map((row) => row.walText.length));
+    const sui = Math.max(...shown.map((row) => row.suiText.length));
+    for (const row of shown) {
+        say(`  ${String(row.rank).padStart(3)}. ${row.label.padEnd(label)}  ${row.walText.padStart(wal)} WAL  ${row.suiText.padStart(sui)} SUI`);
+    }
+    const rest = hall.entries.length - shown.length;
+    say(``);
+    if (rest > 0)
+        say(`  ${rest} more ${rest === 1 ? "entry is" : "entries are"} in the list at ${HOME_URL}/hall.`);
+    say(`  Ranked by cumulative amount; SUI and WAL are compared at a reference rate measured on ${hall.measuredOn}.`);
+    return 0;
+}
+/**
+ * The read itself.
+ *
+ * ⛔ A 404 IS "NOTHING TO SHOW", NOT A BREAKAGE. The routes are mounted only where the server holds
+ *    a gift address, so a server that takes no gifts answers 404 — the same answer the browser
+ *    page draws its empty state from. Every other failure is reported as itself.
+ */
+async function readHall(server) {
+    try {
+        return { mounted: true, body: await request(server, "/v1/gifts/hall") };
+    }
+    catch (error) {
+        const status = error instanceof HttpError || error instanceof ServerError ? error.status : 0;
+        if (status === 404)
+            return { mounted: false, body: null };
+        throw error;
+    }
+}
+/** `--name` and `--remove`: sign the message, send it, and say what the hall shows now. */
+async function setName(server, say, options) {
+    const resolved = await requireAccountCode();
+    // ⛔ The address is derived here rather than taken from a flag: a signature only proves ownership
+    //    of the address it was made by, so the two must come from the same NMTS key.
+    const address = await walletAddress(resolved.code);
+    const name = options.remove === true ? null : (options.name ?? null);
+    const issuedAt = new Date(Date.now()).toISOString();
+    const message = hallMessage(address, name, issuedAt);
+    const sign = options.sign ?? (await import("../wallet-sign.js")).signMessage;
+    const signature = await sign({ code: resolved.code, message });
+    let answer;
+    try {
+        answer = await request(server, "/v1/gifts/listing", {
+            method: "POST",
+            body: { address, name, issuedAt, signature },
+        });
+    }
+    catch (error) {
+        const known = error instanceof ServerError ? REFUSALS[error.code] : undefined;
+        if (known === undefined)
+            throw error;
+        throw new NmtsError(known.line, { exitCode: known.exitCode, nextStep: known.nextStep });
+    }
+    if (options.json === true) {
+        say(JSON.stringify(answer));
+        return 0;
+    }
+    const label = isRecord(answer) ? text(answer["label"]) : "";
+    say(`Listed as ${label}`);
+    say(``);
+    say(`  The hall of fame is at ${HOME_URL}/hall. Run \`${BINARY_NAME} wallet hall --remove\` to go`);
+    say(`  back to a shortened address; the gifts themselves stay on the chain either way.`);
+    return 0;
+}

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

@@ -0,0 +1,22 @@
+import { type Network } from "../network.ts";
+import type { SendReads } from "../wallet-send-chain.ts";
+import type { SignTransfer } from "../wallet-sign.ts";
+export interface WalletSendOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /** Actually send. Without it the review is printed and nothing is signed. */
+    yes?: boolean;
+    /** Print the review and stop, even with --yes. */
+    dryRun?: boolean;
+    /** A ceiling on the fee, in SUI ("0.01"). Clamped to the usable range, never refused. */
+    feeCap?: string | undefined;
+    /** The instant to measure the wallet agreement against. */
+    now?: number;
+    /** ⚠ A SEAM, NOT AN OPTION — no flag reaches it. */
+    readChain?: (network: Network) => SendReads | Promise<SendReads>;
+    /** ⛔ SEPARATE FROM THE READS so a test can prove the review stops before this. */
+    sign?: SignTransfer;
+}
+export declare function walletSend(operands: readonly string[], options?: WalletSendOptions): Promise<number>;

package/dist/commands/wallet-send.js

@@ -0,0 +1,153 @@
+// `nmts wallet send <SUI|WAL> <amount|max> <address>` — move coins out of the wallet this NMTS
+// key derives, to one address. ⛔ THE ONE COMMAND BESIDES `extend` THAT SIGNS.
+//
+// ⛔ THE ORDER IS THE SAFETY. ① the address and the amount are judged by the browser's own rules
+//    (`shared/lib/wallet/send-rules.ts`, copied byte-for-byte) ② both balances are READ, and an
+//    unread one stops the run — it is not zero ③ the exact transfer is dry-run for its fee ④ the
+//    review is printed: the whole address, the amount, the fee, what is left ⑤ without `--yes`
+//    that is the end — a transfer to a typed address cannot be undone, and this tool has no
+//    prompt (`consent.ts`: a command, not a keystroke) ⑥ the wallet agreement is held against
+//    the amount and the fee, scope `all` (`wallet-grant.ts`) ⑦ 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. Whether an agent may send money on its own is the person's `mode` and `--scope all`
+//    decision at the command line, said in AGENTS.md — not a tool a model finds in a 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 { explorerTxUrl } from "../shared/lib/wallet/activity.js";
+import { clampGasBudgetMist, maxSendableBaseUnits, parseTokenAmountToBaseUnits, validateSendForm, } from "../shared/lib/wallet/send-rules.js";
+import { coinAmount, walCoinType, walletAddress } from "../wallet.js";
+import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
+const COIN_WORDS = {
+    invalidAddress: "That is not a Sui address: it is 0x followed by 64 hexadecimal characters.",
+    invalidAmount: "The amount must be a number above zero, with at most nine decimals.",
+    insufficientBalance: "The wallet does not hold that much.",
+    noGasForWal: "A WAL transfer pays its fee in SUI, and the wallet holds less SUI than the reserve kept for that.",
+};
+function coinOf(raw) {
+    const up = (raw ?? "").toUpperCase();
+    if (up === "SUI" || up === "WAL")
+        return up;
+    throw new NmtsError("Say which coin: SUI or WAL.", {
+        exitCode: 2,
+        nextStep: `\`${BINARY_NAME} wallet send <SUI|WAL> <amount|max> <address>\``,
+    });
+}
+export async function walletSend(operands, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const [coinRaw, amountRaw, destinationRaw] = operands;
+    const coin = coinOf(coinRaw);
+    if (amountRaw === undefined || destinationRaw === undefined) {
+        throw new NmtsError("Say how much, and to which address.", {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} wallet send ${coin} <amount|max> <address>\` — "max" sends everything that can be sent.`,
+        });
+    }
+    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 = await (options.readChain ?? (async (net) => (await import("../wallet-send-chain.js")).sendReads(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 sent.", {
+            exitCode: 1,
+            nextStep: `Nothing was signed. That is not an empty wallet — ${which.join("; ")}.`,
+        });
+    }
+    const suiBalance = purse.sui.baseUnits;
+    const walBalance = purse.wal.baseUnits;
+    // ① The rules — the browser's, unchanged.
+    const amountInput = amountRaw.toLowerCase() === "max"
+        ? coinAmount(maxSendableBaseUnits({ coin, suiBalance, walBalance }))
+        : amountRaw;
+    const verdict = validateSendForm({ coin, amountInput, addressInput: destinationRaw, suiBalance, walBalance });
+    if (!verdict.ok) {
+        const exit = verdict.error === "invalidAddress" || verdict.error === "invalidAmount" ? 2 : 4;
+        throw new NmtsError(COIN_WORDS[verdict.error], {
+            exitCode: exit,
+            nextStep: `Nothing was signed. The wallet holds ${coinAmount(suiBalance)} SUI and ${coinAmount(walBalance)} WAL; ` +
+                `the most that can be sent is ${coinAmount(maxSendableBaseUnits({ coin, suiBalance, walBalance }))} ${coin} ` +
+                `(SUI keeps a reserve back for fees).`,
+        });
+    }
+    const gasBudgetMist = options.feeCap === undefined ? undefined : clampGasBudgetMist(parseTokenAmountToBaseUnits(options.feeCap) ?? 0n);
+    const shape = {
+        coin,
+        amountBaseUnits: verdict.amountBaseUnits,
+        destination: verdict.address,
+        walType: walCoinType(network),
+        gasBudgetMist,
+    };
+    // ③ The fee of this exact transfer.
+    const feeMist = await reads.estimateFee(shape, address);
+    const suiAfter = suiBalance - (coin === "SUI" ? shape.amountBaseUnits : 0n) - (feeMist ?? 0n);
+    const walAfter = walBalance - (coin === "WAL" ? shape.amountBaseUnits : 0n);
+    const facts = {
+        from: address,
+        to: shape.destination,
+        coin,
+        amountBaseUnits: shape.amountBaseUnits.toString(),
+        amount: coinAmount(shape.amountBaseUnits),
+        feeMist: feeMist === null ? null : feeMist.toString(),
+        feeSui: feeMist === null ? null : coinAmount(feeMist),
+        feeCapMist: gasBudgetMist === undefined ? null : gasBudgetMist.toString(),
+        network,
+        suiAfter: coinAmount(suiAfter < 0n ? 0n : suiAfter),
+        walAfter: coinAmount(walAfter < 0n ? 0n : walAfter),
+    };
+    // ④ The review, every time.
+    if (!options.json) {
+        say(`Sending ${facts.amount} ${coin}`);
+        say(`  to    ${shape.destination}`);
+        say(`  from  ${address}`);
+        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(`  Afterwards the wallet holds about ${facts.suiAfter} SUI and ${facts.walAfter} WAL.`);
+        say(``);
+        say(`  ⛔ A transfer cannot be undone by anybody, NMTS included. Check the address once more.`);
+    }
+    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 send it.`);
+            return 0;
+        }
+        throw new NmtsError("Nothing was signed: sending needs --yes.", {
+            exitCode: 4,
+            nextStep: `Read the review above, then: \`${BINARY_NAME} wallet send ${coin} ${amountRaw} ${shape.destination} --yes\``,
+        });
+    }
+    // ⑥ The agreement — scope `all`, the amount and the fee held against its ceiling.
+    const spend = {
+        walFrost: coin === "WAL" ? shape.amountBaseUnits : 0n,
+        suiMist: (coin === "SUI" ? shape.amountBaseUnits : 0n) + (feeMist ?? 0n),
+    };
+    requireWalletGrant("send", spend, new Date(options.now ?? Date.now()));
+    // ⑦ The signature.
+    const sign = options.sign ?? (await import("../wallet-sign.js")).signTransfer;
+    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(`  Sent. Transaction ${digest}`);
+    say(`  ${explorerTxUrl(digest, network)}`);
+    return 0;
+}

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

@@ -0,0 +1,24 @@
+import { type Network } from "../network.ts";
+import { type StorageOpsReads } from "../storage-control-chain.ts";
+import type { SignStorageOp } from "../wallet-sign.ts";
+export type StorageOp = "split" | "merge" | "transfer";
+export interface StorageOpsOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    yes?: boolean;
+    dryRun?: boolean;
+    /** `split --size <bytes|KiB|MiB|GiB>`: what the named resource keeps; the rest becomes a new one. */
+    size?: string | undefined;
+    /** `split --epochs <n>`: how many epochs, from its start, the named resource keeps. */
+    epochs?: string | undefined;
+    now?: number;
+    /** ⚠ A SEAM, NOT AN OPTION — no flag reaches it. */
+    storageReads?: (network: Network) => StorageOpsReads;
+    /** ⛔ SEPARATE FROM THE READS so a test can prove the review stops before this. */
+    signStorage?: SignStorageOp;
+}
+export declare function walletStorageOps(op: StorageOp, rest: readonly string[], options?: StorageOpsOptions): Promise<number>;
+/** "500MiB", "1GiB", "4096" — bytes, in binary units, the way the listing prints them. */
+export declare function parseBytes(text: string): number;