- Roll2Mnemonic
- Features
- Prerequisites
- Installation
- Online Usage
- Offline Usage
- Demo Video
- Support and Feedback
- Donations
- Disclaimer
- License
Roll2Mnemonic is an educational tool for studying BIP39 mnemonic generation, Bitcoin derivation paths, addresses, and BIP85 child mnemonics. It can generate corresponding private keys and public addresses for supported Bitcoin script types.
The application opens with an embedded terminal on the left and controls on the right. It starts maximized, requires an explicit security acknowledgement, and currently exposes 12-word and 24-word choices in the UI. Other supported word-count controls remain in the code for future use.
- Dice Roll:
- Physical Dice or Coin Toss: You have the flexibility to roll physical dice or conduct a coin toss and input the resulting data as either binary (1 or 0) or numbers (1 to 6). This method ensures absolute randomness for generating your mnemonic seed phrase.
- Generate From Entropy: The application uses Python's OS-backed
secretsCSPRNG for this educational mode. This mode is not recommended for real funds; use your own physical dice or coin flips for highest assurance. - Mnemonic Seed Generation: After collecting the dice roll data, the program seamlessly proceeds to generate a valid checksum and creates a BIP39 mnemonic seed phrase. This seed phrase forms the cornerstone for generating Bitcoin private keys and public addresses.
- Mnemonic Code Converter: The generated mnemonic seed phrase is then processed through the Mnemonic Code Converter, capable of generating BIP39 private keys and public addresses for all script types: Legacy (P2PKH), Nested SegWit (P2SH-P2WPKH), Native SegWit (P2WPKH), and Taproot (P2TR).
- Mnemonic Converter:
- Generate From Entropy: The application can generate entropy with the OS-backed CSPRNG for educational testing. This mode is explicitly not recommended for real funds.
- Mnemonic Seed Generation: After collecting the Hex seed, the program seamlessly proceeds to generate a valid checksum and creates a BIP39 mnemonic seed phrase.
- Own Mnemonic Seed Phrase: You have the option to enter your own mnemonic seed phrase into the program.
- Mnemonic Code Converter: The generated mnemonic seed phrase is then processed through the Mnemonic Code Converter, capable of generating BIP39 private keys and public addresses for all script types: Legacy (P2PKH), Nested SegWit (P2SH-P2WPKH), Native SegWit (P2WPKH), and Taproot (P2TR).
- BIP85 Generator: Generate BIP85 Child Keys from your own Mnemonic Seed Phrase or using seeds generated with the tools above, then specify the numbers of words and number of Child Keys using the index number.
- QR Code Generator: A built-in QR code generator from text.
This project is educational and has not been independently audited. Do not use it to generate or handle real Bitcoin funds without independently reviewing and verifying the complete code, dependencies, operating system, and device.
A seed phrase and passphrase control the wallet. If they are exposed, an attacker can spend the funds, and Bitcoin transactions are generally irreversible. A valid BIP39 checksum does not prove that the original entropy was secure; weak, predictable, reused, or manipulated entropy can produce a phrase an attacker can reproduce.
For the highest assurance, use a trusted offline device and create entropy by rolling your own fair dice or performing your own fair coin flips. Never enter a seed or passphrase into a website, online verifier, screenshot, cloud service, or untrusted computer. Before funding a wallet, independently verify its addresses and test restoration from an offline backup.
The library/ directory contains archived development snapshots. Do not execute files from that directory; they are not covered by the current security review.
Before using the Mnemonic Code Converter, ensure you have the following prerequisites installed on your system:
- Python 3.11 or newer (the current development environment uses Python 3.13)
- Tkinter for your operating system
- Python packages listed in
requirements.txt
Install Python 3.11 or newer and Tkinter for your operating system.
Install Python from python.org. During setup, enable Add Python to PATH and install tcl/tk when offered. In PowerShell:
py -3-m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txtIf PowerShell blocks activation, run the commands with .venv\Scripts\python.exe directly instead.
On Debian or Ubuntu, install Python, Tkinter, and virtual-environment support:
sudo apt update
sudo apt install python3 python3-pip python3-tk python3-venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txtFor other distributions, install the equivalent python3-tk and venv packages using that distribution's package manager.
Install Python 3.11 or newer from python.org. The python.org installer includes Tkinter and is the recommended macOS setup for this project.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txtIf Tkinter cannot be imported, use the python.org installer or install the matching python-tk package for the Python version in use.
After setup, continue with the platform-specific launch instructions below.
Clone this repository to your local machine:
To clone the repository using HTTPS, open your terminal or command prompt and run the following command:
git clone https://github.com/SaniExp/Roll2Mnemonic.git
cd Roll2MnemonicAlternatively, download and extract the latest source archive:
Download the main branch as a ZIP
Run the application from the repository directory after installation:
python main.pyOn Windows PowerShell:
python .\main.pyOn Linux or macOS:
python3 main.pyThe application is local-only and does not require an internet connection while running. Select an entropy source, choose the mnemonic length, and follow the prompts in the embedded terminal. When entering your own values, use only the number and character set requested by each prompt.
The application displays a security warning before use. Do not enter real seed phrases, passphrases, or private keys on an internet-connected or otherwise untrusted computer. For real wallet creation, use the offline procedure below and independently verify all generated addresses.
The application uses Python, Tkinter, and platform-neutral Python libraries and is intended to run on Windows, Linux, and macOS. Windows-specific console hiding and window maximizing are guarded by os.name; Linux and macOS use Tk's non-Windows zoom behavior when supported. Number formatting falls back to the system locale if en_US.UTF-8 is unavailable.
Tkinter must be installed separately on many Linux distributions and some macOS Python installations. The application has been verified in this repository's current Windows environment; Linux and macOS should be smoke-tested on the target OS before handling sensitive data.
To run the automated tests:
python -m unittest discover -s tests -vTo set up Python in an offline environment you must download the packages by using an internet-enabled computer, and then transfer the files to the offline computer. Ensure target machine is the same architecture, OS, and Python version as the original device.
- Download latest version of python from:
https://www.python.org/downloads/- Download latest version of pip, if you don't have it on ur current computer or offline computer and follow instructions from:
https://pip.pypa.io/en/stable/installation/Clone or download the repository (Make sure you have the latest release), and extract it.
Cloning dependencies, same method for all operating systems:
a. In a terminal, navigate to the Roll2Mnemonic directory:
cd C:\Roll2Mnemonic
b. Create a subdirectory named wheelhouse:
mkdir wheelhouse
c. Run the following command to download the required dependencies to the subdirectory:
pip download -r requirements.txt -d wheelhouse
d. Copy the Python and pip packages you downloaded earlier and the folder Roll2Mnemonic, which contains the repository and the sub-folder Wheelhouse, into a USB stick and transfer them to your offline computer.
e. Install the Python and pip packages then, in a terminal, navigate to the Roll2Mnemonic folder:
cd C:\Roll2Mnemonic
f. Run the following to install the dependencies:
pip install -r requirements.txt --no-index --find-links wheelhouse
g. If you encounter installation errors you can try this alternative method to install the dependencies. Otherwise, you need to retrieve the failed dependencies manually:
Windows (Command Prompt):
for%iin ("C:\path\to\folder with spaces\*") do pip install "%i"
Linux/Mac (Command Prompt):
forpackagein"/path/to/folder with spaces"/*;do pip install "$package"done
Now your offline device should have the required dependencies to run offline. Do not use the online clone/download machine to enter or generate wallet secrets.
If you have any questions, encounter issues, or want to provide feedback, please open an issue in this repository or provide feedback through twitter @SaniExp.
If you find this project useful and would like to support its development, you can make a donation to help keep it going. Your contributions are greatly appreciated!
- Bitcoin lightning address (Wallet Of Satoshi): sani@walletofsatoshi.com
- Bitcoin lightning address (Blink): sani@blink.sv
The application displays a security disclaimer and requires the user to type I UNDERSTAND before use. This acknowledgement is not a security guarantee. If the device, operating system, dependencies, display, terminal output, logs, or application is compromised, assume every displayed seed, passphrase, private key, and extended private key is compromised and abandon the wallet.
This project is licensed under the MIT License - see the LICENSE file for details.