2016-07-27 11:26:11 +03:00
|
|
|
# MMGen = Multi-Mode GENerator
|
|
|
|
|
|
2020-02-22 19:54:03 +00:00
|
|
|
##### An online/offline cryptocurrency wallet for the command line
|
2014-04-03 13:51:05 +04:00
|
|
|
|
|
|
|
|
### Description
|
|
|
|
|
|
2017-12-18 20:19:01 +03:00
|
|
|
MMGen is a wallet and cold storage solution for Bitcoin (and selected altcoins)
|
|
|
|
|
implemented as a suite of lightweight Python scripts. The scripts work in
|
2019-06-10 09:17:05 +00:00
|
|
|
tandem with a reference Bitcoin or altcoin daemon running on both online and
|
|
|
|
|
offline computers to provide a robust solution for securely storing, tracking,
|
|
|
|
|
sending and receiving your crypto assets.
|
|
|
|
|
|
|
|
|
|
The online computer is used for tracking balances and creating and sending
|
2020-02-22 19:54:03 +00:00
|
|
|
transactions, while the offline machine (typically an air-gapped, low-power
|
2019-06-10 09:17:05 +00:00
|
|
|
device such as a Raspberry Pi) takes care of wallet creation, address generation
|
|
|
|
|
and transaction signing. All operations involving secret data are handled
|
|
|
|
|
offline: **your seed and private keys never come into contact with a
|
|
|
|
|
network-connected device.**
|
|
|
|
|
|
|
|
|
|
MMGen is designed for reliability by having the reference Bitcoin or altcoin
|
|
|
|
|
daemon, rather than less-tested third-party software, do all the “heavy lifting”
|
|
|
|
|
of tracking and signing transactions. It’s also designed with privacy in mind:
|
|
|
|
|
unlike some other online/offline wallets, MMGen is a completely self-contained
|
|
|
|
|
system that makes **no connections to the Internet** apart from the coin network
|
|
|
|
|
itself: no information about which addresses you’re tracking is ever leaked to
|
|
|
|
|
the outside world.
|
2014-04-03 13:51:05 +04:00
|
|
|
|
|
|
|
|
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
|
2017-12-18 20:19:01 +03:00
|
|
|
back it up only once.
|
2014-04-03 13:51:05 +04:00
|
|
|
|
2016-07-27 11:26:11 +03:00
|
|
|
At the heart of the MMGen system is the seed, the “master key” providing access
|
2020-02-22 19:54:03 +00:00
|
|
|
to all your crypto assets. The seed can be stored in many different formats:
|
|
|
|
|
as a password-encrypted wallet (the default), as a one-line base58 or
|
2020-02-25 19:03:47 +00:00
|
|
|
hexadecimal seed file, as formatted “dieroll base6” data, as an Electrum-based
|
|
|
|
|
or BIP39 mnemonic seed phrase, as a brainwallet passphrase, or as “incognito
|
|
|
|
|
data” hideable within random data in a file or block device. Conversion between
|
|
|
|
|
all formats is supported.
|
2015-01-04 11:14:11 +03:00
|
|
|
|
2019-03-08 09:06:45 +00:00
|
|
|
***mmgen-txcreate running in a terminal window***
|
|
|
|
|
![mmgen-txcreate running in a terminal window][9]
|
|
|
|
|
|
|
|
|
|
#### Simplified key derivation and seed-phrase generation
|
|
|
|
|
|
|
|
|
|
To deterministically derive its keys, MMGen uses a non-hierarchical scheme
|
2019-06-10 09:17:05 +00:00
|
|
|
differing from the BIP32 protocol on which most of today’s popular wallets are
|
|
|
|
|
based. One advantage of this simple, hash-based scheme is that you can easily
|
|
|
|
|
[recover your private keys from your seed without the MMGen program itself][K]
|
|
|
|
|
using standard command-line utilities.
|
2019-03-08 09:06:45 +00:00
|
|
|
|
|
|
|
|
MMGen also differs from most cryptocurrency wallets today in its use of the
|
|
|
|
|
original 1626-word [Electrum wordlist][ew] for mnemonic seed phrases. Seed
|
2019-06-10 09:17:05 +00:00
|
|
|
phrases are derived using ordinary base conversion, similarly allowing you to
|
|
|
|
|
regenerate your seed from your seed phrase without MMGen program itself, should
|
|
|
|
|
the need arise. An example of how to do this at the Python prompt is provided
|
2019-03-08 09:06:45 +00:00
|
|
|
[here.][S]
|
|
|
|
|
|
|
|
|
|
The original Electrum wordlist was derived from a [frequency list][fl] of words
|
|
|
|
|
found in contemporary English poetry. The high emotional impact of these words
|
|
|
|
|
makes seed phrases easy to memorize. Curiously, only 861 of them are shared by
|
|
|
|
|
the more prosaic 2048-word [BIP39 wordlist][bw] used in most wallets today.
|
2014-04-03 13:51:05 +04:00
|
|
|
|
2020-02-25 19:03:47 +00:00
|
|
|
Beginning with version 0.12.0, BIP39 mnemonic format is also supported, allowing
|
|
|
|
|
you to use MMGen as a master wallet for other wallets supporting that widespread
|
|
|
|
|
standard.
|
|
|
|
|
|
2019-06-10 09:17:05 +00:00
|
|
|
#### A brief overview of MMGen’s unique feature set:
|
|
|
|
|
|
|
|
|
|
- **[Full transaction and address tracking support][T]** for Bitcoin, [Bcash][bx],
|
|
|
|
|
[Litecoin][bx], [Ethereum][E], Ethereum Classic and [ERC20 tokens][E].
|
|
|
|
|
- **[Address generation support][ag]** for the above coins, plus [Monero][mx],
|
|
|
|
|
[Zcash][zx] (t and z addresses) and [144 Bitcoin-derived altcoins][ax].
|
2020-02-22 19:54:03 +00:00
|
|
|
- **Support for all Bitcoin address types** including Segwit-P2SH and Bech32.
|
2019-06-10 09:17:05 +00:00
|
|
|
- **Independent key derivation for each address type:** No two addresses ever
|
|
|
|
|
share the same private key. Certain wallets in wide use today regrettably
|
|
|
|
|
fail to guarantee this property, leading to the danger of inadvertent key
|
|
|
|
|
reuse.
|
|
|
|
|
- **Coin control:** You select the outputs your transaction will spend. An
|
|
|
|
|
essential requirement for maintaining anonymity.
|
|
|
|
|
- **[BIP69 transaction input and output ordering][69]** helps anonymize the
|
|
|
|
|
“signature” of your transactions.
|
|
|
|
|
- **[Full control over transaction fees][M]:** Fees are specified as absolute or
|
2020-03-12 16:38:02 +00:00
|
|
|
satoshi/byte amounts and can be adjusted interactively, letting you round fees
|
|
|
|
|
to improve anonymity. Network fee estimation (with selectable estimation
|
|
|
|
|
mode), [RBF][R] and [fee bumping][B] are supported.
|
2020-02-25 19:03:47 +00:00
|
|
|
- **Support for nine wallet formats:** three encrypted (native wallet,
|
|
|
|
|
brainwallet, incognito wallet) and six unencrypted (native mnemonic,
|
|
|
|
|
**BIP39,** mmseed, hexseed, plain hex, dieroll).
|
|
|
|
|
- Interactive **dieroll wallet** generation via `mmgen-walletconv -i dieroll`.
|
|
|
|
|
- Support for new-style **Monero mnemonics** in `mmgen-tool` and `mmgen-passgen`.
|
2019-06-10 09:17:05 +00:00
|
|
|
- **[Subwallets][U]:** Subwallets have many applications, the most notable being
|
2019-06-12 14:21:28 +00:00
|
|
|
online hot wallets, decoy wallets and travel wallets. MMGen subwallets are
|
|
|
|
|
functionally and externally identical to ordinary wallets, which provides a
|
|
|
|
|
key security benefit: only the user who generated the subwallet knows that it
|
|
|
|
|
is indeed a subwallet. Subwallets don’t need to be backed up, as they can
|
|
|
|
|
always be regenerated from their parent.
|
2020-02-25 19:03:47 +00:00
|
|
|
- **[XOR (N-of-N) seed splitting][O]** with shares exportable to all MMGen
|
|
|
|
|
wallet formats. The [master share][ms] feature allows you to create multiple
|
|
|
|
|
splits with a single master share.
|
2019-06-10 09:17:05 +00:00
|
|
|
- **[Transaction autosigning][X]:** This feature puts your offline signing
|
|
|
|
|
machine into “hands-off” mode, allowing you to transact directly from cold
|
2020-03-12 16:38:02 +00:00
|
|
|
storage securely and conveniently. Additional LED signaling support is
|
2019-12-07 12:20:21 +00:00
|
|
|
provided for Raspbian and Armbian platforms.
|
2019-06-10 09:17:05 +00:00
|
|
|
- **[Password generation][G]:** MMGen can be used to generate and manage your
|
2020-02-22 19:54:03 +00:00
|
|
|
online passwords. Password lists are identified by arbitrarily chosen strings
|
|
|
|
|
like “alice@github” or “bob@reddit”. Passwords of different lengths and
|
2020-02-25 19:03:47 +00:00
|
|
|
formats, including BIP39, are supported.
|
2019-06-10 09:17:05 +00:00
|
|
|
- **Selectable seed lengths** of 128, 192 or 256 bits. Subwallets may have
|
|
|
|
|
shorter seeds than their parent.
|
|
|
|
|
- **User-enhanced entropy:** All operations requiring random data will prompt
|
|
|
|
|
you for additional entropy from the keyboard. Keystroke timings are used in
|
|
|
|
|
addition to the characters typed.
|
|
|
|
|
- **Wallet-free operation:** All wallet operations can be performed directly
|
|
|
|
|
from your seed phrase at the prompt, allowing you to dispense with a
|
|
|
|
|
physically stored wallet entirely if you wish.
|
new mnemonic entry modes, new 'mn2hex_interactive' tool command
Auto-completion functionality for seed phrase entry provides real benefit to the
user, reducing the number of keystrokes required and permitting quick re-entry
of mistyped words. In addition, unifying the number of keystrokes among words
improves security against acoustic side-channel attacks. To this end, three
new interactive mnemonic entry modes are introduced by this patch.
Each entry mode is optimized for a particular wordlist. The “short” mode, for
example, takes advantage of the fact that each word in the Monero wordlist is
uniquely identifiable by its first three letters. For MMGen’s default Electrum
wordlist, which lacks this unique substring property, the “minimal” mode was
developed to reduce keystrokes to a minimum while retaining the option of
obfuscating entry with pad characters.
Users who prefer not to use auto-completion may specify the “full” mode, which
emulates the previous default behavior.
Overview of the key entry modes:
- 'full' (all wordlists): words are typed in full and entered with the ENTER
or SPACE key, or by exceeding the pad character limit (see below).
- 'short' (BIP39, Monero): words are entered automatically once user types
UNIQ_SS_LEN (see below) valid word letters. 3-letter words in the BIP39
wordlist must be entered with the ENTER or SPACE key, or by exceeding the
pad character limit.
- 'fixed' (BIP39, Electrum): words are entered automatically once user types
UNIQ_SS_LEN characters in total. Words shorter than UNIQ_SS_LEN must be
padded to fit. Thus the total number of characters entered is the same for
all words.
- 'minimal' (Electrum): words are entered automatically once user types the
minimum number of characters required to uniquely identify a word (varies
from word to word). Words that are substrings of other words in the wordlist
must be entered with the ENTER or SPACE key, or by exceeding the pad
character limit. This is the only mode that checks user input letter by
letter.
Pad character limits by mode:
-----------------------------
short: 16
minimal: 16
full: longest_word - word_len
fixed: uniq_ss_len - word_len
Wordlist parameters:
--------------------
Parameter Electrum BIP39 XMRSEED
--------- -------- ----- -------
uniq_ss_len: 10 4 3
shortest_word: 3 3 4
longest word: 12 8 12
optimum mode: minimal fixed short
Default modes for each wordlist may be configured in 'mmgen.cfg' via the
'mnemonic_entry_modes' option.
Usage / testing:
$ mmgen-walletconv -i words
$ mmgen-walletconv -i bip39
$ mmgen-tool mn2hex_interactive fmt=mmgen mn_len=12 print_mn=1
$ mmgen-tool mn2hex_interactive fmt=bip39
$ mmgen-tool mn2hex_interactive fmt=xmrseed
$ test/unit_tests.py mn_entry
$ test/test.py -e input
2020-03-12 17:12:43 +00:00
|
|
|
- Word-completing **mnemonic entry modes** customized for each of MMGen’s
|
|
|
|
|
supported wordlists minimize keystrokes during seed phrase entry.
|
2020-03-12 16:38:02 +00:00
|
|
|
- **Stealth mnemonic entry:** This feature allows you to obfuscate your seed
|
|
|
|
|
phrase with “dead” keystrokes to guard against acoustic side-channel attacks.
|
2019-06-10 09:17:05 +00:00
|
|
|
- **Network privacy:** MMGen never “calls home” or checks for upgrades over the
|
|
|
|
|
network. No information about your wallet installation or crypto assets is
|
|
|
|
|
ever leaked to third parties.
|
|
|
|
|
- **Human-readable wallet files:** All of MMGen’s wallet formats, with the
|
|
|
|
|
exception of incognito wallets, can be printed or copied by hand.
|
|
|
|
|
- **Terminal-based:** MMGen can be run in a screen or tmux session on your local
|
|
|
|
|
network.
|
|
|
|
|
- **Scriptability:** Most MMGen commands can be made non-interactive, allowing
|
2020-03-12 16:38:02 +00:00
|
|
|
you to automate repetitive tasks using shell scripts.
|
|
|
|
|
- The project also includes the [`mmgen-tool`][L] utility, a handy “pocket
|
|
|
|
|
knife” for cryptocurrency developers, along with an easy-to-use [**tool API
|
|
|
|
|
interface**][ta] providing access to a subset of its commands from within
|
|
|
|
|
Python.
|
2020-02-25 19:03:47 +00:00
|
|
|
|
|
|
|
|
#### Supported platforms:
|
|
|
|
|
|
|
|
|
|
Linux, Armbian, Raspbian, Windows/MSYS2
|
2019-06-10 09:17:05 +00:00
|
|
|
|
2014-04-03 13:51:05 +04:00
|
|
|
### Download/Install
|
|
|
|
|
|
2016-08-06 23:51:49 +03:00
|
|
|
> #### [Install from source on Microsoft Windows][1]
|
2014-04-03 13:51:05 +04:00
|
|
|
|
2017-08-03 08:56:40 +03:00
|
|
|
> #### [Install from source on Debian, Ubuntu, Raspbian or Armbian Linux][2]
|
2014-04-03 13:51:05 +04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
### Using MMGen
|
|
|
|
|
|
2014-08-09 23:08:18 +04:00
|
|
|
> #### [Getting Started with MMGen][3]
|
2014-04-04 00:33:56 +04:00
|
|
|
|
2019-06-10 09:17:05 +00:00
|
|
|
> #### [MMGen Quick Start with Regtest Mode][Q]
|
2017-09-30 14:45:11 +03:00
|
|
|
|
2014-07-30 00:48:45 +04:00
|
|
|
> #### [MMGen command help][6]
|
|
|
|
|
|
2019-06-10 09:17:05 +00:00
|
|
|
> #### [Recovering your keys without the MMGen software][K]
|
2017-10-01 11:04:05 +03:00
|
|
|
|
2019-06-10 09:17:05 +00:00
|
|
|
> #### [Altcoin and Forkcoin support (ETH,ETC,XMR,ZEC,LTC,BCH and 144 Bitcoin-derived alts)][F]
|
2017-10-04 11:05:33 +03:00
|
|
|
|
2019-05-25 15:47:20 +00:00
|
|
|
> #### [Subwallets][U]
|
|
|
|
|
|
2020-02-25 19:03:47 +00:00
|
|
|
> #### [XOR Seed Splitting][O]
|
|
|
|
|
|
|
|
|
|
> #### [Test Suite][ts]
|
|
|
|
|
|
|
|
|
|
> #### [Tool API][ta]
|
|
|
|
|
|
2014-04-04 00:33:56 +04:00
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
|
|
|
|
2014-04-27 14:04:26 +04:00
|
|
|
[**Forum**][4] |
|
2017-02-23 10:55:39 +03:00
|
|
|
[Reddit][0] |
|
2018-04-08 06:42:53 +00:00
|
|
|
[PGP Public Keys][5] |
|
2018-02-10 19:54:17 +03:00
|
|
|
Donate (BTC,BCH): 15TLdmi5NYLdqmtCqczUs5pBPkJDXRs83w
|
2014-04-11 23:25:09 +04:00
|
|
|
|
2017-02-23 10:55:39 +03:00
|
|
|
[0]: https://www.reddit.com/user/mmgen-py
|
2014-04-11 23:25:09 +04:00
|
|
|
[1]: https://github.com/mmgen/mmgen/wiki/Install-MMGen-on-Microsoft-Windows
|
|
|
|
|
[2]: https://github.com/mmgen/mmgen/wiki/Install-MMGen-on-Debian-or-Ubuntu-Linux
|
|
|
|
|
[3]: https://github.com/mmgen/mmgen/wiki/Getting-Started-with-MMGen
|
2014-04-27 14:04:26 +04:00
|
|
|
[4]: https://bitcointalk.org/index.php?topic=567069.0
|
2018-04-08 06:42:53 +00:00
|
|
|
[5]: https://github.com/mmgen/mmgen/wiki/MMGen-Signing-Keys
|
2014-07-31 01:31:36 +04:00
|
|
|
[6]: https://github.com/mmgen/mmgen/wiki/MMGen-command-help
|
2015-01-04 11:14:11 +03:00
|
|
|
[7]: http://bitcoinmagazine.com/8396/deterministic-wallets-advantages-flaw/
|
2016-07-27 11:26:11 +03:00
|
|
|
[8]: https://github.com/mmgen/MMGenLive
|
2016-11-28 19:52:03 +03:00
|
|
|
[9]: https://cloud.githubusercontent.com/assets/6071028/20677261/6ccab1bc-b58a-11e6-8ab6-094f88befef2.jpg
|
2019-06-10 09:17:05 +00:00
|
|
|
[Q]: https://github.com/mmgen/mmgen/wiki/MMGen-Quick-Start-with-Regtest-Mode
|
|
|
|
|
[K]: https://github.com/mmgen/mmgen/wiki/Recovering-Your-Keys-Without-the-MMGen-Software
|
2019-03-08 09:06:45 +00:00
|
|
|
[S]: https://github.com/mmgen/mmgen/wiki/Recovering-Your-Keys-Without-the-MMGen-Software#a_mh
|
2019-06-10 09:17:05 +00:00
|
|
|
[F]: https://github.com/mmgen/mmgen/wiki/Altcoin-and-Forkcoin-Support
|
|
|
|
|
[W]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
|
2019-03-08 09:06:45 +00:00
|
|
|
[ew]: https://github.com/spesmilo/electrum/blob/1.9.5/lib/mnemonic.py
|
|
|
|
|
[bw]: https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt
|
|
|
|
|
[fl]: https://en.wiktionary.org/wiki/Wiktionary:Frequency_lists/Contemporary_poetry
|
2019-05-25 15:47:20 +00:00
|
|
|
[U]: https://github.com/mmgen/mmgen/wiki/Subwallets
|
2019-06-10 09:17:05 +00:00
|
|
|
[X]: https://github.com/mmgen/mmgen/wiki/autosign-[MMGen-command-help]
|
|
|
|
|
[G]: https://github.com/mmgen/mmgen/wiki/passgen-[MMGen-command-help]
|
|
|
|
|
[T]: https://github.com/mmgen/mmgen/wiki/Getting-Started-with-MMGen#a_ct
|
|
|
|
|
[E]: https://github.com/mmgen/mmgen/wiki/Altcoin-and-Forkcoin-Support#a_tx
|
|
|
|
|
[ag]: https://github.com/mmgen/mmgen/wiki/addrgen-[MMGen-command-help]
|
|
|
|
|
[bx]: https://github.com/mmgen/mmgen/wiki/Altcoin-and-Forkcoin-Support#a_bch
|
|
|
|
|
[mx]: https://github.com/mmgen/mmgen/wiki/Altcoin-and-Forkcoin-Support#a_xmr
|
|
|
|
|
[zx]: https://github.com/mmgen/mmgen/wiki/Altcoin-and-Forkcoin-Support#a_zec
|
|
|
|
|
[ax]: https://github.com/mmgen/mmgen/wiki/Altcoin-and-Forkcoin-Support#a_kg
|
|
|
|
|
[M]: https://github.com/mmgen/mmgen/wiki/Getting-Started-with-MMGen#a_fee
|
|
|
|
|
[R]: https://github.com/mmgen/mmgen/wiki/Getting-Started-with-MMGen#a_rbf
|
|
|
|
|
[B]: https://github.com/mmgen/mmgen/wiki/txbump-[MMGen-command-help]
|
|
|
|
|
[69]: https://github.com/bitcoin/bips/blob/master/bip-0069.mediawiki
|
2020-02-25 19:03:47 +00:00
|
|
|
[O]: https://github.com/mmgen/mmgen/wiki/XOR-Seed-Splitting:-Theory-and-Practice
|
|
|
|
|
[ms]: https://github.com/mmgen/mmgen/wiki/seedsplit-[MMGen-command-help]
|
|
|
|
|
[ta]: https://github.com/mmgen/mmgen/wiki/Tool-API
|
|
|
|
|
[ts]: https://github.com/mmgen/mmgen/wiki/Test-Suite
|
2020-03-12 16:38:02 +00:00
|
|
|
[L]: https://github.com/mmgen/mmgen/wiki/tool-[MMGen-command-help].md
|
