From c5443946031ec32a7b3008fa751eb7916654a9f6 Mon Sep 17 00:00:00 2001 From: Adam Soltys Date: Sun, 14 Jun 2026 23:01:03 -0700 Subject: Rebuild as single-file offline BIP84 wallet Replace the SvelteKit/daisyUI prototype with a vanilla JS + hand-rolled CSS app that Bun bundles (code + scure/noble crypto + QR + CSS) into one self-contained dist/index.html runnable offline from file://. Wallet core (src/wallet.js): - BIP84 native-segwit HD wallet from BIP39 seed (+optional passphrase) - gap-limit scan of receive/change chains, aggregate balance, tx history - fresh receive/change addresses; signs with witnessUtxo only (enables offline signing with no prev-tx fetch) - coin selection + fee estimation via btc-signer selectUTXO; send-max; manual coin control - offline JSON snapshot export/import (keyless) + signed-tx hex/QR export - realtime mempool.space WebSocket: track-addresses -> debounced auto refresh of balances/history (no polling); live status badge UI (src/app.js): clean light paper-wallet; create (with optional, skippable backup verification) / import flow; receive (QR) / send / history / coins / tools tabs; clickable logo returns home. API (src/api.js): mempool.space wrapper with retry/backoff for scan-burst rate limiting; single network choke-point for offline enforcement. Verified: BIP84 spec vectors, build/sign/parse for auto/max/manual flows, snapshot roundtrip, live scan + WebSocket, headless-Chrome UI smoke tests. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 61 insertions(+), 23 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b5b2950..3821f32 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,76 @@ -# sv +# Bitcoin Wallet -Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli). +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. -## Creating a project +- **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. -If you're seeing this, you've probably already done this step. Congrats! +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. -```bash -# create a new project in the current directory -npx sv create +## Develop -# create a new project in my-app -npx sv create my-app -``` +Requires [Bun](https://bun.sh). -## Developing +```bash +bun install +bun run dev # http://localhost:5173 (rebuilds on each refresh) +``` -Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server: +## Build ```bash -npm run dev - -# or start the server and open the app in a new browser tab -npm run dev -- --open +bun run build # → dist/index.html (one self-contained file) ``` -## Building +`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. -To create a production version of your app: +## Using it offline (air-gapped spending) -```bash -npm run build -``` +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). + +## Layout + +| File | Purpose | +| --- | --- | +| `src/wallet.js` | BIP84 derivation, scanning, coin selection, signing, snapshots | +| `src/api.js` | mempool.space REST wrapper (the single network choke-point) | +| `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 | -You can preview the production build with `npm run preview`. +## Security notes -> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment. +- 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. -- cgit v1.2.3