# mmgen = Multi-Mode GENerator ## command-line Bitcoin cold storage solution NOTE: For the time being, MMGen should be considered Alpha software. Downloading and testing it out is easy, risk-free and encouraged. However, spending significant amounts of BTC into your mmgen-generated addresses is done at your own risk. ### Features: > As with all deterministic wallets, mmgen can generate an unlimited number > of address/key pairs from a single seed. You back up your wallet only once. > MMGen gives you four ways to access your Bitcoins: >> 1) with a wallet encrypted with AES256 using the crack-resistant scrypt >> function to hash the password. The wallet's password and hash >> strength can be changed; >> 2) with a one-line seed file (unencrypted); >> 3) with an Electrum-like mnemonic of 12, 18 or 24 words; or >> 4) with a brain password (recommended for expert users only). > Furthermore, these methods can all be combined. If you forget your > Electrum-like mnemonic, for example, you can regenerate it and your > keys from a stored wallet or seed. Correspondingly, a lost wallet or > seed can be recovered from the mnemonic. > The wallet and seed are short, simple text files suitable for printing > or even writing out by hand. The base-58-encoded seed is short enough > to memorize, providing another brain storage alternative. > Implemented as a suite of python scripts, MMGen is super-lightweight. > Combined with bitcoind compiled with the watch-only address feature > (see below), it provides a complete solution for securely storing > Bitcoins offline and tracking and spending them online. ### Instructions for Linux/Unix: ### Download: > `git clone https://github.com/mmgen/mmgen.git` ### Install: > Install the ecdsa, scrypt and pycrypto modules: sudo pip install ecdsa scrypt pycrypto > Install vanitygen (optional but recommended): git clone https://github.com/samr7/vanitygen.git (build, put the 'keyconv' executable in your path) > Install mmgen: cd mmgen; sudo ./setup.py install ### Getting Started: > On your offline computer: > Generate a wallet with a random seed: $ mmgen-walletgen ... Wallet saved to file '89ABCDEF-76543210[256,3].dat' > "89ABCDEF" is the Seed ID; "76543210" is the Key ID. > The Seed ID never changes and will be used to identify all > keys/addresses generated by this wallet. > The Key ID changes when the wallet's password or hash preset are changed. > "256" is the seed length; "3" is the scrypt hash preset. > These are configurable. > Generate ten addresses with the wallet: $ mmgen-addrgen 89ABCDEF-76543210[256,3].dat 1-10 ... Address data saved to file '89ABCDEF[1-10].addrs' > Note that the address range, "1-10", is indicated in the filename. > To generate addresses 1000 through 2000 (for example), specify > "1000-2000" on the command line and the filename will be > '89ABCDEF[1000-2000].addrs' $ cat '89ABCDEF[1-10].addrs' 89ABCDEF { 1 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE 2 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc 3 1HgYCsfqYzIg7LVVfDTp7gYJocJEiDAy6N 4 14Tu3z1tiexXDonNsFIkvzqutE5E3pTK8s 5 1PeI55vtp2bX2uKDkAAR2c6ekHNYe4Hcq7 6 1FEqfEsSILwXPfMvVvVuUovzTaaST62Mnf 7 1LTTzuhMqPLwQ4IGCwwugny6ZMtUQJSJ1 8 1F9495H8EJLb54wirgZkVgI47SP7M2RQWv 9 1JbrCyt7BdxRE9GX1N7GiEct8UnIjPmpYd 10 1H7vVTk4ejUbQXw45I6g5qvPBSe9bsjDqh } > To store your Bitcoins, spend them into these addresses from whatever > wallets/software you're currently using. If you have lots of BTC, > generate lots of addresses so that each address will have only a > relatively small balance. ### Spending your stored coins: > Take address 1 out of cold storage by generating a key for it: $ mmgen-keygen 89ABCDEF-76543210[256,3].dat 1 ... Key data saved to file '89ABCDEF[1].akeys' $ cat 89ABCDEF[1].akeys 89ABCDEF { 1 sec: 5JCAfK1pjRoJgmpmd2HEMNwHxAzprGIXeQt8dz5qt3iLvU2KCbS addr: 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE } > Save the \*.akeys file to a USB stick and transfer it to your online computer. > On your online computer, import the secret key into > a running bitcoind or bitcoin-qt: $ bitcoind importprivkey 5JCAfK1pjRoJgmpmd2HEMNwHxAzprGIXeQt8dz5qt3iLvU2KCbS > That's all there is to it! > OPTIONAL: To track balances without exposing secret keys on your > online computer, download and compile sipa's bitcoind patched for > watch-only addresses: $ git clone https://github.com/sipa/bitcoin $ git branch mywatchonly remotes/origin/watchonly $ git checkout mywatchonly (build, install) > Track the balances of the addresses in '89ABCDEF[1-10].addrs': $ bitcoind importaddress 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE $ bitcoind importaddress 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc $ ... ### Using the mnemonic and seed features: > Using our example above, > Generate a mnemonic from the wallet: $ mmgen-walletchk -m '89ABCDEF-76543210[256,3].dat' ... Mnemonic data saved to file '89ABCDEF.words' $ cat 89ABCDEF.words pleasure tumble spider laughter many stumble secret bother after search float relationship path strong curtain savior worst suspend bright touch away dirty measure thorn > Note: a 128-bit or 192-bit seed will generate a shorter mnemonic of 12 > or 18 words. Generate a wallet with a shorter seed by using > `mmgen-walletgen -l`. Whether you consider 128 or 192 bytes of > entropy to be enough is up to you. > Generate addresses 1-11 using the mnemonic instead of the wallet: $ mmgen-addrgen -m 89ABCDEF.words 1-11 ... Address data saved to file '89ABCDEF[1-11].addrs' > Compare the first ten addresses with those earlier generated from the > wallet. You'll see they're the same. > Recover a lost wallet using the mnemonic: $ mmgen-walletgen -m 89ABCDEF.words ... Wallet saved to file '89ABCDEF-01234567[256,3].dat' > Note that the regenerated wallet has a different Key ID but > of course the same Seed ID. > Seeds are generated the same way as mnemonics. Just change the > '-m' option to '-s' in the preceding commands. > A seed file for a 256-bit seed looks like this: $ cat 8B7392ED.mmseed f4c84b C5ZT wWpT Jsoi wRVw 2dm9 Aftd WLb8 FggQ eC8h Szjd da9L > And for a 128-bit seed: $ cat 8E0DFB78.mmseed 0fe02f XnyC NfPH piuW dQ2d nM47 VU > The latter is short enough to be memorized or written down. > The first word is a checksum. > To check that you've written or memorized the seed correctly, take the > first 3 bytes of a sha256 hash of the remainder of the line (with > spaces removed). #### Mnemonics and seeds — additional information: > Mnemonic and seed data may be entered at the prompt instead of from a > file. Just omit the filename on the command line. > Mnemonic and seed data may be printed to standard output instead of a > file with `mmgen-walletchk -S` > Mnemonic and seed files may be output to a directory besides the > current one with `mmgen-walletchk -d` > Bear in mind that mnemonic and seed data is unencrypted. If it's > compromised, your Bitcoins can easily be stolen. Make sure no one's > looking when you print mnemonic or seed data to screen. Securely > delete your mnemonic and seed files. In Linux, you can achieve > additional security by writing the files to volatile memory in > '/dev/shm' instead of disk. ### Vanitygen note: > When available, the 'keyconv' utility from the vanitygen package is > used to generate addresses because it's much faster than the python > ecdsa library. ### Test suite: > To see what tests are available, run the scripts in the 'tests' > directory without arguments. Some of the more interesting tests to > try: tests/bitcoin.py keyconv_compare_randloop 10 tests/bitcoin.py hextob58_pad_randloop 1000 tests/mnemonic.py random128 tests/mnemonic.py random192 tests/mnemonic.py random256