beignet 0.30.1 → 0.31.0

package/README.md

@@ -7,7 +7,7 @@ Two layers, one mnemonic:
 - **On-chain wallet:** HD keys, address generation, UTXO tracking, transaction building, PSBT/hardware signing, multisig, watch-only, Electrum connectivity.
 - **Lightning:** channel lifecycle, onion-routed payments, BOLT 11 invoices, BOLT 12 offers, gossip and pathfinding, anchors, splicing, taproot channels, watchtower client. Interop-tested against LND, Core Lightning and Eclair on regtest.
 
-Requires **Node.js 18+**. MIT licensed.
+Requires **Node.js 22.23.4+, 24.22.1+ or 26.12.1+**. Earlier releases on those lines, and all of Node.js 18 and 20, lack the October 21, 2026 Node.js security fixes; the daemon warns at startup when it runs on one. MIT licensed.
 
 **Jump to:** [Install](#install) · [Examples](#try-the-examples) · [On-chain wallet](#on-chain-wallet) · [Lightning](#lightning) · [Daemon & CLI](#http-daemon--cli) · [Protocol layer](#protocol-layer-advanced) · [Tests](#tests) · [Status & limitations](#status--limitations)
 
@@ -52,16 +52,16 @@ npm install
 npm run example
 ```
 
-Creates a mainnet wallet (a fresh mnemonic unless you pass one), syncs it against a public Electrum server, prints the balance and a receive address, then drops you at a `>` prompt with the wallet bound to `wallet`. Type `help()` for the command list.
+Creates a regtest wallet (a fresh mnemonic unless you pass one), syncs it against a public Electrum server, prints the balance and a receive address, then drops you at a `>` prompt with the wallet bound to `wallet`. Type `help()` for the command list.
 
 ```js
 > wallet.getBalance()
 > await wallet.getAddress()
 > await wallet.refreshWallet()
-> await wallet.send({ address: 'bc1q...', amount: 10000, satsPerByte: 2 })
+> await wallet.send({ address: 'bcrt1q...', amount: 10000, satsPerByte: 2 })
 ```
 
-State persists as JSON under `example/walletData/`. Pass a mnemonic as the first argument to reuse a wallet: `npm run example -- "abandon abandon ... about"`.
+State persists as JSON under `example/walletData/`. Pass a mnemonic to reuse a wallet: `npm run example -- "abandon abandon ... about"`. Pass `testnet` or `mainnet` to change the network.
 
 ### 2. Lightning node REPL
 
@@ -69,7 +69,7 @@ State persists as JSON under `example/walletData/`. Pass a mnemonic as the first
 npm run example:lightning
 ```
 
-Boots a real Lightning node (`BeignetNode`) with an auto-created wallet, storage and funding provider, waits for it to become operational, prints info/balance/health, and drops you at a `beignet>` prompt with the node bound to `node`. Type `help()` for the command list. Top-level `await` works.
+Boots a real regtest Lightning node (`BeignetNode`) with an auto-created wallet, storage and funding provider, waits for it to become operational, prints info/balance/health, and drops you at a `beignet>` prompt with the node bound to `node`. Type `help()` for the command list. Top-level `await` works.
 
 ```js
 beignet> await node.getNewAddress()          // fund this on-chain, then:
@@ -83,7 +83,7 @@ The flags you will actually reach for (everything after `--`):
 
 | Flag | Effect |
 |------|--------|
-| `mainnet` \| `testnet` \| `regtest` | Network, as a bare positional arg (default `mainnet`) |
+| `mainnet` \| `testnet` \| `regtest` | Network, as a bare positional arg (default `regtest`) |
 | `<12 or 24 words>` | Reuse a mnemonic, as bare positional args (default generates one) |
 | `--electrum-host <h>` `--electrum-port <p>` | Point at your own Electrum server |
 | `--alias <name>` | Node alias in `node_announcement` |
@@ -93,6 +93,8 @@ The flags you will actually reach for (everything after `--`):
 npm run example:lightning -- regtest --electrum-host 127.0.0.1 --electrum-port 60001 --alias mynode
 ```
 
+Both examples print the network and the mnemonic before anything else. A generated mnemonic exists only in that output, so write it down before funding the wallet, and pass your own on mainnet.
+
 Tor, full-graph gossip, the low-level `LightningNode` variant and the non-interactive payment-API walkthrough have flags too: see [the flag reference](example/REPL_TESTING.md#repl-flags).
 
 Node state lives in a SQLite DB under `~/.beignet/data/<hash-of-mnemonic>/` (the `--low-level` example uses `example/lightningData/node.db`).
@@ -160,7 +162,7 @@ const res = await Wallet.create({
 ```
 
 - **Failover:** with multiple servers the wallet rotates through them in order on connect/reconnect failure, then through hardcoded fallback peers for the network, with a per-server cooldown so dead servers are not hammered. Inspect `wallet.electrum.currentServer` and `wallet.electrum.rotationCount`.
-- **Certificate verification:** by default a TLS Electrum connection is encrypted but the server certificate is not checked, because the client library dials with `rejectUnauthorized: false`. An on-path attacker can therefore stand in for the server. On Node, pass `tls: withTlsVerification(tls)` to accept only certificates that chain to a trusted CA and match the host, and add `{ fingerprints: ['AB:CD:…'] }` to also accept self-signed servers by SHA-256 fingerprint (`openssl x509 -noout -fingerprint -sha256`). The CLI/daemon and React Native do not verify yet.
+- **Certificate verification:** by default a TLS Electrum connection is encrypted but the server certificate is not checked, because the client library dials with `rejectUnauthorized: false`. An on-path attacker can therefore stand in for the server. On Node, pass `tls: withTlsVerification(tls)` to accept only certificates that chain to a trusted CA and match the host, and add `{ fingerprints: ['AB:CD:…'] }` to also accept self-signed servers by SHA-256 fingerprint (`openssl x509 -noout -fingerprint -sha256`). A caller that resolves the host itself and dials the address passes `{ servernames: { [address]: hostName } }` so the check still uses the name. The client library keeps one connection per network for the whole process, shared by every wallet on that network, so wallets in one process should all pass the same `tls`. The daemon verifies when `BEIGNET_ELECTRUM_TLS_VERIFY=true` (see `src/cli/README.md`); it is off by default. React Native does not verify yet.
 - **Fee source:** `'electrum'` queries only the connected server via `blockchain.estimatefee`, so fee lookups never leak to mempool.space/blocktank over clearnet. `'auto'` prefers Electrum and falls back to HTTP. All remote rates are clamped to 5000 sat/vB.
 - **Networks:** mainnet, testnet, regtest and signet work end to end (wallet, Electrum, CLI/daemon `--network signet`, Lightning chain hash and `tbs` invoice prefix). Signet shares testnet address formats and coin type 1.
 - **BIP21:** `encodeBip21({ address, amountSats?, label?, message? })` builds a `bitcoin:` URI.
@@ -291,6 +293,8 @@ coordinator.exportDescriptors();
 
 The wallet persists through the host-injected `TStorage` interface (`storage: { getData, setData }`), and values are handed over as-is, so by default they are stored in plaintext. Persisted data is addresses, indexes, UTXOs, transactions, balance and fee estimates: no private keys and no mnemonic are ever written, so exposure is a privacy concern (full wallet history), not fund loss. The staged send (`transaction`) is written without signing keys, so a key pair handed to `sweepPrivateKey` or `addExternalInputs` never reaches storage, and `send`, `sendMany`, `sendMax`, `buildPsbt` and `sweepPrivateKey` reset the staged send when they return, so a restart never replays an earlier call's recipients.
 
+`getData` must return `ok(undefined)` for a key it does not hold and `err` only when the read fails. `Wallet.create` returns an error on a failed read rather than start from defaults and save them over the data it could not read; pass `resetOnReadFailure: true` to start from defaults anyway.
+
 Wrap any `TStorage` with `createEncryptedStorage` to encrypt at rest with AES-256-GCM under an HKDF-derived key from the seed. Pre-existing plaintext values pass through unchanged and migrate lazily as they are rewritten.
 
 ```typescript
@@ -403,6 +407,7 @@ Automatic modes, opt-in via `BeignetNodeOptions` / `INodeConfig`:
 ```typescript
 const node = await BeignetNode.create({
   mnemonic,
+  network: 'mainnet',
   // Periodically executes the rebalance plan. Routing fees spent on rebalances
   // are capped per UTC day and the running spend is persisted, so restarts
   // never overspend the same day. Resets at midnight UTC.
@@ -428,6 +433,7 @@ Penalty enforcement normally needs this node's chain monitor to be online: if a
 ```typescript
 const node = await BeignetNode.create({
   mnemonic,
+  network: 'mainnet',
   watchtowers: ['03abc...@tower.example.com:9911'] // off when empty
 });
 ```
@@ -670,9 +676,8 @@ LightningNode              High-level API (EventEmitter)
 
 ## Tests
 
-Use **Node.js 20 (20.19+)** for development and `npm ci` to install the locked tools.
-The linter and test runner have newer Node requirements than the library API.
-CI uses Node.js 20.
+Use **Node.js 24 (24.22.1+)** for development and `npm ci` to install the locked tools.
+CI uses Node.js 24.22.1.
 
 The lint configuration keeps the established CommonJS imports, enum aliases,
 unused catch bindings, `any` warnings and Chai assertion style. Rules removed