Persist payment-received ack across reloads; footer + README

- The "Payment received!" celebration now persists: the acknowledged fresh
  index is stored (per seed) in localStorage, so a received payment keeps
  showing the dialog until you tap past it, even after a refresh.
- Footer: only "GitHub" is the link now.
- README rewritten for the current state (mainnet-only, realtime, Nostr sync,
  multi-recipient, sats default, explorer resilience, etc.).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

1 files changed, 70 insertions, 39 deletions

diff --git a/README.md b/README.md
index 96a35dd..e848fa2 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,43 @@
 # Bitcoin Wallet
 
 A self-contained, **single-file** Bitcoin wallet that runs entirely in the
-browser. Think bitaddress.org, but a modern BIP84 HD wallet built from a seed
-phrase, able to scan history, fetch UTXOs, and spend — online or fully offline.
+browser — think bitaddress.org, but a modern BIP84 HD wallet from a seed
+phrase that scans history, watches for payments in real time, and spends.
+
+Live at **https://bitcoin.coinos.io** (and the built `index.html` runs offline
+straight from the filesystem).
+
+## Features
 
 - **BIP84 / native SegWit (p2wpkh)** HD wallet from a 12/24-word BIP39 seed
-  (optional passphrase).
-- **HD scanning** with the standard gap limit across the receive (`…/0/i`) and
-  change (`…/1/i`) chains — real aggregate balance, fresh addresses, and
-  transaction history via [mempool.space](https://mempool.space).
-- **Spending** with proper coin selection + fee estimation
-  (`@scure/btc-signer`'s `selectUTXO`), a fee-rate picker, send-max, and
-  **manual coin control**.
-- **Fresh addresses** for receiving and for change — no address reuse.
-- **Offline mode**: import UTXOs from a JSON snapshot (fetched on an online
-  device), sign locally, and export the signed transaction (hex / file / QR) to
-  broadcast elsewhere. No network calls are made.
-- **Runs offline from `file://`** — keys never leave the page; nothing is sent
-  anywhere except, when online, read-only requests + a broadcast to
-  mempool.space.
+  (optional passphrase). Mainnet.
+- **One fresh address at a time** — a new receive address is only handed out
+  after the current one is paid, so used addresses stay contiguous and scans
+  stay tiny (no 20-address gap probing).
+- **Real-time** via the mempool.space WebSocket: an incoming payment shows a
+  "Payment received!" screen the moment it hits the mempool, then reveals the
+  next address. A ping/pong heartbeat keeps the socket alive (auto-reconnect on
+  drop, sleep, or network change).
+- **Spending** with proper coin selection + fee estimation (`@scure/btc-signer`
+  `selectUTXO`), multiple recipients, a fee-rate picker, send-max, and manual
+  coin control.
+- **Encrypted cross-device sync over Nostr** — wallet state is NIP-44-encrypted
+  to yourself and stored as a replaceable event (kind 30078) on
+  relay.coinos.io. The Nostr identity is derived from the same seed (NIP-06),
+  so opening the wallet on another device restores state with no rescan.
+- **Offline signing** — export a keyless JSON snapshot of your coins on an
+  online device, import it on an offline one, sign locally, and export the
+  signed transaction (hex / file / QR) to broadcast elsewhere.
+- **Global sats/BTC toggle** (defaults to sats) — every amount label is
+  clickable to switch, persisted across sessions.
+- **Resilient explorer access** — mempool.space + Blockstream with a global
+  request throttle, per-host cooldown on 429s, request timeouts with failover,
+  and a localStorage cache so reloads are instant.
 
-Built with the modern audited [`@scure`](https://github.com/paulmillr/scure-btc-signer)
-/ [`@noble`](https://github.com/paulmillr/noble-hashes) libraries. Pure JS: no
-`crypto.subtle`, so it works from the filesystem with no server.
+Built with the audited [`@scure`](https://github.com/paulmillr/scure-btc-signer)
+/ [`@noble`](https://github.com/paulmillr/noble-hashes) libraries plus
+[`nostr-tools`](https://github.com/nbd-wtf/nostr-tools). Pure JS, no
+`crypto.subtle`, so it works from `file://` with no server.
 
 ## Develop
 
@@ -39,28 +54,42 @@ bun run dev      # http://localhost:5173 (rebuilds on each refresh)
 bun run build    # → dist/index.html  (one self-contained file)
 ```
 
-`dist/index.html` inlines all code, the crypto libraries, the QR generator, and
-the CSS. **To use it offline: save that one file and open it directly in a
-browser** — no server, no internet.
+`dist/index.html` inlines all code, the crypto/QR/Nostr libraries, and the CSS.
+Save that one file and open it directly in a browser — no server, no internet
+needed (network features simply stay idle until you're online).
+
+## How state is kept
+
+Three layers, fastest first:
+
+1. **sessionStorage** — keeps the wallet open across a refresh (cleared on
+   logout / tab close).
+2. **localStorage** — caches scanned state (addresses, UTXOs, history) keyed by
+   a hash of the seed, so a reload shows balances instantly.
+3. **Nostr** — encrypted, replaceable cross-device state on relay.coinos.io.
+
+Idle polling only ever re-checks the fresh receive/change address; already-
+scanned coin addresses are never re-polled (spends come over the WebSocket /
+post-send refresh / Nostr). A manual **Settings → Rescan** covers anything
+missed (e.g. a payment to a reused old address).
 
-## Using it offline (air-gapped spending)
+## Offline / air-gapped spending
 
-1. **Online device** (with internet): open the wallet, let it scan, then go to
-   **Tools → Export snapshot**. This downloads a JSON file of your UTXOs and fee
-   rates. It contains **no keys**.
-2. Move the file to your **offline device** (e.g. an air-gapped laptop running
-   the saved `index.html`).
-3. On the offline device, open the wallet, enter your **seed phrase** with
-   *Offline mode* checked, then **Tools → Import snapshot**.
-4. Build and **sign** a transaction. Copy/download the signed hex (or scan the
-   QR) and broadcast it from any online device (e.g. mempool.space → Broadcast).
+1. **Online device:** open the wallet, let it scan, then **Settings → Export
+   snapshot** (a keyless JSON of your UTXOs + fee rates).
+2. Move the file to an **offline device** running the saved `index.html`.
+3. There, enter your **seed phrase** (it auto-detects no network), then
+   **Settings → Import snapshot**.
+4. Build and **sign** a transaction; copy/download the signed hex (or scan the
+   QR) and broadcast it from any online device.
 
 ## Layout
 
 | File | Purpose |
 | --- | --- |
-| `src/wallet.js` | BIP84 derivation, scanning, coin selection, signing, snapshots |
-| `src/api.js` | Esplora REST wrapper (mempool.space + Blockstream, with throttle/rotation/cooldown to dodge rate limits); the single network choke-point |
+| `src/wallet.js` | BIP84 derivation, scanning, coin selection, signing, realtime, cache, sync |
+| `src/api.js` | Esplora wrapper (mempool.space + Blockstream) with throttle/cooldown/timeout |
+| `src/nostr.js` | Encrypted cross-device state sync over Nostr |
 | `src/app.js` | UI controller (vanilla DOM) |
 | `src/qr.js` | QR → SVG (zero-dep) |
 | `src/format.js` | sat/BTC formatting helpers |
@@ -69,8 +98,10 @@ browser** — no server, no internet.
 
 ## Security notes
 
-- This is self-custody software handling real keys — review the code before
-  trusting it with funds, and prefer an offline machine for the seed phrase.
-- Mainnet and testnet are both supported (select on the unlock screen).
-- The seed phrase and passphrase live only in memory while the page is open;
-  locking or closing the tab clears them.
+- Self-custody software handling real keys — review the code before trusting it
+  with funds, and prefer an offline machine for the seed phrase.
+- The seed/passphrase live in memory while the page is open and in
+  sessionStorage for the tab session; locking or closing the tab clears them.
+- The localStorage cache and the Nostr event hold public chain data (addresses,
+  UTXOs, amounts); the Nostr copy is encrypted and keyed to your seed-derived
+  identity, but the relay can see that an identity is publishing app data.