@needmoretruth/nmts-cli 0.34.4 → 0.36.1

package/dist/upload-wallet-put.js

@@ -0,0 +1,221 @@
+// A WALLET-PAID upload with no terminal in it: one file sealed here, its storage bought by the
+// wallet the NMTS key derives instead of by credits, the sealed bytes pushed, the file named in
+// the account's sealed list.
+//
+// ⛔ WHY THIS IS NOT IN `commands/`. Paying for storage from somebody's own coins existed only as
+//    `nmts put --pay wallet`, and a command cannot be called from a library: it parses arguments,
+//    prints, asks a person and exits. Everything below takes its inputs as values and reports
+//    through a return value and thrown `NmtsError`s, which is what lets the SDK — and somebody's
+//    own server — pay for an upload from their own coins without inheriting a terminal.
+//
+// ⛔ 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 `onReview` told the numbers, a known
+//    shortfall refused, and `agree` given its say. A dry run stops at the review and never loads
+//    the signing module.
+//
+// ⛔ `agree` IS THE ONE GATE BETWEEN A PROGRAM AND SOMEBODY'S WALLET, and it is a parameter
+//    because who may say yes differs: the command holds the review against this machine's wallet
+//    agreement, and a library call IS the agreement, made by the caller who wrote the call.
+//    Everything before it is a read.
+//
+// ⛔ 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`).
+//
+// ⛔ A HELD RESOURCE IS OFFERED, NEVER CHOSEN FOR THE CALLER — the owner's rule for storage
+//    resources. Without `storage` this buys new storage and the review counts the free resources
+//    the wallet holds; with it the review says in bytes what is cut free or bound with the file.
+//
+// ⚠ NO SPENDING LEDGER AND NO GIFT LIVE HERE. Both are the command's: the ledger counts what one
+//   machine signed under one agreement, and a standing gift is a choice a person made in their own
+//   account. A library that kept either would be deciding for a caller who never asked it to.
+import { DERIVED } from "./crypto.js";
+import { NmtsError } from "./errors.js";
+import { setTrashed } from "./item-trash.js";
+import { addEntry } from "./manifest-write.js";
+import { sealedLenFor } from "./seal.js";
+import { statusOf } from "./shared/lib/storage-control/plan.js";
+import { createUploadApi } from "./upload-api.js";
+import { partKeysOf, uploadFile } from "./upload-file.js";
+import { CREDIT_BYTES, planAndPrice } from "./upload-price.js";
+import { clearItemRecord, clearReservation } from "./upload-store.js";
+import { walletRail } from "./upload-wallet.js";
+import { chooseUploadEpochs, daysOf, parseStorageAsk, pickResource, uploadBudget, uploadShortfallNextStep, } from "./upload-wallet-plan.js";
+import { walletAddress } from "./wallet.js";
+import { createBlobProtocol } from "./walrus-write.js";
+/**
+ * Price, agree, sign, upload and record ONE file, paid from the wallet the NMTS key derives.
+ *
+ * ⛔ THE SIGNING MODULE IS LOADED ONLY AFTER `agree` HAS RETURNED. A dry run and a refusal never
+ *    bring the code that can spend into memory.
+ */
+export async function walletPut(ctx, file, seams = {}) {
+    const { plan, sealedBytes, sealFor } = planAndPrice(file.source.size, ctx.partSize, ctx.rule);
+    const sealedLens = plan.map((range) => sealedLenFor(sealFor(range)));
+    const storageAsk = parseStorageAsk(seams.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 the storage resource off, or raise the part size so the file is one part.`,
+        });
+    }
+    const protocol = (seams.protocol ?? createBlobProtocol)(ctx.network, sealedBytes, (sent, total) => seams.onProgress?.(sent, total));
+    const reads = await (seams.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 will not spend against a guess.`,
+        });
+    }
+    const epochs = chooseUploadEpochs(seams.epochs, window);
+    const endEpoch = window.clock.current + epochs;
+    const quotes = await reads.quoteParts(sealedLens, epochs);
+    // ⛔ THE ADDRESS THAT IS PRICED IS THE ADDRESS THAT SIGNS — the same number the rail carries.
+    const address = await walletAddress(ctx.code, ctx.wallet);
+    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 {
+        // ⚠ A read that fails is null, not zero: this number only offers a choice, and losing it must
+        //   not lose the upload.
+        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 review = {
+        name: file.name,
+        bytes: file.source.size,
+        sealedBytes,
+        parts: plan.length,
+        epochs,
+        days: daysOf(window, epochs),
+        endEpoch,
+        tipMist: quotes.reduce((sum, q) => sum + q.tipMist, 0n),
+        storage,
+        heldResources,
+        budget,
+    };
+    seams.onReview?.(review);
+    if (seams.dryRun === true)
+        return { kind: "review", review };
+    // ⛔ 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) });
+    }
+    seams.agree?.(review);
+    const sign = seams.sign ?? (await signers());
+    const onSpend = seams.onSpend ?? (() => undefined);
+    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: seams.api ?? createUploadApi(ctx.server, ctx.apiKey),
+            protocol,
+            crypt: ctx.crypt,
+            dataKey,
+            source: file.source,
+            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 },
+            ...(seams.onStep === undefined ? {} : { onStep: seams.onStep }),
+            buy: walletRail({
+                network: ctx.network,
+                code: ctx.code,
+                wallet: ctx.wallet,
+                relayUrl: protocol.relayUrl,
+                epochs,
+                storage,
+                quotes,
+                feeMist,
+                signRegister: sign.register,
+                signCertify: sign.certify,
+                onSpend,
+            }),
+        });
+    }
+    finally {
+        dataKey.fill(0);
+    }
+    const now = Date.now();
+    // ⛔ FROM `result.entry`, NOT FROM THIS CALL. The key that opens the stored bytes is the key they
+    //    were sealed with, which on a resume belongs to the call that sealed them.
+    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 the credit rail keeps and for the same reason: a
+    //    paid-for file the list does not name is invisible, and the records are what let a second
+    //    call finish the job without signing again.
+    await clearItemRecord(result.fileKey);
+    for (const record of partKeysOf(result.fileKey, result.parts))
+        await clearReservation(record);
+    if (added.replaced)
+        await setTrashed(ctx.server, ctx.apiKey, added.replaced.id, true);
+    return {
+        kind: "uploaded",
+        review,
+        itemId: result.itemId,
+        savedAs: added.name,
+        replaced: added.replaced?.id ?? null,
+        fileListVersion: added.seq,
+        resumed: result.resumed,
+    };
+}
+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/upload-wallet.d.ts

@@ -7,6 +7,9 @@ export interface WalletRailContext {
     network: Network;
     /** ⛔ The NMTS key. Held for the signatures and never written anywhere. */
     code: string;
+    /** Which of this key's wallets pays — the account's own number, resolved before anything was
+     *  priced (`wallet-pay-index.ts`), so the address in the review is the address that signs. */
+    wallet: number;
     relayUrl: string;
     epochs: number;
     /** Where the storage comes from. A held resource serves one blob, so it applies to a one-part file. */

package/dist/upload-wallet.js

@@ -18,6 +18,7 @@
 // ⛔ THE SIGNATURES ARE A SEAM. `wallet-sign.ts` is loaded by the command, after the agreement,
 //    and handed in; the tests hand in recorders and prove that `--dry-run` and a shortfall never
 //    reach them.
+import { fromBase64Url, toBase64Url } from "./bytes.js";
 import { NmtsError } from "./errors.js";
 import { readReservationBytes, readReservationRecord, writeReservation } from "./upload-store.js";
 import { UploadError } from "./upload-wire.js";
@@ -30,14 +31,14 @@ export function walletRail(ctx) {
 }
 async function buyAndPushPartWithWallet(ctx, input) {
     const { protocol, key, sealed, onStep } = input;
-    const existing = readReservationRecord(key);
+    const existing = await readReservationRecord(key);
     if (existing !== null && existing.paidFrom !== "wallet") {
         throw new UploadError({
             phase: "reserve",
             message: "This upload was started with credits paying, and this run would pay from the wallet.",
             paid: existing.ledgerId !== undefined,
-            nextStep: "Run it again without --pay wallet to finish it, or move the records in the uploads " +
-                "directory aside to start over. Nothing was sent.",
+            nextStep: "Run it again without --pay wallet to finish it, or clear the unfinished upload records " +
+                "to start over. Nothing was sent.",
         });
     }
     if (existing !== null && (existing.partIndex !== input.part.index || existing.partTotal !== input.part.total)) {
@@ -46,8 +47,8 @@ async function buyAndPushPartWithWallet(ctx, input) {
             message: `This upload was started as part ${existing.partIndex + 1} of ${existing.partTotal} and this ` +
                 `run is treating it as part ${input.part.index + 1} of ${input.part.total}.`,
             paid: existing.registerTxDigest !== undefined,
-            nextStep: "Run it again with the part size the first attempt used, or move the records in the " +
-                "uploads directory aside to start over. Nothing was sent.",
+            nextStep: "Run it again with the part size the first attempt used, or clear the unfinished upload " +
+                "records to start over. Nothing was sent.",
         });
     }
     // ── already certified: nothing left to sign or send ──
@@ -58,9 +59,9 @@ async function buyAndPushPartWithWallet(ctx, input) {
     // ── registered by an earlier run: push and certify, sign nothing twice ──
     if (existing?.registerTxDigest !== undefined && existing.blobObjectId !== undefined) {
         onStep?.({ step: "resuming", ledgerId: 0, state: "registered" });
-        const certificate = await push(input, existing, existing.registerTxDigest, existing.blobObjectId, readReservationBytes(key));
+        const certificate = await push(input, existing, existing.registerTxDigest, existing.blobObjectId, await readReservationBytes(key));
         await certify(ctx, input, key, existing, certificate);
-        return paidPart(readReservationRecord(key) ?? existing, true);
+        return paidPart((await readReservationRecord(key)) ?? existing, true);
     }
     // ── fresh, or interrupted before the signature ──
     onStep?.({ step: "encoding", bytes: sealed.length });
@@ -68,7 +69,7 @@ async function buyAndPushPartWithWallet(ctx, input) {
     try {
         meta = await protocol.computeMetadata({
             bytes: sealed,
-            nonce: existing ? new Uint8Array(Buffer.from(existing.nonceB64, "base64url")) : undefined,
+            nonce: existing ? fromBase64Url(existing.nonceB64) : undefined,
         });
     }
     catch (error) {
@@ -83,8 +84,8 @@ async function buyAndPushPartWithWallet(ctx, input) {
         attempt: existing?.attempt ?? 0,
         paidFrom: "wallet",
         blobId: meta.blobId,
-        nonceB64: Buffer.from(meta.nonce).toString("base64url"),
-        rootHashB64: Buffer.from(meta.rootHash).toString("base64url"),
+        nonceB64: toBase64Url(meta.nonce),
+        rootHashB64: toBase64Url(meta.rootHash),
         relayUrl: input.relayUrl,
         epochs: input.epochs,
         sealedLen: sealed.length,
@@ -98,7 +99,7 @@ async function buyAndPushPartWithWallet(ctx, input) {
         parentId: input.entry.parentId,
     };
     // ⛔ BEFORE THE SIGNATURE. See the module header.
-    writeReservation(key, record, sealed);
+    await writeReservation(key, record, sealed);
     onStep?.({ step: "reserving" });
     const quote = ctx.quotes[input.part.index];
     if (quote === undefined)
@@ -108,6 +109,7 @@ async function buyAndPushPartWithWallet(ctx, input) {
         registered = await ctx.signRegister({
             network: ctx.network,
             code: ctx.code,
+            wallet: ctx.wallet,
             relayUrl: input.relayUrl,
             epochs: ctx.epochs,
             storage: ctx.storage.kind === "buy" ? { kind: "buy" } : ctx.storage,
@@ -132,14 +134,14 @@ async function buyAndPushPartWithWallet(ctx, input) {
     record.registerTxDigest = registered.digest;
     record.blobObjectId = registered.blobObjectId;
     record.endEpoch = registered.endEpoch;
-    writeReservation(key, record, sealed);
+    await writeReservation(key, record, sealed);
     ctx.onSpend({
         walFrost: quote.writeFrost + (ctx.storage.kind === "buy" ? quote.storageFrost : 0n),
         suiMist: quote.tipMist + (ctx.feeMist ?? 0n),
     });
     const certificate = await push(input, record, registered.digest, registered.blobObjectId, sealed);
     await certify(ctx, input, key, record, certificate);
-    return paidPart(readReservationRecord(key) ?? record, false);
+    return paidPart((await readReservationRecord(key)) ?? record, false);
 }
 /** The bytes to the relay named in the register transaction. The storage is already bought. */
 async function push(input, record, registerTxDigest, blobObjectId, sealed) {
@@ -148,7 +150,7 @@ async function push(input, record, registerTxDigest, blobObjectId, sealed) {
         return await input.protocol.uploadToRelay({
             blobId: record.blobId,
             bytes: sealed,
-            nonce: new Uint8Array(Buffer.from(record.nonceB64, "base64url")),
+            nonce: fromBase64Url(record.nonceB64),
             registerTxDigest,
             blobObjectId,
         });
@@ -173,6 +175,7 @@ async function certify(ctx, input, key, record, certificate) {
         digest = await ctx.signCertify({
             network: ctx.network,
             code: ctx.code,
+            wallet: ctx.wallet,
             relayUrl: record.relayUrl,
             blobId: record.blobId,
             blobObjectId: record.blobObjectId,
@@ -190,7 +193,7 @@ async function certify(ctx, input, key, record, certificate) {
                     "certifies again, which costs gas and nothing else.",
         });
     }
-    writeReservation(key, { ...record, certifyTxDigest: digest }, readReservationBytes(key));
+    await writeReservation(key, { ...record, certifyTxDigest: digest }, await readReservationBytes(key));
     // The certify fee is not measured beforehand, so the ledger is told about the tip and the
     // register fee only — the review said so.
 }

package/dist/upload.js

@@ -26,6 +26,7 @@
 // ⛔ EVERY SEAM IS INJECTED. The storage-network protocol and the api are interfaces, so the tests
 //    drive the real decisions — including every failure branch — without a network and without
 //    spending anything. The seams themselves are in `upload-wire.ts`.
+import { fromBase64Url, toBase64Url } from "./bytes.js";
 import { NmtsError } from "./errors.js";
 import { ServerError } from "./api.js";
 import { readReservationBytes, readReservationRecord, writeReservation, } from "./upload-store.js";
@@ -53,7 +54,7 @@ function why(error) {
  */
 export async function buyAndPushPart(input) {
     const { api, protocol, key, sealed, onStep } = input;
-    const existing = readReservationRecord(key);
+    const existing = await readReservationRecord(key);
     // ⛔ THE STORED PLACEMENT WINS THE ARGUMENT, AND A DISAGREEMENT STOPS THE RUN. The bytes on disk
     //    were sealed as part i of n and paid for as that; pushing them while this run believes the
     //    file splits some other way would file storage under the wrong position in the file. It
@@ -64,8 +65,8 @@ export async function buyAndPushPart(input) {
             phase: "reserve",
             message: "This upload was started with the wallet paying, and this run would pay with credits.",
             paid: existing.registerTxDigest !== undefined,
-            nextStep: "Run it again with --pay wallet to finish it, or move the records in the uploads directory " +
-                "aside to start over with credits. Nothing was sent.",
+            nextStep: "Run it again with --pay wallet to finish it, or clear the unfinished upload records to " +
+                "start over with credits. Nothing was sent.",
         });
     }
     if (existing !== null) {
@@ -76,8 +77,8 @@ export async function buyAndPushPart(input) {
                 message: `This upload was started as part ${record.partIndex + 1} of ${record.partTotal} and this ` +
                     `run is treating it as part ${input.part.index + 1} of ${input.part.total}.`,
                 paid: record.ledgerId !== undefined,
-                nextStep: "Run it again with the part size the first attempt used, or move the records in the " +
-                    "uploads directory aside to start over. Nothing was sent.",
+                nextStep: "Run it again with the part size the first attempt used, or clear the unfinished upload " +
+                    "records to start over. Nothing was sent.",
             });
         }
     }
@@ -111,7 +112,7 @@ export async function buyAndPushPart(input) {
             //    whatever state it is in — `failed` included. A cleared record means the next run
             //    rebuilds the same key, is handed the same dead row, and is told to start over into it.
             //    Forever. Counting up is what starting over actually means.
-            writeReservation(key, { ...stripReservation(record), attempt: record.attempt + 1 }, readReservationBytes(key));
+            await writeReservation(key, { ...stripReservation(record), attempt: record.attempt + 1 }, await readReservationBytes(key));
             throw new UploadError({
                 phase: "reserve",
                 message: `The credit reservation for this file ended as "${status.state}" and cannot be used.`,
@@ -131,12 +132,12 @@ export async function buyAndPushPart(input) {
         await pushPart(input, {
             ledgerId,
             blobId: record.blobId,
-            nonce: Buffer.from(record.nonceB64, "base64url"),
+            nonce: fromBase64Url(record.nonceB64),
             registerTxDigest: status.register_tx_digest,
             blobObjectId: status.blob_object_id,
             // ⛔ THE STORED BYTES AND THE STORED RELAY. Not the caller's — see the module header.
             //    Read here, and only here: a part that came back certified never needs them at all.
-            sealed: readReservationBytes(key),
+            sealed: await readReservationBytes(key),
             relayUrl: record.relayUrl,
         });
         return paidPart(record, ledgerId, true);
@@ -149,7 +150,7 @@ export async function buyAndPushPart(input) {
             bytes: sealed,
             // Re-feeding a stored nonce is what makes the retry reproduce the digest a paid tip was
             // computed for. A fresh random one would strand the reservation.
-            nonce: existing ? new Uint8Array(Buffer.from(existing.nonceB64, "base64url")) : undefined,
+            nonce: existing ? fromBase64Url(existing.nonceB64) : undefined,
         });
     }
     catch (error) {
@@ -160,14 +161,14 @@ export async function buyAndPushPart(input) {
             nextStep: "Nothing was sent and nothing was spent.",
         });
     }
-    const nonceB64 = Buffer.from(meta.nonce).toString("base64url");
+    const nonceB64 = toBase64Url(meta.nonce);
     const record = {
         // ⛔ The attempt number is CARRIED FORWARD, not reset. A record that survives a dead
         //    reservation is exactly the case that needs a different idempotency key.
         attempt: existing?.attempt ?? 0,
         blobId: meta.blobId,
         nonceB64,
-        rootHashB64: Buffer.from(meta.rootHash).toString("base64url"),
+        rootHashB64: toBase64Url(meta.rootHash),
         relayUrl: input.relayUrl,
         epochs: input.epochs,
         sealedLen: sealed.length,
@@ -181,7 +182,7 @@ export async function buyAndPushPart(input) {
         parentId: input.entry.parentId,
     };
     // ⛔ BEFORE THE MONEY. See the module header.
-    writeReservation(key, record, sealed);
+    await writeReservation(key, record, sealed);
     onStep?.({ step: "reserving" });
     let reply;
     try {
@@ -196,7 +197,7 @@ export async function buyAndPushPart(input) {
             deposit_credits: input.depositCredits,
             relay: {
                 host: input.relayUrl,
-                blob_digest_b64: Buffer.from(meta.blobDigest).toString("base64url"),
+                blob_digest_b64: toBase64Url(meta.blobDigest),
                 nonce_b64: nonceB64,
             },
         });
@@ -217,7 +218,7 @@ export async function buyAndPushPart(input) {
     if (!isLive(reply.state)) {
         // Same reason as the resumed branch above: keep the record, count up, so the next run does not
         // ask under a key the server has already settled.
-        writeReservation(key, { ...stripReservation(record), attempt: record.attempt + 1 }, sealed);
+        await writeReservation(key, { ...stripReservation(record), attempt: record.attempt + 1 }, sealed);
         throw new UploadError({
             phase: "reserve",
             message: `The reservation came back as "${reply.state}", which cannot become storage.`,
@@ -230,7 +231,7 @@ export async function buyAndPushPart(input) {
         record.registerTxDigest = reply.register_tx_digest;
     if (reply.blob_object_id)
         record.blobObjectId = reply.blob_object_id;
-    writeReservation(key, record, sealed);
+    await writeReservation(key, record, sealed);
     if (reply.state === "certified") {
         return paidPart(record, reply.ledger_id, false);
     }

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

@@ -0,0 +1,4 @@
+import type { Network } from "./network.ts";
+/** How long the two questions get together. A read that stalls is a read that failed. */
+export declare const HISTORY_TIMEOUT_MS = 20000;
+export declare function hasHistory(network: Network, address: string): Promise<boolean>;

package/dist/wallet-list-chain.js

@@ -0,0 +1,21 @@
+// The live read behind `nmts wallet list`'s walk: has this address ever been in a transaction?
+//
+// ⛔ READ ONLY, and one question in each direction. The RPC filter has no OR, so "from" and "to"
+//    are asked separately — a wallet that only ever RECEIVED is in use too, and a walk that asked
+//    about balances alone would report a wallet somebody emptied as one that does not exist.
+//
+// ⚠ ONE transaction is enough to answer, so one is what is asked for. This runs once per wallet
+//   the walk looks at, which is why it asks for as little as the chain will sell.
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import { suiRpcTransport } from "./sui-rpc.js";
+/** How long the two questions get together. A read that stalls is a read that failed. */
+export const HISTORY_TIMEOUT_MS = 20_000;
+export async function hasHistory(network, address) {
+    const client = new SuiJsonRpcClient({ network, transport: suiRpcTransport(network) });
+    const signal = AbortSignal.timeout(HISTORY_TIMEOUT_MS);
+    const sent = await client.queryTransactionBlocks({ filter: { FromAddress: address }, limit: 1, signal });
+    if (sent.data.length > 0)
+        return true;
+    const received = await client.queryTransactionBlocks({ filter: { ToAddress: address }, limit: 1, signal });
+    return received.data.length > 0;
+}

package/dist/wallet-pay-index.d.ts

@@ -0,0 +1,21 @@
+export interface PayingWalletInput {
+    server?: string | undefined;
+    network?: string | undefined;
+    /** `--wallet N` — this run only, and it never writes the account's choice. */
+    wallet?: string | undefined;
+    /**
+     * ⚠ A SEAM, NOT AN OPTION: how the account's number is read. No flag reaches it. It exists
+     *   because the alternative is a test that signs in and reads a live file list to check that a
+     *   review was printed.
+     */
+    readActiveWallet?: () => Promise<number>;
+}
+/**
+ * A wallet number as a person typed it.
+ *
+ * ⛔ REFUSED, NEVER ROUNDED. `--wallet 1.5` and `--wallet -1` are command lines to correct; taking
+ *    either of them to a neighbouring wallet would spend from an address nobody named.
+ */
+export declare function walletIndexOf(raw: string): number;
+/** Which wallet this run pays from: the flag if it was given, otherwise the account's own number. */
+export declare function payingWalletIndex(input: PayingWalletInput): Promise<number>;

package/dist/wallet-pay-index.js

@@ -0,0 +1,68 @@
+// WHICH WALLET PAYS — the number this account keeps in its sealed file list, and the one flag that
+// overrides it for a single run.
+//
+// ⛔ WHY IT IS NOT A CONSTANT ANY MORE (2026-09-16). One NMTS key derives a wallet at
+//    every index (NCF-3 §1.3) and the account chooses which of them pays, so that a phone, a
+//    laptop and this tool all spend from the same address. That choice lives where no server can
+//    read it: inside the sealed list, beside the padding rule.
+//
+// ⛔ AND IT REFUSES RATHER THAN GUESSING. If the list cannot be read, this tool does not fall back
+//    to the first wallet: that would sign with a wallet the person may not have funded, print a
+//    review naming an address nobody chose, and — with `--yes` — spend from it. "I do not know
+//    which wallet should pay" is an answer; wallet 0 is not.
+//
+// ⚠ THE NUMBER IS RESOLVED BEFORE ANYTHING IS PRICED. Every command that spends prints a review
+//   with the paying address in it, so the address that is read, priced and shown has to be the
+//   address that signs. Asking for the number at signing time would let those two differ.
+import { NmtsError } from "./errors.js";
+import { readFileList } from "./manifest.js";
+import { BINARY_NAME } from "./product.js";
+import { openSession } from "./session.js";
+import { activeWalletOf, WALLET_INDEX_LIMIT } from "./shared/lib/drive/manifest-settings.js";
+/**
+ * A wallet number as a person typed it.
+ *
+ * ⛔ REFUSED, NEVER ROUNDED. `--wallet 1.5` and `--wallet -1` are command lines to correct; taking
+ *    either of them to a neighbouring wallet would spend from an address nobody named.
+ */
+export function walletIndexOf(raw) {
+    const text = raw.trim();
+    const value = Number(text);
+    if (!/^[0-9]+$/u.test(text) || !Number.isSafeInteger(value) || value >= WALLET_INDEX_LIMIT) {
+        throw new NmtsError(`A wallet number is a whole number from 0 to ${WALLET_INDEX_LIMIT - 1}, not "${raw}".`, {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} wallet list\` shows this key's wallets and their numbers.`,
+        });
+    }
+    return value;
+}
+/** Which wallet this run pays from: the flag if it was given, otherwise the account's own number. */
+export async function payingWalletIndex(input) {
+    const said = input.wallet;
+    if (said !== undefined && said !== "")
+        return walletIndexOf(said);
+    const read = input.readActiveWallet ?? (() => fromSealedList(input));
+    try {
+        return await read();
+    }
+    catch (error) {
+        // ⛔ A refusal this tool already worded (no API key, a locked code) is passed on as it stands —
+        //    it names the thing to fix, and wrapping it would bury that under a second sentence.
+        if (error instanceof NmtsError)
+            throw error;
+        throw new NmtsError(`Which wallet should pay is written in this account's file list, and it could not be read: ` +
+            `${error instanceof Error ? error.message : String(error)}`, {
+            exitCode: 1,
+            nextStep: `Nothing was signed. Try again when the list can be read, or name the wallet for this ` +
+                `one run with \`--wallet N\` — \`${BINARY_NAME} wallet list\` shows the numbers.`,
+        });
+    }
+}
+/** The account's own number, out of the sealed file list. One request, and no flag reaches it. */
+async function fromSealedList(input) {
+    const session = await openSession({ server: input.server, network: input.network });
+    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+    // An account that has never written a setting pays from the first wallet — that is a READ
+    // answer, not a fallback: the list opened, and it said nothing about a wallet.
+    return activeWalletOf(list.manifest?.settings);
+}