@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/wallet-swap-quote.js

@@ -0,0 +1,126 @@
+// A venue's answer, read from the chain: how much comes out now, what stays unused, and the fee the
+// quote's own numbers say the venue charges. ⛔ EVERYTHING HERE IS A READ — `devInspect`, no gas,
+// no key, no signature, and a zero address as the nominal sender so a quote needs no funded wallet.
+//
+// ⛔ THE ARITHMETIC IS THE BROWSER'S, copied byte-for-byte (`shared/lib/wallet/swap-rules.ts`); this
+//    file only asks the chain and hands the answers to it. DeepBook's fee has no constant: it is
+//    MEASURED by quoting the same amount with the fee taken from the input coin and again with the
+//    fee paid in DEEP, then comparing output per unit actually spent. Bluefin's quote reports its
+//    fee outright (`fee_amount` + `protocol_fee`; both parts count).
+//
+// ⛔ A FEE RATE THAT CANNOT BE MEASURED IS NULL, NEVER 0. A quote that cannot be read THROWS — the
+//    command says "this venue did not answer", never a number in its place. An output of 0 is an
+//    answer, not a failure: the amount is below one lot, or the book is empty.
+import { bcs } from "@mysten/sui/bcs";
+import { Transaction } from "@mysten/sui/transactions";
+import { deepbookRowFrom, feeRateBpsOf, measureDeepbookFeeBps, } from "./shared/lib/wallet/swap-rules.js";
+import { BLUEFIN_MAX_SQRT_PRICE, BLUEFIN_MIN_SQRT_PRICE, DEEPBOOK_PACKAGE_IDS, DEEPBOOK_WAL_SUI_POOLS, } from "./shared/lib/wallet/venue-ids.js";
+import { SUI_COIN_TYPE, walCoinType } from "./wallet.js";
+/** The zero address: a quote is a read, and a read needs no wallet. */
+export const QUOTE_SENDER = `0x${"0".repeat(64)}`;
+function readU64(value) {
+    return BigInt(bcs.U64.parse(Uint8Array.from(value[0])));
+}
+/**
+ * The FRONT of Bluefin's `SwapResult`, in the order its `pool.move` declares them. BCS reads from
+ * the front, so the fields behind these need not be known. The first three are checked against the
+ * question asked; if they do not echo it, the rest cannot be trusted either.
+ */
+const BluefinSwapResultPrefix = bcs.struct("BluefinSwapResultPrefix", {
+    a2b: bcs.bool(),
+    by_amount_in: bcs.bool(),
+    amount_specified: bcs.u64(),
+    amount_specified_remaining: bcs.u64(),
+    amount_calculated: bcs.u64(),
+    fee_growth_global: bcs.u128(),
+    fee_amount: bcs.u64(),
+    protocol_fee: bcs.u64(),
+});
+async function quoteBluefin(client, network, direction, amountInUnits, binding) {
+    const a2b = direction === "WAL_TO_SUI";
+    const tx = new Transaction();
+    tx.moveCall({
+        target: `${binding.packageId}::pool::calculate_swap_results`,
+        typeArguments: [walCoinType(network), SUI_COIN_TYPE],
+        arguments: [
+            tx.object(binding.poolId),
+            tx.pure.bool(a2b),
+            tx.pure.bool(true),
+            tx.pure.u64(amountInUnits),
+            tx.pure.u128(a2b ? BLUEFIN_MIN_SQRT_PRICE : BLUEFIN_MAX_SQRT_PRICE),
+        ],
+    });
+    const res = await client.devInspectTransactionBlock({ sender: QUOTE_SENDER, transactionBlock: tx });
+    if (res.error)
+        throw new Error(`the Bluefin quote was refused on chain: ${res.error}`);
+    const returned = res.results?.[0]?.returnValues;
+    const first = returned?.[0];
+    if (first === undefined)
+        throw new Error("the Bluefin quote came back with no value");
+    const result = BluefinSwapResultPrefix.parse(Uint8Array.from(first[0]));
+    if (result.a2b !== a2b || result.by_amount_in !== true || BigInt(result.amount_specified) !== amountInUnits) {
+        throw new Error("the Bluefin quote did not echo the question it was asked");
+    }
+    return {
+        venue: "bluefin",
+        outUnits: BigInt(result.amount_calculated),
+        feeRateBps: feeRateBpsOf(BigInt(result.fee_amount) + BigInt(result.protocol_fee), amountInUnits),
+        leftoverInUnits: BigInt(result.amount_specified_remaining),
+    };
+}
+async function quoteDeepbook(client, network, direction, amountInUnits) {
+    const pkg = DEEPBOOK_PACKAGE_IDS[network];
+    const pool = DEEPBOOK_WAL_SUI_POOLS[network];
+    const types = [walCoinType(network), SUI_COIN_TYPE];
+    const inputFeeFn = direction === "SUI_TO_WAL" ? "get_base_quantity_out_input_fee" : "get_quote_quantity_out_input_fee";
+    const deepModeArgs = direction === "SUI_TO_WAL" ? [0n, amountInUnits] : [amountInUnits, 0n];
+    const build = (withDeepMode) => {
+        const tx = new Transaction();
+        tx.moveCall({
+            target: `${pkg}::pool::${inputFeeFn}`,
+            typeArguments: types,
+            arguments: [tx.object(pool), tx.pure.u64(amountInUnits), tx.object.clock()],
+        });
+        if (withDeepMode) {
+            tx.moveCall({
+                target: `${pkg}::pool::get_quantity_out`,
+                typeArguments: types,
+                arguments: [tx.object(pool), tx.pure.u64(deepModeArgs[0]), tx.pure.u64(deepModeArgs[1]), tx.object.clock()],
+            });
+        }
+        return tx;
+    };
+    // Both modes in ONE inspection so they see the same book. If the DEEP-mode call is refused, the
+    // quote is asked again alone: what comes out matters more than what the fee was.
+    let res = await client.devInspectTransactionBlock({ sender: QUOTE_SENDER, transactionBlock: build(true) });
+    let deepModeAnswered = true;
+    if (res.error) {
+        deepModeAnswered = false;
+        res = await client.devInspectTransactionBlock({ sender: QUOTE_SENDER, transactionBlock: build(false) });
+    }
+    if (res.error)
+        throw new Error(`the DeepBook quote was refused on chain: ${res.error}`);
+    const rowOf = (values) => values !== undefined && values.length >= 3 && values[0] !== undefined && values[1] !== undefined
+        ? deepbookRowFrom(direction, readU64(values[0]), readU64(values[1]))
+        : null;
+    const inputMode = rowOf(res.results?.[0]?.returnValues);
+    if (inputMode === null)
+        throw new Error("the DeepBook quote came back in a shape this tool does not read");
+    const deepMode = deepModeAnswered ? rowOf(res.results?.[1]?.returnValues) : null;
+    return {
+        venue: "deepbook",
+        outUnits: inputMode.outUnits,
+        feeRateBps: measureDeepbookFeeBps(amountInUnits, inputMode, deepMode),
+        leftoverInUnits: inputMode.leftoverInUnits,
+    };
+}
+/** One venue's answer now. Bluefin needs its resolved binding; DeepBook needs nothing resolved. */
+export async function quoteVenue(client, network, venue, direction, amountInUnits, bluefin) {
+    if (amountInUnits <= 0n)
+        throw new Error("a swap quote needs an amount above zero");
+    if (venue === "deepbook")
+        return quoteDeepbook(client, network, direction, amountInUnits);
+    if (bluefin === null)
+        throw new Error("Bluefin's package was not resolved");
+    return quoteBluefin(client, network, direction, amountInUnits, bluefin);
+}

package/dist/wallet.d.ts

@@ -0,0 +1,135 @@
+import { type CryptoGlue } from "./crypto.ts";
+import type { Network } from "./network.ts";
+/**
+ * The wallet this NMTS key 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 declare const BUILT_IN_WALLET_INDEX = 0;
+/** The chain's own coin. Its type is fixed by the chain itself and takes no network. */
+export declare 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 declare const WAL_COIN_TYPES: Readonly<Record<Network, string>>;
+/** The WAL coin type for one network. */
+export declare function walCoinType(network: Network): string;
+/**
+ * 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 declare function addressFromSeed(seed: Uint8Array): string;
+/**
+ * The address of the wallet this NMTS key 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 declare function walletAddress(code: string): Promise<string>;
+/**
+ * The engine functions this module uses. Narrowed to the one it actually calls.
+ *
+ * ⛔ NOT A SEAM FOR REPLACING THE ENGINE. Every address this tool prints comes from the real
+ *    WebAssembly, and a fake derivation would only prove this file agrees with a fake. The narrow
+ *    type exists so a test can WRAP the real function and watch what was handed to it — which is
+ *    the only way the wiping below can be checked at all, and the wiping is the part that matters.
+ */
+export type WalletGlue = Pick<CryptoGlue, "wallet_seed_for">;
+/**
+ * The NMTS key 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 declare function addressFromDerived(glue: WalletGlue, derived: Uint8Array): string;
+/**
+ * How much of one coin an address holds, exactly as the chain reported it — or why nobody knows.
+ *
+ * ⛔ THE TWO CASES ARE DIFFERENT TYPES ON PURPOSE. A number with a "did it work" flag beside it is
+ *    a number somebody will read without checking the flag. This shape makes the check unavoidable.
+ */
+export type CoinBalance = {
+    readonly read: true;
+    readonly baseUnits: bigint;
+} | {
+    readonly read: false;
+    readonly why: string;
+};
+/** Both balances of one wallet, each answering for itself. */
+export interface WalletBalances {
+    readonly sui: CoinBalance;
+    readonly wal: CoinBalance;
+}
+/**
+ * The chain, as this tool needs it: two questions, no writing.
+ *
+ * ⛔ A SEAM, NOT AN OPTION. There is no flag that reaches it and no way to supply one from a
+ *    command line. It exists so the arithmetic and every failure branch below can be driven by
+ *    `node --test` — a test that needed a live chain could not run offline, would answer
+ *    differently every day, and could not produce a refusal on demand at all.
+ */
+export interface ChainReader {
+    /** Total held of one coin type, in base units. Throws, with the reason, when it cannot be read. */
+    totalOf(coinType: string): Promise<bigint>;
+    /**
+     * Has this chain heard of the coin type at all?
+     *
+     * ⛔ THE ONLY QUESTION THAT TELLS AN EMPTY WALLET FROM A COIN TYPE THIS BUILD HAS WRONG. Both
+     *    answer "0" to the balance question — see the note on `WAL_COIN_TYPES`.
+     */
+    knowsCoinType(coinType: string): Promise<boolean>;
+}
+/**
+ * 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 declare function readBalances(reader: ChainReader, walType: string): Promise<WalletBalances>;
+/**
+ * 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 declare function coinAmount(baseUnits: bigint): string;

package/dist/wallet.js

@@ -1,4 +1,4 @@
-// The wallet an account code derives: its address, and what a chain says it holds.
+// The wallet an NMTS key 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
@@ -19,7 +19,7 @@ import { assertUsableCode } from "./account.js";
 import { DERIVED, loadCrypto } from "./crypto.js";
 import { NmtsError } from "./errors.js";
 /**
- * The wallet this account code opens by itself.
+ * The wallet this NMTS key 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
@@ -83,7 +83,7 @@ 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 address of the wallet this NMTS key 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.
@@ -101,7 +101,7 @@ export async function walletAddress(code) {
         // ⛔ 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 });
+        throw new NmtsError("The NMTS key 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
@@ -116,7 +116,7 @@ export async function walletAddress(code) {
     }
 }
 /**
- * The built-in wallet's address, from a buffer the caller already holds.
+ * The NMTS key 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

package/dist/walrus-write.d.ts

@@ -0,0 +1,56 @@
+import { type EpochClock } from "./expiry.ts";
+import type { BlobProtocol } from "./upload-wire.ts";
+/**
+ * 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 declare function relayTimeoutMs(bodyBytes: number): number;
+/**
+ * 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 declare function createBlobProtocol(network: string, bodyBytes: number, onSent?: (sent: number, total: number) => void): BlobProtocol & {
+    relayUrl: string;
+};
+/**
+ * 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 declare function readCurrentEpoch(network: string): Promise<number | 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 declare function readEpochWindow(network: string): Promise<EpochClock | 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.ts";

package/dist/walrus-write.js

@@ -16,7 +16,8 @@ import { epochClock } from "./expiry.js";
 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";
+import { relayHost } from "./walrus.js";
+import { suiRpcTransport } from "./sui-rpc.js";
 /**
  * How long the relay gets for one blob PUT, sized to the body.
  *
@@ -45,7 +46,7 @@ function extend(network, relayUrl, bodyBytes, onSent) {
         // ⛔ 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),
+        transport: suiRpcTransport(network),
     });
     return base.$extend(walrus({
         uploadRelay: {
@@ -128,7 +129,7 @@ export async function readCurrentEpoch(network) {
     try {
         const base = new SuiJsonRpcClient({
             network: network === "mainnet" ? "mainnet" : "testnet",
-            url: suiRpcHost(network),
+            transport: suiRpcTransport(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.
@@ -159,7 +160,7 @@ export async function readEpochWindow(network) {
     try {
         const base = new SuiJsonRpcClient({
             network: network === "mainnet" ? "mainnet" : "testnet",
-            url: suiRpcHost(network),
+            transport: suiRpcTransport(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

package/dist/walrus.d.ts

@@ -0,0 +1,86 @@
+/** Curated Walrus aggregator (read) endpoints per network, preference order. */
+export declare const AGGREGATOR_HOSTS: Readonly<Record<string, readonly string[]>>;
+/**
+ * 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 declare const RELAY_HOSTS: Readonly<Record<string, readonly string[]>>;
+/**
+ * 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.
+ *
+ * ⭐ 2026-09-01 — a LIST per network, two operators, first-that-answers. It used to be one host,
+ *    and the testnet one was measured dead that morning: `rpc-testnet.suiscan.xyz` completes the
+ *    TCP handshake in 31 ms and then sends nothing for 12 seconds, three times running. It had
+ *    been that way for eleven days, so every `nmts` command that needed the shard count on testnet
+ *    simply stopped. Each host below answered `sui_getChainIdentifier` with the right value the
+ *    same morning, 8/8 on a burst.
+ */
+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";
+/** The relay this run writes through: the environment's if it named one, else the network's. */
+export declare function relayHost(network: string): string;
+/**
+ * Every Sui JSON-RPC node this run may ask, in order.
+ *
+ * ⛔ Naming one in the environment REPLACES the list rather than adding to it — the same rule the
+ *    aggregator override follows, and for the same reason: somebody who names a node is saying
+ *    *that one*, and quietly reaching a public mirror instead would send their traffic somewhere
+ *    they did not choose.
+ */
+export declare function suiRpcHosts(network: string): readonly string[];
+/** The node whose address gets RECORDED — the first one, since that is the one normally asked. */
+export declare function suiRpcHost(network: string): string;
+export interface ReadOptions {
+    /** Override the host list — for a development stack, or an aggregator somebody runs themselves. */
+    hosts?: readonly string[];
+    timeoutMs?: number;
+    signal?: AbortSignal | undefined;
+    /**
+     * Read only these bytes: inclusive start, EXCLUSIVE end. Absent reads the whole object.
+     *
+     * ⛔ IT IS A REQUEST, NOT A GUARANTEE. An aggregator is free to ignore `Range` and answer 200
+     *    with everything, so what comes back is cut to the asked-for length here. Without that cut
+     *    the one caller that uses this — the rebuild's 72-byte key check — would quietly become a
+     *    download of the whole account.
+     */
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+/** Whole-blob read: `GET {aggregator}/v1/blobs/{blobId}`. */
+export declare function readBlob(network: string, blobId: string, options?: ReadOptions): Promise<Uint8Array>;
+/**
+ * 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 declare function readQuiltPatch(network: string, patchId: string, options?: ReadOptions): Promise<Uint8Array>;

package/dist/walrus.js

@@ -36,10 +36,17 @@ export const RELAY_HOSTS = {
  *    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.
+ *
+ * ⭐ 2026-09-01 — a LIST per network, two operators, first-that-answers. It used to be one host,
+ *    and the testnet one was measured dead that morning: `rpc-testnet.suiscan.xyz` completes the
+ *    TCP handshake in 31 ms and then sends nothing for 12 seconds, three times running. It had
+ *    been that way for eleven days, so every `nmts` command that needed the shard count on testnet
+ *    simply stopped. Each host below answered `sui_getChainIdentifier` with the right value the
+ *    same morning, 8/8 on a burst.
  */
 export const SUI_RPC_HOSTS = {
-    testnet: "https://rpc-testnet.suiscan.xyz",
-    mainnet: "https://rpc-mainnet.suiscan.xyz",
+    testnet: ["https://sui-testnet-rpc.publicnode.com", "https://testnet.suiet.app"],
+    mainnet: ["https://rpc-mainnet.suiscan.xyz", "https://sui-rpc.publicnode.com"],
 };
 /** 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;
@@ -72,18 +79,29 @@ export function relayHost(network) {
     }
     return host;
 }
-/** The Sui JSON-RPC node this run asks about shard count. */
-export function suiRpcHost(network) {
+/**
+ * Every Sui JSON-RPC node this run may ask, in order.
+ *
+ * ⛔ Naming one in the environment REPLACES the list rather than adding to it — the same rule the
+ *    aggregator override follows, and for the same reason: somebody who names a node is saying
+ *    *that one*, and quietly reaching a public mirror instead would send their traffic somewhere
+ *    they did not choose.
+ */
+export function suiRpcHosts(network) {
     const named = process.env[SUI_RPC_ENV_VAR]?.trim();
     if (named)
-        return named;
-    const host = SUI_RPC_HOSTS[network];
-    if (host === undefined) {
+        return [named];
+    const hosts = SUI_RPC_HOSTS[network];
+    if (hosts === undefined || hosts.length === 0) {
         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;
+    return hosts;
+}
+/** The node whose address gets RECORDED — the first one, since that is the one normally asked. */
+export function suiRpcHost(network) {
+    return suiRpcHosts(network)[0] ?? "";
 }
 function fromEnvironment() {
     const raw = process.env[AGGREGATOR_ENV_VAR];
@@ -122,12 +140,24 @@ async function readFrom(network, pathOf, what, options) {
         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" });
+            const response = await fetch(url, { signal, redirect: "follow", ...headersFor(options) });
             if (!response.ok) {
                 tried.push(`${host} → ${response.status}`);
                 continue;
             }
-            return new Uint8Array(await response.arrayBuffer());
+            const body = new Uint8Array(await response.arrayBuffer());
+            const range = options.range;
+            if (range === undefined)
+                return body;
+            const want = range.end - range.start;
+            // A 206 already holds exactly the asked-for bytes; a 200 holds the object from byte zero.
+            if (body.length === want)
+                return body;
+            if (body.length < range.end) {
+                tried.push(`${host} → answered ${body.length} bytes for a ${want}-byte range`);
+                continue;
+            }
+            return body.subarray(range.start, range.end);
         }
         catch (error) {
             // ⛔ The reason is kept, not flattened to "failed". A timeout and a refused connection mean
@@ -141,6 +171,14 @@ async function readFrom(network, pathOf, what, options) {
             `this is the wrong network — the same identifier does not exist on both.`,
     });
 }
+/** The `Range` header for a partial read, or nothing at all for a whole one. */
+function headersFor(options) {
+    const range = options.range;
+    if (range === undefined)
+        return {};
+    // HTTP ranges are inclusive at both ends; this one is exclusive at the end.
+    return { headers: { Range: `bytes=${range.start}-${range.end - 1}` } };
+}
 /** 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);

package/dist/zstd-node.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Make this program able to write and read compression flag 0x02. Safe to call more than once.
+ *
+ * ⛔ CALLED FROM THE FILE-LIST FLOW RATHER THAN FROM THE ENTRY POINT, and that is deliberate: the
+ *    package is a library and an MCP server as well as a command, and a list opened through any of
+ *    those doors has to be able to expand a zstd frame the browser wrote. Putting it here also
+ *    means `nmts --help` never loads it.
+ */
+export declare function registerNodeZstd(): void;
+/** For tests that need this process to look like a build with no encoder. */
+export declare function forgetNodeZstd(): void;