nat-cli 0.0.3 → 0.3.0

package/lib/chain.mjs

@@ -0,0 +1,238 @@
+// Chain side of the bnat CLI: deployment, reads, calldata and the contract arithmetic.
+// Every number that decides a transaction is read from the chain, except a mint's burn, which
+// comes signed from the site's signer. The rest of the site API only feeds lists.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  createPublicClient, decodeEventLog, encodeFunctionData, http, parseAbi, recoverTypedDataAddress,
+} from 'viem';
+import { lang, t } from './i18n.mjs';
+
+const REVERTS = JSON.parse(readFileSync(new URL('../i18n/revert.json', import.meta.url), 'utf8'));
+
+export const ZERO = '0x0000000000000000000000000000000000000000';
+export const UNIT = 10n ** 18n;
+/** BNAT.FEE_BPS: 1% on wrap and on unwrap. */
+export const VAULT_FEE_BPS = 100n;
+/** Max NFTs per NAT.wrapBatch / BNAT.unwrapBatch (~1.0M gas warm, ~1.3M cold). */
+export const BATCH_MAX = 50;
+export const MARKET_FEE_BPS = 100n;
+
+export const ABI = {
+  // NAT: the NFT.
+  nat: parseAbi([
+    'function mint(uint256 blk, uint256 burnGwei, bytes sig)',
+    'function mint(uint256 blk, uint256 burnGwei, bytes sig, address to)',
+    'function wrap(uint256 blk)',
+    'function wrapBatch(uint256[] blks)',
+    'function burnOf(uint256) view returns (uint256)',
+    'function ownerOf(uint256) view returns (address)',
+    'function balanceOf(address) view returns (uint256)',
+    'function getApproved(uint256) view returns (address)',
+    'function isApprovedForAll(address, address) view returns (bool)',
+    'function signer() view returns (address)',
+    'function agentId() view returns (address)',
+    'function eip712Domain() view returns (bytes1 fields, string name, string version, uint256 chainId, address verifyingContract, bytes32 salt, uint256[] extensions)',
+    'event Minted(uint256 indexed blk, address indexed minter, address indexed to, uint256 burnGwei)',
+    'event Wrapped(uint256 indexed blk, address indexed owner, address indexed to, uint256 amount, uint256 fee)',
+    'error BeforeActivation()', 'error FutureBlock()', 'error ZeroBurn()', 'error AlreadyMinted()', 'error BadSignature()',
+    'error NotAuthorized()', 'error ZeroAddress()', 'error NoAgentId()', 'error EmptyBatch()', 'error ERC721NonexistentToken(uint256)',
+  ]),
+  // BNAT: the ERC-20 (BNAT) and the vault that holds wrapped NFTs.
+  bnat: parseAbi([
+    'function unwrap(uint256 blk)',
+    'function unwrapBatch(uint256[] blks)',
+    'function quote(uint256 blk) view returns (uint256 amount, uint256 fee)',
+    'function FEE_BPS() view returns (uint256)',
+    'function balanceOf(address) view returns (uint256)',
+    'function allowance(address, address) view returns (uint256)',
+    'function approve(address, uint256) returns (bool)',
+    'event Unwrapped(uint256 indexed blk, address indexed by, uint256 amount, uint256 fee)',
+    'error NotInVault()', 'error EmptyBatch()', 'error CannotWithdrawNft()', 'error OnlyNft()', 'error OnlyDev()',
+    'error ZeroAddress()', 'error TransferFailed()',
+    'error ERC20InsufficientBalance(address, uint256, uint256)',
+    'error ERC20InsufficientAllowance(address, uint256, uint256)',
+  ]),
+  registry: parseAbi(['function balanceOf(address) view returns (uint256)']),
+  market: parseAbi([
+    'function bid(uint256 price, uint256 amount) payable returns (uint256)',
+    'function fill(uint256 id, uint256 amount)',
+    'function cancel(uint256 id)',
+    'function bids(uint256) view returns ((address buyer, uint256 price, uint256 remaining, uint256 escrow))',
+    'function bidCount() view returns (uint256)',
+    'event BidPlaced(uint256 indexed id, address indexed buyer, uint256 price, uint256 amount, uint256 escrow)',
+    'event BidFilled(uint256 indexed id, address indexed seller, address indexed buyer, uint256 amount, uint256 paid, uint256 fee)',
+    'event BidCancelled(uint256 indexed id, address indexed buyer, uint256 refund)',
+    'error ZeroAmount()', 'error WrongValue(uint256)', 'error NotBuyer()', 'error BidClosed()',
+    'error TooMuch(uint256)', 'error NothingToPay()', 'error TransferFailed()',
+  ]),
+};
+
+/** Revert name -> what the user should know (i18n/revert.json); read at lookup so it follows the
+ *  current language. */
+export const REVERT_TEXT = Object.defineProperties({}, Object.fromEntries(
+  Object.entries(REVERTS).map(([k, v]) => [k, { get: () => v[lang], enumerable: true }]),
+));
+
+export function explainRevert(e) {
+  for (let cur = e; cur; cur = cur.cause) {
+    const name = cur?.data?.errorName ?? cur?.errorName;
+    if (name) return `${REVERT_TEXT[name] ?? name}${t('chain.revertNameSuffix', { name })}`;
+  }
+  return e?.shortMessage ?? e?.message ?? String(e);
+}
+
+// ---- deployment & config ----
+
+// A configured RPC URL often carries an API key in its path or query, and viem puts the full URL
+// into its error messages. Everything the CLI prints goes through redact() (scripts/cli.mjs).
+const SECRET_URLS = new Set();
+export function redact(s) {
+  let out = String(s);
+  for (const u of SECRET_URLS) out = out.split(u).join(`${new URL(u).origin}/…`);
+  return out;
+}
+
+const ASSET = fileURLToPath(new URL('../assets/deployment.json', import.meta.url));
+const REQUIRED = ['chainId', 'nat', 'bnat', 'market', 'agentId'];
+const DEFAULT_RPC = { 56: 'https://bsc-dataseed.bnbchain.org' };
+
+/**
+ * BNAT_DEPLOYMENT overrides the bundled deployment (local dev chains only).
+ * BNAT_SITE is the site serving /api/v1 and /api/signer; BNAT_RPC the contract chain RPC.
+ */
+export function loadConfig(env = process.env) {
+  const path = env.BNAT_DEPLOYMENT ?? ASSET;
+  let d;
+  try { d = JSON.parse(readFileSync(path, 'utf8')); } catch (e) { throw Error(t('chain.cannotReadTheDeploymentFile', { path }) + e.message); }
+  for (const k of REQUIRED) if (d[k] === undefined) throw Error(t('chain.theDeploymentFileLacks', { k }));
+  const site = (env.BNAT_SITE ?? d.site ?? '').replace(/\/+$/, '');
+  // A mock deployment runs on a local chain that may also use chainId 56; never fall back to the real BSC RPC for it.
+  if (d.mockAgentId && !env.BNAT_RPC) throw Error(t('chain.aDevDeploymentMockagentidNeeds'));
+  const rpc = env.BNAT_RPC ?? DEFAULT_RPC[d.chainId];
+  if (!rpc) throw Error(t('chain.noDefaultRpcForChainid', { chainId: d.chainId }));
+  if (env.BNAT_RPC) for (const u of [rpc, rpc.replace(/\/+$/, '')]) if (URL.canParse(u) && new URL(u).origin !== u) SECRET_URLS.add(u);
+  return { d, site, rpc };
+}
+
+/**
+ * Native balance by plain eth_getBalance. viem >= 2.5x sends getBalance through Multicall3.getEthBalance
+ * when multicall batching is on, which needs a full Multicall3 on the RPC's chain.
+ */
+export const nativeBalance = async (client, address) => BigInt(await client.request({ method: 'eth_getBalance', params: [address, 'latest'] }));
+
+/** Multicall3 on BSC; a deployment file may name another ("multicall3"). */
+export const MULTICALL3 = '0xcA11bde05977b3631167028862bE2a173976CA11';
+
+/**
+ * Reads issued together (e.g. ownerOf / burnOf for every block of a 50-NFT wrap) go out as one
+ * Multicall3 aggregate3 eth_call. A revert in one read still surfaces as that read's own error.
+ * Without a known Multicall3 (an unknown chain) reads are sent one by one. batchSize: viem splits
+ * at 1 KB of calldata by default; the reads of a 50-block batch are ~20 KB.
+ */
+export function makeClient(cfg) {
+  const mc = cfg.d.multicall3 ?? (cfg.d.chainId === 56 && !cfg.d.mockAgentId ? MULTICALL3 : undefined);
+  const chain = mc ? { id: cfg.d.chainId, name: 'contract chain', nativeCurrency: { name: 'BNB', symbol: 'BNB', decimals: 18 },
+    rpcUrls: { default: { http: [cfg.rpc] } }, contracts: { multicall3: { address: mc } } } : undefined;
+  return createPublicClient({ chain, transport: http(cfg.rpc, { timeout: 30_000 }), batch: mc ? { multicall: { batchSize: 65_536 } } : undefined });
+}
+
+// ---- parsing & formatting (18-decimal fixed point, exact) ----
+
+/** "0.05" -> 5e16. Rejects anything that is not a plain decimal with at most 18 decimals. */
+export function parseUnits18(s) {
+  const m = /^(\d+)(?:\.(\d{1,18}))?$/.exec(String(s ?? '').trim());
+  if (!m) return null;
+  return BigInt(m[1]) * UNIT + BigInt((m[2] ?? '').padEnd(18, '0') || '0');
+}
+
+export function fmt18(v) {
+  const neg = v < 0n; if (neg) v = -v;
+  const w = v / UNIT, f = (v % UNIT).toString().padStart(18, '0').replace(/0+$/, '');
+  return `${neg ? '-' : ''}${w}${f ? '.' + f : ''}`;
+}
+
+export const parseBlk = (s) => (/^[1-9]\d{0,11}$/.test(String(s ?? '')) ? Number(s) : null);
+
+// ---- mirrors of contract arithmetic (must match the contracts' integer math exactly) ----
+
+/** NATMarket.costOf: BNB a bid locks, rounded up. */
+export const costOf = (price, amount) => (amount * price + UNIT - 1n) / UNIT;
+/** NATMarket.payOf: the last fill releases everything left, including round-up dust. */
+export const payOf = (bid, amount) => (amount === bid.remaining ? bid.escrow : (amount * bid.price) / UNIT);
+export const marketFee = (pay) => (pay * MARKET_FEE_BPS) / 10_000n;
+/** BNAT.quote: amount = burnGwei * 1e9, fee = 1% floored, per block. Wrap pays out amount - fee; unwrap costs amount + fee. */
+export function wrapAmounts(burnGwei) {
+  const amount = burnGwei * 1_000_000_000n;
+  const fee = (amount * VAULT_FEE_BPS) / 10_000n;
+  return { amount, fee, toHolder: amount - fee, unwrapCost: amount + fee };
+}
+
+/** First block with a BEP-95 burn record; earlier blocks cannot be minted. */
+export const ELEMENT_ACTIVATION_BLOCK = 13_082_000;
+
+// ---- site API ----
+
+export async function api(cfg, path) {
+  if (!cfg.site) throw Error(t('chain.noSiteAddressSetBnat'));
+  const res = await fetch(`${cfg.site}${path}`, { signal: AbortSignal.timeout(30_000) });
+  const body = await res.json().catch(() => null);
+  if (res.status === 503 && /index syncing/.test(body?.error ?? '')) throw Error(`${path}: ${t('chain.indexSyncing')}`);
+  if (!res.ok || body === null || typeof body !== 'object') throw Error(`${path}: ${body?.error ?? `HTTP ${res.status}`}`);
+  return body;
+}
+
+export const MINT_TYPES = { Mint: [{ name: 'blk', type: 'uint256' }, { name: 'burnGwei', type: 'uint256' }] };
+
+/**
+ * Ask the signer for a mint signature and its burn, and check before use that it is for this
+ * contract and recovers to the contract's current signer. The burn is the signer's (the site's
+ * burn index): the CLI does not recompute it.
+ */
+export async function attest(cfg, client, blk) {
+  const body = await api(cfg, `/api/signer/mint/${blk}`);
+  if (typeof body.sig !== 'string' || typeof body.burnGwei !== 'string' || !/^[0-9]+$/.test(body.burnGwei) || body.blk !== blk) throw Error(t('chain.unexpectedReplyFromTheSigning'));
+  if (body.chainId !== cfg.d.chainId || String(body.contract).toLowerCase() !== cfg.d.nat.toLowerCase()) throw Error(t('chain.theSignatureIsNotFor'));
+  const burn = BigInt(body.burnGwei);
+  // The domain comes from the contract itself, so the check can never drift from what mint() verifies.
+  const [[, name, version, chainId, verifyingContract], onchain] = await Promise.all([
+    client.readContract({ address: cfg.d.nat, abi: ABI.nat, functionName: 'eip712Domain' }),
+    client.readContract({ address: cfg.d.nat, abi: ABI.nat, functionName: 'signer' }),
+  ]);
+  const rec = await recoverTypedDataAddress({
+    domain: { name, version, chainId: Number(chainId), verifyingContract }, // viem drops a bigint chainId from the domain type
+    types: MINT_TYPES, primaryType: 'Mint', message: { blk: BigInt(blk), burnGwei: burn }, signature: body.sig,
+  });
+  if (rec.toLowerCase() !== onchain.toLowerCase()) throw Error(t('chain.theSignerDiffersFromThe'));
+  return { sig: body.sig, burn };
+}
+
+// ---- reads ----
+
+export async function walletState(cfg, client, a) {
+  const [agent, bnb, nfts, bnat] = await Promise.all([
+    client.readContract({ address: cfg.d.agentId, abi: ABI.registry, functionName: 'balanceOf', args: [a] }),
+    nativeBalance(client, a),
+    client.readContract({ address: cfg.d.nat, abi: ABI.nat, functionName: 'balanceOf', args: [a] }),
+    client.readContract({ address: cfg.d.bnat, abi: ABI.bnat, functionName: 'balanceOf', args: [a] }),
+  ]);
+  return { address: a, agentId: agent > 0n, bnb, nfts, bnat };
+}
+
+export async function readBid(cfg, client, id) {
+  const n = await client.readContract({ address: cfg.d.market, abi: ABI.market, functionName: 'bidCount' });
+  if (BigInt(id) >= n) throw Error(t('chain.bidDoesnTExistIn', { id, n }));
+  return client.readContract({ address: cfg.d.market, abi: ABI.market, functionName: 'bids', args: [BigInt(id)] });
+}
+
+export const calldata = (abi, functionName, args) => encodeFunctionData({ abi, functionName, args });
+
+/** Decode this contract's events out of a receipt (unknown logs are skipped). */
+export function eventsOf(receipt, abi, address) {
+  const out = [];
+  for (const l of receipt.logs) {
+    if (l.address.toLowerCase() !== address.toLowerCase()) continue;
+    try { out.push(decodeEventLog({ abi, data: l.data, topics: l.topics })); } catch { /* not ours */ }
+  }
+  return out;
+}

package/lib/i18n.mjs

@@ -0,0 +1,96 @@
+// Two languages: the texts live in i18n/zh.json and i18n/en.json, looked up with t(key, params);
+// a text names its parameters as {name}. The language is decided at start, before any other module
+// evaluates (they import this one, and the first-run question below is a top-level await):
+//   1. `--lang zh|en` on the command line (this run only)
+//   2. BNAT_LANG from the environment
+//   3. "lang" in ~/.config/bnat/config.json; on the first run in a terminal, ask once and save it there
+//   4. otherwise (agents, pipes, --json) the locale: Chinese -> zh, anything else -> en
+// The TUI can switch it later with setLang(); texts are looked up when shown, not cached.
+// Children started by the TUI inherit the result through BNAT_LANG.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+const ok = (v) => v === 'zh' || v === 'en';
+
+/** The settings file: ~/.config/bnat/config.json (XDG_CONFIG_HOME respected; BNAT_CONFIG_DIR moves it, for tests). */
+export const configFile = (env = process.env) =>
+  join(env.BNAT_CONFIG_DIR ?? join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'bnat'), 'config.json');
+
+function readConfig(path) {
+  try { const c = JSON.parse(readFileSync(path, 'utf8')); return c && typeof c === 'object' ? c : {}; } catch { return {}; }
+}
+
+/** Set one key in config.json, keeping the others (undefined removes it). */
+export function saveSetting(key, value, path = configFile()) {
+  const c = { ...readConfig(path), [key]: value };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(`${path}.tmp`, `${JSON.stringify(c, null, 2)}\n`);
+  renameSync(`${path}.tmp`, path);
+}
+
+function argLang(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const m = /^--lang(?:=(.*))?$/.exec(argv[i]);
+    if (m) return m[1] ?? argv[i + 1];
+  }
+  return undefined;
+}
+
+const localeLang = (env) => ((env.LC_ALL || env.LC_MESSAGES || env.LANG || '').toLowerCase().startsWith('zh') ? 'zh' : 'en');
+
+async function ask(def) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (;;) {
+      const a = (await rl.question(`选择语言 / Choose language:  1) 中文   2) English   [${def === 'zh' ? 1 : 2}] `)).trim().toLowerCase();
+      if (a === '') return def;
+      if (a === '1' || a === 'zh') return 'zh';
+      if (a === '2' || a === 'en') return 'en';
+    }
+  } finally { rl.close(); }
+}
+
+async function decide(argv = process.argv, env = process.env) {
+  const flag = argLang(argv);
+  if (ok(flag)) return flag;
+  if (ok(env.BNAT_LANG)) return env.BNAT_LANG;
+  const saved = readConfig(configFile(env)).lang;
+  if (ok(saved)) return saved;
+  const interactive = process.stdin.isTTY && process.stdout.isTTY && !argv.includes('--json') && argv[2] !== 'lang';
+  if (!interactive) return localeLang(env);
+  const chosen = await ask(localeLang(env));
+  try {
+    saveSetting('lang', chosen, configFile(env));
+    console.log(chosen === 'zh' ? `已保存到 ${configFile(env)}（改用 bnat lang en）\n` : `Saved to ${configFile(env)} (change with bnat lang zh)\n`);
+  } catch (e) {
+    console.log(chosen === 'zh' ? `没能保存（${e.message}），下次还会再问\n` : `Could not save it (${e.message}); you will be asked again\n`);
+  }
+  return chosen;
+}
+
+export let lang = await decide();
+process.env.BNAT_LANG = lang;
+
+/** Switch the language of this process (and of the children it starts from now on). */
+export function setLang(l) {
+  if (!ok(l)) throw Error(`bad language ${l}`);
+  lang = l;
+  process.env.BNAT_LANG = l;
+}
+
+/** The saved settings (config.json), {} when there are none. */
+export const settings = () => readConfig(configFile());
+
+const dicts = {};
+const dict = (l) => (dicts[l] ??= JSON.parse(readFileSync(new URL(`../i18n/${l}.json`, import.meta.url), 'utf8')));
+
+/** The text for `key` in language `l`, with {name} filled from `params`. */
+export function tIn(l, key, params) {
+  const s = dict(l)[key] ?? key;
+  return params ? s.replace(/\{(\w+)\}/g, (m, k) => (k in params ? String(params[k]) : m)) : s;
+}
+
+/** The text for `key` in the current language. */
+export const t = (key, params) => tIn(lang, key, params);

package/lib/journal.mjs

@@ -0,0 +1,59 @@
+// Append-only journal of every write. An entry is written before `execute`, so a crash
+// between "sent" and "recorded" leaves an open entry that blocks new writes until it is
+// settled with `bnat resume`. Nothing is ever re-sent automatically.
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { t } from './i18n.mjs';
+
+export const stateDir = (env = process.env) => env.BNAT_STATE_DIR ?? join(env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'bnat');
+
+export class Journal {
+  constructor(dir = stateDir()) {
+    mkdirSync(dir, { recursive: true });
+    this.path = join(dir, 'journal.jsonl');
+  }
+
+  /** Entries folded by id, oldest first. */
+  entries() {
+    let text = '';
+    try { text = readFileSync(this.path, 'utf8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    const by = new Map();
+    for (const [i, line] of text.split('\n').entries()) {
+      if (!line.trim()) continue;
+      let ev; // a corrupt line is a hard stop, not a skipped one
+      try { ev = JSON.parse(line); } catch { throw Error(t('journal.corruptLine', { path: this.path, n: i + 1 })); }
+      by.set(ev.id, { ...(by.get(ev.id) ?? {}), ...ev });
+    }
+    return [...by.values()];
+  }
+
+  /** Writes whose outcome is not known yet. */
+  open() {
+    return this.entries().filter((e) => e.status === 'executing' || e.status === 'sent');
+  }
+
+  /** Appended and fsynced before the caller goes on: the "executing" entry must survive a crash
+   * or power loss that happens while the wallet is sending, or the next run could resend. */
+  #append(ev) {
+    const line = JSON.stringify({ ...ev, at: new Date().toISOString() }, (_, v) => (typeof v === 'bigint' ? v.toString() : v)) + '\n';
+    const fd = openSync(this.path, 'a');
+    try {
+      writeSync(fd, line);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+  }
+
+  begin(plan) {
+    const id = randomUUID();
+    this.#append({ id, status: 'executing', ...plan });
+    return id;
+  }
+
+  update(id, fields) {
+    this.#append({ id, ...fields });
+  }
+}