diff --git a/Getting-Started-with-MMGen.md b/Getting-Started-with-MMGen.md index 65d1ff2..437ea1a 100644 --- a/Getting-Started-with-MMGen.md +++ b/Getting-Started-with-MMGen.md @@ -4,7 +4,7 @@ * Before you begin * Invocation * Configuration file -* Testnet and regtest mode +* Bob and Alice regtest mode #### Basic Operations * Generate an MMGen wallet @@ -79,7 +79,7 @@ wish to edit at some point to customize MMGen to your needs. These settings include the maximum transaction fee; the user name, password and hostname used for communicating with bitcoind; and a number of others. -#### Testnet and regtest mode +#### Bob and Alice regtest mode If you just want to quickly try out MMGen, it's possible to perform all wallet generation, wallet format conversion, address and key generation, and address @@ -89,67 +89,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 coins to play with. To avoid risking real funds, it's *highly recommended* to -practice transaction operations on [testnet][04] or in [regtest mode][05] until -you feel confident you know what you're doing. +practice transaction operations using **Bob and Alice regtest mode** 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 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. With testnet you can safely practice all the -operations below, including the offline ones, on an online computer. - -**Regtest mode** is a more convenient alternative to testnet that requires no -Internet connection and no blockchain sync time. In regtest mode, bitcoind -creates a private blockchain on which you can mine, send and receive -transactions. MMGen commands support regtest mode with the `--regtest=1` option -or the `regtest` option in `mmgen.cfg`. The following is a brief guide to get -you started with regtest mode: - -Start the bitcoin daemon, generate 432 blocks to activate Segwit on the regtest -chain and stop: - - $ bitcoind -regtest -daemon - $ bitcoin-cli -regtest generate 432 - $ bitcoin-cli -regtest stop - -Move 'wallet.dat' out of harm's way (**important:** it's the 'wallet.dat' in the -'regtest' directory under your bitcoin data directory being referred to here, -**not** the one in your bitcoin data directory). Restart the daemon: - - $ bitcoind -regtest -daemon - -A new ‘wallet.dat’ will be created. This is your tracking wallet. Create an -MMGen wallet, generate some MMGen addresses and import them into the tracking -wallet as described below. Stop the daemon again: - - $ bitcoin-cli -regtest stop - -Move your tracking wallet (the new 'wallet.dat') out of harm's way and move the -original 'wallet.dat' back. Restart the daemon, send some funds to one of your -tracked addresses, mine a block and stop the daemon: - - $ bitcoind -regtest -daemon - $ bitcoin-cli -regtest sendtoaddress 100.00 - $ bitcoin-cli -regtest generate 1 - $ bitcoin-cli -regtest stop - -Replace the original 'wallet.dat' with your tracking wallet again, restart -bitcoind and list your tracked addresses: - - $ bitcoind -regtest -daemon - $ mmgen-tool --regtest=1 listaddresses - -Your address should now have a balance of 100 BTC. You may now practice creating -and sending transactions to yourself as described below. -After sending each transaction, you must mine a new block for the transaction to -confirm: - - $ bitcoin-cli -regtest generate 1 +A convenient frontend for bitcoind's regression test mode, MMGen's Bob and Alice +mode creates a private blockchain and a virtual network of two users who can +send bitcoins to each other. All of MMGen's functionality is available in this +mode, making it an ideal, risk-free way to acquaint yourself with the wallet's +features. Refer to [MMGen Quick Start with Regtest Mode][06] to get started. ### Basic Operations @@ -221,9 +168,14 @@ Now generate ten addresses with your just-created wallet: 10 1H7vVTk4ejUbQXw45I6g5qvPBSe9bsjDqh } -NOTE: As of version 0.9.2, MMGen supports Segwit. To generate Segwit addresses, -add `--type segwit` to the command line. Segwit address files are distinguished -from Legacy ones by the ‘-S’ in the filename: +Note that the address range ‘1-10’ specified on the command line is included in +the resulting filename. + +NOTE: MMGen supports Segwit addresses as of version 0.9.2 and compressed P2PKH +addresses as of version 0.9.3. To generate Segwit or compressed addresses, add +`--type=segwit` or `--type=compressed` to the command line. Segwit and +compressed address files are distinguished from Legacy ones by an added ‘-S’ and +‘-C’ in the filenames: $ mmgen-addrgen --type segwit 1-10 ... @@ -232,8 +184,12 @@ from Legacy ones by the ‘-S’ in the filename: 1 32GiSWo9zIQgkCmjAaLIrbPwXhKry2jHhj ... -Note that the address range ‘1-10’ specified on the command line is included in -the resulting filename. + $ mmgen-addrgen --type compressed 1-10 + ... + $ cat '89ABCDEF-C[1-10].addrs' + 89ABCDEF COMPRESSED { + 1 13jbRxWjswXtaDzLBJDboMcIe6nLohFb9M + ... To fund your MMGen wallet, first import the addresses into your tracking wallet and then spend some BTC into any of them. If you run out of addresses, generate @@ -306,10 +262,10 @@ through the network. To use it, you must save the keys corresponding to the addresses where the funds are stored in a separate file to use during signing.* Note that each address has a unique ID (the ‘MMGen ID’) consisting of its Seed -ID, its address type (‘L’ for Legacy, ‘S’ for Segwit), and its number (index). -Legacy and Segwit addresses may be imported into the same tracking wallet; -they're generated from different sub-seeds, so you needn't worry about key -reuse. +ID, its address type (‘L’ for Legacy, ‘S’ for Segwit and ‘C’ for Compressed), +and its number (index). Addresses of different types may be imported into the +same tracking wallet; since they're generated from different sub-seeds you +needn't worry about key reuse. Now that your addresses are being tracked, you may go ahead and send some BTC to them over the Bitcoin network. If you send 0.1, 0.2, 0.3 and 0.4 BTC @@ -343,12 +299,9 @@ Note that 'mmgen-txcreate' accepts either MMGen IDs or Bitcoin addresses as arguments. IMPORTANT NOTE: For the time being, Legacy addresses are the default, so -address ‘89ABCDEF:5’ is equivalent to ‘89ABCDEF:L:5’. In the future, users will -have the option to make Segwit addresses the default, so that ‘89ABCDEF:5’ will -be equivalent to ‘89ABCDEF:S:5’ and the ‘L’ will be required to specify a legacy -address. This may seem confusing, but it was the best possible way to make -the MMGen ID backwards-compatible for now while allowing users the option of -a non-compatible upgrade in the future. +address ‘89ABCDEF:5’ is equivalent to ‘89ABCDEF:L:5’. In the future, users may +be given the option to make Segwit (for BTC) or Compressed (for BCH) addresses +the default. To send 0.1 BTC to each of your addresses 89ABCDEF:6 and 89ABCDEF:7 and return the change to 89ABCDEF:8, you’d do this: @@ -884,3 +837,4 @@ them in turn until you get a confirmation: [03]: Recovering-Keys-Without-MMGen [04]: https://bitcoin.org/en/developer-examples#testnet [05]: https://bitcoin.org/en/developer-examples#regtest-mode +[06]: https://github.com/mmgen/mmgen/wiki/MMGen-Quick-Start-with-Regtest-Mode diff --git a/Home.md b/Home.md index d3eaa3f..4fbec72 100644 --- a/Home.md +++ b/Home.md @@ -9,6 +9,8 @@ > #### [Getting Started with MMGen](Getting-Started-with-MMGen) +> #### [MMGen Quick Start with Regtest Mode](MMGen-Quick-Start-with-Regtest-Mode) + > #### [MMGen command help](MMGen-command-help) > #### [Recovering your keys without the MMGen software](Recovering-Keys-Without-MMGen) diff --git a/MMGen-Quick-Start-with-Regtest-Mode.md b/MMGen-Quick-Start-with-Regtest-Mode.md new file mode 100644 index 0000000..06bc4f3 --- /dev/null +++ b/MMGen-Quick-Start-with-Regtest-Mode.md @@ -0,0 +1,160 @@ +MMGen's regtest mode, also known as Bob and Alice mode, provides a convenient +front-end for bitcoind's regression test mode. It creates a private blockchain +and a virtual network of two users who can perform all MMGen operations, +including sending bitcoins to each other. + +To transact as Bob or Alice, just add the '--bob' or '--alice' option to any +MMGen command. MMGen will start and stop the Bitcoin daemon automatically as +required. All of MMGen's functionality is available in this mode, making it an +ideal, risk-free way to acquaint yourself with the MMGen wallet's features and +transacting on the Bitcoin blockchain in general. + +This tutorial provides a quick, hands-on introduction. + +1. Create the blockchain and Bob and Alice's tracking wallets: + + $ mmgen-regtest setup + +2. Generate Bob's MMGen wallet: + + $ mmgen-walletgen --bob + ... + Make this wallet your default and move it to the data directory? (Y/n): y + +3. Generate three type 'C' (compressed) addresses with Bob's MMGen wallet: + + $ mmgen-addrgen --bob --type=compressed 1-3 + ... + Addresses written to file '1163DDF1-C[1-3].addrs' + # 1163DDF1 is Bob's Seed ID; since it's generated randomly, your Bob's will be different + +4. Import the addresses into Bob's tracking wallet: + + $ mmgen-addrimport --bob 1163DDF1-C[1-3].addrs + ... + Type uppercase 'YES' to confirm: YES + +5. List the addresses in Bob's tracking wallet. You should see the addresses +you just imported: + + $ mmgen-tool --bob listaddresses showempty=1 + MMGenID ADDRESS COMMENT BALANCE + 1163DDF1:C:1 mw42oJ94yRA6ZUNSzmMpjZDR74JNyvqzzZ - 0 + 1163DDF1:C:2 n1oszhfAyRrHi7qJupyzaWXTcpMQGsGJEf - 0 + 1163DDF1:C:3 mhYYHM7renPpNi8SUj5yeEZ54eAUJ5HyQ1 - 0 + +6. Fund one of the addresses (let's choose the first one) with some BTC: + + $ mmgen-regtest send mw42oJ94yRA6ZUNSzmMpjZDR74JNyvqzzZ 500 + +7. Make sure the funds arrived: + + $ mmgen-tool --bob listaddresses showempty=1 + MMGenID ADDRESS COMMENT BALANCE + 1163DDF1:C:1 mw42oJ94yRA6ZUNSzmMpjZDR74JNyvqzzZ - 500 + 1163DDF1:C:2 n1oszhfAyRrHi7qJupyzaWXTcpMQGsGJEf - 0 + 1163DDF1:C:3 mhYYHM7renPpNi8SUj5yeEZ54eAUJ5HyQ1 - 0 + +8. You can view Bob's total balance this way too: + + $ mmgen-tool --bob getbalance + +9. Generate Alice's MMGen wallet: + + $ mmgen-walletgen --alice + ... + Make this wallet your default and move it to the data directory? (Y/n): y + +10. Generate three type 'S' (segwit) addresses with Alice's MMGen wallet: + + $ mmgen-addrgen --alice --type=segwit 1-3 + ... + Addresses written to file '9304C211-S[1-3].addrs' + +11. Repeat steps 4-7 for Alice by substituting '--bob' for '--alice'. Don't +forget to adjust the address filename and send address as well. The result of +step 7 should look something like this: + + MMGenID ADDRESS COMMENT BALANCE + 9304C211:S:1 2N3HhxasbRvrJyHg72JNVCCPi9EUGrEbFnu - 500 + 9304C211:S:2 2N8w8qTupvd9L9wLFbrn6UhdfF1gadDAmFD - 0 + 9304C211:S:3 2NF4y3y4CEjQCcssjX2BDLHT88XHn8z53JS - 0 + TOTAL: 500 BTC + +12. Split Alice's funds, sending 200 BTC to address S:2 and the change to S:3. +Specify a fee of 20 satoshis/byte and '--quiet' for less noisy output: + + $ mmgen-txdo --alice --tx-fee=20s --quiet 9304C211:S:2,300 9304C211:S:3 + ... + Type uppercase 'YES' to confirm: YES + Transaction sent: 78ca853816b55527b42ca8784c887a5f482c752522f914d2f17d6afcd8a3b076 + +13. Check the mempool for the transaction: + + $ mmgen-regtest show_mempool + ['78ca853816b55527b42ca8784c887a5f482c752522f914d2f17d6afcd8a3b076'] + +14. Mine a block: + + $ mmgen-regtest generate + +15. Check the mempool again: + + $ mmgen-regtest show_mempool + [] + +16. List Alice's addresses. Note that Alice has lost a bit to transaction fees: + + $ mmgen-tool --alice listaddresses showempty=1 + MMGenID ADDRESS COMMENT BALANCE + 9304C211:S:1 2N3HhxasbRvrJyHg72JNVCCPi9EUGrEbFnu - 0 + 9304C211:S:2 2N8w8qTupvd9L9wLFbrn6UhdfF1gadDAmFD - 300 + 9304C211:S:3 2NF4y3y4CEjQCcssjX2BDLHT88XHn8z53JS - 199.999967 + TOTAL: 499.999967 BTC + +17. Have Alice send 10 BTC to Bob's C:2 address, with the change back to her S:1 +address. This time Alice specifies an absolute fee in BTC. + + $ mmgen-txdo --alice --tx-fee=0.0001 --quiet 9304C211:S:1 n1oszhfAyRrHi7qJupyzaWXTcpMQGsGJEf,10 + ... + Enter a range or space-separated list of outputs to spend: 1 + ... + + Note that Alice is reusing address S:1 here, and address reuse is generally a + bad idea. You'd be better off generating and importing some new addresses for + Alice by repeating steps 3 and 4 with a different address range. I'll leave + that to you as an exercise. + +18. Mine a block: + + $ mmgen-regtest generate + +19. List Alice's addresses, omitting the empty ones: + + $ mmgen-tool --alice listaddresses + MMGenID ADDRESS COMMENT BALANCE + 9304C211:S:1 2N3HhxasbRvrJyHg72JNVCCPi9EUGrEbFnu - 189.999867 + 9304C211:S:2 2N8w8qTupvd9L9wLFbrn6UhdfF1gadDAmFD - 300 + TOTAL: 489.999867 BTC + +19. List Bob's addresses: + + $ mmgen-tool --bob listaddresses + MMGenID ADDRESS COMMENT BALANCE + 1163DDF1:C:1 mw42oJ94yRA6ZUNSzmMpjZDR74JNyvqzzZ - 500 + 1163DDF1:C:2 n1oszhfAyRrHi7qJupyzaWXTcpMQGsGJEf - 10 + TOTAL: 510 BTC + +20. Add a label to Bob's tracking wallet: + + $ mmgen-tool --bob add_label 1163DDF1:C:2 'From Alice' + +21. List Bob's addresses: + + $ mmgen-tool --bob listaddresses + MMGenID ADDRESS COMMENT BALANCE + 1163DDF1:C:1 mw42oJ94yRA6ZUNSzmMpjZDR74JNyvqzzZ - 500 + 1163DDF1:C:2 n1oszhfAyRrHi7qJupyzaWXTcpMQGsGJEf From Alice 10 + TOTAL: 510 BTC + +[q]: MMGen-Quick-Start-with-Regtest-Mode diff --git a/Recovering-Keys-Without-MMGen.md b/Recovering-Keys-Without-MMGen.md index 4488771..ffae241 100644 --- a/Recovering-Keys-Without-MMGen.md +++ b/Recovering-Keys-Without-MMGen.md @@ -84,8 +84,8 @@ Linux or other Unix-like system. $ echo -n segwit | openssl dgst -r -sha256 -mac hmac -macopt hexkey:456d7f5f1c4bfe3bc916b87560ae6a3e | xxd -r -p > cooked-seed.bin -> If your addresses are of the compressed ('C') type, just use string 'compressed' -> instead of 'segwit' as the 'echo' command's argument. +> If your addresses are of the compressed ('C') type, just use the string +> 'compressed' instead of 'segwit' as the 'echo' command's argument. > Now add the ten rounds of sha256: @@ -137,7 +137,7 @@ Or, in the Segwit case: 3LpkKqtGkcCukRrgEFWyCajSApioiEWeTw # matches FE3C6545:S:1 above But since we're trying to do this without the MMGen software, we need to find -some other way to convert our hex key to a WIF key. We could use one of many +some other way to do the hex-to-WIF conversion. We could use one of many key-manipulation tools available on the Internet, such as [this one][01], or [this one][02]. Or we can do it ourselves: that will be covered in the next section. @@ -202,13 +202,11 @@ with lowercase 'l', he dropped those characters, leaving the following 58: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz With '0' gone, '1' now represents decimal zero, '2' represents decimal one, and -so forth all the way up to 'z', representing decimal fifty-seven. So the -familiar '1' at the beginning of most Bitcoin addresses is actually just a -prepended zero! +so forth all the way up to 'z', representing decimal fifty-seven. -Now all that remains is to convert our hexadecimal key to decimal and then to -Base 58 using this alphabet. This can be done in just four lines of code you can -try out at the Python prompt: +Now all that remains is to convert our hexadecimal key to decimal and then Base +58 using this alphabet. This can be done in just four lines of code you can try +out at the Python prompt: # uncompressed example: $ python @@ -225,10 +223,10 @@ try out at the Python prompt: L3R8Fn21PsY3PWgT8BMggFwXswA2EZntwEGFS5mfDJpSiLq29a9F # matches key for FE3C6545:S:1 above Explanation: the variable 'b58a' holds the Base 58 alphabet; 'num' holds the key -converted from hexidecimal to decimal using Python's `int()` function; the third -line is the base conversion routine proper; and the last line formats the result -by reversing it, converting it to a string and stripping off the leading zeroes -('1's). +in decimal, converted from hexidecimal by Python's `int()` function; the third +line does the base-58 conversion; and the last line formats the result by +reversing the order of the digits, converting it to a string and stripping off +the leading zeroes ('1's). Programmers unfamiliar with Python might find the following base conversion code clearer: @@ -270,7 +268,7 @@ If a number has more than one digit, its value is the sum of its digits multiplied by increasing powers of ten, beginning with the rightmost, least significant digit (the “ones column”). -Thus the number 1234, for example, can be summed as follows: +Thus the number 1234, for example, can be represented as follows: 4 x 1 + 3 x 10 + @@ -284,8 +282,8 @@ Or in exponential notation: 2 x 10^2 + 1 x 10^3 -An MMGen seed mnemonic is a number too, only the “digits” it's made up come from -an alphabetically sorted series of 1626 words, the [Electrum wordlist][03], +An MMGen seed mnemonic is a number too, only the “digits” it's comprised of come +from an alphabetically sorted series of 1626 words, the [Electrum wordlist][03], which begins like this: able (0), about (1), above (2), abuse (3), accept (4) ... @@ -296,8 +294,8 @@ and ends like this: (Type `mmgen-tool mn_printlist` to see the full list) -The words of the Electrum wordlist thus comprise a base-1626 numbering system, -fully analogous to the digits of our familiar base-10 system. +The words of the Electrum wordlist thus make up a base-1626 numbering system, +just like the ten digits that make up our familiar base-10 system. Here's the mnemonic of our seed (FE3C6545): @@ -335,7 +333,8 @@ the results: 562 x 1626^10 + 439 x 1626^11 -With a bit of Python code we can automate the process: +While we could do this with pencil and paper, a few lines of Python code will +make life much easier: $ python >>> sum = power = 0 @@ -343,9 +342,9 @@ With a bit of Python code we can automate the process: >>> sum += word * 1626 ** power >>> power += 1 >>> print sum - 92285275468192044354531703963345906238 # the value in decimal + 92285275468192044354531703963345906238 # the result in decimal >>> print '{:x}'.format(sum) - 456d7f5f1c4bfe3bc916b87560ae6a3e # the value in hexadecimal: matches our original hex seed above + 456d7f5f1c4bfe3bc916b87560ae6a3e # the result in hexadecimal: matches our original hex seed above In case you're wondering why 1626 was chosen as the base: 1626 is just large enough to allow a 128-bit seed to be represented by twelve words. This can also