@needmoretruth/nmts-cli 0.17.2

package/dist/wallet-chain.js

@@ -0,0 +1,76 @@
+// The real chain reads behind `nmts wallet` — the only file in this command that loads the Sui SDK.
+//
+// ⛔ SPLIT OUT SO THE COMMAND CAN BE TESTED. `wallet.ts` decides what a balance means and what is
+//    said when there is none; this only knows how to ask. Keeping the SDK out of the deciding half
+//    is what lets `node --test` drive every branch — including the ones a live chain would only
+//    produce by being broken.
+//
+// ⛔ IT READS AND CANNOT DO ANYTHING ELSE. No signer is built here, no transaction is assembled,
+//    and the two calls below are the whole of this file's contact with the network: what one
+//    address holds, and whether a coin type exists. A balance is public data — anybody can ask the
+//    same question about the same address — so nothing about this run leaves that was not already
+//    published by the chain itself.
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import { suiRpcHost } from "./walrus.js";
+/**
+ * How long one balance question gets.
+ *
+ * A read that stalls is a read that failed, and the caller has something honest to print either
+ * way. Long enough for a slow public node, short enough that an agent waiting on this does not
+ * conclude the tool has hung.
+ */
+export const BALANCE_TIMEOUT_MS = 20_000;
+/**
+ * Read balances for one address on one network.
+ *
+ * ⚠ THE NODE IS NOT TRUSTED WITH ANYTHING, and it does not have to be: what it answers is printed
+ *   as a number and nothing is decided on it. A node that lies about a balance produces a wrong
+ *   number on a screen — where its owner will see it disagree with every other wallet they own —
+ *   and it cannot produce a wrong address, because the address never came from it.
+ */
+export function chainReader(network, address) {
+    // The network name reaches the SDK as well as the URL, which is what keeps a mirror pointed at
+    // the wrong chain from being discovered later, as an answer that quietly made no sense.
+    const client = new SuiJsonRpcClient({ network, url: suiRpcHost(network) });
+    return {
+        async totalOf(coinType) {
+            const { totalBalance } = await client.getBalance({
+                owner: address,
+                coinType,
+                signal: AbortSignal.timeout(BALANCE_TIMEOUT_MS),
+            });
+            return baseUnitsOf(totalBalance);
+        },
+        async knowsCoinType(coinType) {
+            // Null is the answer for a type that does not exist — measured against the public mainnet
+            // node this tool reads from, 2026-08-24, which is also where the balance-of-a-made-up-coin
+            // measurement in `wallet.ts` comes from.
+            const metadata = await client.getCoinMetadata({
+                coinType,
+                signal: AbortSignal.timeout(BALANCE_TIMEOUT_MS),
+            });
+            return metadata !== null;
+        },
+    };
+}
+/**
+ * A total off the wire, as base units.
+ *
+ * ⛔ A STRING, AND IT STAYS EXACT. Balances run past what a JavaScript number holds without losing
+ *    digits, so the value is never converted through one. Anything that is not a whole,
+ *    non-negative count of base units is refused rather than rounded into something printable:
+ *    this tool would rather say it could not read the balance than print a number the chain did
+ *    not say.
+ */
+function baseUnitsOf(total) {
+    let units;
+    try {
+        units = BigInt(total);
+    }
+    catch {
+        throw new Error("the chain answered with a balance this tool cannot read as a number");
+    }
+    if (units < 0n)
+        throw new Error("the chain answered with a negative balance, which is not a balance");
+    return units;
+}

package/dist/wallet.js

@@ -0,0 +1,209 @@
+// The wallet an account code derives: its address, and what a chain says it holds.
+//
+// ⛔ NOTHING HERE SIGNS OR SPENDS, AND NOTHING HERE HANDS OUT A KEY. The only secret this module
+//    touches is the 32-byte wallet seed; it lives for the length of one address computation and is
+//    wiped on every path out, failures included. No function returns a seed, a private key or a
+//    keypair, so a later caller cannot reach one without deciding to add one.
+//
+// ⛔ THE DERIVATION IS THE ENGINE'S, NOT THIS FILE'S. `wallet_seed_for` is the same WebAssembly
+//    function the browser app calls, off the same wallet root, at the same index — so the address
+//    printed here is the address the account already has. A second derivation written in
+//    TypeScript would be free to drift from the first, and the way that surfaces is somebody
+//    funding an address their account cannot spend from.
+//
+// ⛔ A BALANCE THAT COULD NOT BE READ IS NOT ZERO. On a screen the two look identical; they mean
+//    opposite things — "this wallet is empty" and "nobody here knows". Every result below says
+//    which of the two it is, and a caller has to open the result to get at a number at all.
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { assertUsableCode } from "./account.js";
+import { DERIVED, loadCrypto } from "./crypto.js";
+import { NmtsError } from "./errors.js";
+/**
+ * The wallet this account code opens by itself.
+ *
+ * ⛔ IT IS WALLET 0 BECAUSE THAT IS THE ONE THE BROWSER OPENS. Every wallet, including this one,
+ *    comes out of `wallet_seed_for` — there is no special case for the first — so the index is the
+ *    whole of the difference between "the account's wallet" and somebody else's.
+ *
+ * ⛔ EXPORTED SO THE SIGNER CANNOT PICK ITS OWN. `extend-sign.ts` derives a keypair from the same
+ *    root and has to reach the SAME wallet as the address printed here; a second literal `0` over
+ *    there would be a second answer to a question with one right one, and the failure is silent —
+ *    a signature from an address nobody funded. `extend-sign.test.ts` compares the two.
+ */
+export const BUILT_IN_WALLET_INDEX = 0;
+/**
+ * How many base units make one coin. SUI counts in MIST and WAL counts in FROST; both are 1e9.
+ *
+ * The two constants are written as digits and scale rather than as one number so they cannot
+ * disagree with each other.
+ */
+const BASE_UNIT_DIGITS = 9;
+const BASE_UNITS_PER_COIN = 10n ** BigInt(BASE_UNIT_DIGITS);
+/** The chain's own coin. Its type is fixed by the chain itself and takes no network. */
+export const SUI_COIN_TYPE = "0x2::sui::SUI";
+/**
+ * The storage network's coin, per chain.
+ *
+ * ⛔ A WRONG VALUE HERE READS AS AN EMPTY WALLET RATHER THAN AS A FAULT. Measured against the
+ *    public mainnet node this tool reads from, 2026-08-24: asking for a coin type that does not
+ *    exist answers `totalBalance: "0"` — the same answer a real empty balance gives. That
+ *    measurement is why `readBalances` never reports a zero WAL balance without first asking the
+ *    chain whether it has heard of the type at all; see `ChainReader.knowsCoinType`.
+ *
+ * ⚠ THIS IS A SECOND COPY. The browser app carries the same two strings for the same reason, and
+ *   no machine holds the two level — this package deliberately imports nothing from that tree.
+ *   What keeps them honest is the check above: a copy that went stale stops answering zero and
+ *   starts saying it could not be read.
+ */
+export const WAL_COIN_TYPES = {
+    testnet: "0x8270feb7375eee355e64fdb69c50abb6b5f9393a722883c1cf45f8e26048810a::wal::WAL",
+    mainnet: "0x356a26eb9e012a68958082340d4c4116e7f55615cf27affcff209cf0ae544f59::wal::WAL",
+};
+/** The WAL coin type for one network. */
+export function walCoinType(network) {
+    return WAL_COIN_TYPES[network];
+}
+/**
+ * The Sui address of one 32-byte wallet seed.
+ *
+ * ⛔ IT IS THE SDK'S COMPUTATION, NOT ONE WRITTEN HERE. An address is BLAKE2b-256 over a scheme
+ *    byte and the public key; hand-rolling that would put a second answer in the world for a
+ *    question that must have exactly one, and the failure would be silent — a well-formed address
+ *    nobody can spend from.
+ *
+ * ⚠ THE KEYPAIR HOLDS THE SECRET AND CANNOT BE WIPED. `@mysten/sui` keeps the key inside its own
+ *   object, with no method that clears it; the same is true in the browser's worker. What is
+ *   controlled here is lifetime: it is built, asked one question, and dropped, and the caller's
+ *   copy of the seed is zeroed. Nothing retains it.
+ *
+ * Exported because the vectors that hold this to the other implementations of the same derivation
+ * are (seed, address) pairs, and a test cannot check them through the account-code entry point.
+ */
+export function addressFromSeed(seed) {
+    return Ed25519Keypair.fromSecretKey(seed).toSuiAddress();
+}
+/**
+ * The address of the wallet this account code derives. Offline: nothing is asked of anybody.
+ *
+ * The same address on every network — an account has one wallet, and which chain it is looked up
+ * on is a separate question from what it is called.
+ */
+export async function walletAddress(code) {
+    // ⛔ The one refusal text for a malformed code lives in `account.ts`. Checking here means a typo
+    //    fails the same way it fails everywhere else in this tool rather than as an engine error.
+    await assertUsableCode(code);
+    const glue = await loadCrypto();
+    let bytes;
+    try {
+        bytes = glue.account_code_parse(code);
+    }
+    catch {
+        // ⛔ Unreachable in practice — the same parser accepted this input a line ago. It is caught
+        //    anyway because the alternative is an engine message going out verbatim, and an engine
+        //    message about a code can carry the code (see `errors.ts`).
+        throw new NmtsError("The account code could not be read on this machine.", { exitCode: 1 });
+    }
+    // ⛔ THIS BUFFER IS EVERY KEY IN THE ACCOUNT, not just the wallet root: the sign-in secret, the
+    //    key that opens the files, the key that opens the file list. It is wiped below along with
+    //    everything sliced out of it, on the failing paths as well as the good one.
+    const derived = glue.kdf_derive(bytes);
+    try {
+        return addressFromDerived(glue, derived);
+    }
+    finally {
+        derived.fill(0);
+        bytes.fill(0);
+    }
+}
+/**
+ * The built-in wallet's address, from a buffer the caller already holds.
+ *
+ * ⛔ IT TAKES KEY MATERIAL AND RETURNS A STRING. `derived` belongs to the caller and is left
+ *    alone; the two secrets this function makes — the wallet root it slices out and the seed the
+ *    engine expands from it — are wiped before it returns, on the failing path as well as the
+ *    good one. Neither one leaves.
+ */
+export function addressFromDerived(glue, derived) {
+    const [from, to] = DERIVED.walletRoot;
+    const root = derived.slice(from, to);
+    let seed = null;
+    try {
+        seed = glue.wallet_seed_for(root, BUILT_IN_WALLET_INDEX);
+        return addressFromSeed(seed);
+    }
+    finally {
+        root.fill(0);
+        seed?.fill(0);
+    }
+}
+/** Why a coin came back unread, from whatever was thrown. */
+function reasonOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Read both balances, keeping "could not be read" apart from "empty" in every branch.
+ *
+ * ⚠ THE REASON A READ FAILED IS SAFE TO PRINT, and that is worth saying because in this tool it
+ *   usually is not (`errors.ts`). Nothing secret is in one of these requests: what goes out is a
+ *   public address and a coin type, so what comes back cannot quote a secret.
+ *
+ * ⛔ ONE COIN'S FAILURE DOES NOT TAKE THE OTHER DOWN. They are separate requests about separate
+ *   coins, and an answer for one of them is worth more than a matching pair of silences.
+ */
+export async function readBalances(reader, walType) {
+    const [sui, wal] = await Promise.all([readSui(reader), readWal(reader, walType)]);
+    return { sui, wal };
+}
+async function readSui(reader) {
+    // ⛔ NO COIN-TYPE CHECK FOR THIS ONE, and the asymmetry is deliberate: `0x2::sui::SUI` is the
+    //    chain's own coin, named by the chain rather than by this build, so a zero here is a zero.
+    try {
+        return { read: true, baseUnits: await reader.totalOf(SUI_COIN_TYPE) };
+    }
+    catch (error) {
+        return { read: false, why: reasonOf(error) };
+    }
+}
+async function readWal(reader, walType) {
+    let total;
+    try {
+        total = await reader.totalOf(walType);
+    }
+    catch (error) {
+        return { read: false, why: reasonOf(error) };
+    }
+    // A positive balance is its own proof that the coin type is real; only zero is ambiguous.
+    if (total > 0n)
+        return { read: true, baseUnits: total };
+    try {
+        if (await reader.knowsCoinType(walType))
+            return { read: true, baseUnits: total };
+        return {
+            read: false,
+            why: "this chain does not know the WAL coin type this version of the tool was built with, so a zero balance here would mean nothing",
+        };
+    }
+    catch (error) {
+        // ⛔ A FAILED CHECK IS NOT A CONFIRMED ZERO. Reporting the zero anyway would be reporting a
+        //    number whose one supporting question went unanswered.
+        return { read: false, why: `the balance came back as zero and could not be confirmed: ${reasonOf(error)}` };
+    }
+}
+/**
+ * Base units as a person reads them — the exact value, never rounded.
+ *
+ * ⛔ NOT `toFixed`, NOT A SHORTENED FORM. A wallet holding 0.000000004 SUI is not holding "0.00",
+ *    and money that reads as zero when it is not is the one rounding error nobody forgives. The
+ *    fractional part is trimmed of trailing zeros only, which removes nothing that was there.
+ *
+ * Callers hand it a total the chain reported; a negative one is refused where it is read, so this
+ * never sees one.
+ */
+export function coinAmount(baseUnits) {
+    const whole = baseUnits / BASE_UNITS_PER_COIN;
+    const fraction = baseUnits % BASE_UNITS_PER_COIN;
+    if (fraction === 0n)
+        return whole.toString();
+    const digits = fraction.toString().padStart(BASE_UNIT_DIGITS, "0").replace(/0+$/, "");
+    return `${whole}.${digits}`;
+}

package/dist/walrus-write.js

@@ -0,0 +1,188 @@
+// The real Walrus protocol client — the ONE file in this tool that loads the storage network's SDK.
+//
+// ⛔ SPLIT OUT FROM `upload.ts` ON PURPOSE. That file decides what gets bought and when; this one
+//    only knows how to talk to the network. Keeping the SDK out of it is what lets `node --test`
+//    drive every spending decision, including all of its failure branches, against fakes.
+//
+// ⛔ THERE IS NO SIGNER HERE AND NOTHING IS BUILT AS A TRANSACTION. On the credit rail the server
+//    registers the blob and pays the relay's tip out of the treasury; this tool computes the id
+//    locally and hands over the bytes. The one thing it must get right is telling the relay WHICH
+//    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 { 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.
+import { epochStartedMs as readEpochStart } from "./shared/lib/extend/epochs.js";
+import { NmtsError } from "./errors.js";
+import { countingFetch } from "./progress.js";
+import { relayHost, suiRpcHost } from "./walrus.js";
+/**
+ * How long the relay gets for one blob PUT, sized to the body.
+ *
+ * The SDK's own default is 30 seconds, which a multi-megabyte body cannot finish on an ordinary
+ * connection — and a timeout here happens AFTER the storage is paid for.
+ */
+export function relayTimeoutMs(bodyBytes) {
+    const perMiB = 20_000;
+    const floor = 60_000;
+    return Math.max(floor, Math.ceil((bodyBytes / 2 ** 20) * perMiB));
+}
+/**
+ * ⛔ `sendTip` IS A FLAG HERE, NOT A BUDGET. The SDK decides whether to tell the relay which
+ *    transaction paid its tip by asking `!!config.uploadRelay.sendTip` — with the field absent it
+ *    sends the bytes WITHOUT the nonce and the transaction id, and the relay refuses them because
+ *    as far as it can tell nobody paid. On this rail the treasury already paid, inside the
+ *    register transaction; this tool holds no wallet and cannot pay anything whatever this number
+ *    says. It is a ceiling on a payment that has no way of happening.
+ *
+ * ⚠ Which also means it does NOT have to agree with the browser's ceiling, and no gate holds the
+ *   two level: the browser's number bounds a real payment made by a real wallet.
+ */
+const TIP_CEILING_UNUSED_MIST = 1;
+function extend(network, relayUrl, bodyBytes, onSent) {
+    const base = new SuiJsonRpcClient({
+        // ⛔ The network name reaches the SDK as well as the URL. A mirror pointed at the wrong chain
+        //    would otherwise be discovered as a blob the storage nodes refuse, after the money moved.
+        network: network === "mainnet" ? "mainnet" : "testnet",
+        url: suiRpcHost(network),
+    });
+    return base.$extend(walrus({
+        uploadRelay: {
+            host: relayUrl,
+            sendTip: { max: TIP_CEILING_UNUSED_MIST },
+            timeout: relayTimeoutMs(bodyBytes),
+            // ⛔ THE ONLY WAY TO SEE AN UPLOAD MOVE. The SDK does not report progress, and the relay
+            //    PUT is the one step of an upload that takes real time — a person watching a large
+            //    file with no feedback cannot tell a slow upload from a hung one, and neither can an
+            //    agent deciding whether to give up.
+            ...(onSent ? { fetch: countingFetch(onSent) } : {}),
+        },
+    }));
+}
+function fail(what, error) {
+    throw new NmtsError(`${what}: ${error instanceof Error ? error.message : String(error)}`);
+}
+/**
+ * Build a protocol client bound to ONE relay, for ONE upload of a known size.
+ *
+ * `onSent` is called as the request body leaves — that is the honest measure of an upload, and it
+ * is the only phase of one that anything can report on.
+ */
+export function createBlobProtocol(network, bodyBytes, onSent) {
+    const relayUrl = relayHost(network);
+    const client = extend(network, relayUrl, bodyBytes, onSent);
+    return {
+        relayUrl,
+        async computeMetadata({ bytes, nonce }) {
+            // ⛔ The shard count is NOT supplied. It is a property of the live storage network, the
+            //    erasure coding depends on it, and a number written down here would be right until the
+            //    day it was not — at which point every id this tool computed would be refused after the
+            //    credits had moved. The SDK reads it from the chain.
+            const meta = await client.walrus
+                .computeBlobMetadata({
+                bytes,
+                // Omitted rather than passed as undefined so the SDK's own "make a random one" path runs
+                // on a first encode; supplied on a retry so the digest reproduces bit for bit.
+                ...(nonce ? { nonce } : {}),
+            })
+                .catch((error) => fail("The storage network's encoder could not prepare this file", error));
+            return {
+                blobId: meta.blobId,
+                rootHash: meta.rootHash,
+                nonce: meta.nonce,
+                // The SDK hands this back as a thunk, because computing it costs a hash of the encoded
+                // blob. Awaited once here so nothing downstream has to know it was ever lazy.
+                blobDigest: await meta.blobDigest(),
+            };
+        },
+        async uploadToRelay({ blobId, bytes, nonce, registerTxDigest, blobObjectId }) {
+            const { certificate } = await client.walrus
+                .writeBlobToUploadRelay({
+                blobId,
+                blob: bytes,
+                nonce,
+                txDigest: registerTxDigest,
+                blobObjectId,
+                // Not a choice made here: the chain service hard-codes it and refuses a registration
+                // that says otherwise, so a different value would make the relay reject these bytes.
+                deletable: true,
+            })
+                .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"),
+            };
+        },
+    };
+}
+/**
+ * The storage network's current epoch, or `null` when it could not be read.
+ *
+ * ⚠ ADVISORY ONLY. It becomes the `expiry_epoch` the server records beside the file, which the
+ *   chain — not this number — is the authority on. `null` is written as 0, meaning "not recorded",
+ *   which is honest; inventing a number would put a date in the drive that nothing stands behind.
+ */
+export async function readCurrentEpoch(network) {
+    try {
+        const base = new SuiJsonRpcClient({
+            network: network === "mainnet" ? "mainnet" : "testnet",
+            url: suiRpcHost(network),
+        }).$extend(walrus({}));
+        // The epoch lives on the COMMITTEE, not beside it: the system state describes capacity and
+        // the deny lists as well, and only the committee is stamped with which epoch it serves.
+        const state = await base.walrus.systemState();
+        const epoch = state.committee.epoch;
+        return typeof epoch === "number" ? epoch : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The storage network's epoch clock: which epoch, how long one lasts, and when this one began.
+ *
+ * ⛔ THE EPOCH LENGTH IS READ, NEVER ASSUMED. It is one day on one network and fourteen on the
+ *    other, so a constant borrowed from either would turn "fourteen days left" into "196 days
+ *    left" on the wrong one — beside a sentence about a file being deleted.
+ *
+ * ⚠ `startedMs` is usually ABSENT and that is normal, not a failure: the network only carries the
+ *   moment an epoch settled while it is not changing epochs. Everything downstream treats its
+ *   absence as "the day count is a lower bound", which is the safe direction.
+ *
+ * `null` means the clock could not be read at all. ⛔ The caller must say so rather than draw a
+ * drive with nothing expiring — an unread clock and an account in no danger look identical from
+ * the outside and are the opposite of each other.
+ */
+export async function readEpochWindow(network) {
+    try {
+        const base = new SuiJsonRpcClient({
+            network: network === "mainnet" ? "mainnet" : "testnet",
+            url: suiRpcHost(network),
+        }).$extend(walrus({}));
+        const [system, staking] = await Promise.all([base.walrus.systemState(), base.walrus.stakingState()]);
+        // Both numbers can arrive as strings — Sui reports 64-bit values that way — so they are
+        // converted here and the constructor below refuses whatever did not survive it.
+        const epoch = system.committee.epoch;
+        const duration = staking.epoch_duration;
+        return epochClock(Number(epoch), Number(duration), readEpochStart(staking.epoch_state));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * When the current epoch began, or null.
+ *
+ * ⛔ THE NARROWING ITSELF IS NOT WRITTEN HERE (2026-08-25). It used to be, and it accepted a single
+ *    enum case while the network sits in a different one for nearly all of every epoch — so the
+ *    anchor was thrown away almost always and this tool reported "N days or more" where it could
+ *    have reported a date. The browser had the same bug in its own copy of the same judgement,
+ *    which is the point: two narrowings are two answers. It now lives beside the arithmetic that
+ *    depends on it, in the file both programs copy from.
+ *
+ * ⛔ STILL EXPORTED FROM HERE. `extend-chain.ts` reads the same state for a different reason and
+ *    imports this name; re-exporting keeps one import path for callers in this package.
+ */
+export { epochStartedMs } from "./shared/lib/extend/epochs.js";

package/dist/walrus.js

@@ -0,0 +1,156 @@
+// Reading bytes back from the Walrus storage network.
+//
+// ⛔ THE AGGREGATOR IS NOT TRUSTED, and nothing here pretends otherwise. Whatever these hosts hand
+//    back goes straight into the NCF-3 stream decryptor, which authenticates every chunk under the
+//    file's own key. A host that returns the wrong bytes — by mistake or on purpose — produces a
+//    decryption failure, never a quietly wrong file. What an aggregator CAN do is refuse to serve,
+//    or serve nothing, which is why more than one is listed.
+//
+// ⛔ THE HOST LIST IS WRITTEN IN THREE LANGUAGES and `deploy/check-walrus-hosts.mjs` set-compares
+//    them: here, the browser build, and the standalone recovery tool. One copy going stale shows
+//    up as "file not found", which reads as "the file is gone" — so the machine holds them level
+//    rather than a person remembering to.
+import { NmtsError } from "./errors.js";
+/** Curated Walrus aggregator (read) endpoints per network, preference order. */
+export const AGGREGATOR_HOSTS = {
+    testnet: ["https://aggregator.walrus-testnet.walrus.space"],
+    mainnet: ["https://aggregator.walrus-mainnet.walrus.space"],
+};
+/**
+ * Curated Walrus upload-relay (write) endpoints per network, preference order.
+ *
+ * ⛔ A RELAY IS NOT AN AGGREGATOR, and the difference is money. The relay is named inside the
+ *    register transaction the server pays a tip in, so the bytes have to go to the SAME host the
+ *    reservation was made for. That is why a write picks its host BEFORE the storage is bought and
+ *    then never moves: failing over to a second relay would push bytes nobody paid that relay for.
+ */
+export const RELAY_HOSTS = {
+    testnet: ["https://upload-relay.testnet.walrus.space"],
+    mainnet: ["https://upload-relay.mainnet.walrus.space"],
+};
+/**
+ * Sui JSON-RPC endpoints per network — public mirrors, because the official full nodes retired
+ * JSON-RPC on both networks (browser measurements 2026-07-29 testnet, 2026-08-03 mainnet).
+ *
+ * ⛔ READ-ONLY, AND NOT TRUSTED WITH ANYTHING. This tool asks one question here: how many shards
+ *    the storage network currently has, which the erasure coding needs. A wrong answer produces a
+ *    blob id the storage network refuses, so it fails loudly at the relay rather than quietly
+ *    storing something unreadable. No key is ever sent to one of these, and nothing is signed.
+ */
+export const SUI_RPC_HOSTS = {
+    testnet: "https://rpc-testnet.suiscan.xyz",
+    mainnet: "https://rpc-mainnet.suiscan.xyz",
+};
+/** How long one host gets before the next is tried. A read that stalls is a read that failed. */
+export const READ_TIMEOUT_MS = 60_000;
+/**
+ * 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 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 const RELAY_ENV_VAR = "NMTS_RELAY";
+/** Ask a different Sui JSON-RPC node the shard-count question. */
+export const SUI_RPC_ENV_VAR = "NMTS_SUI_RPC";
+/** The relay this run writes through: the environment's if it named one, else the network's. */
+export function relayHost(network) {
+    const named = process.env[RELAY_ENV_VAR]?.trim();
+    if (named)
+        return named;
+    const host = RELAY_HOSTS[network]?.[0];
+    if (host === undefined) {
+        throw new NmtsError(`No upload relay is known for the ${network} storage network.`, {
+            nextStep: `Name one in ${RELAY_ENV_VAR} to upload anyway.`,
+        });
+    }
+    return host;
+}
+/** The Sui JSON-RPC node this run asks about shard count. */
+export function suiRpcHost(network) {
+    const named = process.env[SUI_RPC_ENV_VAR]?.trim();
+    if (named)
+        return named;
+    const host = SUI_RPC_HOSTS[network];
+    if (host === undefined) {
+        throw new NmtsError(`No Sui RPC endpoint is known for the ${network} network.`, {
+            nextStep: `Name one in ${SUI_RPC_ENV_VAR} to upload anyway.`,
+        });
+    }
+    return host;
+}
+function fromEnvironment() {
+    const raw = process.env[AGGREGATOR_ENV_VAR];
+    if (raw === undefined)
+        return null;
+    const hosts = raw.split(",").map((h) => h.trim()).filter((h) => h !== "");
+    return hosts.length > 0 ? hosts : null;
+}
+function hostsFor(network, options) {
+    if (options.hosts !== undefined && options.hosts.length > 0)
+        return options.hosts;
+    const chosen = fromEnvironment();
+    if (chosen !== null)
+        return chosen;
+    const known = AGGREGATOR_HOSTS[network];
+    if (known === undefined) {
+        throw new NmtsError(`No storage-network hosts are known for "${network}".`, {
+            exitCode: 2,
+            nextStep: "Use --network mainnet or --network testnet.",
+        });
+    }
+    return known;
+}
+/**
+ * Fetch one stored object, trying each host in order.
+ *
+ * ⛔ It reports what it tried. A read that fails everywhere is either a blob that is gone, a
+ *    network that is wrong, or hosts that are all down, and those need different next steps — a
+ *    bare "not found" would send somebody looking for the wrong one.
+ */
+async function readFrom(network, pathOf, what, options) {
+    const hosts = hostsFor(network, options);
+    const tried = [];
+    for (const host of hosts) {
+        const url = pathOf(host.replace(/\/$/, ""));
+        const timer = AbortSignal.timeout(options.timeoutMs ?? READ_TIMEOUT_MS);
+        const signal = options.signal === undefined ? timer : AbortSignal.any([timer, options.signal]);
+        try {
+            const response = await fetch(url, { signal, redirect: "follow" });
+            if (!response.ok) {
+                tried.push(`${host} → ${response.status}`);
+                continue;
+            }
+            return new Uint8Array(await response.arrayBuffer());
+        }
+        catch (error) {
+            // ⛔ The reason is kept, not flattened to "failed". A timeout and a refused connection mean
+            //    different things, and the last host's reason is what the person reads.
+            tried.push(`${host} → ${error instanceof Error ? error.message : "no answer"}`);
+        }
+    }
+    throw new NmtsError(`${what} could not be read from the ${network} storage network.`, {
+        exitCode: 5,
+        nextStep: `Tried: ${tried.join(" · ")}. If every host answered 404, either the bytes are gone or ` +
+            `this is the wrong network — the same identifier does not exist on both.`,
+    });
+}
+/** Whole-blob read: `GET {aggregator}/v1/blobs/{blobId}`. */
+export function readBlob(network, blobId, options = {}) {
+    return readFrom(network, (host) => `${host}/v1/blobs/${encodeURIComponent(blobId)}`, `Blob ${blobId}`, options);
+}
+/**
+ * Quilt-patch read: `GET {aggregator}/v1/blobs/by-quilt-patch-id/{patchId}`.
+ *
+ * A quilt is one stored blob holding many small files; the patch id addresses one of them. Files
+ * under 64 MiB share a quilt, so this is the common path rather than the exotic one.
+ */
+export function readQuiltPatch(network, patchId, options = {}) {
+    return readFrom(network, (host) => `${host}/v1/blobs/by-quilt-patch-id/${encodeURIComponent(patchId)}`, `Quilt patch ${patchId}`, options);
+}