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.