modified: README.md

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:
-
-                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
+> directory without arguments.  Some may find the following tests
+> interesting:
+
+>> 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`