Build your seed, block by block.
Open-source experimental firmware for the standard LILYGO T-Display-S3. A falling-block game mixes physical button timing and gameplay decisions with the ESP32-S3 hardware random-number generator, then produces a valid 12- or 24-word BIP-39 mnemonic using the official English word list.
Experimental software
This project is intended for experimentation and open review of an entropy-generation method on embedded hardware. It is not an audited security product and is not ready to protect real funds.
The design has automated tests and encouraging pilot data, but it has not received an independent cryptographic and security audit.
Do not use any seed phrase generated by this project to protect real funds until an independent audit has been completed, its results published, and relevant findings resolved. Until then, use test wallets and test funds only. An audit does not eliminate every risk: review its scope, findings, and limitations before relying on the system.
You are responsible for deciding whether this software is appropriate for your use, verifying the source code, firmware, and hardware, and protecting any generated seed phrase.
Physical dice remain a transparent and valuable way to generate entropy. The Entropy Game does not replace them or diminish their value. It offers a less tedious alternative: instead of recording a long series of dice rolls, the user plays a video game.
The game also avoids relying on human input alone. Its cryptographic foundation is the ESP32-S3 hardware RNG, enabled according to Espressif's documented requirements. Human timing, button transitions, logical actions, piece context, and board snapshots are absorbed incrementally as a second source. SHA-256 conditions the combined input; it does not create missing entropy.
- Choose English or Spanish for the complete interface. BIP-39 words always remain in English for wallet compatibility.
- Choose 12 words (128 placed pieces) or 24 words (256 placed pieces).
- Play one continuous game. Reaching the top invalidates the attempt, explicitly clears its volatile state, and requires a new game.
- The firmware mixes initial hardware RNG, interaction records, a fresh hardware-RNG sample after every placed piece, and a final hardware-RNG sample.
- The final 256-bit digest is converted to a checksum-valid BIP-39 mnemonic.
- After the user verifies the words, both buttons clear the sensitive state and restart the device.
Completing the game demonstrates sustained human participation and physical time spent. The 128/256-piece targets numerically match the BIP-39 entropy lengths only as a gameplay convention: the progress bar counts pieces, not entropy bits, and completion is not a mathematical certification of one bit per piece. The human contribution is defense in depth; the hardware RNG remains the primary cryptographic source.
- Standard LILYGO T-Display-S3 only: ESP32-S3, 170×320 ST7789 display, 16 MB flash, 8 MB PSRAM.
- Menus and seed display use landscape orientation; gameplay uses portrait orientation.
- GPIO0 and GPIO14 are active-low physical buttons.
| Gesture | Game action |
|---|---|
| Tap one button | Move toward that side |
| Tap both buttons | Rotate |
| Hold either button | Hard drop |
Do not hold the GPIO0 button while powering on unless you intend to enter the ROM bootloader. See HARDWARE.md.
The web installer is designed for desktop Chrome or Edge:
https://vibe-coder-git.github.io/the-entropy-game/
It packages production firmware only, verifies SHA-256 before flashing, reads the written image back, and verifies it again. It has no telemetry, game-data capture, or serial console. See docs/WEB_INSTALLER.md.
For a sensitive session, disconnect the board from the computer after installation and power it from a battery or trusted wall charger.
Before relying on a generated phrase, validate it offline with an independent BIP-39 implementation and test the complete recovery procedure using a test wallet with no real funds.
The supported toolchain is ESP-IDF 5.5.5.
source /path/to/esp-idf-v5.5.5/export.sh
python -m pip install -r requirements-release.txt
make test audit
RELEASE=1 ./scripts/build_firmware.sh production build-production distThe release process, pinned Docker environment, manifests, and binary comparison procedure are documented in REPRODUCIBLE.md.
Production firmware has no Wi-Fi, Bluetooth, filesystem, NVS, telemetry, analytics, or application console. Seed material exists only in volatile memory and is explicitly cleared on completion, timeout, loss, or restart. Never photograph, copy to a connected device, or share a seed phrase.
Read the security model, architecture, testing procedure, and research notes. Security-sensitive findings must use the private reporting process in SECURITY.md.
The project includes adapted earlier work and the official BIP-39 English list. Attribution and licensing details are in PROVENANCE.md and third_party/README.md.
The Entropy Game is an independent project. It is not affiliated with or endorsed by Bitcoin, Espressif Systems, or LILYGO. Product names are used only to identify protocols and compatible hardware.
The project is released under the MIT License.