deleted: README.md
This commit is contained in:
philemon
parent
416f1328ce
commit
ed4549bb2d
1 changed files with 0 additions and 436 deletions
436
README.md
436
README.md
|
|
@ -1,436 +0,0 @@
|
|||
MMGen = Multi-Mode GENerator
|
||||
============================
|
||||
|
||||
a Bitcoin cold storage solution for the command line
|
||||
----------------------------------------------------
|
||||
|
||||
### Description
|
||||
|
||||
MMGen is implemented as a suite of lightweight Python command-line
|
||||
scripts that require only a bare minimum of system resources.
|
||||
The scripts function in tandem with a modified
|
||||
bitcoind running on an online computer and a standard
|
||||
bitcoind running offline to provide a robust solution for securely
|
||||
storing, tracking, spending and receiving your Bitcoins. "Non-MMGen"
|
||||
addresses can be tracked and spent as well, creating an easy migration
|
||||
path from other wallets.
|
||||
|
||||
The online bitcoin daemon is modified to support watch-only addresses,
|
||||
a feature soon to be included in the mainline Satoshi build.
|
||||
In the meantime, instructions are provided below for compiling the
|
||||
watch-only bitcoind, which under Linux is surprisingly easy.
|
||||
|
||||
MMGen uses the reference Satoshi daemon, rather than less-reliable
|
||||
third-party software, to do all the "heavy lifting" of tracking and
|
||||
signing transactions.
|
||||
And unlike other online/offline wallet solutions, the MMGen system is
|
||||
completely self-contained, relying on no external server to do its
|
||||
work; no third party will know which addresses you're tracking.
|
||||
|
||||
Like all deterministic wallets, MMGen can generate a virtually
|
||||
unlimited number of address/key pairs from a single seed. Your wallet
|
||||
never changes, so you need back it up only once.
|
||||
Transactions are signed offline: your private keys never touch an
|
||||
online computer.
|
||||
|
||||
At the heart of the MMGen system is the seed, the "master key"
|
||||
providing access to all your Bitcoins. The seed can be stored in four
|
||||
different ways:
|
||||
|
||||
> 1) as a wallet with a password
|
||||
> encrypted using the crack-resistant scrypt hash function.
|
||||
> Scrypt's parameters can be adjusted on the command line, making your
|
||||
> wallet's password virtually impossible to crack should it fall into the wrong
|
||||
> hands. The wallet is a tiny text file
|
||||
> suitable for printing or even writing out by hand;
|
||||
|
||||
> 2) as a seed file: a one-line base-58 representation of your
|
||||
> unencrypted seed plus a checksum;
|
||||
|
||||
> 3) as an Electrum-like mnemonic of 12, 18 or 24 words; or
|
||||
|
||||
> 4) as a brainwallet password (this option is recommended for expert
|
||||
> users only).
|
||||
|
||||
The best part is that all these methods can be combined. If you
|
||||
forget your mnemonic, for example, you can regenerate it and your keys
|
||||
from the stored wallet or seed file. Correspondingly, a lost wallet can
|
||||
be regenerated from the mnemonic or seed or a lost seed from the wallet or
|
||||
mnemonic.
|
||||
|
||||
|
||||
### Download/Install
|
||||
|
||||
> #### [Install on Microsoft Windows](doc/MMGenInstallMSWin.md)
|
||||
|
||||
> #### [Install on Debian/Ubuntu Linux](doc/MMGenInstallLinux.md)
|
||||
|
||||
|
||||
### Using MMGen
|
||||
|
||||
#### Generate a wallet (offline computer):
|
||||
|
||||
On your offline computer, generate a wallet with a random seed:
|
||||
|
||||
$ mmgen-walletgen
|
||||
...
|
||||
Wallet saved to file '89ABCDEF-76543210[256,3].mmdat'
|
||||
|
||||
"89ABCDEF" is the Seed ID; "76543210" is the Key ID. These are
|
||||
randomly generated, so your IDs will of course be different than the
|
||||
fictitious ones used here.
|
||||
|
||||
The Seed ID never changes and will be used to identify all keys/addresses
|
||||
generated by this seed. 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 values
|
||||
are configurable: type `mmgen-walletgen --help` for details.
|
||||
|
||||
#### Generate addresses (offline computer):
|
||||
|
||||
Now generate ten addresses with your just-created wallet:
|
||||
|
||||
$ mmgen-addrgen 89ABCDEF-76543210[256,3].mmdat 1-10
|
||||
...
|
||||
Address data saved to file '89ABCDEF[1-10].addrs'
|
||||
$ cat '89ABCDEF[1-10].addrs'
|
||||
89ABCDEF {
|
||||
1 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE
|
||||
2 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc
|
||||
3 1HgYCsfqYzIg7LVVfDTp7gYJocJEiDAy6N
|
||||
4 14Tu3z1tiexXDonNsFIkvzqutE5E3pTK8s
|
||||
5 1PeI55vtp2bX2uKDkAAR2c6ekHNYe4Hcq7
|
||||
6 1FEqfEsSILwXPfMvVvVuUovzTaaST62Mnf
|
||||
7 1LTTzuhMqPLwQ4IGCwwugny6ZMtUQJSJ1
|
||||
8 1F9495H8EJLb54wirgZkVgI47SP7M2RQWv
|
||||
9 1JbrCyt7BdxRE9GX1N7GiEct8UnIjPmpYd
|
||||
10 1H7vVTk4ejUbQXw45I6g5qvPBSe9bsjDqh
|
||||
}
|
||||
|
||||
Note that the address range, "1-10", is reflected in the resulting filename.
|
||||
MMGen addresses are identified by their seed ID plus number, separated
|
||||
by a colon. In this example, "89ABCDEF:1" is the MMGen equivalent
|
||||
of Bitcoin address 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE, "89ABCDEF:2"
|
||||
the equivalent of 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc, and so forth.
|
||||
|
||||
Let's say you've decided to transfer some BTC into the first four
|
||||
addresses above. Your first step, then, will be to import these
|
||||
addresses into the tracking wallet on your online machine.
|
||||
You've chosen to provide the addresses with the labels "Donations",
|
||||
"Storage 1", "Storage 2" and "Storage 3" for convenient identification.
|
||||
|
||||
Make a copy of the file:
|
||||
|
||||
$ cp '89ABCDEF[1-10].addrs' my_addrs_for_import
|
||||
|
||||
and edit the copy using your favorite text editor. The result will
|
||||
look something like this:
|
||||
|
||||
$ cat my_addrs_for_import
|
||||
89ABCDEF {
|
||||
1 16bNmyYISiptuvJG3X7MPwiiS4HYvD7ksE Donations
|
||||
2 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc Storage 1
|
||||
3 1HgYCsfqYzIg7LVVfDTp7gYJocJEiDAy6N Storage 2
|
||||
4 14Tu3z1tiexXDonNsFIkvzqutE5E3pTK8s Storage 3
|
||||
}
|
||||
|
||||
Note that rows in the list may be arranged in any order; addresses
|
||||
need not be consecutive.
|
||||
|
||||
Copy this file onto a USB stick and transfer it to your online
|
||||
computer.
|
||||
|
||||
#### Import addresses (online computer):
|
||||
|
||||
On your online computer, start bitcoind and import the addresses into
|
||||
the tracking wallet:
|
||||
|
||||
$ mmgen-addrimport my_addrs_for_import
|
||||
|
||||
These addresses are now being "tracked". Any BTC transferred
|
||||
to them will show up in our listing of unspent outputs.
|
||||
|
||||
You'll want to track your existing addresses with balances too.
|
||||
Make a plain list of these addresses, one address per line, and import
|
||||
the list into the tracking wallet using the same command
|
||||
with the `'-l'` option:
|
||||
|
||||
$ mmgen-addrimport -l my_existing_addrs_with_balances
|
||||
|
||||
Since the importing process is slow, you may want to do it in stages,
|
||||
a few addresses at a time.
|
||||
|
||||
For your convenience, comments beginning with a '#' symbol may be
|
||||
included in address lists.
|
||||
Continue in this fashion until you've imported all addresses with
|
||||
balances into your tracking wallet.
|
||||
|
||||
#### Create a transaction (online computer):
|
||||
|
||||
Now that your existing addresses are imported, you're ready to create
|
||||
a test transaction using the `mmgen-txcreate` command. Note that
|
||||
transactions are harmless until they're signed and broadcast to the
|
||||
network, so feel free to experiment with different transactions
|
||||
using different combinations of inputs and outputs.
|
||||
|
||||
First of all, you'll probably want to examine your balances:
|
||||
|
||||
$ mmgen-txcreate -i
|
||||
|
||||
A list of all your unspent outputs will appear,
|
||||
along with a menu allowing you to sort the outputs by four
|
||||
criteria: transaction ID, address, amount and transaction age.
|
||||
Your overall balance in BTC appears at the top of the screen. The
|
||||
list may be viewed in a pager or printed to file. If you have
|
||||
ten unspent outputs, your display will look something like this:
|
||||
|
||||
UNSPENT OUTPUTS (sort order: reverse amount) Total BTC: 39.72
|
||||
Num TX id Vout Address Amount (BTC) Age(days)
|
||||
1) 04f97185... 2 1F93Znz8PI5Pnvv8ZAJsb74EzKpmRMLFbk 10 320
|
||||
2) dd900544... 1 194Fceqx86jqIWumphUmfVyFMjAAbMLcSE 9.9287435 7
|
||||
3) 7ec81a8f... 0 1FhIkRabPSZhhUsA6qvukmfK4T4PZLbC4M 7.26 17
|
||||
4) 64094b55... 0 16JSUJdGMbxUBEQatAR5sGE89tbSIsLHqg 3.15 140
|
||||
5) fd687c65... 1 1QKAtU66aUntCBx9m6TfEIf3gQuCNWCVDY 3.15 140
|
||||
6) 9a8f20e2... 1 1FMNDFz1yUywjJSprjvYY9t1yxkE8GGIwT 3.15 140
|
||||
7) 03a7c51a... 3 1svxnSdKVIcMs6qWYA7qLzA29orXbzXUm 1.6382466 54
|
||||
8) 9955f06c... 2 18nWPLQGUzI7X1Rcm4zmVV6Z3xhokdYx9G 1.2 27
|
||||
9) 8a4ab4f5... 0 13S9HNu7PQn1aJ4qILfhqRSakXwvSTnbwJ 0.23033 3
|
||||
10) 5bfe5621... 1 1FV1Lhs6Dnc9gMxjJTo6h4nTeIjJbQ1PgV 0.01 42
|
||||
|
||||
Sort options: [t]xid, [a]mount, a[d]dress, [A]ge, [r]everse, [M]mgen addr
|
||||
View options: [g]roup, show [m]mgen addr
|
||||
(Type 'q' to quit sorting, 'p' to print to file, 'v' to view in pager):
|
||||
|
||||
Now let's actually create a transaction. Let's say you've decided to
|
||||
gradually begin spending your 39.72 BTC balance into your shiny new
|
||||
MMGen wallet with seed ID 89ABCDEF.
|
||||
|
||||
Before doing anything else, you should back up your MMGen wallet in
|
||||
several places and possibly on several media too: paper, flash memory
|
||||
or CD-ROM, for example. Of course the wallet should have a
|
||||
passphrase. Otherwise, anyone who gains physical control of one of
|
||||
your backups can easily steal your coins.
|
||||
|
||||
Recall that there's no limit to the number of addresses you can
|
||||
generate with your seed. You've wisely determined that having many
|
||||
addresses with relatively small balances is a Good Idea.
|
||||
You've decided to begin by breaking up your
|
||||
address with the largest balance, 10 BTC, into three roughly equal parts,
|
||||
sending it to the addresses labeled "Storage 1", "Storage 2" and
|
||||
"Storage 3" (89ABCDEF:1, 89ABCDEF:2 and 89ABCDEF:3).
|
||||
|
||||
To refresh our memory, here are the three addresses in question:
|
||||
|
||||
89ABCDEF {
|
||||
2 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc Storage 1
|
||||
3 1HgYCsfqYzIg7LVVfDTp7gYJocJEiDAy6N Storage 2
|
||||
4 14Tu3z1tiexXDonNsFIkvzqutE5E3pTK8s Storage 3
|
||||
}
|
||||
|
||||
The following command will send 3.3 BTC to the first two addresses and
|
||||
the remainder of the transaction's inputs to the third, subtracting a
|
||||
default transaction fee of 0.001 BTC:
|
||||
|
||||
$ mmgen-txcreate 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc,3.3 1HgYCsfqYzIg7LVVfDTp7gYJocJEiDAy6N,3.3 14Tu3z1tiexXDonNsFIkvzqutE5E3pTK8s
|
||||
|
||||
The third address has the amount left out, making it a **change
|
||||
address**.
|
||||
MMGen will compute the change amount (3.399 BTC in this case) automatically.
|
||||
|
||||
Alternatively, and more conveniently, you can write the
|
||||
addresses in MMGen format:
|
||||
|
||||
$ mmgen-txcreate -a addrs 89ABCDEF:2,3.3 89ABCDEF:3,3.3 89ABCDEF:4
|
||||
|
||||
'addrs' is an MMGen address file containing the requested output
|
||||
addresses. Any unneeded addresses in the file will be ignored.
|
||||
|
||||
Now hit ENTER, choose the
|
||||
transaction's input from the list (10 BTC, address
|
||||
1F9495H8EJLb54wirgZkVgI47SP7M2RQWv, txid 04f97185...,2),
|
||||
and confirm.
|
||||
If all goes well, the command will exit with a message like this:
|
||||
|
||||
Transaction data saved to file 'tx_1EDCBA[6.6].raw'
|
||||
|
||||
Note that the transaction has a unique ID, and the non-change output
|
||||
amount, 6.6 BTC, is conveniently included in the filename.
|
||||
|
||||
#### Sign the transaction (offline computer):
|
||||
|
||||
Now copy the raw transaction you've just created to a USB stick and
|
||||
transfer it to your offline computer for signing. You need to find
|
||||
the key for your transaction's one input address,
|
||||
1F9495H8EJLb54wirgZkVgI47SP7M2RQWv. If the key in question is in a
|
||||
bitcoin 'wallet.dat', there's an included command that will
|
||||
conveniently extract the key for you:
|
||||
|
||||
$ mmgen-pywallet -k wallet.dat
|
||||
...
|
||||
wallet.dat secret keys saved to file wd_EDBC983A[102].keys
|
||||
|
||||
You've in fact extracted a list of all of the wallet's 102 keys here,
|
||||
but that's not a problem, as the unused keys will be ignored.
|
||||
Now go ahead and sign the transaction using this list of keys.
|
||||
|
||||
$ mmgen-txsign -k wd_EDBC983A[102].keys tx_1EDCBA[6.6].raw
|
||||
...
|
||||
Signed transaction saved to file tx_1EDCBA[6.6].sig
|
||||
|
||||
Note that mmgen-pywallet's output is just a flat list of keys.
|
||||
So if you have several Bitcoin wallets with balances, you can just
|
||||
dump all their keys and concatenate them into a single file which you
|
||||
can use to sign all your future transactions involving wallet.dat
|
||||
inputs:
|
||||
|
||||
$ mmgen-pywallet -k wallet1.dat
|
||||
$ mmgen-pywallet -k wallet2.dat
|
||||
$ mmgen-pywallet -k wallet3.dat
|
||||
$ cat wd_*.keys > all_keys
|
||||
|
||||
For transactions whose inputs are MMGen addresses, an MMGen
|
||||
seed source (i.e. wallet, mnemonic or seed file) is listed on the
|
||||
command line after the transaction file, and the required keys are
|
||||
automatically generated:
|
||||
|
||||
$ mmgen-txsign tx_9D2C3A[1.23].raw B73B58EA-125FB230[256,3].mmdat
|
||||
|
||||
Transactions may contain a mixture of MMGen and non-MMGen inputs as
|
||||
well as inputs with more than one MMGen seed ID. Just provide a seed
|
||||
source for each seed ID on the command line.
|
||||
|
||||
Eventually, when you've placed all your BTC under MMGen control,
|
||||
you'll never have to deal with keys again. MMGen just generates them
|
||||
on the fly as the need arises.
|
||||
|
||||
#### Send the transaction (online computer):
|
||||
|
||||
Now we're ready for the final step: broadcasting the transaction to
|
||||
the network. Copy the \*.sig file to your online computer, start
|
||||
bitcoind, if it's not running, and execute the command
|
||||
|
||||
$ mmgen-txsend tx_1EDCBA[6.6].sig
|
||||
|
||||
Like all mmgen commands, `mmgen-txsend` is interactive, so you'll be
|
||||
asked for confirmation before the transaction is actually sent.
|
||||
|
||||
Once the transaction's confirmed by the network, your three new MMGen
|
||||
addresses will appear on the listing of `mmgen-txcreate -i`. Type
|
||||
'm' at the menu and they'll be displayed in MMGen format.
|
||||
|
||||
Congratulations! You've performed your first MMGen transaction.
|
||||
|
||||
### Additional Features
|
||||
|
||||
#### Using the mnemonic and seed features:
|
||||
|
||||
Continuing our example above, generate a mnemonic from the wallet:
|
||||
|
||||
$ mmgen-walletchk -m '89ABCDEF-76543210[256,3].mmdat'
|
||||
...
|
||||
Mnemonic data saved to file '89ABCDEF.mmwords'
|
||||
|
||||
$ cat 89ABCDEF.mmwords
|
||||
pleasure tumble spider laughter many stumble secret bother
|
||||
after search 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 a these seed lengths
|
||||
using the `'-l'` option to `mmgen-walletgen`.
|
||||
|
||||
Though some consider 128 bits of entropy to provide adequate security
|
||||
for the foreseeable future, you should stick to the default 256-bit
|
||||
seed length if you're not planning to use the mnemonic feature.
|
||||
|
||||
NOTE: MMGen mnemonics are generated from the Electrum wordlist, only
|
||||
using ordinary base conversion instead of Electrum's more complicated
|
||||
algorithm.
|
||||
|
||||
Generate addresses 1-11 using the mnemonic instead of the wallet:
|
||||
|
||||
$ mmgen-addrgen 89ABCDEF.mmwords 1-11
|
||||
...
|
||||
Address data saved to file '89ABCDEF[1-11].addrs'
|
||||
|
||||
Compare the first ten addresses with those earlier generated by the
|
||||
wallet. You'll see they're the same.
|
||||
|
||||
Recover a lost wallet using the mnemonic:
|
||||
|
||||
$ mmgen-walletgen 89ABCDEF.mmwords
|
||||
...
|
||||
Wallet saved to file '89ABCDEF-01234567[256,3].mmdat'
|
||||
|
||||
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 listed on the command
|
||||
line the same way as mnemonic files are.
|
||||
|
||||
A seed file for a 256-bit seed looks like this:
|
||||
|
||||
$ cat 8B7392ED.mmseed
|
||||
f4c84b C5ZT wWpT Jsoi wRVw 2dm9 Aftd WLb8 FggQ eC8h Szjd da9L
|
||||
|
||||
And for a 128-bit seed:
|
||||
|
||||
$ cat 8E0DFB78.mmseed
|
||||
0fe02f XnyC NfPH piuW dQ2d nM47 VU
|
||||
|
||||
As you can see, the latter is short enough to practically be memorized.
|
||||
From the unix command line,
|
||||
you can test your memory using the seed's checksum ('0fe02f' in this example)
|
||||
as follows:
|
||||
|
||||
$ echo -n XnyCNfPHpiuWdQ2dnM47VU | sha256sum | cut -c 1-6
|
||||
0fe02f
|
||||
|
||||
#### Mnemonics and seeds — additional information:
|
||||
|
||||
With the `'-m'` or `'-s'` option,
|
||||
MMGen commands that take mnemonic and seed data may receive the data
|
||||
from a prompt instead of a file.
|
||||
|
||||
MMGen commands that produce mnemonic and seed data may be forced to
|
||||
print it to standard output instead of file with the `'-S'` option.
|
||||
This feature was intentionally made optional to safeguard against
|
||||
looking-over-the-shoulder, Van Eyck phreaking and other side-channel
|
||||
attacks. MMGen commands never print private data to the screen
|
||||
unless explicitly asked to.
|
||||
|
||||
The output file of any MMGen command may be written to a directory of
|
||||
your choice using the `'-d'` option. For example, on a Linux system you
|
||||
could use `'-d /dev/shm'` to write key and seed data to volatile memory
|
||||
instead of disk.
|
||||
This also has obvious security benefits, ensuring that no sensitive data
|
||||
remains on disk after your computer's been powered down.
|
||||
|
||||
### Test suite:
|
||||
|
||||
To see what tests are available, run the scripts in the 'tests'
|
||||
directory with no arguments. You might find the following tests to be
|
||||
of interest:
|
||||
|
||||
> Compare 10 addresses generated by 'keyconv' with mmgen's
|
||||
> internally-generated ones:
|
||||
>> `tests/bitcoin.py keyconv_compare_randloop 10`
|
||||
|
||||
> Convert a string to base 58 and back:
|
||||
>> `tests/bitcoin.py strtob58 'a string'`
|
||||
|
||||
> Convert a hex number to base 58 and back:
|
||||
>> `tests/bitcoin.py hextob58 deadbeef`
|
||||
|
||||
> Perform 1000 hex -> base58 -> hex conversions, comparing results stringwise:
|
||||
>> `tests/bitcoin.py hextob58_pad_randloop 1000`
|
||||
|
||||
> Generate a 12-word mnemonic from a random 128-bit seed:
|
||||
>> `tests/mnemonic.py random128`
|
||||
|
||||
> or an 18-word mnemonic from a random 192-bit seed:
|
||||
>> `tests/mnemonic.py random192`
|
||||
|
||||
> or a 24-word mnemonic from a random 256-bit seed:
|
||||
>> `tests/mnemonic.py random256`
|
||||
Loading…
Add table
Add a link
Reference in a new issue