@needmoretruth/nmts-cli 0.34.4 → 0.35.0

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

@@ -15,6 +15,8 @@ export interface WalletPayOptions {
     epochs?: string | number | undefined;
     /** `fit`, `whole`, or a held resource's object id. Absent = buy new storage. */
     storage?: string | undefined;
+    /** `--wallet N`: which wallet pays, this run only. Absent = the account's own number. */
+    wallet?: string | undefined;
     /** The instant the wallet agreement is measured against. */
     now?: number;
     /** ⚠ A SEAM, NOT AN OPTION — no flag reaches it. */
@@ -54,16 +56,20 @@ export interface WalletUploadContext {
     onCollision?: OnCollision | undefined;
     /** The sealed list's account settings, as read for this run — the standing tip lives in them. */
     settings?: AccountSettings | undefined;
+    /** Which of this key's wallets pays (`wallet-pay-index.ts`). Read from the same list as above. */
+    wallet: number;
     progress: Progress;
     say: (line: string) => void;
     json: boolean;
 }
 export declare function putWithWallet(target: string | undefined, options: PutWalletOptions): Promise<number>;
 /**
- * Review, agree, upload and record ONE file. Null when `--dry-run` stopped at the review.
+ * Review, agree, upload and record ONE file for a person who is watching. Null when `--dry-run`
+ * stopped at the review.
  *
- * ⛔ THE SIGNING MODULE IS LOADED AFTER THE AGREEMENT, and only then — a dry run and a refusal
- *    never bring the code that can spend into memory.
+ * ⛔ THE AGREEMENT HANDED IN BELOW IS THIS MACHINE'S GRANT, held against the total the review
+ *    names. It is the one gate between a program and somebody's wallet, and the reason it is
+ *    handed to the library rather than living inside it: a library call has nobody to ask.
  */
 export declare function uploadOneWithWallet(ctx: WalletUploadContext, file: WalletUploadFile, options: WalletPayOptions & {
     dryRun?: boolean | undefined;

package/dist/commands/put-wallet.js

@@ -1,16 +1,14 @@
 // `nmts put <file> --pay wallet` — one file in, sealed on this machine, its storage bought by the
 // PERSON'S OWN WALLET on the storage network instead of by credits.
 //
-// ⛔ IT PRICES BEFORE IT SIGNS, ALWAYS, in the order `extend` set: the parts are planned, the chain
-//    quotes each part in WAL and the relay's tip in SUI, the register transaction is dry-run for
-//    its fee, both balances are read — and only then is the review printed, a known shortfall
-//    refused, and the `wallet` agreement (scope `storage`) held against the total. `--dry-run`
-//    stops at the review and never loads the signing module.
+// ⛔ THE UPLOAD ITSELF IS NOT HERE. `upload-wallet-put.ts` prices, refuses, signs, pushes and
+//    records; this file is the terminal around it — the arguments, the printed review, the wallet
+//    agreement this machine holds, the spending ledger and the standing gift. The split is what
+//    lets the SDK pay from a wallet without a second copy of the order that keeps money safe.
 //
-// ⛔ THE SERVER IS TOLD THE STORAGE IS THE PERSON'S BY SAYING NOTHING ELSE. `POST /v1/items` forces
-//    treasury ownership only on a part that names a certified reservation; a wallet-paid part names
-//    none and carries the blob object and the end epoch instead, exactly as the browser's own
-//    wallet-paid commit does (`upload-steps.ts`).
+// ⛔ THE REVIEW IS PRINTED BEFORE ANY REFUSAL, and the agreement is asked for only after a known
+//    shortfall has already stopped the run — so a person who cannot afford it reads the numbers
+//    instead of a question. `--dry-run` stops at the review and never loads the signing module.
 //
 // ⛔ A HELD RESOURCE IS OFFERED, NEVER CHOSEN FOR THE PERSON — the owner's rule for storage
 //    resources: the leftover is shown in bytes and the person decides. The review names how many
@@ -20,27 +18,22 @@ import { basename, resolve } from "node:path";
 import { identityOf } from "../account.js";
 import { requireAccountCode } from "../code-access.js";
 import { parseAsked } from "../collision.js";
-import { DERIVED, loadCrypto } from "../crypto.js";
+import { loadCrypto } from "../crypto.js";
 import { API_KEY_ENV_VAR, readCredentialsFile, resolveApiKey } from "../credentials.js";
 import { NmtsError } from "../errors.js";
-import { setTrashed } from "../item-trash.js";
-import { addEntry } from "../manifest-write.js";
+import { payingWalletIndex } from "../wallet-pay-index.js";
+import { activeWalletOf } from "../shared/lib/drive/manifest-settings.js";
 import { paddingRuleOf, readFileList } from "../manifest.js";
 import { resolveNetwork } from "../network.js";
 import { BINARY_NAME } from "../product.js";
 import { Progress, silentSink, stderrSink } from "../progress.js";
-import { sealedLenFor } from "../seal.js";
 import { resolveServer } from "../server.js";
-import { statusOf } from "../shared/lib/storage-control/plan.js";
-import { createUploadApi } from "../upload-api.js";
-import { fileSource, partKeysOf, uploadFile } from "../upload-file.js";
-import { CREDIT_BYTES, measureLocal, partSizeFor, planAndPrice } from "../upload-price.js";
-import { clearItemRecord, clearReservation } from "../upload-store.js";
-import { walletRail } from "../upload-wallet.js";
-import { chooseUploadEpochs, daysOf, describeUploadReview, parseStorageAsk, pickResource, uploadBudget, uploadShortfallNextStep, walPrice, } from "../upload-wallet-plan.js";
-import { coinAmount, walletAddress } from "../wallet.js";
+import { fileSource } from "../upload-file.js";
+import { measureLocal, partSizeFor } from "../upload-price.js";
+import { describeUploadReview } from "../upload-wallet-plan.js";
+import { walletPut } from "../upload-wallet-put.js";
+import { coinAmount } from "../wallet.js";
 import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
-import { createBlobProtocol } from "../walrus-write.js";
 import { folderIdFor } from "./put.js";
 export async function putWithWallet(target, options) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
@@ -65,6 +58,12 @@ export async function putWithWallet(target, options) {
     const asked = parseAsked(options.onCollision);
     const list = await readFileList(server, key.key, resolved.code, identity.accountId);
     const rule = paddingRuleOf(list.manifest?.settings);
+    // ⛔ WHICH WALLET PAYS, BEFORE ANYTHING IS PRICED — out of the list that was just read, so this
+    //    costs no second request and the address in the review is the address that signs.
+    const wallet = await payingWalletIndex({
+        ...options,
+        readActiveWallet: async () => activeWalletOf(list.manifest?.settings),
+    });
     const name = options.name ?? basename(localPath);
     const destination = (options.to ?? "").replace(/^\.?\//, "").replace(/\/$/, "");
     const parentId = folderIdFor(options.to, list.manifest?.entries ?? []);
@@ -79,6 +78,7 @@ export async function putWithWallet(target, options) {
         rule,
         onCollision: asked,
         settings: list.manifest?.settings,
+        wallet,
         progress: new Progress(options.json === true ? silentSink() : stderrSink(), "uploading"),
         say,
         json: options.json === true,
@@ -100,174 +100,75 @@ export async function putWithWallet(target, options) {
     return 0;
 }
 /**
- * Review, agree, upload and record ONE file. Null when `--dry-run` stopped at the review.
+ * Review, agree, upload and record ONE file for a person who is watching. Null when `--dry-run`
+ * stopped at the review.
  *
- * ⛔ THE SIGNING MODULE IS LOADED AFTER THE AGREEMENT, and only then — a dry run and a refusal
- *    never bring the code that can spend into memory.
+ * ⛔ THE AGREEMENT HANDED IN BELOW IS THIS MACHINE'S GRANT, held against the total the review
+ *    names. It is the one gate between a program and somebody's wallet, and the reason it is
+ *    handed to the library rather than living inside it: a library call has nobody to ask.
  */
 export async function uploadOneWithWallet(ctx, file, options) {
     const { say } = ctx;
-    const { plan, sealedBytes, sealFor } = planAndPrice(file.size, ctx.partSize, ctx.rule);
-    const sealedLens = plan.map((range) => sealedLenFor(sealFor(range)));
-    const storageAsk = parseStorageAsk(options.storage);
-    if (storageAsk !== null && plan.length > 1) {
-        throw new NmtsError(`A held storage resource holds one blob, and this file is ${plan.length} parts.`, {
-            exitCode: 4,
-            nextStep: `Nothing was signed. Leave --storage off, or raise --part-size so the file is one part.`,
-        });
-    }
-    const protocol = (options.protocol ?? createBlobProtocol)(ctx.network, sealedBytes, (sent, total) => ctx.progress.update(sent, total));
-    const reads = await (options.readChain ?? defaultReads)(ctx.network, protocol.relayUrl);
-    const window = await reads.readWindow();
-    if (window === null) {
-        throw new NmtsError(`The ${ctx.network} storage network could not be read.`, {
-            exitCode: 1,
-            nextStep: `Nothing was signed and nothing was sent. Which epoch the network is in, and how far ahead it will sell, are facts only the chain has — this tool will not spend against a guess.`,
+    let outcome;
+    try {
+        outcome = await walletPut({
+            code: ctx.code,
+            apiKey: ctx.apiKey,
+            server: ctx.server,
+            network: ctx.network,
+            accountId: ctx.accountId,
+            crypt: ctx.crypt,
+            wallet: ctx.wallet,
+            partSize: ctx.partSize,
+            rule: ctx.rule,
+            onCollision: ctx.onCollision,
+        }, { source: fileSource(file.localPath, file.size), name: file.name, parentId: file.parentId, destination: file.destination }, {
+            epochs: options.epochs,
+            storage: options.storage,
+            dryRun: options.dryRun,
+            readChain: options.readChain,
+            sign: options.sign,
+            protocol: options.protocol,
+            api: options.api,
+            onProgress: (sent, total) => ctx.progress.update(sent, total),
+            onStep: (step) => tell(ctx, file.size, step),
+            onReview: (review) => {
+                if (ctx.json)
+                    return;
+                describeUploadReview(say, {
+                    name: review.name,
+                    bytes: review.bytes,
+                    parts: review.parts,
+                    epochs: review.epochs,
+                    days: review.days,
+                    endEpoch: review.endEpoch,
+                    walNeeded: review.budget.walNeededFrost,
+                    tipMist: review.tipMist,
+                    storage: review.storage,
+                    heldResources: review.heldResources,
+                }, review.budget);
+            },
+            agree: (review) => {
+                requireWalletGrant("seal", { walFrost: review.budget.walNeededFrost, suiMist: review.budget.suiNeededMist }, new Date(options.now ?? Date.now()));
+            },
+            onSpend: recordWalletSpend,
         });
     }
-    const epochs = chooseUploadEpochs(options.epochs, window);
-    const endEpoch = window.clock.current + epochs;
-    const quotes = await reads.quoteParts(sealedLens, epochs);
-    const address = await walletAddress(ctx.code);
-    let storage = { kind: "buy" };
-    let heldResources = null;
-    if (storageAsk !== null) {
-        const firstQuote = quotes[0];
-        const firstLen = sealedLens[0];
-        if (firstQuote === undefined || firstLen === undefined)
-            throw new NmtsError("unreachable: a plan with no part");
-        let resources;
-        try {
-            resources = await reads.readStorage(address);
-        }
-        catch (error) {
-            throw new NmtsError("The storage resources this wallet holds could not be read.", {
-                exitCode: 1,
-                nextStep: `Nothing was signed. That is not the same as holding none. Cause: ${error instanceof Error ? error.message : String(error)}`,
-            });
-        }
-        const encoded = await reads.encodedLength(address, firstLen);
-        storage = pickResource(storageAsk, resources, encoded, window.clock.current, endEpoch, firstQuote.writeFrost);
-    }
-    else {
-        heldResources = await reads.readStorage(address).then((rows) => rows.filter((r) => statusOf(r, window.clock.current) === "usable").length, () => null);
-    }
-    const [purse, feeMist] = await Promise.all([
-        reads.readWallet(address),
-        reads.estimateRegisterGas({
-            sender: address,
-            sealedLen: Math.max(...sealedLens),
-            epochs,
-            storage: storage.kind === "buy" ? storage : { kind: "reuse", objectId: storage.objectId, cutToBytes: storage.cutToBytes, writeFrost: storage.writeFrost },
-        }),
-    ]);
-    const budget = uploadBudget({ address, purse, feeMist, quotes, storage });
-    const tipMist = quotes.reduce((sum, q) => sum + q.tipMist, 0n);
-    const facts = {
-        bytes: file.size,
-        sealedBytes,
-        parts: plan.length,
-        epochs,
-        days: daysOf(window, epochs),
-        endEpoch,
-        paidFrom: "wallet",
-        priceFrost: budget.walNeededFrost.toString(),
-        priceWal: coinAmount(budget.walNeededFrost),
-        tipMist: tipMist.toString(),
-        tipSui: coinAmount(tipMist),
-        feeMist: feeMist === null ? null : feeMist.toString(),
-        feeSui: feeMist === null ? null : coinAmount(feeMist),
-        wallet: address,
-        walletWal: budget.walFrost === null ? null : coinAmount(budget.walFrost),
-        walletSui: budget.suiMist === null ? null : coinAmount(budget.suiMist),
-        storage: storage.kind === "buy"
-            ? { kind: "buy" }
-            : { kind: "reuse", objectId: storage.objectId, cutToBytes: storage.cutToBytes, leftoverBytes: storage.leftoverBytes },
-    };
-    if (!ctx.json) {
-        describeUploadReview(say, { name: file.name, bytes: file.size, parts: plan.length, epochs, days: daysOf(window, epochs), endEpoch, walNeeded: walPrice(quotes, storage), tipMist, storage, heldResources }, budget);
+    finally {
+        ctx.progress.done();
     }
-    if (options.dryRun === true) {
+    const facts = factsOf(outcome.review);
+    if (outcome.kind === "review") {
         if (ctx.json)
-            say(JSON.stringify({ dryRun: true, name: file.name, ...facts, signed: false }));
+            say(JSON.stringify({ dryRun: true, name: outcome.review.name, ...facts, signed: false }));
         else {
             say(``);
-            if (budget.shortfall !== null)
-                say(`  ⚠ ${budget.shortfall} As it stands, it would be refused.`);
+            if (outcome.review.budget.shortfall !== null)
+                say(`  ⚠ ${outcome.review.budget.shortfall} As it stands, it would be refused.`);
             say(`  Nothing was signed and nothing was sent. Run the same command without --dry-run to upload it.`);
         }
         return null;
     }
-    // ⛔ A WALLET KNOWN TO BE SHORT IS REFUSED BEFORE THE AGREEMENT IS ASKED FOR (`extend-budget.ts`).
-    if (budget.shortfall !== null) {
-        throw new NmtsError(budget.shortfall, { exitCode: 4, nextStep: uploadShortfallNextStep(budget) });
-    }
-    // ⛔ THE ONE GATE BETWEEN A PROGRAM AND SOMEBODY'S WALLET. Everything above is a read.
-    requireWalletGrant("seal", { walFrost: budget.walNeededFrost, suiMist: budget.suiNeededMist }, new Date(options.now ?? Date.now()));
-    const sign = options.sign ?? (await signers());
-    const derived = ctx.crypt.kdf_derive(ctx.crypt.account_code_parse(ctx.code));
-    const dataKey = derived.slice(DERIVED.dataKey[0], DERIVED.dataKey[1]);
-    derived.fill(0);
-    let result;
-    try {
-        result = await uploadFile({
-            api: options.api ?? createUploadApi(ctx.server, ctx.apiKey),
-            protocol,
-            crypt: ctx.crypt,
-            dataKey,
-            source: fileSource(file.localPath, file.size),
-            name: file.name,
-            parentId: file.parentId,
-            destination: file.destination,
-            relayUrl: protocol.relayUrl,
-            epochs,
-            currentEpoch: window.clock.current,
-            partSize: ctx.partSize,
-            padding: { rule: ctx.rule, unitBytes: CREDIT_BYTES },
-            onStep: (step) => tell(ctx, file.size, step),
-            buy: walletRail({
-                network: ctx.network,
-                code: ctx.code,
-                relayUrl: protocol.relayUrl,
-                epochs,
-                storage,
-                quotes,
-                feeMist,
-                signRegister: sign.register,
-                signCertify: sign.certify,
-                onSpend: recordWalletSpend,
-            }),
-        });
-    }
-    finally {
-        ctx.progress.done();
-        dataKey.fill(0);
-    }
-    const now = Date.now();
-    const added = await addEntry({
-        server: ctx.server,
-        apiKey: ctx.apiKey,
-        code: ctx.code,
-        accountId: ctx.accountId,
-        ...(ctx.onCollision !== undefined ? { onCollision: ctx.onCollision } : {}),
-        entry: {
-            id: result.itemId,
-            parentId: file.parentId,
-            kind: 1,
-            name: result.entry.name,
-            size: result.entry.plaintextLen,
-            createdAt: now,
-            updatedAt: now,
-            dekWrapped: result.entry.dekWrapped,
-            contentHashCt: result.entry.contentHashCt,
-        },
-    });
-    // ⛔ ONLY NOW, AND EVERY PART — the same order `put.ts` keeps and for the same reason.
-    clearItemRecord(result.fileKey);
-    for (const record of partKeysOf(result.fileKey, result.parts))
-        clearReservation(record);
-    if (added.replaced)
-        await setTrashed(ctx.server, ctx.apiKey, added.replaced.id, true);
     // ⛔ THE STANDING SHARE, AFTER THE PAYMENT AND NEVER INSIDE IT: a gift that fails must not fail
     //    the upload. A resumed run paid nothing now, so it owes nothing now. In --json the tip speaks
     //    on stderr — stdout carries the machine's one answer and nothing else.
@@ -276,11 +177,37 @@ export async function uploadOneWithWallet(ctx, file, options) {
         network: ctx.network,
         code: ctx.code,
         settings: ctx.settings,
-        paidWalFrost: result.resumed ? 0n : budget.walNeededFrost,
+        wallet: ctx.wallet,
+        paidWalFrost: outcome.resumed ? 0n : outcome.review.budget.walNeededFrost,
         say: ctx.json ? (line) => void process.stderr.write(`${line}\n`) : say,
         ...(options.tip ?? {}),
     });
-    return { itemId: result.itemId, savedAs: added.name, replaced: added.replaced?.id ?? null, seq: added.seq, resumed: result.resumed, facts };
+    return { itemId: outcome.itemId, savedAs: outcome.savedAs, replaced: outcome.replaced, seq: outcome.fileListVersion, resumed: outcome.resumed, facts };
+}
+/** The review as `--json` prints it: base units as strings, with the coin amounts beside them. */
+function factsOf(review) {
+    const { budget, storage } = review;
+    return {
+        bytes: review.bytes,
+        sealedBytes: review.sealedBytes,
+        parts: review.parts,
+        epochs: review.epochs,
+        days: review.days,
+        endEpoch: review.endEpoch,
+        paidFrom: "wallet",
+        priceFrost: budget.walNeededFrost.toString(),
+        priceWal: coinAmount(budget.walNeededFrost),
+        tipMist: review.tipMist.toString(),
+        tipSui: coinAmount(review.tipMist),
+        feeMist: budget.feeMist === null ? null : budget.feeMist.toString(),
+        feeSui: budget.feeMist === null ? null : coinAmount(budget.feeMist),
+        wallet: budget.address,
+        walletWal: budget.walFrost === null ? null : coinAmount(budget.walFrost),
+        walletSui: budget.suiMist === null ? null : coinAmount(budget.suiMist),
+        storage: storage.kind === "buy"
+            ? { kind: "buy" }
+            : { kind: "reuse", objectId: storage.objectId, cutToBytes: storage.cutToBytes, leftoverBytes: storage.leftoverBytes },
+    };
 }
 /** Each step, for a person watching. The signatures are named as what they are. */
 function tell(ctx, size, step) {
@@ -307,10 +234,3 @@ function tell(ctx, size, step) {
     if (step.step === "committing")
         say(`  saving to the drive`);
 }
-async function defaultReads(network, relayUrl) {
-    return (await import("../upload-wallet-chain.js")).walletUploadReads(network, relayUrl);
-}
-async function signers() {
-    const signing = await import("../wallet-sign.js");
-    return { register: signing.signBlobRegister, certify: signing.signBlobCertify };
-}

package/dist/commands/put.d.ts

@@ -35,16 +35,14 @@ export interface PutOptions {
     epochs?: string | number | undefined;
     /** `--pay wallet`: a held storage resource to use — `fit`, `whole`, or its object id. */
     storage?: string | undefined;
+    /** `--pay wallet`: which of this key's wallets pays, this run only. Absent = the account's own. */
+    wallet?: string | undefined;
     json?: boolean;
     write?: (line: string) => void;
 }
-/** Who pays, or a refusal for a payer this tool does not know. */
-export declare function payerOf(pay: string | undefined): "credits" | "wallet";
-/** The two options that only mean something when the wallet pays, refused when it does not. */
-export declare function refuseWalletOnlyOptions(options: {
-    epochs?: string | number | undefined;
-    storage?: string | undefined;
-}): void;
+/** Who pays, and the options that lose their meaning under that answer — the rule is in `put-payer.ts`; this is its one road. */
+import { payerOf, refuseWalletOnlyOptions } from "./put-payer.ts";
+export { payerOf, refuseWalletOnlyOptions };
 /**
  * The folder id `--to` names, or null for the root. Refuses rather than guessing.
  *

package/dist/commands/put.js

@@ -31,32 +31,9 @@ import { createUploadApi } from "../upload-api.js";
 import { fileSource, partKeysOf, uploadFile } from "../upload-file.js";
 import { CREDIT_BYTES, creditsFor, measureLocal, partSizeFor, planAndPrice, UPLOAD_EPOCHS, } from "../upload-price.js";
 import { createBlobProtocol, readCurrentEpoch } from "../walrus-write.js";
-/** Who pays, or a refusal for a payer this tool does not know. */
-export function payerOf(pay) {
-    if (pay === undefined || pay === "credits")
-        return "credits";
-    if (pay === "wallet")
-        return "wallet";
-    throw new NmtsError(`--pay takes credits or wallet, not "${pay}".`, {
-        exitCode: 2,
-        nextStep: `Nothing was sent. --pay wallet buys the storage from the wallet this NMTS key derives; without it credits pay.`,
-    });
-}
-/** The two options that only mean something when the wallet pays, refused when it does not. */
-export function refuseWalletOnlyOptions(options) {
-    if (options.epochs !== undefined) {
-        throw new NmtsError("--epochs only applies with --pay wallet: one credit buys a fixed term.", {
-            exitCode: 2,
-            nextStep: `Nothing was sent. Add --pay wallet to choose the term, or leave --epochs off to pay with credits.`,
-        });
-    }
-    if (options.storage !== undefined) {
-        throw new NmtsError("--storage only applies with --pay wallet: credits buy storage from the treasury.", {
-            exitCode: 2,
-            nextStep: `Nothing was sent. Add --pay wallet to use a storage resource this wallet holds.`,
-        });
-    }
-}
+/** Who pays, and the options that lose their meaning under that answer — the rule is in `put-payer.ts`; this is its one road. */
+import { payerOf, refuseWalletOnlyOptions } from "./put-payer.js";
+export { payerOf, refuseWalletOnlyOptions };
 /**
  * The folder id `--to` names, or null for the root. Refuses rather than guessing.
  *

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

@@ -15,7 +15,10 @@ export interface WalletDonateOptions {
     yes?: boolean;
     dryRun?: boolean;
     feeCap?: string | undefined;
+    /** `--wallet N`: which wallet the gift comes from, this run only. Absent = the account's number. */
+    wallet?: string | undefined;
     /** ⚠ SEAMS, NOT OPTIONS — no flag reaches them. */
+    readActiveWallet?: () => Promise<number>;
     readDonation?: (server: string) => Promise<DonationConfig>;
     readChain?: (network: Network) => SendReads | Promise<SendReads>;
     sign?: SignTransfer;

package/dist/commands/wallet-donate.js

@@ -25,6 +25,7 @@ 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";
+import { payingWalletIndex } from "../wallet-pay-index.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.",
@@ -57,7 +58,10 @@ export async function walletDonate(operands, options = {}) {
         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);
+    // ⛔ A gift leaves the same wallet storage is paid from, and it is resolved before the review is
+    //    priced — so the address a person reads is the address the coins leave.
+    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);
@@ -143,7 +147,7 @@ export async function walletDonate(operands, options = {}) {
         });
     }
     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 });
     if (options.json) {
         say(JSON.stringify({ ...facts, signed: true, digest, explorerUrl: explorerTxUrl(digest, network) }));
         return 0;

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. */