@needmoretruth/nmts-cli 0.34.3 → 0.35.0

package/dist/commands/put-payer.js

@@ -0,0 +1,41 @@
+// WHO PAYS FOR AN UPLOAD, and which options mean anything once that is answered.
+//
+// ⛔ THE OPTIONS ARE REFUSED, NOT IGNORED. `--epochs 12 --pay credits` is somebody asking for a
+//    term credits do not sell; accepting it silently would upload for a different length than the
+//    person typed and charge them for it. Every refusal here happens before a file is measured.
+//
+// ⚠ They moved out of `put.ts` on 2026-09-16 (`--wallet` joined them and that file has a ceiling).
+//   `put.ts` re-exports them, so `push.ts` and the tests spell the same path they always did.
+import { NmtsError } from "../errors.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.wallet !== undefined) {
+        throw new NmtsError("--wallet only applies with --pay wallet: credits are not held in a wallet.", {
+            exitCode: 2,
+            nextStep: `Nothing was sent. Add --pay wallet to pay from one of this key's wallets.`,
+        });
+    }
+    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.`,
+        });
+    }
+}

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>;