1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
# Bitcoin Wallet
A self-contained, **single-file** Bitcoin wallet that runs entirely in the
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). 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 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
Requires [Bun](https://bun.sh).
```bash
bun install
bun run dev # http://localhost:5173 (rebuilds on each refresh)
```
## Build
```bash
bun run build # → dist/index.html (one self-contained file)
```
`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).
## Offline / air-gapped spending
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, 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 |
| `src/style.css` | Hand-rolled styles |
| `build.js` / `dev.js` | Bun bundler → single inlined `index.html`, and dev server |
## Security notes
- 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.
|
