nat-cli 0.0.3 → 0.3.0

package/llms.txt

@@ -0,0 +1,26 @@
+# bNAT
+
+> One NFT per BNB Smart Chain block (tokenId = block number), carrying the BNB that block burned under BEP-95, in gwei. Minting is limited to addresses holding a SPACE ID Agent ID (.ai) and is done by AI agents through the Binance Agentic Wallet with the bnat CLI. Wrap / unwrap and the bid-only market need no .ai and can be done on the website with an ordinary browser wallet, or by the agent with the bnat CLI.
+
+- Mint: any finalized BSC block since 13,082,000 with burn >= 1 gwei, once, first come first served. `mint(blk, burnGwei, sig, to)`: the caller must hold a .ai and is recorded as minter; the NFT goes to `to`, which can be any address. A signer attests the burn from the site's burn index (BSC finalized blocks, a few seconds behind); the CLI checks the signature is for this contract and recovers to its current signer.
+- Wrap: an NFT can be wrapped into the ERC-20 BNAT (bNAT), 1 BNAT = 1 BNB burned (1e9 gwei). The NFT moves into the BNAT vault; the wrapper gets 99%, 1% stays in the BNAT contract as a fee the developer can withdraw.
+- Unwrap: reversible. Anyone can take any block out of the vault by paying its burn + 1% in BNAT (the burn part is burned, the 1% stays as the fee); the NFT goes to the payer. `BNAT.quote(blk)` returns (amount, fee).
+- Market: bid-only. Buyers lock BNB at a per-BNAT price; holders sell into any bid, fully or partly; 1% of each fill goes to the developer address; unfilled BNB can be withdrawn by cancelling.
+- On-chain art: tokenURI returns metadata with an SVG sigil generated by the contract.
+
+## Agent
+
+- Install: `npm install -g nat-cli` (installs baw as a dependency), then the user runs `bnat` in a terminal and scans the QR with the Binance App, then `bnat wallet`.
+- Skill: SKILL.md (shipped in the nat-cli package and served at /skill/SKILL.md).
+- Commands: `bnat status | wallet | blocks | top | block --block N | holdings | vault | bids | history`, `bnat mint --block N | --best [--to ADDRESS]`, `bnat wrap --block N[,N2,…]` (up to 50 blocks in one transaction; BNAT always goes to the wrapping wallet), `bnat unwrap --block N[,N2,…]` (pays burn + 1% per block in BNAT, no approval; the NFTs go to the unwrapping wallet), `bnat bid --price P --amount A`, `bnat sell --bid ID --amount A | --all`, `bnat cancel --bid ID`, `bnat resume --hash 0x… | --abandon ID`, `bnat lang [zh|en]`, `bnat config [mintTo ADDRESS|self]`.
+- Writes run only with `--yes`, after the user approves the printed plan. Never resend; settle with `bnat resume`.
+
+## Read API (same origin as the site)
+
+- /api/v1/status (contract: chainId and contract addresses; heads and index progress; contract.lastEvent changes only when a contract event was indexed: refetch other data when it moves), /api/v1/stats
+- /api/v1/recent?n=96[&since=N] (the newest blocks of the burn index with burn and minted flag; signableTo: the newest block the signer will sign; since: only rows after N, mintedBlks covers the window)
+- /api/v1/mints?filter=all|held|wrapped&sort=recent|burn&limit=&offset=
+- /api/v1/top?filter=unminted|minted|all&limit=&offset= (blocks by burn, highest first; filter defaults to unminted, limit to 50, at most 100 per request; ranked 10,000 deep: offset ≤ 9999, a page past rank 10,000 is cut short and the returned limit says so)
+- /api/v1/blk/{N}, /api/v1/burn/{N} (burn of one indexed block; 503 until the index reaches it), /api/v1/addr/{address}?limit=&offset=
+- /api/v1/candidates (the 8 newest indexed blocks with burn and minted flag)
+- /api/v1/market, /api/v1/market/trades?limit=&offset=, /api/v1/market/buyer/{address}[?status=open]

package/package.json

@@ -1,8 +1,42 @@
 {
   "name": "nat-cli",
-  "version": "0.0.3",
-  "description": "Reserved for the bNAT CLI (mint NAT, wrap / unwrap BNAT on BSC). Not released yet; see https://bnat.live",
+  "version": "0.3.0",
+  "description": "Mint NAT, wrap / unwrap BNAT and trade it through the Binance Agentic Wallet. Ships SKILL.md for AI agents.",
+  "type": "module",
   "homepage": "https://bnat.live",
-  "license": "MIT",
-  "files": ["README.md"]
+  "keywords": [
+    "bnat",
+    "nat",
+    "bsc",
+    "bep-95",
+    "binance",
+    "agentic-wallet",
+    "cli"
+  ],
+  "bin": {
+    "bnat": "scripts/cli.mjs"
+  },
+  "files": [
+    "scripts/cli.mjs",
+    "lib",
+    "i18n",
+    "assets",
+    "SKILL.md",
+    "llms.txt",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "BNAT_LANG=zh node --no-warnings --test test/*.test.mjs",
+    "assets": "node scripts/assets.mjs",
+    "prepublishOnly": "node scripts/prepublish.mjs && npm test"
+  },
+  "dependencies": {
+    "@binance/agentic-wallet": "1.12.0",
+    "qrcode": "1.5.4",
+    "viem": "2.57.10"
+  },
+  "license": "MIT"
 }

package/scripts/cli.mjs

@@ -0,0 +1,570 @@
+#!/usr/bin/env node
+// bnat: mint NAT, wrap / unwrap it into BNAT and trade BNAT through the Binance Agentic Wallet (baw).
+// Every write: local checks -> on-chain simulation -> wallet preview checked field by field
+// -> journal -> execute once -> receipt and event verified. See SKILL.md.
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { getAddress, isAddress } from 'viem';
+import {
+  ABI, ELEMENT_ACTIVATION_BLOCK, ZERO, api, attest, calldata, costOf, eventsOf, explainRevert,
+  fmt18, loadConfig, makeClient, marketFee, nativeBalance, redact, parseBlk, BATCH_MAX, parseUnits18, payOf, readBid, REVERT_TEXT, wrapAmounts, walletState,
+} from '../lib/chain.mjs';
+import * as wallet from '../lib/baw.mjs';
+import { configFile, lang, saveSetting, settings, t, tIn } from '../lib/i18n.mjs';
+import { Journal } from '../lib/journal.mjs';
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const HELP = t('cli.help', { VERSION, BATCH_MAX });
+
+const { values: o, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    yes: { type: 'boolean' }, 'preview-only': { type: 'boolean' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+    block: { type: 'string' }, best: { type: 'boolean' }, to: { type: 'string' }, size: { type: 'string' },
+    price: { type: 'string' }, amount: { type: 'string' }, all: { type: 'boolean' }, bid: { type: 'string' },
+    hash: { type: 'string' }, id: { type: 'string' }, abandon: { type: 'string' }, version: { type: 'boolean', short: 'v' },
+    filter: { type: 'string' }, offset: { type: 'string' }, address: { type: 'string' }, sort: { type: 'string' }, mine: { type: 'boolean' },
+    lang: { type: 'string' }, // read by lib/i18n.mjs at import
+  },
+});
+
+const json = (v) => JSON.stringify(v, (_, x) => (typeof x === 'bigint' ? x.toString() : x), 2);
+const lines = [];
+const say = (s = '') => { if (!o.json) console.log(redact(s)); else lines.push(s); };
+const { Stop } = wallet; // a refused precondition: exit 2, nothing was sent
+
+let cfg, client; // loaded in main() so a bad config is reported like any other error
+const short = (a) => `${a.slice(0, 6)}…${a.slice(-4)}`;
+const bnb = (wei) => `${fmt18(wei)} BNB`;
+const UNKNOWN_RESULT = t('cli.outcomeUnknownDoNotResend');
+const FROM_INDEX = t('cli.fromTheSiteIndexChecked');
+
+async function main() {
+  const cmd = positionals[0];
+  if (o.version) return say(VERSION);
+  if (o.lang !== undefined && o.lang !== 'zh' && o.lang !== 'en') throw new Stop(t('cli.langMustBeZhOr'));
+  // Bare `bnat` in a terminal opens the TUI; piped or under an agent (no TTY) it stays the help text.
+  if ((!cmd && !o.help && !o.json && process.stdin.isTTY && process.stdout.isTTY) || cmd === 'gui') {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Stop(t('cli.theInteractiveScreenNeedsA'));
+    const { runTui } = await import('../lib/tui.mjs');
+    return runTui();
+  }
+  if (!cmd || o.help || cmd === 'help') return say(HELP);
+  if (cmd === 'lang') return langCmd();
+  if (cmd === 'config') return configCmd();
+  const run = { status, wallet: walletCmd, blocks, top, block: blockCmd, holdings, vault, bids, history, mint, wrap, unwrap, bid, sell, cancel, resume }[cmd];
+  if (!run) throw new Stop(`${t('cli.unknownCommand')} ${cmd}\n\n${HELP}`);
+  cfg = loadConfig();
+  client = makeClient(cfg);
+  return run();
+}
+
+// ---------------- read-only ----------------
+
+/** `bnat config [mintTo <address|self>]`: show the settings, or set the default mint recipient. */
+function configCmd() {
+  const [, key, value] = positionals;
+  if (key === undefined) {
+    const c = settings();
+    say(t('cli.configShow', { lang, mintTo: c.mintTo ?? t('cli.thisWallet'), file: configFile() }));
+    return { lang, mintTo: c.mintTo ?? null, file: configFile() };
+  }
+  if (key !== 'mintTo' || value === undefined) throw new Stop(t('cli.configUsage'));
+  if (value !== 'self' && !isAddress(value)) throw new Stop(t('tui.badAddress', { v: value }));
+  const v = value === 'self' ? undefined : getAddress(value);
+  saveSetting('mintTo', v);
+  say(t('cli.configSaved', { key, value: v ?? t('cli.thisWallet'), file: configFile() }));
+  return { mintTo: v ?? null, file: configFile() };
+}
+
+/** `bnat lang [zh|en]`: show or save the language ("lang" in config.json). */
+function langCmd() {
+  const v = positionals[1];
+  if (v === undefined) {
+    say(t('cli.languageEnglishSettingsFile', { v0: configFile() }));
+    return { lang, file: configFile() };
+  }
+  if (v !== 'zh' && v !== 'en') throw new Stop(t('cli.usageBnatLangZhEn'));
+  saveSetting('lang', v);
+  say(tIn(v, 'cli.langSaved', { file: configFile() })); // in the newly chosen language
+  return { lang: v, file: configFile() };
+}
+
+async function status() {
+  const out = { chainId: cfg.d.chainId, nat: cfg.d.nat, bnat: cfg.d.bnat, market: cfg.d.market, agentIdRegistry: cfg.d.agentId };
+  say(t('cli.chainNatBnatMarket', { chainId: cfg.d.chainId, nat: cfg.d.nat, bnat: cfg.d.bnat, market: cfg.d.market }));
+  if (cfg.site) {
+    const [s, m] = await Promise.all([api(cfg, '/api/v1/stats'), api(cfg, '/api/v1/market')]);
+    Object.assign(out, { stats: s, market: m.stats });
+    const sealed = fmt18(BigInt(s.totalBurnGwei) * 10n ** 9n);
+    say(t('cli.mintedOfThemInThe', { minted: s.minted, wrapped: s.wrapped, sealed, holders: s.holders }));
+    const price = m.stats.bestPrice ? fmt18(BigInt(m.stats.bestPrice)) : '—';
+    const vol = fmt18(BigInt(m.stats.volumePaid));
+    say(t('cli.marketBidsCurrentPriceBnb', { openBids: m.stats.openBids, price, vol }));
+  }
+  return out;
+}
+
+async function walletCmd() {
+  const a = await wallet.walletAddress();
+  const w = await walletState(cfg, client, a);
+  say(`${t('cli.wallet')} ${a}`);
+  say(`Agent ID   ${w.agentId ? t('cli.yes') : t('cli.noneClaimOneInThe')}`);
+  say(`BNB        ${fmt18(w.bnb)}`);
+  say(`NAT        ${w.nfts}${t('cli.countUnit')}`);
+  say(`BNAT       ${fmt18(w.bnat)}`);
+  return w;
+}
+
+async function candidates() {
+  const r = await api(cfg, '/api/v1/recent?n=96');
+  if (!Array.isArray(r.rows) || !Number.isInteger(r.signableTo)) throw Error(t('cli.unexpectedReplyFromRecent'));
+  // Only blocks the signer's burn index has reached (it answers 503 above signableTo).
+  return r.rows.filter((x) => x.blk <= r.signableTo && !x.minted && BigInt(x.burnGwei) >= 1n).sort((a, b) => (BigInt(b.burnGwei) > BigInt(a.burnGwei) ? 1 : -1));
+}
+
+async function blocks() {
+  const size = intOpt('size', 20, 1, 96);
+  const rows = (await candidates()).slice(0, size);
+  say(t('cli.blockBurnGwei'));
+  for (const r of rows) say(`#${String(r.blk).padEnd(14)} ${r.burnGwei}`);
+  if (!rows.length) say(t('cli.theLast96FinalizedBlocks'));
+  say(FROM_INDEX);
+  return rows;
+}
+
+/** --name as an integer in [lo, hi], or the default; anything else stops. */
+function intOpt(name, dflt, lo, hi) {
+  const v = o[name];
+  if (v === undefined) return dflt;
+  if (!/^\d+$/.test(v) || Number(v) < lo || Number(v) > hi) throw new Stop(t('cli.mustBeAnIntegerFrom', { name, lo, hi }));
+  return Number(v);
+}
+
+async function top() {
+  const filter = o.filter ?? 'unminted';
+  if (!['unminted', 'minted', 'all'].includes(filter)) throw new Stop(t('cli.filterMustBeUnmintedMinted'));
+  const size = intOpt('size', 20, 1, 100), offset = intOpt('offset', 0, 0, 9_999);
+  const r = await api(cfg, `/api/v1/top?filter=${filter}&limit=${size}&offset=${offset}`);
+  if (!Array.isArray(r.rows)) throw Error(t('cli.unexpectedReplyFromTop'));
+  say(t('cli.rankBlockBurnGweiStatus'));
+  r.rows.forEach((x, i) => say(`${String(offset + i + 1).padEnd(7)} #${String(x.blk).padEnd(14)} ${x.burnGwei.padEnd(18)} ${x.minted ? t('cli.minted') : t('cli.unminted')}`));
+  if (!r.rows.length) say(t('cli.noMatchingBlocks'));
+  say(FROM_INDEX);
+  return r.rows;
+}
+
+async function blockCmd() {
+  const blk = parseBlk(o.block);
+  if (blk === null) throw new Stop(t('cli.nameTheBlockWithBlock'));
+  const b = await api(cfg, `/api/v1/blk/${blk}`);
+  say(`${t('cli.block')} #${b.blk}`);
+  say(`${t('cli.burn')} ${b.burnGwei ?? '—'} gwei${b.bscBurnGwei ? t('cli.bscRecomputesWhichDiffersFrom', { bscBurnGwei: b.bscBurnGwei }) : ''}`);
+  say(`${t('cli.final')} ${b.finalized ? t('cli.yes2') : t('cli.no')}`);
+  say(`${t('cli.minted2')} ${b.minted
+    ? t('cli.mintedHeldBy', { owner: b.owner, where: b.wrapped ? t('cli.inTheBnatVaultCan') : '' })
+    : t('cli.no2')}`);
+  return b;
+}
+
+async function holdings() {
+  const who = o.address ?? await wallet.walletAddress();
+  if (!/^0x[0-9a-fA-F]{40}$/.test(who)) throw new Stop(t('cli.addressMustBeAFull'));
+  const size = intOpt('size', 100, 1, 100), offset = intOpt('offset', 0, 0, 1e9);
+  const r = await api(cfg, `/api/v1/addr/${who}?limit=${size}&offset=${offset}`);
+  if (!Array.isArray(r.held)) throw Error(t('cli.unexpectedReplyFromAddr'));
+  const range = r.heldTotal > r.held.length ? t('cli.showing', { v0: offset + 1, v1: offset + r.held.length }) : '';
+  say(t('cli.holdsNat', { who, heldTotal: r.heldTotal, range }));
+  for (const h of r.held) say(`#${String(h.blk).padEnd(14)} ${h.burnGwei} gwei`);
+  return r;
+}
+
+async function vault() {
+  const sort = o.sort ?? 'burn';
+  if (!['burn', 'recent'].includes(sort)) throw new Stop(t('cli.sortMustBeBurnOr'));
+  const size = intOpt('size', 20, 1, 100), offset = intOpt('offset', 0, 0, 1e9);
+  const r = await api(cfg, `/api/v1/mints?filter=wrapped&sort=${sort}&limit=${size}&offset=${offset}`);
+  if (!Array.isArray(r.rows)) throw Error(t('cli.unexpectedReplyFromMints'));
+  const range = r.total > r.rows.length ? t('cli.showing', { v0: offset + 1, v1: offset + r.rows.length }) : '';
+  say(t('cli.natInTheVault', { total: r.total, range }));
+  say(t('cli.blockBurnGweiUnwrapCost'));
+  for (const x of r.rows) say(`#${String(x.blk).padEnd(14)} ${x.burnGwei.padEnd(18)} ${fmt18(wrapAmounts(BigInt(x.burnGwei)).unwrapCost)}`);
+  return r;
+}
+
+async function bids() {
+  const size = intOpt('size', 100, 1, 100), offset = intOpt('offset', 0, 0, 1e9);
+  const m = o.mine
+    ? await api(cfg, `/api/v1/market/buyer/${await wallet.walletAddress()}?status=open&limit=${size}&offset=${offset}`)
+    : await api(cfg, `/api/v1/market?limit=${size}&offset=${offset}`);
+  if (!Array.isArray(m.bids)) throw Error(t('cli.unexpectedReplyFromMarket'));
+  const total = m.bidsTotal ?? m.total;
+  if (total > m.bids.length) say(t('cli.bidsShowing', { total, v0: offset + 1, v1: offset + m.bids.length }));
+  say(t('cli.idPriceBnbBnatLeft'));
+  for (const b of m.bids) say(`#${String(b.id).padEnd(5)} ${fmt18(BigInt(b.price)).padEnd(18)} ${fmt18(BigInt(b.remaining)).padEnd(17)} ${fmt18(BigInt(b.escrow)).padEnd(13)} ${short(b.buyer)}`);
+  if (!m.bids.length) say(o.mine ? t('cli.thisWalletHasNoOpen') : t('cli.thereAreNoBidsRight'));
+  return m.bids;
+}
+
+async function history() {
+  const all = new Journal().entries();
+  for (const e of all) say(`${e.at}  ${e.status.padEnd(10)} ${e.action} ${e.summary ?? ''}${e.hash ? ` ${e.hash}` : ''}  [${e.id}]`);
+  if (!all.length) say(t('cli.noEntriesYet'));
+  return all;
+}
+
+// ---------------- the write pipeline ----------------
+
+/**
+ * plan: { action, summary, address, abi, functionName, args, value, assets, native, approve?, verify(receipt) }
+ */
+const loopback = (u) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(u).hostname); } catch { return false; } };
+function fakeWallet() {
+  const bin = process.env.BNAT_BAW_BIN;
+  return !!bin && !/agentic-wallet|(^|[/\\])baw(\.\w+)?$/.test(bin) && loopback(cfg.rpc) && loopback(process.env.FAKE_BAW_RPC);
+}
+
+async function send(from, plan) {
+  // A dev deployment lives on a local chain, but the real wallet signs on BSC mainnet, where these
+  // addresses mean something else. Only the fake wallet may send for it: an override that is not
+  // the packaged baw, with both this CLI and the fake wallet on a loopback RPC.
+  if (cfg.d.mockAgentId && !fakeWallet()) {
+    throw new Stop(t('cli.thisIsADevDeployment'));
+  }
+  const j = new Journal();
+  const open = j.open();
+  if (open.length) {
+    const list = open.map((e) => `${e.action} ${e.hash ?? t('cli.noHash')} [${e.id}]`).join(t('common.listSep'));
+    throw new Stop(t('cli.transactionSWithAnUnknown', { length: open.length, list }));
+  }
+  const value = plan.value ?? 0n;
+  const data = calldata(plan.abi, plan.functionName, plan.args);
+  const errs = [...plan.abi, ...ABI.bnat, ...ABI.nat].filter((x) => x.type === 'error');
+  try {
+    await client.simulateContract({ address: plan.address, abi: [...plan.abi, ...errs], functionName: plan.functionName, args: plan.args, account: from, value });
+  } catch (e) {
+    throw new Stop(t('cli.onChainSimulationFailed') + explainRevert(e));
+  }
+  const [gas, gasPrice, bal] = await Promise.all([
+    client.estimateGas({ account: from, to: plan.address, data, value }), client.getGasPrice(), nativeBalance(client, from),
+  ]);
+  const need = value + gas * gasPrice;
+  if (bal < need) throw new Stop(t('cli.notEnoughBnbNeedIncluding', { need: bnb(need), v0: bnb(gas * gasPrice), bal: bnb(bal), short: bnb(need - bal) }));
+
+  say(t('cli.plan') + plan.summary);
+  say(t('cli.contractSendsGasAbout', { address: plan.address, functionName: plan.functionName, value: bnb(value), v0: bnb(gas * gasPrice) }));
+  say(t('cli.onChainSimulationPassed'));
+  if (!o.yes && !o['preview-only']) {
+    say(t('cli.withoutYesOnlyCheckedNothing'));
+    return { planned: true, data };
+  }
+
+  const tx = { from, to: plan.address, data, value };
+  const pv = wallet.validatePreview(await wallet.preview(cfg.d.chainId, tx), {
+    ...tx, assets: plan.assets ?? {}, native: plan.native ?? {}, approve: plan.approve,
+  });
+  say(t('cli.walletPreviewEveryFieldChecked'));
+  if (o['preview-only']) return { previewed: true, requestId: pv.requestId, data };
+
+  const id = j.begin({ action: plan.action, summary: plan.summary, from, to: plan.address, data, value: value.toString() });
+  let res;
+  try {
+    res = await wallet.execute(pv.requestId, () => say(t('cli.stillWaitingForTheWallet', { id })));
+  } catch (e) {
+    // The request may or may not have reached the chain: keep the entry open.
+    j.update(id, { error: String(e.message ?? e) });
+    throw Error(`${t('cli.executeErrorPrefix', { message: e.message })}${UNKNOWN_RESULT}`);
+  }
+  if (!res.hash) {
+    j.update(id, { status: 'sent', orderId: res.orderId, walletStatus: res.status });
+    throw Error(t('cli.theWalletAcceptedItBut', { v0: res.orderId ?? '?', status: res.status }) + UNKNOWN_RESULT);
+  }
+  j.update(id, { status: 'sent', hash: res.hash });
+  say(t('cli.sentWaitingForTheReceipt', { hash: res.hash }));
+  return settle(j, id, res.hash, plan.verify);
+}
+
+async function settle(j, id, hash, verify) {
+  let rc;
+  try {
+    rc = await client.waitForTransactionReceipt({ hash, timeout: 180_000 });
+  } catch (e) {
+    // Still pending or the RPC failed: the entry stays open (status "sent"), nothing is resent.
+    const why = e.shortMessage ?? e.message;
+    throw Error(t('cli.transactionWasSentButHas', { hash, why }));
+  }
+  if (rc.status !== 'success') {
+    j.update(id, { status: 'failed', hash, block: Number(rc.blockNumber) });
+    throw Error(t('cli.transactionIsOnChainBut', { hash, blockNumber: rc.blockNumber }));
+  }
+  const result = verify ? verify(rc) : {};
+  j.update(id, { status: 'confirmed', hash, block: Number(rc.blockNumber), result });
+  say(t('cli.doneBlock', { hash, blockNumber: rc.blockNumber }));
+  return { hash, block: Number(rc.blockNumber), ...result };
+}
+
+const one = (evs, name, ok) => {
+  const e = evs.find((x) => x.eventName === name && ok(x.args));
+  if (!e) throw Error(t('cli.theReceiptLacksTheExpected', { name }));
+  return e.args;
+};
+
+// ---------------- writes ----------------
+
+async function mint() {
+  const from = await wallet.walletAddress();
+  // Recipient: --to, else the mintTo setting (`bnat config mintTo …`), else this wallet.
+  const saved = o.to === undefined ? settings().mintTo : undefined;
+  if (saved !== undefined && (!isAddress(String(saved)) || saved === ZERO)) throw new Stop(t('cli.mintToBad', { v: saved }));
+  const to = o.to ? (isAddress(o.to) ? getAddress(o.to) : null) : saved ? getAddress(saved) : from;
+  if (!to || to === ZERO) throw new Stop(t('cli.toIsNotAValid'));
+  const self = to.toLowerCase() === from.toLowerCase();
+  const w = await walletState(cfg, client, from);
+  if (!w.agentId) {
+    throw new Stop(t('cli.walletHasNoAiAgent', { from }));
+  }
+
+  let blk;
+  if (o.best) {
+    const c = await candidates();
+    for (const r of c) {
+      // burnOf is nonzero exactly when the block has been minted
+      const b = await client.readContract({ address: cfg.d.nat, abi: ABI.nat, functionName: 'burnOf', args: [BigInt(r.blk)] });
+      if (b === 0n) { blk = r.blk; break; }
+    }
+    if (blk === undefined) throw new Stop(t('cli.nothingLeftToMintIn'));
+  } else {
+    blk = parseBlk(o.block);
+    if (blk === null) throw new Stop(t('cli.nameTheBlockWithBlock2'));
+  }
+  if (blk < ELEMENT_ACTIVATION_BLOCK) throw new Stop(t('cli.isBeforeTheBep95', { blk, ELEMENT_ACTIVATION_BLOCK }));
+  const onChain = await client.readContract({ address: cfg.d.nat, abi: ABI.nat, functionName: 'burnOf', args: [BigInt(blk)] });
+  if (onChain !== 0n) throw new Stop(t('cli.isAlreadyMintedFirstCome', { blk }));
+  // The signer refuses blocks that are not in its burn index yet or burned < 1 gwei.
+  const { sig, burn } = await attest(cfg, client, blk);
+
+  return send(from, {
+    action: 'mint', summary: t('cli.mintSummary', { blk, burn, dest: self ? t('cli.thisWallet') : to }),
+    address: cfg.d.nat, abi: ABI.nat, functionName: 'mint',
+    // To self: the 3-arg overload (simplest calldata for the wallet); otherwise name the recipient.
+    args: self ? [BigInt(blk), burn, sig] : [BigInt(blk), burn, sig, to],
+    // Minting to another address moves nothing in or out of this wallet: no asset may change.
+    assets: self ? { [cfg.d.nat]: { in: true } } : {},
+    verify: (rc) => {
+      const a = one(eventsOf(rc, ABI.nat, cfg.d.nat), 'Minted', (x) => x.blk === BigInt(blk)
+        && x.minter.toLowerCase() === from.toLowerCase() && x.to.toLowerCase() === to.toLowerCase());
+      return { blk, to: a.to, burnGwei: a.burnGwei };
+    },
+  });
+}
+
+async function wrap() {
+  const blks = blockList('wrap');
+  if (o.to !== undefined) throw new Stop(t('cli.wrapHasNoToBnat'));
+  const from = await wallet.walletAddress();
+  // Each step reads every block at once (one aggregate3), then checks them in block order, so the
+  // first failing block is the one reported.
+  const read = (functionName, args, abi = ABI.nat, address = cfg.d.nat) => client.readContract({ address, abi, functionName, args });
+  const owners = await Promise.allSettled(blks.map((blk) => read('ownerOf', [BigInt(blk)])));
+  const foreign = [];
+  blks.forEach((blk, i) => {
+    const r = owners[i];
+    if (r.status === 'rejected') throw new Stop(t('cli.hasNoHolderNotMinted', { blk }) + explainRevert(r.reason));
+    if (r.value.toLowerCase() === cfg.d.bnat.toLowerCase()) throw new Stop(t('cli.isAlreadyInTheBnat', { blk }));
+    if (r.value.toLowerCase() !== from.toLowerCase()) foreign.push({ blk, owner: r.value });
+  });
+  const approvals = await Promise.all(foreign.map(({ blk, owner }) => Promise.all([read('getApproved', [BigInt(blk)]), read('isApprovedForAll', [owner, from])])));
+  foreign.forEach(({ blk, owner }, i) => {
+    const [ap, all] = approvals[i];
+    if (ap.toLowerCase() !== from.toLowerCase() && !all) throw new Stop(t('cli.belongsToNotThisWallet', { blk, owner }));
+  });
+  const burns = await Promise.all(blks.map((blk) => read('burnOf', [BigInt(blk)])));
+  let toHolder = 0n, fee = 0n;
+  for (const burn of burns) {
+    const s = wrapAmounts(burn); // fee floors per block, as the contract does
+    toHolder += s.toHolder;
+    fee += s.fee;
+  }
+  const batch = blks.length > 1;
+  const names = blks.map((b) => `#${b}`).join(' ');
+  return send(from, {
+    action: 'wrap',
+    summary: t('cli.wrapBnatToThisWallet', { names, toHolder: fmt18(toHolder), fee: fmt18(fee) }),
+    address: cfg.d.nat, abi: ABI.nat,
+    ...(batch ? { functionName: 'wrapBatch', args: [blks.map(BigInt)] } : { functionName: 'wrap', args: [BigInt(blks[0])] }),
+    assets: { [cfg.d.nat]: { maxOut: BigInt(blks.length) }, [cfg.d.bnat]: { in: true } },
+    verify: (rc) => {
+      const evs = eventsOf(rc, ABI.nat, cfg.d.nat);
+      const got = blks.map((blk) => one(evs, 'Wrapped', (x) => x.blk === BigInt(blk)));
+      const sum = (k) => got.reduce((acc, a) => acc + a[k], 0n);
+      return batch ? { blks, to: got[0].to, amount: sum('amount'), fee: sum('fee') } : { blk: blks[0], to: got[0].to, amount: got[0].amount, fee: got[0].fee };
+    },
+  });
+}
+
+async function unwrap() {
+  const blks = blockList('unwrap');
+  if (o.to !== undefined) throw new Stop(t('cli.unwrapHasNoToThe'));
+  const from = await wallet.walletAddress();
+  // ownerOf of every block, the contract's own quote of every block (amount = burnOf * 1e9, fee =
+  // 1% floored per block) and the balance: one aggregate3, then checked in block order.
+  const [owners, quotes, bal] = await Promise.all([
+    Promise.allSettled(blks.map((blk) => client.readContract({ address: cfg.d.nat, abi: ABI.nat, functionName: 'ownerOf', args: [BigInt(blk)] }))),
+    Promise.allSettled(blks.map((blk) => client.readContract({ address: cfg.d.bnat, abi: ABI.bnat, functionName: 'quote', args: [BigInt(blk)] }))),
+    client.readContract({ address: cfg.d.bnat, abi: ABI.bnat, functionName: 'balanceOf', args: [from] }),
+  ]);
+  let amount = 0n, fee = 0n;
+  blks.forEach((blk, i) => {
+    const r = owners[i];
+    if (r.status === 'rejected') throw new Stop(`#${blk}${t('common.colon')}${REVERT_TEXT.NotInVault}${t('cli.notMintedYet', { reason: explainRevert(r.reason) })}`);
+    if (r.value.toLowerCase() !== cfg.d.bnat.toLowerCase()) throw new Stop(`#${blk}${t('common.colon')}${REVERT_TEXT.NotInVault}${t('cli.heldBy', { value: r.value })}`);
+    if (quotes[i].status === 'rejected') throw quotes[i].reason;
+    amount += quotes[i].value[0];
+    fee += quotes[i].value[1];
+  });
+  const total = amount + fee;
+  if (bal < total) {
+    throw new Stop(t('cli.notEnoughBnatNeedIncluding', { total: fmt18(total), fee: fmt18(fee), bal: fmt18(bal), v0: fmt18(total - bal) }));
+  }
+  const batch = blks.length > 1;
+  const names = blks.map((b) => `#${b}`).join(' ');
+  return send(from, {
+    action: 'unwrap',
+    summary: t('cli.unwrapPayBnatBurnFee', { names, total: fmt18(total), amount: fmt18(amount), fee: fmt18(fee), length: blks.length }),
+    address: cfg.d.bnat, abi: ABI.bnat,
+    ...(batch ? { functionName: 'unwrapBatch', args: [blks.map(BigInt)] } : { functionName: 'unwrap', args: [BigInt(blks[0])] }),
+    // No approval: BNAT burns and moves the caller's own tokens.
+    assets: { [cfg.d.bnat]: { maxOut: total }, [cfg.d.nat]: { in: true } },
+    verify: (rc) => {
+      const evs = eventsOf(rc, ABI.bnat, cfg.d.bnat);
+      const got = blks.map((blk) => one(evs, 'Unwrapped', (x) => x.blk === BigInt(blk) && x.by.toLowerCase() === from.toLowerCase()));
+      const sum = (k) => got.reduce((acc, a) => acc + a[k], 0n);
+      return batch ? { blks, amount: sum('amount'), fee: sum('fee') } : { blk: blks[0], amount: got[0].amount, fee: got[0].fee };
+    },
+  });
+}
+
+/** --block N1,N2,… for wrap / unwrap: valid, distinct, at most BATCH_MAX. */
+function blockList(verb) {
+  const parts = String(o.block ?? '').split(',').map((x) => x.trim()).filter(Boolean);
+  const blks = parts.map(parseBlk);
+  if (blks.length === 0 || blks.includes(null)) throw new Stop(t('cli.nameTheNatToWith', { verb }));
+  if (new Set(blks).size !== blks.length) throw new Stop(t('cli.blockListsABlockTwice'));
+  if (blks.length > BATCH_MAX) throw new Stop(t('cli.atMostPerSplitIt', { verb, BATCH_MAX }));
+  return blks;
+}
+
+async function bid() {
+  const price = parseUnits18(o.price), amount = parseUnits18(o.amount);
+  if (price === null || amount === null) throw new Stop(t('cli.priceBnbPerBnatAnd'));
+  if (price === 0n || amount === 0n) throw new Stop(t('cli.priceAndAmountMustBoth'));
+  const from = await wallet.walletAddress();
+  const cost = costOf(price, amount);
+  return send(from, {
+    action: 'bid', summary: t('cli.bidBnatAtBnbLocking', { amount: fmt18(amount), price: fmt18(price), cost: bnb(cost) }),
+    address: cfg.d.market, abi: ABI.market, functionName: 'bid', args: [price, amount], value: cost,
+    native: { maxOut: cost },
+    verify: (rc) => {
+      const a = one(eventsOf(rc, ABI.market, cfg.d.market), 'BidPlaced', (x) => x.buyer.toLowerCase() === from.toLowerCase());
+      say(t('cli.bid', { id: a.id }));
+      return { bid: Number(a.id), price, amount, escrow: a.escrow };
+    },
+  });
+}
+
+async function sell() {
+  if (!/^\d+$/.test(o.bid ?? '')) throw new Stop(t('cli.nameTheBidWithBid'));
+  if (!o.all && parseUnits18(o.amount) === null) throw new Stop(t('cli.giveTheAmountWithAmount'));
+  const from = await wallet.walletAddress();
+  const id = BigInt(o.bid);
+  const b = await readBid(cfg, client, id);
+  if (b.remaining === 0n) throw new Stop(t('cli.bidIsAlreadyFilledOr', { id }));
+  const bal = await client.readContract({ address: cfg.d.bnat, abi: ABI.bnat, functionName: 'balanceOf', args: [from] });
+  const amount = o.all ? (bal < b.remaining ? bal : b.remaining) : parseUnits18(o.amount);
+  if (amount === null) throw new Stop(t('cli.giveTheAmountWithAmount'));
+  if (amount === 0n) throw new Stop(t('cli.theSellAmountMustBe'));
+  if (amount > b.remaining) throw new Stop(t('cli.bidHasOnlyBnatLeft', { id, remaining: fmt18(b.remaining), amount: fmt18(amount) }));
+  if (bal < amount) throw new Stop(t('cli.notEnoughBnatNeedHave', { amount: fmt18(amount), bal: fmt18(bal), short: fmt18(amount - bal) }));
+  const pay = payOf(b, amount);
+  if (pay === 0n) throw new Stop(t('cli.amountTooSmallWorthLess'));
+  const fee = marketFee(pay);
+  const summary = t('cli.sellBnatToBidReceive', { amount: fmt18(amount), id, v0: bnb(pay - fee), fee: bnb(fee) });
+
+  const allowance = await client.readContract({ address: cfg.d.bnat, abi: ABI.bnat, functionName: 'allowance', args: [from, cfg.d.market] });
+  let approval = null;
+  if (allowance < amount) {
+    say(t('cli.plan') + summary); // the sale runs after the approval: show it now, not only then
+    say(t('cli.theMarketSBnatAllowance', { allowance: fmt18(allowance), amount: fmt18(amount) }));
+    approval = await send(from, {
+      action: 'approve', summary: t('cli.approveTheMarketToUse', { amount: fmt18(amount) }),
+      address: cfg.d.bnat, abi: ABI.bnat, functionName: 'approve', args: [cfg.d.market, amount],
+      approve: { token: cfg.d.bnat, spender: cfg.d.market, max: amount },
+    });
+    if (approval.planned || approval.previewed) {
+      say(t('cli.theApprovalHasNotRun'));
+      return { approval };
+    }
+  }
+  const r = await send(from, {
+    action: 'sell', summary,
+    address: cfg.d.market, abi: ABI.market, functionName: 'fill', args: [id, amount],
+    assets: { [cfg.d.bnat]: { maxOut: amount } }, native: { in: true },
+    verify: (rc) => {
+      const a = one(eventsOf(rc, ABI.market, cfg.d.market), 'BidFilled', (x) => x.id === id && x.seller.toLowerCase() === from.toLowerCase());
+      return { bid: Number(id), amount: a.amount, paid: a.paid, fee: a.fee };
+    },
+  });
+  return approval ? { approval, ...r } : r;
+}
+
+async function cancel() {
+  if (!/^\d+$/.test(o.bid ?? '')) throw new Stop(t('cli.nameTheBidToCancel'));
+  const from = await wallet.walletAddress();
+  const id = BigInt(o.bid);
+  const b = await readBid(cfg, client, id);
+  if (b.buyer.toLowerCase() !== from.toLowerCase()) throw new Stop(t('cli.bidWasPlacedByNot', { id, buyer: b.buyer }));
+  if (b.remaining === 0n) throw new Stop(t('cli.bidIsAlreadyFilledOr', { id }));
+  return send(from, {
+    action: 'cancel', summary: t('cli.cancelBidRefunding', { id, escrow: bnb(b.escrow) }),
+    address: cfg.d.market, abi: ABI.market, functionName: 'cancel', args: [id], native: { in: true },
+    verify: (rc) => {
+      const a = one(eventsOf(rc, ABI.market, cfg.d.market), 'BidCancelled', (x) => x.id === id);
+      return { bid: Number(id), refund: a.refund };
+    },
+  });
+}
+
+async function resume() {
+  const j = new Journal();
+  const open = j.open();
+  if (o.abandon) {
+    const e = open.find((x) => x.id === o.abandon);
+    if (!e) throw new Stop(t('cli.noOpenEntry', { abandon: o.abandon }));
+    if (e.hash) throw new Stop(t('cli.thisEntryHasAHash'));
+    j.update(e.id, { status: 'abandoned' });
+    say(t('cli.voided', { action: e.action, id: e.id }));
+    return { abandoned: e.id };
+  }
+  if (!/^0x[0-9a-fA-F]{64}$/.test(o.hash ?? '')) throw new Stop(t('cli.giveTheTransactionHashWith'));
+  const e = o.id ? open.find((x) => x.id === o.id) : open.find((x) => x.hash?.toLowerCase() === o.hash.toLowerCase()) ?? (open.length === 1 ? open[0] : null);
+  if (!e) {
+    throw new Stop(open.length
+      ? t('cli.openEntriesPickOneWith', { length: open.length }) + open.map((x) => x.id).join(', ')
+      : t('cli.noOpenEntries'));
+  }
+  const tx = await client.getTransaction({ hash: o.hash });
+  if (tx.from.toLowerCase() !== e.from.toLowerCase() || tx.to?.toLowerCase() !== e.to.toLowerCase()
+    || tx.input.toLowerCase() !== e.data.toLowerCase() || tx.value !== BigInt(e.value ?? 0)) {
+    throw new Stop(t('cli.thisTransactionDoesNotMatch'));
+  }
+  return settle(j, e.id, o.hash, null);
+}
+
+main().then((r) => {
+  if (o.json) console.log(redact(json({ ok: true, result: r ?? null, log: lines })));
+}).catch((e) => {
+  const stop = e instanceof Stop;
+  if (o.json) console.log(redact(json({ ok: false, stopped: stop, error: e.message, log: lines })));
+  else console.error(redact(`${stop ? t('cli.stopped') : t('cli.error')}${t('common.colon')}${e.message}`));
+  process.exit(stop ? 2 : 1);
+});