English | 日本語
- Status: experimental / work in progress. Specifications, APIs and file layout change without notice.
- No third-party security audit. An internal source review is available in docs/10-security-audit-2026-10-13.md, but critical architecture work remains: there is no target-device main loop or physical approval gate, camera/QR code is not wired to hardware, and the firmware has not run on the target board.
- Do not store real funds. You may lose them.
- Heavy use of LLMs (large language models) in development. Most of the design, code, tests and documentation was generated by LLMs and reviewed by a human. Generated code can contain mistakes.
Read DISCLAIMER.md before anything else.
An attempt at a fully open-source, multi-chain hardware wallet that anyone can assemble from commodity parts — no soldering.
- Initial scope: Bitcoin + EVM (Ethereum / ERC-20 / major L2s)
- Hardware: Waveshare RP2350-PiZero (no wireless) + Adafruit Mini PiTFT + ArduCam UC-805 (HM01B0) camera, in a clear 3D-printed case — off-the-shelf parts, no soldering
- Target cost: roughly ¥8,000–11,000 (USD 55–75) per unit
- Status: protocol primitives and host tools are tested, including a separate approved native-P2WPKH workflow with an independent BIP143 guard. Physical approval, target HAL/TrustZone and end-to-end device firmware are not implemented, and the firmware has not yet run on the target hardware
Existing open-source hardware wallets fall into three groups.
| Category | Examples | Problem |
|---|---|---|
| Fully open, but Bitcoin-only | SeedSigner, Krux, Specter DIY | Cannot be used multi-chain |
| Multi-chain, but hardware/firmware closed | Ledger and others | Not "fully open source" |
| Multi-chain with open firmware | Trezor, BitBox02, Keystone | Hardware design closed, or not self-buildable |
This project aims at the intersection: buildable by anyone from commodity parts × multi-chain × fully open source. The hardware follows SeedSigner's shape — a camera on the back, a screen and buttons on the front, no radio, no battery — on a microcontroller board with secure-boot features; the software is written from scratch to support BTC + EVM.
- Keys know nothing about chains — key management, randomness and signing primitives live in
core; chain-specific logic lives inapps. Adding a chain means adding an app, and does not require re-auditing the core. - Sign only what is displayed (clear signing) — per-chain transaction parsing and human-readable display are mandatory; blind signing is not allowed. BTC uses PSBT, EVM uses ERC-7730 descriptors.
- Secrets die with the power (stateless) — the seed exists only in RAM and is never written to flash. Power off, and it is gone.
"Fully open source" and "chain signing inside an SE" are not simultaneously achievable with today's parts.
| SE | Curves | Conclusion |
|---|---|---|
| ATECC608A/B | NIST P-256 only | Cannot sign secp256k1 (used for key storage/attestation in BTC/ETH designs) |
| OPTIGA Trust M V3 | NIST/Brainpool | Used by Trezor Safe 3/5, but the seed does not live in the SE; signing happens on the MCU |
| Java Card based | Some support secp256k1 | Leads to a design without a display, badly degrading UX |
| TROPIC01 | Auditable SE | Used by Trezor Safe 7; currently almost impossible to buy as an individual |
This project therefore chooses no SE and a stateless design, and documents the residual risk of physical attacks in docs/05-threat-model.md. Physical-attack resistance is compensated by multisig, passphrases, keeping balances small, and powering the device off after use.
zhww/
├── README.md ← this file (English)
├── README.ja.md ← Japanese version
├── DISCLAIMER.md ← disclaimer, development process, LLM disclosure (read this)
├── SECURITY.md ← how to report vulnerabilities
├── LICENSE ← MIT (firmware and tools)
├── LICENSES/ ← every licence text used here (MIT, CERN-OHL-S-2.0, CC-BY-4.0, BSD-2-Clause)
├── REUSE.toml ← licences of the files that cannot carry an SPDX header
├── LICENSE-POLICY.md ← which licence applies where, and why
├── TRADEMARKS.md ← how the name "zhww" may be used
├── THIRD-PARTY-NOTICES.md ← third-party software and test vector sources
├── docs/ ← design documents
│ ├── 01-requirements.md ← requirements, scope, acceptance criteria
│ ├── 02-architecture.md ← architecture, key derivation, signing flow
│ ├── 03-hardware-bom.md ← BOM, sourcing, assembly, enclosure
│ ├── 04-chain-support.md ← BTC/EVM implementation matrix
│ ├── 05-threat-model.md ← threat model and residual risks
│ ├── 06-roadmap.md ← milestones and definitions of done
│ ├── 08-rp2350-pizero.md ← the RP2350-PiZero port: pins, power, flash, HAL plan
│ ├── 10-security-audit-2026-10-13.md ← internal source review, fixes, and release blockers
│ ├── 11-rp2350-security.md ← RP2350 security architecture (TrustZone, boot, OTP)
│ ├── 12-rp2350-memory-budget.md ← SRAM inventory and bounded workspace
│ ├── 13-independent-p2wpkh-guard.md ← independent check of the P2WPKH signing plan
│ ├── 14-target-link-and-fault-prototype.md ← offline Cortex-M33 links, stack frames, fatal wipe
│ ├── 15-security-audit-2026-10-14.md ← follow-up internal review
│ └── next-session.md ← handoff: current state, next steps, landmines
├── firmware/ ← Zig implementation
│ ├── build.zig
│ ├── src/core/ ← chain-agnostic primitives
│ ├── src/apps/ ← BTC and EVM applications
│ ├── src/security/ ← Secure-world prototypes (approval, sessions, guard, SRAM budget)
│ ├── src/ui/ ← screen, LCD driver, QR encoder and decoder, status indicator
│ ├── src/transport/ ← BC-UR (QR transport)
│ ├── src/cli/ ← development CLI (host side)
│ └── tests/ ← official test vectors and integration tests
├── tools/ ← offline checks (licences, target link, memory layout)
└── hardware/enclosure/ ← parametric SolidCraft enclosure (scripts, STEP / STL exports)
| Item | State |
|---|---|
| Design documents | Working drafts present (requirements, architecture, BOM, chain support, threat model, roadmap and the RP2350 port plan); security/memory/guard design and release blockers remain under review |
| Firmware (Zig + libsecp256k1) | Bitcoin: BIP39 (incl. dice entropy), BIP32, address generation, transaction/PSBT parsing, legacy and BIP143 signing/finalization, fee/change analysis, BC-UR, screen rendering, and QR encode/decode. Taproot and 2-of-3 P2WSH are standalone signing modules with interoperability tests; they are not integrated into signPsbtBytes. EVM: RLP, EIP-55, EIP-155/EIP-1559 signing, EIP-191 hashing, EIP-712, ABI decoding, and ERC-7730 rendering exist as separate modules; they are not connected by an on-device approval flow. |
| Security prototypes | Host approved native-P2WPKH/SIGHASH_ALL flow, owned secret/context erasure, mandatory bounded entropy, fixed-workspace tests and independent wire/BIP143 message comparison. No actual TrustZone/HAL or physical approval. See security, memory and guard scope. |
| Tests | 353 passing in four optimization modes (normal host library and selected target C arithmetic configuration), including the previous crypto/interoperability vectors plus approval, wipe, RNG/workspace failure, independent guard and mutation checks. Tests are not a target execution or security proof; see firmware details and the historical review report. |
| CI | GitHub Actions runs Linux host regressions, bare-metal Pico compile checks, Cortex-M33 memory inventory and tool/dependency checks. This is not RP2350 hardware execution. |
| Hardware | Parts decided (2026-10-14): Waveshare RP2350-PiZero + Adafruit Mini PiTFT #4393 + ArduCam UC-805 (HM01B0) camera, USB power only (BOM and wiring). Enclosure: a clear 97.2 × 38.6 × 19.7 mm case, generated from Zig and built in SolidCraft, every clearance checked (hardware/enclosure). Nothing has been bought or measured yet |
| Target link prototype | Actual offline Secure/NS links with pinned C crypto and static frames, retained large storage and separate-stack fatal wipe prototype. No boot/startup, real attribution or NS gateway (scope). |
| Next | Actual boot/SDK/CMSE gateway and attribution, transitive Zig/C/IRQ stack bounds, physical display/buttons, camera capture and TRNG HAL; then guarded P2TR/P2WSH/EVM integration and real-hardware tests. |
cd firmware && zig build test # 353 tests
zig build pico # compile checks, not hardware execution
zig build memory # provisional Cortex-M33 inventory, not a full fit proofThe development CLI can sign PSBTs, preview screen components, and decode the camera's QR codes from image files. These commands do not implement a physical approval gate and must not be treated as the final device flow:
cd firmware && zig build
./zig-out/bin/zhww help
# sign a PSBT from stdin, show what would be signed, render device screens,
# decode QR codes from grayscale images (as the camera would), and moreEverything in this project is written in English — user-facing text, documentation, code comments, test descriptions, commit messages and issue replies — so that anyone in the world can use it, review it and contribute to it.
The device UI is English only (the 240×135 screen shows plain ASCII), and the firmware has no
Japanese font embedded. Translations of the documentation into other languages are welcome as
additional files (for example README.ja.md), but English stays the source of truth.
The recommended reading order:
- Requirements — what is built, and what is not
- Hardware BOM — what to buy
- Enclosure — the case, the wiring and the assembly
- Architecture — how it fits together
- Chain support — the specs implemented for BTC/EVM
- Threat model — what is protected, and what is not
- Roadmap — the order of work
- Internal security review — fixed findings and remaining release blockers
- Firmware and tools: MIT (LICENSE)
- Hardware design, the enclosure included: CERN-OHL-S-2.0 (LICENSES/CERN-OHL-S-2.0.txt)
- Documentation: CC-BY-4.0 (LICENSES/CC-BY-4.0.txt)
- The name "zhww": forks are welcome under their own name (TRADEMARKS.md)
Every file states its licence, with an SPDX header or in REUSE.toml, and CI checks it
(git ls-files -z | zig run tools/license_check.zig). Until 2026-10-14 the firmware was GPL-3.0-or-later
and the enclosure CC-BY-SA-4.0. Third-party software and test data are
credited in THIRD-PARTY-NOTICES.md; the policy is in
LICENSE-POLICY.md.
This project is developed with heavy LLM assistance.
| Role | Owner |
|---|---|
| Design decisions, requirements, acceptance | Human |
| Design documents, code, tests, documentation | LLM (coding agents) |
| Verification (running tests, cross-checking against official vectors) | Automated tests + human review |
Most of the Zig implementation (firmware/src/), the test suites (firmware/tests/) and the
design documents in docs/ were generated by LLMs. A human reviews them, but generated code
can contain mistakes. Testing and review have found numerous bugs in LLM-generated code, including memory-lifetime,
display/signing-consistency, parser, arithmetic and filesystem-boundary issues. The 2026-10-13
findings and remaining release blockers are recorded in
docs/10-security-audit-2026-10-13.md. One earlier finding
also showed that a reference implementation used as an oracle was wrong, not this code.
Because of this, passing tests is not treated as proof of safety here. Unverified areas are stated as unverified. Pull requests, corrections and reviews are very welcome.
This is an experimental research project and has not been audited. Do not store real funds. You may lose assets at any stage: design, implementation or operation. Verify the whole flow on test networks first (Bitcoin Signet / Ethereum Sepolia).
See DISCLAIMER.md for the full text.