@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/upload-wallet-plan.js

@@ -0,0 +1,184 @@
+// What a WALLET-PAID upload would buy, worked out before anything is sealed or signed.
+//
+// ⛔ NO NETWORK, NO SDK, NO KEY. Everything here is arithmetic over numbers somebody else read, so
+//    `node --test` drives every branch — the shortfalls, the resource that does not fit, the length
+//    the network will not sell. The reads live in `upload-wallet-chain.ts`, the signatures in
+//    `wallet-sign.ts`, and neither can be reached from here.
+//
+// ⛔ THE PRICE HAS THREE PARTS AND THE REVIEW SAYS ALL THREE. Storage and the write are WAL; the
+//    relay's tip and the chain fee are SUI. The browser's payment sheet itemises exactly these, and
+//    a person comparing the two programs should see the same numbers under the same names.
+//
+// ⛔ AN UNREAD BALANCE IS NOT A SHORTFALL — the rule `extend-budget.ts` states, kept here where it
+//    costs the most: a zero would refuse an upload the wallet can afford.
+import { NmtsError } from "./errors.js";
+import { BINARY_NAME } from "./product.js";
+import { fits, leftoverBytes, statusOf, usableFirst } from "./shared/lib/storage-control/plan.js";
+import { coinAmount } from "./wallet.js";
+/** The browser's default rung, and the term one credit buys. A number of EPOCHS, not days. */
+export const DEFAULT_UPLOAD_EPOCHS = 2;
+/**
+ * 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 function chooseUploadEpochs(asked, window) {
+    const epochs = asked === undefined ? DEFAULT_UPLOAD_EPOCHS : typeof asked === "number" ? asked : Number(asked.trim());
+    if (!Number.isSafeInteger(epochs) || epochs <= 0) {
+        throw new NmtsError(`A storage term is a whole number of epochs: ${String(asked)}.`, {
+            exitCode: 2,
+            nextStep: `Nothing was signed. \`--epochs 4\` buys four of the storage network's epochs — ${daysOf(window, 1)} each.`,
+        });
+    }
+    if (epochs > window.maxAhead) {
+        throw new NmtsError(`The storage network sells at most ${window.maxAhead} epochs ahead.`, {
+            exitCode: 4,
+            nextStep: `Nothing was signed. Ask for ${window.maxAhead} or fewer: \`${BINARY_NAME} put <file> --pay wallet --epochs ${window.maxAhead}\`.`,
+        });
+    }
+    return epochs;
+}
+/** A number of epochs as days, read from the network's own clock. */
+export function daysOf(window, epochs) {
+    const days = (epochs * window.clock.durationMs) / 86_400_000;
+    const rounded = Number.isInteger(days) ? String(days) : days.toFixed(1);
+    return `${rounded} day${days === 1 ? "" : "s"}`;
+}
+export function parseStorageAsk(text) {
+    if (text === undefined || text === "")
+        return null;
+    if (text === "fit" || text === "whole")
+        return { mode: text };
+    if (/^0x[0-9a-fA-F]{64}$/.test(text))
+        return { mode: "object", objectId: text.toLowerCase() };
+    throw new NmtsError(`--storage takes fit, whole, or a storage resource's object id, not "${text}".`, {
+        exitCode: 2,
+        nextStep: `\`${BINARY_NAME} wallet storage\` lists the resources this wallet holds.`,
+    });
+}
+/**
+ * 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 function pickResource(ask, resources, encodedBytes, currentEpoch, needUntilEpoch, writeFrost) {
+    const usable = usableFirst(resources, currentEpoch).filter((r) => statusOf(r, currentEpoch) === "usable");
+    let chosen;
+    if (ask.mode === "object") {
+        chosen = resources.find((r) => r.objectId === ask.objectId);
+        if (chosen === undefined) {
+            throw new NmtsError(`This wallet holds no free storage resource ${ask.objectId}.`, {
+                exitCode: 4,
+                nextStep: `Nothing was signed. \`${BINARY_NAME} wallet storage\` lists what it holds.`,
+            });
+        }
+        if (!fits(chosen, encodedBytes, needUntilEpoch) || statusOf(chosen, currentEpoch) !== "usable") {
+            throw new NmtsError(`Resource ${ask.objectId} cannot hold this part until epoch ${needUntilEpoch}.`, {
+                exitCode: 4,
+                nextStep: `Nothing was signed. It holds ${chosen.sizeBytes} bytes from epoch ${chosen.startEpoch} to ` +
+                    `${chosen.endEpoch}; this part is ${encodedBytes} bytes once encoded. Leave --storage off to buy new storage.`,
+            });
+        }
+    }
+    else {
+        // Smallest first among those that fit: the one that wastes least when bound whole.
+        chosen = usable.filter((r) => fits(r, encodedBytes, needUntilEpoch)).sort((a, b) => a.sizeBytes - b.sizeBytes)[0];
+        if (chosen === undefined) {
+            throw new NmtsError(`No free storage resource in this wallet holds ${encodedBytes} encoded bytes until epoch ${needUntilEpoch}.`, {
+                exitCode: 4,
+                nextStep: `Nothing was signed. \`${BINARY_NAME} wallet storage\` lists what it holds; leave --storage off ` +
+                    `to buy new storage, or ask for fewer epochs.`,
+            });
+        }
+    }
+    const cut = ask.mode === "fit";
+    return {
+        kind: "reuse",
+        objectId: chosen.objectId,
+        cutToBytes: cut ? encodedBytes : null,
+        writeFrost,
+        leftoverBytes: leftoverBytes(chosen, encodedBytes),
+        resource: chosen,
+    };
+}
+function held(coin) {
+    return coin.read ? coin.baseUnits : null;
+}
+export function uploadBudget(input) {
+    const { address, purse, feeMist, quotes, storage } = input;
+    const walNeededFrost = walPrice(quotes, storage);
+    const tips = quotes.reduce((sum, q) => sum + q.tipMist, 0n);
+    const suiNeededMist = tips + (feeMist ?? 0n) * BigInt(quotes.length);
+    const walFrost = held(purse.wal);
+    const suiMist = held(purse.sui);
+    const unread = [];
+    if (!purse.wal.read)
+        unread.push(`WAL: ${purse.wal.why}`);
+    if (!purse.sui.read)
+        unread.push(`SUI: ${purse.sui.why}`);
+    let shortfall = null;
+    if (walFrost !== null && walFrost < walNeededFrost) {
+        shortfall = `The wallet holds ${coinAmount(walFrost)} WAL and this upload costs ${coinAmount(walNeededFrost)} WAL.`;
+    }
+    else if (suiMist !== null && suiMist < suiNeededMist) {
+        shortfall =
+            `The wallet holds ${coinAmount(suiMist)} SUI and this upload needs about ${coinAmount(suiNeededMist)} SUI ` +
+                `for the relay tip and the chain fees.`;
+    }
+    return { address, walNeededFrost, suiNeededMist, walFrost, suiMist, feeMist, unread, shortfall };
+}
+/** WAL for the whole file: storage and write when buying, the write alone on a held resource. */
+export function walPrice(quotes, storage) {
+    return quotes.reduce((sum, q) => sum + q.writeFrost + (storage.kind === "buy" ? q.storageFrost : 0n), 0n);
+}
+/** The next step when the wallet is short: where to send what, said once. */
+export function uploadShortfallNextStep(b) {
+    const coin = b.walFrost !== null && b.walFrost < b.walNeededFrost ? "WAL" : "SUI";
+    return (`Nothing was signed and nothing was sent. Send ${coin} to ${b.address} — ` +
+        `\`${BINARY_NAME} wallet\` shows the address and both balances — and run this again.`);
+}
+/** The numbers, for a person, in the order somebody deciding needs them. */
+export function describeUploadReview(say, facts, budget) {
+    say(`${facts.name}  ${facts.bytes} bytes  →  ${coinAmount(facts.walNeeded)} WAL from the wallet`);
+    if (facts.parts > 1)
+        say(`  in ${facts.parts} parts — each one is registered and certified with its own signatures`);
+    say(`  Stored for ${facts.epochs} epoch${facts.epochs === 1 ? "" : "s"} — ${facts.days} — until epoch ${facts.endEpoch}.`);
+    if (facts.storage.kind === "reuse") {
+        const r = facts.storage.resource;
+        say(`  Storage comes from resource ${r.objectId} (${r.sizeBytes} bytes, until epoch ${r.endEpoch}); the WAL above is the write alone.`);
+        say(facts.storage.cutToBytes === null
+            ? `  Used whole: ${facts.storage.leftoverBytes} bytes beyond this file are bound with it and cannot be taken back.`
+            : `  Cut to fit: ${facts.storage.leftoverBytes} bytes stay free as a resource of their own.`);
+    }
+    else if (facts.heldResources !== null && facts.heldResources > 0) {
+        say(`  This wallet also holds ${facts.heldResources} free storage resource${facts.heldResources === 1 ? "" : "s"} — \`${BINARY_NAME} wallet storage\` lists them; --storage fit or whole tries one.`);
+    }
+    say(`  Relay tip ${coinAmount(facts.tipMist)} SUI, paid inside the register signature${facts.parts > 1 ? "s" : ""}.`);
+    if (budget.feeMist === null) {
+        say(`  The chain fee (SUI) of a register signature could not be measured just now; it is charged with each signature.`);
+    }
+    else {
+        say(`  Chain fee about ${coinAmount(budget.feeMist)} SUI per register signature, measured by a dry run just now; ` +
+            `each certify signature pays its own smaller fee on top.`);
+    }
+    const wal = budget.walFrost === null ? "WAL not read" : `${coinAmount(budget.walFrost)} WAL`;
+    const sui = budget.suiMist === null ? "SUI not read" : `${coinAmount(budget.suiMist)} SUI`;
+    say(`  Wallet ${budget.address} holds ${wal} and ${sui}.`);
+    if (budget.walFrost !== null && budget.suiMist !== null) {
+        const walAfter = budget.walFrost - budget.walNeededFrost;
+        const suiAfter = budget.suiMist - budget.suiNeededMist;
+        say(`  Afterwards it holds about ${coinAmount(walAfter < 0n ? 0n : walAfter)} WAL and ${coinAmount(suiAfter < 0n ? 0n : suiAfter)} SUI.`);
+    }
+    for (const why of budget.unread) {
+        say(`  A balance could not be read — ${why}. That is not zero: the chain decides at signing.`);
+    }
+    say(``);
+    say(`  This is paid in WAL and SUI from the wallet this NMTS key derives — not from credits, which`);
+    say(`  is what \`${BINARY_NAME} put\` spends without --pay wallet. Nobody, NMTS included, can reverse it.`);
+    say(`  The storage is the wallet's own: NMTS records the file and does not hold it. This upload does`);
+    say(`  not carry the recovery list's storage-network copy, whatever the account's switch says —`);
+    say(`  only the browser's small-file uploads do.`);
+}

package/dist/upload-wallet.d.ts

@@ -0,0 +1,24 @@
+import type { Network } from "./network.ts";
+import type { PartQuote, StorageChoice } from "./upload-wallet-plan.ts";
+import { type PaidPart, type UploadInput } from "./upload-wire.ts";
+import type { Spend } from "./wallet-grant.ts";
+import type { SignBlobCertify, SignBlobRegister } from "./wallet-sign.ts";
+export interface WalletRailContext {
+    network: Network;
+    /** ⛔ The NMTS key. Held for the signatures and never written anywhere. */
+    code: string;
+    relayUrl: string;
+    epochs: number;
+    /** Where the storage comes from. A held resource serves one blob, so it applies to a one-part file. */
+    storage: StorageChoice;
+    /** What each part was quoted, in part order — what the grant ledger is told after each signature. */
+    quotes: readonly PartQuote[];
+    /** The measured register fee, added to the ledger with the tip; null adds the tip alone. */
+    feeMist: bigint | null;
+    signRegister: SignBlobRegister;
+    signCertify: SignBlobCertify;
+    /** Told what left the wallet, after each signature. */
+    onSpend: (spend: Spend) => void;
+}
+/** The rail: what `uploadFile` calls once per part. */
+export declare function walletRail(ctx: WalletRailContext): (input: UploadInput) => Promise<PaidPart>;

package/dist/upload-wallet.js

@@ -0,0 +1,208 @@
+// The WALLET rail for ONE part: register (signature one), push the bytes at the relay, certify
+// (signature two) — with the same written-down records the credit rail keeps.
+//
+// ⛔ THE ORDER IS WHAT STANDS BETWEEN AN INTERRUPTION AND MONEY THAT BOUGHT NOTHING, as in
+//    `upload.ts`:
+//
+//      encode → WRITE IT DOWN → sign register (WAL and the tip leave here) → write it down again
+//            → relay → sign certify (gas) → write it down again     … once per part …
+//
+//    Before the signature, so a retry has the sealed bytes and the tip nonce that reproduce the
+//    blob the registration named. After it, so the transaction the relay checks its tip in, and
+//    the blob object the certification names, are not lost with the process.
+//
+// ⛔ NOTHING IS SIGNED TWICE FOR ONE PART. A record carrying a register digest skips the register;
+//    one carrying a certify digest skips everything. That is what makes running the same command
+//    again cost nothing more — the same promise the credit rail makes with a reservation.
+//
+// ⛔ THE SIGNATURES ARE A SEAM. `wallet-sign.ts` is loaded by the command, after the agreement,
+//    and handed in; the tests hand in recorders and prove that `--dry-run` and a shortfall never
+//    reach them.
+import { NmtsError } from "./errors.js";
+import { readReservationBytes, readReservationRecord, writeReservation } from "./upload-store.js";
+import { UploadError } from "./upload-wire.js";
+function why(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The rail: what `uploadFile` calls once per part. */
+export function walletRail(ctx) {
+    return (input) => buyAndPushPartWithWallet(ctx, input);
+}
+async function buyAndPushPartWithWallet(ctx, input) {
+    const { protocol, key, sealed, onStep } = input;
+    const existing = readReservationRecord(key);
+    if (existing !== null && existing.paidFrom !== "wallet") {
+        throw new UploadError({
+            phase: "reserve",
+            message: "This upload was started with credits paying, and this run would pay from the wallet.",
+            paid: existing.ledgerId !== undefined,
+            nextStep: "Run it again without --pay wallet to finish it, or move the records in the uploads " +
+                "directory aside to start over. Nothing was sent.",
+        });
+    }
+    if (existing !== null && (existing.partIndex !== input.part.index || existing.partTotal !== input.part.total)) {
+        throw new UploadError({
+            phase: "reserve",
+            message: `This upload was started as part ${existing.partIndex + 1} of ${existing.partTotal} and this ` +
+                `run is treating it as part ${input.part.index + 1} of ${input.part.total}.`,
+            paid: existing.registerTxDigest !== undefined,
+            nextStep: "Run it again with the part size the first attempt used, or move the records in the " +
+                "uploads directory aside to start over. Nothing was sent.",
+        });
+    }
+    // ── already certified: nothing left to sign or send ──
+    if (existing?.certifyTxDigest !== undefined) {
+        onStep?.({ step: "resuming", ledgerId: 0, state: "certified" });
+        return paidPart(existing, true);
+    }
+    // ── registered by an earlier run: push and certify, sign nothing twice ──
+    if (existing?.registerTxDigest !== undefined && existing.blobObjectId !== undefined) {
+        onStep?.({ step: "resuming", ledgerId: 0, state: "registered" });
+        const certificate = await push(input, existing, existing.registerTxDigest, existing.blobObjectId, readReservationBytes(key));
+        await certify(ctx, input, key, existing, certificate);
+        return paidPart(readReservationRecord(key) ?? existing, true);
+    }
+    // ── fresh, or interrupted before the signature ──
+    onStep?.({ step: "encoding", bytes: sealed.length });
+    let meta;
+    try {
+        meta = await protocol.computeMetadata({
+            bytes: sealed,
+            nonce: existing ? new Uint8Array(Buffer.from(existing.nonceB64, "base64url")) : undefined,
+        });
+    }
+    catch (error) {
+        throw new UploadError({
+            phase: "encoding",
+            message: `Could not prepare this file for the storage network: ${why(error)}`,
+            paid: false,
+            nextStep: "Nothing was sent and nothing was signed.",
+        });
+    }
+    const record = {
+        attempt: existing?.attempt ?? 0,
+        paidFrom: "wallet",
+        blobId: meta.blobId,
+        nonceB64: Buffer.from(meta.nonce).toString("base64url"),
+        rootHashB64: Buffer.from(meta.rootHash).toString("base64url"),
+        relayUrl: input.relayUrl,
+        epochs: input.epochs,
+        sealedLen: sealed.length,
+        plaintextLen: input.entry.plaintextLen,
+        partPlaintextLen: input.part.plaintextLen,
+        partIndex: input.part.index,
+        partTotal: input.part.total,
+        dekWrapped: input.entry.dekWrapped,
+        contentHashCt: input.entry.contentHashCt,
+        name: input.entry.name,
+        parentId: input.entry.parentId,
+    };
+    // ⛔ BEFORE THE SIGNATURE. See the module header.
+    writeReservation(key, record, sealed);
+    onStep?.({ step: "reserving" });
+    const quote = ctx.quotes[input.part.index];
+    if (quote === undefined)
+        throw new NmtsError("unreachable: a part with no quote");
+    let registered;
+    try {
+        registered = await ctx.signRegister({
+            network: ctx.network,
+            code: ctx.code,
+            relayUrl: input.relayUrl,
+            epochs: ctx.epochs,
+            storage: ctx.storage.kind === "buy" ? { kind: "buy" } : ctx.storage,
+            part: { sealedLen: sealed.length, blobId: meta.blobId, rootHash: meta.rootHash, nonce: meta.nonce, blobDigest: meta.blobDigest },
+        });
+    }
+    catch (error) {
+        throw new UploadError({
+            phase: "reserve",
+            message: why(error),
+            // ⛔ A refusal did not spend more than gas. A request that never got an answer MIGHT have
+            //    registered — the record is on disk either way, and the next run reads the chain's
+            //    answer through the same signature path rather than guessing here.
+            paid: false,
+            nextStep: error instanceof NmtsError && error.nextStep !== null
+                ? error.nextStep
+                : "If the transaction reached the chain the storage may be bought; running the same " +
+                    "command again finds the record and does not sign a second registration for a part " +
+                    "that has one.",
+        });
+    }
+    record.registerTxDigest = registered.digest;
+    record.blobObjectId = registered.blobObjectId;
+    record.endEpoch = registered.endEpoch;
+    writeReservation(key, record, sealed);
+    ctx.onSpend({
+        walFrost: quote.writeFrost + (ctx.storage.kind === "buy" ? quote.storageFrost : 0n),
+        suiMist: quote.tipMist + (ctx.feeMist ?? 0n),
+    });
+    const certificate = await push(input, record, registered.digest, registered.blobObjectId, sealed);
+    await certify(ctx, input, key, record, certificate);
+    return paidPart(readReservationRecord(key) ?? record, false);
+}
+/** The bytes to the relay named in the register transaction. The storage is already bought. */
+async function push(input, record, registerTxDigest, blobObjectId, sealed) {
+    input.onStep?.({ step: "uploading", relayUrl: record.relayUrl, bytes: sealed.length });
+    try {
+        return await input.protocol.uploadToRelay({
+            blobId: record.blobId,
+            bytes: sealed,
+            nonce: new Uint8Array(Buffer.from(record.nonceB64, "base64url")),
+            registerTxDigest,
+            blobObjectId,
+        });
+    }
+    catch (error) {
+        throw new UploadError({
+            phase: "uploading",
+            message: `Uploading to the storage network failed: ${why(error)}`,
+            paid: true,
+            nextStep: "The storage is already bought and the tip is paid. Running the same command again pushes " +
+                "the same bytes to the same relay and signs nothing more for it.",
+        });
+    }
+}
+/** The second signature. Gas only. Written down before returning so a rerun never certifies twice. */
+async function certify(ctx, input, key, record, certificate) {
+    if (record.blobObjectId === undefined)
+        throw new NmtsError("unreachable: certifying a part with no blob object");
+    input.onStep?.({ step: "certifying" });
+    let digest;
+    try {
+        digest = await ctx.signCertify({
+            network: ctx.network,
+            code: ctx.code,
+            relayUrl: record.relayUrl,
+            blobId: record.blobId,
+            blobObjectId: record.blobObjectId,
+            certificate,
+        });
+    }
+    catch (error) {
+        throw new UploadError({
+            phase: "certify",
+            message: why(error),
+            paid: true,
+            nextStep: error instanceof NmtsError && error.nextStep !== null
+                ? error.nextStep
+                : "The bytes are on the network and the storage is bought. Running the same command again " +
+                    "certifies again, which costs gas and nothing else.",
+        });
+    }
+    writeReservation(key, { ...record, certifyTxDigest: digest }, readReservationBytes(key));
+    // The certify fee is not measured beforehand, so the ledger is told about the tip and the
+    // register fee only — the review said so.
+}
+/** What the commit needs about a finished part — off the RECORD, never off the run. */
+function paidPart(record, resumed) {
+    return {
+        partIndex: record.partIndex,
+        ledgerId: null,
+        blobId: record.blobId,
+        sealedLen: record.sealedLen,
+        resumed,
+        ...(record.blobObjectId !== undefined ? { suiObjectId: record.blobObjectId } : {}),
+        ...(record.endEpoch !== undefined ? { endEpoch: record.endEpoch } : {}),
+    };
+}

package/dist/upload-wire.d.ts

@@ -0,0 +1,244 @@
+import { NmtsError } from "./errors.ts";
+/** What the storage network's encoder says about one sealed blob, before anything is bought. */
+export interface BlobMeta {
+    /** The network's own id for these bytes. Deterministic in (bytes, nonce). */
+    blobId: string;
+    /** Merkle root of the encoded blob. Handed to the chain service verbatim. */
+    rootHash: Uint8Array;
+    /** The relay tip nonce. Random on a first encode, re-fed on a retry so the digest repeats. */
+    nonce: Uint8Array;
+    /** What the relay checks the paid tip against. */
+    blobDigest: Uint8Array;
+}
+/** What the storage nodes signed. Passed to the server unread — this tool never interprets it. */
+export interface Certificate {
+    signers: number[];
+    serialized_message_b64: string;
+    signature_b64: string;
+}
+/** The Walrus protocol seam. The real one is in `walrus-write.ts`; the tests supply a fake. */
+export interface BlobProtocol {
+    computeMetadata(input: {
+        bytes: Uint8Array;
+        nonce?: Uint8Array | undefined;
+    }): Promise<BlobMeta>;
+    uploadToRelay(input: {
+        blobId: string;
+        bytes: Uint8Array;
+        nonce: Uint8Array;
+        registerTxDigest: string;
+        blobObjectId: string;
+    }): Promise<Certificate>;
+}
+/** The reservation as the server describes it. */
+export interface ReserveReply {
+    ledger_id: number;
+    state: string;
+    blob_object_id?: string;
+    register_tx_digest?: string;
+    credits_spent: number;
+}
+/** The resume surface. */
+export interface StatusReply {
+    ledger_id: number;
+    state: string;
+    blob_object_id?: string;
+    register_tx_digest?: string;
+}
+/** The api calls this rail makes. */
+export interface UploadApi {
+    reserve(body: {
+        idempotency_key: string;
+        blob_id: string;
+        root_hash_b64: string;
+        size: number;
+        epochs: number;
+        /**
+         * How many credits this file sets aside as a deposit, 0 to 64.
+         *
+         * ⛔ ALWAYS SENT, NEVER LEFT TO THE SERVER'S DEFAULT. The number is a choice — the upload's
+         *    own `--deposit`, or the account's sealed default — and the price this tool printed named
+         *    it. A request that omitted it would let a server default decide an amount the person had
+         *    already been told, which is how a screen and a ledger come to disagree.
+         */
+        deposit_credits: number;
+        relay: {
+            host: string;
+            blob_digest_b64: string;
+            nonce_b64: string;
+        };
+    }): Promise<ReserveReply>;
+    status(ledgerId: number): Promise<StatusReply>;
+    uploaded(ledgerId: number, certificate: Certificate): Promise<unknown>;
+    createItem(body: {
+        size: number;
+        dek_wrapped: string;
+        content_hash_ct: string;
+        visibility: number;
+        parts: readonly Record<string, unknown>[];
+    }, idempotencyKey: string): Promise<{
+        id: string;
+    }>;
+}
+/** Where an upload stopped. The phase is what makes the message say the right true thing. */
+export type UploadPhase = "encoding" | "reserve" | "uploading" | "certify" | "committing";
+/** Told about each step, so a person watching a slow upload sees it moving. */
+export type UploadStep = {
+    step: "encoding";
+    bytes: number;
+} | {
+    step: "reserving";
+} | {
+    step: "uploading";
+    relayUrl: string;
+    bytes: number;
+} | {
+    step: "certifying";
+} | {
+    step: "committing";
+} | {
+    step: "resuming";
+    ledgerId: number;
+    state: string;
+};
+/**
+ * A failure that names its phase — and, crucially, whether the account has already paid.
+ *
+ * ⛔ `paid` IS NOT COSMETIC. Before the reserve, a failure costs nothing and "try again" is honest
+ *    advice. After it, the credits are gone and the storage exists; the honest advice is that the
+ *    same command will FINISH it rather than buy it again, and that saying otherwise would send
+ *    somebody to spend twice.
+ */
+export declare class UploadError extends NmtsError {
+    readonly phase: UploadPhase;
+    readonly paid: boolean;
+    constructor(input: {
+        phase: UploadPhase;
+        message: string;
+        paid: boolean;
+        nextStep?: string | null;
+    });
+}
+/**
+ * What making the FILE needs — everything that is true of the whole upload rather than one part.
+ *
+ * ⛔ THE ENTRY IS NOT REBUILT PER RUN. What is stored on the network is one particular sealing of
+ *    the file, under one particular file key. A resumed run that wrote its own freshly generated
+ *    key into the list would produce a file that is paid for, present, correctly named — and
+ *    impossible to open, because the key in the list would not be the key the bytes were sealed
+ *    with. It comes off the record that was written before the first reservation.
+ */
+export interface CommitInput {
+    api: UploadApi;
+    /** Storage term in storage-network epochs. */
+    epochs: number;
+    /** The current storage-network epoch, or null when it could not be read. */
+    currentEpoch: number | null;
+    /** Everything the file list will need, carried through so a resumed run writes the same entry. */
+    entry: {
+        name: string;
+        parentId: string | null;
+        plaintextLen: number;
+        dekWrapped: string;
+        contentHashCt: string;
+    };
+    onStep?: (step: UploadStep) => void;
+}
+export interface UploadInput extends CommitInput {
+    protocol: BlobProtocol;
+    /** The stable, account-scoped name for THIS PART — see `upload-store.ts`. */
+    key: string;
+    /**
+     * The sealed NCF-3 stream for this part. These exact bytes are what gets stored.
+     *
+     * ⛔ ON A RESUME THE CALLER MUST PASS THE STORED BYTES, not a fresh sealing. Sealing is
+     *    non-deterministic — a new file key and a new nonce every time — so re-sealing produces a
+     *    DIFFERENT blob id, and the relay refuses bytes that are not the blob the treasury paid to
+     *    register. `upload-store.ts` keeps them for exactly this.
+     */
+    sealed: Uint8Array;
+    /** How many credits this file sets aside as a deposit, 0 to 64. Passed straight to the reserve. */
+    depositCredits: number;
+    /**
+     * The relay this run writes through when the reservation is new.
+     *
+     * ⚠ IGNORED ON A RESUME. The tip was paid to whichever relay the first attempt chose, and it is
+     *   recorded; pushing to a different one is pushing bytes nobody tipped that relay for.
+     */
+    relayUrl: string;
+    /**
+     * Where these sealed bytes sit in the file. A file that fits in one blob is part 0 of 1.
+     *
+     * ⛔ IT IS ALREADY SEALED INTO THE BYTES. NCF-3 writes both numbers into the part's header, so
+     *    this is not where the placement is decided — it is a copy the record keeps so a resumed run
+     *    can check it is about to push the same piece of the same file.
+     */
+    part: {
+        index: number;
+        total: number;
+        plaintextLen: number;
+    };
+}
+/**
+ * ONE part that is bought, pushed and certified — everything the commit needs to name it.
+ *
+ * ⛔ IT IS NOT A FINISHED FILE. Nothing in the account can see these bytes yet: a file becomes
+ *    real when `POST /v1/items` names every one of its parts at once. A part that stopped here is
+ *    storage that is paid for and filled, waiting for the rest of the file.
+ */
+export interface PaidPart {
+    /** Its position in the file. */
+    partIndex: number;
+    /**
+     * The reservation row that paid for it — or null when the person's OWN WALLET paid.
+     *
+     * ⛔ THE ONE FIELD THAT SAYS WHO PAID. The server forces treasury ownership only on a part that
+     *    names a certified reservation; a part without one is the person's, and the commit says
+     *    nothing else about it (`upload-steps.ts`).
+     */
+    ledgerId: number | null;
+    /** The storage network's id for its sealed bytes. */
+    blobId: string;
+    /** How many sealed bytes it is — what the credits were charged on. */
+    sealedLen: number;
+    /** True when this run did not have to spend on it, because a previous one already had. */
+    resumed: boolean;
+    /** Wallet rail only: the on-chain blob object, recorded for the recovery list. */
+    suiObjectId?: string;
+    /** Wallet rail only: the epoch the bought storage ends at, read from the blob object. */
+    endEpoch?: number;
+}
+/** What finished. The caller writes the file list, THEN clears the records. */
+export interface UploadResult {
+    itemId: string;
+    /** True when no part of this run had to spend, because a previous one already had. */
+    resumed: boolean;
+    /** The reservation rows, for a message that can be checked against the account screen. Empty on the wallet rail. */
+    ledgerIds: readonly number[];
+    /**
+     * The account-scoped name this upload's records were filed under, and how many parts it had.
+     *
+     * ⛔ HANDED BACK RATHER THAN RECOMPUTED. Working it out again needs the account's data key and
+     *    another full read of the file, and the caller wipes that key the moment the upload returns.
+     *    A caller that could not name the records could not clear them, and an uncleared record is
+     *    resumed by the next run instead of being overwritten.
+     */
+    fileKey: string;
+    parts: number;
+    /**
+     * What the FILE LIST must record — taken from the reservation, not from this run.
+     *
+     * ⛔ THE CALLER MUST WRITE THESE AND NOT ITS OWN. What is stored on the network is one
+     *    particular sealing of the file, under one particular file key. A resumed run that wrote its
+     *    own freshly generated key into the list would produce a file that is paid for, present,
+     *    correctly named — and impossible to open, because the key in the list would not be the key
+     *    the stored bytes were sealed with. Returning them is what makes that mistake unavailable.
+     */
+    entry: {
+        name: string;
+        parentId: string | null;
+        plaintextLen: number;
+        dekWrapped: string;
+        contentHashCt: string;
+    };
+}