beignet 0.31.0 → 0.32.0

package/README.md

@@ -99,7 +99,7 @@ Tor, full-graph gossip, the low-level `LightningNode` variant and the non-intera
 
 Node state lives in a SQLite DB under `~/.beignet/data/<hash-of-mnemonic>/` (the `--low-level` example uses `example/lightningData/node.db`).
 
-Both examples run straight off the TypeScript sources through `ts-node`, so no build step is needed. Use `npm run build` when you want the compiled `dist/`.
+Both examples run through `ts-node`. The on-chain example runs straight off the TypeScript sources. The Lightning example imports only the public entry points (`beignet`, `beignet/cli`, `beignet/lightning`, `beignet/lightning/sqlite`), so `npm run example:lightning` builds `dist/` first, and the file runs unchanged in a project that installed `beignet` from npm.
 
 **→ [example/REPL_TESTING.md](example/REPL_TESTING.md) is a copy-pasteable walkthrough** of the whole lifecycle in the REPL: funding, peers, channels, invoices, payments, keysend, offers, splicing, closing, backup.
 
@@ -108,7 +108,9 @@ Both examples run straight off the TypeScript sources through `ts-node`, so no b
 | Import | Contains | Use when |
 |--------|----------|----------|
 | `beignet` | `Wallet`, `generateMnemonic`, types | You want the on-chain wallet |
-| `beignet/cli` | `BeignetNode`, `startDaemon`, error helpers | **You want Lightning.** Sats-denominated, string IDs, structured errors |
+| `beignet/node` | `BeignetNode`, error helpers | **You want Lightning.** Sats-denominated, string IDs, structured errors. Runs on React Native |
+| `beignet/daemon` | `startDaemon`, API keys, webhooks | You serve the HTTP API from your own Node process |
+| `beignet/cli` | Both of the above | Existing imports; it loads the daemon too |
 | `beignet/lightning` | Namespaced protocol modules (`node`, `channel`, `onion`, ...) | You need the raw BOLT layer: bigint msat, Buffer IDs, wire messages |
 
 ## On-chain wallet
@@ -132,23 +134,70 @@ await wallet.send({ address: 'bc1q...', amount: 50_000, satsPerByte: 2 });
 await wallet.sendMany({ txs: [{ address: 'bc1q...', amount: 1000 }] });
 await wallet.refreshWallet();
 
-const utxos = wallet.listUtxos();
-const history = await wallet.getAddressHistory('bc1q...');
+const utxos = wallet.listUtxos(); // what the last refresh stored
+const history = await wallet.fetchAddressHistory('bc1q...'); // asks Electrum
+
+// Build and sign without broadcasting, then broadcast separately
+const signed = await wallet.createSignedTransaction({ address: 'bc1q...', amount: 50_000 });
+if (signed.isOk()) await wallet.broadcastTransaction(signed.value.txHex);
 ```
 
-Every fallible call returns a `Result<T>`: check `isErr()` before reading `.value`. Amounts are always satoshis.
+A method's verb says where its answer comes from: `get*` and `list*` read what the wallet holds, `fetch*` asks Electrum, and `refresh*` asks Electrum and stores the answer. [docs/API-CONVENTIONS.md](docs/API-CONVENTIONS.md) lists the older names, which still work and go in the next major release.
+
+Most fallible calls return a `Result<T>`: check `isErr()` before reading `.value`. The error is a `CodedError`: branch on `error.code`, never on the message, which can be reworded. The code is an `EWalletErrorCode` (`UNSPECIFIED` when the failure has no code of its own), or the code of an error passed through unchanged, such as `WATCH_ONLY_CANNOT_SIGN` or a `BoostError`'s. `error.cause` holds the failure it wraps, when there is one.
+
+A few calls do not return a `Result`, so check them differently:
+
+- `getAddress()` resolves to `''` when it cannot derive an address.
+- `fetchFeeEstimates()` never errs. When its sources fail it returns the previous estimates or built-in defaults (fixed values on regtest).
+- `updateAddressType()` throws on a type the wallet cannot use, and `resetAddressIndexes()` resolves to nothing.
+
+Balances, UTXO values and send amounts are satoshis, and fee rates are sat/vB: every `satsPerByte` option and field is sat/vB despite its name. Stored transactions (`wallet.transactions`) carry their amounts in satoshis as `valueSats`, `feeSats`, `totalInputSats`, `matchedInputSats`, `totalOutputSats` and `matchedOutputSats`. Their older BTC twins (`value`, `fee`, `totalInputValue` and the rest) are deprecated and go in the next major release. `btcToSats`, `satsToMsat` and `msatToSatsFloor` convert between units.
+
+Options worth knowing on `Wallet.create`: `network` (`Network.bitcoin` | `testnet` | `regtest` | `signet`), `addressType` (`EAddressType.p2wpkh` default, `p2sh` for P2SH-wrapped segwit, `p2pkh`, `p2tr`), `passphrase`, `account`, `storage`, `logger`, `onMessage`, `coinSelectPreference`, `feeEstimationSource`, `gapLimitOptions`, `remainOffline`.
 
-Options worth knowing on `Wallet.create`: `network` (`EAvailableNetworks.mainnet` | `testnet` | `regtest` | `signet`), `addressType` (`p2wpkh` default, `p2sh-p2wpkh`, `p2pkh`, `p2tr`), `passphrase`, `account`, `storage`, `logger`, `coinSelectPreference`, `feeEstimationSource`, `gapLimitOptions`.
+`remainOffline: true` makes a wallet that never opens a connection: no Electrum server, and no fee lookup over HTTP. Calls that need a server fail, and a refresh stops after deriving the first addresses.
+
+`wallet.data` is a frozen copy of the wallet's data, taken when it is read. Change data with `wallet.updateData({ utxos, balance })`, which replaces those fields and saves them in order with the wallet's own writes. Each read of `wallet.data` copies the whole history, so code reading one field often should use `wallet.balance`, `wallet.utxos` or `wallet.transactions`.
+
+<details>
+<summary><b>Fees, sweeping, boosting, coin control, events and shutdown</b></summary>
+
+```typescript
+import { EBoostType } from 'beignet';
+
+const fees = await wallet.fetchFeeEstimates(); // { fast, normal, slow, minimum, timestamp }, sat/vB
+await wallet.sendMax({ address: 'bc1q...', satsPerByte: fees.normal }); // sweeps every unfrozen coin
+
+// Fee bumping an unconfirmed transaction
+wallet.canBoost(txid);                     // { canBoost, rbf, cpfp }
+wallet.getBoostableTransactions();         // { rbf: [...], cpfp: [...] }
+await wallet.boost({ txid, type: EBoostType.rbf, satsPerByte: 20 }); // or EBoostType.cpfp
+
+// Coin control: a frozen coin is left out of every coin selection
+await wallet.freezeUtxo({ txid, vout: 0 });
+await wallet.unfreezeUtxo({ txid, vout: 0 });
+wallet.listUtxos();           // every coin, frozen ones included
+wallet.listFrozenUtxos();
+wallet.getBalanceBreakdown(); // { total, spendable, frozen }
+
+// Waits (up to refreshTimeout) for an in-flight refresh and queued storage writes
+await wallet.stop();
+```
+
+`onMessage(key, data)` on `Wallet.create` receives wallet events. The keys are `newBlock`, `transactionReceived`, `transactionSent`, `transactionConfirmed` (each with `{ transaction }`), `reorg` (the affected UTXOs), `rbf` (the replaced txids), `connectedToElectrum` (`true` or `false`) and `storageWriteFailed` (a write storage refused). `disableMessages: true` silences them, and `disableMessagesOnCreate: true` holds them until the first refresh ends, so stored history does not replay as news.
+
+</details>
 
 <details>
 <summary><b>Custom Electrum servers, failover, fee sources, BIP21</b></summary>
 
 ```typescript
-import { EAvailableNetworks, EProtocol, Wallet } from 'beignet';
+import { EProtocol, Network, Wallet } from 'beignet';
 
 const res = await Wallet.create({
   mnemonic,
-  network: EAvailableNetworks.mainnet,
+  network: Network.bitcoin,
   feeEstimationSource: 'electrum', // 'electrum' | 'http' | 'auto' (default)
   electrumOptions: {
     net,
@@ -172,12 +221,12 @@ const res = await Wallet.create({
 <details>
 <summary><b>Watch-only wallets (account xpub)</b></summary>
 
-Built from an account-level extended public key instead of a mnemonic. The key is assumed to sit at `m/purpose'/coin'/account'` (e.g. `m/84'/0'/0'`), so addresses derive as `xpub/0/i` and `xpub/1/i`. SLIP-132 version bytes are normalized: `zpub`/`vpub` implies p2wpkh, `ypub`/`upub` implies p2sh-p2wpkh, a plain `xpub`/`tpub` uses `addressType` (default p2wpkh). One account xpub yields exactly one address type, so a watch-only wallet monitors only that type.
+Built from an account-level extended public key instead of a mnemonic. The key is assumed to sit at `m/purpose'/coin'/account'` (e.g. `m/84'/0'/0'`), so addresses derive as `xpub/0/i` and `xpub/1/i`. SLIP-132 version bytes are normalized: `zpub`/`vpub` implies p2wpkh, `ypub`/`upub` implies p2sh-p2wpkh (`EAddressType.p2sh`), a plain `xpub`/`tpub` uses `addressType` (default p2wpkh). One account xpub yields exactly one address type, so a watch-only wallet monitors only that type.
 
 ```typescript
 const res = await Wallet.createWatchOnly({
   xpub: 'zpub6r...',
-  network: EAvailableNetworks.mainnet,
+  network: Network.bitcoin,
   electrumOptions: { net, tls }
 });
 if (res.isErr()) return;
@@ -244,7 +293,7 @@ const a = await Wallet.createMultisig({
   threshold: 2,
   mnemonic: mnemonicA,       // we are one cosigner; our xpub is added automatically
   cosigners: [xpubB, xpubC],
-  network: EAvailableNetworks.mainnet,
+  network: Network.bitcoin,
   electrumOptions: { net, tls }
 });
 const b = await Wallet.createMultisig({ threshold: 2, mnemonic: mnemonicB, cosigners: [xpubA, xpubC], /* ... */ });
@@ -280,7 +329,9 @@ await coordinator.broadcastTransaction(finalized.value.txHex);
 // 'Input 0 is below the multisig threshold: have 1 signature(s), need 2.'
 
 // Interop: import into Bitcoin Core / Sparrow / Specter.
-coordinator.exportDescriptors();
+const exported = coordinator.exportDescriptors(); // Result<IExportDescriptorsResponse>
+if (exported.isErr()) return;
+exported.value.descriptors[0].external;
 // wsh(sortedmulti(2,[fp/48h/0h/0h/2h]xpub.../0/*,[fp]xpub.../0/*,...))#checksum
 ```
 
@@ -289,13 +340,19 @@ coordinator.exportDescriptors();
 </details>
 
 <details>
-<summary><b>Encrypted storage and leveled logging</b></summary>
+<summary><b>Storage, encryption and leveled logging</b></summary>
+
+The wallet persists through the `storage` option, an `IWalletStorage`: `getData(key)`, `setData(key, value)` and the optional `setTransactionChanges` below. It holds one value per `IWalletData` field, under `<name>-<network>-<field>` (`<name>-<network>-acct<n>-<field>` for a non-zero account), and each value is plain JSON data. `createMemoryStorage()` implements all of it in memory: use it for tests and short-lived wallets, and start from it when writing a persistent store. Without `storage` the wallet keeps its data in memory and saves nothing.
 
-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.
+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.
+`setData` must keep a copy of the value: the wallet goes on changing the object it handed over. Writes to one key arrive one at a time, in the order the wallet made them. A write that resolves `err`, or rejects, reaches `onMessage` as `storageWriteFailed`.
+
+By default every change to the transaction history hands `setData` the whole history. A storage that also implements `setTransactionChanges(key, { set, deleted })` gets only the records that changed: new transactions, confirmations, reorgs, deletions and boosts. Its `getData` must then return the history with those changes applied. Replacing or clearing the history, and the one-time upgrade of old records on load, still go through `setData`. `createEncryptedStorage` does not pass `setTransactionChanges` through, so an encrypted storage keeps receiving the whole history.
+
+Wrap any `IWalletStorage` 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
 import * as bip39 from 'bip39';
@@ -326,10 +383,10 @@ Diagnostics flow through a small injectable `ILogger` (`debug`/`info`/`warn`/`er
 > putting meaningful mainnet funds behind it: this is a self-custodial Lightning
 > implementation, and channel funds are only as safe as the node watching them.
 
-`BeignetNode` from `beignet/cli` is the recommended API: it wraps the protocol layer with satoshi amounts, string channel IDs and structured error codes.
+`BeignetNode` from `beignet/node` is the recommended API: it wraps the protocol layer with satoshi amounts, string channel IDs and structured error codes. `beignet/cli` exports it too.
 
 ```typescript
-import { BeignetNode, isRetryableError } from 'beignet/cli';
+import { BeignetNode, isRetryableError } from 'beignet/node';
 
 // Creates the wallet, storage and funding provider for you
 const node = await BeignetNode.create({
@@ -364,7 +421,7 @@ node.listInvoices();
 await node.destroy();
 ```
 
-Events: `node:ready`, `channel:ready`, `channel:closed`, `channel:resolved`, `peer:connect`, `peer:disconnect`, `peer:error`, `payment:sent`, `payment:received`, `node:error`, `log`.
+`BeignetNode` is a typed emitter: `node.on('channel:ready', ({ channelId }) => ...)`. Every event, its payload and whether the daemon relays it over SSE is in the [generated events table](src/cli/README.md#events); every `BeignetNode.create` option is in the [options table](src/cli/README.md#factory).
 
 Useful variants: `payInvoiceSafe` (never throws), `payInvoiceWithRetry({ maxRetries, backoffMs, maxFeeSats })`, `sendPaymentAsync` (returns the hash immediately), `connectAndOpenChannel`, `openChannelAndWait`, `sendKeysend`, `createOffer`/`payOffer`, `spliceIn`/`spliceOut`, `backup`, `gracefulShutdown`.
 
@@ -493,7 +550,7 @@ curl http://localhost:2112/ready                                       # load-ba
 - Full spec at `GET /openapi.json`.
 - Authentication is on for every install `beignet init` creates (releases after 0.22.0): `init` mints a random `apiToken` and saves it in `config.json` (run `init` again on an older config to add one). Auth is off only for a config with neither `apiToken` nor `apiKeys` (named keys with `readonly`/`invoice`/`admin` scopes); `beignet start` warns on stderr in that case. `GET /health`, `/ready` and `/openapi.json` are auth-exempt; `/metrics` only with `metricsPublic`; everything else requires the bearer token. The daemon binds `127.0.0.1` by default.
 - While auth is off, three browser guards keep a web page from driving the loopback daemon (issue #1005): a request body must be `Content-Type: application/json` (else `415 UNSUPPORTED_MEDIA_TYPE`), an `Origin` other than the configured `cors` origin or a `Sec-Fetch-Site: cross-site` request is refused (`403 CROSS_SITE_REQUEST_REFUSED`), and the `Host` header must be the loopback name the daemon is bound on (else `421 HOST_NOT_ALLOWED`, which also defeats DNS rebinding). They apply to every route but `OPTIONS`; plain clients (curl, the CLI, the SDKs) send none of those headers and are unaffected, and with a token configured the guards do not run at all.
-- Embed it instead of shelling out: `import { startDaemon } from 'beignet/cli'`.
+- Embed it instead of shelling out: `import { startDaemon } from 'beignet/daemon'`.
 
 ### FFOR offline receive
 
@@ -513,8 +570,7 @@ node can run for others, each an explicit opt-in switched on with an exact
 | `BEIGNET_FFOR_WITNESS` | Store a receiver-encrypted record of every delegated preimage this node relays before propagating the fulfil (a receipt witness). `BEIGNET_FFOR_WITNESS_MAX_MAILBOXES` and `BEIGNET_FFOR_WITNESS_MAX_BYTES` cap it. `GET /ffor/witness/status`. |
 | `BEIGNET_FFOR_ISSUER` | Answer BOLT 12 invoice requests for offers a receiver delegated to this node, one fixed-amount slot per invoice. Needs the witness. `GET /ffor/issuer/status`. |
 
-The SSE stream carries `ffor:state`, `ffor:settled`, `ffor:slot-resolved`, `ffor:delegated-failed`,
-`ffor:enforce` and the witness and issuer events.
+The SSE stream carries every `ffor:*` event (see the [events table](src/cli/README.md#events)).
 
 The experimental concurrent profile keeps ordinary payments available
 within the channel's remaining capacity. `LightningNode.fforSync()` fetches paid
@@ -555,10 +611,8 @@ depth and been re-verified unspent immediately before the dispatch, binds
 every HTLC of the payment to `refundHeight` minus its claim margins, judges
 the payment by the node's own HTLC view (never by a wall clock or a failed
 record while an HTLC is out), and persists its claim before broadcasting it.
-The SSE stream carries `swap:created` through `swap:settled`, `swap:refunded`
-and `swap:exposed` for the reverse direction and `swap:funding-seen`,
-`swap:paying`, `swap:preimage`, `swap:claim-broadcast`,
-`swap:claim-confirmed` and `swap:payment-failed` for the submarine one.
+The SSE stream carries every `swap:*` event of both directions (see the
+[events table](src/cli/README.md#events)).
 
 ## Protocol layer (advanced)
 
@@ -600,14 +654,14 @@ node.on('node:error', (err) => console.error(`[${err.code}]`, err.message));
 Without a `fundingProvider`, build the funding transaction yourself and call `node.createFunding(channel, fundingTxid, outputIndex, signature)` after `openChannel`.
 
 ```
-LightningNode              High-level API (EventEmitter)
+LightningNode              High-level API (typed EventEmitter)
   ├── ChannelManager       Multiplexes messages to Channel instances
-  │     └── Channel        BOLT 2 state machine (returns ChannelAction[])
-  ├── PeerManager          TCP connections + Noise_XK encrypted transport
+  │     ├── Channel        BOLT 2 state machine (returns ChannelAction[])
+  │     └── ChainMonitor   BOLT 5 force-close detection + sweep
+  ├── PeerManager          TCP/WebSocket connections + Noise_XK encrypted transport
   │     └── Peer           Per-connection BOLT 8 handshake + message framing
   ├── NetworkGraph         BOLT 7 gossip topology + Dijkstra pathfinding
-  ├── InvoiceManager       BOLT 11 encode/decode/sign
-  ├── ChainMonitor         BOLT 5 force-close detection + sweep
+  ├── invoice (module)     BOLT 11 encode/decode/sign functions
   └── FundingProvider?     Auto-builds + broadcasts funding txs (via Wallet)
 ```
 
@@ -615,64 +669,9 @@ LightningNode              High-level API (EventEmitter)
 
 **→ [src/lightning/README.md](src/lightning/README.md)** documents the protocol layer in detail: data flow, events reference, typed payment errors, channel lifecycle, zero-conf, anchors, dual funding, splicing, offers, onion messages, forwarding, chain monitoring.
 
-<details>
-<summary><b>BOLT coverage</b></summary>
-
-| BOLT | Specification | Implemented |
-|------|--------------|-------------|
-| 1 | Base Protocol | Peer messaging, init, error, ping/pong, feature negotiation, peer storage |
-| 2 | Channel Management | Full state machine: open, fund, normal operation, shutdown, close, reestablish; v2 dual-funded opens (interactive-tx), splicing, quiescence |
-| 3 | Transactions | Commitment txs, HTLC scripts, funding scripts, anchor outputs, fee calculation; simple taproot channels (MuSig2 funding, Schnorr HTLC sigs) |
-| 4 | Onion Routing | Sphinx encryption, TLV hop payloads, payment_secret, failure codes, route blinding, onion messages |
-| 5 | On-Chain | Force-close detection, HTLC sweep, output resolution, chain monitoring, wallet-funded anchor fee bumping (commitment CPFP + zero-fee HTLC fee-attach) |
-| 7 | Gossip | Channel/node announcements, network graph, Dijkstra routing, gossip sync, Rapid Gossip Sync |
-| 8 | Transport | Noise_XK handshake, encrypted transport, key rotation |
-| 9 | Features | DATA_LOSS_PROTECT, STATIC_REMOTE_KEY, PAYMENT_SECRET, TLV_ONION, BASIC_MPP, CHANNEL_TYPE, GOSSIP_QUERIES, ANCHORS_ZERO_FEE_HTLC_TX (default), ROUTE_BLINDING, ONION_MESSAGES, QUIESCE, SCID_ALIAS, ZERO_CONF, KEYSEND, OPTION_TAPROOT, OPTION_WILL_FUND |
-| 10 | DNS Bootstrap | Seed resolution for discovering initial peers |
-| 11 | Invoices | Encode, decode, sign, verify, amount formatting, hold invoices |
-| 12 | Offers | Offer encode/decode, invoice_request/invoice over onion messages, receive-side settlement, async payment offers |
-| bLIP-51 | Liquidity Ads | lease_rates/request_funds/will_fund negotiation, lease fee accounting, CLTV-locked lessor to_local, advisor lease quoting |
-
-</details>
-
-<details>
-<summary><b>Module reference (<code>src/lightning/</code>)</b></summary>
-
-| Module | Description |
-|--------|-------------|
-| `crypto/` | ChaCha20-Poly1305 AEAD, ECDH, HKDF, MuSig2 (BIP 327) for taproot channels |
-| `message/` | Wire encode/decode for all channel, gossip and control messages |
-| `features/` | Feature flag bitmap management (BOLT 9) |
-| `transport/` | Noise_XK handshake, transport cipher, TCP/WebSocket peer connections, PeerManager |
-| `keys/` | HD derivation, per-commitment secrets (shachain), signing, wallet keys |
-| `script/` | Funding 2-of-2 multisig, commitment outputs, HTLC scripts, revocation, anchors, taproot scripts |
-| `channel/` | Channel state machine, ChannelManager, commitment builder, actions, validation, liquidity ads |
-| `chain/` | ChainMonitor, ChainWatcher, output resolver, closing tx, sweep tx, Electrum backend |
-| `invoice/` | BOLT 11 encoding/decoding, bech32 words, signature verification |
-| `gossip/` | NetworkGraph, Dijkstra pathfinding, gossip sync state machine, SCID encoding |
-| `onion/` | Sphinx crypto, packet construction/processing, hop payloads, failures, blinded paths |
-| `onion-message/` | Onion message construction/processing (carries BOLT 12 and async-payment messages) |
-| `offer/` | BOLT 12 offers: encode/decode, OfferManager invoice_request/invoice flows |
-| `async-payments/` | Hold invoices and AsyncPaymentManager (LSP held-forward, release_held_htlc, wake) |
-| `ffor/` | FFOR Variant D offline receive: signed epoch lifecycle, voucher book, transcript hashes, delegated settlement arithmetic |
-| `interactive-tx/` | Interactive transaction construction for v2 dual-funded opens and splicing |
-| `watchtower/` | Altruist watchtower client: wtwire protocol, justice blobs, tower sessions |
-| `backup/` | Static channel backup (SCB) export/import |
-| `recovery/` | Safety transition layer: atomic persistence, the durable outbound-message outbox, the opt-in hash-chained recovery journal, and the peer_storage Recovery Capsule |
-| `liquidity/` | JIT channel receive (LSP role): intercept SCIDs, held HTLCs, zero-conf open or splice, then forward; the opening fee is skimmed off the delivery for wallets that accept it, or charged to the sender through the invoice hint (hop mode) for wallets that cannot settle a short HTLC |
-| `direct-funding/` | Third-party direct funding: the signed payment request envelope, sealed frames, protocol messages, outstanding-request store, the transport registry with its direct-peer, onion and blind-relay lanes, the receiver engine that turns a payer's offered UTXO into channel funding, and the payer engine that verifies and signs it |
-| `swaps/` | Swaps: the P2WSH HTLC contract, claim/refund transactions, preimage extraction, admission policies, the durable swap ledger, the chain resolver, the wire protocol, and the swap provider engines (reverse: Lightning to on-chain; submarine: on-chain to Lightning) |
-| `l402/` | L402 (Lightning HTTP 402) client: challenge parsing, macaroon reading, paid credentials |
-| `node/` | LightningNode orchestrator, the main protocol-layer entry point |
-| `wallet/` | WalletFundingProvider, adapts the on-chain Wallet for auto-funded opens |
-| `bootstrap/` | DNS seed resolution for discovering initial peers |
-| `advisor/` | Liquidity, fee and channel-suggestion advisors |
-| `storage/` | SQLite persistence backend, channel state serialization |
-| `validation/` | Input validation shared across modules |
-
-`beignet/lightning` re-exports each of these as a namespace (`crypto`, `message`, `node`, ...). `async-payments` and `watchtower` are reachable via their source paths.
+The protocol-layer README has the [BOLT coverage table](src/lightning/README.md#bolt-specification-coverage) and the [module reference](src/lightning/README.md#module-reference), one row per module of `src/lightning/` with its key exports. `beignet/lightning` re-exports each module as a namespace, camel-casing hyphenated names: `import { asyncPayments, ffor, watchtower } from 'beignet/lightning'`.
 
-</details>
+`SqliteStorage` and `GuardianStore` load from `beignet/lightning/sqlite`. They need `better-sqlite3`, an optional dependency that npm installs by default, and `beignet/lightning` loads without it.
 
 ## Tests
 
@@ -688,19 +687,21 @@ every TypeScript file.
 
 ```bash
 npm run test:local         # test:lightning + test:cli at once; no infrastructure needed
-npm run test:lightning     # 6200+ Lightning unit tests (parallel), no infrastructure needed
-npm run test:cli           # 1350+ CLI + daemon unit tests (parallel), no infrastructure needed
-npm run test:conformance   # 250+ official BOLT vector cases (subset of test:lightning)
+npm run coverage           # test:local under c8, with a coverage summary of src
+npm run test:lightning     # 9500+ Lightning unit tests (parallel), no infrastructure needed
+npm run test:cli           # 2200+ CLI + daemon unit tests (parallel), no infrastructure needed
+npm run test:conformance   # 300+ official BOLT vector cases (subset of test:lightning)
 npm run test:chaos         # recovery kill matrices (parallel), split out of test:lightning
 npm run test:sigkill       # process-level SIGKILL chaos matrix (builds dist first)
+npm run test:api           # exported API vs tests/api-snapshot (npm run api:snapshot regenerates it)
 npm run test:integration   # daemon/Electrum integration (needs an Electrum server)
-npm run test:interop       # 190+ cases vs LND/CLN/Eclair (needs Docker)
+npm run test:interop       # 300+ cases vs LND/CLN/Eclair (needs Docker)
 npm run test:interop:ffor  # FFOR Variant D chain gates on regtest (needs only the bitcoind container)
 npm run test:interop:ffor-concurrent  # Concurrent receive process, durable boundary and current-chain qualification (bitcoind regtest)
 npm run test:all           # Lightning + CLI + interop (needs Docker + Electrum)
 ```
 
-Counts are floors, not snapshots. Run the suites for exact numbers.
+Counts are floors, not snapshots, and this is the only place they are kept. Run the suites for exact numbers (`npx mocha --dry-run` with a suite's arguments counts without running).
 
 `test:local` is the fast inner loop. `test:lightning` and `test:cli` are
 independent processes and neither saturates the machine alone, so running them at
@@ -716,6 +717,15 @@ three concurrently failed with `chaosWait timed out with the victim alive` while
 the same suite passes 30/30 on its own. Run it separately. See
 `scripts/run-suites.js` for the worker split and why more workers is not better.
 
+`npm run coverage` prints a line, branch and function summary for `src`, and
+writes per-file numbers to `coverage/coverage-summary.json` and per-line hits to
+`coverage/lcov.info`. CI prints a summary per suite at the end of its
+`test:lightning` and `test:cli` steps. The numbers are information, not a gate:
+no threshold is set, and nothing fails on a percentage. A file the run never
+loads counts as wholly uncovered. Two runs of the same tree can differ by a few
+covered lines, because tests with random keys reach different branches. c8 also
+counts a comment or type declaration as covered when the code around it ran.
+
 The on-chain wallet suites live in `tests/*.test.ts` and connect to **live public
 Electrum servers**, so they need network access and can fail on a server outage
 rather than on your change. Each script runs `npm run build` first:
@@ -810,21 +820,43 @@ Recommended safeguards in production:
 }
 ```
 
+`BeignetNode` runs there from `beignet/node`, on storage passed in place of SQLite:
+
+```typescript
+import { BeignetNode } from 'beignet/node';
+import { storage } from 'beignet/lightning';
+
+const node = await BeignetNode.create({
+  network: 'mainnet',
+  mnemonic,
+  storage: new storage.MemoryStorage(), // or a backend over the app's database
+});
+```
+
+Neither entry loads `fs`, `net`, `tls` or better-sqlite3 when imported. The node requires `net` and `tls` when it opens a connection, and `fs` only for a `dataDir`, which a node on `storage` does not need. Both entries still import `crypto`, `path`, `os`, `dns`, `http`, `https` and `zlib`, so the bundle needs a substitute for each.
+
+The backend must implement the `walletData` capability: the node keeps its wallet state, spend ledger and sweep journal there. `MemoryStorage` loses everything when the app exits, so a wallet needs a backend over a persistent store; [src/lightning/README.md](src/lightning/README.md) describes the interface and its conformance suite. On such a node the payment queue lives in memory, and what copies or installs a SQLite file (`backupPath`, `backup()`, capsule restore) is refused.
+
+Nothing in the `beignet` entry loads Node `crypto` until `createEncryptedStorage` is first called. It then needs HKDF-SHA256, random bytes and AES-256-GCM. An app that encrypts wallet storage either ships a `crypto` shim that covers those, or passes its own implementation (of the `ICryptoProvider` interface) to `setCryptoProvider` before the first call. Each primitive is checked against a known-answer vector before its first use, and one that fails throws an error naming it rather than returning wrong bytes. The check catches a missing or broken primitive, not a weak one: no test can tell predictable random bytes from secure ones, so a provider's `randomBytes` must come from the platform's secure generator.
+
 ## Documentation
 
-| Document | Contents |
-|----------|----------|
-| [example/REPL_TESTING.md](example/REPL_TESTING.md) | Copy-pasteable REPL walkthrough of the full node lifecycle |
-| [docs/AI_AGENT_GUIDE.md](docs/AI_AGENT_GUIDE.md) | Deployment, monitoring, safety rails, HTTP daemon patterns |
-| [src/lightning/README.md](src/lightning/README.md) | Protocol-layer reference and usage guide |
-| [docs/ROADMAP.md](docs/ROADMAP.md) | Feature roadmap and progress |
-| [docs/RECOVERY-PROTOCOL.md](docs/RECOVERY-PROTOCOL.md) | Proposed replicated state-continuity design |
-| [API reference](docs/markdown/classes/Wallet.md) | Generated typedoc ([HTML](docs/html/classes/Wallet.html)) |
+[docs/README.md](docs/README.md) indexes every guide, reference and design document in the repository.
+
+The API reference for every entry point (`beignet`, `beignet/node`, `beignet/daemon`, `beignet/cli`, `beignet/lightning`, `beignet/lightning/sqlite`, `beignet/lightning/iroh-node`) is generated by typedoc and not kept in git. CI builds it on every run and uploads it as the `api-docs` artifact of the docs workflow; `npm run docs:html` (or `docs:markdown`) builds it locally into `api-docs/`.
 
 ## Support
 
 Open an issue, or reach out on [Telegram](https://t.me/bitkitchat).
 
+## Security
+
+Report a vulnerability privately, as [SECURITY.md](SECURITY.md) describes, and not in a public issue.
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md) covers setup, the checks CI runs, and the rules for pull requests.
+
 ## License
 
 MIT