From 6896f719fcb65bfbb2f17afa1dc6785e96130c5a Mon Sep 17 00:00:00 2001 From: philemon Date: Sun, 28 May 2017 10:53:10 +0300 Subject: [PATCH] modified: Getting-Started-with-MMGen.md --- Getting-Started-with-MMGen.md | 140 ++++++++++++++++++---------------- 1 file changed, 74 insertions(+), 66 deletions(-) diff --git a/Getting-Started-with-MMGen.md b/Getting-Started-with-MMGen.md index 307fc3f..1d55c99 100644 --- a/Getting-Started-with-MMGen.md +++ b/Getting-Started-with-MMGen.md @@ -34,11 +34,11 @@ The MMGen wallet system is not a single program but a suite of lightweight commands run from the command line. MMGen's commands all begin, not surprisingly, with 'mmgen'. To see a list of available commands, type 'mmgen' -followed by the TAB key. Every mmgen commands has a help screen displaying +followed by the TAB key. Every mmgen command has a help screen displaying detailed usage and options information. To view it, type the command name followed by `--help`. Note that most command options have long and short -versions. For example, the `--help` option may be abbreviated to `-h`. The -exception are the options listed by `--longhelp`, which have no short versions. +versions. For example, the `--help` option may be abbreviated to `-h`. +Exceptions are the options listed by `--longhelp`, which have no short versions. MMGen commands are generally interactive, informing you at every step and prompting you for input. The `--verbose` or `-v` option requests commands to be @@ -78,14 +78,14 @@ balance. If you want to practice creating, signing and sending transactions, however, as well as tracking balances, you'll need a fully synced blockchain and some -actual bitcoins to play with. To avoid risking real funds, it's *highly +actual coins to play with. To avoid risking real funds, it's *highly recommended* to practice transaction operations on testnet until you feel confident you know what you're doing. Testnet is just like the real Bitcoin network, but testnet coins have no monetary value. Free testnet coins may be obtained at [https://tpfaucet.appspot.com][02]. To use MMGen with testnet, you must first start bitcoind with the `-testnet` -option and sync the testnet blockchain (about 12GB at this time of writing). To +option and sync the testnet blockchain (about 12GB at the time of writing). To force any MMGen command to use testnet just add the `--testnet=1` option after the command name. Or just set the `testnet` option to `true` in 'mmgen.cfg' to make *all* commands use testnet. @@ -143,9 +143,12 @@ Don’t forget your passphrase. If you do, the coins in your MMGen wallet are gone forever. Since the wallet is a small, humanly readable ASCII file, it can easily be -printed out on paper. It can also be exported to more compact forms: the seed -file and mnemonic (discussed below). These formats are short enough to be -written out by hand or memorized. +printed out on paper. + +Another highly recommended way to back up your wallet is to generate a mnemonic +or seed file as described below and memorize it. If you +have an average or better memory, you'll find memorizing mnemonics to be +surprisingly easy. #### Generate addresses (offline computer) @@ -383,29 +386,33 @@ Continuing our example above, generate a mnemonic from the default wallet: 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 these seed lengths using the `-l` -option to 'mmgen-walletgen'. +Since our seed is 256 bits long, the mnemonic contains 24 words. 128-bit and +192-bit seeds generate shorter mnemonics of 12 and 18 words, respectively. +Wallets with these seed lengths can be generated using the `--seed-len` option +to 'mmgen-walletgen'. Though some consider 128 bits of entropy to provide adequate security for the -foreseeable future, it’s advisable to stick to the default 256-bit seed length -if you’re not planning to use the mnemonic feature. +foreseeable future, it’s advisable to stick to the default 256-bit seed length. +You'll find that even a 24-word mnemonic is not difficult to memorize. NOTE: MMGen mnemonics are generated from the Electrum wordlist, but using ordinary base conversion instead of Electrum’s more complicated algorithm. -The mnemonic file may be used any place you’d use a MMGen wallet with the same -Seed ID. You can generate ten addresses with it just as you did with the -wallet, for example: +The mnemonic is a complete representation of your seed and may be used anywhere +where you’d use an MMGen wallet. You can generate addresses with it just as you +do with a wallet: $ mmgen-addrgen 89ABCDEF.mmwords 1-10 ... Address data written to file '89ABCDEF[1-10].addrs' -The resulting address file will be identical to one generated by any wallet with -Seed ID '89ABCDEF'. +You can use it to sign transactions: -The mnemonic can be used to regenerate a lost wallet: + $ mmgen-txsign FEDCBA[0.1].rawtx 89ABCDEF.mmwords + ... + Signed transaction written to file 'FEDCBA[0.1].sigtx' + +The mnemonic can also be used to regenerate a lost wallet: $ mmgen-walletconv 89ABCDEF.mmwords ... @@ -414,32 +421,33 @@ The mnemonic can be used to regenerate a lost wallet: 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 generated and used exactly -the same way as mnemonic files: +An alternative to mnemonics, seed files provide yet another way of representing +your seed. They bear the extension '.mmseed' and are generated exactly the same +way as mnemonic files: $ mmgen-walletconv -o seed ... Seed data written to file '89ABCDEF.mmseed' -And they can also be used to regenerate a wallet: +They can be used just like mnemonics to regenerate a wallet: $ mmgen-walletconv 89ABCDEF.mmseed ... MMGen wallet written to file '89ABCDEF-23456701[256,3].mmdat' -Here’s a sample seed file for a 256-bit wallet: +Here’s a sample seed file for a 256-bit seed: $ cat 8B7392ED.mmseed f4c84b C5ZT wWpT Jsoi wRVw 2dm9 Aftd WLb8 FggQ eC8h Szjd da9L -And for a 128-bit wallet: +And for a 128-bit seed: $ cat 8E0DFB78.mmseed 0fe02f XnyC NfPH piuW dQ2d nM47 VU As you can see, seed files are short enough to be easily written out by hand or -even memorized. And their built-in checksum makes it easy to test your memory -using a simple Unix shell command: +memorized. And their built-in checksum makes it easy to test your memory using +a simple Unix shell command: $ echo -n XnyC NfPH piuW dQ2d nM47 VU | tr -d ' '| sha256sum | cut -c 1-6 0fe02f @@ -449,10 +457,9 @@ Or you can do the same thing with 'mmgen-tool': $ mmgen-tool str2id6 'XnyC NfPH piuW dQ2d nM47 VU' 0fe02f -Beginning with version 0.9.0, export to and generation from hexadecimal -(hexseed) format is also supported. Hexseed files are identical to seed files -but encoded in hexadecimal rather than base 58. They bear the extension -'.mmhex': +Beginning with version 0.9.0, MMGen also supports seed files in hexadecimal +(hexseed) format. Hexseed files are identical to seed files but encoded in +hexadecimal rather than base 58. They bear the extension '.mmhex': $ cat FE3C6545.mmhex afc3fe 456d 7f5f 1c4b fe3b c916 b875 60ae 6a3e @@ -463,19 +470,22 @@ standard command-line tools: $ echo 456d 7f5f 1c4b fe3b c916 b875 60ae 6a3e | tr -d ' ' | xxd -r -p | sha256sum -b | xxd -r -p | sha256sum -b | cut -c 1-8 fe3c6545 -A hexseed can be used to easily generate keys even without the MMGen software, -as explained in [this tutorial][03]. +A hexseed can be used to generate keys even without the MMGen software, +using basic command-line utilities, as explained in [this tutorial][03]. #### Mnemonics, seeds and hexseeds: additional information -MMGen commands that take mnemonic, seed or hexseed data may receive the data +All MMGen commands that take mnemonic, seed or hexseed data may receive the data from a prompt instead of a file. Just omit the file name and specify the input format: - $ mmgen-walletconv -i words + $ mmgen-addrgen -i words 1-10 ... Enter mnemonic data: +This means that you may keep your seed entirely in your head, as either a +mnemonic, seed or hexseed, and never record it anywhere on any medium. + With the `-S` option, MMGen commands may be requested to print wallet data to screen instead of a file. To safeguard against over-the-shoulder, Van Eck phreaking and other side-channel attacks, you’ll be prompted before this @@ -635,9 +645,9 @@ might choose to reserve all addresses in the range 1-1000 for cold storage and everything above that for your hot wallet. The next step is to create a key-address file for a sufficient number of “hot” -addresses to cover your day-to-day transaction needs for now. A key-address -file is just like an address file except that it contains keys as well as -addresses. Thus it functions as a hot wallet for a range of addresses. +addresses to cover your day-to-day transaction needs for the foreseeable future. +A key-address file is just like an address file except that it contains keys as +well as addresses, thus functioning as a hot wallet for a range of addresses. Assuming your hot address range begins at 1001, you could start by creating a key-address file for a hundred hot addresses like this: @@ -646,8 +656,8 @@ key-address file for a hundred hot addresses like this: Secret keys written to file '89ABCDEF[1001-1100].akeys.mmenc' `mmgen-keygen` prompts you for a password to encrypt the key-address file with. -This is a wise precaution, as it provides some security for keys that will be -stored on an online machine. +This is a wise precaution, as it provides at least some security for keys that +will be stored on an online machine. Now copy the key-address file to your online machine and import the addresses into your tracking wallet: @@ -663,8 +673,8 @@ can do quickie transactions with these funds using the `mmgen-txdo` command: The `--mmgen-keys-from-file` or `-M` option is required when using a key-address file in place of a default wallet. Note that your change address 89ABCDEF:1010 -is contained in the key-address file, so your change funds will remain “hot -spendable”. +is within the range covered by the key-address file, so your change funds will +remain “hot spendable”. Using `mmgen-txdo` with a default online hot wallet is even simpler. For a hot wallet with Seed ID 0FDE89AB, for instance, creating and sending a transaction @@ -695,29 +705,27 @@ satoshis-per-byte specification is an integer followed by the letter 's'. A fee of 90 satoshis per byte is thus represented as '90s'. MMGen has a hard maximum fee (currently 0.01 BTC) which is alterable only in the -config file. Thus MMGen will never create any transaction with a mistakenly or -dangerously high fee, or broadcast it to the network, unless you expressly -permit it to. +config file. Thus MMGen will never create or broadcast any transaction with a +mistakenly or dangerously high fee unless you expressly permit it to. #### BIP 125 replace-by-fee (RBF) transactions As of version 0.9.1, MMGen supports creating replaceable and replacement transactions in accordance with the BIP 125 replace-by-fee (RBF) specification. -Creating replaceable transactions is easy: First off, make sure bitcoind is -running with the `-walletrbf` option enabled. Then specify the `--rbf` option -when creating your transactions with `mmgen-txcreate` or `mmgen-txdo`. +To make your transactions replaceable, just specify the `--rbf` option when +creating them with `mmgen-txcreate` or `mmgen-txdo`. -Version 0.9.1 also introduces `mmgen-txbump`, a convenient command for creating -replacement transactions based on existing replaceable transactions. +Version 0.9.1 also introduces `mmgen-txbump`, a convenient command for quickly +creating replacement transactions from existing replaceable ones. `mmgen-txbump` can create, sign and send transactions in a single operation if desired. Continuing the examples from our primer above, we'll examine two RBF scenarios, one for a hot wallet and one for a cold storage wallet. In the first scenario, initial and replacement transactions will be created, signed and sent in one -operation. In the second, a batch of replacement transactions with incremented -fees will created for signing offline. +operation. In the second, a batch of replacement transactions with +incrementally increasing fees will created online and then signed offline. #### With an online (hot) wallet @@ -736,12 +744,12 @@ yourself at address #5 of your default hot wallet with Seed ID 0FDE89AB. Note that the fee is shown in the filename after the send amount. The presence of the fee in the filename identifies the transaction as replaceable. -If the transaction fails to confirm as desired, then create, sign and send a -replacement transaction with a higher fee, say 80 satoshis per byte: +If the transaction fails to confirm in your desired timeframe, then create, sign +and send a replacement transaction with a higher fee, say 100 satoshis per byte: - $ mmgen-txbump --send --tx-fee 80s --output-to-reduce c 'FEDCBB[0.1,50].sigtx' + $ mmgen-txbump --send --tx-fee 100s --output-to-reduce c 'FEDCBB[0.1,50].sigtx' ... - Signed transaction written to file 'DAE123[0.1,80].sigtx' + Signed transaction written to file 'DAE123[0.1,100].sigtx' ... Transaction sent: eef01357.... @@ -770,22 +778,22 @@ create the initial transaction with `mmgen-txcreate` instead of `mmgen-txdo`: ... Transaction written to file 'FEDCBC[0.1,50].rawtx' -Now create a series of transactions with incrementally increased fees for +Now create a series of transactions with incrementally increasing fees for offline signing: - $ mmgen-txbump --tx-fee 80s --output-to-reduce c 'FEDCBC[0.1,50].rawtx' - $ mmgen-txbump --tx-fee 120s --output-to-reduce c 'FEDCBC[0.1,50].rawtx' + $ mmgen-txbump --tx-fee 100s --output-to-reduce c 'FEDCBC[0.1,50].rawtx' $ mmgen-txbump --tx-fee 150s --output-to-reduce c 'FEDCBC[0.1,50].rawtx' + $ mmgen-txbump --tx-fee 200s --output-to-reduce c 'FEDCBC[0.1,50].rawtx' -To speed things up, you may add the `--yes` switch to make `mmgen-txbump` -completely non-interactive. +To speed things up, add the `--yes` switch to make `mmgen-txbump` completely +non-interactive. The result will be four raw transaction files with increasing fees, like this: FEDCBC[0.1,50].rawtx - 3EBB00[0.1,80].rawtx - 124FFF[0.1,120].rawtx - 73DABB[0.1,150].rawtx + 3EBB00[0.1,100].rawtx + 124FFF[0.1,150].rawtx + 73DABB[0.1,200].rawtx Copy the files to an empty folder, transfer the folder to your offline machine and batch sign them: @@ -795,9 +803,9 @@ Then copy the signed transaction files back to your online machine and broadcast them in turn until you get a confirmation: $ mmgen-txsend FEDCBC[0.1,50].sigtx # ...if this doesn't confirm, then - $ mmgen-txsend 3EBB00[0.1,80].sigtx # ...if this doesn't confirm, then - $ mmgen-txsend 124FFF[0.1,120].sigtx # ...if this doesn't confirm, then - $ mmgen-txsend 73DABB[0.1,150].sigtx + $ mmgen-txsend 3EBB00[0.1,100].sigtx # ...if this doesn't confirm, then + $ mmgen-txsend 124FFF[0.1,150].sigtx # ...if this doesn't confirm, then + $ mmgen-txsend 73DABB[0.1,200].sigtx [01]: https://github.com/mmgen/mmgen/wiki/Tracking-and-spending-ordinary-Bitcoin-addresses [02]: https://tpfaucet.appspot.com