@needmoretruth/nmts-cli 0.34.4 → 0.36.1

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

@@ -0,0 +1,18 @@
+import { type Network } from "../network.ts";
+import { type ChainReader } from "../wallet.ts";
+export interface WalletListOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+    /** ⚠ SEAMS, NOT OPTIONS — no flag reaches either. A live chain cannot be asked to fail on demand. */
+    openChain?: (network: Network, address: string) => Promise<ChainReader> | ChainReader;
+    /** Has this address any transaction at all? A wallet that has been emptied is still in use. */
+    hasHistory?: (network: Network, address: string) => Promise<boolean>;
+    /** The account's own numbers, out of the sealed list. */
+    readWalletSettings?: () => Promise<{
+        active: number;
+        count: number;
+    }>;
+}
+export declare function walletList(options?: WalletListOptions): Promise<number>;

package/dist/commands/wallet-list.js

@@ -0,0 +1,116 @@
+// `nmts wallet list` — every wallet this NMTS key has, what is in it, and which one pays.
+//
+// ⛔ IT READS. Nothing here signs, and nothing here writes the account's choice: `wallet use N`
+//    does that. Running this repeatedly costs nothing but questions to a public node.
+//
+// ⛔ WHICH WALLETS EXIST IS NOT A LIST ANYBODY KEEPS. One key derives a wallet at every index
+//    (NCF-3 §1.3), so "how many do I have" is answered by WALKING — ask about a number, then the
+//    next, and stop after twenty unused ones in a row. That rule is the browser's own, copied
+//    byte-for-byte (`shared/lib/wallet/discover.ts`), so the same key shows the same wallets in
+//    both programs. ⚠ A wallet funded further out than the gap is not found by the walk; it is not
+//    lost — `--wallet N` and `wallet use N` reach any number directly.
+//
+// ⛔ A BALANCE THAT COULD NOT BE READ IS PRINTED AS THAT, NEVER AS ZERO, and the run exits
+//    non-zero — the same rule as `nmts wallet`, for the same reason: an empty wallet and an
+//    unanswered question look identical on a screen, and one of them is a reason to stop.
+import { requireAccountCode } from "../code-access.js";
+import { readCredentialsFile } from "../credentials.js";
+import { readFileList } from "../manifest.js";
+import { resolveNetwork } from "../network.js";
+import { BINARY_NAME } from "../product.js";
+import { resolveServer } from "../server.js";
+import { openSession } from "../session.js";
+import { activeWalletOf, walletCountOf } from "../shared/lib/drive/manifest-settings.js";
+import { discoverWallets } from "../shared/lib/wallet/discover.js";
+import { coinAmount, readBalances, walCoinType, walletAddress, SUI_COIN_TYPE, } from "../wallet.js";
+/** The table's column widths. A Sui address is 66 characters and gets two spaces after it. */
+const NUMBER_W = 8;
+const ADDRESS_W = 68;
+const AMOUNT_W = 21;
+export async function walletList(options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const resolved = await requireAccountCode();
+    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 walType = walCoinType(network);
+    const settings = await (options.readWalletSettings ?? (() => walletSettings(options)))();
+    const open = options.openChain ??
+        (async (net, addr) => (await import("../wallet-chain.js")).chainReader(net, addr));
+    const history = options.hasHistory ??
+        (async (net, addr) => (await import("../wallet-list-chain.js")).hasHistory(net, addr));
+    // Every number the walk asked about, so nothing is derived or read twice.
+    const seen = new Map();
+    const scan = await discoverWallets(async (index) => {
+        const address = await walletAddress(resolved.code, index);
+        const balances = await readBalances(await open(network, address), walType);
+        seen.set(index, { index, address, balances });
+        const held = (b) => b.read && b.baseUnits > 0n;
+        if (held(balances.sui) || held(balances.wal))
+            return true;
+        return history(network, address);
+    }, { count: settings.count });
+    // What is printed: the wallets this account has made, plus any the walk found beyond them. The
+    // rest of the walk is the gap — empty wallets nobody has asked for.
+    const rows = [...seen.values()]
+        .filter((row) => row.index < settings.count || scan.used.includes(row.index))
+        .sort((a, b) => a.index - b.index);
+    const unread = rows.some((row) => !row.balances.sui.read || !row.balances.wal.read);
+    if (options.json === true) {
+        say(JSON.stringify({
+            network,
+            active: settings.active,
+            scanned: scan.scanned,
+            wallets: rows.map((row) => ({
+                index: row.index,
+                address: row.address,
+                pays: row.index === settings.active,
+                sui: asJson(row.balances.sui, SUI_COIN_TYPE),
+                wal: asJson(row.balances.wal, walType),
+            })),
+        }));
+        return unread ? 1 : 0;
+    }
+    // ⚠ The columns are laid out with the same widths the rows use, from the same constants — a
+    //   header written out by hand drifts one space at a time until nothing lines up.
+    say(`${"Wallet".padEnd(NUMBER_W)}${"Address".padEnd(ADDRESS_W)}${"SUI".padEnd(AMOUNT_W)}WAL`);
+    for (const row of rows) {
+        const pays = row.index === settings.active ? "  pays" : "";
+        say(`${String(row.index).padEnd(NUMBER_W)}${row.address.padEnd(ADDRESS_W)}` +
+            `${inWords(row.balances.sui).padEnd(AMOUNT_W)}${inWords(row.balances.wal)}${pays}`);
+    }
+    say(``);
+    say(`  Every wallet above comes from this NMTS key, at the number in the first column. The one`);
+    say(`  marked "pays" is the one storage is paid from — \`${BINARY_NAME} wallet use <number>\` moves it,`);
+    say(`  on this account rather than on this machine. Numbers come from the key, so a wallet`);
+    say(`  cannot be deleted.`);
+    say(`  The list stops after twenty unused wallets in a row; a wallet further out than that is`);
+    say(`  reached by its number.`);
+    if (unread) {
+        say(`  A balance that could not be read is printed as that and never as zero, and this command`);
+        say(`  exits non-zero when it happens.`);
+    }
+    return unread ? 1 : 0;
+}
+/** The account's own numbers, read out of the sealed file list. */
+async function walletSettings(options) {
+    const session = await openSession({ server: options.server, network: options.network });
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    const settings = list.manifest?.settings;
+    return { active: activeWalletOf(settings), count: walletCountOf(settings) };
+}
+/** One balance, for a person. The same two sentences `nmts wallet` prints. */
+function inWords(balance) {
+    return balance.read ? coinAmount(balance.baseUnits) : `⛔ could not be read`;
+}
+/** One balance, for a program. `baseUnits` is a string: a balance outruns a JSON number. */
+function asJson(balance, coinType) {
+    if (!balance.read)
+        return { coinType, read: false, error: balance.why };
+    return {
+        coinType,
+        read: true,
+        baseUnits: balance.baseUnits.toString(),
+        amount: coinAmount(balance.baseUnits),
+    };
+}

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

@@ -12,6 +12,10 @@ export interface WalletSendOptions {
     dryRun?: boolean;
     /** A ceiling on the fee, in SUI ("0.01"). Clamped to the usable range, never refused. */
     feeCap?: string | undefined;
+    /** `--wallet N`: which wallet pays, this run only. Absent = the account's own number. */
+    wallet?: string | undefined;
+    /** ⚠ A SEAM, NOT AN OPTION — where that number is read from (`wallet-pay-index.ts`). */
+    readActiveWallet?: () => Promise<number>;
     /** The instant to measure the wallet agreement against. */
     now?: number;
     /** ⚠ A SEAM, NOT AN OPTION — no flag reaches it. */

package/dist/commands/wallet-send.js

@@ -21,6 +21,7 @@ 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 { payingWalletIndex } from "../wallet-pay-index.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.",
@@ -48,7 +49,10 @@ export async function walletSend(operands, options = {}) {
         });
     }
     const resolved = await requireAccountCode();
-    const address = await walletAddress(resolved.code);
+    // ⛔ WHICH WALLET PAYS, FIRST — everything below is about one address: the balances that are
+    //    read, the fee that is measured, the line the review prints, and the key that signs.
+    const wallet = await payingWalletIndex(options);
+    const address = await walletAddress(resolved.code, wallet);
     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);
@@ -140,7 +144,7 @@ export async function walletSend(operands, options = {}) {
     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 });
+    const digest = await sign({ network, code: resolved.code, wallet, shape });
     recordWalletSpend(spend);
     if (options.json) {
         say(JSON.stringify({ ...facts, signed: true, digest, explorerUrl: explorerTxUrl(digest, network) }));

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

@@ -13,8 +13,11 @@ export interface StorageOpsOptions {
     size?: string | undefined;
     /** `split --epochs <n>`: how many epochs, from its start, the named resource keeps. */
     epochs?: string | undefined;
+    /** `--wallet N`: whose resources these are, this run only. Absent = the account's own number. */
+    wallet?: string | undefined;
     now?: number;
-    /** ⚠ A SEAM, NOT AN OPTION — no flag reaches it. */
+    /** ⚠ SEAMS, NOT OPTIONS — no flag reaches them. */
+    readActiveWallet?: () => Promise<number>;
     storageReads?: (network: Network) => StorageOpsReads;
     /** ⛔ SEPARATE FROM THE READS so a test can prove the review stops before this. */
     signStorage?: SignStorageOp;

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

@@ -23,6 +23,7 @@ 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 { payingWalletIndex } from "../wallet-pay-index.js";
 import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
 import { formatBytes } from "./wallet-storage.js";
 const FUSE_WHY = {
@@ -34,7 +35,10 @@ const FUSE_WHY = {
 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);
+    // ⛔ WHICH WALLET, FIRST — the resources are read from this address, the review names it, and the
+    //    same wallet signs; a resource is reshaped by the wallet that holds it and by no other.
+    const wallet = await payingWalletIndex(options);
+    const address = await walletAddress(resolved.code, wallet);
     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);
@@ -76,6 +80,7 @@ export async function walletStorageOps(op, rest, options = {}) {
     // ④ The review.
     if (!options.json) {
         say(`Would ${lines.what}`);
+        say(`  from  ${address} (wallet ${wallet})`);
         for (const l of lines.detail)
             say(`  ${l}`);
         say(feeMist === null
@@ -106,7 +111,7 @@ export async function walletStorageOps(op, rest, options = {}) {
     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 });
+    const digest = await sign({ network, code: resolved.code, wallet, shape, walrusPackageId });
     recordWalletSpend(spend);
     if (options.json) {
         say(JSON.stringify({ ...facts, signed: true, digest, explorerUrl: explorerTxUrl(digest, network) }));

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

@@ -22,8 +22,11 @@ export interface WalletSwapOptions {
     slippageBps?: string | undefined;
     /** `--accept-extremes`: go on past the extremes gate. A person's act — refused outside mode off. */
     acceptExtremes?: boolean;
+    /** `--wallet N`: which wallet swaps, this run only. Absent = the account's own number. */
+    wallet?: string | undefined;
     now?: number;
     /** ⚠ SEAMS, NOT OPTIONS — no flag reaches them. */
+    readActiveWallet?: () => Promise<number>;
     readChain?: (network: Network) => SwapReads | Promise<SwapReads>;
     readPrices?: (server: string) => Promise<MarketPrices | null>;
     sign?: SignSwap;

package/dist/commands/wallet-swap.js

@@ -25,6 +25,7 @@ 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 { payingWalletIndex } from "../wallet-pay-index.js";
 import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
 import { railsFor } from "../wallet-swap-chain.js";
 const EXTREME_WORDS = {
@@ -73,7 +74,10 @@ export async function walletSwap(operands, options = {}) {
         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);
+    // ⛔ WHICH WALLET SWAPS, FIRST — the coins that are read, the quote that is priced, the address
+    //    the review names and the key that signs are all this one wallet's.
+    const wallet = await payingWalletIndex(options);
+    const address = await walletAddress(resolved.code, wallet);
     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);
@@ -211,7 +215,7 @@ export async function walletSwap(operands, options = {}) {
     // ⑥ The review, every time.
     if (!options.json) {
         say(`Swapping ${facts.amountIn} ${coinIn} for ${coinOut} on ${venueName(venue)}`);
-        say(`  from      ${address}`);
+        say(`  from      ${address} (wallet ${wallet})`);
         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`);
@@ -244,7 +248,7 @@ export async function walletSwap(operands, options = {}) {
                 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();
+        const mode = await 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.` });
         }
@@ -273,7 +277,7 @@ export async function walletSwap(operands, options = {}) {
     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 });
+    const digest = await sign({ network, code: resolved.code, wallet, shape });
     recordWalletSpend(spend);
     if (options.json) {
         say(JSON.stringify({ ...facts, signed: true, digest, explorerUrl: explorerTxUrl(digest, network) }));

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

@@ -0,0 +1,7 @@
+export interface WalletUseOptions {
+    server?: string | undefined;
+    network?: string | undefined;
+    json?: boolean;
+    write?: (line: string) => void;
+}
+export declare function walletUse(said: string | undefined, options?: WalletUseOptions): Promise<number>;

package/dist/commands/wallet-use.js

@@ -0,0 +1,55 @@
+// `nmts wallet use <number>` — which of this key's wallets pays for storage from now on.
+//
+// ⛔ IT WRITES THE ACCOUNT'S CHOICE, NOT THIS MACHINE'S. The number lives inside the sealed file
+//    list (`activeWallet`), where the server cannot read it and where a phone, a laptop and this
+//    tool all find the same answer. That is the whole point: money leaving from one address on one
+//    device and another address on another is how a balance goes missing without anything failing.
+//
+// ⛔ THE LIST IS WHERE THE SETTING LIVES, so an account with no list has nowhere to put it — the
+//    same refusal `nmts padding` gives, for the same reason, and the same way out: upload once.
+//
+// ⛔ NOTHING IS DELETED AND NOTHING IS CREATED. Every number a key can derive already exists
+//    (NCF-3 §1.3); this says which of them the next payment comes out of, and takes the count up
+//    with it so every screen lists the wallet it just named.
+import { NmtsError } from "../errors.js";
+import { readFileList } from "../manifest.js";
+import { applyManyToList } from "../manifest-write.js";
+import { BINARY_NAME } from "../product.js";
+import { openSession } from "../session.js";
+import { walletIndexOf } from "../wallet-pay-index.js";
+import { walletAddress } from "../wallet.js";
+export async function walletUse(said, options = {}) {
+    const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    if (said === undefined || said === "") {
+        throw new NmtsError(`Say which wallet: \`${BINARY_NAME} wallet use <number>\`.`, {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} wallet list\` shows this key's wallets and which one pays now.`,
+        });
+    }
+    // ⛔ BEFORE THE NETWORK. A misspelled number is a command line to fix, not a question to ask the
+    //    server, and a run that opened a session first would refuse for the wrong reason.
+    const index = walletIndexOf(said);
+    const session = await openSession({ server: options.server, network: options.network });
+    const before = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    if (before.manifest === null) {
+        throw new NmtsError(`This account has no file list yet; which wallet pays lives in the list, and there is nothing to write it into.`, { exitCode: 4, nextStep: `Upload once (\`${BINARY_NAME} put\`) and set it after.` });
+    }
+    const result = await applyManyToList(session, () => [], { activeWallet: index });
+    const address = await walletAddress(session.code, index);
+    if (options.json === true) {
+        say(JSON.stringify({ wallet: index, address, changed: result.changed }));
+        return 0;
+    }
+    if (!result.changed) {
+        say(`Wallet ${index} was already the one that pays. Nothing changed.`);
+        say(`Address  ${address}`);
+        return 0;
+    }
+    say(`Wallet ${index} pays from now on.`);
+    say(`Address  ${address}`);
+    say(``);
+    say(`  Storage paid from this account's wallet now leaves this address, on every device — the`);
+    say(`  number rides in the sealed file list, not on this machine. What is already stored is`);
+    say(`  unaffected, and the wallets you were using keep whatever is in them.`);
+    return 0;
+}

package/dist/commands/wallet.d.ts

@@ -7,6 +7,10 @@ export interface WalletOptions {
     write?: (line: string) => void;
     /** `wallet address --qr`: the address as a code a phone can scan, drawn in the terminal. */
     qr?: boolean;
+    /** `wallet address --index N`: which of this key's wallets to print. Absent = the first one. */
+    index?: string | undefined;
+    /** `--wallet N` on `send`/`donate`/`swap`/`storage`/`hall`: which wallet, this run only. */
+    wallet?: string | undefined;
     /** `wallet send`: the operands after "send", and its flags (`wallet-send.ts`). */
     rest?: readonly string[];
     yes?: boolean;

package/dist/commands/wallet.js

@@ -22,9 +22,10 @@ import { NmtsError } from "../errors.js";
 import { resolveNetwork } from "../network.js";
 import { BINARY_NAME } from "../product.js";
 import { resolveServer } from "../server.js";
-import { coinAmount, readBalances, walCoinType, walletAddress, SUI_COIN_TYPE, } from "../wallet.js";
+import { walletIndexOf } from "../wallet-pay-index.js";
+import { BUILT_IN_WALLET_INDEX, coinAmount, readBalances, walCoinType, walletAddress, SUI_COIN_TYPE, } from "../wallet.js";
 /** What the operand may say. Anything else is a command line to correct, not a guess to act on. */
-const MODES = ["address", "balance", "activity", "storage", "send", "donate", "swap", "hall"];
+const MODES = ["address", "balance", "list", "use", "activity", "storage", "send", "donate", "swap", "hall"];
 function modeOf(what) {
     if (what === undefined)
         return "balance";
@@ -33,7 +34,9 @@ function modeOf(what) {
         return found;
     throw new NmtsError(`\`${BINARY_NAME} wallet ${what}\` is not something this command does.`, {
         exitCode: 2,
-        nextStep: `\`${BINARY_NAME} wallet\` shows the address and the balances; \`${BINARY_NAME} wallet address\` ` +
+        nextStep: `\`${BINARY_NAME} wallet\` shows the address and the balances; \`${BINARY_NAME} wallet list\` ` +
+            `shows every wallet this key has and which one pays, and \`${BINARY_NAME} wallet use <number>\` ` +
+            `moves that. \`${BINARY_NAME} wallet address\` ` +
             `shows the address alone, without touching a network (add --qr for a code to scan); ` +
             `\`${BINARY_NAME} wallet activity\` lists the recent transactions; \`${BINARY_NAME} wallet storage\` ` +
             `lists the storage resources it holds. None of those signs. \`${BINARY_NAME} wallet send <SUI|WAL> ` +
@@ -48,6 +51,11 @@ export async function wallet(what, options = {}) {
     // The two lists live in files of their own; each reads through a seam of its own.
     if (mode === "activity")
         return (await import("./wallet-activity.js")).walletActivity(options);
+    // Every wallet of this key and which one pays: listing reads, choosing writes one line of the list.
+    if (mode === "list")
+        return (await import("./wallet-list.js")).walletList(options);
+    if (mode === "use")
+        return (await import("./wallet-use.js")).walletUse(options.rest?.[0], options);
     if (mode === "storage") {
         const [sub, ...more] = options.rest ?? [];
         if (sub === "split" || sub === "merge" || sub === "transfer") {
@@ -70,13 +78,17 @@ export async function wallet(what, options = {}) {
     if (mode === "hall")
         return (await import("./wallet-hall.js")).walletHall(options);
     const resolved = await requireAccountCode();
-    const address = await walletAddress(resolved.code);
+    // ⛔ `wallet address --index N` IS OFFLINE — the person named the number, so there is no list to
+    //    read; without a number it is the first wallet. "Which one pays" is a question the list
+    //    answers, and `wallet list` is where it is asked.
+    const index = options.index === undefined || options.index === "" ? BUILT_IN_WALLET_INDEX : walletIndexOf(options.index);
+    const address = await walletAddress(resolved.code, index);
     if (mode === "address") {
         if (options.json) {
-            // ⛔ NO `network` FIELD. There is no network in this answer — an account has one wallet and
-            //    it is called the same thing on every chain — and a field naming one would invite a
-            //    reader to believe this address was looked up somewhere.
-            say(JSON.stringify({ address }));
+            // ⛔ NO `network` FIELD. There is no network in this answer — a wallet is the same wallet on
+            //    every chain — and a field naming one would invite a reader to believe this address was
+            //    looked up somewhere. The NUMBER is here, because it is what the address came from.
+            say(JSON.stringify({ address, index }));
             return 0;
         }
         say(`Address  ${address}`);

package/dist/crypto.d.ts

@@ -1,4 +1,4 @@
-import { type CryptoGlue } from "./crypto-surface.ts";
+import type { CryptoGlue } from "./crypto-surface.ts";
 export type { CryptoGlue, StreamOpener, StreamSealer } from "./crypto-surface.ts";
 /**
  * The associated-data strings of NCF-3, for the envelopes this tool opens.
@@ -74,8 +74,11 @@ export declare const DERIVED: {
      */
     readonly aiAccountRoot: readonly [256, 288];
 };
-export declare function engineDir(): string;
-/** Load the engine once per process. */
+/**
+ * The engine, loaded once by whichever host this program registered.
+ *
+ * Every derivation in the package goes through this one call, so a program that has not registered
+ * a host is told so here rather than somewhere deeper, where the message would be about a missing
+ * function instead of a missing entry point.
+ */
 export declare function loadCrypto(): Promise<CryptoGlue>;
-/** For tests that need a fresh load. */
-export declare function forgetCrypto(): void;

package/dist/crypto.js

@@ -1,4 +1,4 @@
-// Loading the real NMTS crypto engine in Node.
+// The frozen tables of NCF-3, and the one door to the engine that reads them.
 //
 // ⛔ NOTHING IS RE-IMPLEMENTED HERE. The bytes that derive an account's keys are the same
 //    WebAssembly the browser runs, built from the same Rust crate. Two harnesses in this repo
@@ -7,24 +7,12 @@
 //    be a second implementation that can drift from the first, silently and in the direction that
 //    loses files.
 //
-// ⛔ NO TYPE ASSERTION. A dynamically imported module is `unknown` and staying honest about that
-//    matters here more than anywhere: if a rebuild renamed an export, an `as` would turn that into
-//    "undefined is not a function" deep inside a derivation. The guard below checks each function
-//    exists before anything is derived, so a missing export is named at load time.
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-import { readFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { NmtsError } from "./errors.js";
-import { isCryptoGlue, missingExports } from "./crypto-surface.js";
+// ⛔ WHERE THE ENGINE COMES FROM IS THE HOST'S BUSINESS, not this file's. Node finds it on disk
+//    and a browser fetches it, and both answers land in `host().engine` — so the tables below, and
+//    every module that derives anything from them, are the same code in both. The shape check
+//    stays on the host's side of the door for the same reason: `crypto-surface.ts` is one gate
+//    that both loads pass, rather than two guards that can come to disagree.
+import { host } from "./host.js";
 /**
  * The associated-data strings of NCF-3, for the envelopes this tool opens.
  *
@@ -104,47 +92,13 @@ export const DERIVED = {
      */
     aiAccountRoot: [256, 288],
 };
-export function engineDir() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const candidates = [
-        join(here, "..", "vendor", "nmts-crypto"),
-        join(here, "..", "..", "vendor", "nmts-crypto"),
-        join(here, "..", "..", "web", "vendor", "nmts-crypto"),
-    ];
-    for (const dir of candidates) {
-        if (existsSync(join(dir, "nmts_crypto_wasm_bg.wasm")))
-            return dir;
-    }
-    throw new NmtsError("The NMTS crypto engine is missing from this installation.", {
-        exitCode: 1,
-        nextStep: "Reinstall the package. Nothing can be encrypted or decrypted without it.",
-    });
-}
-let cached = null;
-/** Load the engine once per process. */
+/**
+ * The engine, loaded once by whichever host this program registered.
+ *
+ * Every derivation in the package goes through this one call, so a program that has not registered
+ * a host is told so here rather than somewhere deeper, where the message would be about a missing
+ * function instead of a missing entry point.
+ */
 export async function loadCrypto() {
-    if (cached !== null)
-        return cached;
-    const dir = engineDir();
-    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(join(dir, "nmts_crypto_wasm.js")).href));
-    if (typeof module !== "object" || module === null || !("default" in module)) {
-        throw new NmtsError("The NMTS crypto engine did not load (no initialiser).", { exitCode: 1 });
-    }
-    const init = Reflect.get(module, "default");
-    if (typeof init !== "function") {
-        throw new NmtsError("The NMTS crypto engine did not load (initialiser is not callable).", {
-            exitCode: 1,
-        });
-    }
-    await init({ module_or_path: await readFile(join(dir, "nmts_crypto_wasm_bg.wasm")) });
-    if (!isCryptoGlue(module)) {
-        const missing = missingExports(module);
-        throw new NmtsError(`The NMTS crypto engine is missing: ${missing.join(", ")}. This build does not match this tool.`, { exitCode: 1, nextStep: "Reinstall the package." });
-    }
-    cached = module;
-    return module;
-}
-/** For tests that need a fresh load. */
-export function forgetCrypto() {
-    cached = null;
+    return host().engine.load();
 }

package/dist/download-sink-node.d.ts

@@ -0,0 +1,49 @@
+import type { PlaintextSink } from "./download-sink.ts";
+import { type ByteDestination } from "./stdout.ts";
+/**
+ * Write to a file, through a temporary name beside it, renamed into place only when the whole
+ * file has been proved.
+ *
+ * ⛔ THE TEMPORARY FILE IS IN THE SAME DIRECTORY AS THE DESTINATION, not in a system temporary
+ *    directory, and that is the whole mechanism: `rename` is atomic only within one filesystem,
+ *    and only an atomic rename guarantees that a reader either sees nothing under the real name or
+ *    sees the finished file. A temporary directory can be — and on the machines this runs on
+ *    usually is — a different filesystem, where the same call becomes copy-then-delete and a
+ *    reader can catch the copy half done.
+ *
+ * ⛔ IT IS CREATED 0600 AND THE RENAME KEEPS THAT. The file is somebody's plaintext; it must not
+ *    be readable by other accounts on the machine for the seconds it takes to download, any more
+ *    than it may be afterwards.
+ */
+export declare function fileSink(destination: string, options: {
+    force: boolean;
+}): PlaintextSink;
+/**
+ * How much plaintext `--out -` will hold before it hands anything over. One part's worth.
+ *
+ * ⛔ NOT AN ARBITRARY NUMBER: it is the upload path's default part size, which is the most memory
+ *    this tool has ever asked for. Keeping the stdout ceiling there means the whole tool's bound
+ *    is one part plus one chunk whichever direction the bytes are going.
+ */
+export declare const STDOUT_HOLD_LIMIT: number;
+/**
+ * Hand the whole file to whatever is reading stdout — after it has been proved, not during.
+ *
+ * ⛔ THERE IS NO RENAME ON A PIPE, so the trick the file path uses is not available: a byte handed
+ *    to a reader cannot be taken back, and a reader that has already consumed half a file cannot
+ *    be told afterwards that the half was wrong. An exit code does not fix that — `nmts get x
+ *    --out - > y` leaves the truncated bytes in `y` whatever the exit code says, and an agent
+ *    reading a pipe usually acts on what it read. So this branch keeps the ORIGINAL guarantee
+ *    rather than the original size: the file is held, checked, and only then handed over, exactly
+ *    as before streaming existed.
+ *
+ * ⛔ WHICH MEANS IT HAS TO REFUSE SOMEWHERE, AND IT REFUSES OUT LOUD AND EARLY. Above the ceiling
+ *    the answer is a refusal naming `--out <name>`, which streams and is checked before the file
+ *    appears — not a silent trade of the guarantee for the size, and not the out-of-memory crash
+ *    that this used to be. `put` already refuses this way rather than discovering a limit halfway.
+ *
+ * ⚠ Every protection this branch already had is still here and still applies to the whole file:
+ *   bytes a terminal would act on are refused (`readableOnATerminal`), a reader that closed the
+ *   pipe first is an ordinary end and not a failure, and any other write failure throws.
+ */
+export declare function stdoutSink(to: ByteDestination, limit?: number): PlaintextSink;