@needmoretruth/nmts-cli 0.35.0 → 0.36.1

package/dist/upload-store.js

@@ -9,25 +9,21 @@
 //
 //    So they are written down BEFORE the money moves. That ordering is the whole design.
 //
-// ⛔ WHAT IS ON DISK IS ALREADY PUBLIC. The `.bin` is the sealed NCF-3 stream — the exact bytes
-//    about to be handed to a public storage network. It is still written 0600, because "already
-//    public" is about the CONTENT and the file's presence would otherwise say which files this
-//    account uploaded and when.
+// ⛔ WHAT IS KEPT IS ALREADY PUBLIC. The `.bin` half is the sealed NCF-3 stream — the exact bytes
+//    about to be handed to a public storage network. The host still keeps it as privately as it
+//    can (0600 on this machine), because "already public" is about the CONTENT and the record's
+//    presence would otherwise say which files this account uploaded and when.
 //
-// ⛔ THE FILE NAME IS NOT A CONTENT FINGERPRINT. Keying by SHA-256 of the plaintext would leave a
-//    directory of hashes matchable against published hash sets — the very thing sealing the
-//    content hash avoids. The key mixes the account's data key in, so it identifies the file only
-//    to somebody who already holds the account.
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { configDir, modesAreEnforced } from "./credentials.js";
-import { chmodSync } from "node:fs";
+// ⛔ THE KEY IS NOT A CONTENT FINGERPRINT. Keying by SHA-256 of the plaintext would leave a store
+//    of hashes matchable against published hash sets — the very thing sealing the content hash
+//    avoids. The key mixes the account's data key in, so it identifies the file only to somebody
+//    who already holds the account.
+import { sha256 } from "@noble/hashes/sha2.js";
+import { fromUtf8, toBase64Url, utf8 } from "./bytes.js";
 import { NmtsError } from "./errors.js";
-/** Where unfinished uploads live. */
-export function uploadsDir() {
-    return join(configDir(), "uploads");
-}
+import { host } from "./host.js";
+/** The area of the host's state these records live in. One key per file below it. */
+const AREA = "uploads";
 /**
  * A stable, account-scoped name for one file's upload attempt.
  *
@@ -71,12 +67,12 @@ export function reservationKeyStreamed(dataKey, plaintextChunks, name, destinati
  *    what lets both come out of a single pass instead of two reads of a very large file.
  */
 export function startReservationKey(dataKey) {
-    return createHash("sha256").update(dataKey);
+    return sha256.create().update(dataKey);
 }
 /** Finish it. The name and the destination go in last, exactly as the one-shot form does. */
 export function finishReservationKey(hash, name, destination) {
-    const digest = hash.update(new TextEncoder().encode(`\u0000${name}\u0000${destination}`)).digest();
-    return Buffer.from(digest).toString("base64url").slice(0, 32);
+    const digest = hash.update(utf8(`\u0000${name}\u0000${destination}`)).digest();
+    return toBase64Url(digest).slice(0, 32);
 }
 /**
  * The record name for ONE part of a file.
@@ -89,9 +85,9 @@ export function finishReservationKey(hash, name, destination) {
 export function partKey(fileKey, partIndex) {
     return `${fileKey}~p${partIndex}`;
 }
-function paths(key) {
-    const dir = uploadsDir();
-    return { json: join(dir, `${key}.json`), bin: join(dir, `${key}.bin`) };
+/** The two keys one part's reservation occupies: its record, and the sealed bytes it bought. */
+function keysFor(key) {
+    return { json: `${AREA}/${key}.json`, bin: `${AREA}/${key}.bin` };
 }
 function isReservation(value) {
     if (typeof value !== "object" || value === null)
@@ -114,23 +110,25 @@ function isReservation(value) {
  *    resume that only needs to commit still reads every byte of a very large upload off the disk.
  *    They are fetched separately, by the one step that actually pushes them.
  */
-export function readReservationRecord(key) {
-    const { json, bin } = paths(key);
-    if (!existsSync(json) || !existsSync(bin))
+export async function readReservationRecord(key) {
+    const { json, bin } = keysFor(key);
+    const state = host().state;
+    const held = await state.read(json);
+    if (held === undefined || (await state.read(bin)) === undefined)
         return null;
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(json, "utf8"));
+        parsed = JSON.parse(fromUtf8(held));
     }
     catch {
         // ⛔ Unreadable is not the same as absent, and treating it as absent would buy storage twice.
-        throw new NmtsError(`An unfinished upload record at ${json} could not be read.`, {
+        throw new NmtsError(`The unfinished upload record ${json} could not be read.`, {
             nextStep: "It names storage this account may already have paid for. Move it aside rather than " +
                 "deleting it if the upload matters, then try again.",
         });
     }
     if (!isReservation(parsed)) {
-        throw new NmtsError(`The unfinished upload record at ${json} is not in a shape this version knows.`, {
+        throw new NmtsError(`The unfinished upload record ${json} is not in a shape this version knows.`, {
             nextStep: "Move it aside and try again. Nothing was sent.",
         });
     }
@@ -143,38 +141,36 @@ export function readReservationRecord(key) {
  *    different blob from the one the treasury registered — the relay refuses them, forever, and
  *    the credits are gone.
  */
-export function readReservationBytes(key) {
-    const { bin } = paths(key);
-    return new Uint8Array(readFileSync(bin));
+export async function readReservationBytes(key) {
+    const { bin } = keysFor(key);
+    const held = await host().state.read(bin);
+    if (held === undefined) {
+        throw new NmtsError(`The sealed bytes of ${bin} are gone.`, {
+            nextStep: "Nothing was sent. The storage they bought cannot be filled by re-sealing — run the " +
+                "upload again to buy storage for a fresh sealing of the same file.",
+        });
+    }
+    return held;
 }
 /** The record and its bytes together, for the callers that need both. */
-export function readReservation(key) {
-    const record = readReservationRecord(key);
+export async function readReservation(key) {
+    const record = await readReservationRecord(key);
     if (record === null)
         return null;
-    return { record, sealed: readReservationBytes(key) };
+    return { record, sealed: await readReservationBytes(key) };
 }
 /** Write the record and its sealed bytes. Called BEFORE the reserve, and again after it answers. */
-export function writeReservation(key, record, sealed) {
-    const dir = uploadsDir();
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    if (modesAreEnforced())
-        chmodSync(dir, 0o700);
-    const { json, bin } = paths(key);
-    // ⛔ WRITTEN ASIDE AND RENAMED OVER, never truncated in place. A rename within one directory is
-    //    atomic, so a reader sees the old record or the new one and never a half-written one. The
-    //    write that matters is the LAST one — the one that adds the item id — because a truncated
-    //    file there is the only local pointer to a file that is already paid for and committed, and
-    //    losing it makes that file invisible.
-    atomically(bin, sealed);
-    atomically(json, Buffer.from(`${JSON.stringify(record, null, 2)}\n`, "utf8"));
-}
-function atomically(target, bytes) {
-    const scratch = `${target}.${process.pid}.tmp`;
-    writeFileSync(scratch, bytes, { mode: 0o600 });
-    if (modesAreEnforced())
-        chmodSync(scratch, 0o600);
-    renameSync(scratch, target);
+export async function writeReservation(key, record, sealed) {
+    const { json, bin } = keysFor(key);
+    // ⛔ THE BYTES GO DOWN FIRST, AND THE RECORD IS WHAT MAKES THE PAIR COUNT. A reader treats a
+    //    record without its bytes as no reservation at all, so a run that stopped between these two
+    //    writes leaves nothing that can be resumed — rather than a record pointing at bytes that are
+    //    not there. Each write on its own is all-or-nothing; that is the host's promise, and the
+    //    write that matters most is the LAST one, because a half-written record is the only local
+    //    pointer to a file that is already paid for.
+    const state = host().state;
+    await state.write(bin, sealed);
+    await state.write(json, utf8(`${JSON.stringify(record, null, 2)}\n`));
 }
 /**
  * Forget a reservation.
@@ -183,11 +179,11 @@ function atomically(target, bytes) {
  *   upload already succeeded" was not true of every caller. What IS true of all of them is that
  *   nothing further depends on the record, which is why it never throws.
  */
-export function clearReservation(key) {
-    const { json, bin } = paths(key);
-    for (const path of [json, bin]) {
+export async function clearReservation(key) {
+    const { json, bin } = keysFor(key);
+    for (const name of [json, bin]) {
         try {
-            rmSync(path, { force: true });
+            await host().state.remove(name);
         }
         catch {
             // ⚠ A record that cannot be removed is left where it is. That is not free -- a record
@@ -197,8 +193,8 @@ export function clearReservation(key) {
         }
     }
 }
-function itemPath(fileKey) {
-    return join(uploadsDir(), `${fileKey}.item.json`);
+function itemKey(fileKey) {
+    return `${AREA}/${fileKey}.item.json`;
 }
 function isItemRecord(value) {
     if (typeof value !== "object" || value === null)
@@ -209,41 +205,38 @@ function isItemRecord(value) {
     return id === undefined || typeof id === "string";
 }
 /** What is known about this file's commit, or `null` when it has not been attempted. */
-export function readItemRecord(fileKey) {
-    const path = itemPath(fileKey);
-    if (!existsSync(path))
+export async function readItemRecord(fileKey) {
+    const path = itemKey(fileKey);
+    const held = await host().state.read(path);
+    if (held === undefined)
         return null;
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
+        parsed = JSON.parse(fromUtf8(held));
     }
     catch {
         // ⛔ Same reasoning as an unreadable reservation: unreadable is not absent. This file is the
         //    only local pointer to storage that is already bought and possibly already committed.
-        throw new NmtsError(`An unfinished upload record at ${path} could not be read.`, {
+        throw new NmtsError(`The unfinished upload record ${path} could not be read.`, {
             nextStep: "It names a file this account may already have paid for. Move it aside rather than " +
                 "deleting it if the upload matters, then try again.",
         });
     }
     if (!isItemRecord(parsed)) {
-        throw new NmtsError(`The unfinished upload record at ${path} is not in a shape this version knows.`, {
+        throw new NmtsError(`The unfinished upload record ${path} is not in a shape this version knows.`, {
             nextStep: "Move it aside and try again. Nothing was sent.",
         });
     }
     return parsed;
 }
 /** Write the file-level record. Called before the commit, and again once it has an id. */
-export function writeItemRecord(fileKey, record) {
-    const dir = uploadsDir();
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    if (modesAreEnforced())
-        chmodSync(dir, 0o700);
-    atomically(itemPath(fileKey), Buffer.from(`${JSON.stringify(record, null, 2)}\n`, "utf8"));
+export async function writeItemRecord(fileKey, record) {
+    await host().state.write(itemKey(fileKey), utf8(`${JSON.stringify(record, null, 2)}\n`));
 }
 /** Forget the file-level record. Never throws, for the same reason `clearReservation` does not. */
-export function clearItemRecord(fileKey) {
+export async function clearItemRecord(fileKey) {
     try {
-        rmSync(itemPath(fileKey), { force: true });
+        await host().state.remove(itemKey(fileKey));
     }
     catch {
         // ⚠ Left where it is. A stale one carrying an item id would be resumed rather than

package/dist/upload-wallet-chain.js

@@ -21,6 +21,7 @@ import { bcs } from "@mysten/sui/bcs";
 import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
 import { Transaction } from "@mysten/sui/transactions";
 import { blobIdFromInt, blobIdToInt, MAINNET_WALRUS_PACKAGE_CONFIG, TESTNET_WALRUS_PACKAGE_CONFIG, walrus, } from "@mysten/walrus";
+import { fromBase64Url } from "./bytes.js";
 import { NmtsError } from "./errors.js";
 import { extendReads, netGasFee, readBlobLease } from "./extend-chain.js";
 import { readOwnedStorage, readStorageType } from "./shared/lib/storage-control/chain.js";
@@ -104,8 +105,8 @@ export function certifyTransaction(client, input) {
         deletable: true,
         certificate: {
             signers: input.certificate.signers,
-            serializedMessage: new Uint8Array(Buffer.from(input.certificate.serialized_message_b64, "base64url")),
-            signature: new Uint8Array(Buffer.from(input.certificate.signature_b64, "base64url")),
+            serializedMessage: fromBase64Url(input.certificate.serialized_message_b64),
+            signature: fromBase64Url(input.certificate.signature_b64),
         },
     });
 }

package/dist/upload-wallet-put.js

@@ -197,9 +197,9 @@ export async function walletPut(ctx, file, seams = {}) {
     // ⛔ 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.
-    clearItemRecord(result.fileKey);
+    await clearItemRecord(result.fileKey);
     for (const record of partKeysOf(result.fileKey, result.parts))
-        clearReservation(record);
+        await clearReservation(record);
     if (added.replaced)
         await setTrashed(ctx.server, ctx.apiKey, added.replaced.id, true);
     return {

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)
@@ -133,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) {
@@ -149,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,
         });
@@ -192,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-sign-seams.d.ts

@@ -8,6 +8,14 @@ import type { Network } from "./network.ts";
 export type SignMessage = (input: {
     /** ⛔ The NMTS key. It never leaves this machine: it derives the wallet and nothing else. */
     code: string;
+    /**
+     * Which of this key's wallets proves the name.
+     *
+     * ⛔ IT IS THE PAYING WALLET BECAUSE THAT IS THE WALLET THE GIFT CAME FROM. A hall entry is an
+     *    address, and `wallet donate` sends from the account's own number; signing with any other
+     *    wallet would offer the server a name for an address that has never given anything.
+     */
+    wallet: number;
     message: string;
 }) => Promise<string>;
 /** The seam `commands/wallet-send.ts` signs through. Returns the transaction digest. */
@@ -24,6 +32,8 @@ export type SignSwap = (input: {
     network: Network;
     /** ⛔ The NMTS key. It never leaves this machine: it derives the wallet and nothing else. */
     code: string;
+    /** Which of this key's wallets swaps — the account's own number (`wallet-pay-index.ts`). */
+    wallet: number;
     shape: SwapShape;
 }) => Promise<string>;
 /** The seam the wallet rail registers through. */
@@ -52,6 +62,8 @@ export type SignBlobCertify = (input: {
 export type SignStorageOp = (input: {
     network: Network;
     code: string;
+    /** Which of this key's wallets holds the resource — the account's own number. */
+    wallet: number;
     shape: StorageOpShape;
     walrusPackageId: string;
 }) => Promise<string>;

package/dist/wallet-sign.js

@@ -189,10 +189,10 @@ export const signTransfer = async ({ network, code, wallet, shape }) => {
  *    makes. `signPersonalMessage` and not `sign`: that intent is the domain separator which stops
  *    signed text from ever being read as a transaction this wallet authorised.
  */
-export const signMessage = async ({ code, message }) => {
-    // ⚠ THE FIRST WALLET SIGNS THE NAME — the address that stands in the hall is that wallet's, and
-    //   the account's choice of paying wallet does not reach this command yet.
-    const keypair = await keypairFor(code, BUILT_IN_WALLET_INDEX);
+export const signMessage = async ({ code, wallet, message }) => {
+    // The wallet the caller resolved signs it: the hall entry is that wallet's address, and it is
+    // the wallet a gift left from, so any other one would name an address that gave nothing.
+    const keypair = await keypairFor(code, wallet);
     const { signature } = await keypair.signPersonalMessage(new TextEncoder().encode(message));
     return signature;
 };
@@ -207,12 +207,9 @@ export const signMessage = async ({ code, message }) => {
  *
  * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED — the same words as the extension above.
  */
-export const signSwap = async ({ network, code, shape }) => {
+export const signSwap = async ({ network, code, wallet, shape }) => {
     const client = walrusClient(network);
-    // ⚠ SWAPS FROM THE FIRST WALLET — the coins being swapped are that wallet's, and the account's
-    //   choice of paying wallet does not reach this command yet. The day it does, this line and the
-    //   review above it carry the same number.
-    const keypair = await keypairFor(code, BUILT_IN_WALLET_INDEX);
+    const keypair = await keypairFor(code, wallet);
     const tx = swapTransaction({ ...shape, network, sender: keypair.toSuiAddress() });
     const result = await client.signAndExecuteTransaction({
         transaction: tx,
@@ -303,11 +300,11 @@ export const signBlobCertify = async ({ network, code, wallet, relayUrl, ...shap
  *    so what is signed is what was reviewed. A failed execution still has a digest and still
  *    spent its gas, so the status is read and a failure is said as one.
  */
-export const signStorageOp = async ({ network, code, shape, walrusPackageId }) => {
+export const signStorageOp = async ({ network, code, wallet, shape, walrusPackageId }) => {
     const client = walrusClient(network);
-    // ⚠ RESHAPES THE FIRST WALLET'S STORAGE — that wallet holds the resource; the paying-wallet choice
-    //   does not reach this command yet.
-    const keypair = await keypairFor(code, BUILT_IN_WALLET_INDEX);
+    // The resource the review named was read from this wallet's address, so this wallet is the one
+    // that can reshape or hand it over.
+    const keypair = await keypairFor(code, wallet);
     const tx = storageOpTransaction(shape, { walrusPackageId, sender: keypair.toSuiAddress() });
     const result = await client.signAndExecuteTransaction({ transaction: tx, signer: keypair, options: { showEffects: true } });
     const effects = result.effects;

package/dist/walrus-write.js

@@ -10,6 +10,7 @@
 //    transaction paid — see the note on `sendTip` below, which is not what its name suggests.
 import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
 import { walrus } from "@mysten/walrus";
+import { toBase64Url } from "./bytes.js";
 import { epochClock } from "./expiry.js";
 // ⛔ The re-export below is what callers use; this local name is the same function,
 //    imported so the reader above can call it without importing from itself.
@@ -112,8 +113,8 @@ export function createBlobProtocol(network, bodyBytes, onSent) {
                 .catch((error) => fail("The upload relay refused the bytes", error));
             return {
                 signers: certificate.signers,
-                serialized_message_b64: Buffer.from(certificate.serializedMessage).toString("base64url"),
-                signature_b64: Buffer.from(certificate.signature).toString("base64url"),
+                serialized_message_b64: toBase64Url(certificate.serializedMessage),
+                signature_b64: toBase64Url(certificate.signature),
             };
         },
     };

package/dist/walrus.d.ts

@@ -28,22 +28,7 @@ export declare const RELAY_HOSTS: Readonly<Record<string, readonly string[]>>;
 export declare const SUI_RPC_HOSTS: Readonly<Record<string, readonly string[]>>;
 /** How long one host gets before the next is tried. A read that stalls is a read that failed. */
 export declare const READ_TIMEOUT_MS = 60000;
-/**
- * Point reads at somebody else's aggregator, or at a development stack.
- *
- * ⚠ It replaces the list rather than adding to it, and that is deliberate: a run should read from
- *   where it was told to read, not from there AND the public hosts. Comma-separated for more
- *   than one, tried in the order given.
- */
-export declare const AGGREGATOR_ENV_VAR = "NMTS_AGGREGATOR";
-/**
- * Push writes through somebody else's relay, or through a development stack.
- *
- * ⚠ ONE host, not a list. Unlike reads there is nothing to fail over to — see `RELAY_HOSTS`.
- */
-export declare const RELAY_ENV_VAR = "NMTS_RELAY";
-/** Ask a different Sui JSON-RPC node the shard-count question. */
-export declare const SUI_RPC_ENV_VAR = "NMTS_SUI_RPC";
+export { AGGREGATOR_ENV_VAR, RELAY_ENV_VAR, SUI_RPC_ENV_VAR } from "./env-vars.ts";
 /** The relay this run writes through: the environment's if it named one, else the network's. */
 export declare function relayHost(network: string): string;
 /**