@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/upload.d.ts

@@ -0,0 +1,18 @@
+import { type Reservation } from "./upload-store.ts";
+import { type PaidPart, type UploadInput, type UploadResult } from "./upload-wire.ts";
+export * from "./upload-wire.ts";
+/**
+ * Buy storage for ONE PART, put its bytes on the network, and stop there.
+ *
+ * ⛔ IT DOES NOT MAKE A FILE. Committing is one act for the whole file — `commitItem` names every
+ *    part at once — and a part that returns from here is bought, filled and certified storage that
+ *    nothing in the account can see yet. Splitting it this way is what lets a file be larger than
+ *    memory: the parts are bought one at a time, each written down before its own money moves.
+ *
+ * ⛔ IT DOES NOT WRITE THE FILE LIST either. That is the caller's step, and it must happen before
+ *    the records are cleared — a committed file the list does not name is invisible and, to the
+ *    person, indistinguishable from one that never uploaded.
+ */
+export declare function buyAndPushPart(input: UploadInput): Promise<PaidPart>;
+/** What the file list must record about this upload. Always from the record, never from a run. */
+export declare function entryOf(record: Reservation): UploadResult["entry"];

package/dist/upload.js

@@ -59,6 +59,15 @@ export async function buyAndPushPart(input) {
     //    file splits some other way would file storage under the wrong position in the file. It
     //    happens for one ordinary reason — the same file put again with a different part size — so
     //    it is said plainly rather than left to fail later as an unreadable download.
+    if (existing?.paidFrom === "wallet") {
+        throw new UploadError({
+            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.",
+        });
+    }
     if (existing !== null) {
         const record = existing;
         if (record.partIndex !== input.part.index || record.partTotal !== input.part.total) {
@@ -184,6 +193,7 @@ export async function buyAndPushPart(input) {
             // on are the same sealed bytes.
             size: sealed.length,
             epochs: input.epochs,
+            deposit_credits: input.depositCredits,
             relay: {
                 host: input.relayUrl,
                 blob_digest_b64: Buffer.from(meta.blobDigest).toString("base64url"),

package/dist/usage-report.d.ts

@@ -0,0 +1,35 @@
+import { type ManifestIndex } from "./drive-paths.ts";
+/** How many of the largest files a report carries. */
+export declare const BIGGEST_SHOWN = 5;
+/** One of the largest files, with enough to go and fetch it. */
+export interface BiggestFile {
+    id: string;
+    name: string;
+    /** The whole path, exactly as `ls` prints it and `get` accepts it. */
+    path: string;
+    size: number;
+}
+export interface UsageReport {
+    /** Live files. Folders hold nothing, so they are not in this. */
+    files: number;
+    /** Live folders. */
+    folders: number;
+    /** Plaintext bytes of the live files. */
+    bytes: number;
+    /** Files sitting in the trash — still stored, still paid for. */
+    trashedFiles: number;
+    /** Plaintext bytes held by those — the figure that explains "deleting did not free anything". */
+    trashedBytes: number;
+    /** The largest live files, largest first. At most `BIGGEST_SHOWN` of them. */
+    biggest: BiggestFile[];
+}
+/**
+ * The whole report, in one pass over the list.
+ *
+ * The counts come from the same `totalsOf` the browser's own usage figures are built on — this
+ * package carries that module as a byte-for-byte copy — so the two cannot drift into disagreeing
+ * about what "in the trash" means. Being in the trash is INHERITED: a file under a trashed folder
+ * is trashed even though nothing marked the file itself, and a count that read only the file's own
+ * mark would report bytes as live that the server has already stopped serving.
+ */
+export declare function computeUsage(index: ManifestIndex): UsageReport;

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

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

package/dist/wallet-activity-chain.js

@@ -0,0 +1,31 @@
+// The live read behind `nmts wallet activity`: the chain's two lists for one address.
+//
+// ⛔ READ ONLY. The same JSON-RPC client `wallet-chain.ts` reads balances with; nothing here builds
+//    or signs a transaction. Imported lazily, only when no seam was supplied.
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import { FETCH_PER_DIRECTION } from "./commands/wallet-activity.js";
+import { suiRpcTransport } from "./sui-rpc.js";
+/** How long the two questions get together. A read that stalls is a read that failed. */
+export const ACTIVITY_TIMEOUT_MS = 20_000;
+export async function queryActivity(network, address) {
+    const client = new SuiJsonRpcClient({ network, transport: suiRpcTransport(network) });
+    const options = { showBalanceChanges: true, showInput: true, showEffects: true };
+    const signal = AbortSignal.timeout(ACTIVITY_TIMEOUT_MS);
+    const [sent, received] = await Promise.all([
+        client.queryTransactionBlocks({
+            filter: { FromAddress: address },
+            options,
+            limit: FETCH_PER_DIRECTION,
+            order: "descending",
+            signal,
+        }),
+        client.queryTransactionBlocks({
+            filter: { ToAddress: address },
+            options,
+            limit: FETCH_PER_DIRECTION,
+            order: "descending",
+            signal,
+        }),
+    ]);
+    return { sent: sent.data, received: received.data };
+}

package/dist/wallet-chain.d.ts

@@ -0,0 +1,19 @@
+import type { Network } from "./network.ts";
+import type { ChainReader } from "./wallet.ts";
+/**
+ * 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 declare const BALANCE_TIMEOUT_MS = 20000;
+/**
+ * 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 declare function chainReader(network: Network, address: string): ChainReader;

package/dist/wallet-chain.js

@@ -11,7 +11,7 @@
 //    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";
+import { suiRpcTransport } from "./sui-rpc.js";
 /**
  * How long one balance question gets.
  *
@@ -31,7 +31,7 @@ export const BALANCE_TIMEOUT_MS = 20_000;
 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) });
+    const client = new SuiJsonRpcClient({ network, transport: suiRpcTransport(network) });
     return {
         async totalOf(coinType) {
             const { totalBalance } = await client.getBalance({

package/dist/wallet-grant.d.ts

@@ -0,0 +1,50 @@
+export declare const WALLET_SCOPES: readonly ["storage", "all"];
+export type WalletScope = (typeof WALLET_SCOPES)[number];
+/** What a signature is for. `donate` is deliberately not here: no grant reaches a gift. */
+export type WalletAction = "extend" | "seal" | "reshape" | "exchange" | "send" | "give";
+/** The ceiling on any grant's length. The browser's standing approval has the same one. */
+export declare const MAX_GRANT_DAYS = 30;
+export interface WalletGrant {
+    scope: WalletScope;
+    grantedAt: string;
+    expiresAt: string;
+    byVersion: string;
+    /** Ceilings in base units, as strings (a JSON number would round them). `null` = no ceiling. */
+    capWalFrost: string | null;
+    capSuiMist: string | null;
+    /** What this tool has signed away under this grant, in base units. */
+    spentWalFrost: string;
+    spentSuiMist: string;
+}
+export interface Spend {
+    walFrost: bigint;
+    suiMist: bigint;
+}
+/** A decimal coin amount ("1.25") as base units. Nine decimals, like the chain. */
+export declare function parseCoinAmount(text: string, what: string): bigint;
+export declare function scopeCovers(scope: WalletScope, action: WalletAction): boolean;
+/** Turn what was typed into a grant, or refuse with the line to correct. Nothing is written. */
+export declare function parseWalletGrant(input: {
+    days?: string | undefined;
+    until?: string | undefined;
+    scope?: string | undefined;
+    capWal?: string | undefined;
+    capSui?: string | undefined;
+}, now: Date, version: string): WalletGrant;
+/** The grant on this machine, or null — an older bare-date record, or a malformed one, is null. */
+export declare function readWalletGrant(): WalletGrant | null;
+export declare function writeWalletGrant(grant: WalletGrant): void;
+export type GrantState = "none" | "expired" | "active";
+export declare function walletGrantState(grant: WalletGrant | null, now: Date): GrantState;
+/** What is left under a ceiling, or null when there is none. */
+export declare function roomLeft(cap: string | null, spent: string): bigint | null;
+/**
+ * Stop unless an active grant covers this signature and its amount, and say what would.
+ *
+ * ⛔ THE MESSAGE IS THE PRODUCT HERE, as with every other agreement: what happens, what can go
+ *    wrong, what is not covered, and the one command that agrees — and, new for this key, the
+ *    three things the grant carries.
+ */
+export declare function requireWalletGrant(action: WalletAction, spend: Spend, now: Date): WalletGrant;
+/** Add what was just signed to the grant's ledger. Called after a signature, never before. */
+export declare function recordWalletSpend(spend: Spend): void;

package/dist/wallet-grant.js

@@ -0,0 +1,218 @@
+// The `wallet` agreement with a SCOPE, an EXPIRY and, if the person wants one, a SPENDING CEILING.
+//
+// ⛔ WHY THE PLAIN "ONCE PER MACHINE, FOREVER" GRANT WAS NOT ENOUGH HERE. Every other agreement in
+//    this tool is about a capability whose cost is bounded by something else — credits by the
+//    server's ceilings, a share by the file it names. A wallet has no such bound: whatever is in it
+//    can leave in one signature, and an agent in `mode auto` that could grant an open-ended wallet
+//    agreement could give ITSELF unlimited, indefinite spending. So this one grant carries three
+//    things the others do not, in the same file, under the same key:
+//      · a scope — `storage` (extending a file's lease, paying for a file's storage) or `all`
+//        (also exchanging and sending). A gift is in neither: a person approves every gift.
+//      · an expiry — never more than 30 days away. The browser's standing approval has the same
+//        ceiling, for the same reason: a grant nobody remembers giving should run out on its own.
+//      · optionally a ceiling per coin. What this tool signs under the grant is added up here,
+//        and a signature that would pass the ceiling is refused BEFORE it is made.
+//
+// ⛔ AN OLDER RECORD WITHOUT AN EXPIRY COUNTS AS NO GRANT. Versions before this one wrote the wallet
+//    agreement as a bare date. Reading that as "agreed to everything, forever" would be the exact
+//    grant this file exists to make impossible, so it is asked for again — with the new words.
+//
+// ⚠ THE LEDGER IS THIS MACHINE'S. It counts what THIS tool signed under THIS grant. The wallet can
+//   be spent from elsewhere with the same NMTS key, and nothing here can see that.
+import { NmtsError } from "./errors.js";
+import { readConsentRecords, writeConsentRecords } from "./consent.js";
+import { BINARY_NAME, SUPPORT_EMAIL } from "./product.js";
+import { coinAmount } from "./wallet.js";
+export const WALLET_SCOPES = ["storage", "all"];
+const SCOPE_ACTIONS = {
+    storage: ["extend", "seal", "reshape"],
+    all: ["extend", "seal", "reshape", "exchange", "send", "give"],
+};
+/** The ceiling on any grant's length. The browser's standing approval has the same one. */
+export const MAX_GRANT_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** A decimal coin amount ("1.25") as base units. Nine decimals, like the chain. */
+export function parseCoinAmount(text, what) {
+    const m = /^(\d+)(?:\.(\d{1,9}))?$/.exec(text.trim());
+    if (m === null || m[1] === undefined) {
+        throw new NmtsError(`${what} must be a number of coins, like 12 or 0.5.`, { exitCode: 2 });
+    }
+    return BigInt(m[1]) * 1000000000n + BigInt((m[2] ?? "").padEnd(9, "0"));
+}
+export function scopeCovers(scope, action) {
+    return SCOPE_ACTIONS[scope].includes(action);
+}
+/** Turn what was typed into a grant, or refuse with the line to correct. Nothing is written. */
+export function parseWalletGrant(input, now, version) {
+    const scope = input.scope ?? "storage";
+    if (!WALLET_SCOPES.includes(scope)) {
+        throw new NmtsError(`--scope must be one of: ${WALLET_SCOPES.join(" · ")}.`, {
+            exitCode: 2,
+            nextStep: "storage = extending a file's lease and paying for a file's storage. all = also exchanging and sending. A gift is in neither.",
+        });
+    }
+    let expiresMs;
+    if (input.until !== undefined) {
+        const at = Date.parse(input.until);
+        if (!Number.isFinite(at)) {
+            throw new NmtsError("--until must be a date, like 2026-09-30 or 2026-09-30T12:00Z.", { exitCode: 2 });
+        }
+        expiresMs = at;
+    }
+    else if (input.days !== undefined) {
+        const days = Number(input.days);
+        if (!Number.isInteger(days) || days < 1) {
+            throw new NmtsError("--days must be a whole number of days, at least 1.", { exitCode: 2 });
+        }
+        expiresMs = now.getTime() + days * DAY_MS;
+    }
+    else {
+        throw new NmtsError("A wallet agreement needs an expiry: say how long it lasts.", {
+            exitCode: 2,
+            nextStep: `\`${BINARY_NAME} unlock wallet --days 7\` (up to ${MAX_GRANT_DAYS}), or --until <date>. ` +
+                `Add --scope storage|all (default storage) and, if you want a ceiling, --cap-wal <coins> --cap-sui <coins>.`,
+        });
+    }
+    const ceiling = now.getTime() + MAX_GRANT_DAYS * DAY_MS;
+    if (expiresMs <= now.getTime()) {
+        throw new NmtsError("That expiry is already in the past.", { exitCode: 2 });
+    }
+    if (expiresMs > ceiling) {
+        throw new NmtsError(`A wallet agreement lasts at most ${MAX_GRANT_DAYS} days.`, {
+            exitCode: 2,
+            nextStep: `Grant it again when it runs out. That is the point: a grant nobody remembers giving should run out on its own.`,
+        });
+    }
+    return {
+        scope: scope,
+        grantedAt: now.toISOString(),
+        expiresAt: new Date(expiresMs).toISOString(),
+        byVersion: version,
+        capWalFrost: input.capWal === undefined ? null : parseCoinAmount(input.capWal, "--cap-wal").toString(),
+        capSuiMist: input.capSui === undefined ? null : parseCoinAmount(input.capSui, "--cap-sui").toString(),
+        spentWalFrost: "0",
+        spentSuiMist: "0",
+    };
+}
+function isScope(value) {
+    return typeof value === "string" && WALLET_SCOPES.includes(value);
+}
+/** The grant on this machine, or null — an older bare-date record, or a malformed one, is null. */
+export function readWalletGrant() {
+    const raw = readConsentRecords()["wallet"];
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const at = (name) => Reflect.get(raw, name);
+    const scope = at("scope");
+    const grantedAt = at("grantedAt");
+    const expiresAt = at("expiresAt");
+    const byVersion = at("byVersion");
+    if (!isScope(scope) || typeof grantedAt !== "string" || typeof expiresAt !== "string" || typeof byVersion !== "string") {
+        return null;
+    }
+    const units = (name) => {
+        const v = at(name);
+        return typeof v === "string" && /^\d+$/.test(v) ? v : null;
+    };
+    return {
+        scope,
+        grantedAt,
+        expiresAt,
+        byVersion,
+        capWalFrost: units("capWalFrost"),
+        capSuiMist: units("capSuiMist"),
+        spentWalFrost: units("spentWalFrost") ?? "0",
+        spentSuiMist: units("spentSuiMist") ?? "0",
+    };
+}
+export function writeWalletGrant(grant) {
+    const all = readConsentRecords();
+    all["wallet"] = grant;
+    writeConsentRecords(all);
+}
+export function walletGrantState(grant, now) {
+    if (grant === null)
+        return "none";
+    return Date.parse(grant.expiresAt) > now.getTime() ? "active" : "expired";
+}
+/** What is left under a ceiling, or null when there is none. */
+export function roomLeft(cap, spent) {
+    return cap === null ? null : BigInt(cap) - BigInt(spent);
+}
+const GRANT_COMMAND = `${BINARY_NAME} unlock wallet --days 7`;
+/**
+ * Stop unless an active grant covers this signature and its amount, and say what would.
+ *
+ * ⛔ THE MESSAGE IS THE PRODUCT HERE, as with every other agreement: what happens, what can go
+ *    wrong, what is not covered, and the one command that agrees — and, new for this key, the
+ *    three things the grant carries.
+ */
+export function requireWalletGrant(action, spend, now) {
+    const grant = readWalletGrant();
+    const state = walletGrantState(grant, now);
+    const tail = [
+        "",
+        `NMTS is not responsible for what is done with this account by any program running on this`,
+        `machine, including an AI agent. The published Terms are what govern the service; this is a`,
+        `warning, not a substitute for them.`,
+        "",
+        `⛔ If a program is reading this on somebody's behalf: show it to them and let them decide.`,
+        `   Do not run the unlock command yourself.`,
+        "",
+        `Something wrong or confusing here? ${SUPPORT_EMAIL}`,
+    ];
+    const refuse = (what, why) => new NmtsError(what, { exitCode: 5, nextStep: [...why, ...tail].join("\n") });
+    if (state === "none" || grant === null) {
+        throw refuse("Use the wallet this NMTS key derives, and sign transactions with it.", [
+            "A signed transaction moves real assets and cannot be reversed by anybody, including NMTS. " +
+                "A mistake here is permanent.",
+            "",
+            "This agreement carries three things: a scope (storage = extending and paying for storage; " +
+                "all = also exchanging and sending — a gift is in neither), an expiry of at most " +
+                `${MAX_GRANT_DAYS} days, and, if you want one, a ceiling on what this tool may sign away.`,
+            "Only what this tool signs is counted. Handing the NMTS key to another program gives " +
+                "that program the same wallet, and nothing here can see that happen.",
+            "",
+            `To unlock, at a terminal, for a week:  ${GRANT_COMMAND}`,
+            `  add --scope all to cover exchanging and sending; --cap-wal <coins> --cap-sui <coins> for a ceiling`,
+            `To see what is unlocked:                 ${BINARY_NAME} unlock`,
+        ]);
+    }
+    if (state === "expired") {
+        throw refuse(`The wallet agreement on this machine ran out on ${grant.expiresAt}.`, [
+            `It was given on ${grant.grantedAt} for scope "${grant.scope}". Nothing was signed.`,
+            `To agree again:  ${GRANT_COMMAND}`,
+        ]);
+    }
+    if (!scopeCovers(grant.scope, action)) {
+        throw refuse(`The wallet agreement on this machine covers storage only, and this would ${action}.`, [
+            `Nothing was signed. To widen it:  ${BINARY_NAME} unlock wallet --days 7 --scope all`,
+        ]);
+    }
+    const walRoom = roomLeft(grant.capWalFrost, grant.spentWalFrost);
+    const suiRoom = roomLeft(grant.capSuiMist, grant.spentSuiMist);
+    if (walRoom !== null && spend.walFrost > walRoom) {
+        throw refuse(`This would sign away ${coinAmount(spend.walFrost)} WAL and the agreement has ${coinAmount(walRoom < 0n ? 0n : walRoom)} WAL left under its ceiling.`, [
+            `Ceiling ${coinAmount(BigInt(grant.capWalFrost ?? "0"))} WAL, of which ${coinAmount(BigInt(grant.spentWalFrost))} WAL is already signed away since ${grant.grantedAt}. Nothing was signed.`,
+            `To raise it, agree again with a higher --cap-wal, or without one.`,
+        ]);
+    }
+    if (suiRoom !== null && spend.suiMist > suiRoom) {
+        throw refuse(`This would spend about ${coinAmount(spend.suiMist)} SUI in fees and the agreement has ${coinAmount(suiRoom < 0n ? 0n : suiRoom)} SUI left under its ceiling.`, [
+            `Ceiling ${coinAmount(BigInt(grant.capSuiMist ?? "0"))} SUI, of which ${coinAmount(BigInt(grant.spentSuiMist))} SUI is already counted since ${grant.grantedAt}. Nothing was signed.`,
+            `To raise it, agree again with a higher --cap-sui, or without one.`,
+        ]);
+    }
+    return grant;
+}
+/** Add what was just signed to the grant's ledger. Called after a signature, never before. */
+export function recordWalletSpend(spend) {
+    const grant = readWalletGrant();
+    if (grant === null)
+        return;
+    writeWalletGrant({
+        ...grant,
+        spentWalFrost: (BigInt(grant.spentWalFrost) + spend.walFrost).toString(),
+        spentSuiMist: (BigInt(grant.spentSuiMist) + spend.suiMist).toString(),
+    });
+}

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

@@ -0,0 +1,24 @@
+import { Transaction } from "@mysten/sui/transactions";
+import type { Network } from "./network.ts";
+import type { SendCoin } from "./shared/lib/wallet/send-rules.ts";
+import { type WalletBalances } from "./wallet.ts";
+export interface TransferShape {
+    coin: SendCoin;
+    amountBaseUnits: bigint;
+    /** A full, validated Sui address. */
+    destination: string;
+    /** The WAL coin type of the network (unused for SUI). */
+    walType: string;
+    /** A gas ceiling, or undefined to let the SDK set one from its own dry run. */
+    gasBudgetMist?: bigint | undefined;
+}
+export declare function transferTransaction(input: TransferShape & {
+    sender: string;
+}): Transaction;
+/** What `commands/wallet-send.ts` reads before it prints a review. */
+export interface SendReads {
+    readWallet(address: string): Promise<WalletBalances>;
+    /** The fee in MIST measured by dry-running this exact transfer, or null when it could not be. */
+    estimateFee(shape: TransferShape, sender: string): Promise<bigint | null>;
+}
+export declare function sendReads(network: Network): SendReads;

package/dist/wallet-send-chain.js

@@ -0,0 +1,49 @@
+// The transfer transaction and its live reads: the wallet's balances and the fee a dry run measures.
+//
+// ⛔ ONE BUILDER FOR THE FEE AND THE SIGNATURE. `estimateTransferFee` and `wallet-sign.ts` both call
+//    `transferTransaction`, so the fee printed is the fee of the transaction that is then signed. Two
+//    builders would let a screen price one transaction and approve another.
+//
+// ⛔ THE TWO COINS MOVE DIFFERENTLY, and the difference is not cosmetic: SUI is split off the gas
+//    coin the transaction is already paying with; WAL is a separate coin type gathered from the
+//    wallet's own WAL coins, and the gas is still SUI. The browser's `withdrawFromEmbedded` does the
+//    same two things.
+import { coinWithBalance, Transaction } from "@mysten/sui/transactions";
+import { walrusClient, netGasFee } from "./extend-chain.js";
+import { readBalances, walCoinType } from "./wallet.js";
+import { chainReader } from "./wallet-chain.js";
+export function transferTransaction(input) {
+    const tx = new Transaction();
+    tx.setSender(input.sender);
+    if (input.coin === "SUI") {
+        const [sui] = tx.splitCoins(tx.gas, [input.amountBaseUnits]);
+        tx.transferObjects([sui], input.destination);
+    }
+    else {
+        const wal = tx.add(coinWithBalance({ balance: input.amountBaseUnits, type: input.walType }));
+        tx.transferObjects([wal], input.destination);
+    }
+    if (input.gasBudgetMist !== undefined)
+        tx.setGasBudget(input.gasBudgetMist);
+    return tx;
+}
+export function sendReads(network) {
+    const client = walrusClient(network);
+    return {
+        async readWallet(address) {
+            return readBalances(chainReader(network, address), walCoinType(network));
+        },
+        async estimateFee(shape, sender) {
+            try {
+                const bytes = await transferTransaction({ ...shape, sender }).build({ client });
+                const { effects } = await client.dryRunTransactionBlock({ transactionBlock: bytes });
+                if (effects.status.status !== "success")
+                    return null;
+                return netGasFee(effects.gasUsed);
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}

package/dist/wallet-sign.d.ts

@@ -0,0 +1,133 @@
+import type { SignExtension } from "./extend-plan.ts";
+import { type TransferShape } from "./wallet-send-chain.ts";
+import { type StorageOpShape } from "./storage-control-chain.ts";
+import { type SwapShape } from "./wallet-swap-chain.ts";
+import type { Network } from "./network.ts";
+import type { RegisterShape } from "./upload-wallet-plan.ts";
+import type { Certificate } from "./upload-wire.ts";
+/**
+ * The address this tool would sign as.
+ *
+ * ⛔ IT EXISTS TO BE HELD AGAINST `walletAddress`. That function is what `nmts wallet address`
+ *    prints and what somebody funds; this one is what a transaction would actually be signed by.
+ *    Nothing else in this package proves the two are the same wallet, and the failure if they ever
+ *    part is silent — a signature from an address with nothing in it, or worse, money sent to an
+ *    address that signs nothing. A test compares them, offline, for free.
+ */
+export declare function signerAddress(code: string): Promise<string>;
+/**
+ * Extend every listed blob by `epochs`, in ONE transaction, signed by the account's own wallet.
+ *
+ * ONE SIGNATURE FOR ALL OF IT: `extendBlob` returns a transaction fragment, so every blob a file
+ * sits on goes into the same transaction. A multi-part file is one payment and one gas fee, not
+ * five — and a partial extension would buy nothing, because one expired blob is enough to make the
+ * file unreadable.
+ *
+ * ⛔ THE IDS ARE DE-DUPLICATED. Naming the same blob twice pays for the same epochs twice.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED. A refusal from the node, a timeout, a
+ *   connection that dropped after the bytes went out — none of them say whether the transaction
+ *   was executed. The caller re-reads the chain rather than offering a second attempt against
+ *   numbers it read before.
+ */
+export declare const signExtension: SignExtension;
+/**
+ * Send SUI or WAL to one address, in ONE transaction, signed by the account's own wallet.
+ *
+ * ⛔ THE TRANSACTION IS BUILT BY `wallet-send-chain.ts`, the same builder the fee was measured
+ *    with, so what is signed is what was priced. The destination is whatever the caller validated
+ *    (`send-rules.ts`) — nothing here checks it again, and nothing can take it back.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED — the same words as the extension above.
+ */
+export declare const signTransfer: SignTransfer;
+/**
+ * Sign one short message with the account's own wallet. NOT a transaction: nothing moves.
+ *
+ * ⛔ THE MESSAGE IS THE CALLER'S, WHOLE AND UNCHANGED — the server rebuilds the same bytes from
+ *    the fields it was sent, so a byte added here would invalidate every signature this tool
+ *    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 declare const signMessage: SignMessage;
+/** The seam `commands/wallet-hall.ts` signs through. Returns the base64 signature, nothing else. */
+export type SignMessage = (input: {
+    /** ⛔ The NMTS key. It never leaves this machine: it derives the wallet and nothing else. */
+    code: string;
+    message: string;
+}) => Promise<string>;
+/** The seam `commands/wallet-send.ts` signs through. Returns the transaction digest. */
+export type SignTransfer = (input: {
+    network: string;
+    /** ⛔ The NMTS key. It never leaves this machine: it derives the wallet and nothing else. */
+    code: string;
+    shape: TransferShape;
+}) => Promise<string>;
+/**
+ * Swap SUI for WAL or WAL for SUI on the named venue, in ONE transaction, signed by the account's
+ * own wallet. Every output goes back to the signer — DeepBook's three coins are sent there by this
+ * transaction, Bluefin's by its own entry function — so there is no destination to get wrong.
+ *
+ * ⛔ THE TRANSACTION IS BUILT BY `wallet-swap-chain.ts`, the same builder the fee was measured with,
+ *    on the same Bluefin package the quote used. The minimum-out in the shape is what protects the
+ *    person: the chain refuses a swap that would give less, and the fee for that refusal is spent.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED — the same words as the extension above.
+ */
+export declare const signSwap: SignSwap;
+/** The seam `commands/wallet-swap.ts` signs through. Returns the transaction digest. */
+export type SignSwap = (input: {
+    network: Network;
+    /** ⛔ The NMTS key. It never leaves this machine: it derives the wallet and nothing else. */
+    code: string;
+    shape: SwapShape;
+}) => Promise<string>;
+/**
+ * Register ONE part's blob, signed by the account's own wallet: the relay's tip, then the storage
+ * — bought for `epochs`, or a resource the wallet already holds, cut to fit first if asked.
+ *
+ * ⛔ THE TRANSACTION IS BUILT BY `upload-wallet-chain.ts`, the same builder the fee was measured
+ *    with, so what is signed is what was priced. What comes back is what the commit and the resume
+ *    need: the digest the relay checks its tip in, the blob object, and the epoch the chain says
+ *    the storage ends at.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED — the same words as the extension above.
+ *   The caller keeps its record and re-reads it rather than registering again.
+ */
+export declare const signBlobRegister: SignBlobRegister;
+/** Certify ONE registered part from the relay's certificate. Gas only; nothing else leaves the wallet. */
+export declare const signBlobCertify: SignBlobCertify;
+/** The seam the wallet rail registers through. */
+export type SignBlobRegister = (input: {
+    network: Network;
+    code: string;
+    relayUrl: string;
+} & RegisterShape) => Promise<{
+    digest: string;
+    blobObjectId: string;
+    endEpoch: number;
+}>;
+/** The seam the wallet rail certifies through. Returns the transaction digest. */
+export type SignBlobCertify = (input: {
+    network: Network;
+    code: string;
+    relayUrl: string;
+    blobId: string;
+    blobObjectId: string;
+    certificate: Certificate;
+}) => Promise<string>;
+/** How a storage-resource operation is signed; the shape carries what the review priced. */
+export type SignStorageOp = (input: {
+    network: Network;
+    code: string;
+    shape: StorageOpShape;
+    walrusPackageId: string;
+}) => Promise<string>;
+/**
+ * Cut, join or hand over a storage resource, in ONE transaction, signed by the account's own wallet.
+ *
+ * ⛔ THE TRANSACTION IS BUILT BY `storage-control-chain.ts`, the same builder the dry run priced,
+ *    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 declare const signStorageOp: SignStorageOp;