@needmoretruth/nmts-cli 0.34.4 → 0.35.0

package/dist/shared/lib/drive/manifest-settings.d.ts

@@ -51,12 +51,58 @@ export interface AccountSettings {
      * = never agreed: raising the tip above 0 asks for that agreement once, and later changes do not.
      */
     tipConsentAt?: number;
+    /**
+     * WHICH WALLET PAYS — the index the NMTS key derives it at (NCF-3 §1.3, `walletSeed(N)`). Absent
+     * = 0, the wallet every account has had since the beginning.
+     *
+     * ⛔ HERE, IN THE SEALED LIST, AND NOT BESIDE THE derived/imported SWITCH. That switch is about
+     * this DEVICE (which key this browser opens), so it lives in device storage; the number is about
+     * the ACCOUNT — it decides which address the storage is paid from, and a phone and a laptop that
+     * disagreed about it would spend from two different balances for one person.
+     *
+     * Whole, 0 to just under 2^31: the format derives a wallet at every index and this is the range
+     * an index is written in.
+     */
+    activeWallet?: number;
+    /**
+     * HOW MANY WALLETS THIS ACCOUNT HAS MADE — the list the wallets screen draws, 1 to 1000. Absent
+     * = 1, the one wallet an account starts with.
+     *
+     * ⚠ IT IS A COUNT, NOT A SET. Numbers come from the key, so a wallet cannot be deleted and the
+     * list is always 0…count-1; "making the next wallet" is this number going up by one, and a scan
+     * that finds a funded wallet further out pulls it up to that number + 1.
+     */
+    walletCount?: number;
 }
 /** The sanity bounds a stored text scale must sit in to be USED. One place; codec and UI agree. */
 export declare const TEXT_SCALE_MIN_PCT = 80;
 export declare const TEXT_SCALE_MAX_PCT = 160;
 /** Follow the device. Not written to the wire — absence is the only spelling of it. */
 export declare const TEXT_SCALE_DEFAULT_PCT = 100;
+/**
+ * The index range a wallet number is written in: whole, 0 to just under 2^31.
+ *
+ * ⛔ THE CEILING IS THE WIRE'S, NOT THE FORMAT'S. `walletSeed(N)` is defined for every N the
+ * engine can be handed; what is bounded here is what this build will WRITE and read back, so a
+ * number some other build miswrote cannot come back as something no screen can draw.
+ */
+export declare const WALLET_INDEX_LIMIT: number;
+/** The wallet an account pays from when nobody chose. Not written to the wire — absence spells it. */
+export declare const ACTIVE_WALLET_DEFAULT = 0;
+/** The most wallets one account's list holds. */
+export declare const WALLET_COUNT_MAX = 1000;
+/** What an account's list holds before anybody made a second one. Absence spells it. */
+export declare const WALLET_COUNT_DEFAULT = 1;
+/** Which wallet this account pays from. Absence is wallet 0, never "unknown". */
+export declare function activeWalletOf(settings: AccountSettings | null | undefined): number;
+/**
+ * How many wallets this account's list holds.
+ *
+ * ⛔ THE INVARIANT LIVES HERE: the paying wallet is always IN the list. A stored count that does
+ * not reach the active number is raised to hold it — never the other way round, because lowering
+ * it would hide a wallet somebody is paying from, and a wallet cannot be deleted anyway.
+ */
+export declare function walletCountOf(settings: AccountSettings | null | undefined): number;
 export interface WireSettings {
     /** developerMode. */
     dm?: 1;
@@ -84,6 +130,15 @@ export interface WireSettings {
     tp?: number;
     /** tipConsentAt. */
     tc?: number;
+    /** activeWallet, present only when it is not wallet 0. */
+    aw?: number;
+    /**
+     * walletCount, present only when the account has made more than one.
+     *
+     * ⚠ A count above the ceiling is DROPPED on both sides, and nothing is lost by that: the read
+     * below raises the count to hold `aw` again, so the paying wallet stays in the list either way.
+     */
+    wc?: number;
 }
 /** The most a standing tip can be: the whole payment. Above the dial's 10 % it is typed and confirmed. */
 export declare const TIP_TENTHS_MAX = 1000;
@@ -107,7 +162,3 @@ export declare function settingsToWire(s: AccountSettings | undefined): WireSett
  * to the device's own size, which is always readable.
  */
 export declare function settingsFromWire(w: unknown): AccountSettings | undefined;
-/** Folds a deposit patch into a settings copy: out-of-range is clamped, the full deposit clears. */
-export declare function applyDepositPatch(next: AccountSettings, depositDefault?: number): void;
-/** Folds a tip patch into a settings copy: 0 clears, above the cap is capped, fractions are rounded. */
-export declare function applyTipPatch(next: AccountSettings, tipTenths?: number, tipConsentAt?: number): void;

package/dist/shared/lib/drive/manifest-settings.js

@@ -14,6 +14,48 @@ export const TEXT_SCALE_MIN_PCT = 80;
 export const TEXT_SCALE_MAX_PCT = 160;
 /** Follow the device. Not written to the wire — absence is the only spelling of it. */
 export const TEXT_SCALE_DEFAULT_PCT = 100;
+/**
+ * The index range a wallet number is written in: whole, 0 to just under 2^31.
+ *
+ * ⛔ THE CEILING IS THE WIRE'S, NOT THE FORMAT'S. `walletSeed(N)` is defined for every N the
+ * engine can be handed; what is bounded here is what this build will WRITE and read back, so a
+ * number some other build miswrote cannot come back as something no screen can draw.
+ */
+export const WALLET_INDEX_LIMIT = 2 ** 31;
+/** The wallet an account pays from when nobody chose. Not written to the wire — absence spells it. */
+export const ACTIVE_WALLET_DEFAULT = 0;
+/** The most wallets one account's list holds. */
+export const WALLET_COUNT_MAX = 1000;
+/** What an account's list holds before anybody made a second one. Absence spells it. */
+export const WALLET_COUNT_DEFAULT = 1;
+/** Is this a wallet index this build writes and reads? */
+function usableWalletIndex(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value < WALLET_INDEX_LIMIT;
+}
+/** Is this a wallet count this build writes and reads? */
+function usableWalletCount(value) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= WALLET_COUNT_DEFAULT &&
+        value <= WALLET_COUNT_MAX);
+}
+/** Which wallet this account pays from. Absence is wallet 0, never "unknown". */
+export function activeWalletOf(settings) {
+    const stored = settings?.activeWallet;
+    return usableWalletIndex(stored) ? stored : ACTIVE_WALLET_DEFAULT;
+}
+/**
+ * How many wallets this account's list holds.
+ *
+ * ⛔ THE INVARIANT LIVES HERE: the paying wallet is always IN the list. A stored count that does
+ * not reach the active number is raised to hold it — never the other way round, because lowering
+ * it would hide a wallet somebody is paying from, and a wallet cannot be deleted anyway.
+ */
+export function walletCountOf(settings) {
+    const stored = settings?.walletCount;
+    const held = usableWalletCount(stored) ? stored : WALLET_COUNT_DEFAULT;
+    return Math.max(held, activeWalletOf(settings) + 1);
+}
 /** The most a standing tip can be: the whole payment. Above the dial's 10 % it is typed and confirmed. */
 export const TIP_TENTHS_MAX = 1000;
 /**
@@ -59,12 +101,18 @@ export function settingsToWire(s) {
     if (typeof s.tipConsentAt === "number" && Number.isFinite(s.tipConsentAt) && s.tipConsentAt > 0) {
         w.tc = Math.round(s.tipConsentAt);
     }
+    if (usableWalletIndex(s.activeWallet) && s.activeWallet !== ACTIVE_WALLET_DEFAULT)
+        w.aw = s.activeWallet;
+    if (usableWalletCount(s.walletCount) && s.walletCount !== WALLET_COUNT_DEFAULT)
+        w.wc = s.walletCount;
     return w.dm !== undefined ||
         w.tx !== undefined ||
         w.pd !== undefined ||
         w.dd !== undefined ||
         w.tp !== undefined ||
-        w.tc !== undefined
+        w.tc !== undefined ||
+        w.aw !== undefined ||
+        w.wc !== undefined
         ? w
         : null;
 }
@@ -84,6 +132,8 @@ export function settingsFromWire(w) {
     const dd = Reflect.get(w, "dd");
     const tp = Reflect.get(w, "tp");
     const tc = Reflect.get(w, "tc");
+    const aw = Reflect.get(w, "aw");
+    const wc = Reflect.get(w, "wc");
     const s = {};
     if (dm === 1)
         s.developerMode = true;
@@ -109,38 +159,26 @@ export function settingsFromWire(w) {
         s.tipTenths = tp;
     if (typeof tc === "number" && Number.isFinite(tc) && tc > 0)
         s.tipConsentAt = Math.round(tc);
+    // A wallet number outside the range is DROPPED, not clamped: paying from a wallet some other
+    // build miswrote would spend from an address this person has never seen, and wallet 0 is the one
+    // every account already has.
+    if (usableWalletIndex(aw) && aw !== ACTIVE_WALLET_DEFAULT)
+        s.activeWallet = aw;
+    if (usableWalletCount(wc) && wc !== WALLET_COUNT_DEFAULT)
+        s.walletCount = wc;
+    // ⛔ AND THE INVARIANT IS RESTORED HERE, UPWARDS ONLY (`walletCountOf`). A list whose count does
+    // not reach the paying wallet would draw a screen the paying wallet is missing from.
+    const counted = walletCountOf(s);
+    if (counted !== WALLET_COUNT_DEFAULT)
+        s.walletCount = counted;
     return s.developerMode !== undefined ||
         s.textScalePct !== undefined ||
         s.paddingMode !== undefined ||
         s.depositDefault !== undefined ||
         s.tipTenths !== undefined ||
-        s.tipConsentAt !== undefined
+        s.tipConsentAt !== undefined ||
+        s.activeWallet !== undefined ||
+        s.walletCount !== undefined
         ? s
         : undefined;
 }
-/** Folds a deposit patch into a settings copy: out-of-range is clamped, the full deposit clears. */
-export function applyDepositPatch(next, depositDefault) {
-    if (depositDefault === undefined || !Number.isFinite(depositDefault))
-        return;
-    const credits = Math.round(Math.min(DEPOSIT_MAX_CREDITS, Math.max(0, depositDefault)));
-    if (credits === DEPOSIT_DEFAULT_CREDITS)
-        delete next.depositDefault;
-    else
-        next.depositDefault = credits;
-}
-/** Folds a tip patch into a settings copy: 0 clears, above the cap is capped, fractions are rounded. */
-export function applyTipPatch(next, tipTenths, tipConsentAt) {
-    if (tipTenths !== undefined && Number.isFinite(tipTenths)) {
-        const t = Math.round(Math.min(TIP_TENTHS_MAX, Math.max(0, tipTenths)));
-        if (t === 0)
-            delete next.tipTenths;
-        else
-            next.tipTenths = t;
-    }
-    if (tipConsentAt !== undefined && Number.isFinite(tipConsentAt)) {
-        if (tipConsentAt <= 0)
-            delete next.tipConsentAt;
-        else
-            next.tipConsentAt = Math.round(tipConsentAt);
-    }
-}

package/dist/shared/lib/wallet/discover.d.ts

@@ -0,0 +1,54 @@
+/**
+ * How many unused wallets in a row end the walk.
+ *
+ * ⛔ TWENTY, THE SAME NUMBER EVERY OTHER WALLET USES. Somebody who has funded a wallet in another
+ *    tool and comes looking for it here has been taught what a scan finds by that tool; a different
+ *    number here would make the same key look like it holds different wallets in two programs.
+ */
+export declare const WALLET_SCAN_GAP = 20;
+/** What a walk found: the wallets that are in use, lowest first, and how many were asked about. */
+export interface WalletScan {
+    /** Every index the probe said was in use, ascending. */
+    readonly used: readonly number[];
+    /** How many times the probe was called — what the walk cost, in questions. */
+    readonly scanned: number;
+}
+/**
+ * Is this wallet IN USE? Answered by the caller, because what counts as "in use" is a question
+ * about a chain and this file has none: a balance in either coin, or any transaction the address
+ * has ever been in.
+ *
+ * ⚠ A PROBE THAT FAILS SHOULD THROW, not answer `false`. "Nobody could ask" and "nothing is there"
+ *   are opposite facts, and answering the second for the first would quietly end the walk early and
+ *   report a wallet with money in it as one that does not exist.
+ */
+export type WalletProbe = (index: number) => Promise<boolean>;
+/**
+ * Walk the wallets of one NMTS key from 0 upwards, and stop when the walk has learned enough.
+ *
+ * TWO RULES, AND THEY ARE DIFFERENT RULES:
+ *   · every wallet the account has already MADE is asked about, whatever the answers are. Those
+ *     wallets are on the person's screen; a walk that skipped one because its neighbour was empty
+ *     would be reporting about a wallet it never asked about.
+ *   · past those, the walk keeps going as long as it keeps finding wallets in use, and ends after
+ *     `gap` unused ones in a row.
+ *
+ * ⚠ THE RUN CARRIES OVER from the made wallets into the walk past them. A list of thirty wallets
+ *   nobody ever funded is thirty unused answers, and starting the count again at the end of it
+ *   would ask for twenty more that nobody has any reason to expect anything from.
+ */
+export declare function discoverWallets(probe: WalletProbe, { count, gap }: {
+    count: number;
+    gap?: number;
+}): Promise<WalletScan>;
+/**
+ * How far a walk can reach as it stands — the number a progress line counts towards.
+ *
+ * ⛔ IT MOVES, because the walk's end moves: finding a wallet in use buys another `gap` questions
+ *    past it. A progress line drawn against the number the walk STARTED with would sit at "20/20"
+ *    while the walk kept going, which reads as a screen that has stopped answering.
+ */
+export declare function walletScanReach({ count, gap }: {
+    count: number;
+    gap?: number;
+}, highestUsed: number | null): number;

package/dist/shared/lib/wallet/discover.js

@@ -0,0 +1,66 @@
+// Finding the wallets an NMTS key has already used — the scan every HD wallet does, and where it
+// stops. ⚠ PUBLISHED — copied byte-for-byte into the `nmts` command-line package; keep comments
+// self-contained English.
+//
+// ⛔ PURE, AND THAT IS THE WHOLE POINT. One NMTS key derives a wallet at every index (NCF-3 §1.3),
+//    so "which of them exist" is not a question anybody can answer by looking: nothing is
+//    registered anywhere, and an unused wallet and a wallet nobody has funded yet are the same
+//    thing. The answer is a WALK — ask about one number, then the next — and the only real decision
+//    in it is when to stop. That decision is arithmetic, so it is written here, once, with no
+//    chain, no fetch and no clock in it; the browser and the `nmts` command each bring their own
+//    `probe` and get the same answer out.
+//
+// ⛔ WHY IT STOPS AT ALL. The index space is unbounded, so a walk that asked for proof of absence
+//    would never end. Stopping after a run of unused wallets is what every HD wallet does (the
+//    convention BIP-44 §Address gap limit wrote down), and the cost of the rule is stated rather
+//    than hidden: a wallet funded further out than the gap is NOT found by a scan. It is not lost —
+//    numbers come from the key, so asking for that number directly still opens it.
+/**
+ * How many unused wallets in a row end the walk.
+ *
+ * ⛔ TWENTY, THE SAME NUMBER EVERY OTHER WALLET USES. Somebody who has funded a wallet in another
+ *    tool and comes looking for it here has been taught what a scan finds by that tool; a different
+ *    number here would make the same key look like it holds different wallets in two programs.
+ */
+export const WALLET_SCAN_GAP = 20;
+/**
+ * Walk the wallets of one NMTS key from 0 upwards, and stop when the walk has learned enough.
+ *
+ * TWO RULES, AND THEY ARE DIFFERENT RULES:
+ *   · every wallet the account has already MADE is asked about, whatever the answers are. Those
+ *     wallets are on the person's screen; a walk that skipped one because its neighbour was empty
+ *     would be reporting about a wallet it never asked about.
+ *   · past those, the walk keeps going as long as it keeps finding wallets in use, and ends after
+ *     `gap` unused ones in a row.
+ *
+ * ⚠ THE RUN CARRIES OVER from the made wallets into the walk past them. A list of thirty wallets
+ *   nobody ever funded is thirty unused answers, and starting the count again at the end of it
+ *   would ask for twenty more that nobody has any reason to expect anything from.
+ */
+export async function discoverWallets(probe, { count, gap = WALLET_SCAN_GAP }) {
+    const used = [];
+    let scanned = 0;
+    let unusedInARow = 0;
+    for (let index = 0; index < count || unusedInARow < gap; index += 1) {
+        const inUse = await probe(index);
+        scanned += 1;
+        if (inUse) {
+            used.push(index);
+            unusedInARow = 0;
+        }
+        else {
+            unusedInARow += 1;
+        }
+    }
+    return { used, scanned };
+}
+/**
+ * How far a walk can reach as it stands — the number a progress line counts towards.
+ *
+ * ⛔ IT MOVES, because the walk's end moves: finding a wallet in use buys another `gap` questions
+ *    past it. A progress line drawn against the number the walk STARTED with would sit at "20/20"
+ *    while the walk kept going, which reads as a screen that has stopped answering.
+ */
+export function walletScanReach({ count, gap = WALLET_SCAN_GAP }, highestUsed) {
+    return Math.max(count, highestUsed === null ? 0 : highestUsed + 1) + gap;
+}

package/dist/standing-tip.d.ts

@@ -15,6 +15,9 @@ export interface StandingTipInput {
     } | undefined;
     /** What was just paid for storage, in WAL base units. */
     paidWalFrost: bigint;
+    /** ⛔ The wallet the storage was just paid from — a gift from a different one would come out of
+     *  a balance nobody was looking at, and the payment above named this one. */
+    wallet: number;
     say: (line: string) => void;
     /** Seams for tests. */
     readDonation?: (server: string) => Promise<DonationConfig>;

package/dist/standing-tip.js

@@ -37,6 +37,7 @@ export async function standingTipAfter(input) {
         const digest = await sign({
             network: input.network,
             code: input.code,
+            wallet: input.wallet,
             shape: { coin: "WAL", amountBaseUnits: amount, destination: config.devAddress, walType: walCoinType(input.network) },
         });
         input.say(`  Your standing ${percentText(tenths)} % gift — ${coinAmount(amount)} WAL — went to the developer. Transaction ${digest}`);

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

@@ -0,0 +1,118 @@
+import type { OnCollision } from "./collision.ts";
+import { type CryptoGlue } from "./crypto.ts";
+import type { Network } from "./network.ts";
+import type { PaddingRule } from "./shared/lib/crypto/size-padding.ts";
+import { type FileUploadStep, type PlaintextSource } from "./upload-file.ts";
+import { type StorageChoice, type UploadBudget, type WalletUploadReads } from "./upload-wallet-plan.ts";
+import type { BlobProtocol, UploadApi } from "./upload-wire.ts";
+import type { Spend } from "./wallet-grant.ts";
+import type { SignBlobCertify, SignBlobRegister } from "./wallet-sign.ts";
+/** The account this upload belongs to, and how it seals. */
+export interface WalletPutContext {
+    /** ⛔ The NMTS key. It seals the file AND derives the wallet that pays. It is never written down. */
+    code: string;
+    apiKey: string;
+    server: string;
+    network: Network;
+    accountId: string;
+    crypt: CryptoGlue;
+    /** How much of the file goes into one part. */
+    partSize: number;
+    /** The rounding rule from the account's sealed list — it changes the stored size, so the price. */
+    rule: PaddingRule;
+    /** What to do about a name already in use. Absent = the machine's setting, as `addEntry` reads it. */
+    onCollision?: OnCollision | undefined;
+    /**
+     * Which of this key's wallets pays, by index (0 = the first one).
+     *
+     * ⛔ THE CALLER RESOLVES IT, BEFORE ANYTHING IS PRICED. It is the account's own number, kept in
+     *    the sealed file list (`wallet-pay-index.ts`), and a library that guessed at it here would
+     *    price one address and sign with another.
+     */
+    wallet: number;
+}
+/** One file and where it goes — already resolved, because a library resolves nothing by asking. */
+export interface WalletPutFile {
+    source: PlaintextSource;
+    name: string;
+    parentId: string | null;
+    /** The destination AS TYPED — part of the reservation key, so both runs of a resume agree. */
+    destination: string;
+}
+/** The chain, the signatures, the wire and the four things a caller may be told. */
+export interface WalletPutSeams {
+    /** How many of the storage network's epochs to buy. Default `DEFAULT_UPLOAD_EPOCHS`. */
+    epochs?: string | number | undefined;
+    /** `fit`, `whole`, or a held resource's object id. Absent = buy new storage. */
+    storage?: string | undefined;
+    /** Stop at the review. Nothing is sealed, signed or sent, and no signer is even loaded. */
+    dryRun?: boolean | undefined;
+    /** ⚠ A SEAM, NOT AN OPTION — what the chain is asked. */
+    readChain?: ((network: Network, relayUrl: string) => WalletUploadReads | Promise<WalletUploadReads>) | undefined;
+    /** ⛔ SEPARATE FROM THE READS so a caller can prove the review stops before this. */
+    sign?: {
+        register: SignBlobRegister;
+        certify: SignBlobCertify;
+    } | undefined;
+    /** ⚠ SEAMS, NOT OPTIONS — the storage-network protocol and the server calls. */
+    protocol?: ((network: Network, bodyBytes: number, onSent: (sent: number, total: number) => void) => BlobProtocol & {
+        relayUrl: string;
+    }) | undefined;
+    api?: UploadApi | undefined;
+    /** Told as sealed bytes leave for the relay. */
+    onProgress?: ((sent: number, total: number) => void) | undefined;
+    /** Told about each step as it starts. */
+    onStep?: ((step: FileUploadStep) => void) | undefined;
+    /** Told the numbers the moment they are known — before the dry run returns and before a refusal. */
+    onReview?: ((review: WalletPutReview) => void) | undefined;
+    /** ⛔ THE GATE. Throwing here stops the upload with nothing signed. See the module header. */
+    agree?: ((review: WalletPutReview) => void) | undefined;
+    /** Told what left the wallet, after each signature. */
+    onSpend?: ((spend: Spend) => void) | undefined;
+}
+/** What this upload would buy, in the order somebody deciding needs it. Base units throughout. */
+export interface WalletPutReview {
+    name: string;
+    /** Plaintext bytes. */
+    bytes: number;
+    /** Bytes the storage network holds, padding and sealing included. */
+    sealedBytes: number;
+    parts: number;
+    epochs: number;
+    /** The term in days, read from the network's own clock. */
+    days: string;
+    /** The epoch the storage runs to. */
+    endEpoch: number;
+    /** The relay's tip over every part, in MIST. Paid inside the register signatures. */
+    tipMist: bigint;
+    /** Where the storage comes from. */
+    storage: StorageChoice;
+    /** Free storage resources the wallet holds when none was asked for; null when unreadable. */
+    heldResources: number | null;
+    /** The wallet against the price: what is needed, what is held, and the shortfall if there is one. */
+    budget: UploadBudget;
+}
+/** A dry run's answer, or a finished upload's. The review is in both, so both report one price. */
+export type WalletPutOutcome = {
+    kind: "review";
+    review: WalletPutReview;
+} | {
+    kind: "uploaded";
+    review: WalletPutReview;
+    itemId: string;
+    /** The name it got — numbered if the one asked for was taken. */
+    savedAs: string;
+    /** The id of the file this one displaced into the trash, when the machine overwrites. */
+    replaced: string | null;
+    /** The file-list version this write produced. */
+    fileListVersion: number;
+    /** True when every part was already signed for by an earlier run: this call spent nothing. */
+    resumed: boolean;
+};
+/**
+ * Price, agree, sign, upload and record ONE file, paid from the wallet the NMTS key derives.
+ *
+ * ⛔ THE SIGNING MODULE IS LOADED ONLY AFTER `agree` HAS RETURNED. A dry run and a refusal never
+ *    bring the code that can spend into memory.
+ */
+export declare function walletPut(ctx: WalletPutContext, file: WalletPutFile, seams?: WalletPutSeams): Promise<WalletPutOutcome>;