Cryptohack

A semi-secure, hacker-friendly hardware crypto wallet on the hip-badge ESP32-C3 platform with the onboard ATECC608B secure element. Signs transactions for BTC, ETH (+ 8 EVM chains), SOL, and XMR with an on-device SIGN screen the user has to approve before any private key touches the message.

firmware/badge/      runtime wallet
firmware/factory/    one-shot provisioning firmware + host driver
ref/                 gitignored — clone upstream schematics here

Quick start

⚠ Flash the factory firmware FIRST on a fresh badge. The runtime wallet expects the ATECC608B to be provisioned (slot keys loaded, config-zone configured) and won't unlock its PIN-wrapped seed without that. Order is: build factory → flash factory → run host driver (factory_provision.py) → build runtime → flash runtime. Skip the factory step and you'll get an SE-init failure and a stalled boot at the splash. See docs/TOOLS.md § Factory provisioning for the host driver walkthrough.

# Activate ESP-IDF in this shell (see firmware/BUILDING.md for install)
. ~/esp/esp-idf/export.sh           # or export.ps1 on Windows

# 1. Factory provision (one-time per badge)
cd firmware/factory
idf.py -B build -p $PORT build flash monitor
# (in another shell) cd firmware/factory/tools && \
#   uv run --with pyserial --with cbor2 factory_provision.py --port $PORT

# 2. Build + flash the runtime (do this AFTER factory)
cd ../badge
export SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.dev"
idf.py -B build_dev -p $PORT build flash monitor

Full walk-through (Linux / macOS / Windows): firmware/BUILDING.md.

To provision a fresh badge or reproduce the test suite: docs/TOOLS.md.

Documentation map

Read this	If you want to…
firmware/BUILDING.md	Install ESP-IDF and flash the device for the first time
docs/ARCHITECTURE.md	Understand how the wallet works — components, trust zones, signing flow
docs/TOOLS.md	Run the factory provisioning host driver or the per-coin sign tests
docs/VERIFY.md	Run the verification sweep before / after substantial changes
docs/PLAN.md	Read the exhaustive security spec — KEK ceremony, slot maps, recovery flows
docs/CODE_STYLE.md	Submit a PR that fits the project conventions
CONTRIBUTING.md	Open a PR (branching, commits, review expectations)
TODO.md	Find something to work on or check what's already shipped
CLAUDE.md	Brief an AI assistant (Claude, Cursor, etc.) on the project

Three operating modes

Flavor	eFuse	Use	Reflashable?
dev	virtual (flash)	daily iteration	yes, always
stage	real, unlocked	end-to-end silicon test	yes, until you lock
prod	real, locked	shipped device, Secure Boot V2	no

License

Mixed:

• firmware/badge/components/trezor-crypto/ — MIT (vendored from Trezor)
• firmware/badge/components/tinycbor/ — MIT (Intel)
• firmware/badge/components/qrcodegen/ — MIT (Project Nayuki)
• firmware/badge/main/ (extending hip-badge blinkenlights/) — GPL-2.0-or-later
• Everything else original to this repo — pick one when ready.