beignet 0.1.1 → 0.3.0

package/README.md

@@ -137,6 +137,210 @@ const utxos = wallet.value.listUtxos();
 const history = await wallet.value.getAddressHistory('bc1q...');
 ```
 
+### Watch-Only Wallets
+
+A watch-only wallet is constructed from an account-level extended public key
+(xpub/ypub/zpub for mainnet, tpub/upub/vpub for testnet/regtest) instead of a
+mnemonic. The key is assumed to sit at the account level
+(m/purpose'/coin'/account', e.g. m/84'/0'/0' for p2wpkh), so receive and
+change addresses derive publicly as xpub/0/i and xpub/1/i. SLIP-132 version
+bytes are normalized automatically: a zpub/vpub implies p2wpkh and a
+ypub/upub implies p2sh-p2wpkh; a plain xpub/tpub uses the `addressType`
+option (default p2wpkh). Because one account xpub yields exactly one address
+type, a watch-only wallet monitors only that type.
+
+Everything read-only works: address generation, gap-limit scanning, Electrum
+refresh, balances, transaction history, UTXOs, fee estimates and address
+subscriptions. Anything that requires private keys
+(send/sendMax/sendMany/sweepPrivateKey/getPrivateKey and the internal signing
+paths) fails with the typed `WatchOnlySigningError`
+(`code: 'WATCH_ONLY_CANNOT_SIGN'`, message `watch-only wallet cannot sign`).
+
+Watch-only is a library feature only for now: the HTTP daemon always runs
+with a mnemonic.
+
+```typescript
+import { Wallet } from 'beignet';
+
+const res = await Wallet.createWatchOnly({
+  xpub: 'zpub6r...',
+  network: 'bitcoin',
+  electrumOptions: { net, tls },
+});
+if (res.isErr()) return;
+const watchOnly = res.value;
+
+const address = await watchOnly.getAddress(); // works
+const balance = watchOnly.getBalance(); // works
+const sendRes = await watchOnly.send({ address: 'bc1q...', amount: 1000 });
+// sendRes.isErr() === true; sendRes.error.message === 'watch-only wallet cannot sign'
+```
+
+### External Signer (Hardware Wallet) PSBT Flow
+
+`buildPsbt` runs the normal transaction setup (coin selection, change, fee)
+but stops before signing and returns a base64 PSBT populated with everything
+a hardware signer needs: `witnessUtxo` (or `nonWitnessUtxo` for legacy
+p2pkh), `redeemScript` for p2sh-p2wpkh, `tapInternalKey` plus
+`tapBip32Derivation` for p2tr, and `bip32Derivation` (fingerprint + path +
+pubkey) on every wallet input. It works on both full and watch-only wallets.
+Note for watch-only wallets: the true master fingerprint is unknowable from
+an account xpub, so the xpub's parent fingerprint is used; signers should
+locate keys by derivation path.
+
+```typescript
+// 1. Build (works on a watch-only wallet)
+const build = await wallet.buildPsbt({
+  address: 'bc1q...',
+  amount: 50000,
+  satsPerByte: 4,
+});
+if (build.isErr()) return;
+const { psbtBase64, fee, vsizeEstimate } = build.value;
+
+// 2. Sign externally (hardware wallet / HWI / another machine)
+const signedBase64 = await myHardwareWallet.signPsbt(psbtBase64);
+
+// 3. Import: validates a signature on EVERY input, finalizes, does NOT broadcast
+const imported = wallet.importSignedPsbt(signedBase64);
+if (imported.isErr()) return; // missing/invalid signatures are rejected loudly
+const { txHex, txid } = imported.value;
+
+// 4. Broadcast when ready
+await wallet.broadcastTransaction(txHex);
+
+// Multi-party signing: merge partially signed copies of the same PSBT
+const combined = wallet.combinePsbts([copyA, copyB]);
+```
+
+The HTTP daemon exposes the same flow on its (mnemonic-backed) wallet via
+`POST /psbt/build`, `POST /psbt/import-signed` and `POST /psbt/combine`, and
+the CLI via `beignet psbt build|import-signed|combine`.
+
+### Multisig P2WSH Wallets (sortedmulti)
+
+`Wallet.createMultisig` creates a descriptor-based sorted-multisig wallet:
+`wsh(sortedmulti(threshold, key1, key2, ...))`, the interoperable standard
+used by Bitcoin Core, Sparrow and Specter. Derivation follows BIP 48 with
+script type 2 (`m/48'/coin'/account'/2'`, receive `/0/*`, change `/1/*`) and
+public keys are ordered per BIP 67 at every index, so any wallet built from
+the same account xpubs produces identical addresses regardless of the order
+the cosigners were listed in.
+
+Cosigners are supplied as account-level extended public keys (`xpub`/`tpub`,
+or the SLIP-132 multisig encodings `Zpub`/`Vpub`, normalized automatically).
+When a mnemonic is provided, this wallet IS one of the cosigners: its BIP 48
+account xpub is derived and included automatically (pass `ourXpub` to assert
+it explicitly; a mismatch is rejected). Omit the mnemonic for a watch-only
+multisig coordinator: the full read-only surface (scanning, balances,
+history, subscriptions) works, signing does not.
+
+Spending is PSBT-only. Direct spends (`send`/`sendMany`/`sendMax`) fail with
+the typed `MultisigSpendError` (`code: 'MULTISIG_REQUIRES_PSBT'`). `buildPsbt`
+attaches the `witnessScript` and one `bip32Derivation` entry per cosigner to
+every input; `signPsbtWithOurKey` adds this cosigner's partial signature
+without finalizing; `importSignedPsbt` counts the VALID partial signatures on
+each input against the witnessScript threshold and refuses to finalize below
+it (the error names how many signatures it has and needs).
+`exportDescriptors()` emits the checksummed `wsh(sortedmulti(...))` receive
+and change descriptors for import into Bitcoin Core/Sparrow/Specter; our key
+carries its full key origin, cosigners known only as xpubs carry a
+fingerprint-only origin. Multisig is a library-only feature for now: the
+HTTP daemon wallet stays single-sig.
+
+Full 2-of-3 walkthrough:
+
+```typescript
+import { Wallet } from 'beignet';
+
+// Each cosigner shares their BIP 48 account xpub (m/48'/0'/0'/2' on mainnet).
+// Grab ours from exportDescriptors() or derive it with any BIP 48 tool.
+
+// 1. Cosigner A creates their multisig wallet (A holds mnemonicA).
+const walletA = (
+  await Wallet.createMultisig({
+    threshold: 2,
+    mnemonic: mnemonicA, // we are one cosigner; our xpub is added automatically
+    cosigners: [xpubB, xpubC],
+    network: 'bitcoin',
+    electrumOptions: { net, tls },
+  })
+).value;
+
+// Cosigner B does the same in their own instance/machine.
+const walletB = (
+  await Wallet.createMultisig({
+    threshold: 2,
+    mnemonic: mnemonicB,
+    cosigners: [xpubA, xpubC],
+    network: 'bitcoin',
+    electrumOptions: { net, tls },
+  })
+).value;
+
+// An optional watch-only coordinator holds no keys at all.
+const coordinator = (
+  await Wallet.createMultisig({
+    threshold: 2,
+    cosigners: [xpubA, xpubB, xpubC],
+    network: 'bitcoin',
+    electrumOptions: { net, tls },
+  })
+).value;
+
+// 2. Fund the multisig: every instance derives the same addresses.
+const deposit = await walletA.getAddress(); // == walletB/coordinator address
+
+// 3. Build the unsigned PSBT (works on any instance, coordinator included).
+const built = await walletA.buildPsbt({
+  address: 'bc1q...',
+  amount: 50000,
+  satsPerByte: 4,
+});
+const unsigned = built.value.psbtBase64;
+
+// 4. Each cosigner signs their own copy (below threshold nothing finalizes).
+const signedA = walletA.signPsbtWithOurKey(unsigned).value;
+const signedB = walletB.signPsbtWithOurKey(unsigned).value;
+
+// 5. Combine the partials, finalize at threshold, broadcast.
+const combined = coordinator.combinePsbts([signedA, signedB]).value;
+const finalized = coordinator.importSignedPsbt(combined).value; // 2-of-3 met
+await coordinator.broadcastTransaction(finalized.txHex);
+
+// Importing with only one signature fails loudly:
+// 'Input 0 is below the multisig threshold: have 1 signature(s), need 2.'
+
+// Interop: import the wallet into Bitcoin Core/Sparrow/Specter.
+const descriptors = walletA.exportDescriptors().value;
+// wsh(sortedmulti(2,[fp/48h/0h/0h/2h]xpub.../0/*,[fp]xpub.../0/*,...))#checksum
+```
+
+### Networks, Fee Estimates & Electrum Failover
+
+- **Networks:** `mainnet`, `testnet`, `regtest`, and `signet` are supported end to end (on-chain wallet, Electrum, CLI/daemon via `--network signet`, and the Lightning node config, which uses the signet chain hash and `tbs` invoice prefix). Signet shares testnet's address formats and derivation paths (coin type 1); only the chain differs.
+- **Fee estimation source:** `Wallet.create({ feeEstimationSource })` accepts `'electrum' | 'http' | 'auto'` (default `'auto'`). `'electrum'` queries only the connected Electrum server via `blockchain.estimatefee`, so fee lookups never leak to mempool.space/blocktank over clearnet; `'auto'` prefers Electrum and falls back to HTTP only when Electrum is unavailable or returns unusable values. All remote-sourced rates are clamped to at most 5000 sat/vB. The daemon exposes the same option as `feeEstimationSource` / `--fee-source` / `BEIGNET_FEE_SOURCE`.
+- **Electrum failover:** when multiple `electrumOptions.servers` are provided, 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. `wallet.electrum.currentServer` and `wallet.electrum.rotationCount` expose the current server and rotation history.
+- **BIP21:** `encodeBip21({ address, amountSats?, label?, message? })` builds a `bitcoin:` payment URI; the daemon's `POST /address/new` accepts `{ bip21: true, amountSats?, label?, message? }` and the CLI supports `address --bip21 [--amount <sats>] [--label L] [--message M]`.
+
+### Storage & Encryption
+
+The wallet persists its state through the host-injected `TStorage` interface (`storage: { getData, setData }` on `Wallet.create`). Values are handed to the host as-is, so by default they are stored in plaintext. The persisted data is addresses, address 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.
+
+To encrypt at rest, wrap any `TStorage` with `createEncryptedStorage` before passing it in. Values are encrypted with AES-256-GCM under a key derived from the seed via HKDF, and pre-existing plaintext values are passed through unchanged and migrate lazily as they are rewritten:
+
+```typescript
+import { createEncryptedStorage, Wallet } from 'beignet';
+import * as bip39 from 'bip39';
+
+const seed = bip39.mnemonicToSeedSync(mnemonic);
+const wallet = await Wallet.create({
+  mnemonic,
+  storage: createEncryptedStorage({ getData, setData }, seed),
+  // ...
+});
+```
+
 ## Lightning Network
 
 ### Lightning Quick Start (BeignetNode)
@@ -212,6 +416,85 @@ const readiness = node.getMainnetReadiness();
 console.log('Score:', readiness.score + '/100', 'Ready:', readiness.ready);
 ```
 
+### Advisor Execution (circular rebalancing + fee auto-tuning)
+
+The advisor can also *act*, not just recommend. Both features are **off by
+default** and only run when explicitly enabled in the node options.
+
+```typescript
+// One-shot circular rebalance: self-payment out over fromChannelId and back
+// in over toChannelId. Aborts WITHOUT paying if the route fee > maxFeeSats.
+const result = await node.rebalanceChannel(
+  fromChannelId, toChannelId, 50_000, /* maxFeeSats: */ 50
+);
+
+// Inspect what the executor would do (read-only)
+const recs = node.getAdvisorRecommendations(); // analyze() + rebalancePlan[]
+
+// Run the advisor's rebalance plan under a per-day fee budget
+const summary = await node.executeRebalances(/* budgetSatsPerDay: */ 500);
+```
+
+Automatic modes (opt-in via `BeignetNodeOptions` / `INodeConfig`):
+
+```typescript
+const node = await BeignetNode.create({
+  mnemonic,
+  // Periodically executes the rebalance plan. Routing fees spent on
+  // rebalances are capped at budgetSatsPerDay per UTC day; the running spend
+  // is persisted, so restarts never overspend the same day. The budget
+  // resets at midnight UTC.
+  autoRebalance: { enabled: true, budgetSatsPerDay: 500, minImbalancePct: 20 },
+  // Every intervalMs (default 6h) nudges each channel's proportional fee:
+  // +25% when outbound is depleted (<20% local) but still forwarding,
+  // -25% when the channel saw no forwards in the window, clamped to
+  // [floorPpm, ceilPpm]. One adjustment per channel per interval.
+  autoTuneFees: { enabled: true, floorPpm: 1, ceilPpm: 5_000 }
+});
+```
+
+Daemon/CLI surfaces: `POST /rebalance`, `GET /advisor/recommendations`,
+`POST /advisor/execute-rebalances`; `beignet rebalance <from> <to> <sats>
+--max-fee <sats>`, `beignet advisor recommendations`, `beignet advisor
+execute-rebalances [--budget <sats>]`.
+
+### Watchtowers
+
+Penalty enforcement normally requires this node's own chain monitor to be online:
+if a counterparty broadcasts a revoked commitment while you are offline, nobody
+sweeps the breach. The **watchtower client** closes that gap. At every revocation
+it builds an encrypted *justice kit* (the revoked commitment's breach hint plus a
+pre-signed to_local penalty) and ships it to one or more remote towers over the
+standard BOLT 8 Noise transport. When a tower later sees the breach transaction on
+chain, it decrypts the kit and broadcasts the penalty on your behalf — reclaiming
+the channel even though you never came back online.
+
+- **Altruist only.** Sessions use `reward = 0`; towers take no cut. There is no
+  server mode (beignet is a tower *client*, not a tower).
+- **LND-tower compatible.** Implements LND's `wtwire` protocol (Init/CreateSession/
+  StateUpdate/DeleteSession, message types 600-607) and the version-0 justice blob
+  (XChaCha20-Poly1305, breach hint = `SHA256(txid)[:16]`, key = `SHA256(txid‖txid)`),
+  so it interoperates with existing public LND altruist towers.
+- **Legacy + anchor channels.** The to_local revocation penalty (the fund-critical
+  breach punishment) is packed for both; taproot channels are not yet backed up.
+- **Durable.** Per-tower session state and the un-acked update backlog are persisted
+  (encrypted at rest) and drained with exponential backoff on reconnect. An un-acked
+  update is never dropped silently.
+
+Configure towers as `pubkey@host:port` URIs (off when empty):
+
+```ts
+const node = await BeignetNode.create({
+  mnemonic,
+  watchtowers: ['03abc...@tower.example.com:9911']
+});
+```
+
+Daemon/CLI surfaces: `GET /watchtowers`, `POST /watchtower/add`,
+`DELETE /watchtower/remove`; `beignet watchtower list`, `beignet watchtower add
+<pubkey@host:port>`, `beignet watchtower remove <uri>`; daemon flag `--watchtower`
+(repeatable) or `BEIGNET_WATCHTOWERS` (comma-separated).
+
 ### HTTP Daemon
 
 BeignetNode can also run as an HTTP/SSE daemon for language-agnostic integrations:
@@ -512,7 +795,7 @@ Beignet is under active development. The following features are missing or carry
 
 | Feature | Status | Impact |
 |---------|--------|--------|
-| **Watchtowers** | Not implemented | If your node goes offline, a counterparty could theoretically broadcast a revoked state. Mitigate with frequent backups and auto-reconnect. |
+| **Watchtowers** | Client implemented (altruist) | Ships encrypted justice data to remote LND altruist towers at every revocation so a breach is punished while you are offline (see [Watchtowers](#watchtowers)). Legacy + anchor channels only; taproot channels are not yet backed up, and server mode is out of scope. |
 | **LSP / LSPS protocols** | Not implemented | No automated inbound liquidity acquisition via LSPS0/1/2. Liquidity ads (bLIP-51) are supported for negotiated leases; otherwise open channels manually. |
 | **Trampoline routing** | Not implemented | All route computation is local. Cannot delegate pathfinding to a trampoline node. |
 | **BOLT 12 offers** | Newer | Offer creation/decoding, invoice_request/invoice over onion messages, and receive-side settlement are implemented, but the surface is newer and less battle-tested than BOLT 11. Prefer BOLT 11 invoices for production. |