From e2e4f59bee9b1f98bb59a54714426ef0de79e1e0 Mon Sep 17 00:00:00 2001 From: philemon Date: Sat, 30 Nov 2013 22:19:32 +0400 Subject: [PATCH] modified: README.md --- README.md | 139 +++++++++++++++++++++++++++++------------------------- 1 file changed, 76 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index b8d593b5..4e1517be 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # mmgen = Multi-Mode GENerator -## command-line Bitcoin cold storage solution +## a Bitcoin cold storage solution for the command line NOTE: For the time being, MMGen should be considered Alpha software. Downloading and testing it out is easy, risk-free and encouraged. @@ -11,45 +11,46 @@ addresses is done at your own risk. > 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: +> With MMGen you can choose from four different 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; +>> 1) an encrypted wallet (the AES 256 key is generated from your +>> password using the crack-resistant scrypt hash function. The +>> wallet's password and hash strength can be changed); ->> 2) with a one-line seed file (unencrypted); +>> 2) a short, human-readable seed file (unencrypted); ->> 3) with an Electrum-like mnemonic of 12, 18 or 24 words; or +>> 3) an Electrum-like mnemonic of 12, 18 or 24 words; or ->> 4) with a brain password (recommended for expert users only). +>> 4) a brainwallet 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. +> 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. +> or even writing out by hand. Their built-in checksums can be used to +> verify they've been correctly copied. 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. +> Implemented as a suite of lightweight python scripts with a +> command-line interface, MMGen demands practically no system resources. +> Yet in tandem with a bitcoind enabled for watch-only addresses +> (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: +### Download/Install: > Install the ecdsa, scrypt and pycrypto modules: sudo pip install ecdsa scrypt pycrypto > Install mmgen: + git clone https://github.com/mmgen/mmgen.git + cd mmgen; sudo ./setup.py install > Install vanitygen (optional but recommended): @@ -67,13 +68,16 @@ addresses is done at your own risk. ... Wallet saved to file '89ABCDEF-76543210[256,3].dat' +> "89ABCDEF" is the Seed ID; "76543210" is the Key ID. These are +> randomly generated, so your IDs will naturally be different than the +> fictitious ones used in this example. -> "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. +> 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: @@ -83,10 +87,7 @@ addresses is done at your own risk. 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' +> Note that the address range, "1-10", is included in the resulting filename. $ cat '89ABCDEF[1-10].addrs' 89ABCDEF { @@ -105,7 +106,7 @@ addresses is done at your own risk. > 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 +> generate many addresses so that each address will have only a > relatively small balance. ### Spending your stored coins: @@ -121,10 +122,10 @@ addresses is done at your own risk. addr: 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE } -> Save the \*.akeys file to a USB stick and transfer it to your online computer. +> 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: +> On your online computer, import the secret key into a running bitcoind +> or bitcoin-qt: $ bitcoind importprivkey 5JCAfK1pjRoJgmpmd2HEMNwHxAzprGIXeQt8dz5qt3iLvU2KCbS @@ -140,7 +141,8 @@ addresses is done at your own risk. (build, install) -> Track the balances of the addresses in '89ABCDEF[1-10].addrs': +> With your newly-compiled bitcoind running, import the addresses from +> '89ABCDEF[1-10].addrs' to track their balances: $ bitcoind importaddress 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE $ bitcoind importaddress 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc @@ -158,13 +160,14 @@ addresses is done at your own risk. $ cat 89ABCDEF.words pleasure tumble spider laughter many stumble secret bother - after search float relationship path strong curtain savior + after search float absent 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. +> 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 by +> using the `-l` option of `mmgen-walletgen`. Whether you consider +> 128 bits of entropy enough is your call. It's probably adequate for +> the foreseeable future. > Generate addresses 1-11 using the mnemonic instead of the wallet: @@ -184,8 +187,8 @@ addresses is done at your own risk. > 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. +> Seeds are generated and input 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: @@ -199,40 +202,50 @@ addresses is done at your own risk. > 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). +> The first word in the seed file is a checksum. +> To check that you've written or memorized the seed correctly (should +> you choose to do so), compare it with the first 6 characters 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 +> Mnemonic and seed data may be entered at a 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` +> file using the `-S` option of `mmgen-walletchk` -> Mnemonic and seed files may be output to a directory besides the -> current one with `mmgen-walletchk -d` +> Mnemonic and seed files may be output to a directory of your choice +> using the `-d` option of `mmgen-walletchk` > 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. +> looking over your shoulder 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. +> used to generate addresses as 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: +> directory without arguments. Some may find the following tests +> interesting: - 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 +>> Compare 10 addresses generated with 'keyconv' with internally-generated ones: +>>> `tests/bitcoin.py keyconv_compare_randloop 10` + +>> Perform 1000 hex -> base58 -> hex conversions, comparing results: +>>> `tests/bitcoin.py hextob58_pad_randloop 1000` + + +>> Generate a 12-word mnemonic for a random 128-bit seed: +>>> `tests/mnemonic.py random128` + +>> Ditto, random 192-bit seed: +>>> `tests/mnemonic.py random192` + +>> Ditto, random 256-bit seed: +>>> `tests/mnemonic.py random256`