diff --git a/README.md b/README.md deleted file mode 100644 index d17237cf..00000000 --- a/README.md +++ /dev/null @@ -1,436 +0,0 @@ -MMGen = Multi-Mode GENerator -============================ - -a Bitcoin cold storage solution for the command line ----------------------------------------------------- - -### Description - -MMGen is implemented as a suite of lightweight Python command-line -scripts that require only a bare minimum of system resources. -The scripts function in tandem with a modified -bitcoind running on an online computer and a standard -bitcoind running offline to provide a robust solution for securely -storing, tracking, spending and receiving your Bitcoins. "Non-MMGen" -addresses can be tracked and spent as well, creating an easy migration -path from other wallets. - -The online bitcoin daemon is modified to support watch-only addresses, -a feature soon to be included in the mainline Satoshi build. -In the meantime, instructions are provided below for compiling the -watch-only bitcoind, which under Linux is surprisingly easy. - -MMGen uses the reference Satoshi daemon, rather than less-reliable -third-party software, to do all the "heavy lifting" of tracking and -signing transactions. -And unlike other online/offline wallet solutions, the MMGen system is -completely self-contained, relying on no external server to do its -work; no third party will know which addresses you're tracking. - -Like all deterministic wallets, MMGen can generate a virtually -unlimited number of address/key pairs from a single seed. Your wallet -never changes, so you need back it up only once. -Transactions are signed offline: your private keys never touch an -online computer. - -At the heart of the MMGen system is the seed, the "master key" -providing access to all your Bitcoins. The seed can be stored in four -different ways: - -> 1) as a wallet with a password -> encrypted using the crack-resistant scrypt hash function. -> Scrypt's parameters can be adjusted on the command line, making your -> wallet's password virtually impossible to crack should it fall into the wrong -> hands. The wallet is a tiny text file -> suitable for printing or even writing out by hand; - -> 2) as a seed file: a one-line base-58 representation of your -> unencrypted seed plus a checksum; - -> 3) as an Electrum-like mnemonic of 12, 18 or 24 words; or - -> 4) as a brainwallet password (this option is recommended for expert -> users only). - -The best part is that all these methods can be combined. If you -forget your mnemonic, for example, you can regenerate it and your keys -from the stored wallet or seed file. Correspondingly, a lost wallet can -be regenerated from the mnemonic or seed or a lost seed from the wallet or -mnemonic. - - -### Download/Install - -> #### [Install on Microsoft Windows](doc/MMGenInstallMSWin.md) - -> #### [Install on Debian/Ubuntu Linux](doc/MMGenInstallLinux.md) - - -### Using MMGen - -#### Generate a wallet (offline computer): - -On your offline computer, generate a wallet with a random seed: - - $ mmgen-walletgen - ... - Wallet saved to file '89ABCDEF-76543210[256,3].mmdat' - -"89ABCDEF" is the Seed ID; "76543210" is the Key ID. These are -randomly generated, so your IDs will of course be different than the -fictitious ones used here. - -The Seed ID never changes and will be used to identify all keys/addresses -generated by this seed. 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 values -are configurable: type `mmgen-walletgen --help` for details. - -#### Generate addresses (offline computer): - -Now generate ten addresses with your just-created wallet: - - $ mmgen-addrgen 89ABCDEF-76543210[256,3].mmdat 1-10 - ... - Address data saved to file '89ABCDEF[1-10].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 - } - -Note that the address range, "1-10", is reflected in the resulting filename. -MMGen addresses are identified by their seed ID plus number, separated -by a colon. In this example, "89ABCDEF:1" is the MMGen equivalent -of Bitcoin address 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE, "89ABCDEF:2" -the equivalent of 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc, and so forth. - -Let's say you've decided to transfer some BTC into the first four -addresses above. Your first step, then, will be to import these -addresses into the tracking wallet on your online machine. -You've chosen to provide the addresses with the labels "Donations", -"Storage 1", "Storage 2" and "Storage 3" for convenient identification. - -Make a copy of the file: - - $ cp '89ABCDEF[1-10].addrs' my_addrs_for_import - -and edit the copy using your favorite text editor. The result will -look something like this: - - $ cat my_addrs_for_import - 89ABCDEF { - 1 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE Donations - 2 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc Storage 1 - 3 1HgYCsfqYzIg7LVVfDTp7gYJocJEiDAy6N Storage 2 - 4 14Tu3z1tiexXDonNsFIkvzqutE5E3pTK8s Storage 3 - } - -Note that rows in the list may be arranged in any order; addresses -need not be consecutive. - -Copy this file onto a USB stick and transfer it to your online -computer. - -#### Import addresses (online computer): - -On your online computer, start bitcoind and import the addresses into -the tracking wallet: - - $ mmgen-addrimport my_addrs_for_import - -These addresses are now being "tracked". Any BTC transferred -to them will show up in our listing of unspent outputs. - -You'll want to track your existing addresses with balances too. -Make a plain list of these addresses, one address per line, and import -the list into the tracking wallet using the same command -with the `'-l'` option: - - $ mmgen-addrimport -l my_existing_addrs_with_balances - -Since the importing process is slow, you may want to do it in stages, -a few addresses at a time. - -For your convenience, comments beginning with a '#' symbol may be -included in address lists. -Continue in this fashion until you've imported all addresses with -balances into your tracking wallet. - -#### Create a transaction (online computer): - -Now that your existing addresses are imported, you're ready to create -a test transaction using the `mmgen-txcreate` command. Note that -transactions are harmless until they're signed and broadcast to the -network, so feel free to experiment with different transactions -using different combinations of inputs and outputs. - -First of all, you'll probably want to examine your balances: - - $ mmgen-txcreate -i - -A list of all your unspent outputs will appear, -along with a menu allowing you to sort the outputs by four -criteria: transaction ID, address, amount and transaction age. -Your overall balance in BTC appears at the top of the screen. The -list may be viewed in a pager or printed to file. If you have -ten unspent outputs, your display will look something like this: - - UNSPENT OUTPUTS (sort order: reverse amount) Total BTC: 39.72 - Num TX id Vout Address Amount (BTC) Age(days) - 1) 04f97185... 2 1F93Znz8PI5Pnvv8ZAJsb74EzKpmRMLFbk 10 320 - 2) dd900544... 1 194Fceqx86jqIWumphUmfVyFMjAAbMLcSE 9.9287435 7 - 3) 7ec81a8f... 0 1FhIkRabPSZhhUsA6qvukmfK4T4PZLbC4M 7.26 17 - 4) 64094b55... 0 16JSUJdGMbxUBEQatAR5sGE89tbSIsLHqg 3.15 140 - 5) fd687c65... 1 1QKAtU66aUntCBx9m6TfEIf3gQuCNWCVDY 3.15 140 - 6) 9a8f20e2... 1 1FMNDFz1yUywjJSprjvYY9t1yxkE8GGIwT 3.15 140 - 7) 03a7c51a... 3 1svxnSdKVIcMs6qWYA7qLzA29orXbzXUm 1.6382466 54 - 8) 9955f06c... 2 18nWPLQGUzI7X1Rcm4zmVV6Z3xhokdYx9G 1.2 27 - 9) 8a4ab4f5... 0 13S9HNu7PQn1aJ4qILfhqRSakXwvSTnbwJ 0.23033 3 - 10) 5bfe5621... 1 1FV1Lhs6Dnc9gMxjJTo6h4nTeIjJbQ1PgV 0.01 42 - - Sort options: [t]xid, [a]mount, a[d]dress, [A]ge, [r]everse, [M]mgen addr - View options: [g]roup, show [m]mgen addr - (Type 'q' to quit sorting, 'p' to print to file, 'v' to view in pager): - -Now let's actually create a transaction. Let's say you've decided to -gradually begin spending your 39.72 BTC balance into your shiny new -MMGen wallet with seed ID 89ABCDEF. - -Before doing anything else, you should back up your MMGen wallet in -several places and possibly on several media too: paper, flash memory -or CD-ROM, for example. Of course the wallet should have a -passphrase. Otherwise, anyone who gains physical control of one of -your backups can easily steal your coins. - -Recall that there's no limit to the number of addresses you can -generate with your seed. You've wisely determined that having many -addresses with relatively small balances is a Good Idea. -You've decided to begin by breaking up your -address with the largest balance, 10 BTC, into three roughly equal parts, -sending it to the addresses labeled "Storage 1", "Storage 2" and -"Storage 3" (89ABCDEF:1, 89ABCDEF:2 and 89ABCDEF:3). - -To refresh our memory, here are the three addresses in question: - - 89ABCDEF { - 2 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc Storage 1 - 3 1HgYCsfqYzIg7LVVfDTp7gYJocJEiDAy6N Storage 2 - 4 14Tu3z1tiexXDonNsFIkvzqutE5E3pTK8s Storage 3 - } - -The following command will send 3.3 BTC to the first two addresses and -the remainder of the transaction's inputs to the third, subtracting a -default transaction fee of 0.001 BTC: - - $ mmgen-txcreate 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc,3.3 1HgYCsfqYzIg7LVVfDTp7gYJocJEiDAy6N,3.3 14Tu3z1tiexXDonNsFIkvzqutE5E3pTK8s - -The third address has the amount left out, making it a **change -address**. -MMGen will compute the change amount (3.399 BTC in this case) automatically. - -Alternatively, and more conveniently, you can write the -addresses in MMGen format: - - $ mmgen-txcreate -a addrs 89ABCDEF:2,3.3 89ABCDEF:3,3.3 89ABCDEF:4 - -'addrs' is an MMGen address file containing the requested output -addresses. Any unneeded addresses in the file will be ignored. - -Now hit ENTER, choose the -transaction's input from the list (10 BTC, address -1F9495H8EJLb54wirgZkVgI47SP7M2RQWv, txid 04f97185...,2), -and confirm. -If all goes well, the command will exit with a message like this: - - Transaction data saved to file 'tx_1EDCBA[6.6].raw' - -Note that the transaction has a unique ID, and the non-change output -amount, 6.6 BTC, is conveniently included in the filename. - -#### Sign the transaction (offline computer): - -Now copy the raw transaction you've just created to a USB stick and -transfer it to your offline computer for signing. You need to find -the key for your transaction's one input address, -1F9495H8EJLb54wirgZkVgI47SP7M2RQWv. If the key in question is in a -bitcoin 'wallet.dat', there's an included command that will -conveniently extract the key for you: - - $ mmgen-pywallet -k wallet.dat - ... - wallet.dat secret keys saved to file wd_EDBC983A[102].keys - -You've in fact extracted a list of all of the wallet's 102 keys here, -but that's not a problem, as the unused keys will be ignored. -Now go ahead and sign the transaction using this list of keys. - - $ mmgen-txsign -k wd_EDBC983A[102].keys tx_1EDCBA[6.6].raw - ... - Signed transaction saved to file tx_1EDCBA[6.6].sig - -Note that mmgen-pywallet's output is just a flat list of keys. -So if you have several Bitcoin wallets with balances, you can just -dump all their keys and concatenate them into a single file which you -can use to sign all your future transactions involving wallet.dat -inputs: - - $ mmgen-pywallet -k wallet1.dat - $ mmgen-pywallet -k wallet2.dat - $ mmgen-pywallet -k wallet3.dat - $ cat wd_*.keys > all_keys - -For transactions whose inputs are MMGen addresses, an MMGen -seed source (i.e. wallet, mnemonic or seed file) is listed on the -command line after the transaction file, and the required keys are -automatically generated: - - $ mmgen-txsign tx_9D2C3A[1.23].raw B73B58EA-125FB230[256,3].mmdat - -Transactions may contain a mixture of MMGen and non-MMGen inputs as -well as inputs with more than one MMGen seed ID. Just provide a seed -source for each seed ID on the command line. - -Eventually, when you've placed all your BTC under MMGen control, -you'll never have to deal with keys again. MMGen just generates them -on the fly as the need arises. - -#### Send the transaction (online computer): - -Now we're ready for the final step: broadcasting the transaction to -the network. Copy the \*.sig file to your online computer, start -bitcoind, if it's not running, and execute the command - - $ mmgen-txsend tx_1EDCBA[6.6].sig - -Like all mmgen commands, `mmgen-txsend` is interactive, so you'll be -asked for confirmation before the transaction is actually sent. - -Once the transaction's confirmed by the network, your three new MMGen -addresses will appear on the listing of `mmgen-txcreate -i`. Type -'m' at the menu and they'll be displayed in MMGen format. - -Congratulations! You've performed your first MMGen transaction. - -### Additional Features - -#### Using the mnemonic and seed features: - -Continuing our example above, generate a mnemonic from the wallet: - - $ mmgen-walletchk -m '89ABCDEF-76543210[256,3].mmdat' - ... - Mnemonic data saved to file '89ABCDEF.mmwords' - - $ cat 89ABCDEF.mmwords - pleasure tumble spider laughter many stumble secret bother - after search float absent path strong curtain savior - worst suspend bright touch away dirty measure thorn - -Note: a 128- or 192-bit seed will generate a shorter mnemonic of 12 or -18 words. You may generate a wallet with a these seed lengths -using the `'-l'` option to `mmgen-walletgen`. - -Though some consider 128 bits of entropy to provide adequate security -for the foreseeable future, you should stick to the default 256-bit -seed length if you're not planning to use the mnemonic feature. - -NOTE: MMGen mnemonics are generated from the Electrum wordlist, only -using ordinary base conversion instead of Electrum's more complicated -algorithm. - -Generate addresses 1-11 using the mnemonic instead of the wallet: - - $ mmgen-addrgen 89ABCDEF.mmwords 1-11 - ... - Address data saved to file '89ABCDEF[1-11].addrs' - -Compare the first ten addresses with those earlier generated by the -wallet. You'll see they're the same. - -Recover a lost wallet using the mnemonic: - - $ mmgen-walletgen 89ABCDEF.mmwords - ... - Wallet saved to file '89ABCDEF-01234567[256,3].mmdat' - -Note that the regenerated wallet has a different Key ID but -of course the same Seed ID. - -Seed files bear the extension '\*.mmseed' and are listed on the command -line the same way as mnemonic files are. - -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 - -As you can see, the latter is short enough to practically be memorized. -From the unix command line, -you can test your memory using the seed's checksum ('0fe02f' in this example) -as follows: - - $ echo -n XnyCNfPHpiuWdQ2dnM47VU | sha256sum | cut -c 1-6 - 0fe02f - -#### Mnemonics and seeds — additional information: - -With the `'-m'` or `'-s'` option, -MMGen commands that take mnemonic and seed data may receive the data -from a prompt instead of a file. - -MMGen commands that produce mnemonic and seed data may be forced to -print it to standard output instead of file with the `'-S'` option. -This feature was intentionally made optional to safeguard against -looking-over-the-shoulder, Van Eyck phreaking and other side-channel -attacks. MMGen commands never print private data to the screen -unless explicitly asked to. - -The output file of any MMGen command may be written to a directory of -your choice using the `'-d'` option. For example, on a Linux system you -could use `'-d /dev/shm'` to write key and seed data to volatile memory -instead of disk. -This also has obvious security benefits, ensuring that no sensitive data -remains on disk after your computer's been powered down. - -### Test suite: - -To see what tests are available, run the scripts in the 'tests' -directory with no arguments. You might find the following tests to be -of interest: - -> Compare 10 addresses generated by 'keyconv' with mmgen's -> internally-generated ones: ->> `tests/bitcoin.py keyconv_compare_randloop 10` - -> Convert a string to base 58 and back: ->> `tests/bitcoin.py strtob58 'a string'` - -> Convert a hex number to base 58 and back: ->> `tests/bitcoin.py hextob58 deadbeef` - -> Perform 1000 hex -> base58 -> hex conversions, comparing results stringwise: ->> `tests/bitcoin.py hextob58_pad_randloop 1000` - -> Generate a 12-word mnemonic from a random 128-bit seed: ->> `tests/mnemonic.py random128` - -> or an 18-word mnemonic from a random 192-bit seed: ->> `tests/mnemonic.py random192` - -> or a 24-word mnemonic from a random 256-bit seed: ->> `tests/mnemonic.py random256`