An air-gapped wallet for Bitcoin SV¶
Built on a Raspberry Pi Zero 2 WH, a 1.3" TFT bonnet, and a Pi Camera Module 3. Your seed phrase never touches a network. The companion PWA in your phone or laptop talks to the chain; the Pi just signs.
Alpha software
PiWalletSV is in active development. There is no warranty and no custodial backup. Read the Disclaimer and Security briefing before storing real funds on a device you built from this code.
How it works¶
The system is intentionally split into two pieces that never share a trust boundary:
flowchart LR
subgraph air["Air-gapped signer (Pi)"]
seed["BIP39 seed<br/>encrypted vault"]
verify["verify_proposal<br/>(BEEF + Merkle + anchors)"]
sign["sign_transaction"]
seed --> verify --> sign
end
subgraph online["Online companion (PWA)"]
woc["WhatsOnChain<br/>or other backend"]
select["UTXO + coin selection"]
proposal["unsigned_proposal<br/>builder"]
broadcast["broadcast"]
woc --> select --> proposal
broadcast --> woc
end
proposal -- "QR (PW1 multipart)" --> verify
sign -- "QR (PW1 multipart)" --> broadcastThe Pi has no Wi-Fi, no Bluetooth, no Ethernet — nothing reaches the network from the device that holds the keys. The companion runs in your existing browser at the companion and ferries transactions to the Pi over animated QR codes. Every input the companion proposes is cryptographically re-verified on the Pi (BEEF proofs anchored to user-displayed block headers) before the device signs anything.
Three reasons it's different¶
-
Public key only on the network
The companion sees only your public xpub and pre-signed transactions. The seed phrase, the encrypted vault, and every signing key live exclusively on the Pi.
-
Open spec, not a black box
The wire format, QR transport, derivation rules, and SPV requirements are documented as an open protocol spec. Anyone can build a compatible signer or companion.
-
Off-the-shelf parts
Raspberry Pi Zero 2 WH, Adafruit 1.3" TFT bonnet, Pi Camera Module 3. No proprietary hardware, no soldering, no signed firmware to trust.
Want to use it?¶
-
Bring up the bonnet, install the signer, run the companion in a browser. Start here if you've just got the hardware.
-
Open the PWA. Pair a wallet, scan an unsigned proposal, broadcast a signed transaction. Works on any phone, tablet, or laptop with a camera and a modern browser.
-
Pairing, receiving, sending, broadcasting, restoring — the same journey a normal user takes.
-
Plain-language operator-facing trust model: what's on the network, what isn't, and why the PIN-encrypted vault is not magic.
Want to understand it?¶
-
The two-host design, the trust boundary, the data flow, and why everything that crosses the air gap is gzipped CBOR over animated QR.
-
Take a blank Pi from a freshly-flashed SD card to an autostarting bonnet kiosk under systemd, with bounded journald logs.
-
Day-to-day ops: logs, exit codes, vault stewardship, factory reset, updates, and troubleshooting the deployment itself.
-
Every
piwalletsubcommand with options, exit codes, and pipe-friendly examples. -
Repo layout, dev setup, testing matrix, fixture regeneration, release checklist.
-
The wire formats, QR transport, derivation rules, and SPV requirements that any compatible companion (or signer) must follow.
-
How PiWalletSV's design choices compare to existing air-gapped BSV setups, and what that comparison tells us about future scope.
-
What of BRC-100 / BRC-95 / BRC-74 PiWalletSV implements, and what it deliberately doesn't.
Project status¶
| Phase | Scope | Status |
|---|---|---|
| 1 | Offline core (mnemonic, derivation, envelope, vault, verify, sign, CLI) | done |
| 2 | Pi-side bonnet UX (display, joystick word entry, first-boot disclaimer) | in progress |
| 3 | Python + TypeScript PW1 multipart transport | done |
| 4 | Companion PWA (pairing, receive, UTXO scan, proposal, broadcast, terms) | done |
| 7 | Documentation site + protocol spec + v0.1 release | this site |
| 8 | Enclosure, tamper-evidence, first-boot hardening, signed SD image | planned |