diff --git a/Altcoin-and-Forkcoin-Support.md b/Altcoin-and-Forkcoin-Support.md index 14d5ead..190e185 100644 --- a/Altcoin-and-Forkcoin-Support.md +++ b/Altcoin-and-Forkcoin-Support.md @@ -228,9 +228,9 @@ Generate ten Monero address pairs from your default wallet: $ mmgen-keygen --coin=xmr 1-10 MMGen’s enhanced support for Monero includes automated Monero wallet creation -and syncing. +and syncing tools. -*Note that the use of these commands requires private data to be exposed on a +*Note that the use of these tools requires private data to be exposed on a network-connected machine in order to unlock the Monero wallets, which is a violation of MMGen’s security policy.* diff --git a/Home.md b/Home.md index 20f92c9..82f8eb2 100644 --- a/Home.md +++ b/Home.md @@ -1,10 +1,11 @@ -#### This is the main documentation page for the MMGen wallet system. +**This is the main documentation page for the MMGen wallet system.** -For newly-added features that aren’t yet documented here, check the [commit -log][cn], which always documents important new features, usually with helpful -examples. To search the commit log locally, `cd` to the root of your cloned -MMGen repository, ensure that it’s up-to-date by doing a `git checkout master && -git pull`, type `git log` and perform a search using the `/` key. +Features added since the last release may not yet be documented here. For +these, check the [commit log][cn], which always documents new features, usually +with helpful examples. To search the commit log locally, `cd` to the root of +your cloned MMGen repository, ensure that it’s up-to-date by doing a `git +checkout master && git pull`, and invoke `git log`. Searches within the pager +are performed via the `/` key. ### Download/Install diff --git a/Subwallets.md b/Subwallets.md index 569be7f..ac9e224 100644 --- a/Subwallets.md +++ b/Subwallets.md @@ -130,4 +130,4 @@ screen][sh]. [c1]: https://github.com/mmgen/mmgen/commit/7538a9460e897b9b23d8ac58853c33713334043f [c2]: https://github.com/mmgen/mmgen/commit/d1b8aefde6d3a13337cbe3147d9913eb09b6765b [c3]: https://github.com/mmgen/mmgen/commit/82086c9936843dc43c1892b672cdf1680763ee84 -[sh]: https://github.com/mmgen/mmgen/wiki/subwalletgen-[MMGen-command-help].md +[sh]: https://github.com/mmgen/mmgen/wiki/subwalletgen-[MMGen-command-help] diff --git a/Test-Suite.md b/Test-Suite.md index 142f07d..c7fedc3 100644 --- a/Test-Suite.md +++ b/Test-Suite.md @@ -3,15 +3,16 @@ In addition to low-level subsystems, the suite tests the overall operation of MMGen’s commands by running them interactively as a user would. Thus the test suite is useful not only for ensuring the MMGen system is correctly installed -and working on your platform but also for observing how it works. +and working on your platform but also for learning how it works. -For BTC-only testing, only Bitcoin Core need be installed. For altcoin testing, -requirements are discussed below. Non-standard RPC ports and data directories -are always used, so there’s no need to stop your running node or nodes. +BTC-only testing requires only Bitcoin Core to be installed. Altcoin testing +requires various helper programs and libraries. Installation instructions for +these are provided below. Non-standard RPC ports and data directories are +always used, so there’s no need to stop your running node or nodes. On Linux/x86\_64 with a reasonably fast processor, the full suite should run in -under 15 minutes when invoked with the `-F` option. On other platforms, -performance may be much slower. +under 15 minutes when invoked with the `-F` option. Execution times on other +platforms may be much slower. ## Quick start @@ -98,13 +99,13 @@ MMGen’s functionality. Launch the script with the `-t` option to view the invocations without running them. The test scripts themselves are all located in the `test/` directory and bear -the `.py` extension. They may be run individually if desired. Each test has an -informative help screen available via the `--help` option. +the `.py` extension. They may be run individually if desired. Options and +arguments required by the tests are described in detail on their help screens. -The most important test in the suite, `test/test.py`, uses the `pexpect` library -to simulate interactive operation of MMGen commands. Running `test/test.py` -with the `-e` switch will produce the same output as if the commands had been -run by a user. +High-level testing of the MMGen system is performed by `test/test.py`, which +uses the `pexpect` library to simulate interactive operation of MMGen user +commands. Launching `test/test.py` with the `-e` option will display the +commands’ output on the screen as they’re being run. | Test | What it tests | |:----------------------|:-----------------------------------------------------| diff --git a/XOR-Seed-Splitting:-Theory-and-Practice.md b/XOR-Seed-Splitting:-Theory-and-Practice.md index fd13cd4..840db85 100644 --- a/XOR-Seed-Splitting:-Theory-and-Practice.md +++ b/XOR-Seed-Splitting:-Theory-and-Practice.md @@ -237,10 +237,73 @@ unique, and differ from their non-master-share counterparts. ### Seed Splitting with MMGen -The MMGen wallet implements seed splitting and joining functionality via the -commands [`mmgen-seedsplit`][mms] and [`mmgen-seedjoin`][mmj]. +The MMGen wallet implements the seed splitting and joining functionality +described above via the commands [`mmgen-seedsplit`][SS] and +[`mmgen-seedjoin`][SJ]. Many usage examples can be found on the +`mmgen-seedsplit` help screen. -For usage information, follow the above links. +Shares can be made from and exported to all supported MMGen wallet formats. +This means you can split a BIP39 seed phrase, for example, and export a share +back to BIP39, all in one command: + + # Create share 1 of a 2-way split of the provided BIP39 seed phrase: + $ mmgen-seedsplit -o bip39 sample.bip39 1:2 + +Each share of a split has a unique share ID. The share IDs are displayed by +`mmgen-seedsplit` so that the user may record them for later reference. They +may also be viewed with the `mmgen-tool list_shares` command: + + # List the share IDs of a 2-way named split 'alice' of your default wallet: + $ mmgen-tool list_shares 2 id_str=alice + + Seed: 71CA5049 (256 bits) + Split Type: 2-of-2 (XOR) + ID String: alice + + Shares + ------ + 1: D0BBD210 + 2: 25F0BD65 + + # List the share IDs of a 3-way default split of provided BIP39 seed phrase: + $ mmgen-tool list_shares 3 wallet=sample.bip39 + + Seed: 03BAE887 (128 bits) + Split Type: 3-of-3 (XOR) + ID String: default + + Shares + ------ + 1: 83B9AF74 + 2: 109485F4 + 3: 424522DC + +Share IDs are handy for checking the correctness of shares when rejoining a +split. Let’s say you’ve decided to rejoin your 2-way split with Alice, whose +share you exported to BIP39 format. This can be done by contacting Alice by +phone, for example, and having her read the mnemonic phrase to you. If the ID +of Alice’s share as displayed by `mmgen-seedjoin` matches the value you recorded +when making the split, then you know Alice has given you the correct phrase. + +***Note:*** *when recovering shares over an insecure channel like the telephone, +it’s advisable to destroy all copies of your share once you’ve rejoined the +seed to safeguard against a possible eavesdropping attacker.* + +Ordinary named splits can easily be rejoined even without the MMGen software. +First, each share must be converted to hexadecimal data. If your shares are in +BIP39 format, for example, there are command-line tools available to do this. +Then a single line of Python code is all that’s required to finish the job: + + $ python3 + >>> seed_hex = hex(int(share1_hex,16) ^ int(share2_hex,16)) # 2-way split + +(Note that the XOR operator in Python is `^`.) + +Rejoining master-share splits on your own is far less trivial, unfortunately. +This is because converting the master share into the temporary share used to +make the split involves an additional step, as you’ll recall from the +theoretical discussion above. In addition, MMGen implements it somewhat +differently than in the provided example. [⊕]: https://mmgen.github.io/images/ss/o_xor.svg "⊕" ["a: 1 0 0 1 0 1 0 0"]: https://mmgen.github.io/images/ss/byte_a.svg "a: 1 0 0 1 0 1 0 0" @@ -274,5 +337,5 @@ For usage information, follow the above links. [wm]: https://en.wikipedia.org/wiki/Modular_arithmetic [otp]: https://en.wikipedia.org/wiki/One-time_pad [sc]: https://en.wikipedia.org/wiki/Stream_cipher -[mms]: seedsplit-[MMGen-command-help] -[mmj]: seedjoin-[MMGen-command-help] +[SS]: seedsplit-[MMGen-command-help] +[SJ]: seedjoin-[MMGen-command-help]