@needmoretruth/nmts-cli 0.34.4 → 0.35.0

package/dist/wallet.d.ts

@@ -1,16 +1,16 @@
 import { type CryptoGlue } from "./crypto.ts";
 import type { Network } from "./network.ts";
 /**
- * The wallet this NMTS key opens by itself.
+ * The wallet this NMTS key opens by itself, when nobody has said which one.
  *
- * ⛔ IT IS WALLET 0 BECAUSE THAT IS THE ONE THE BROWSER OPENS. Every wallet, including this one,
- *    comes out of `wallet_seed_for` — there is no special case for the first — so the index is the
- *    whole of the difference between "the account's wallet" and somebody else's.
+ * ⛔ IT IS WALLET 0 BECAUSE THAT IS THE ONE EVERY ACCOUNT STARTS WITH. Every wallet, including this
+ *    one, comes out of `wallet_seed_for` — there is no special case for the first — so the index is
+ *    the whole of the difference between one wallet of this key and another.
  *
- * ⛔ EXPORTED SO THE SIGNER CANNOT PICK ITS OWN. `extend-sign.ts` derives a keypair from the same
- *    root and has to reach the SAME wallet as the address printed here; a second literal `0` over
- *    there would be a second answer to a question with one right one, and the failure is silent —
- *    a signature from an address nobody funded. `extend-sign.test.ts` compares the two.
+ * ⚠ IT IS THE OFFLINE ANSWER, NOT THE PAYING ONE (2026-09-16). `nmts wallet address` asks
+ *   nothing of anybody and so cannot know which wallet the account pays from; every command that
+ *   SPENDS reads that number out of the sealed file list first (`wallet-pay-index.ts`) and refuses
+ *   rather than falling back here — paying from the wrong wallet is not a thing to guess at.
  */
 export declare const BUILT_IN_WALLET_INDEX = 0;
 /** The chain's own coin. Its type is fixed by the chain itself and takes no network. */
@@ -50,12 +50,12 @@ export declare function walCoinType(network: Network): string;
  */
 export declare function addressFromSeed(seed: Uint8Array): string;
 /**
- * The address of the wallet this NMTS key derives. Offline: nothing is asked of anybody.
+ * The address of one of the wallets this NMTS key derives. Offline: nothing is asked of anybody.
  *
- * The same address on every network — an account has one wallet, and which chain it is looked up
- * on is a separate question from what it is called.
+ * The same address on every network — a wallet is the same wallet on every chain, and which chain
+ * it is looked up on is a separate question from what it is called.
  */
-export declare function walletAddress(code: string): Promise<string>;
+export declare function walletAddress(code: string, index?: number): Promise<string>;
 /**
  * The engine functions this module uses. Narrowed to the one it actually calls.
  *
@@ -73,7 +73,7 @@ export type WalletGlue = Pick<CryptoGlue, "wallet_seed_for">;
  *    engine expands from it — are wiped before it returns, on the failing path as well as the
  *    good one. Neither one leaves.
  */
-export declare function addressFromDerived(glue: WalletGlue, derived: Uint8Array): string;
+export declare function addressFromDerived(glue: WalletGlue, derived: Uint8Array, index?: number): string;
 /**
  * How much of one coin an address holds, exactly as the chain reported it — or why nobody knows.
  *

package/dist/wallet.js

@@ -19,16 +19,16 @@ import { assertUsableCode } from "./account.js";
 import { DERIVED, loadCrypto } from "./crypto.js";
 import { NmtsError } from "./errors.js";
 /**
- * The wallet this NMTS key opens by itself.
+ * The wallet this NMTS key opens by itself, when nobody has said which one.
  *
- * ⛔ IT IS WALLET 0 BECAUSE THAT IS THE ONE THE BROWSER OPENS. Every wallet, including this one,
- *    comes out of `wallet_seed_for` — there is no special case for the first — so the index is the
- *    whole of the difference between "the account's wallet" and somebody else's.
+ * ⛔ IT IS WALLET 0 BECAUSE THAT IS THE ONE EVERY ACCOUNT STARTS WITH. Every wallet, including this
+ *    one, comes out of `wallet_seed_for` — there is no special case for the first — so the index is
+ *    the whole of the difference between one wallet of this key and another.
  *
- * ⛔ EXPORTED SO THE SIGNER CANNOT PICK ITS OWN. `extend-sign.ts` derives a keypair from the same
- *    root and has to reach the SAME wallet as the address printed here; a second literal `0` over
- *    there would be a second answer to a question with one right one, and the failure is silent —
- *    a signature from an address nobody funded. `extend-sign.test.ts` compares the two.
+ * ⚠ IT IS THE OFFLINE ANSWER, NOT THE PAYING ONE (2026-09-16). `nmts wallet address` asks
+ *   nothing of anybody and so cannot know which wallet the account pays from; every command that
+ *   SPENDS reads that number out of the sealed file list first (`wallet-pay-index.ts`) and refuses
+ *   rather than falling back here — paying from the wrong wallet is not a thing to guess at.
  */
 export const BUILT_IN_WALLET_INDEX = 0;
 /**
@@ -83,12 +83,12 @@ export function addressFromSeed(seed) {
     return Ed25519Keypair.fromSecretKey(seed).toSuiAddress();
 }
 /**
- * The address of the wallet this NMTS key derives. Offline: nothing is asked of anybody.
+ * The address of one of the wallets this NMTS key derives. Offline: nothing is asked of anybody.
  *
- * The same address on every network — an account has one wallet, and which chain it is looked up
- * on is a separate question from what it is called.
+ * The same address on every network — a wallet is the same wallet on every chain, and which chain
+ * it is looked up on is a separate question from what it is called.
  */
-export async function walletAddress(code) {
+export async function walletAddress(code, index = BUILT_IN_WALLET_INDEX) {
     // ⛔ The one refusal text for a malformed code lives in `account.ts`. Checking here means a typo
     //    fails the same way it fails everywhere else in this tool rather than as an engine error.
     await assertUsableCode(code);
@@ -108,7 +108,7 @@ export async function walletAddress(code) {
     //    everything sliced out of it, on the failing paths as well as the good one.
     const derived = glue.kdf_derive(bytes);
     try {
-        return addressFromDerived(glue, derived);
+        return addressFromDerived(glue, derived, index);
     }
     finally {
         derived.fill(0);
@@ -123,12 +123,12 @@ export async function walletAddress(code) {
  *    engine expands from it — are wiped before it returns, on the failing path as well as the
  *    good one. Neither one leaves.
  */
-export function addressFromDerived(glue, derived) {
+export function addressFromDerived(glue, derived, index = BUILT_IN_WALLET_INDEX) {
     const [from, to] = DERIVED.walletRoot;
     const root = derived.slice(from, to);
     let seed = null;
     try {
-        seed = glue.wallet_seed_for(root, BUILT_IN_WALLET_INDEX);
+        seed = glue.wallet_seed_for(root, index);
         return addressFromSeed(seed);
     }
     finally {

package/docs/commands/wallet.md

@@ -1,12 +1,26 @@
 # nmts wallet — the wallet your NMTS key derives
 
 Commands: wallet
-Tiers: wallet=none · wallet.send=high(wallet) · wallet.swap=high(wallet) · wallet.donate=high(donate) · wallet.storage.reshape=high(wallet) · wallet.storage.give=high(wallet) · wallet.hall=none · wallet.hall.set=medium
+Tiers: wallet=none · wallet.use=low · wallet.send=high(wallet) · wallet.swap=high(wallet) · wallet.donate=high(donate) · wallet.storage.reshape=high(wallet) · wallet.storage.give=high(wallet) · wallet.hall=none · wallet.hall.set=medium
 
 `wallet` shows the address and its SUI and WAL balances; `wallet address` derives the address
-offline (`--qr` draws it); `wallet activity` lists recent transactions, named only where the chain
-proves it; `wallet storage` lists storage resources (size × time) held outside any file. None of
-these signs.
+offline (`--qr` draws it, `--index N` derives another of this key's wallets); `wallet activity`
+lists recent transactions, named only where the chain proves it; `wallet storage` lists storage
+resources (size × time) held outside any file. None of these signs.
+
+## One key, many wallets
+
+Your NMTS key derives a wallet at every number from 0 upwards, and one of them pays. `wallet list`
+walks them — it shows each number, its address and its balances, marks the one that pays, and stops
+after twenty unused wallets in a row. `wallet use <number>` moves which one pays: the number is
+kept inside your sealed file list, so the browser, this tool and every other device agree on it.
+Numbers come from the key, so a wallet cannot be deleted, and a wallet you leave keeps whatever is
+in it.
+
+`put`, `push`, `extend`, `wallet send` and `wallet donate` all pay from that wallet, and each takes
+`--wallet <number>` to pay from a different one for that run only, without changing the setting.
+⛔ If the file list cannot be read, they refuse rather than falling back to wallet 0 — paying from
+a wallet nobody chose is not a thing to guess at.
 
 ## Where SUI comes from, and why it is SUI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needmoretruth/nmts-cli",
-  "version": "0.34.4",
+  "version": "0.35.0",
   "description": "Command-line and MCP access to NMTS (NeedMoreTruthStorage, https://nmts.me): open-source, end-to-end encrypted storage on the Walrus network. No fee to NMTS; you pay the network from your own wallet. For people and for their agents.",
   "license": "Apache-2.0",
   "publishConfig": {