@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/upload-store.d.ts

@@ -0,0 +1,182 @@
+import { type Hash } from "node:crypto";
+/** Where unfinished uploads live. */
+export declare function uploadsDir(): string;
+/**
+ * A stable, account-scoped name for one file's upload attempt.
+ *
+ * Same account, same bytes, same destination give the same key — which is what lets a second `put`
+ * of a file whose first attempt died find the reservation instead of paying again.
+ *
+ * ⛔ THE DESTINATION IS PART OF IT, and leaving it out was a real defect. Two local files with
+ *    identical content — a copy, a re-download, `a.bin` and `backup/a.bin` — would otherwise share
+ *    one reservation, and putting the second one would silently resume the first: it would report
+ *    success, spend nothing, and write a SECOND file-list entry pointing at the FIRST file's item.
+ *    Deleting either would then break the other. They are two files in the drive, so they are two
+ *    uploads.
+ *
+ * ⚠ It is the destination AS TYPED, not the folder id, because the id needs a network round trip
+ *   and this key is wanted before one. Two spellings of one folder therefore make two reservations
+ *   — one extra unfinished record, never a wrong file.
+ */
+export declare function reservationKey(dataKey: Uint8Array, plaintext: Uint8Array, name: string, destination: string): string;
+/**
+ * The same key, computed without ever holding the file.
+ *
+ * ⛔ IT MUST HASH THE IDENTICAL BYTE SEQUENCE. A file large enough to need several parts is a file
+ *    too large to hand `reservationKey` as one array, and a second construction here — hashing a
+ *    hash, hashing the parts' digests — would give the same file two different keys depending on
+ *    how it was read. The one above is written in terms of this one so there is only ever one
+ *    answer, and a test feeds the same file both ways to hold that.
+ */
+export declare function reservationKeyStreamed(dataKey: Uint8Array, plaintextChunks: Iterable<Uint8Array>, name: string, destination: string): string;
+/**
+ * Begin the hash a reservation key is made from.
+ *
+ * ⛔ TWO HASHES, ONE READ. A file large enough to need parts is read once to work out its key AND
+ *    the SHA-256 the account checks its contents against; handing the caller the running hash is
+ *    what lets both come out of a single pass instead of two reads of a very large file.
+ */
+export declare function startReservationKey(dataKey: Uint8Array): Hash;
+/** Finish it. The name and the destination go in last, exactly as the one-shot form does. */
+export declare function finishReservationKey(hash: Hash, name: string, destination: string): string;
+/**
+ * The record name for ONE part of a file.
+ *
+ * ⛔ EVERY PART IS ITS OWN RESERVATION. Each one buys its own storage, under its own idempotency
+ *    key, and can fail or resume on its own — so each one is written down on its own. Sharing a
+ *    record between parts would mean a run that died between part 3 and part 4 could not say which
+ *    of them the credits had already been spent on.
+ */
+export declare function partKey(fileKey: string, partIndex: number): string;
+/** What is known about an upload that has not finished. Written before the credits move. */
+export interface Reservation {
+    /** The storage network's id for the sealed bytes. Deterministic in (bytes, nonce). */
+    blobId: string;
+    /** The relay tip nonce, base64url. Re-fed on a retry so the digest repeats. */
+    nonceB64: string;
+    /** Merkle root of the encoded blob, base64url. The server hands it to the chain verbatim. */
+    rootHashB64: string;
+    /** The relay the tip was paid to. A retry must go to the SAME one. */
+    relayUrl: string;
+    /** Storage term, in storage-network epochs. */
+    epochs: number;
+    /** Sealed byte count — what storage was bought for and what the credits counted. */
+    sealedLen: number;
+    /**
+     * The WHOLE FILE's plaintext byte count — what the file list records.
+     *
+     * ⚠ NOT THIS PART'S LENGTH. A file stored in several parts has one entry in the list and that
+     *   entry names the file's size; `partPlaintextLen` below is the piece this record covers. They
+     *   are equal for a file that fits in one part, which is why keeping the field's meaning
+     *   unchanged matters: it is read straight into the list entry.
+     */
+    plaintextLen: number;
+    /** This part's own plaintext byte count. Equal to `plaintextLen` when the file is one part. */
+    partPlaintextLen: number;
+    /**
+     * Where this part sits in the file — its index, and how many parts there are.
+     *
+     * ⛔ SEALED INTO THE BYTES, NOT JUST RECORDED HERE. NCF-3 puts both numbers in each part's
+     *    header and therefore in every chunk's associated data, so a part served in another part's
+     *    position fails authentication rather than decrypting into the wrong place. What is here is
+     *    a copy for the resume: a run that came back has to seal the SAME piece of the file under
+     *    the SAME placement, or the bytes it pushes are not the blob that was paid for.
+     */
+    partIndex: number;
+    partTotal: number;
+    /** The file's own key, wrapped. Carried so a resumed commit writes the same list entry. */
+    dekWrapped: string;
+    /** The sealed content hash. Same reason. */
+    contentHashCt: string;
+    /** The name this file is to have in the account's file list. */
+    name: string;
+    /** The folder id it goes in, or null for the root. */
+    parentId: string | null;
+    /**
+     * How many reservations this file has needed. Part of the idempotency key.
+     *
+     * ⛔ WITHOUT IT, A FAILED RESERVATION BRICKS THIS FILE FOREVER. The idempotency key is derived
+     *    from a key that is a pure function of (account, bytes, destination), and the server replays
+     *    a reservation row under its key WHATEVER STATE IT IS IN — including `failed`, which can
+     *    never become storage. So every later attempt would be handed the same dead row, be told to
+     *    start over, start over into the same dead row, and this account could never upload this
+     *    file again unless a byte of it changed. Counting up is what "start over" actually means.
+     */
+    attempt: number;
+    /** Present once the server answered: the reservation row. */
+    ledgerId?: number;
+    /** Present once registered: the transaction the relay checks its tip in. */
+    registerTxDigest?: string;
+    /** Present once registered: the on-chain blob object. */
+    blobObjectId?: string;
+    /**
+     * Present when the PERSON'S OWN WALLET is paying (`upload-wallet.ts`), absent on the credit rail.
+     *
+     * ⛔ WRITTEN SO THE OTHER RAIL REFUSES THE RECORD. The bytes and the blob id are the same
+     *    whoever pays, but what "paid" means is not: a credit record names a reservation the server
+     *    can be asked about, a wallet record names a transaction the person signed. A run on one
+     *    rail that resumed the other's record would either buy the storage a second time or commit
+     *    a part under the wrong payer.
+     */
+    paidFrom?: "wallet";
+    /** Wallet rail: present once the certify transaction executed — the part is finished on-chain. */
+    certifyTxDigest?: string;
+    /** Wallet rail: the epoch the bought storage ends at, read from the blob object after registering. */
+    endEpoch?: number;
+}
+/**
+ * The waiting reservation's RECORD, without its sealed bytes.
+ *
+ * ⛔ THE BYTES ARE THE FILE. Reading them to answer "has this part been paid for?" would mean a
+ *    resume that only needs to commit still reads every byte of a very large upload off the disk.
+ *    They are fetched separately, by the one step that actually pushes them.
+ */
+export declare function readReservationRecord(key: string): Reservation | null;
+/**
+ * The sealed bytes a reservation bought.
+ *
+ * ⛔ NEVER RE-SEALED ONES. Sealing is non-deterministic, so bytes produced by a later run are a
+ *    different blob from the one the treasury registered — the relay refuses them, forever, and
+ *    the credits are gone.
+ */
+export declare function readReservationBytes(key: string): Uint8Array;
+/** The record and its bytes together, for the callers that need both. */
+export declare function readReservation(key: string): {
+    record: Reservation;
+    sealed: Uint8Array;
+} | null;
+/** Write the record and its sealed bytes. Called BEFORE the reserve, and again after it answers. */
+export declare function writeReservation(key: string, record: Reservation, sealed: Uint8Array): void;
+/**
+ * Forget a reservation.
+ *
+ * ⚠ Called on success AND on a couple of failure paths, so the comment that used to say "the
+ *   upload already succeeded" was not true of every caller. What IS true of all of them is that
+ *   nothing further depends on the record, which is why it never throws.
+ */
+export declare function clearReservation(key: string): void;
+/**
+ * The FILE-level half of an unfinished upload: what happened after every part was paid for.
+ *
+ * ⛔ IT CANNOT LIVE ON A PART. Committing is one act for the whole file — one `POST /v1/items`
+ *    naming every part — so "this file is committed" is not a fact about part 3. Writing it onto
+ *    one arbitrary part would work until somebody reordered the resume, and then a committed file
+ *    would be committed a second time.
+ */
+export interface ItemRecord {
+    /** Present once `POST /v1/items` answered: the file exists on the server and is paid for. */
+    itemId?: string;
+    /**
+     * How many commits this file has attempted. Part of the commit's idempotency key.
+     *
+     * Separate from a part's `attempt` for the same reason the record is: a part that had to buy its
+     * storage twice says nothing about how many times the file was committed.
+     */
+    attempt: number;
+}
+/** What is known about this file's commit, or `null` when it has not been attempted. */
+export declare function readItemRecord(fileKey: string): ItemRecord | null;
+/** Write the file-level record. Called before the commit, and again once it has an id. */
+export declare function writeItemRecord(fileKey: string, record: ItemRecord): void;
+/** Forget the file-level record. Never throws, for the same reason `clearReservation` does not. */
+export declare function clearItemRecord(fileKey: string): void;

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

@@ -0,0 +1,54 @@
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import { Transaction } from "@mysten/sui/transactions";
+import type { Network } from "./network.ts";
+import type { RegisterShape, WalletUploadReads } from "./upload-wallet-plan.ts";
+import type { Certificate } from "./upload-wire.ts";
+/**
+ * The most this tool will pay an upload relay as a tip, in MIST, per network.
+ *
+ * ⚠ A SECOND COPY of the browser's `RELAY_TIP_MAX_MIST`, for the same reason `WAL_COIN_TYPES` is:
+ *   this package imports nothing from that tree. It is a CEILING, not the charge — the relay's own
+ *   tip configuration sets the amount, which the review prints — and a relay asking for more than
+ *   this is refused by the SDK before anything is signed.
+ */
+export declare const RELAY_TIP_CEILING_MIST: Readonly<Record<Network, number>>;
+/** The Walrus package addresses of one network. Exported from the SDK; the system object survives upgrades. */
+export declare function packageConfig(network: Network): {
+    systemObjectId: string;
+};
+declare function build(network: Network, relayUrl: string): import("@mysten/sui/client").ClientWithExtensions<{
+    walrus: import("@mysten/walrus").WalrusClient;
+}, SuiJsonRpcClient>;
+export type PayingClient = ReturnType<typeof build>;
+/** A Walrus client bound to ONE relay, able to pay that relay's tip. */
+export declare function payingClient(network: Network, relayUrl: string): PayingClient;
+/**
+ * The register transaction of ONE part — the tip, then either a purchase or a held resource.
+ *
+ * ⛔ SENDER FIRST. `coinWithBalance` and the SDK's own coin selection pick WAL and SUI from the
+ *    sender's address when the fragments resolve; without it the build fails late.
+ */
+export declare function registerTransaction(client: PayingClient, network: Network, input: RegisterShape & {
+    sender: string;
+}): Promise<Transaction>;
+/** The certify transaction of ONE part, from the certificate the relay handed back. */
+export declare function certifyTransaction(client: PayingClient, input: {
+    blobId: string;
+    blobObjectId: string;
+    certificate: Certificate;
+}): Transaction;
+/**
+ * The blob object a register transaction created, and when its storage ends.
+ *
+ * ⛔ THE OBJECT IS FOUND BY ITS TYPE, not by position: the transaction also creates the leftover
+ *    resource on a cut, and on a purchase the storage object is created and consumed inside it.
+ */
+export declare function createdBlob(client: PayingClient, objectChanges: unknown): Promise<{
+    blobObjectId: string;
+    endEpoch: number;
+}>;
+/** What this part is once the network has encoded it — the number registration compares a resource against. */
+export declare function encodedLength(client: PayingClient, sender: string, sealedLen: number): Promise<number>;
+/** The live reads one wallet-paid upload needs, bound to one network and one relay. */
+export declare function walletUploadReads(network: Network, relayUrl: string): WalletUploadReads;
+export {};

package/dist/upload-wallet-chain.js

@@ -0,0 +1,203 @@
+// The chain behind a WALLET-PAID upload: the client that can pay a relay's tip, the register and
+// certify transactions, the live reads that price an upload, and the two facts read back after
+// the register signature.
+//
+// ⛔ ONE BUILDER FOR THE FEE AND THE SIGNATURE. `registerTransaction` is what the dry run measures
+//    and what `wallet-sign.ts` signs — the same rule `wallet-send-chain.ts` keeps. Two builders
+//    would let the review price one transaction and the wallet approve another.
+//
+// ⛔ THE TIP IS IN THE REGISTER TRANSACTION, exactly as the SDK's own flow orders it: the auth
+//    payload and the transfer to the relay first, then the registration. On the credit rail the
+//    treasury pays that tip inside its own transaction; here the person does, and the relay checks
+//    it in the transaction named when the bytes arrive (`walrus-write.ts`).
+//
+// ⛔ THE ENCODED SIZE IS THE CHAIN'S ARITHMETIC, NOT A COPY. Registration checks
+//    `encoded_size <= storage_size` with `walrus::encoding::encoded_blob_length`, and the SDK keeps
+//    its own copy unexported. Cutting a held resource to fit needs that exact number, so it is
+//    asked of the chain itself, in a dev-inspect that costs nothing — a copy kept here would be
+//    wrong the day the protocol changed it, and the way that surfaces is a refused registration
+//    after the split was signed.
+import { bcs } from "@mysten/sui/bcs";
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import { Transaction } from "@mysten/sui/transactions";
+import { blobIdFromInt, blobIdToInt, MAINNET_WALRUS_PACKAGE_CONFIG, TESTNET_WALRUS_PACKAGE_CONFIG, walrus, } from "@mysten/walrus";
+import { NmtsError } from "./errors.js";
+import { extendReads, netGasFee, readBlobLease } from "./extend-chain.js";
+import { readOwnedStorage, readStorageType } from "./shared/lib/storage-control/chain.js";
+import { registerIntoStorage, splitStorageToFit } from "./shared/lib/storage-control/reuse.js";
+import { suiRpcTransport } from "./sui-rpc.js";
+import { readBalances, walCoinType } from "./wallet.js";
+import { chainReader } from "./wallet-chain.js";
+/**
+ * The most this tool will pay an upload relay as a tip, in MIST, per network.
+ *
+ * ⚠ A SECOND COPY of the browser's `RELAY_TIP_MAX_MIST`, for the same reason `WAL_COIN_TYPES` is:
+ *   this package imports nothing from that tree. It is a CEILING, not the charge — the relay's own
+ *   tip configuration sets the amount, which the review prints — and a relay asking for more than
+ *   this is refused by the SDK before anything is signed.
+ */
+export const RELAY_TIP_CEILING_MIST = {
+    testnet: 100_000,
+    mainnet: 250_000_000,
+};
+/** The Walrus package addresses of one network. Exported from the SDK; the system object survives upgrades. */
+export function packageConfig(network) {
+    return network === "mainnet" ? MAINNET_WALRUS_PACKAGE_CONFIG : TESTNET_WALRUS_PACKAGE_CONFIG;
+}
+function build(network, relayUrl) {
+    return new SuiJsonRpcClient({ network, transport: suiRpcTransport(network) }).$extend(walrus({ uploadRelay: { host: relayUrl, sendTip: { max: RELAY_TIP_CEILING_MIST[network] } } }));
+}
+/** A Walrus client bound to ONE relay, able to pay that relay's tip. */
+export function payingClient(network, relayUrl) {
+    return build(network, relayUrl);
+}
+/**
+ * The register transaction of ONE part — the tip, then either a purchase or a held resource.
+ *
+ * ⛔ SENDER FIRST. `coinWithBalance` and the SDK's own coin selection pick WAL and SUI from the
+ *    sender's address when the fragments resolve; without it the build fails late.
+ */
+export async function registerTransaction(client, network, input) {
+    const tx = new Transaction();
+    tx.setSender(input.sender);
+    const { part } = input;
+    tx.add(client.walrus.sendUploadRelayTip({ size: part.sealedLen, blobDigest: part.blobDigest, nonce: part.nonce }));
+    if (input.storage.kind === "buy") {
+        const blob = tx.add(client.walrus.registerBlob({
+            size: part.sealedLen,
+            epochs: input.epochs,
+            blobId: part.blobId,
+            rootHash: part.rootHash,
+            deletable: true,
+        }));
+        tx.transferObjects([blob], input.sender);
+        return tx;
+    }
+    const walrusPackageId = (await client.walrus.systemObject()).package_id;
+    if (input.storage.cutToBytes !== null) {
+        splitStorageToFit({
+            walrusPackageId,
+            storageObjectId: input.storage.objectId,
+            keepBytes: input.storage.cutToBytes,
+            owner: input.sender,
+        }, tx);
+    }
+    registerIntoStorage({
+        systemObjectId: packageConfig(network).systemObjectId,
+        walrusPackageId,
+        walType: walCoinType(network),
+        storageObjectId: input.storage.objectId,
+        blobIdAsInt: blobIdToInt(part.blobId),
+        rootHash: part.rootHash,
+        rawBytes: part.sealedLen,
+        writeCost: input.storage.writeFrost,
+        deletable: true,
+        owner: input.sender,
+    }, tx);
+    return tx;
+}
+/** The certify transaction of ONE part, from the certificate the relay handed back. */
+export function certifyTransaction(client, input) {
+    return client.walrus.certifyBlobTransaction({
+        blobId: input.blobId,
+        blobObjectId: input.blobObjectId,
+        deletable: true,
+        certificate: {
+            signers: input.certificate.signers,
+            serializedMessage: new Uint8Array(Buffer.from(input.certificate.serialized_message_b64, "base64url")),
+            signature: new Uint8Array(Buffer.from(input.certificate.signature_b64, "base64url")),
+        },
+    });
+}
+/**
+ * The blob object a register transaction created, and when its storage ends.
+ *
+ * ⛔ THE OBJECT IS FOUND BY ITS TYPE, not by position: the transaction also creates the leftover
+ *    resource on a cut, and on a purchase the storage object is created and consumed inside it.
+ */
+export async function createdBlob(client, objectChanges) {
+    const created = Array.isArray(objectChanges)
+        ? objectChanges.find((change) => typeof change === "object" &&
+            change !== null &&
+            Reflect.get(change, "type") === "created" &&
+            typeof Reflect.get(change, "objectType") === "string" &&
+            String(Reflect.get(change, "objectType")).endsWith("::blob::Blob"))
+        : undefined;
+    const id = created === undefined ? undefined : Reflect.get(created, "objectId");
+    if (typeof id !== "string") {
+        throw new NmtsError("The registration executed but the chain did not list the blob object it created.", {
+            exitCode: 1,
+            nextStep: "The storage is bought. Running the same command again does not pay again: it reads the record and continues.",
+        });
+    }
+    const lease = await readBlobLease(client, id);
+    return { blobObjectId: id, endEpoch: lease.endEpoch };
+}
+/** What this part is once the network has encoded it — the number registration compares a resource against. */
+export async function encodedLength(client, sender, sealedLen) {
+    const [system, state] = await Promise.all([client.walrus.systemObject(), client.walrus.systemState()]);
+    const tx = new Transaction();
+    tx.moveCall({
+        package: system.package_id,
+        module: "encoding",
+        function: "encoded_blob_length",
+        // 1 = RS2, the encoding every registration in this tool names (`reuse.ts`).
+        arguments: [tx.pure.u64(sealedLen), tx.pure.u8(1), tx.pure.u16(state.committee.n_shards)],
+    });
+    const result = await client.devInspectTransactionBlock({ sender, transactionBlock: tx });
+    const value = result.results?.[0]?.returnValues?.[0]?.[0];
+    if (value === undefined) {
+        throw new NmtsError("The chain did not say how large this part is once encoded.", {
+            exitCode: 1,
+            nextStep: "Nothing was signed. A held resource cannot be cut to fit without that number; buy new storage instead, or try again.",
+        });
+    }
+    return Number(bcs.u64().parse(Uint8Array.from(value)));
+}
+/** A part shaped like a real one, for measuring the fee of a registration before anything is sealed. */
+function placeholderPart(sealedLen) {
+    return {
+        sealedLen,
+        blobId: blobIdFromInt(1n),
+        rootHash: new Uint8Array(32),
+        nonce: new Uint8Array(32),
+        blobDigest: new Uint8Array(32),
+    };
+}
+/** The live reads one wallet-paid upload needs, bound to one network and one relay. */
+export function walletUploadReads(network, relayUrl) {
+    const client = build(network, relayUrl);
+    return {
+        readWindow: () => extendReads(network).readWindow(),
+        async quoteParts(sealedLens, epochs) {
+            return Promise.all(sealedLens.map(async (sealedLen) => {
+                const [cost, tip] = await Promise.all([
+                    client.walrus.storageCost(sealedLen, epochs),
+                    client.walrus.calculateUploadRelayTip({ size: sealedLen }),
+                ]);
+                return { sealedLen, storageFrost: cost.storageCost, writeFrost: cost.writeCost, tipMist: BigInt(tip) };
+            }));
+        },
+        readWallet: (address) => readBalances(chainReader(network, address), walCoinType(network)),
+        async estimateRegisterGas({ sender, sealedLen, epochs, storage }) {
+            // ⛔ THE SAME BUILDER THE SIGNATURE USES, with a placeholder blob: the gas of `register_blob`
+            //    does not depend on which id is registered, and the real id exists only after sealing.
+            try {
+                const tx = await registerTransaction(client, network, { sender, epochs, storage, part: placeholderPart(sealedLen) });
+                const bytes = await tx.build({ client });
+                const { effects } = await client.dryRunTransactionBlock({ transactionBlock: bytes });
+                if (effects.status.status !== "success")
+                    return null;
+                return netGasFee(effects.gasUsed);
+            }
+            catch {
+                return null;
+            }
+        },
+        async readStorage(address) {
+            const type = await readStorageType(client, packageConfig(network).systemObjectId);
+            return readOwnedStorage(client, address, type);
+        },
+        encodedLength: (sender, sealedLen) => encodedLength(client, sender, sealedLen),
+    };
+}

package/dist/upload-wallet-plan.d.ts

@@ -0,0 +1,128 @@
+import type { ExtendWindow } from "./extend-plan.ts";
+import type { StorageResource } from "./shared/lib/storage-control/chain.ts";
+import { type WalletBalances } from "./wallet.ts";
+/** The browser's default rung, and the term one credit buys. A number of EPOCHS, not days. */
+export declare const DEFAULT_UPLOAD_EPOCHS = 2;
+/** What ONE part costs, as the chain quotes it. Base units throughout. */
+export interface PartQuote {
+    sealedLen: number;
+    /** Storage over time, in FROST. Zero when a held resource supplies the storage. */
+    storageFrost: bigint;
+    /** The write, in FROST. Charged whoever supplies the storage. */
+    writeFrost: bigint;
+    /** The relay's tip, in MIST. */
+    tipMist: bigint;
+}
+/** Where a part's storage comes from. */
+export type StorageChoice = {
+    kind: "buy";
+} | {
+    kind: "reuse";
+    objectId: string;
+    /** Cut the resource down to this many bytes first (`fit`), or null to bind it whole. */
+    cutToBytes: number | null;
+    /** The write cost, which a held resource does not cover. */
+    writeFrost: bigint;
+    /** What the resource holds beyond this part, once encoded — bound with the file, or left over. */
+    leftoverBytes: number;
+    resource: StorageResource;
+};
+/** One part as the register transaction needs it. */
+export interface RegisterShape {
+    epochs: number;
+    storage: {
+        kind: "buy";
+    } | {
+        kind: "reuse";
+        objectId: string;
+        cutToBytes: number | null;
+        writeFrost: bigint;
+    };
+    part: {
+        sealedLen: number;
+        blobId: string;
+        rootHash: Uint8Array;
+        nonce: Uint8Array;
+        blobDigest: Uint8Array;
+    };
+}
+/** The chain, as a wallet-paid upload READS it. ⚠ A seam — no flag reaches it. */
+export interface WalletUploadReads {
+    readWindow(): Promise<ExtendWindow | null>;
+    quoteParts(sealedLens: readonly number[], epochs: number): Promise<PartQuote[]>;
+    readWallet(address: string): Promise<WalletBalances>;
+    /** The fee of ONE register signature, measured by a dry run — or null when it could not be. */
+    estimateRegisterGas(input: {
+        sender: string;
+        sealedLen: number;
+        epochs: number;
+        storage: RegisterShape["storage"];
+    }): Promise<bigint | null>;
+    /** The free storage resources the wallet holds. Rejects when they could not be read. */
+    readStorage(address: string): Promise<StorageResource[]>;
+    /** What a part of this many sealed bytes occupies once encoded — the chain's own number. */
+    encodedLength(sender: string, sealedLen: number): Promise<number>;
+}
+/**
+ * How many epochs to buy: what was asked for, or the browser's default, held against the ceiling.
+ *
+ * ⛔ IT REFUSES RATHER THAN CLAMPS, for the reason `extend-plan.ts` gives: quietly buying fewer
+ *    epochs spends money on something nobody asked for.
+ */
+export declare function chooseUploadEpochs(asked: string | number | undefined, window: ExtendWindow): number;
+/** A number of epochs as days, read from the network's own clock. */
+export declare function daysOf(window: ExtendWindow, epochs: number): string;
+/** What `--storage` asks for. */
+export type StorageAsk = {
+    mode: "fit";
+} | {
+    mode: "whole";
+} | {
+    mode: "object";
+    objectId: string;
+};
+export declare function parseStorageAsk(text: string | undefined): StorageAsk | null;
+/**
+ * Which held resource supplies this part's storage, and how much of it.
+ *
+ * ⛔ THE LEFTOVER IS A NUMBER THE PERSON SEES — the owner's rule: registration binds the WHOLE resource,
+ *    so `whole` says how many bytes go in with the file, and `fit` cuts first and says what stays
+ *    free. `fit` and `whole` pick the smallest usable resource that fits; an object id names one.
+ */
+export declare function pickResource(ask: StorageAsk, resources: readonly StorageResource[], encodedBytes: number, currentEpoch: number, needUntilEpoch: number, writeFrost: bigint): StorageChoice;
+/** The wallet against the price — before the agreement, before any signature. */
+export interface UploadBudget {
+    readonly address: string;
+    readonly walNeededFrost: bigint;
+    /** Tips plus the measured register fee per part. The certify fees are on top and unmeasured. */
+    readonly suiNeededMist: bigint;
+    readonly walFrost: bigint | null;
+    readonly suiMist: bigint | null;
+    readonly feeMist: bigint | null;
+    readonly unread: readonly string[];
+    readonly shortfall: string | null;
+}
+export declare function uploadBudget(input: {
+    address: string;
+    purse: WalletBalances;
+    feeMist: bigint | null;
+    quotes: readonly PartQuote[];
+    storage: StorageChoice;
+}): UploadBudget;
+/** WAL for the whole file: storage and write when buying, the write alone on a held resource. */
+export declare function walPrice(quotes: readonly PartQuote[], storage: StorageChoice): bigint;
+/** The next step when the wallet is short: where to send what, said once. */
+export declare function uploadShortfallNextStep(b: UploadBudget): string;
+/** The numbers, for a person, in the order somebody deciding needs them. */
+export declare function describeUploadReview(say: (line: string) => void, facts: {
+    name: string;
+    bytes: number;
+    parts: number;
+    epochs: number;
+    days: string;
+    endEpoch: number;
+    walNeeded: bigint;
+    tipMist: bigint;
+    storage: StorageChoice;
+    heldResources: number | null;
+}, budget: UploadBudget): void;