Dice Entropy

Turns physical entropy into a BIP-39 mnemonic:

• Dice — d6 rolls (1–6)
• Coins — fair coin flips (0/1, Heads=0, Tails=1)

Two uses:

1. Generate — flip/roll, type the digits, get words
2. Cross-check — enter the same sequence again and confirm you get the same words

Core conversion is Python stdlib only (hashlib). Pillow is optional, for the small UI.

Why this exists

I don’t feel great typing real dice rolls into Ian Coleman’s BIP39 tool on a normal computer. Even offline, that machine usually isn’t a true airgap — browsers, disks, and leftover software are a lot of surface area. You can boot something like Tails for this, but you still need a full PC, which is bulkier and more expensive than I wanted for “roll dice → get words.”

A Pi Zero with no network is cheap, and I already had one sitting around with a Waveshare LCD. No camera, no enclosure, and I wasn’t trying to build a full signer — just seed generation / verification with as few external dependencies as possible. SeedSigner is great if you want the whole stack; this is the thin slice I actually needed.

Security warning

• Do not enter rolls/flips for a seed you plan to fund on an internet-connected computer.
• Start with the published test vectors below.
• For a funded seed on Pi + Waveshare, run Dice Entropy OS (or other air‑gapped gear) — not Raspberry Pi OS / a normal desktop.
• Physical dice / a fair coin only. Do not invent digits or mash the keyboard for “entropy.”

Disclaimer

This is a personal project for people who already know their way around Bitcoin seed hygiene, Buildroot/Pi flashing, and verifying software themselves. It is not a product, not audited, and not “financial advice” of any kind.

If you lose coins, brick a Pi, flash the wrong image, or trust a bad download — that’s on you. I’m not responsible for any loss of funds or anything else that goes wrong. The MIT license already says the software is provided AS IS with no warranty; this section is just saying the same thing in plain English because seed stuff is scary and I don’t want anyone treating this like a supported wallet vendor.

Use the published test vectors. Build your own image if you can. Don’t put money on anything you haven’t verified.

Hardware (Pi Zero)

Target kit (same display setup SeedSigner popularized):

• Raspberry Pi Zero — prefer 1.3 (no Wi‑Fi); Zero W / W v1.1 works with the same image
• Waveshare 1.3" 240×240 LCD HAT (wiki) — must be 240×240
• GPIO headers on the Pi

No camera needed. More detail: docs/hardware.md. SeedSigner’s shopping list is a good reference for picking the right Waveshare board.

Compatibility (two recipes — don’t mix them)

Dice rolls

Tool	Mode	Compatible?
SeedSigner	Tools → New Seed → Dice (50 or 99 rolls)	Yes
Ian Coleman BIP39	Entropy → Hex or Base 10, force 12/24 words	Yes
Ian Coleman BIP39	Entropy → Dice [1-6]	No

digest = SHA256(utf-8(roll_digit_string))
50 rolls  → first 16 bytes → 12-word BIP39
99 rolls  → 32 bytes       → 24-word BIP39

Coin flips

Tool	Mode	Compatible?
Ian Coleman BIP39	Entropy → Binary, mnemonic length Use Raw Entropy	Yes
Ian Coleman BIP39	Binary + force 12 Words / 24 Words	No (Ian re-hashes; words won’t match)
SeedSigner coin SHA256(string) helper	—	No (different algorithm)

128 flips of 0/1  → 128-bit entropy → 12 words  (Heads=0, Tails=1)
256 flips of 0/1  → 256-bit entropy → 24 words

Wordlist: standard BIP-39 English (bitcoin/bips).

Requirements

• Python 3.10+
• Core / CLI / tests: no third-party packages
• Desktop UI preview: Pillow
• Pi + Waveshare airgap: dice-entropy-os

cd dice-entropy
pip3 install Pillow pytest   # optional

Tests

PYTHONPATH=src pytest tests/ -v

Dice vectors

Rolls	Length	Expected mnemonic (start … end)
50	12 words	hole luggage … identify path
99	24 words	eyebrow obvious … claim radio

99-roll string (from SeedSigner dice verification):

655152231316521321611331544441236164664431121534415633526456254462245546236542364246312613322234612

50 rolls:

65515223131652132161133154444123616466443112153441

Coin vectors

Cross-check on Ian Coleman: Binary + Use Raw Entropy.

Flips	Length	Expected mnemonic (start … end)
128 × 0	12 words	abandon … about
128 × 1	12 words	zoo … wrong
01 × 64	12 words	fetch primary … problem

CLI

# dice (default)
PYTHONPATH=src python3 -m dice_entropy.cli 65515223131652132161133154444123616466443112153441

# coin flips
PYTHONPATH=src python3 -m dice_entropy.cli --coin $(python3 -c 'print("0"*128)')

Desktop UI (preview)

PYTHONPATH=src python3 -m ui.main

Flow: Dice rolls or Coin flips → 128/256 bit → enter digits → mnemonic.

Keys: 1–6 (dice), 0/1 (coins), arrows, Enter, Backspace, Escape.

Releases / SD images

Best: build the OS image yourself from dice-entropy-os.

On a Mac, prefer the GitHub Actions build (real amd64) over local Docker emulation. Pre-built .img + SHA256 land on dice-entropy-os Releases (and get mirrored here when we cut a release). See docs/releases.md.

Scope

In: choose method → choose length → enter digits → show mnemonic (generate or cross-check).

Out: wallets, xpubs, QR, signing, camera entropy, SeedSigner firmware, networking, mixing software RNG into your flips/rolls.

Layout

src/dice_entropy/   # stdlib math + CLI
wordlists/          # BIP-39 English
ui/                 # desktop / Waveshare screens
tests/
docs/

License

MIT — see LICENSE.

BIP-39 wordlist © Bitcoin BIP authors / community.

Credits

• SeedSigner — dice flow, verification docs, Pi Zero + Waveshare airgap idea
• Ian Coleman BIP39
• BIP-39