modified: Getting-Started-with-MMGen.md

modified:   Home.md
	new file:   MMGen-Quick-Start-with-Regtest-Mode.md
	modified:   Recovering-Keys-Without-MMGen.md
philemon 2017-09-30 14:19:34 +03:00
commit baaeb37cf2
Signed by untrusted user who does not match committer: mmgen
GPG key ID: 62DBE9E5212F05BE
4 changed files with 213 additions and 98 deletions

@ -4,7 +4,7 @@
* <a href='#a_bb'>Before you begin</a>
* <a href='#a_iv'>Invocation</a>
* <a href='#a_cf'>Configuration file</a>
* <a href='#a_ts'>Testnet and regtest mode</a>
* <a href='#a_ts'>Bob and Alice regtest mode</a>
#### <a href='#a_bo'>Basic Operations</a>
* <a href='#a_gw'>Generate an MMGen wallet</a>
@ -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.
#### <a name='a_ts'>Testnet and regtest mode</a>
#### <a name='a_ts'>Bob and Alice regtest mode</a>
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 <a href='#a_bo'>as described below</a>. 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 <a tracked address> 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 <a href='#a_ct'>as described below</a>.
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.
### <a name='a_bo'>Basic Operations</a>
@ -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

@ -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)

@ -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

@ -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