From 5b5c08b22a2293adfd08d432176debe1167da615 Mon Sep 17 00:00:00 2001 From: The MMGen Project Date: Thu, 27 Feb 2025 13:48:52 +0000 Subject: [PATCH] doc/wiki: add missing pages, manpages --- README.md | 2 +- ...stall-MMGen-Wallet-on-Microsoft-Windows.md | 491 +++++++ doc/wiki/Install-MMGen-Wallet-on-Windows.md | 458 ------ doc/wiki/Key-address-files.md | 53 + doc/wiki/MMGen-Wallet-command-help.md | 26 + doc/wiki/Unix-commands-and-environment.md | 36 + doc/wiki/commands/command-help-addrgen.md | 124 ++ doc/wiki/commands/command-help-addrimport.md | 35 + doc/wiki/commands/command-help-autosign.md | 131 ++ doc/wiki/commands/command-help-keygen.md | 129 ++ doc/wiki/commands/command-help-msg.md | 110 ++ doc/wiki/commands/command-help-passchg.md | 57 + doc/wiki/commands/command-help-passgen.md | 105 ++ doc/wiki/commands/command-help-regtest.md | 29 + doc/wiki/commands/command-help-seedjoin.md | 66 + doc/wiki/commands/command-help-seedsplit.md | 148 ++ .../commands/command-help-subwalletgen.md | 101 ++ .../commands/command-help-swaptxcreate.md | 179 +++ doc/wiki/commands/command-help-swaptxdo.md | 243 ++++ .../commands/command-help-tool(detail).md | 1244 +++++++++++++++++ doc/wiki/commands/command-help-tool(usage).md | 191 +++ doc/wiki/commands/command-help-tool.md | 202 +++ doc/wiki/commands/command-help-txbump.md | 120 ++ doc/wiki/commands/command-help-txcreate.md | 127 ++ doc/wiki/commands/command-help-txdo.md | 191 +++ doc/wiki/commands/command-help-txsend.md | 22 + doc/wiki/commands/command-help-txsign.md | 86 ++ doc/wiki/commands/command-help-walletchk.md | 55 + doc/wiki/commands/command-help-walletconv.md | 66 + doc/wiki/commands/command-help-walletgen.md | 58 + doc/wiki/commands/command-help-xmrwallet.md | 503 +++++++ 31 files changed, 4929 insertions(+), 459 deletions(-) create mode 100644 doc/wiki/Install-MMGen-Wallet-on-Microsoft-Windows.md delete mode 100644 doc/wiki/Install-MMGen-Wallet-on-Windows.md create mode 100644 doc/wiki/Key-address-files.md create mode 100644 doc/wiki/MMGen-Wallet-command-help.md create mode 100644 doc/wiki/Unix-commands-and-environment.md create mode 100644 doc/wiki/commands/command-help-addrgen.md create mode 100644 doc/wiki/commands/command-help-addrimport.md create mode 100644 doc/wiki/commands/command-help-autosign.md create mode 100644 doc/wiki/commands/command-help-keygen.md create mode 100644 doc/wiki/commands/command-help-msg.md create mode 100644 doc/wiki/commands/command-help-passchg.md create mode 100644 doc/wiki/commands/command-help-passgen.md create mode 100644 doc/wiki/commands/command-help-regtest.md create mode 100644 doc/wiki/commands/command-help-seedjoin.md create mode 100644 doc/wiki/commands/command-help-seedsplit.md create mode 100644 doc/wiki/commands/command-help-subwalletgen.md create mode 100644 doc/wiki/commands/command-help-swaptxcreate.md create mode 100644 doc/wiki/commands/command-help-swaptxdo.md create mode 100644 doc/wiki/commands/command-help-tool(detail).md create mode 100644 doc/wiki/commands/command-help-tool(usage).md create mode 100644 doc/wiki/commands/command-help-tool.md create mode 100644 doc/wiki/commands/command-help-txbump.md create mode 100644 doc/wiki/commands/command-help-txcreate.md create mode 100644 doc/wiki/commands/command-help-txdo.md create mode 100644 doc/wiki/commands/command-help-txsend.md create mode 100644 doc/wiki/commands/command-help-txsign.md create mode 100644 doc/wiki/commands/command-help-walletchk.md create mode 100644 doc/wiki/commands/command-help-walletconv.md create mode 100644 doc/wiki/commands/command-help-walletgen.md create mode 100644 doc/wiki/commands/command-help-xmrwallet.md diff --git a/README.md b/README.md index 04203b8b..0daa69b0 100644 --- a/README.md +++ b/README.md @@ -198,7 +198,7 @@ Donate: [2]: ../../wiki/Install-MMGen-Wallet-on-Linux-or-macOS [3]: ../../wiki/Getting-Started-with-MMGen-Wallet [5]: ../../wiki/MMGen-Signing-Keys -[6]: ../../wiki/MMGen-command-help +[6]: ../../wiki/MMGen-Wallet-command-help [7]: http://bitcoinmagazine.com/8396/deterministic-wallets-advantages-flaw/ [8]: https://github.com/mmgen/MMGenLive [9]: https://mmgen.org/images/rxvt-txcreate.jpg diff --git a/doc/wiki/Install-MMGen-Wallet-on-Microsoft-Windows.md b/doc/wiki/Install-MMGen-Wallet-on-Microsoft-Windows.md new file mode 100644 index 00000000..9c2e6459 --- /dev/null +++ b/doc/wiki/Install-MMGen-Wallet-on-Microsoft-Windows.md @@ -0,0 +1,491 @@ +## Table of Contents + +#### [Introduction](#a_i) + +#### [Install MSYS2 and MMGen Wallet](#a_m) +* [1. Install MSYS2](#a_ms) +* [2. Upgrade MSYS2](#a_ug) + * [Online install](#a_ug1) + * [Offline install](#a_ug2) +* [3. Install MMGen Wallet’s MSYS2 dependencies](#a_md) + * [Offline install](#a_md1) +* [4. Set up your shell environment](#a_ev) +* [5. Choose your Python environment](#a_pev) +* [6. Install the Python ECDSA library (offline install only)](#a_ec) +* [7. Install the standalone scrypt package (required for strong password hashing)](#a_sc) +* [8. Clone and copy the secp256k1 library (offline install only)](#a_se) +* [9. Install MMGen Wallet](#a_mm) + * [Stable version](#a_mms) + * [Development version](#a_mmd) +* [10. Install Python Ethereum dependencies (if applicable)](#a_pe) +* [11. Install and launch your coin daemons](#a_cd) +* [12. You’re done!](#a_do) + +#### [Keeping your installation up to date](#a_u) +* [Upgrading MSYS2](#a_us) +* [Upgrading MMGen Wallet](#a_um) + * [Upgrade to latest stable version](#a_ums) + * [Upgrade to latest development version](#a_umd) + +## Introduction + +MMGen Wallet is supported on Microsoft Windows via [MSYS2][mh], which provides a +Unix-like command-line environment within Windows. Windows 8.1 and later +versions are supported. + +MSYS2 is the successor project to MinGW-64 and the earlier MSYS, bringing many +improvements such as package management and support for Python 3. The MSYS2 +project page is located [here][mp] and its wiki [here][mw]. + +Before you get started, just a reminder that MMGen Wallet must be installed on +two computers, one online and one offline. All operations involving private +data—wallet generation, address generation and transaction signing—are handled +offline, while the online machine takes care of tracking balances and creating +and sending transactions. + +This means that once you’ve finished the install process, the computer you’ve +designated for offline use must be taken offline **permanently.** Furthermore, +its wifi and bluetooth interfaces must be disabled as well to safeguard against +private data leakage. + +With some extra steps, it’s possible to perform the installation on a machine +that’s *already* offline. These steps will be additionally outlined in +sections entitled **Offline install.** When doing an online install you will +ignore these sections. + +## Install MSYS2 and MMGen Wallet + +### 1. Install MSYS2 + +Download the MSYS2 executable installer for your architecture from the [MSYS2 +homepage][mh], but ignore the installation instructions there. + +Run the installer, accepting all defaults. When installation completes, +uncheck ‘Run MSYS2 now’ and click ‘Finish’. From the Start menu, drag the +‘MSYS2 UCRT64’ icon to the desktop. You will use it to launch all MSYS2 +terminal sessions from now on. Double-click the icon to launch the terminal. + +Note that the root of your MSYS2 installation is located in `C:\\msys64`, so the +following commands, for example, will produce a listing of the same directory: + +```text +$ ls /etc # the path as seen within MSYS2 +$ ls 'C:\\msys64\etc' # the path as seen by Windows +``` + +### 2. Upgrade MSYS2 + +#### Online install: + +> Update the package database and core system packages: +> +> ```text +> $ pacman -Syu +> ``` +> +> Exit and restart the MSYS2 terminal. Complete upgrading the system: +> +> ```text +> $ pacman -Su +> ``` + +#### Offline install: + +> You must now download the required database and package files on your online +> computer and then copy them to your offline box. A USB flash drive works +> ideally for this. +> +> Begin by updating the pacman database. The database files and their +> associated signatures can be listed by issuing the following command: +> +> ```text +> $ ls /var/lib/pacman/sync +> ``` +> +> Download up-to-date versions of these files from the primary MSYS2 mirror: +> +>> +>> +>> +>> +>> +>> +>> +>> +>> +>> +>> +>> +>> +>> +> +> Copy the files to your offline machine, replacing the originals at +> `C:\msys64\var\lib\pacman\sync`. +> +> Now issue the following command: +> +> ```text +> $ pacman -Sup > urls.txt +> ``` +> +> This command may cause your MSYS2 terminal window to close. If so, just +> reopen another one. +> +> The command's output is now saved in the file `urls.txt` (this redirection +> trick using `>` works for most shell commands, by the way). Copy `urls.txt` +> to your online machine and download the URLs listed in it. +> +> Create a new folder on your offline machine: +> +> ```text +> $ mkdir packages1 +> ``` +> +> Transfer the downloaded package files to the offline machine and place them in +> this folder. +> +> Now issue the following command to install the packages: +> +> ```text +> $ pacman -U packages1/* +> ``` +> +> When the process is finished, close your terminal window and reopen another +> one. +> +> Now reissue the `pacman -Sup` command, which may or may not generate another +> list of URLs. If it does, repeat the same download/copy/install procedure +> with the new URLs, only with a new `packages2` directory instead of +> `packages1`. +> +> Your system upgrade is now complete. + +### 3. Install MMGen Wallet’s MSYS2 dependencies + +Now you’re ready to install the packages specifically required by MMGen. + +#### Offline install: + +> As you’ve probably noticed by now, the command `pacman -S ` +> downloads and installs MSYS2 packages and their dependencies, while `pacman +> -Sp ` prints a list of download URLs for those same packages and +> dependencies. Accordingly, you must issue the command below with `-Sp` +> instead of `-S` to produce a URL list. Then repeat the above +> download/copy/install steps once again with the new URLs, downloading into +> a new directory, say `packages3`. + +Install the MMGen Wallet dependencies: + +```text +pacman -S tar git vim autoconf automake-wrapper autogen libtool cygrunsrv \ + mingw-w64-ucrt-x86_64-python-build \ + mingw-w64-ucrt-x86_64-python-wheel \ + mingw-w64-ucrt-x86_64-python-pip \ + mingw-w64-ucrt-x86_64-libltdl \ + mingw-w64-ucrt-x86_64-gcc \ + mingw-w64-ucrt-x86_64-make \ + mingw-w64-ucrt-x86_64-pcre \ + mingw-w64-ucrt-x86_64-libsodium \ + mingw-w64-ucrt-x86_64-python-pynacl \ + mingw-w64-ucrt-x86_64-python-cryptography \ + mingw-w64-ucrt-x86_64-python-pycryptodome \ + mingw-w64-ucrt-x86_64-python-six \ + mingw-w64-ucrt-x86_64-python-pexpect \ + mingw-w64-ucrt-x86_64-python-gmpy2 \ + mingw-w64-ucrt-x86_64-python-pysocks \ + mingw-w64-ucrt-x86_64-python-requests \ + mingw-w64-ucrt-x86_64-python-aiohttp \ + mingw-w64-ucrt-x86_64-python-pyreadline3 +``` + +### 4. Set up your shell environment + +Create the `/usr/local/bin` directory. This is where you’ll place various +binaries required by MMGen: + +```text +$ mkdir -p /usr/local/bin # seen by Windows as 'C:\\msys64\usr\local\bin' +``` + +Open your shell’s runtime configuration file in a text editor: + +```text +$ nano ~/.bashrc +``` + +Add the following lines to the end of the file (if this is a Bitcoin-only +installation, you may omit the non-Bitcoin components of `daemon_paths`): + +```bash +win_home="/${HOMEDRIVE/:}${HOMEPATH//\\//}" +daemon_paths="/c/Program Files/Bitcoin/daemon:/c/Program Files/Litecoin/daemon:/c/Program Files/Bitcoin-Cash-Node/daemon:/c/Program Files/Geth" +export PATH="$win_home/.local/bin:$PATH:$daemon_paths" +export PYTHONUTF8=1 +``` + +Save and exit. Close and reopen the terminal window to update your working +environment. + +### 5. Choose your Python environment + +If you have other Python packages installed under MSYS2, then you may wish to +use a [virtual environment][vv] to keep your MMGen Wallet installation isolated +from them. + +If you choose not to use a virtual environment, then you should add `--user` to +the command line every time you run `pip install` as directed below. This will +prevent pip from installing packages in the system directory. + +### 6. Install the Python ECDSA library (offline install only) + +On your online machine: + +```text +$ python3 -m pip download ecdsa +``` + +Copy the downloaded file to your offline machine and install: + +```text +$ python3 -m pip install ecdsa-*.whl +``` + +### 7. Install the standalone scrypt package (required for strong password hashing) + +Due to a faulty implementation of the `scrypt` function included in Python’s +`hashlib`, the standalone `scrypt` module is required for stronger-than-default +password hashing (i.e. hash presets greater than `3`). Installing the package is +therefore highly advisable. + +On your online machine, clone the Py-Scrypt repository from Github: + +```text +$ git clone https://github.com/holgern/py-scrypt.git +``` + +Offline install: + +> Copy the cloned repo to your offline machine. + +Build and install: + +```text +$ cd py-scrypt +$ python3 -m build --no-isolation +$ python3 -m pip install dist/*.whl +``` + +### 8. Clone and copy the secp256k1 library (offline install only) + +On your online machine, clone the secp256k1 repository from Github: + +```text +$ git clone https://github.com/bitcoin-core/secp256k1.git +``` + +On your offline machine, create a magic location and copy the cloned secp256k1 +directory to it: + +```text +$ mkdir -p ~/.cache/mmgen # the magic location +$ cp -a /path/to/secp256k1/repo/secp256k1 ~/.cache/mmgen +$ ls ~/.cache/mmgen/secp256k1/autogen.sh # check that files were correctly copied +``` + +### 9. Install MMGen Wallet + +Now you’re ready to install MMGen Wallet itself. + +#### Stable version: + +Online install: + +> ```text +> $ python3 -m pip install mmgen-wallet +> ``` + +Offline install: + +> ```text +> $ python3 -m pip download mmgen-wallet +> ``` +> +> Copy the downloaded tar.gz archive to your offline machine. +> +> ```text +> $ python3 -m pip install --no-build-isolation mmgen-wallet.*tar.gz +> ``` + +#### Development version: + +*Bear in mind that security vulnerabilities are more likely to be present in +development code than in a stable release. In addition, while the tip of +`master` is always tested on Linux before being pushed to the public repository, +it’s not guaranteed to run or even install on MSYS2. Installation or runtime +issues may also arise due to missing dependencies or installation steps not yet +covered in the documentation.* + +On your online machine, clone the MMGen Wallet repository: + +```text +$ git clone https://github.com/mmgen/mmgen-wallet +Cloning into ’mmgen-wallet’... +``` + +Offline install: + +> Copy the cloned mmgen-wallet directory to your offline machine. + +Enter the repo directory, build and install: + +```text +$ cd mmgen-wallet +$ python3 -m build --no-isolation +$ python3 -m pip install dist/*.whl +``` + +The `--force` and `--no-deps` options to `pip install` also come in handy on +occasion. + +Note that MMGen Wallet has a test suite. Refer to the [Test Suite][ts] wiki +page for details. + +### 10. Install Python Ethereum dependencies (if applicable) + +If you’ll be using MMGen Wallet with Ethereum, then you must install a few +dependencies. From the MMGen repository root, type the following: + +Online install: + +> ```text +> $ python3 -m pip install --no-deps -r eth-requirements.txt +> ``` + +Offline install: + +> ```text +> $ python3 -m pip download --no-deps -r eth-requirements.txt +> ``` +> +> Transfer the downloaded files to your offline machine, `cd` to the directory +> containing the files and install them: +> +> ```text +> $ python3 -m pip install --no-deps *.whl +> ``` + +### 11. Install and launch your coin daemons + +At this point your installation will be able to generate wallets, along with +keys and addresses for all supported coins. However, if you intend to do any +transacting, as you probably do, you’ll need to install and launch a coin daemon +or daemons. MMGen Wallet has full transaction support for BTC, BCH, LTC, ETH, +ETC and ERC20 tokens. + +Go to the [**Install Bitcoind and other supported coin daemons**][ib] wiki page +and follow the instructions for your coins of choice. You can skip the parts +about adding to the Windows path, since your `PATH` variable was taken care of +in [Step 4](#a_ev). Note that the daemons must be installed on both your +online and offline machines. + +To transact ETH, ETC or ERC20 tokens you’ll need the latest Geth or Parity (for +Ethereum Classic) binary. See the [**Altcoin-and-Forkcoin-Support**][pl] page +for information on downloading and launching these daemons. The `parity.exe` +and `ethkey.exe` binaries should be copied to `/usr/local/bin`. For Geth, +download and run the Windows installer and add `/c/Program Files/Geth` to the +end of the `PATH` variable in your `~/.bashrc` file: + +Please note that Ethereum daemons perform rather poorly under Windows due to +threading limitations. Unless you have very fast hardware, transacting and +syncing the blockchain will be painfully slow. + +### 12. You’re done! + +Congratulations, your installation is now complete, and you can proceed to +[**Getting Started with MMGen Wallet**][gs]. Note that all features supported +by MMGen Wallet on Linux and macOS, except for [autosigning][ax], are now +supported on MSYS2 too. Please be aware of the following, however: + ++ Non-ASCII filenames cannot be used with the `mmgen-xmrwallet` utility. This + is an issue with the Monero wallet RPC daemon rather than MMGen. + ++ The Bitcoin Cash Node daemon cannot handle non-ASCII pathnames. This is an + issue with the Bitcoin Cash Node implementation for Windows, not MMGen. + +## Keeping your installation up to date + +### Upgrading MSYS2 + +You should periodically upgrade your MSYS2 installation, especially when [new +releases][mh] appear. The most reliable way to check your current MSYS2 version +is to examine the date on the installation binary, which you’ve hopefully saved +somewhere. + +To perform the upgrade, just repeat [Step 2](#a_ug) of this guide. + +Note that [Step 3](#a_md) need not be performed, as the MMGen dependencies +are already in `pacman`’s database. + +### Upgrading MMGen Wallet + +You should periodically upgrade your MMGen Wallet installation from one of its +public repositories, especially when [new releases][mr] appear. You can check +your currently installed version by executing `mmgen-tool --version`. + +#### Upgrade to latest stable version: + +Online upgrade: + +> ```text +> $ python3 -m pip install --upgrade mmgen-wallet +> ``` + +Offline upgrade: + +> On your online machine: +> +> ```text +> $ python3 -m pip download mmgen-wallet +> ``` +> +> Copy the downloaded tar.gz archive to your offline machine and execute: +> +> ```text +> $ python3 -m pip install --no-build-isolation mmgen-wallet.*tar.gz +> ``` + +#### Upgrade to latest development version: + +Enter the MMGen Wallet repository root on your online computer and issue the +following commands: + +Online upgrade: + +> ```text +> $ git checkout master +> $ git pull +> $ rm -rf dist build *.egg-info +> $ python3 -m build --no-isolation +> $ python3 -m pip install dist/*.whl +> ``` + +Offline upgrade: + +> After the `git pull` step above, copy the updated repository to your offline +> machine, `cd` to the root of the copied repository and perform the remaining +> steps. + +[mh]: https://www.msys2.org +[mp]: https://sourceforge.net/projects/msys2 +[mw]: https://github.com/msys2/msys2/wiki +[ov]: ../../../../releases/tag/v0.9.8 +[sd]: https://download.sysinternals.com/files/SDelete.zip +[mr]: ../../../../releases +[di]: Deprecated-MSWin-Installation.md +[ib]: Install-Bitcoind.md +[gs]: Getting-Started-with-MMGen-Wallet.md +[pl]: Altcoin-and-Forkcoin-Support.md#a_ed +[ax]: commands/command-help-autosign.md +[mc]: Altcoin-and-Forkcoin-Support.md#a_xmr +[ts]: Test-Suite.md +[vv]: https://docs.python.org/3/library/venv.html diff --git a/doc/wiki/Install-MMGen-Wallet-on-Windows.md b/doc/wiki/Install-MMGen-Wallet-on-Windows.md deleted file mode 100644 index fa609d6d..00000000 --- a/doc/wiki/Install-MMGen-Wallet-on-Windows.md +++ /dev/null @@ -1,458 +0,0 @@ -## Table of Contents - -#### [Introduction](#a_i) - -#### [Install MSYS2 and MMGen](#a_m) -* [1. Install MSYS2](#a_ms) -* [2. Upgrade MSYS2](#a_ug) - * [Online users](#a_ug1) - * [Offline install](#a_ug2) -* [3. Install MSYS2 MMGen dependencies](#a_md) - * [Offline install](#a_md1) -* [4. Set up your environment](#a_ev) -* [5. Install the Python ECDSA library (offline install only)](#a_ec) -* [6. Install the standalone scrypt package (required for strong password hashing)](#a_sc) -* [7. Clone and copy the secp256k1 library (offline install only)](#a_se) -* [8. Install MMGen](#a_mm) -* [9. Install Python Ethereum dependencies (Ethereum users only)](#a_pe) -* [10. Install and launch your coin daemons](#a_cd) -* [11. You’re done!](#a_do) - -#### [Keeping your installation up to date](#a_u) -* [MSYS2](#a_us) -* [MMGen](#a_um) - -## Introduction - -MMGen is supported on Microsoft Windows via [MSYS2][mh], which provides a -Unix-like command-line environment within Windows. Windows 8.1 and later -versions are supported. - -MSYS2 is the successor project to MinGW-64 and the earlier MSYS, bringing many -improvements such as package management and support for Python 3. The MSYS2 -project page is located [here][mp] and its wiki [here][mw]. - -Before you get started, just a reminder that MMGen must be installed on two -computers, one online and one offline, if you want to use it securely. All -operations involving private data—wallet generation, address generation and -transaction signing—are handled offline, while the online installation takes -care of tracking balances and creating and sending transactions. - -This means that once you’ve finished the install process, the computer you’ve -designated for offline use must be taken offline **permanently.** Furthermore, -its wi-fi and bluetooth interfaces should be disabled as well to safeguard -against the possibility of private data leakage. - -With some extra steps, it’s possible to perform the installation on a machine -that’s *already* offline. These steps will be additionally outlined in -sections entitled **Offline install.** When doing an online install you may -skip over these sections. - -## Install MSYS2 and MMGen - -### 1. Install MSYS2 - -Download the MSYS2 executable installer for your architecture from the [MSYS2 -homepage][mh], but ignore the installation instructions there. - -Run the installer, accepting all defaults. At the end of the installation, -uncheck ‘Run MSYS2 now’ and click ‘Finish’. From the Start menu, drag the -‘MSYS2 UCRT64’ icon to the desktop. This is the icon you will use to launch -all MSYS2 terminal sessions from now on. Double-click the icon to launch the -terminal. - -Note that the root of your MSYS2 installation is located in `C:\\msys64`, so the -following commands, for example, will produce a listing of the same directory: - -```text -$ ls /etc # the path as seen within MSYS2 -$ ls 'C:\\msys64\etc' # the path as seen by Windows -``` - -### 2. Upgrade MSYS2 - -#### Online users: - -> Optionally edit your mirror lists as described in **Offline install** below. - -> Update the package database and core system packages: - -```text -$ pacman -Syu -``` - -> Exit and restart the MSYS2 terminal. If you’re using modified mirror lists, -> they may have been overwritten by the update operation, in which case you -> should restore them from your modified versions. - -> Now complete upgrading the system: - -```text -$ pacman -Su -``` - -#### Offline install: - -> You must now download the required database and package files from the -> Internet on your online computer and copy them to your offline box. A USB -> flash drive works ideally for this. - -> The mirror list files located in the directory `/etc/pacman.d` specify the -> servers to download packages from. - -> The server that’s listed first in these files is the one that will used by -> default, so you may wish to edit them and place the server you wish to use -> first in the list. For this you may use a text editor such as Notepad or -> Nano: - -```text -$ nano /etc/pacman.d/mirrorlist.msys -... repeat for remaining mirrorlist files ... -``` - -> You need to update your database files as well. The database files and their -> associated signature files can be listed by issuing the following command: - -```text -$ ls /var/lib/pacman/sync -``` - -> Download up-to-date versions of these files from a fast MSYS2 mirror: - ->> ->> ->> ->> ->> ->> ->> ->> ->> ->> ->> ->> ->> ->> - -> Copy the files to your offline machine, replacing the originals at -> `C:\msys64\var\lib\pacman\sync`. - -> Now issue the following command: - -```text -$ pacman -Sup > urls.txt -``` - -> This command may cause your MSYS2 terminal window to close. If so, just -> reopen another one. - -> The command's output is now saved in the file `urls.txt` (this redirection -> trick using '>' works for most shell commands, by the way). Copy `urls.txt` -> to your online machine and download the URLs listed in it. - -> Create a new folder on your offline machine: - -```text -$ mkdir packages1 -``` - -Transfer the downloaded package files to the offline machine and place them in -this folder. - -> Now issue the following command to install the packages: - -```text -$ pacman -U packages1/* -``` - -> When the process is finished, close your terminal window and reopen another -> one. - -> Now reissue the `pacman -Sup` command, which will generate a much longer list -> of URLs this time. Repeat the same download/copy/install procedure with the -> new URLs, only using a new `packages2` directory instead of `packages1`. - -> Your system upgrade is now complete. - -### 3. Install MSYS2 MMGen dependencies - -Now that your system’s fully up to date, you’re ready to install the packages -specifically required by MMGen. - -#### Offline install: - -> As you’ve probably noticed by now, the command `pacman -S ` -> installs MSYS2 packages and their dependencies, while `pacman -Sp -> ` prints a list of download URLs for the same packages and -> dependencies. So before running the command shown below, you must first -> issue it with `-Sp` instead of `-S` to produce a URL list. Then repeat the -> above download/copy/install steps once again with the new URLs, replacing -> `packages2` with `packages3`. - -Install the MMGen requirements and their dependencies: - -```text -pacman -S tar git vim autoconf automake-wrapper autogen libtool cygrunsrv \ - mingw-w64-ucrt-x86_64-python-build \ - mingw-w64-ucrt-x86_64-python-wheel \ - mingw-w64-ucrt-x86_64-python-pip \ - mingw-w64-ucrt-x86_64-libltdl \ - mingw-w64-ucrt-x86_64-gcc \ - mingw-w64-ucrt-x86_64-make \ - mingw-w64-ucrt-x86_64-pcre \ - mingw-w64-ucrt-x86_64-libsodium \ - mingw-w64-ucrt-x86_64-python-pynacl \ - mingw-w64-ucrt-x86_64-python-cryptography \ - mingw-w64-ucrt-x86_64-python-pycryptodome \ - mingw-w64-ucrt-x86_64-python-six \ - mingw-w64-ucrt-x86_64-python-pexpect \ - mingw-w64-ucrt-x86_64-python-gmpy2 \ - mingw-w64-ucrt-x86_64-python-pysocks \ - mingw-w64-ucrt-x86_64-python-requests \ - mingw-w64-ucrt-x86_64-python-aiohttp \ - mingw-w64-ucrt-x86_64-python-pyreadline3 -``` - -### 4. Set up your environment - -Create the `/usr/local/bin` directory. This is where you’ll place various -binaries required by MMGen: - -```text -$ mkdir -p /usr/local/bin # seen by Windows as 'C:\\msys64\usr\local\bin' -``` - -Open your shell’s runtime configuration file in a text editor: - -```text -$ nano ~/.bashrc -``` - -Add the following lines to the end of the file (if this is a Bitcoin-only -installation, you may omit the non-Bitcoin components of `daemon_paths`): - -```bash -win_home="/${HOMEDRIVE/:}${HOMEPATH//\\//}" -daemon_paths="/c/Program Files/Bitcoin/daemon:/c/Program Files/Litecoin/daemon:/c/Program Files/Bitcoin-Cash-Node/daemon:/c/Program Files/Geth" -export PATH="$win_home/.local/bin:$PATH:$daemon_paths" -export PYTHONUTF8=1 -``` - -Save and exit. Close and reopen the terminal window to update your working -environment. - -### 5. Install the Python ECDSA library (offline install only) - -On your online machine: - -```text -$ python3 -m pip download ecdsa -``` - -Copy the downloaded file to your offline machine and install: - -```text -$ python3 -m pip install --user ecdsa-*.whl -``` - -### 6. Install the standalone scrypt package (required for strong password hashing) - -Thanks to a faulty implementation of the `scrypt` function included in Python’s -`hashlib`, the standalone `scrypt` module is required for stronger-than-default -password hashing, i.e. hash presets greater than `3`. Installing the package is -therefore highly recommended. - -On your online machine, clone the Py-Scrypt source repository: - -```text -$ git clone https://github.com/holgern/py-scrypt.git -``` - -Copy the cloned repo to your offline machine. - -Enter the repo root and edit the file ‘setup.py’, adding the following lines -before the line beginning with `elif sys.platform.startswith('win32'):`, making -sure to preserve indentation: - -```python -elif os.environ.get('MSYSTEM') == 'UCRT64': - define_macros = [] - includes = [] - libraries = ['crypto'] - CFLAGS.append('-O2') -``` - -Save ‘setup.py’. Now build and install: - -```text -$ cd py-scrypt -$ python3 -m build --no-isolation -$ python3 -m pip install --user dist/*.whl -``` - -### 7. Clone and copy the secp256k1 library (offline install only) - -On your online machine, clone the secp256k1 repository from Github: - -```text -$ git clone https://github.com/bitcoin-core/secp256k1.git -``` - -On your offline machine, create a magic location and copy the cloned secp256k1 -directory into it: - -```text -$ mkdir -p ~/.cache/mmgen # the magic location -$ cp -a /path/to/secp256k1/repo/secp256k1 ~/.cache/mmgen -$ ls ~/.cache/mmgen/secp256k1/autogen.sh # check that files were correctly copied -``` - -### 8. Install MMGen - -Now you’re ready to install MMGen itself. On your online machine, clone the -repository: - -```text -$ git clone https://github.com/mmgen/mmgen -Cloning into ’mmgen’... -``` - -If you’re doing an offline install, then copy the cloned mmgen directory to -your offline machine. - -Enter the repo directory, build and install: - -```text -$ cd mmgen -$ git checkout stable_msys2 # See 'Note' below -$ python3 -m build --no-isolation -$ python3 -m pip install --user dist/*.whl -``` - -**Note:** if you want to use features that have appeared since the latest -`stable_msys2` release, then you can omit the `git checkout stable_msys2` -step and remain on the `master` branch. Please bear in mind, however, that -security vulnerabilities are more likely to be present in new code than in a -stable release. In addition, while the tip of `master` is always tested on -Linux before being pushed to the public repository, it’s not guaranteed to -install or run on MSYS2. Installation or runtime issues may also arise due -to missing dependencies or installation steps not yet covered in the -documentation. - -**Install Note:** The `--force` and `--no-deps` options also come in handy on -occasion. Note that MMGen has a test suite. Refer to the [Test Suite][ts] -wiki page for details. - -### 9. Install Python Ethereum dependencies (Ethereum users only) - -If you’ll be using MMGen with Ethereum, then you must install a few -dependencies. From the MMGen repository root, type the following: - -```text -$ python3 -m pip install --no-deps --user -r eth-requirements.txt -``` - -For an offline install, do this instead: - -```text -$ python3 -m pip download --no-deps -r eth-requirements.txt -``` - -Then transfer the downloaded files to your offline machine, `cd` to the -directory containing the files and install them as follows: - -```text -$ python3 -m pip install --no-deps --user *.whl -``` - -### 10. Install and launch your coin daemons - -At this point your MMGen installation will be able to generate wallets, along -with keys and addresses for all supported coins. However, if you intend to do -any transacting, as you probably do, you’ll need to install and launch a coin -daemon or daemons. MMGen has full transaction support for BTC, BCH, LTC, ETH, -ETC and ERC20 tokens. - -Go to the [**Install Bitcoind and other supported coin daemons**][ib] wiki page -and follow the instructions for your coins of choice. You can skip the parts -about adding to the Windows path, since your `PATH` variable was taken care of -in [Step 5](#a_ev). Note that the daemons must be installed on both your -online and offline machines. - -To transact ETH, ETC or ERC20 tokens you’ll need the latest Geth or Parity (for -Ethereum Classic) binary. See the [**Altcoin-and-Forkcoin-Support**][pl] page -for information on downloading and launching these daemons. The `parity.exe` -and `ethkey.exe` binaries should be copied to `/usr/local/bin`. For Geth, -download and run the Windows installer and add `/c/Program Files/Geth` to the -end of the `PATH` variable in your `~/.bashrc` file: - -Please note that Ethereum daemons perform rather poorly under Windows due to -threading limitations. Unless you have very fast hardware, transacting and -syncing the blockchain could be painfully slow. - -### 11. You’re done! - -Congratulations, your installation is now complete, and you can proceed to -[**Getting Started with MMGen**][gs]. Note that all features supported by -MMGen on Linux, except for [autosigning][ax], are now supported on MSYS2 too. -Please be aware of the following, however: - -+ Non-ASCII filenames cannot be used with the `mmgen-xmrwallet` utility. This - is an issue with the Monero wallet RPC daemon rather than MMGen. - -+ The Bitcoin Cash Node daemon cannot handle non-ASCII pathnames. This is an - issue with the Bitcoin Cash Node implementation for Windows, not MMGen. - -## Keeping your installation up to date - -### MSYS2 - -You should periodically upgrade your MSYS2 installation, especially when [new -releases][mh] of the installer appear. You can check your currently installed -version of MSYS2 by issuing the command `pacman -Ss msys2-base`. - -To perform the upgrade, just repeat [Step 3](#a_ug) of this guide. Assuming -your currently configured download mirrors are functional, you can skip the -parts relating to downloading and editing mirrorlists. - -Note that [Step 4](#a_md) need not be performed, as the MMGen dependencies -are already in `pacman`’s database. - -### MMGen - -You should periodically upgrade your MMGen installation from the MMGen public -repository, especially when [new releases][mr] appear. You can check your -currently installed version of MMGen by issuing the command `mmgen-tool ---version`. - -To perform the upgrade, enter the MMGen repository root on your online -computer and issue the following commands: - -```text -$ git checkout master -$ git pull -$ git checkout stable_msys2 # See 'Note' to step 9 -$ rm -rf dist build *egg-info -$ rm -rf /mingw64/lib/python*/site-packages/{mmgen,MMGen}* -$ python3 -m build --no-isolation -$ python3 -m pip install --user dist/*.whl -$ rm -rf dist build *egg-info -``` - -To update your offline installation, copy the updated repository (after `git -pull`) to your offline machine, `cd` to the root of the copied repository and -continue from the `git checkout stable_msys2` step. - -[mh]: https://www.msys2.org -[mp]: https://sourceforge.net/projects/msys2 -[mw]: https://github.com/msys2/msys2/wiki -[ov]: ../releases/tag/v0.9.8 -[sd]: https://download.sysinternals.com/files/SDelete.zip -[mr]: ../releases -[di]: Deprecated-MSWin-Installation -[ib]: Install-Bitcoind -[gs]: Getting-Started-with-MMGen -[pl]: Altcoin-and-Forkcoin-Support#a_oe -[ax]: command-help-autosign -[mc]: Altcoin-and-Forkcoin-Support#a_xmr -[ts]: Test-Suite diff --git a/doc/wiki/Key-address-files.md b/doc/wiki/Key-address-files.md new file mode 100644 index 00000000..c329b6ed --- /dev/null +++ b/doc/wiki/Key-address-files.md @@ -0,0 +1,53 @@ +*NOTE: Key-address files have now been obsoleted by [subwallets][U]. The +information on this page is provided for the benefit of legacy installations +only* + +Chances are you’ll want to use MMGen Wallet not only for cold storage but for +day-to-day transactions too. For this you’ll need to place a portion of your +funds in a “hot wallet” on your online computer. With hot wallet funds you +can use the command `mmgen-txdo` to quickly create, sign and send transactions +in one operation. + +You can partition your wallet by mentally setting aside “hot” and “cold” address +ranges. For example, you might choose to reserve all addresses in the range +1-1000 for cold storage and everything above that for your hot wallet. + +The next step is to create a key-address file for a sufficient number of “hot” +addresses to cover your day-to-day transaction needs for the foreseeable future. +A key-address file is just like an address file except that it contains keys as +well as addresses, thus functioning as a hot wallet for a range of addresses. +Assuming your hot address range begins at 1001, you could start by creating a +key-address file for a hundred hot addresses like this: + +```text +$ mmgen-keygen --type=segwit 1001-1100 +... +Secret keys written to file '89ABCDEF-S[1001-1100].akeys.mmenc' +``` + +`mmgen-keygen` prompts you for a password to encrypt the key-address file with. +This is a wise precaution, as it provides at least some security for keys that +will be stored on an online machine. + +Now copy the key-address file to your online machine and import the addresses +into your tracking wallet: + +```text +$ mmgen-addrimport --batch --keyaddr-file '89ABCDEF-S[1001-1100].akeys.mmenc' +``` + +After funding your hot wallet by spending into some addresses in this range you +can do quickie transactions with these funds using the `mmgen-txdo` command: + +```text +$ mmgen-txdo -M '89ABCDEF-S[1001-1100].akeys.mmenc' 1AmkUxrfy5dMrfmeYwTxLxfIswUCcpeysc,0.1 89ABCDEF:S:1010 +... +Transaction sent: dcea1357.... +``` + +The `--mmgen-keys-from-file` or `-M` option is required when using a key-address +file in place of a wallet. Note that your change address `89ABCDEF:S:1010` is +within the range covered by the key-address file, so your change funds will +remain “hot spendable”. + +[U]: Subwallets.md diff --git a/doc/wiki/MMGen-Wallet-command-help.md b/doc/wiki/MMGen-Wallet-command-help.md new file mode 100644 index 00000000..e67086df --- /dev/null +++ b/doc/wiki/MMGen-Wallet-command-help.md @@ -0,0 +1,26 @@ +* [mmgen-addrgen](commands/command-help-addrgen.md) +* [mmgen-addrimport](commands/command-help-addrimport.md) +* [mmgen-autosign](commands/command-help-autosign.md) +* [mmgen-keygen](commands/command-help-keygen.md) +* [mmgen-msg](commands/command-help-msg.md) +* [mmgen-passchg](commands/command-help-passchg.md) +* [mmgen-passgen](commands/command-help-passgen.md) +* [mmgen-regtest](commands/command-help-regtest.md) +* [mmgen-seedjoin](commands/command-help-seedjoin.md) +* [mmgen-seedsplit](commands/command-help-seedsplit.md) +* [mmgen-subwalletgen](commands/command-help-subwalletgen.md) +* [mmgen-tool](commands/command-help-tool.md) +* [mmgen-tool (usage)][u] +* [mmgen-tool (detailed usage)][d] +* [mmgen-txbump](commands/command-help-txbump.md) +* [mmgen-txcreate](commands/command-help-txcreate.md) +* [mmgen-txdo](commands/command-help-txdo.md) +* [mmgen-txsend](commands/command-help-txsend.md) +* [mmgen-txsign](commands/command-help-txsign.md) +* [mmgen-walletchk](commands/command-help-walletchk.md) +* [mmgen-walletconv](commands/command-help-walletconv.md) +* [mmgen-walletgen](commands/command-help-walletgen.md) +* [mmgen-xmrwallet](commands/command-help-xmrwallet.md) + +[u]: commands/command-help-tool(usage).md +[d]: commands/command-help-tool(detail).md diff --git a/doc/wiki/Unix-commands-and-environment.md b/doc/wiki/Unix-commands-and-environment.md new file mode 100644 index 00000000..0be0cdfd --- /dev/null +++ b/doc/wiki/Unix-commands-and-environment.md @@ -0,0 +1,36 @@ +### Unix commands: a very brief summary + +| Command | Action | +|:--------|:--------------------------------------------------------| +| `ls` | view directory contents (`ls -l` for a long view) | +| `rm` | remove files (`rm -r` to remove entire directory trees) | +| `rmdir` | remove an empty directory | +| `cp` | copy a file (`cp -a` to copy directory trees) | +| `mv` | move a file or directory | +| `cat` | output a file to screen | +| `less` | view a file page-by-page, with scrollback | + +Command help texts can be accessed with the `--help` switch. Directories are +separated by `/`, not `\`. The root of the filesystem is `/`. Drive letter +`C:` is expressed as `/c/`. + +### Environment variables in Unix + +Environmental variables may be viewed with the `env` command. Individual +variables may be viewed like this: + +```text +$ echo $PATH +``` + +and set like this: + +```text +$ PATH=$PATH:/home//bin +``` + +Sometimes variables must be exported to be visible to called programs: + +```text +$ export PATH +``` diff --git a/doc/wiki/commands/command-help-addrgen.md b/doc/wiki/commands/command-help-addrgen.md new file mode 100644 index 00000000..84db9a20 --- /dev/null +++ b/doc/wiki/commands/command-help-addrgen.md @@ -0,0 +1,124 @@ +```text + MMGEN-ADDRGEN: Generate a range or list of addresses from an MMGen wallet, + mnemonic, seed or brainwallet + USAGE: mmgen-addrgen [opts] [seed source] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -c, --print-checksum Print address list checksum and exit + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrase or mnemonic to screen upon entry + -i, --in-fmt f Input is from wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -O, --old-incog-fmt Specify old-format incognito input + -k, --use-internal-keccak-module Force use of the internal keccak module + -K, --keygen-backend n Use backend 'n' for public key generation. Options + for BTC: 1:libsecp256k1 [default] 2:python-ecdsa + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Print addresses to stdout + -t, --type t Choose address type. Options: see ADDRESS TYPES below + (default: 'L' or 'legacy') + -U, --subwallet U Generate addresses for subwallet 'U' (see SUBWALLETS + below) + -v, --verbose Produce more verbose output + + + NOTES FOR THIS COMMAND + + Address indexes are given as a comma-separated list and/or hyphen-separated + range(s). + + If available, the libsecp256k1 library will be used for address generation. + + + NOTES FOR ALL GENERATOR COMMANDS + + SUBWALLETS: + + Subwallets (subseeds) are specified by a ‘Subseed Index’ consisting of: + + a) an integer in the range 1-1000000, plus + b) an optional single letter, ‘L’ or ‘S’ + + The letter designates the length of the subseed. If omitted, ‘L’ is assumed. + + Long (‘L’) subseeds are the same length as their parent wallet’s seed + (typically 256 bits), while short (‘S’) subseeds are always 128-bit. + The long and short subseeds for a given index are derived independently, + so both may be used. + + MMGen Wallet has no notion of ‘depth’, and to an outside observer subwallets + are identical to ordinary wallets. This is a feature rather than a bug, as + it denies an attacker any way of knowing whether a given wallet has a parent. + + Since subwallets are just wallets, they may be used to generate other + subwallets, leading to hierarchies of arbitrary depth. However, this is + inadvisable in practice for two reasons: Firstly, it creates accounting + complexity, requiring the user to independently keep track of a derivation + tree. More importantly, however, it leads to the danger of Seed ID + collisions between subseeds at different levels of the hierarchy, as + MMGen checks and avoids ID collisions only among sibling subseeds. + + An exception to this caveat would be a multi-user setup where sibling + subwallets are distributed to different users as their default wallets. + Since the subseeds derived from these subwallets are private to each user, + Seed ID collisions among them doesn’t present a problem. + + A safe rule of thumb, therefore, is for *each user* to derive all of his/her + subwallets from a single parent. This leaves each user with a total of two + million subwallets, which should be enough for most practical purposes. + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it’s recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + + ADDRESS TYPES: + + Code Type Description + ---- ---- ----------- + ‘L’ legacy - Legacy uncompressed address + ‘C’ compressed - Compressed P2PKH address + ‘S’ segwit - Segwit P2SH-P2WPKH address + ‘B’ bech32 - Native Segwit (Bech32) address + ‘E’ ethereum - Ethereum address + ‘Z’ zcash_z - Zcash z-address + ‘M’ monero - Monero address + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-ADDRGEN(1) +``` diff --git a/doc/wiki/commands/command-help-addrimport.md b/doc/wiki/commands/command-help-addrimport.md new file mode 100644 index 00000000..7a8c965a --- /dev/null +++ b/doc/wiki/commands/command-help-addrimport.md @@ -0,0 +1,35 @@ +```text + MMGEN-ADDRIMPORT: Import addresses into an MMGen tracking wallet + USAGE: mmgen-addrimport [opts] [MMGen address file] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -a, --address a Import the single coin address 'a' + -b, --batch Import all addresses in one RPC call + -l, --addrlist Address source is a flat list of non-MMGen coin addresses + -k, --keyaddr-file Address source is a key-address file + -q, --quiet Suppress warnings + -r, --rescan Update address balances by selectively rescanning the + blockchain for unspent outputs that include the imported + address(es). Required if any of the imported addresses + are already in the blockchain and have a balance. + -t, --token-addr A Import addresses for ERC20 token with address 'A' + + + This command can also be used to update the comment fields or balances of + addresses already in the tracking wallet. + + Rescanning now uses the ‘scantxoutset’ RPC call and a selective scan of + blocks containing the relevant UTXOs for much faster performance than the + previous implementation. The rescan operation typically takes around two + minutes total, independent of the number of addresses imported. + + Bear in mind that the UTXO scan will not find historical transactions: to add + them to the tracking wallet, you must perform a full or partial rescan of the + blockchain with the ‘mmgen-tool rescan_blockchain’ utility. A full rescan of + the blockchain may take up to several hours. + + It’s recommended to use ‘--rpc-backend=aio’ with ‘--rescan’. + + MMGEN v15.1.dev17 February 2025 MMGEN-ADDRIMPORT(1) +``` diff --git a/doc/wiki/commands/command-help-autosign.md b/doc/wiki/commands/command-help-autosign.md new file mode 100644 index 00000000..4af03162 --- /dev/null +++ b/doc/wiki/commands/command-help-autosign.md @@ -0,0 +1,131 @@ +```text + MMGEN-AUTOSIGN: Auto-sign MMGen transactions, message files and XMR wallet output files + USAGE: mmgen-autosign [opts] [operation] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -c, --coins c Coins to sign for (comma-separated list) + -I, --no-insert-check Don’t check for device insertion + -l, --seed-len N Specify wallet seed length of ‘N’ bits (for setup only) + -L, --led Use status LED to signal standby, busy and error + -m, --mountpoint M Specify an alternate mountpoint 'M' + (default: '/mnt/mmgen_autosign') + -M, --mnemonic-fmt F During setup, prompt for mnemonic seed phrase of format + 'F' (choices: 'mmgen','bip39'; default: 'mmgen') + -n, --no-summary Don’t print a transaction summary + -r, --macos-ramdisk-size S Set the size (in MB) of the ramdisk used to store + the offline signing wallet(s) on macOS machines. By + default, a runtime-calculated value will be used. This + option is of interest only for setups with unusually + large Monero wallets + -s, --stealth-led Stealth LED mode - signal busy and error only, and only + after successful authorization. + -S, --full-summary Print a full summary of each signed transaction after + each autosign run. The default list of non-MMGen outputs + will not be printed. + -q, --quiet Produce quieter output + -v, --verbose Produce more verbose output + -w, --wallet-dir D Specify an alternate wallet dir + (default: '/dev/shm/autosign') + -W, --allow-non-wallet-swap Allow signing of swap transactions that send funds + to non-wallet addresses + -x, --xmrwallets L Range or list of wallets to be used for XMR autosigning + + + OPERATIONS + + clean - clean the removable device of unneeded files, removing only non- + essential data + gen_key - generate the wallet encryption key and copy it to the removable + device mounted at mountpoint ‘/mnt/mmgen_autosign’ (as currently + configured) + setup - full setup: run ‘gen_key’ and create temporary signing wallet(s) + for all configured coins + xmr_setup - set up Monero temporary signing wallet(s). Not required during + normal operation: use ‘setup’ with --xmrwallets instead + macos_ramdisk_setup - set up the ramdisk used for storing the temporary signing + wallet(s) (macOS only). Required only when creating the wallet(s) + manually, without ‘setup’ + macos_ramdisk_delete - delete the macOS ramdisk + disable_swap - disable disk swap to prevent potentially sensitive data in + volatile memory from being swapped to disk. Applicable only when + creating temporary signing wallet(s) manually, without ‘setup’ + enable_swap - reenable disk swap. For testing only, should not be invoked in + a production environment + wait - start in loop mode: wait-mount-sign-unmount-wait + wipe_key - wipe the wallet encryption key on the removable device, making + signing transactions or stealing the user’s seed impossible. + The operation is intended as a ‘kill switch’ and thus performed + without prompting + + + USAGE NOTES + + If no operation is specified, this program mounts a removable device + (typically a USB flash drive) containing unsigned MMGen transactions, message + files, and/or XMR wallet output files, signs them, unmounts the removable + device and exits. + + If invoked with ‘wait’, the program waits in a loop, mounting the removable + device, performing signing operations and unmounting the device every time it + is inserted. + + On supported platforms (currently Orange Pi, Rock Pi and Raspberry Pi boards), + the status LED indicates whether the program is busy or in standby mode, i.e. + ready for device insertion or removal. + + The removable device must have a partition with a filesystem labeled MMGEN_TX + and a user-writable root directory. For interoperability between OS-es, it’s + recommended to use the exFAT file system. + + On both the signing and online machines the mountpoint ‘/mnt/mmgen_autosign’ + (as currently configured) must exist. Linux (not macOS) machines must have + an ‘/etc/fstab’ with the following entry: + + LABEL=MMGEN_TX /mnt/mmgen_autosign auto noauto,user 0 0 + + Signing is performed with a temporary wallet created in volatile memory in + the directory ‘/dev/shm/autosign’ (as currently configured). The wallet is + encrypted with a 32-byte password saved in the file ‘autosign.key’ in the + root of the removable device’s filesystem. + + The password and temporary wallet may be created in one operation by invoking + ‘mmgen-autosign setup’ with the removable device inserted. In this case, the + temporary wallet is created from the user’s default wallet, if it exists and + the user so desires. If not, the user is prompted to enter a seed phrase. + + Alternatively, the password and temporary wallet may be created separately by + first invoking ‘mmgen-autosign gen_key’ and then creating and encrypting the + wallet using the -P (--passwd-file) option: + + $ mmgen-walletconv -iwords -d/dev/shm/autosign -p1 -N -P/mnt/mmgen_autosign/autosign.key -Lfoo + + Note that the hash preset must be ‘1’. To use a wallet file as the source + instead of an MMGen seed phrase, omit the ‘-i’ option and add the wallet + file path to the end of the command line. Multiple temporary wallets may + be created in this way and used for signing (note, however, that for XMR + operations only one wallet is supported). + + Autosigning is currently supported on Linux and macOS only. + + + SECURITY NOTE + + By placing wallet and password on separate devices, this program creates + a two-factor authentication setup whereby an attacker must gain physical + control of both the removable device and signing machine in order to sign + transactions. It’s therefore recommended to always keep the removable device + secure, separated from the signing machine and hidden (in your pocket, for + example) when not transacting. In addition, since login access on the + signing machine is required to steal the user’s seed, it’s good practice + to lock the signing machine’s screen once the setup process is complete. + + As a last resort, cutting power to the signing machine will destroy the + volatile memory where the temporary wallet resides and foil any attack, + even if you’ve lost control of the removable device. + + Always remember to power off the signing machine when your signing session + is over. + + MMGEN v15.1.dev17 February 2025 MMGEN-AUTOSIGN(1) +``` diff --git a/doc/wiki/commands/command-help-keygen.md b/doc/wiki/commands/command-help-keygen.md new file mode 100644 index 00000000..4f747731 --- /dev/null +++ b/doc/wiki/commands/command-help-keygen.md @@ -0,0 +1,129 @@ +```text + MMGEN-KEYGEN: Generate a range or list of secret keys from an MMGen wallet, + mnemonic, seed or brainwallet + USAGE: mmgen-keygen [opts] [seed source] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -A, --no-addresses Print only secret keys, no addresses + -c, --print-checksum Print address list checksum and exit + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrase or mnemonic to screen upon entry + -i, --in-fmt f Input is from wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -O, --old-incog-fmt Specify old-format incognito input + -k, --use-internal-keccak-module Force use of the internal keccak module + -K, --keygen-backend n Use backend 'n' for public key generation. Options + for BTC: 1:libsecp256k1 [default] 2:python-ecdsa + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Print keys to stdout + -t, --type t Choose address type. Options: see ADDRESS TYPES below + (default: 'L' or 'legacy') + -U, --subwallet U Generate keys for subwallet 'U' (see SUBWALLETS + below) + -V, --viewkeys Print viewkeys, omitting secret keys + -v, --verbose Produce more verbose output + -x, --b16 Print secret keys in hexadecimal too + + + NOTES FOR THIS COMMAND + + Address indexes are given as a comma-separated list and/or hyphen-separated + range(s). + + By default, both addresses and secret keys are generated. + + If available, the libsecp256k1 library will be used for address generation. + + + NOTES FOR ALL GENERATOR COMMANDS + + SUBWALLETS: + + Subwallets (subseeds) are specified by a ‘Subseed Index’ consisting of: + + a) an integer in the range 1-1000000, plus + b) an optional single letter, ‘L’ or ‘S’ + + The letter designates the length of the subseed. If omitted, ‘L’ is assumed. + + Long (‘L’) subseeds are the same length as their parent wallet’s seed + (typically 256 bits), while short (‘S’) subseeds are always 128-bit. + The long and short subseeds for a given index are derived independently, + so both may be used. + + MMGen Wallet has no notion of ‘depth’, and to an outside observer subwallets + are identical to ordinary wallets. This is a feature rather than a bug, as + it denies an attacker any way of knowing whether a given wallet has a parent. + + Since subwallets are just wallets, they may be used to generate other + subwallets, leading to hierarchies of arbitrary depth. However, this is + inadvisable in practice for two reasons: Firstly, it creates accounting + complexity, requiring the user to independently keep track of a derivation + tree. More importantly, however, it leads to the danger of Seed ID + collisions between subseeds at different levels of the hierarchy, as + MMGen checks and avoids ID collisions only among sibling subseeds. + + An exception to this caveat would be a multi-user setup where sibling + subwallets are distributed to different users as their default wallets. + Since the subseeds derived from these subwallets are private to each user, + Seed ID collisions among them doesn’t present a problem. + + A safe rule of thumb, therefore, is for *each user* to derive all of his/her + subwallets from a single parent. This leaves each user with a total of two + million subwallets, which should be enough for most practical purposes. + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it’s recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + + ADDRESS TYPES: + + Code Type Description + ---- ---- ----------- + ‘L’ legacy - Legacy uncompressed address + ‘C’ compressed - Compressed P2PKH address + ‘S’ segwit - Segwit P2SH-P2WPKH address + ‘B’ bech32 - Native Segwit (Bech32) address + ‘E’ ethereum - Ethereum address + ‘Z’ zcash_z - Zcash z-address + ‘M’ monero - Monero address + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-KEYGEN(1) +``` diff --git a/doc/wiki/commands/command-help-msg.md b/doc/wiki/commands/command-help-msg.md new file mode 100644 index 00000000..fa48fbe1 --- /dev/null +++ b/doc/wiki/commands/command-help-msg.md @@ -0,0 +1,110 @@ +```text + MMGEN-MSG: Perform message signing operations for MMGen addresses + USAGE: mmgen-msg [opts] create MESSAGE_TEXT ADDRESS_SPEC [...] + mmgen-msg [opts] sign MESSAGE_FILE [WALLET_FILE ...] + mmgen-msg [opts] verify MESSAGE_FILE [MMGen ID] + mmgen-msg [opts] verify [address] + mmgen-msg [opts] export MESSAGE_FILE [MMGen ID] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -d, --outdir d Output file to directory 'd' instead of working dir + -t, --msghash-type T Specify the message hash type. Supported values: + 'eth_sign' (ETH default), 'raw' (non-ETH default) + -q, --quiet Produce quieter output + + + SUPPORTED OPERATIONS + + create - create a raw MMGen message file with specified message text for + signing for addresses specified by ADDRESS_SPEC (see ADDRESS + SPECIFIER below) + sign - perform signing operation on an unsigned MMGen message file + verify - verify and display the contents of a signed MMGen message file + export - dump signed MMGen message file to ‘signatures.json’, including only + data relevant for a third-party verifier + + + ADDRESS SPECIFIER + + The `create` operation takes one or more ADDRESS_SPEC arguments with the + following format: + + SEED_ID:ADDRTYPE_CODE:ADDR_IDX_SPEC + + where ADDRTYPE_CODE is a one-letter address type code from the list below, and + ADDR_IDX_SPEC is a comma-separated list of address indexes or hyphen-separated + address index ranges. + + + ADDRESS TYPES: + + Code Type Description + ---- ---- ----------- + ‘L’ legacy - Legacy uncompressed address + ‘C’ compressed - Compressed P2PKH address + ‘S’ segwit - Segwit P2SH-P2WPKH address + ‘B’ bech32 - Native Segwit (Bech32) address + ‘E’ ethereum - Ethereum address + ‘Z’ zcash_z - Zcash z-address + ‘M’ monero - Monero address + + + NOTES + + Message signing operations are supported for Bitcoin, Ethereum and code forks + thereof. + + By default, Ethereum messages are prefixed before hashing in conformity with + the standard defined by the Geth ‘eth_sign’ JSON-RPC call. This behavior may + be overridden with the --msghash-type option. + + Messages signed for Segwit-P2SH addresses cannot be verified directly using + the Bitcoin Core `verifymessage` RPC call, since such addresses are not hashes + of public keys. As a workaround for this limitation, this utility creates for + each Segwit-P2SH address a non-Segwit address with the same public key to be + used for verification purposes. This non-Segwit verifying address should then + be passed on to the verifying party together with the signature. The verifying + party may then use a tool of their choice (e.g. `mmgen-tool addr2pubhash`) to + assure themselves that the verifying address and Segwit address share the same + public key. + + Unfortunately, the aforementioned limitation applies to Segwit-P2PKH (Bech32) + addresses as well, despite the fact that Bech32 addresses are hashes of public + keys (we consider this an implementation shortcoming of `verifymessage`). + Therefore, the above procedure must be followed to verify messages for Bech32 + addresses too. `mmgen-tool addr2pubhash` or `bitcoin-cli validateaddress` + may then be used to demonstrate that the two addresses share the same public + key. + + + EXAMPLES + + Create a raw message file for the specified message and specified addresses, + where DEADBEEF is the Seed ID of the user’s default wallet and BEEFCAFE one + of its subwallets: + $ mmgen-msg create '16/3/2022 Earthquake strikes Fukushima coast' DEADBEEF:B:1-3,10,98 BEEFCAFE:S:3,9 + + Sign the raw message file created by the previous step: + $ mmgen-msg sign + + Sign the raw message file using an explicitly supplied wallet: + $ mmgen-msg sign DEADBEEF.bip39 + + Verify and display all signatures in the signed message file: + $ mmgen-msg verify + + Verify and display a single signature in the signed message file: + $ mmgen-msg verify DEADBEEF:B:98 + + Export data relevant for a third-party verifier to ‘signatures.json’: + $ mmgen-msg export + + Same as above, but export only one signature: + $ mmgen-msg export DEADBEEF:B:98 + + Verify and display the exported JSON signature data: + $ mmgen-msg verify signatures.json + + MMGEN v15.1.dev17 February 2025 MMGEN-MSG(1) +``` diff --git a/doc/wiki/commands/command-help-passchg.md b/doc/wiki/commands/command-help-passchg.md new file mode 100644 index 00000000..31864204 --- /dev/null +++ b/doc/wiki/commands/command-help-passchg.md @@ -0,0 +1,57 @@ +```text + MMGEN-PASSCHG: Change the passphrase, hash preset or label of the default or specified MMGen wallet + USAGE: mmgen-passchg [opts] [infile] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrases and other user input to screen + -f, --force-update Force update of wallet even if nothing has changed + -i, --in-fmt f Input from wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -O, --old-incog-fmt Specify old-format incognito input + -k, --keep-passphrase Reuse passphrase of input wallet for output wallet + -K, --keep-hash-preset Reuse hash preset of input wallet for output wallet + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -L, --label l Specify a label 'l' for output wallet + -m, --keep-label Reuse label of input wallet for output wallet + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -N, --passwd-file-new-only Use passwd file only for new, not existing, wallet + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Write wallet data to stdout instead of file + -v, --verbose Produce more verbose output + + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-PASSCHG(1) +``` diff --git a/doc/wiki/commands/command-help-passgen.md b/doc/wiki/commands/command-help-passgen.md new file mode 100644 index 00000000..a5887146 --- /dev/null +++ b/doc/wiki/commands/command-help-passgen.md @@ -0,0 +1,105 @@ +```text + MMGEN-PASSGEN: Generate a range or list of passwords from an MMGen wallet, + mnemonic, seed or brainwallet for the given ID string + USAGE: mmgen-passgen [opts] [seed source] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrase or mnemonic to screen upon entry + -f, --passwd-fmt f Generate passwords of format 'f'. Default: b58. + See PASSWORD FORMATS below + -i, --in-fmt f Input is from wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -O, --old-incog-fmt Specify old-format incognito input + -L, --passwd-len l Specify length of generated passwords. For defaults, + see PASSWORD FORMATS below. An argument of 'h' will + generate passwords of half the default length. + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Print passwords to stdout + -v, --verbose Produce more verbose output + + + NOTES FOR THIS COMMAND + + ID string must be a valid UTF-8 string not longer than 256 characters and + not containing the symbols ' ", ":", "/", "\'. + + Password indexes are given as a comma-separated list and/or hyphen-separated + range(s). + + Changing either the password format (base32,base58) or length alters the seed + and thus generates a completely new set of passwords. + + PASSWORD FORMATS: + + Code Description Min Len Max Len Default Len + b32 - base32 password 10 42 24 + b58 - base58 password 8 36 20 + bip39 - BIP39 mnemonic 12 24 24 + xmrseed - Monero new-style mnemonic 25 25 25 + hex - hexadecimal password 32 64 64 + + EXAMPLES: + + Generate ten base58 passwords of length 20 for Alice's email account: + mmgen-passgen alice@nowhere.com 1-10 + + Generate ten base58 passwords of length 16 for Alice's email account: + mmgen-passgen --passwd-len=16 alice@nowhere.com 1-10 + + Generate ten base32 passwords of length 24 for Alice's email account: + mmgen-passgen --passwd-fmt=b32 alice@nowhere.com 1-10 + + Generate three BIP39 mnemonic seed phrases of length 24 for Alice's + Trezor device: + mmgen-passgen --passwd-fmt=bip39 mytrezor 1-3 + + All passwords are cryptographically unlinkable with each other, including + passwords with the same format but different length, so Alice needn't worry + about inadvertent reuse of private data. + + + NOTES FOR ALL GENERATOR COMMANDS + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it’s recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-PASSGEN(1) +``` diff --git a/doc/wiki/commands/command-help-regtest.md b/doc/wiki/commands/command-help-regtest.md new file mode 100644 index 00000000..15250442 --- /dev/null +++ b/doc/wiki/commands/command-help-regtest.md @@ -0,0 +1,29 @@ +```text + MMGEN-REGTEST: Coin daemon regression test mode setup and operations for the MMGen suite + USAGE: mmgen-regtest [opts] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -b, --bdb-wallet Create and use a legacy Berkeley DB coin daemon wallet + -e, --empty Don't fund Bob and Alice's wallets on setup + -n, --setup-no-stop-daemon Don't stop daemon after setup is finished + -q, --quiet Produce quieter output + -v, --verbose Produce more verbose output + + + AVAILABLE COMMANDS + + setup - set up Bob and Alice regtest mode + start - start the regtest coin daemon + stop - stop the regtest coin daemon + generate N - mine N blocks (defaults to 1) + send ADDR AMT - send amount AMT of miner funds to address ADDR + state - show current state of daemon (ready, busy, or stopped) + balances - get Bob and Alice's balances + mempool - show transaction IDs in mempool + cli - execute an RPC call with supplied arguments + wallet_cli - execute a wallet RPC call with supplied arguments (wallet + is first argument) + + MMGEN v15.1.dev17 February 2025 MMGEN-REGTEST(1) +``` diff --git a/doc/wiki/commands/command-help-seedjoin.md b/doc/wiki/commands/command-help-seedjoin.md new file mode 100644 index 00000000..1542158a --- /dev/null +++ b/doc/wiki/commands/command-help-seedjoin.md @@ -0,0 +1,66 @@ +```text + MMGEN-SEEDJOIN: Regenerate an MMGen deterministic wallet from seed shares + created by 'mmgen-seedsplit' + USAGE: mmgen-seedjoin [options] share1 share2 [...shareN] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -d, --outdir d Output file to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrases and other user input to screen + -i, --id-str s ID String of split (required for master share join only) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated). NOTE: only the + first share may be in hidden incognito format! + -J, --hidden-incog-output-params f,o Write hidden incognito data to file + 'f' at offset 'o' (comma-separated). File 'f' will be + created if necessary and filled with random data. + -o, --out-fmt f Output to wallet format 'f' (see FMT CODES below) + -O, --old-incog-fmt Specify old-format incognito input + -L, --label l Specify a label 'l' for output wallet + -M, --master-share i Use a master share with index 'i' (min:1, max:1024) + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Write wallet data to stdout instead of file + -v, --verbose Produce more verbose output + + + COMMAND NOTES: + + When joining with a master share, the master share must be listed first. + The remaining shares may be listed in any order. + + The --id-str option is required only for master share joins. For ordinary + joins it will be ignored. + + For usage examples, see the help screen for the 'mmgen-seedsplit' command. + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-SEEDJOIN(1) +``` diff --git a/doc/wiki/commands/command-help-seedsplit.md b/doc/wiki/commands/command-help-seedsplit.md new file mode 100644 index 00000000..2e65c45d --- /dev/null +++ b/doc/wiki/commands/command-help-seedsplit.md @@ -0,0 +1,148 @@ +```text + MMGEN-SEEDSPLIT: Generate a seed share from the default or specified MMGen wallet + USAGE: mmgen-seedsplit [opts] [infile] [:]: + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrases and other user input to screen + -i, --in-fmt f Input from wallet format 'f' (see FMT CODES below) + -o, --out-fmt f Output to wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -J, --hidden-incog-output-params f,o Write hidden incognito data to file + 'f' at offset 'o' (comma-separated). File 'f' will be + created if necessary and filled with random data. + -O, --old-incog-fmt Specify old-format incognito input + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -L, --label l Specify a label 'l' for output wallet + -M, --master-share i Use a master share with index 'i' (min:1, max:1024) + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -N, --passwd-file-new-only Use passwd file only for new, not existing, wallet + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Write wallet data to stdout instead of file + -v, --verbose Produce more verbose output + + + COMMAND NOTES: + + This command generates shares one at a time. Shares may be output to any + MMGen wallet format, with one limitation: only one share in a given split may + be in hidden incognito format, and it must be the master share in the case of + a master-share split. + + If the command's optional first argument is omitted, the default wallet is + used for the split. + + The last argument is a seed split specifier consisting of an optional split + ID, a share index, and a share count, all separated by colons. The split ID + must be a valid UTF-8 string. If omitted, the ID 'default' is used. The + share index (the index of the share being generated) must be in the range + 1-1024 and the share count (the total number of shares in the split) + in the range 2-1024. + + Master Shares + + Each seed has a total of 1024 master shares, which can be used as the first + shares in multiple splits if desired. To generate a master share, use the + --master-share (-M) option with an index in the range 1-1024 and omit + the last argument. + + When creating and joining a split using a master share, ensure that the same + master share index is used in all split and join commands. + + EXAMPLES: + + Split a BIP39 seed phrase into two BIP39 shares. Rejoin the split: + + $ echo 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' > sample.bip39 + + $ mmgen-seedsplit -o bip39 sample.bip39 1:2 + BIP39 mnemonic data written to file '03BAE887-default-1of2[D51CB683][128].bip39' + + $ mmgen-seedsplit -o bip39 sample.bip39 2:2 + BIP39 mnemonic data written to file '03BAE887-default-2of2[67BFD36E][128].bip39' + + $ mmgen-seedjoin -o bip39 \ + '03BAE887-default-2of2[67BFD36E][128].bip39' \ + '03BAE887-default-1of2[D51CB683][128].bip39' + BIP39 mnemonic data written to file '03BAE887[128].bip39' + + $ cat '03BAE887[128].bip39' + zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong + + Create a 3-way default split of your default wallet, outputting all shares + to default wallet format. Rejoin the split: + + $ mmgen-seedsplit 1:3 # Step A + $ mmgen-seedsplit 2:3 # Step B + $ mmgen-seedsplit 3:3 # Step C + $ mmgen-seedjoin + + Create a 2-way split of your default wallet with ID string 'alice', + outputting shares to MMGen native mnemonic format. Rejoin the split: + + $ mmgen-seedsplit -o words alice:1:2 # Step D + $ mmgen-seedsplit -o words alice:2:2 # Step E + $ mmgen-seedjoin + + Create a 2-way split of your default wallet with ID string 'bob' using + master share #7, outputting share #1 (the master share) to default wallet + format and share #2 to BIP39 format. Rejoin the split: + + $ mmgen-seedsplit -M7 # Step X + $ mmgen-seedsplit -M7 -o bip39 bob:2:2 # Step Y + $ mmgen-seedjoin -M7 --id-str=bob + + Create a 2-way split of your default wallet with ID string 'alice' using + master share #7. Rejoin the split using master share #7 generated in the + previous example: + + $ mmgen-seedsplit -M7 -o bip39 alice:2:2 # Step Z + $ mmgen-seedjoin -M7 --id-str=alice + + Create a 2-way default split of your default wallet with an incognito-format + master share hidden in file 'my.hincog' at offset 1325. Rejoin the split: + + $ mmgen-seedsplit -M4 -o hincog -J my.hincog,1325 1:2 # Step M (share A) + $ mmgen-seedsplit -M4 -o bip39 2:2 # Step N (share B) + $ mmgen-seedjoin -M4 -H my.hincog,1325 + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it’s recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-SEEDSPLIT(1) +``` diff --git a/doc/wiki/commands/command-help-subwalletgen.md b/doc/wiki/commands/command-help-subwalletgen.md new file mode 100644 index 00000000..117d254c --- /dev/null +++ b/doc/wiki/commands/command-help-subwalletgen.md @@ -0,0 +1,101 @@ +```text + MMGEN-SUBWALLETGEN: Generate a subwallet from the default or specified MMGen wallet + USAGE: mmgen-subwalletgen [opts] [infile] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrases and other user input to screen + -i, --in-fmt f Input from wallet format 'f' (see FMT CODES below) + -o, --out-fmt f Output to wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -J, --hidden-incog-output-params f,o Write hidden incognito data to file + 'f' at offset 'o' (comma-separated). File 'f' will be + created if necessary and filled with random data. + -O, --old-incog-fmt Specify old-format incognito input + -k, --keep-passphrase Reuse passphrase of input wallet for output wallet + -K, --keep-hash-preset Reuse hash preset of input wallet for output wallet + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -L, --label l Specify a label 'l' for output wallet + -m, --keep-label Reuse label of input wallet for output wallet + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -N, --passwd-file-new-only Use passwd file only for new, not existing, wallet + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Write wallet data to stdout instead of file + -v, --verbose Produce more verbose output + + + SUBWALLETS: + + Subwallets (subseeds) are specified by a ‘Subseed Index’ consisting of: + + a) an integer in the range 1-1000000, plus + b) an optional single letter, ‘L’ or ‘S’ + + The letter designates the length of the subseed. If omitted, ‘L’ is assumed. + + Long (‘L’) subseeds are the same length as their parent wallet’s seed + (typically 256 bits), while short (‘S’) subseeds are always 128-bit. + The long and short subseeds for a given index are derived independently, + so both may be used. + + MMGen Wallet has no notion of ‘depth’, and to an outside observer subwallets + are identical to ordinary wallets. This is a feature rather than a bug, as + it denies an attacker any way of knowing whether a given wallet has a parent. + + Since subwallets are just wallets, they may be used to generate other + subwallets, leading to hierarchies of arbitrary depth. However, this is + inadvisable in practice for two reasons: Firstly, it creates accounting + complexity, requiring the user to independently keep track of a derivation + tree. More importantly, however, it leads to the danger of Seed ID + collisions between subseeds at different levels of the hierarchy, as + MMGen checks and avoids ID collisions only among sibling subseeds. + + An exception to this caveat would be a multi-user setup where sibling + subwallets are distributed to different users as their default wallets. + Since the subseeds derived from these subwallets are private to each user, + Seed ID collisions among them doesn’t present a problem. + + A safe rule of thumb, therefore, is for *each user* to derive all of his/her + subwallets from a single parent. This leaves each user with a total of two + million subwallets, which should be enough for most practical purposes. + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it’s recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-SUBWALLETGEN(1) +``` diff --git a/doc/wiki/commands/command-help-swaptxcreate.md b/doc/wiki/commands/command-help-swaptxcreate.md new file mode 100644 index 00000000..2cae10cc --- /dev/null +++ b/doc/wiki/commands/command-help-swaptxcreate.md @@ -0,0 +1,179 @@ +```text + MMGEN-SWAPTXCREATE: Create a DEX swap transaction from one MMGen tracking wallet to another + USAGE: mmgen-swaptxcreate [opts] COIN1 [AMT CHG_ADDR] COIN2 [ADDR] [addr file ...] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -a, --autosign Create a transaction for offline autosigning (see + ‘mmgen-autosign’). The removable device is mounted and + unmounted automatically + -A, --fee-adjust f Adjust transaction fee by factor 'f' (see below) + -B, --no-blank Don't blank screen before displaying unspent outputs + -c, --comment-file f Source the transaction's comment from file 'f' + -C, --fee-estimate-confs c Desired number of confirmations for fee estimation + (default: 3) + -d, --outdir d Specify an alternate directory 'd' for output + -E, --fee-estimate-mode M Specify the network fee estimate mode. Choices: + 'conservative','economical'. Default: 'conservative' + -f, --fee f Transaction fee, as a decimal BTC amount or as + satoshis per byte (an integer followed by 's'). + See FEE SPECIFICATION below. If omitted, fee will be + calculated using network fee estimation. + -i, --info Display unspent outputs and exit + -I, --inputs i Specify transaction inputs (comma-separated list of + MMGen IDs or coin addresses). Note that ALL unspent + outputs associated with each address will be included. + -L, --autochg-ignore-labels Ignore labels when autoselecting change addresses + -m, --minconf n Minimum number of confirmations required to spend + outputs (default: 1) + -q, --quiet Suppress warnings; overwrite files without prompting + -s, --swap-proto Swap protocol to use (Default: thorchain, + Choices: 'thorchain') + -v, --verbose Produce more verbose output + -V, --vsize-adj f Adjust transaction's estimated vsize by factor 'f' + -x, --proxy P Fetch the swap quote via SOCKS5 proxy ‘P’ (host:port) + -y, --yes Answer 'yes' to prompts, suppress non-essential output + + + This script is similar in operation to ‘mmgen-txcreate’, only with additional + steps. Users are advised to first familiarize themselves with the use of that + script before attempting to perform a swap with this one. + + The tracking wallets of both the send and receive coins must be available when + the script is invoked. If the two coin daemons are running on different hosts + than the script, or with non-standard ports, coin-specific RPC options may be + required (see EXAMPLES below). + + The swap protocol’s quote server on the Internet must be reachable either + directly or via the SOCKS5 proxy specified with the --proxy option. To improve + privacy, it’s recommended to proxy requests to the quote server via Tor or + some other anonymity network. + + The resulting transaction file is saved, signed, sent, and optionally bumped, + exactly the same way as one created with ‘mmgen-txcreate’. Autosign with + automount is likewise supported via the --autosign option. + + The command line must contain at minimum a send coin (COIN1) and receive coin + (COIN2) symbol. Currently supported coins are BTC, LTC and BCH. All other + arguments are optional. If AMT is specified, the specified value of send coin + will be swapped and the rest returned to a change address in the originating + tracking wallet. Otherwise, the entire value of the interactively selected + inputs will be swapped. + + By default, the change and destination addresses are chosen automatically by + finding the lowest-indexed unused addresses of the preferred address types in + the send and receive tracking wallets. Types ‘B’, ‘S’ and ‘C’ (see ADDRESS + TYPES below) are searched in that order for unused addresses. + + If the wallet contains eligible unused addresses with multiple Seed IDs, the + user will be presented with a list of the lowest-indexed addresses of + preferred type for each Seed ID and prompted to choose from among them. + + Change and destination addresses may also be specified manually with the + CHG_ADDR and ADDR arguments. These may be given as full MMGen IDs or in the + form ADDRTYPE_CODE or SEED_ID:ADDRTYPE_CODE (see EXAMPLES below and the + ‘mmgen-txcreate’ help screen for details). + + While discouraged, sending change or swapping to non-wallet addresses is also + supported, in which case the signing script (‘mmgen-txsign’ or ‘mmgen- + autosign’, as applicable) must be invoked with the --allow-non-wallet-swap + option. + + Rather than specifying a transaction fee on the command line, it’s advisable + to start with the fee suggested by the swap protocol quote server (the script + does this automatically) and then adjust the fee interactively if desired. + + When choosing a fee, bear in mind that the longer the transaction remains + unconfirmed, the greater the risk that the vault address will expire, leading + to loss of funds. It’s therefore advisable to learn how to create, sign and + send replacement transactions with ‘mmgen-txbump’ before performing a swap + with this script. When bumping a stuck swap transaction, the safest option + is to create a replacement transaction with one output that returns funds back + to the originating tracking wallet, thus aborting the swap, rather than one + that merely increases the fee (see EXAMPLES below). + + Before broadcasting the transaction, it’s advisable to double-check the vault + address on a block explorer such as thorchain.net or runescan.io. + + The MMGen Node Tools suite contains two useful tools to help with fine-tuning + transaction fees, ‘mmnode-feeview’ and ‘mmnode-blocks-info’, in addition to + ‘mmnode-ticker’, which can be used to calculate the current cross-rate between + the asset pair of a swap, as well as the total receive value in terms of the + send value. + + + ADDRESS TYPES: + + Code Type Description + ---- ---- ----------- + ‘L’ legacy - Legacy uncompressed address + ‘C’ compressed - Compressed P2PKH address + ‘S’ segwit - Segwit P2SH-P2WPKH address + ‘B’ bech32 - Native Segwit (Bech32) address + ‘E’ ethereum - Ethereum address + ‘Z’ zcash_z - Zcash z-address + ‘M’ monero - Monero address + + + FEE SPECIFICATION + + Transaction fees, both on the command line and at the interactive prompt, may + be specified as either absolute BTC amounts, using a plain decimal number, or + as satoshis per byte, using an integer followed by 's', for satoshi. + + + EXAMPLES: + + Create a BTC-to-LTC swap transaction, prompting the user for transaction + inputs. The full value of the inputs, minus miner fees, will be swapped + and sent to an unused address in the user’s LTC tracking wallet: + + $ mmgen-swaptxcreate BTC LTC + + Same as above, but swap 0.123 BTC, minus miner fees, and send the change to + an unused address in the BTC tracking wallet: + + $ mmgen-swaptxcreate BTC 0.123 LTC + + Same as above, but specify that the change address be a Segwit P2SH (‘S’) + address: + + $ mmgen-swaptxcreate BTC 0.123 S LTC + + Same as above, but additionally specify that the destination LTC address be + a compressed P2PKH (‘C’) address: + + $ mmgen-swaptxcreate BTC 0.123 S LTC C + + Same as above, but specify the BTC change address explicitly and the + destination LTC address by Seed ID and address type: + + $ mmgen-swaptxcreate BTC 0.123 BEADCAFE:S:6 LTC BEADCAFE:C + + Abort the above swap by creating a replacement transaction that returns the + funds to the originating tracking wallet (omit the transaction filename if + using --autosign): + + $ mmgen-txbump BEADCAFE:S:6 [raw transaction file] + + Swap 0.123 BTC to a non-wallet address (not recommended): + + $ mmgen-swaptxcreate BTC 0.123 LTC ltc1qaq8t3pakcftpk095tnqfv5cmmczysls0xx9388 + + Create an LTC-to-BCH swap transaction, with the Litecoin daemon running on + host ‘orion’ and Bitcoin Cash Node daemon on host ‘gemini’ with non-standard + RPC port 8332. Communicate with the swap quote server via Tor. + + $ mmgen-swaptxcreate --ltc-rpc-host=orion --bch-rpc-host=gemini --bch-rpc-port=8332 --proxy=localhost:9050 LTC BCH + + After sending, check the status of the above swap’s LTC deposit transaction + (omit the transaction filename if using --autosign): + + $ mmgen-txsend --ltc-rpc-host=orion --status [transaction file] + + Check whether the funds have arrived in the BCH destination wallet: + + $ mmgen-tool --coin=bch --bch-rpc-host=gemini twview minconf=0 + + MMGEN v15.1.dev17 February 2025 MMGEN-SWAPTXCREATE(1) +``` diff --git a/doc/wiki/commands/command-help-swaptxdo.md b/doc/wiki/commands/command-help-swaptxdo.md new file mode 100644 index 00000000..12de8d54 --- /dev/null +++ b/doc/wiki/commands/command-help-swaptxdo.md @@ -0,0 +1,243 @@ +```text + MMGEN-SWAPTXDO: Create, sign and send a DEX swap transaction from one MMGen tracking wallet to another + USAGE: mmgen-swaptxdo [opts] COIN1 [AMT CHG_ADDR] COIN2 [ADDR] [addr file ...] [seed source ...] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -A, --fee-adjust f Adjust transaction fee by factor 'f' (see below) + -b, --brain-params l,p Use seed length 'l' and hash preset 'p' for + brainwallet input + -B, --no-blank Don't blank screen before displaying unspent outputs + -c, --comment-file f Source the transaction's comment from file 'f' + -C, --fee-estimate-confs c Desired number of confirmations for fee estimation + (default: 3) + -d, --outdir d Specify an alternate directory 'd' for output + -e, --echo-passphrase Print passphrase to screen when typing it + -E, --fee-estimate-mode M Specify the network fee estimate mode. Choices: + 'conservative','economical'. Default: 'conservative' + -f, --fee f Transaction fee, as a decimal BTC amount or as + satoshis per byte (an integer followed by 's'). + See FEE SPECIFICATION below. If omitted, fee will be + calculated using network fee estimation. + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -i, --in-fmt f Input is from wallet format 'f' (see FMT CODES below) + -I, --inputs i Specify transaction inputs (comma-separated list of + MMGen IDs or coin addresses). Note that ALL unspent + outputs associated with each address will be included. + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -k, --keys-from-file f Provide additional keys for non-MMGen addresses + -K, --keygen-backend n Use backend 'n' for public key generation. Options + for BTC: 1:libsecp256k1 [default] 2:python-ecdsa + -L, --autochg-ignore-labels Ignore labels when autoselecting change addresses + -m, --minconf n Minimum number of confirmations required to spend + outputs (default: 1) + -M, --mmgen-keys-from-file f Provide keys for MMGen addresses in a key- + address file (output of 'mmgen-keygen'). Permits + online signing without an MMGen seed source. The + key-address file is also used to verify MMGen-to-BTC + mappings, so the user should record its checksum. + -O, --old-incog-fmt Specify old-format incognito input + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -P, --passwd-file f Get MMGen wallet passphrase from file 'f' + -q, --quiet Suppress warnings; overwrite files without prompting + -s, --swap-proto Swap protocol to use (Default: thorchain, + Choices: 'thorchain') + -u, --subseeds n The number of subseed pairs to scan for (default: 100, + maximum: 1000000). Only the default or first supplied + wallet is scanned for subseeds. + -v, --verbose Produce more verbose output + -V, --vsize-adj f Adjust transaction's estimated vsize by factor 'f' + -x, --proxy P Fetch the swap quote via SOCKS5 proxy ‘P’ (host:port) + -y, --yes Answer 'yes' to prompts, suppress non-essential output + -z, --show-hash-presets Show information on available hash presets + + + This script is similar in operation to ‘mmgen-txcreate’, only with additional + steps. Users are advised to first familiarize themselves with the use of that + script before attempting to perform a swap with this one. + + The tracking wallets of both the send and receive coins must be available when + the script is invoked. If the two coin daemons are running on different hosts + than the script, or with non-standard ports, coin-specific RPC options may be + required (see EXAMPLES below). + + The swap protocol’s quote server on the Internet must be reachable either + directly or via the SOCKS5 proxy specified with the --proxy option. To improve + privacy, it’s recommended to proxy requests to the quote server via Tor or + some other anonymity network. + + The resulting transaction file is saved, signed, sent, and optionally bumped, + exactly the same way as one created with ‘mmgen-txcreate’. Autosign with + automount is likewise supported via the --autosign option. + + The command line must contain at minimum a send coin (COIN1) and receive coin + (COIN2) symbol. Currently supported coins are BTC, LTC and BCH. All other + arguments are optional. If AMT is specified, the specified value of send coin + will be swapped and the rest returned to a change address in the originating + tracking wallet. Otherwise, the entire value of the interactively selected + inputs will be swapped. + + By default, the change and destination addresses are chosen automatically by + finding the lowest-indexed unused addresses of the preferred address types in + the send and receive tracking wallets. Types ‘B’, ‘S’ and ‘C’ (see ADDRESS + TYPES below) are searched in that order for unused addresses. + + If the wallet contains eligible unused addresses with multiple Seed IDs, the + user will be presented with a list of the lowest-indexed addresses of + preferred type for each Seed ID and prompted to choose from among them. + + Change and destination addresses may also be specified manually with the + CHG_ADDR and ADDR arguments. These may be given as full MMGen IDs or in the + form ADDRTYPE_CODE or SEED_ID:ADDRTYPE_CODE (see EXAMPLES below and the + ‘mmgen-txcreate’ help screen for details). + + While discouraged, sending change or swapping to non-wallet addresses is also + supported, in which case the signing script (‘mmgen-txsign’ or ‘mmgen- + autosign’, as applicable) must be invoked with the --allow-non-wallet-swap + option. + + Rather than specifying a transaction fee on the command line, it’s advisable + to start with the fee suggested by the swap protocol quote server (the script + does this automatically) and then adjust the fee interactively if desired. + + When choosing a fee, bear in mind that the longer the transaction remains + unconfirmed, the greater the risk that the vault address will expire, leading + to loss of funds. It’s therefore advisable to learn how to create, sign and + send replacement transactions with ‘mmgen-txbump’ before performing a swap + with this script. When bumping a stuck swap transaction, the safest option + is to create a replacement transaction with one output that returns funds back + to the originating tracking wallet, thus aborting the swap, rather than one + that merely increases the fee (see EXAMPLES below). + + Before broadcasting the transaction, it’s advisable to double-check the vault + address on a block explorer such as thorchain.net or runescan.io. + + The MMGen Node Tools suite contains two useful tools to help with fine-tuning + transaction fees, ‘mmnode-feeview’ and ‘mmnode-blocks-info’, in addition to + ‘mmnode-ticker’, which can be used to calculate the current cross-rate between + the asset pair of a swap, as well as the total receive value in terms of the + send value. + + + ADDRESS TYPES: + + Code Type Description + ---- ---- ----------- + ‘L’ legacy - Legacy uncompressed address + ‘C’ compressed - Compressed P2PKH address + ‘S’ segwit - Segwit P2SH-P2WPKH address + ‘B’ bech32 - Native Segwit (Bech32) address + ‘E’ ethereum - Ethereum address + ‘Z’ zcash_z - Zcash z-address + ‘M’ monero - Monero address + + + FEE SPECIFICATION + + Transaction fees, both on the command line and at the interactive prompt, may + be specified as either absolute BTC amounts, using a plain decimal number, or + as satoshis per byte, using an integer followed by 's', for satoshi. + + + SIGNING NOTES + + Transactions may contain both MMGen or non-MMGen input addresses. + + To sign non-MMGen inputs, a bitcoind wallet dump or flat key list is used + as the key source (--keys-from-file option). + + To sign MMGen inputs, key data is generated from a seed as with the + mmgen-addrgen and mmgen-keygen commands. Alternatively, a key-address file + may be used (--mmgen-keys-from-file option). + + Multiple wallets or other seed files can be listed on the command line in + any order. If the seeds required to sign the transaction’s inputs are not + found in these files (or in the default wallet), the user will be prompted + for seed data interactively. + + To prevent an attacker from crafting transactions with bogus MMGen-to-Bitcoin + address mappings, all outputs to MMGen addresses are verified with a seed + source. Therefore, seed files or a key-address file for all MMGen outputs + must also be supplied on the command line if the data can’t be found in the + default wallet. + + Seed source files must have the canonical extensions listed in the 'FileExt' + column below: + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + + EXAMPLES: + + Create a BTC-to-LTC swap transaction, prompting the user for transaction + inputs. The full value of the inputs, minus miner fees, will be swapped + and sent to an unused address in the user’s LTC tracking wallet: + + $ mmgen-swaptxdo BTC LTC + + Same as above, but swap 0.123 BTC, minus miner fees, and send the change to + an unused address in the BTC tracking wallet: + + $ mmgen-swaptxdo BTC 0.123 LTC + + Same as above, but specify that the change address be a Segwit P2SH (‘S’) + address: + + $ mmgen-swaptxdo BTC 0.123 S LTC + + Same as above, but additionally specify that the destination LTC address be + a compressed P2PKH (‘C’) address: + + $ mmgen-swaptxdo BTC 0.123 S LTC C + + Same as above, but specify the BTC change address explicitly and the + destination LTC address by Seed ID and address type: + + $ mmgen-swaptxdo BTC 0.123 BEADCAFE:S:6 LTC BEADCAFE:C + + Abort the above swap by creating a replacement transaction that returns the + funds to the originating tracking wallet (omit the transaction filename if + using --autosign): + + $ mmgen-txbump BEADCAFE:S:6 [raw transaction file] + + Swap 0.123 BTC to a non-wallet address (not recommended): + + $ mmgen-swaptxdo BTC 0.123 LTC ltc1qaq8t3pakcftpk095tnqfv5cmmczysls0xx9388 + + Create an LTC-to-BCH swap transaction, with the Litecoin daemon running on + host ‘orion’ and Bitcoin Cash Node daemon on host ‘gemini’ with non-standard + RPC port 8332. Communicate with the swap quote server via Tor. + + $ mmgen-swaptxdo --ltc-rpc-host=orion --bch-rpc-host=gemini --bch-rpc-port=8332 --proxy=localhost:9050 LTC BCH + + After sending, check the status of the above swap’s LTC deposit transaction + (omit the transaction filename if using --autosign): + + $ mmgen-txsend --ltc-rpc-host=orion --status [transaction file] + + Check whether the funds have arrived in the BCH destination wallet: + + $ mmgen-tool --coin=bch --bch-rpc-host=gemini twview minconf=0 + + MMGEN v15.1.dev17 February 2025 MMGEN-SWAPTXDO(1) +``` diff --git a/doc/wiki/commands/command-help-tool(detail).md b/doc/wiki/commands/command-help-tool(detail).md new file mode 100644 index 00000000..50e734c0 --- /dev/null +++ b/doc/wiki/commands/command-help-tool(detail).md @@ -0,0 +1,1244 @@ +# Detailed usage information for `mmgen-tool` commands + +## Table of Contents +* [General string conversion and hashing utilities](#a_1) +* [Cryptocoin key/address utilities](#a_2) +* [Seed phrase utilities](#a_3) +* [Utilities for viewing/checking MMGen address and transaction files](#a_4) +* [File encryption and decryption](#a_5) +* [File utilities](#a_6) +* [Key, address or subseed generation from an MMGen wallet](#a_7) +* [Tracking-wallet commands using the JSON-RPC interface](#a_8) + +## General string conversion and hashing utilities: + +### `mmgen-tool b32tohex` + +```text +Convert an MMGen-flavor base 32 string to hexadecimal + +USAGE: mmgen-tool [OPTS] b32tohex ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + b32_str [str] (use '-' to read from STDIN) + +Optional KEYWORD ARG (type and default value shown in square brackets): + + pad [int=0] Pad output to this width +``` + +### `mmgen-tool b58chktohex` + +```text +Convert a base58-check encoded string to hexadecimal + +USAGE: mmgen-tool [OPTS] b58chktohex ARG + +Required ARG (type shown in square brackets): + + b58chk_str [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool b58tobytes` + +```text +Convert a base 58 string to bytes (warning: outputs binary data) + +USAGE: mmgen-tool [OPTS] b58tobytes ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + b58_str [str] (use '-' to read from STDIN) + +Optional KEYWORD ARG (type and default value shown in square brackets): + + pad [int=0] Pad output to this width +``` + +### `mmgen-tool b58tohex` + +```text +Convert a base 58 string to hexadecimal + +USAGE: mmgen-tool [OPTS] b58tohex ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + b58_str [str] (use '-' to read from STDIN) + +Optional KEYWORD ARG (type and default value shown in square brackets): + + pad [int=0] Pad output to this width +``` + +### `mmgen-tool b6dtohex` + +```text +Convert a die roll base6 (base6d) string to hexadecimal + +USAGE: mmgen-tool [OPTS] b6dtohex ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + b6d_str [str] (use '-' to read from STDIN) + +Optional KEYWORD ARG (type and default value shown in square brackets): + + pad [int=0] Pad output to this width +``` + +### `mmgen-tool bytespec` + +```text +Convert a byte specifier such as ‘4GB’ into an integer + +USAGE: mmgen-tool [OPTS] bytespec ARG + +Required ARG (type shown in square brackets): + + dd_style_byte_specifier [str] + +Valid specifiers: + + c = 1 + w = 2 + b = 512 + kB = 1000 + K = 1024 + MB = 1000000 + M = 1048576 + GB = 1000000000 + G = 1073741824 + TB = 1000000000000 + T = 1099511627776 + PB = 1000000000000000 + P = 1125899906842624 + EB = 1000000000000000000 + E = 1152921504606846976 +``` + +### `mmgen-tool bytestob58` + +```text +Convert bytes to base 58 (supply data via STDIN) + +USAGE: mmgen-tool [OPTS] bytestob58 ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + infile [str] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + pad [int=0] Pad output to this width +``` + +### `mmgen-tool hash160` + +```text +Compute ripemd160(sha256(data)) (convert hex pubkey to hex addr) + +USAGE: mmgen-tool [OPTS] hash160 ARG + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool hash256` + +```text +Compute sha256(sha256(data)) (double sha256) + +USAGE: mmgen-tool [OPTS] hash256 ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + data [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + file_input [bool=False] First arg is the name of a file containing the data + hex_input [bool=False] First arg is a hexadecimal string +``` + +### `mmgen-tool hexdump` + +```text +Create hexdump of data from file (use '-' for stdin) + +USAGE: mmgen-tool [OPTS] hexdump ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + infile [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + cols [int=8] Number of columns in output + line_nums [str='hex'] Format for line numbers (valid choices: 'hex','dec') +``` + +### `mmgen-tool hexlify` + +```text +Convert bytes in file to hexadecimal (use '-' for stdin) + +USAGE: mmgen-tool [OPTS] hexlify ARG + +Required ARG (type shown in square brackets): + + infile [str] +``` + +### `mmgen-tool hexreverse` + +```text +Reverse bytes of a hexadecimal string + +USAGE: mmgen-tool [OPTS] hexreverse ARG + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool hextob32` + +```text +Convert a hexadecimal string to an MMGen-flavor base 32 string + +USAGE: mmgen-tool [OPTS] hextob32 ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) + +Optional KEYWORD ARG (type and default value shown in square brackets): + + pad [int=0] Pad output to this width +``` + +### `mmgen-tool hextob58` + +```text +Convert a hexadecimal string to base 58 + +USAGE: mmgen-tool [OPTS] hextob58 ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) + +Optional KEYWORD ARG (type and default value shown in square brackets): + + pad [int=0] Pad output to this width +``` + +### `mmgen-tool hextob58chk` + +```text +Convert a hexadecimal string to base58-check encoding + +USAGE: mmgen-tool [OPTS] hextob58chk ARG + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool hextob6d` + +```text +Convert a hexadecimal string to die roll base6 (base6d) + +USAGE: mmgen-tool [OPTS] hextob6d ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + pad [int=0] Pad output to this width + add_spaces [bool=True] Add a space after every 5th character +``` + +### `mmgen-tool id6` + +```text +Generate 6-character MMGen ID for a file (use '-' for stdin) + +USAGE: mmgen-tool [OPTS] id6 ARG + +Required ARG (type shown in square brackets): + + infile [str] +``` + +### `mmgen-tool id8` + +```text +Generate 8-character MMGen ID for a file (use '-' for stdin) + +USAGE: mmgen-tool [OPTS] id8 ARG + +Required ARG (type shown in square brackets): + + infile [str] +``` + +### `mmgen-tool randb58` + +```text +Generate random data (default: 32 bytes) and convert it to base 58 + +USAGE: mmgen-tool [OPTS] randb58 [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + nbytes [int=32] Number of bytes to output + pad [int=0] Pad output to this width +``` + +### `mmgen-tool randhex` + +```text +Print 'n' bytes (default 32) of random data in hex format + +USAGE: mmgen-tool [OPTS] randhex [KEYWORD ARG] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + nbytes [int=32] Number of bytes to output +``` + +### `mmgen-tool str2id6` + +```text +Generate 6-character MMGen ID for a string, ignoring spaces in string + +USAGE: mmgen-tool [OPTS] str2id6 ARG + +Required ARG (type shown in square brackets): + + string [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool to_bytespec` + +```text +Convert an integer to a byte specifier such as ‘4GB’ + +USAGE: mmgen-tool [OPTS] to_bytespec ARGS [KEYWORD ARGS] + +Required ARGS (type shown in square brackets): + + n [int] + dd_style_byte_specifier [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + fmt [str='0.2'] Width and precision of output + print_sym [bool=True] Print the specifier after the numerical value + strip [bool=False] Strip trailing zeroes + add_space [bool=False] With print_sym, add space between value and specifier + +Supported specifiers: + + c = 1 + w = 2 + b = 512 + kB = 1000 + K = 1024 + MB = 1000000 + M = 1048576 + GB = 1000000000 + G = 1073741824 + TB = 1000000000000 + T = 1099511627776 + PB = 1000000000000000 + P = 1125899906842624 + EB = 1000000000000000000 + E = 1152921504606846976 +``` + +### `mmgen-tool unhexdump` + +```text +Decode hexdump from file (use '-' for stdin) (warning: outputs binary data) + +USAGE: mmgen-tool [OPTS] unhexdump ARG + +Required ARG (type shown in square brackets): + + infile [str] +``` + +### `mmgen-tool unhexlify` + +```text +Convert a hexadecimal string to bytes (warning: outputs binary data) + +USAGE: mmgen-tool [OPTS] unhexlify ARG + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) +``` + + +## Cryptocoin key/address utilities: + +### `mmgen-tool addr2pubhash` + +```text +Convert coin address to public key hash + +USAGE: mmgen-tool [OPTS] addr2pubhash ARG + +Required ARG (type shown in square brackets): + + addr [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool addr2scriptpubkey` + +```text +Convert coin address to scriptPubKey + +USAGE: mmgen-tool [OPTS] addr2scriptpubkey ARG + +Required ARG (type shown in square brackets): + + addr [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool eth_checksummed_addr` + +```text +Create a checksummed Ethereum address + +USAGE: mmgen-tool [OPTS] eth_checksummed_addr ARG + +Required ARG (type shown in square brackets): + + addr [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool hex2wif` + +```text +Convert a private key from hexadecimal to WIF format + +USAGE: mmgen-tool [OPTS] hex2wif ARG + +Required ARG (type shown in square brackets): + + privhex [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool privhex2addr` + +```text +Generate a coin address from raw hexadecimal private key data + +USAGE: mmgen-tool [OPTS] privhex2addr ARG + +Required ARG (type shown in square brackets): + + privhex [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool privhex2pubhex` + +```text +Generate a hexadecimal public key from raw hexadecimal private key data + +USAGE: mmgen-tool [OPTS] privhex2pubhex ARG + +Required ARG (type shown in square brackets): + + privhex [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool pubhash2addr` + +```text +Convert public key hash to address + +USAGE: mmgen-tool [OPTS] pubhash2addr ARG + +Required ARG (type shown in square brackets): + + pubhashhex [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool pubhex2addr` + +```text +Convert a hexadecimal pubkey to an address + +USAGE: mmgen-tool [OPTS] pubhex2addr ARG + +Required ARG (type shown in square brackets): + + pubkeyhex [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool pubhex2redeem_script` + +```text +Convert a hexadecimal pubkey to a Segwit P2SH-P2WPKH redeem script + +USAGE: mmgen-tool [OPTS] pubhex2redeem_script ARG + +Required ARG (type shown in square brackets): + + pubkeyhex [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool randpair` + +```text +Generate a random private key/address pair + +USAGE: mmgen-tool [OPTS] randpair +``` + +### `mmgen-tool randwif` + +```text +Generate a random private key in WIF format + +USAGE: mmgen-tool [OPTS] randwif +``` + +### `mmgen-tool redeem_script2addr` + +```text +Convert a Segwit P2SH-P2WPKH redeem script to an address + +USAGE: mmgen-tool [OPTS] redeem_script2addr ARG + +Required ARG (type shown in square brackets): + + redeem_script_hex [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool scriptpubkey2addr` + +```text +Convert scriptPubKey to coin address + +USAGE: mmgen-tool [OPTS] scriptpubkey2addr ARG + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool wif2addr` + +```text +Generate a coin address from a key in WIF format + +USAGE: mmgen-tool [OPTS] wif2addr ARG + +Required ARG (type shown in square brackets): + + wifkey [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool wif2hex` + +```text +Convert a private key from WIF to hexadecimal format + +USAGE: mmgen-tool [OPTS] wif2hex ARG + +Required ARG (type shown in square brackets): + + wifkey [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool wif2redeem_script` + +```text +Convert a WIF private key to a Segwit P2SH-P2WPKH redeem script + +USAGE: mmgen-tool [OPTS] wif2redeem_script ARG + +Required ARG (type shown in square brackets): + + wifkey [str] (use '-' to read from STDIN) +``` + +### `mmgen-tool wif2segwit_pair` + +```text +Generate a Segwit P2SH-P2WPKH redeem script and address from a WIF private key + +USAGE: mmgen-tool [OPTS] wif2segwit_pair ARG + +Required ARG (type shown in square brackets): + + wifkey [str] (use '-' to read from STDIN) +``` + + +## Seed phrase utilities: + +### `mmgen-tool hex2mn` + +```text +Convert a 16, 24 or 32-byte hexadecimal string to a mnemonic seed phrase + +USAGE: mmgen-tool [OPTS] hex2mn ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + hexstr [str] (use '-' to read from STDIN) + +Optional KEYWORD ARG (type and default value shown in square brackets): + + fmt [str='mmgen'] Seed phrase format (valid choices: 'mmgen','bip39','xmrseed') +``` + +### `mmgen-tool mn2hex` + +```text +Convert a mnemonic seed phrase to a hexadecimal string + +USAGE: mmgen-tool [OPTS] mn2hex ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + seed_mnemonic [str] (use '-' to read from STDIN) + +Optional KEYWORD ARG (type and default value shown in square brackets): + + fmt [str='mmgen'] Seed phrase format (valid choices: 'mmgen','bip39','xmrseed') +``` + +### `mmgen-tool mn2hex_interactive` + +```text +Convert an interactively supplied mnemonic seed phrase to a hexadecimal string + +USAGE: mmgen-tool [OPTS] mn2hex_interactive [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + fmt [str='mmgen'] Seed phrase format (valid choices: 'mmgen','bip39','xmrseed') + mn_len [int=24] Length of seed phrase in words + print_mn [bool=False] Print the seed phrase after entry +``` + +### `mmgen-tool mn_printlist` + +```text +Print a mnemonic wordlist + +USAGE: mmgen-tool [OPTS] mn_printlist [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + fmt [str='mmgen'] Seed phrase format (valid choices: 'mmgen','bip39','xmrseed') + enum [bool=False] Enumerate the list + pager [bool=False] Send output to pager +``` + +### `mmgen-tool mn_rand128` + +```text +Generate a random 128-bit mnemonic seed phrase + +USAGE: mmgen-tool [OPTS] mn_rand128 [KEYWORD ARG] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + fmt [str='mmgen'] Seed phrase format (valid choices: 'mmgen','bip39','xmrseed') +``` + +### `mmgen-tool mn_rand192` + +```text +Generate a random 192-bit mnemonic seed phrase + +USAGE: mmgen-tool [OPTS] mn_rand192 [KEYWORD ARG] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + fmt [str='mmgen'] Seed phrase format (valid choices: 'mmgen','bip39','xmrseed') +``` + +### `mmgen-tool mn_rand256` + +```text +Generate a random 256-bit mnemonic seed phrase + +USAGE: mmgen-tool [OPTS] mn_rand256 [KEYWORD ARG] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + fmt [str='mmgen'] Seed phrase format (valid choices: 'mmgen','bip39','xmrseed') +``` + +### `mmgen-tool mn_stats` + +```text +Show stats for a mnemonic wordlist + +USAGE: mmgen-tool [OPTS] mn_stats [KEYWORD ARG] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + fmt [str='mmgen'] Seed phrase format (valid choices: 'mmgen','bip39','xmrseed') +``` + + +## Utilities for viewing/checking MMGen address and transaction files: + +### `mmgen-tool addrfile_chksum` + +```text +Compute checksum for MMGen address file + +USAGE: mmgen-tool [OPTS] addrfile_chksum ARG + +Required ARG (type shown in square brackets): + + mmgen_addrfile [str] +``` + +### `mmgen-tool keyaddrfile_chksum` + +```text +Compute checksum for MMGen key-address file + +USAGE: mmgen-tool [OPTS] keyaddrfile_chksum ARG + +Required ARG (type shown in square brackets): + + mmgen_keyaddrfile [str] +``` + +### `mmgen-tool viewkeyaddrfile_chksum` + +```text +Compute checksum for MMGen key-address file + +USAGE: mmgen-tool [OPTS] viewkeyaddrfile_chksum ARG + +Required ARG (type shown in square brackets): + + mmgen_viewkeyaddrfile [str] +``` + +### `mmgen-tool passwdfile_chksum` + +```text +Compute checksum for MMGen password file + +USAGE: mmgen-tool [OPTS] passwdfile_chksum ARG + +Required ARG (type shown in square brackets): + + mmgen_passwdfile [str] +``` + +### `mmgen-tool txview` + +```text +Display specified raw or signed MMGen transaction files in human-readable form + +USAGE: mmgen-tool [OPTS] txview ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + mmgen_tx_file(s) [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + pager [bool=False] Send output to pager + terse [bool=False] Produce compact tabular output + sort [str='addr'] Sort order for transaction inputs and outputs (valid choices: 'addr','raw') + filesort [str='mtime'] File sort order (valid choices: 'mtime','ctime','atime') +``` + + +## File encryption and decryption: + +### `mmgen-tool decrypt` + +```text +Decrypt a file + +USAGE: mmgen-tool [OPTS] decrypt ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + infile [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + outfile [str=''] + hash_preset [str=''] +``` + +### `mmgen-tool encrypt` + +```text +Encrypt a file + +USAGE: mmgen-tool [OPTS] encrypt ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + infile [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + outfile [str=''] + hash_preset [str=''] +``` + + +## File utilities: + +### `mmgen-tool decrypt_keystore` + +```text +Decrypt the data in a keystore wallet, returning the decrypted data in binary format + +USAGE: mmgen-tool [OPTS] decrypt_keystore ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + wallet_file [str] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + output_hex [bool=False] +``` + +### `mmgen-tool decrypt_geth_keystore` + +```text +Decrypt the private key in a Geth keystore wallet, returning the decrypted key in hex format + +USAGE: mmgen-tool [OPTS] decrypt_geth_keystore ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + wallet_file [str] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + check_addr [bool=True] +``` + +### `mmgen-tool find_incog_data` + +```text +Use an Incog ID to find hidden incognito wallet data + +USAGE: mmgen-tool [OPTS] find_incog_data ARGS [KEYWORD ARG] + +Required ARGS (type shown in square brackets): + + filename [str] + incog_id [str] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + keep_searching [bool=False] Continue search after finding data (ID collisions can yield false positives) +``` + +### `mmgen-tool rand2file` + +```text +Write ‘nbytes’ bytes of random data to specified file (dd-style byte specifiers supported) + +USAGE: mmgen-tool [OPTS] rand2file ARGS [KEYWORD ARGS] + +Required ARGS (type shown in square brackets): + + outfile [str] + nbytes [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + threads [int=4] + silent [bool=False] + +Valid specifiers: + + c = 1 + w = 2 + b = 512 + kB = 1000 + K = 1024 + MB = 1000000 + M = 1048576 + GB = 1000000000 + G = 1073741824 + TB = 1000000000000 + T = 1099511627776 + PB = 1000000000000000 + P = 1125899906842624 + EB = 1000000000000000000 + E = 1152921504606846976 +``` + + +## Key, address or subseed generation from an MMGen wallet: + +### `mmgen-tool gen_addr` + +```text +Generate a single MMGen address from default or specified wallet + +USAGE: mmgen-tool [OPTS] gen_addr ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + mmgen_addr [str] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + wallet [str=''] +``` + +### `mmgen-tool gen_key` + +```text +Generate a single WIF key for specified MMGen address from default or specified wallet + +USAGE: mmgen-tool [OPTS] gen_key ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + mmgen_addr [str] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + wallet [str=''] +``` + +### `mmgen-tool get_subseed` + +```text +Get the Seed ID of a single subseed by Subseed Index for default or specified wallet + +USAGE: mmgen-tool [OPTS] get_subseed ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + subseed_idx [str] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + wallet [str=''] +``` + +### `mmgen-tool get_subseed_by_seed_id` + +```text +Get the Subseed Index of a single subseed by Seed ID for default or specified wallet + +USAGE: mmgen-tool [OPTS] get_subseed_by_seed_id ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + seed_id [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + wallet [str=''] + last_idx [int=100] +``` + +### `mmgen-tool list_shares` + +```text +List the Seed IDs of the shares resulting from a split of default or specified wallet + +USAGE: mmgen-tool [OPTS] list_shares ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + share_count [int] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + id_str [str='default'] + master_share [int=0] (min:1, max:1024, 0=no master share) + wallet [str=''] +``` + +### `mmgen-tool list_subseeds` + +```text +List a range of subseed Seed IDs for default or specified wallet + +USAGE: mmgen-tool [OPTS] list_subseeds ARG [KEYWORD ARG] + +Required ARG (type shown in square brackets): + + subseed_idx_range [str] + +Optional KEYWORD ARG (type and default value shown in square brackets): + + wallet [str=''] +``` + + +## Tracking-wallet commands using the JSON-RPC interface: + +### `mmgen-tool add_label` + +```text +Add descriptive label for address in tracking wallet + +USAGE: mmgen-tool [OPTS] add_label ARGS + +Required ARGS (type shown in square brackets): + + mmgen_or_coin_addr [str] + label [str] +``` + +### `mmgen-tool daemon_version` + +```text +Print coin daemon version + +USAGE: mmgen-tool [OPTS] daemon_version +``` + +### `mmgen-tool getbalance` + +```text +List confirmed/unconfirmed, spendable/unspendable balances in tracking wallet + +USAGE: mmgen-tool [OPTS] getbalance [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + minconf [int=1] Minimum number of confirmations + quiet [bool=False] Produce quieter output + pager [bool=False] Send output to pager +``` + +### `mmgen-tool listaddress` + +```text +List the specified MMGen address in the tracking wallet and its balance + +USAGE: mmgen-tool [OPTS] listaddress ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + mmgen_addr [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + wide [bool=False] Display data in wide tabular format + minconf [int=1] Minimum number of confirmations + showcoinaddr [bool=True] Display coin address in addition to MMGen ID + age_fmt [str='confs'] Format for the Age/Date column (valid choices: 'confs','block','days','date','date_time') +``` + +### `mmgen-tool listaddresses` + +```text +List MMGen addresses in the tracking wallet and their balances + +USAGE: mmgen-tool [OPTS] listaddresses [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + pager [bool=False] Send output to pager + reverse [bool=False] Reverse order of unspent outputs + wide [bool=False] Display data in wide tabular format + minconf [int=1] Minimum number of confirmations + sort [str=''] Address sort order (valid choices: 'reverse','mmid','addr','amt') + age_fmt [str='confs'] Format for the Age/Date column (valid choices: 'confs','block','days','date','date_time') + interactive [bool=False] Enable interactive operation + mmgen_addrs [str=''] Hyphenated range or comma-separated list of addresses + showcoinaddrs [bool=True] Display coin addresses in addition to MMGen IDs + showempty [bool=True] Show addresses with no balances + showused [int=1] Show used addresses (tristate: 0=no, 1=yes, 2=all) + all_labels [bool=False] Show all addresses with labels +``` + +### `mmgen-tool remove_address` + +```text +Remove an address from tracking wallet + +USAGE: mmgen-tool [OPTS] remove_address ARG + +Required ARG (type shown in square brackets): + + mmgen_or_coin_addr [str] +``` + +### `mmgen-tool remove_label` + +```text +Remove descriptive label for address in tracking wallet + +USAGE: mmgen-tool [OPTS] remove_label ARG + +Required ARG (type shown in square brackets): + + mmgen_or_coin_addr [str] +``` + +### `mmgen-tool rescan_address` + +```text +Rescan an address in the tracking wallet to update its balance + +USAGE: mmgen-tool [OPTS] rescan_address ARG + +Required ARG (type shown in square brackets): + + mmgen_or_coin_addr [str] +``` + +### `mmgen-tool rescan_blockchain` + +```text +Rescan the blockchain to update historical transactions in the tracking wallet + +USAGE: mmgen-tool [OPTS] rescan_blockchain [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + start_block [int=None] + stop_block [int=None] + +NOTE: + + The rescanning process typically takes several hours and may be interrupted + using Ctrl-C. An interrupted rescan may be resumed using the ‘start_block’ + parameter. +``` + +### `mmgen-tool resolve_address` + +```text +Resolve an MMGen address in the tracking wallet to a coin address or vice-versa + +USAGE: mmgen-tool [OPTS] resolve_address ARG + +Required ARG (type shown in square brackets): + + mmgen_or_coin_addr [str] +``` + +### `mmgen-tool twexport` + +```text +Export a tracking wallet to JSON format + +USAGE: mmgen-tool [OPTS] twexport [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + include_amts [bool=True] + pretty [bool=False] + prune [bool=False] + warn_used [bool=False] + force [bool=False] + +NOTES: + + If ‘include_amts’ is true (the default), Ethereum balances will be restored + from the dump upon import. For Bitcoin and forks, amount fields in the dump + are ignored. + + If ‘pretty’ is true, JSON will be dumped in human-readable format to allow + for editing of comment fields. + + If ‘prune’ is true, an interactive menu will be launched allowing the user + to prune unwanted addresses before creating the JSON dump. Pruning has no + effect on the existing tracking wallet. + + If ‘warn_used’ is true, the user will be prompted before pruning used + addresses. + + If ‘force’ is true, any existing dump will be overwritten without prompting. +``` + +### `mmgen-tool twimport` + +```text +Restore a tracking wallet from a JSON dump created by ‘twexport’ + +USAGE: mmgen-tool [OPTS] twimport ARG [KEYWORD ARGS] + +Required ARG (type shown in square brackets): + + filename [str] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + ignore_checksum [bool=False] + batch [bool=False] + +NOTES: + + If comment fields in the JSON dump have been edited, ‘ignore_checksum’ must + be set to true. + + The restored tracking wallet will have correct balances but no record of + historical transactions. These may be restored by running ‘mmgen-tool + rescan_blockchain’. +``` + +### `mmgen-tool twview` + +```text +View tracking wallet unspent outputs + +USAGE: mmgen-tool [OPTS] twview [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + pager [bool=False] Send output to pager + reverse [bool=False] Reverse order of unspent outputs + wide [bool=False] Display data in wide tabular format + minconf [int=1] Minimum number of confirmations + sort [str='age'] Unspent output sort order (valid choices: 'addr','age','amt','txid','twmmid') + age_fmt [str='confs'] Format for the Age/Date column (valid choices: 'confs','block','days','date','date_time') + interactive [bool=False] Enable interactive operation + show_mmid [bool=True] Show MMGen IDs along with coin addresses +``` + +### `mmgen-tool txhist` + +```text +View transaction history of tracking wallet + +USAGE: mmgen-tool [OPTS] txhist [KEYWORD ARGS] + +Optional KEYWORD ARGS (type and default value shown in square brackets): + + pager [bool=False] Send output to pager + reverse [bool=False] Reverse order of transactions + detail [bool=False] Produce detailed, non-tabular output + sinceblock [int=0] Display transactions starting from this block + sort [str='age'] Transaction sort order (valid choices: 'age','blockheight','amt','total_amt','txid') + age_fmt [str='confs'] Format for the Age/Date column (valid choices: 'confs','block','days','date','date_time') + interactive [bool=False] Enable interactive operation +``` + +```text +MMGEN v15.1.dev17 February 2025 MMGEN-TOOL(DETAIL)(1) +``` diff --git a/doc/wiki/commands/command-help-tool(usage).md b/doc/wiki/commands/command-help-tool(usage).md new file mode 100644 index 00000000..9a88eb23 --- /dev/null +++ b/doc/wiki/commands/command-help-tool(usage).md @@ -0,0 +1,191 @@ +```text +GENERAL USAGE INFORMATION FOR MMGEN-TOOL COMMANDS + + Arguments with only type specified in square brackets are required + + Arguments with both type and default value specified in square brackets are + optional and must be specified in the form ‘name=value’ + + For more detailed usage information for a particular tool command, type + ‘mmgen-tool help ’ + + + Help/usage commands: + + help command_name [str=''] + usage command_name [str=''] + + + General string conversion and hashing utilities: + + b32tohex b32_str [str or STDIN] pad [int=0] + b58chktohex b58chk_str [str or STDIN] + b58tobytes b58_str [str or STDIN] pad [int=0] + b58tohex b58_str [str or STDIN] pad [int=0] + b6dtohex b6d_str [str or STDIN] pad [int=0] + bytespec dd_style_byte_specifier [str] + bytestob58 infile [str] pad [int=0] + hash160 hexstr [str or STDIN] + hash256 data [str] file_input [bool=False] hex_input [bool=False] + hexdump infile [str] cols [int=8] line_nums [str='hex'] + hexlify infile [str] + hexreverse hexstr [str or STDIN] + hextob32 hexstr [str or STDIN] pad [int=0] + hextob58 hexstr [str or STDIN] pad [int=0] + hextob58chk hexstr [str or STDIN] + hextob6d hexstr [str or STDIN] pad [int=0] add_spaces [bool=True] + id6 infile [str] + id8 infile [str] + randb58 nbytes [int=32] pad [int=0] + randhex nbytes [int=32] + str2id6 string [str or STDIN] + to_bytespec n [int] dd_style_byte_specifier [str] fmt [str='0.2'] print_sym [bool=True] strip [bool=False] add_space [bool=False] + unhexdump infile [str] + unhexlify hexstr [str or STDIN] + + + Cryptocoin key/address utilities: + + May require use of the '--coin', '--type' and/or '--testnet' options + + Examples: + mmgen-tool --coin=ltc --type=bech32 wif2addr + mmgen-tool --coin=zec --type=zcash_z randpair + + addr2pubhash addr [str or STDIN] + addr2scriptpubkey addr [str or STDIN] + eth_checksummed_addr addr [str or STDIN] + hex2wif privhex [str or STDIN] + privhex2addr privhex [str or STDIN] + privhex2pubhex privhex [str or STDIN] + pubhash2addr pubhashhex [str or STDIN] + pubhex2addr pubkeyhex [str or STDIN] + pubhex2redeem_script pubkeyhex [str or STDIN] + randpair + randwif + redeem_script2addr redeem_script_hex [str or STDIN] + scriptpubkey2addr hexstr [str or STDIN] + wif2addr wifkey [str or STDIN] + wif2hex wifkey [str or STDIN] + wif2redeem_script wifkey [str or STDIN] + wif2segwit_pair wifkey [str or STDIN] + + + Seed phrase utilities: + + Supported seed phrase formats: 'mmgen' (default), 'bip39', 'xmrseed' + + IMPORTANT NOTE: MMGen Wallet’s default seed phrase format uses the + Electrum wordlist, however seed phrases are computed using a different + algorithm and are NOT Electrum-compatible! + + BIP39 support is fully compatible with the standard, allowing users to + import and export seed entropy from BIP39-compatible wallets. However, + users should be aware that BIP39 support does not imply BIP32 support! + MMGen uses its own key derivation scheme differing from the one described + by the BIP32 protocol. + + For Monero (‘xmrseed’) seed phrases, input data is reduced to a spendkey + before conversion so that a canonical seed phrase is produced. This is + required because Monero seeds, unlike ordinary wallet seeds, are tied + to a concrete key/address pair. To manually generate a Monero spendkey, + use the ‘hex2wif’ command. + + hex2mn hexstr [str or STDIN] fmt [str='mmgen'] + mn2hex seed_mnemonic [str or STDIN] fmt [str='mmgen'] + mn2hex_interactive fmt [str='mmgen'] mn_len [int=24] print_mn [bool=False] + mn_printlist fmt [str='mmgen'] enum [bool=False] pager [bool=False] + mn_rand128 fmt [str='mmgen'] + mn_rand192 fmt [str='mmgen'] + mn_rand256 fmt [str='mmgen'] + mn_stats fmt [str='mmgen'] + + + Utilities for viewing/checking MMGen address and transaction files: + + addrfile_chksum mmgen_addrfile [str] + keyaddrfile_chksum mmgen_keyaddrfile [str] + viewkeyaddrfile_chksum mmgen_viewkeyaddrfile [str] + passwdfile_chksum mmgen_passwdfile [str] + txview mmgen_tx_file(s) [str] pager [bool=False] terse [bool=False] sort [str='addr'] filesort [str='mtime'] + + + File encryption and decryption: + + MMGen encryption suite: + * Key: Scrypt (user-configurable hash parameters, 32-byte salt) + * Enc: AES256_CTR, 16-byte rand IV, sha256 hash + 32-byte nonce + data + * The encrypted file is indistinguishable from random data + + decrypt infile [str] outfile [str=''] hash_preset [str=''] + encrypt infile [str] outfile [str=''] hash_preset [str=''] + + + File utilities: + + decrypt_keystore wallet_file [str] output_hex [bool=False] + decrypt_geth_keystore wallet_file [str] check_addr [bool=True] + find_incog_data filename [str] incog_id [str] keep_searching [bool=False] + rand2file outfile [str] nbytes [str] threads [int=4] silent [bool=False] + + + Key, address or subseed generation from an MMGen wallet: + + gen_addr mmgen_addr [str] wallet [str=''] + gen_key mmgen_addr [str] wallet [str=''] + get_subseed subseed_idx [str] wallet [str=''] + get_subseed_by_seed_id seed_id [str] wallet [str=''] last_idx [int=100] + list_shares share_count [int] id_str [str='default'] master_share [int=0] wallet [str=''] + list_subseeds subseed_idx_range [str] wallet [str=''] + + + Tracking-wallet commands using the JSON-RPC interface: + + add_label mmgen_or_coin_addr [str] label [str] + daemon_version + getbalance minconf [int=1] quiet [bool=False] pager [bool=False] + listaddress mmgen_addr [str] wide [bool=False] minconf [int=1] showcoinaddr [bool=True] age_fmt [str='confs'] + listaddresses pager [bool=False] reverse [bool=False] wide [bool=False] minconf [int=1] sort [str=''] age_fmt [str='confs'] interactive [bool=False] mmgen_addrs [str=''] showcoinaddrs [bool=True] showempty [bool=True] showused [int=1] all_labels [bool=False] + remove_address mmgen_or_coin_addr [str] + remove_label mmgen_or_coin_addr [str] + rescan_address mmgen_or_coin_addr [str] + rescan_blockchain start_block [int=None] stop_block [int=None] + resolve_address mmgen_or_coin_addr [str] + twexport include_amts [bool=True] pretty [bool=False] prune [bool=False] warn_used [bool=False] force [bool=False] + twimport filename [str] ignore_checksum [bool=False] batch [bool=False] + twview pager [bool=False] reverse [bool=False] wide [bool=False] minconf [int=1] sort [str='age'] age_fmt [str='confs'] interactive [bool=False] show_mmid [bool=True] + txhist pager [bool=False] reverse [bool=False] detail [bool=False] sinceblock [int=0] sort [str='age'] age_fmt [str='confs'] interactive [bool=False] + + + To force a command to read from STDIN instead of file (for commands taking + a filename as their first argument), substitute "-" for the filename. + + +EXAMPLES: + + Generate a random LTC Bech32 public/private keypair: + $ mmgen-tool -r0 --coin=ltc --type=bech32 randpair + + Generate a DASH address with compressed public key from the supplied WIF key: + $ mmgen-tool --coin=dash --type=compressed wif2addr XJkVRC3eGKurc9Uzx1wfQoio3yqkmaXVqLMTa6y7s3M3jTBnmxfw + + Generate a well-known burn address: + $ mmgen-tool hextob58chk 000000000000000000000000000000000000000000 + + Generate a random 12-word seed phrase: + $ mmgen-tool -r0 mn_rand128 fmt=bip39 + + Same as above, but get additional entropy from user: + $ mmgen-tool mn_rand128 fmt=bip39 + + Encode bytes from a file to base 58: + $ mmgen-tool bytestob58 /etc/timezone pad=20 + + Reverse a hex string: + $ mmgen-tool hexreverse "deadbeefcafe" + + Same as above, but supply input via STDIN: + $ echo "deadbeefcafe" | mmgen-tool hexreverse - + + MMGEN v15.1.dev17 February 2025 MMGEN-TOOL(USAGE)(1) +``` diff --git a/doc/wiki/commands/command-help-tool.md b/doc/wiki/commands/command-help-tool.md new file mode 100644 index 00000000..f5939b47 --- /dev/null +++ b/doc/wiki/commands/command-help-tool.md @@ -0,0 +1,202 @@ +```text + MMGEN-TOOL: Perform various MMGen- and cryptocoin-related operations + USAGE: mmgen-tool [opts] + OPTIONS: + -d, --outdir d Specify an alternate directory 'd' for output + -h, --help Print this help message + --longhelp Print help message for long (global) options + -e, --echo-passphrase Echo passphrase or mnemonic to screen upon entry + -k, --use-internal-keccak-module Force use of the internal keccak module + -K, --keygen-backend n Use backend 'n' for public key generation. Options + for BTC: 1:libsecp256k1 [default] 2:python-ecdsa + -l, --list List available commands + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -P, --passwd-file f Get passphrase from file 'f'. + -q, --quiet Produce quieter output + -r, --usr-randchars n Get 'n' characters of additional randomness from + user (min=10, max=80) + -t, --type t Specify address type (valid choices: 'legacy', + 'compressed', 'segwit', 'bech32', 'zcash_z') + -v, --verbose Produce more verbose output + -X, --cached-balances Use cached balances (Ethereum only) + -y, --yes Answer 'yes' to prompts, suppress non-essential output + + + COMMANDS + + Help/usage commands: + + help - display usage information for a single command or all commands + usage - display usage information for a single command or all commands + + General string conversion and hashing utilities: + + b32tohex - convert an MMGen-flavor base 32 string to hexadecimal + b58chktohex - convert a base58-check encoded string to hexadecimal + b58tobytes - convert a base 58 string to bytes (warning: outputs binary + data) + b58tohex - convert a base 58 string to hexadecimal + b6dtohex - convert a die roll base6 (base6d) string to hexadecimal + bytespec - convert a byte specifier such as ‘4GB’ into an integer + bytestob58 - convert bytes to base 58 (supply data via STDIN) + hash160 - compute ripemd160(sha256(data)) (convert hex pubkey to hex + addr) + hash256 - compute sha256(sha256(data)) (double sha256) + hexdump - create hexdump of data from file (use '-' for stdin) + hexlify - convert bytes in file to hexadecimal (use '-' for stdin) + hexreverse - reverse bytes of a hexadecimal string + hextob32 - convert a hexadecimal string to an MMGen-flavor base 32 + string + hextob58 - convert a hexadecimal string to base 58 + hextob58chk - convert a hexadecimal string to base58-check encoding + hextob6d - convert a hexadecimal string to die roll base6 (base6d) + id6 - generate 6-character MMGen ID for a file (use '-' for stdin) + id8 - generate 8-character MMGen ID for a file (use '-' for stdin) + randb58 - generate random data (default: 32 bytes) and convert it to + base 58 + randhex - print 'n' bytes (default 32) of random data in hex format + str2id6 - generate 6-character MMGen ID for a string, ignoring spaces + in string + to_bytespec - convert an integer to a byte specifier such as ‘4GB’ + unhexdump - decode hexdump from file (use '-' for stdin) (warning: + outputs binary data) + unhexlify - convert a hexadecimal string to bytes (warning: outputs + binary data) + + Cryptocoin key/address utilities: + + May require use of the '--coin', '--type' and/or '--testnet' options + + Examples: + mmgen-tool --coin=ltc --type=bech32 wif2addr + mmgen-tool --coin=zec --type=zcash_z randpair + + addr2pubhash - convert coin address to public key hash + addr2scriptpubkey - convert coin address to scriptPubKey + eth_checksummed_addr - create a checksummed Ethereum address + hex2wif - convert a private key from hexadecimal to WIF format + privhex2addr - generate a coin address from raw hexadecimal + private key data + privhex2pubhex - generate a hexadecimal public key from raw + hexadecimal private key data + pubhash2addr - convert public key hash to address + pubhex2addr - convert a hexadecimal pubkey to an address + pubhex2redeem_script - convert a hexadecimal pubkey to a Segwit + P2SH-P2WPKH redeem script + randpair - generate a random private key/address pair + randwif - generate a random private key in WIF format + redeem_script2addr - convert a Segwit P2SH-P2WPKH redeem script to an + address + scriptpubkey2addr - convert scriptPubKey to coin address + wif2addr - generate a coin address from a key in WIF format + wif2hex - convert a private key from WIF to hexadecimal format + wif2redeem_script - convert a WIF private key to a Segwit P2SH-P2WPKH + redeem script + wif2segwit_pair - generate a Segwit P2SH-P2WPKH redeem script and + address from a WIF private key + + Seed phrase utilities: + + Supported seed phrase formats: 'mmgen' (default), 'bip39', 'xmrseed' + + IMPORTANT NOTE: MMGen Wallet’s default seed phrase format uses the + Electrum wordlist, however seed phrases are computed using a different + algorithm and are NOT Electrum-compatible! + + BIP39 support is fully compatible with the standard, allowing users to + import and export seed entropy from BIP39-compatible wallets. However, + users should be aware that BIP39 support does not imply BIP32 support! + MMGen uses its own key derivation scheme differing from the one described + by the BIP32 protocol. + + For Monero (‘xmrseed’) seed phrases, input data is reduced to a spendkey + before conversion so that a canonical seed phrase is produced. This is + required because Monero seeds, unlike ordinary wallet seeds, are tied + to a concrete key/address pair. To manually generate a Monero spendkey, + use the ‘hex2wif’ command. + + hex2mn - convert a 16, 24 or 32-byte hexadecimal string to a + mnemonic seed phrase + mn2hex - convert a mnemonic seed phrase to a hexadecimal string + mn2hex_interactive - convert an interactively supplied mnemonic seed + phrase to a hexadecimal string + mn_printlist - print a mnemonic wordlist + mn_rand128 - generate a random 128-bit mnemonic seed phrase + mn_rand192 - generate a random 192-bit mnemonic seed phrase + mn_rand256 - generate a random 256-bit mnemonic seed phrase + mn_stats - show stats for a mnemonic wordlist + + Utilities for viewing/checking MMGen address and transaction files: + + addrfile_chksum - compute checksum for MMGen address file + keyaddrfile_chksum - compute checksum for MMGen key-address file + viewkeyaddrfile_chksum - compute checksum for MMGen key-address file + passwdfile_chksum - compute checksum for MMGen password file + txview - display specified raw or signed MMGen transaction + files in human-readable form + + File encryption and decryption: + + MMGen encryption suite: + * Key: Scrypt (user-configurable hash parameters, 32-byte salt) + * Enc: AES256_CTR, 16-byte rand IV, sha256 hash + 32-byte nonce + data + * The encrypted file is indistinguishable from random data + + decrypt - decrypt a file + encrypt - encrypt a file + + File utilities: + + decrypt_keystore - decrypt the data in a keystore wallet, returning + the decrypted data in binary format + decrypt_geth_keystore - decrypt the private key in a Geth keystore wallet, + returning the decrypted key in hex format + find_incog_data - Use an Incog ID to find hidden incognito wallet + data + rand2file - write ‘nbytes’ bytes of random data to specified + file (dd-style byte specifiers supported) + + Key, address or subseed generation from an MMGen wallet: + + gen_addr - generate a single MMGen address from default or + specified wallet + gen_key - generate a single WIF key for specified MMGen + address from default or specified wallet + get_subseed - get the Seed ID of a single subseed by Subseed + Index for default or specified wallet + get_subseed_by_seed_id - get the Subseed Index of a single subseed by Seed + ID for default or specified wallet + list_shares - list the Seed IDs of the shares resulting from a + split of default or specified wallet + list_subseeds - list a range of subseed Seed IDs for default or + specified wallet + + Tracking-wallet commands using the JSON-RPC interface: + + add_label - add descriptive label for address in tracking wallet + daemon_version - print coin daemon version + getbalance - list confirmed/unconfirmed, spendable/unspendable + balances in tracking wallet + listaddress - list the specified MMGen address in the tracking + wallet and its balance + listaddresses - list MMGen addresses in the tracking wallet and their + balances + remove_address - remove an address from tracking wallet + remove_label - remove descriptive label for address in tracking wallet + rescan_address - rescan an address in the tracking wallet to update its + balance + rescan_blockchain - rescan the blockchain to update historical + transactions in the tracking wallet + resolve_address - resolve an MMGen address in the tracking wallet to a + coin address or vice-versa + twexport - export a tracking wallet to JSON format + twimport - restore a tracking wallet from a JSON dump created by + ‘twexport’ + twview - view tracking wallet unspent outputs + txhist - view transaction history of tracking wallet + + Type ‘mmgen-tool help ’ for help on a particular command + + MMGEN v15.1.dev17 February 2025 MMGEN-TOOL(1) +``` diff --git a/doc/wiki/commands/command-help-txbump.md b/doc/wiki/commands/command-help-txbump.md new file mode 100644 index 00000000..22eb4a7f --- /dev/null +++ b/doc/wiki/commands/command-help-txbump.md @@ -0,0 +1,120 @@ +```text + MMGEN-TXBUMP: Create, and optionally send and sign, a replacement transaction + on networks that support replace-by-fee (RBF) + USAGE: mmgen-txbump [opts] [MMGen TX file] [seed source] ... + mmgen-txbump [opts] [ADDR,AMT ... | DATA_SPEC] ADDR [MMGen TX file] [seed source] ... + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -a, --autosign Bump the most recent transaction created and sent with + the --autosign option. The removable device is mounted + and unmounted automatically. The transaction file + argument must be omitted. Note that only sent trans- + actions may be bumped with this option. To redo an + unsent --autosign transaction, first delete it using + ‘mmgen-txsend --abort’ and then create a new one + -b, --brain-params l,p Use seed length 'l' and hash preset 'p' for + brainwallet input + -c, --comment-file f Source the transaction's comment from file 'f' + -d, --outdir d Specify an alternate directory 'd' for output + -e, --echo-passphrase Print passphrase to screen when typing it + -f, --fee f Transaction fee, as a decimal BTC amount or as + satoshis per byte (an integer followed by 's'). + See FEE SPECIFICATION below. + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -i, --in-fmt f Input is from wallet format 'f' (see FMT CODES below) + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -k, --keys-from-file f Provide additional keys for non-MMGen addresses + -K, --keygen-backend n Use backend 'n' for public key generation. Options + for BTC: 1:libsecp256k1 [default] 2:python-ecdsa + -M, --mmgen-keys-from-file f Provide keys for MMGen addresses in a key- + address file (output of 'mmgen-keygen'). Permits + online signing without an MMGen seed source. The + key-address file is also used to verify MMGen-to-BTC + mappings, so the user should record its checksum. + -o, --output-to-reduce o Deduct the fee from output 'o' (an integer, or 'c' + for the transaction's change output, if present) + -O, --old-incog-fmt Specify old-format incognito input + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -P, --passwd-file f Get MMGen wallet passphrase from file 'f' + -q, --quiet Suppress warnings; overwrite files without prompting + -s, --send Sign and send the transaction (the default if seed + data is provided) + -v, --verbose Produce more verbose output + -W, --allow-non-wallet-swap Allow signing of swap transactions that send funds + to non-wallet addresses + -x, --proxy P Fetch the swap quote via SOCKS5 proxy ‘P’ (host:port) + -y, --yes Answer 'yes' to prompts, suppress non-essential output + -z, --show-hash-presets Show information on available hash presets + + + With --autosign, the TX file argument is omitted, and the last submitted TX + file on the removable device will be used. + + If no outputs are specified, the original outputs will be used for the + replacement transaction, otherwise a new transaction will be created with the + outputs listed on the command line. The syntax for the output arguments is + identical to that of ‘mmgen-txcreate’. + + The user should take care to select a fee sufficient to ensure the original + transaction is replaced in the mempool. + + When bumping a swap transaction, the swap protocol’s quote server on the + Internet must be reachable either directly or via the SOCKS5 proxy specified + with the --proxy option. To improve privacy, it’s recommended to proxy + requests to the quote server via Tor or some other anonymity network. + + + FEE SPECIFICATION + + Transaction fees, both on the command line and at the interactive prompt, may + be specified as either absolute BTC amounts, using a plain decimal number, or + as satoshis per byte, using an integer followed by 's', for satoshi. + + + Transactions may contain both MMGen or non-MMGen input addresses. + + To sign non-MMGen inputs, a bitcoind wallet dump or flat key list is used + as the key source (--keys-from-file option). + + To sign MMGen inputs, key data is generated from a seed as with the + mmgen-addrgen and mmgen-keygen commands. Alternatively, a key-address file + may be used (--mmgen-keys-from-file option). + + Multiple wallets or other seed files can be listed on the command line in + any order. If the seeds required to sign the transaction’s inputs are not + found in these files (or in the default wallet), the user will be prompted + for seed data interactively. + + To prevent an attacker from crafting transactions with bogus MMGen-to-Bitcoin + address mappings, all outputs to MMGen addresses are verified with a seed + source. Therefore, seed files or a key-address file for all MMGen outputs + must also be supplied on the command line if the data can’t be found in the + default wallet. + + Seed source files must have the canonical extensions listed in the 'FileExt' + column below: + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-TXBUMP(1) +``` diff --git a/doc/wiki/commands/command-help-txcreate.md b/doc/wiki/commands/command-help-txcreate.md new file mode 100644 index 00000000..7c249ab7 --- /dev/null +++ b/doc/wiki/commands/command-help-txcreate.md @@ -0,0 +1,127 @@ +```text + MMGEN-TXCREATE: Create a transaction with outputs to specified coin or MMGen addresses + USAGE: mmgen-txcreate [opts] [ADDR,AMT ... | DATA_SPEC] ADDR [addr file ...] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -a, --autosign Create a transaction for offline autosigning (see + ‘mmgen-autosign’). The removable device is mounted and + unmounted automatically + -A, --fee-adjust f Adjust transaction fee by factor 'f' (see below) + -B, --no-blank Don't blank screen before displaying unspent outputs + -c, --comment-file f Source the transaction's comment from file 'f' + -C, --fee-estimate-confs c Desired number of confirmations for fee estimation + (default: 3) + -d, --outdir d Specify an alternate directory 'd' for output + -E, --fee-estimate-mode M Specify the network fee estimate mode. Choices: + 'conservative','economical'. Default: 'conservative' + -f, --fee f Transaction fee, as a decimal BTC amount or as + satoshis per byte (an integer followed by 's'). + See FEE SPECIFICATION below. If omitted, fee will be + calculated using network fee estimation. + -i, --info Display unspent outputs and exit + -I, --inputs i Specify transaction inputs (comma-separated list of + MMGen IDs or coin addresses). Note that ALL unspent + outputs associated with each address will be included. + -l, --locktime t Lock time (block height or unix seconds) (default: 0) + -L, --autochg-ignore-labels Ignore labels when autoselecting change addresses + -m, --minconf n Minimum number of confirmations required to spend + outputs (default: 1) + -q, --quiet Suppress warnings; overwrite files without prompting + -R, --no-rbf Make transaction non-replaceable (non-replace-by-fee + according to BIP 125) + -v, --verbose Produce more verbose output + -V, --vsize-adj f Adjust transaction's estimated vsize by factor 'f' + -y, --yes Answer 'yes' to prompts, suppress non-essential output + + + The transaction’s outputs are listed on the command line, while its inputs + are chosen from a list of the wallet’s unspent outputs via an interactive + menu. Alternatively, inputs may be specified using the --inputs option. + + Addresses on the command line can be either native coin addresses or MMGen + IDs in the form SEED_ID:ADDRTYPE_CODE:INDEX. + + Outputs are specified in the form ADDRESS,AMOUNT or ADDRESS. The first form + creates an output sending the given amount to the given address. The bare + address form designates the given address as either the change output or the + sole output of the transaction (excluding any data output). Exactly one bare + address argument is required. + + For convenience, the bare address argument may be given as ADDRTYPE_CODE or + SEED_ID:ADDRTYPE_CODE (see ADDRESS TYPES below). In the first form, the first + unused address of type ADDRTYPE_CODE for each Seed ID in the tracking wallet + will be displayed in a menu, with the user prompted to select one. In the + second form, the user specifies the Seed ID as well, allowing the script to + select the transaction’s change output or single output without prompting. + See EXAMPLES below. + + A single DATA_SPEC argument may also be given on the command line to create + an OP_RETURN data output with a zero spend amount. This is the preferred way + to embed data in the blockchain. DATA_SPEC may be of the form "data":DATA + or "hexdata":DATA. In the first form, DATA is a string in your system’s native + encoding, typically UTF-8. In the second, DATA is a hexadecimal string (with + the leading ‘0x’ omitted) encoding the binary data to be embedded. In both + cases, the resulting byte string must not exceed 80 bytes in length. + + If the transaction fee is not specified on the command line (see FEE + SPECIFICATION below), it will be calculated dynamically using network fee + estimation for the default (or user-specified) number of confirmations. + If network fee estimation fails, the user will be prompted for a fee. + + Network-estimated fees will be multiplied by the value of --fee-adjust, if + specified. + + + ADDRESS TYPES: + + Code Type Description + ---- ---- ----------- + ‘L’ legacy - Legacy uncompressed address + ‘C’ compressed - Compressed P2PKH address + ‘S’ segwit - Segwit P2SH-P2WPKH address + ‘B’ bech32 - Native Segwit (Bech32) address + ‘E’ ethereum - Ethereum address + ‘Z’ zcash_z - Zcash z-address + ‘M’ monero - Monero address + + + FEE SPECIFICATION + + Transaction fees, both on the command line and at the interactive prompt, may + be specified as either absolute BTC amounts, using a plain decimal number, or + as satoshis per byte, using an integer followed by 's', for satoshi. + + + EXAMPLES: + + Send 0.123 BTC to an external Bitcoin address, returning the change to a + specific MMGen address in the tracking wallet: + + $ mmgen-txcreate bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t,0.123 01ABCDEF:B:7 + + Same as above, but select the change address automatically: + + $ mmgen-txcreate bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t,0.123 01ABCDEF:B + + Same as above, but select the change address automatically by address type: + + $ mmgen-txcreate bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t,0.123 B + + Same as above, but reduce verbosity and specify fee of 20 satoshis + per byte: + + $ mmgen-txcreate -q -f 20s bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t,0.123 B + + Send entire balance of selected inputs minus fee to an external Bitcoin + address: + + $ mmgen-txcreate bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t + + Send entire balance of selected inputs minus fee to first unused wallet + address of specified type: + + $ mmgen-txcreate B + + MMGEN v15.1.dev17 February 2025 MMGEN-TXCREATE(1) +``` diff --git a/doc/wiki/commands/command-help-txdo.md b/doc/wiki/commands/command-help-txdo.md new file mode 100644 index 00000000..201c457a --- /dev/null +++ b/doc/wiki/commands/command-help-txdo.md @@ -0,0 +1,191 @@ +```text + MMGEN-TXDO: Create, sign and send an MMGen transaction + USAGE: mmgen-txdo [opts] [ADDR,AMT ... | DATA_SPEC] ADDR [addr file ...] [seed source ...] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -A, --fee-adjust f Adjust transaction fee by factor 'f' (see below) + -b, --brain-params l,p Use seed length 'l' and hash preset 'p' for + brainwallet input + -B, --no-blank Don't blank screen before displaying unspent outputs + -c, --comment-file f Source the transaction's comment from file 'f' + -C, --fee-estimate-confs c Desired number of confirmations for fee estimation + (default: 3) + -d, --outdir d Specify an alternate directory 'd' for output + -e, --echo-passphrase Print passphrase to screen when typing it + -E, --fee-estimate-mode M Specify the network fee estimate mode. Choices: + 'conservative','economical'. Default: 'conservative' + -f, --fee f Transaction fee, as a decimal BTC amount or as + satoshis per byte (an integer followed by 's'). + See FEE SPECIFICATION below. If omitted, fee will be + calculated using network fee estimation. + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -i, --in-fmt f Input is from wallet format 'f' (see FMT CODES below) + -I, --inputs i Specify transaction inputs (comma-separated list of + MMGen IDs or coin addresses). Note that ALL unspent + outputs associated with each address will be included. + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -k, --keys-from-file f Provide additional keys for non-MMGen addresses + -K, --keygen-backend n Use backend 'n' for public key generation. Options + for BTC: 1:libsecp256k1 [default] 2:python-ecdsa + -l, --locktime t Lock time (block height or unix seconds) (default: 0) + -L, --autochg-ignore-labels Ignore labels when autoselecting change addresses + -m, --minconf n Minimum number of confirmations required to spend + outputs (default: 1) + -M, --mmgen-keys-from-file f Provide keys for MMGen addresses in a key- + address file (output of 'mmgen-keygen'). Permits + online signing without an MMGen seed source. The + key-address file is also used to verify MMGen-to-BTC + mappings, so the user should record its checksum. + -O, --old-incog-fmt Specify old-format incognito input + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -P, --passwd-file f Get MMGen wallet passphrase from file 'f' + -q, --quiet Suppress warnings; overwrite files without prompting + -R, --no-rbf Make transaction non-replaceable (non-replace-by-fee + according to BIP 125) + -u, --subseeds n The number of subseed pairs to scan for (default: 100, + maximum: 1000000). Only the default or first supplied + wallet is scanned for subseeds. + -v, --verbose Produce more verbose output + -V, --vsize-adj f Adjust transaction's estimated vsize by factor 'f' + -y, --yes Answer 'yes' to prompts, suppress non-essential output + -z, --show-hash-presets Show information on available hash presets + + + The transaction’s outputs are listed on the command line, while its inputs + are chosen from a list of the wallet’s unspent outputs via an interactive + menu. Alternatively, inputs may be specified using the --inputs option. + + Addresses on the command line can be either native coin addresses or MMGen + IDs in the form SEED_ID:ADDRTYPE_CODE:INDEX. + + Outputs are specified in the form ADDRESS,AMOUNT or ADDRESS. The first form + creates an output sending the given amount to the given address. The bare + address form designates the given address as either the change output or the + sole output of the transaction (excluding any data output). Exactly one bare + address argument is required. + + For convenience, the bare address argument may be given as ADDRTYPE_CODE or + SEED_ID:ADDRTYPE_CODE (see ADDRESS TYPES below). In the first form, the first + unused address of type ADDRTYPE_CODE for each Seed ID in the tracking wallet + will be displayed in a menu, with the user prompted to select one. In the + second form, the user specifies the Seed ID as well, allowing the script to + select the transaction’s change output or single output without prompting. + See EXAMPLES below. + + A single DATA_SPEC argument may also be given on the command line to create + an OP_RETURN data output with a zero spend amount. This is the preferred way + to embed data in the blockchain. DATA_SPEC may be of the form "data":DATA + or "hexdata":DATA. In the first form, DATA is a string in your system’s native + encoding, typically UTF-8. In the second, DATA is a hexadecimal string (with + the leading ‘0x’ omitted) encoding the binary data to be embedded. In both + cases, the resulting byte string must not exceed 80 bytes in length. + + If the transaction fee is not specified on the command line (see FEE + SPECIFICATION below), it will be calculated dynamically using network fee + estimation for the default (or user-specified) number of confirmations. + If network fee estimation fails, the user will be prompted for a fee. + + Network-estimated fees will be multiplied by the value of --fee-adjust, if + specified. + + + ADDRESS TYPES: + + Code Type Description + ---- ---- ----------- + ‘L’ legacy - Legacy uncompressed address + ‘C’ compressed - Compressed P2PKH address + ‘S’ segwit - Segwit P2SH-P2WPKH address + ‘B’ bech32 - Native Segwit (Bech32) address + ‘E’ ethereum - Ethereum address + ‘Z’ zcash_z - Zcash z-address + ‘M’ monero - Monero address + + + FEE SPECIFICATION + + Transaction fees, both on the command line and at the interactive prompt, may + be specified as either absolute BTC amounts, using a plain decimal number, or + as satoshis per byte, using an integer followed by 's', for satoshi. + + + SIGNING NOTES + + Transactions may contain both MMGen or non-MMGen input addresses. + + To sign non-MMGen inputs, a bitcoind wallet dump or flat key list is used + as the key source (--keys-from-file option). + + To sign MMGen inputs, key data is generated from a seed as with the + mmgen-addrgen and mmgen-keygen commands. Alternatively, a key-address file + may be used (--mmgen-keys-from-file option). + + Multiple wallets or other seed files can be listed on the command line in + any order. If the seeds required to sign the transaction’s inputs are not + found in these files (or in the default wallet), the user will be prompted + for seed data interactively. + + To prevent an attacker from crafting transactions with bogus MMGen-to-Bitcoin + address mappings, all outputs to MMGen addresses are verified with a seed + source. Therefore, seed files or a key-address file for all MMGen outputs + must also be supplied on the command line if the data can’t be found in the + default wallet. + + Seed source files must have the canonical extensions listed in the 'FileExt' + column below: + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + + EXAMPLES: + + Send 0.123 BTC to an external Bitcoin address, returning the change to a + specific MMGen address in the tracking wallet: + + $ mmgen-txdo bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t,0.123 01ABCDEF:B:7 + + Same as above, but select the change address automatically: + + $ mmgen-txdo bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t,0.123 01ABCDEF:B + + Same as above, but select the change address automatically by address type: + + $ mmgen-txdo bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t,0.123 B + + Same as above, but reduce verbosity and specify fee of 20 satoshis + per byte: + + $ mmgen-txdo -q -f 20s bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t,0.123 B + + Send entire balance of selected inputs minus fee to an external Bitcoin + address: + + $ mmgen-txdo bc1qj87nveegsvwmz8yj759xgua2vx2tzsywlny44t + + Send entire balance of selected inputs minus fee to first unused wallet + address of specified type: + + $ mmgen-txdo B + + MMGEN v15.1.dev17 February 2025 MMGEN-TXDO(1) +``` diff --git a/doc/wiki/commands/command-help-txsend.md b/doc/wiki/commands/command-help-txsend.md new file mode 100644 index 00000000..c85f7035 --- /dev/null +++ b/doc/wiki/commands/command-help-txsend.md @@ -0,0 +1,22 @@ +```text + MMGEN-TXSEND: Send a signed MMGen cryptocoin transaction + USAGE: mmgen-txsend [opts] [signed transaction file] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -a, --autosign Send an autosigned transaction created by ‘mmgen-txcreate + --autosign’. The removable device is mounted and unmounted + automatically. The transaction file argument must be omitted + when using this option + -A, --abort Abort an unsent transaction created by ‘mmgen-txcreate + --autosign’ and delete it from the removable device. The + transaction may be signed or unsigned. + -d, --outdir d Specify an alternate directory 'd' for output + -q, --quiet Suppress warnings; overwrite files without prompting + -s, --status Get status of a sent transaction (or the current transaction, + whether sent or unsent, when used with --autosign) + -v, --verbose Be more verbose + -y, --yes Answer 'yes' to prompts, suppress non-essential output + + MMGEN v15.1.dev17 February 2025 MMGEN-TXSEND(1) +``` diff --git a/doc/wiki/commands/command-help-txsign.md b/doc/wiki/commands/command-help-txsign.md new file mode 100644 index 00000000..2ba0a731 --- /dev/null +++ b/doc/wiki/commands/command-help-txsign.md @@ -0,0 +1,86 @@ +```text + MMGEN-TXSIGN: Sign cryptocoin transactions generated by mmgen-txcreate + USAGE: mmgen-txsign [opts] ... [seed source]... + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -b, --brain-params l,p Use seed length 'l' and hash preset 'p' for + brainwallet input + -d, --outdir d Specify an alternate directory 'd' for output + -D, --tx-id Display transaction ID and exit + -e, --echo-passphrase Print passphrase to screen when typing it + -E, --use-internal-keccak-module Force use of the internal keccak module + -i, --in-fmt f Input is from wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -O, --old-incog-fmt Specify old-format incognito input + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -k, --keys-from-file f Provide additional keys for non-MMGen addresses + -K, --keygen-backend n Use backend 'n' for public key generation. Options + for BTC: 1:libsecp256k1 [default] 2:python-ecdsa + -M, --mmgen-keys-from-file f Provide keys for MMGen addresses in a key- + address file (output of 'mmgen-keygen'). Permits + online signing without an MMGen seed source. The + key-address file is also used to verify MMGen-to-BTC + mappings, so the user should record its checksum. + -P, --passwd-file f Get MMGen wallet passphrase from file 'f' + -q, --quiet Suppress warnings; overwrite files without prompting + -I, --info Display information about the transaction and exit + -t, --terse-info Like '--info', but produce more concise output + -u, --subseeds n The number of subseed pairs to scan for (default: 100, + maximum: 1000000). Only the default or first supplied + wallet is scanned for subseeds. + -v, --verbose Produce more verbose output + -V, --vsize-adj f Adjust transaction's estimated vsize by factor 'f' + -W, --allow-non-wallet-swap Allow signing of swap transactions that send funds + to non-wallet addresses + -y, --yes Answer 'yes' to prompts, suppress non-essential output + + + Transactions may contain both MMGen or non-MMGen input addresses. + + To sign non-MMGen inputs, a bitcoind wallet dump or flat key list is used + as the key source (--keys-from-file option). + + To sign MMGen inputs, key data is generated from a seed as with the + mmgen-addrgen and mmgen-keygen commands. Alternatively, a key-address file + may be used (--mmgen-keys-from-file option). + + Multiple wallets or other seed files can be listed on the command line in + any order. If the seeds required to sign the transaction’s inputs are not + found in these files (or in the default wallet), the user will be prompted + for seed data interactively. + + To prevent an attacker from crafting transactions with bogus MMGen-to-Bitcoin + address mappings, all outputs to MMGen addresses are verified with a seed + source. Therefore, seed files or a key-address file for all MMGen outputs + must also be supplied on the command line if the data can’t be found in the + default wallet. + + Seed source files must have the canonical extensions listed in the 'FileExt' + column below: + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-TXSIGN(1) +``` diff --git a/doc/wiki/commands/command-help-walletchk.md b/doc/wiki/commands/command-help-walletchk.md new file mode 100644 index 00000000..a4cede98 --- /dev/null +++ b/doc/wiki/commands/command-help-walletchk.md @@ -0,0 +1,55 @@ +```text + MMGEN-WALLETCHK: Check validity of the default or specified MMGen wallet + USAGE: mmgen-walletchk [opts] [infile] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -e, --echo-passphrase Echo passphrases and other user input to screen + -i, --in-fmt f Input from wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -O, --old-incog-fmt Specify old-format incognito input + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -v, --verbose Produce more verbose output + + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it’s recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-WALLETCHK(1) +``` diff --git a/doc/wiki/commands/command-help-walletconv.md b/doc/wiki/commands/command-help-walletconv.md new file mode 100644 index 00000000..9572ebfc --- /dev/null +++ b/doc/wiki/commands/command-help-walletconv.md @@ -0,0 +1,66 @@ +```text + MMGEN-WALLETCONV: Convert the default or specified MMGen wallet from one format to another + USAGE: mmgen-walletconv [opts] [infile] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrases and other user input to screen + -i, --in-fmt f Convert from wallet format 'f' (see FMT CODES below) + -o, --out-fmt f Convert to wallet format 'f' (see FMT CODES below) + -H, --hidden-incog-input-params f,o Read hidden incognito data from file + 'f' at offset 'o' (comma-separated) + -J, --hidden-incog-output-params f,o Write hidden incognito data to file + 'f' at offset 'o' (comma-separated). File 'f' will be + created if necessary and filled with random data. + -O, --old-incog-fmt Specify old-format incognito input + -k, --keep-passphrase Reuse passphrase of input wallet for output wallet + -K, --keep-hash-preset Reuse hash preset of input wallet for output wallet + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -L, --label l Specify a label 'l' for output wallet + -m, --keep-label Reuse label of input wallet for output wallet + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -N, --passwd-file-new-only Use passwd file only for new, not existing, wallet + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Write wallet data to stdout instead of file + -v, --verbose Produce more verbose output + + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it’s recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-WALLETCONV(1) +``` diff --git a/doc/wiki/commands/command-help-walletgen.md b/doc/wiki/commands/command-help-walletgen.md new file mode 100644 index 00000000..44c56108 --- /dev/null +++ b/doc/wiki/commands/command-help-walletgen.md @@ -0,0 +1,58 @@ +```text + MMGEN-WALLETGEN: Generate an MMGen wallet from a random seed + USAGE: mmgen-walletgen [opts] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -d, --outdir d Output files to directory 'd' instead of working dir + -e, --echo-passphrase Echo passphrases and other user input to screen + -o, --out-fmt f Output to wallet format 'f' (see FMT CODES below) + -J, --hidden-incog-output-params f,o Write hidden incognito data to file + 'f' at offset 'o' (comma-separated). File 'f' will be + created if necessary and filled with random data. + -l, --seed-len l Specify wallet seed length of 'l' bits. This option + is required only for brainwallet and incognito inputs + with non-standard (< 256-bit) seed lengths. + -L, --label l Specify a label 'l' for output wallet + -p, --hash-preset p Use the scrypt hash parameters defined by preset 'p' + for password hashing (default: '3') + -z, --show-hash-presets Show information on available hash presets + -P, --passwd-file f Get wallet passphrase from file 'f' + -q, --quiet Produce quieter output; suppress some warnings + -r, --usr-randchars n Get 'n' characters of additional randomness from user + (min=10, max=80, default=30) + -S, --stdout Write wallet data to stdout instead of file + -v, --verbose Produce more verbose output + + + PASSPHRASE NOTE: + + For passphrases all combinations of whitespace are equal, and leading and + trailing space are ignored. This permits reading passphrase or brainwallet + data from a multi-line file with free spacing and indentation. + + BRAINWALLET NOTE: + + To thwart dictionary attacks, it’s recommended to use a strong hash preset + with brainwallets. For a brainwallet passphrase to generate the correct + seed, the same seed length and hash preset parameters must always be used. + + + FMT CODES: + + Format FileExt Valid codes + ------ ------- ----------- + BIP39Mnemonic .bip39 bip39 + Brainwallet .mmbrain mmbrain,brainwallet,brain,bw + DieRollWallet .b6d b6d,die,dieroll + IncogWallet .mmincog mmincog,incog,icg,i + IncogWalletHex .mmincox mmincox,incox,incog_hex,ix,xi + IncogWalletHidden None incog_hidden,hincog,ih,hi + MMGenHexSeedFile .mmhex seedhex,hexseed,mmhex + MMGenMnemonic .mmwords mmwords,words,mnemonic,mn,m + MMGenSeedFile .mmseed mmseed,seed,s + MMGenWallet .mmdat wallet,w + PlainHexSeedFile .hex hex,rawhex,plainhex + + MMGEN v15.1.dev17 February 2025 MMGEN-WALLETGEN(1) +``` diff --git a/doc/wiki/commands/command-help-xmrwallet.md b/doc/wiki/commands/command-help-xmrwallet.md new file mode 100644 index 00000000..3c3574f1 --- /dev/null +++ b/doc/wiki/commands/command-help-xmrwallet.md @@ -0,0 +1,503 @@ +```text + MMGEN-XMRWALLET: Perform various Monero wallet and transacting operations for + addresses in an MMGen XMR key-address file + USAGE: mmgen-xmrwallet [opts] create | sync | list | view | listview | dump | restore [xmr_keyaddrfile] [wallets] + mmgen-xmrwallet [opts] label [xmr_keyaddrfile] LABEL_SPEC + mmgen-xmrwallet [opts] new [xmr_keyaddrfile] NEW_ADDRESS_SPEC + mmgen-xmrwallet [opts] transfer [xmr_keyaddrfile] TRANSFER_SPEC + mmgen-xmrwallet [opts] sweep | sweep_all [xmr_keyaddrfile] SWEEP_SPEC + mmgen-xmrwallet [opts] submit [TX_file] + mmgen-xmrwallet [opts] relay + mmgen-xmrwallet [opts] resubmit | abort (for use with --autosign only) + mmgen-xmrwallet [opts] txview | txlist [TX_file] ... + mmgen-xmrwallet [opts] export-outputs | export-outputs-sign | import-key-images [wallets] + OPTIONS: + -h, --help Print this help message + --longhelp Print help message for long (global) options + -a, --autosign Use appropriate outdir and other params for + autosigning operations (implies --watch-only). + When this option is in effect, filename argu- + ments must be omitted, as files are located + automatically. + -f, --priority N Specify an integer priority ‘N’ for inclusion + of a transaction in the blockchain (higher + number means higher fee). Valid parameters: + 1=low 2=normal 3=high 4=highest. If option + is omitted, the default priority will be used + -F, --full-address Print addresses in full instead of truncating + -m, --autosign-mountpoint P Specify the autosign mountpoint (defaults to + ‘/mnt/mmgen_autosign’, implies --autosign) + -b, --rescan-blockchain Rescan the blockchain if wallet fails to sync + -d, --outdir D Save transaction files to directory 'D' + instead of the working directory + -D, --daemon H:P Connect to the monerod at HOST:PORT + -e, --skip-empty-accounts Skip display of empty accounts in wallets + where applicable + -E, --skip-empty-addresses Skip display of used empty addresses in + wallets where applicable + -k, --use-internal-keccak-module Force use of the internal keccak module + -p, --hash-preset P Use scrypt hash preset 'P' for password + hashing (default: '3') + -P, --rescan-spent Perform a rescan of spent outputs. Used only + with the ‘export-outputs-sign’ operation + -R, --tx-relay-daemon H:P[:H:P] Relay transactions via a monerod specified by + HOST:PORT[:PROXY_IP:PROXY_PORT] + -r, --restore-height H Scan from height 'H' when creating wallets. + Use special value ‘current’ to create empty + wallet at current blockchain height. + -R, --no-relay Save transaction to file instead of relaying + -s, --no-start-wallet-daemon Don’t start the wallet daemon at startup + -S, --no-stop-wallet-daemon Don’t stop the wallet daemon at exit + -W, --watch-only Create or operate on watch-only wallets + -w, --wallet-dir D Output or operate on wallets in directory 'D' + instead of the working directory + -U, --wallet-rpc-user user Wallet RPC username (currently: 'monero') + -P, --wallet-rpc-password pass Wallet RPC password (currently: [scrubbed]) + + + Many operations take an optional ‘wallets’ argument: one or more address + indexes (expressed as a comma-separated list and/or hyphenated range) in + the default or specified key-address file, each corresponding to a Monero + wallet with the same index. If the argument is omitted, all wallets are + operated upon. + + All operations except for ‘relay’ require a running Monero daemon (monerod). + Unless --daemon is specified, the daemon is assumed to be listening on + localhost at the default RPC port. + + If --tx-relay-daemon is specified, the monerod at HOST:PORT will be used to + relay any created transactions. PROXY_IP:PROXY_PORT, if specified, may point + to a SOCKS proxy, in which case HOST may be a Tor onion address. + + All communications use the RPC protocol via SSL (HTTPS) or Tor. RPC over + plain HTTP is not supported. + + + SUPPORTED OPERATIONS + + create - create wallets for all or specified addresses in key-address file + sync - sync wallets for all or specified addresses in key-address file + and display a summary of accounts and balances + list - same as ‘sync’, but also list detailed address info for accounts + view - display a summary of accounts and balances in offline mode. May + be invoked without a running monerod + listview - same as ‘view’, but also list detailed address info for accounts + label - set a label for an address + new - create a new account in a wallet, or a new address in an account + transfer - transfer specified XMR amount from specified wallet:account to + specified address + sweep - sweep funds in specified wallet:account to new address in same + account, or new or specified account in another wallet + sweep_all - same as above, but sweep balances of all addresses in the account + relay - relay a transaction from a transaction file created using ‘sweep’ + or ‘transfer’ with the --no-relay option + submit - submit an autosigned transaction to a wallet and the network + resubmit - resubmit most recently submitted autosigned transaction (other + actions are required: see Exporting Outputs below) + abort - abort the current transaction created with --autosign. The + transaction may be signed or unsigned + txview - display detailed information about a transaction file or files + txlist - same as above, but display terse information in tabular format + dump - produce JSON dumps of wallet metadata (accounts, addresses and + labels) for a list or range of wallets + restore - same as ‘create’, but additionally restore wallet metadata from + the corresponding JSON dump files created with ‘dump’ + export-outputs - export outputs of watch-only wallets for import into + their corresponding offline wallets + export-outputs-sign - same as above, plus request offline wallet to create + signed key images for import by ‘import-key-images’ + import-key-images - import key images signed by offline wallets into their + corresponding watch-only wallets + + + ‘LABEL’ OPERATION NOTES + + This operation takes a LABEL_SPEC arg with the following format: + + WALLET:ACCOUNT:ADDRESS,"label text" + + where WALLET is a wallet number, ACCOUNT an account index, and ADDRESS an + address index. + + + ‘NEW’ OPERATION NOTES + + This operation takes a NEW_ADDRESS_SPEC arg with the following format: + + WALLET[:ACCOUNT][,"label text"] + + where WALLET is a wallet number and ACCOUNT an account index. If ACCOUNT + is omitted, a new account will be created in the wallet. Otherwise a new + address will be created in the specified account. An optional label text + may be appended to the spec following a comma. + + + ‘TRANSFER’ OPERATION NOTES + + The transfer operation takes a TRANSFER_SPEC arg with the following format: + + SOURCE:ACCOUNT:ADDRESS,AMOUNT + + where SOURCE is a wallet number, ACCOUNT the source account index, ADDRESS + the destination Monero address and AMOUNT the XMR amount to be sent. + + + ‘SWEEP’ AND ‘SWEEP_ALL’ OPERATION NOTES + + The sweep and sweep_all operations take a SWEEP_SPEC arg with the following + format: + + SOURCE:ACCOUNT[,DEST[:ACCOUNT]] + + where SOURCE and DEST are wallet numbers and ACCOUNT account indices for the + respective wallets. + + If DEST is omitted, a new address will be created in ACCOUNT of SOURCE, and + funds from ACCOUNT of SOURCE will be swept into it. + + If DEST is included without its related ACCOUNT, funds from ACCOUNT of SOURCE + will be swept into a newly created account in DEST, or the last existing + account of DEST, if requested by the user. + + If both account indices are included, funds from ACCOUNT of SOURCE will be + swept into ACCOUNT of DEST. + + The user is prompted before addresses are created or funds transferred. + + With ‘sweep’, if the source account has more than one address with a balance, + the balance of a single randomly chosen address will be swept. To sweep the + balances of all addresses in an account, use ‘sweep_all’. + + + ‘SUBMIT’ AND ‘RELAY’ OPERATION NOTES + + By default, transactions are relayed to a monerod running on localhost at the + default RPC port. To relay transactions to a remote or non-default monerod + via optional SOCKS proxy, use the --tx-relay-daemon option described above. + + When ‘submit’ is used with --autosign, the transaction filename must be + omitted. + + + ‘DUMP’ AND ‘RESTORE’ OPERATION NOTES + + These commands produce and read JSON wallet dump files with the same + filenames as their source wallets, plus a .dump extension. + + It’s highly advisable to make regular dumps of your Monero wallets and back + up the dump files, which can be used to easily regenerate the wallets using + the ‘restore’ operation, should the need arise. For watch-only autosigning + wallets, creating the dumps is as easy as executing ‘mmgen-xmrwallet + --autosign dump’ from your wallet directory. The dump files are formatted + JSON and thus suitable for efficient incremental backup using git. + + + ‘TXVIEW’ AND ‘TXLIST’ OPERATION NOTES + + Transactions are displayed in chronological order based on submit time or + creation time. With --autosign, submitted transactions on the removable + device are displayed. + + + SECURITY WARNING + + If you have an existing MMGen Monero hot wallet setup, you’re strongly + advised to migrate to offline autosigning to avoid further exposing your + private keys on your network-connected machine. See OFFLINE AUTOSIGNING + and ‘Replacing Existing Hot Wallets with Watch-Only Wallets’ below. + + + EXAMPLES + + Note that the transacting examples in this section apply for a hot wallet + setup, which is now deprecated. See OFFLINE AUTOSIGNING below. + + Generate an XMR key-address file with 5 addresses from your default wallet: + $ mmgen-keygen --coin=xmr 1-5 + + Create 3 Monero wallets from the key-address file: + $ mmgen-xmrwallet create *.akeys.mmenc 1-3 + + After updating the blockchain, sync wallets 1 and 2: + $ mmgen-xmrwallet sync *.akeys.mmenc 1,2 + + Sweep all funds from account #0 of wallet 1 to a new address: + $ mmgen-xmrwallet sweep *.akeys.mmenc 1:0 + + Same as above, but use a TX relay on the Tor network: + $ mmgen-xmrwallet --tx-relay-daemon=abcdefghijklmnop.onion:127.0.0.1:9050 sweep *.akeys.mmenc 1:0 + + Sweep all funds from account #0 of wallet 1 to wallet 2: + $ mmgen-xmrwallet sweep *.akeys.mmenc 1:0,2 + + Send 0.1 XMR from account #0 of wallet 2 to an external address: + $ mmgen-xmrwallet transfer *.akeys.mmenc 2:0:,0.1 + + Sweep all funds from account #0 of wallet 2 to a new address, saving the + transaction to a file: + $ mmgen-xmrwallet --no-relay sweep *.akeys.mmenc 2:0 + + Relay the created sweep transaction via a host on the Tor network: + $ mmgen-xmrwallet --tx-relay-daemon=abcdefghijklmnop.onion:127.0.0.1:9050 relay *XMR*.sigtx + + Create a new account in wallet 2: + $ mmgen-xmrwallet new *.akeys.mmenc 2 + + Create a new address in account 1 of wallet 2, with label: + $ mmgen-xmrwallet new *.akeys.mmenc 2:1,"from ABC exchange" + + View all the XMR transaction files in the current directory, sending output + to pager: + $ mmgen-xmrwallet --pager txview *XMR*.sigtx + + + OFFLINE AUTOSIGNING + + Tutorial + + Master the basic concepts of the MMGen wallet system and the processes of + wallet creation, conversion and backup described in the Getting Started + guide. Optionally create a default MMGen wallet on your offline machine + using ‘mmgen-walletgen’. If you choose not to do this, you’ll be prompted + for a seed phrase at the start of each signing session. + + Familiarize yourself with the autosigning setup process as described in + ‘mmgen-autosign --help’. Prepare your removable device and set up the + mountpoints on your offline and online machines according to the instructions + therein. Install ‘monero-wallet-rpc’ on your offline machine and the Monero + CLI wallet and daemon binaries on your online machine. + + On the offline machine, insert the removable device and execute: + + $ mmgen-autosign --xmrwallets=1-2,7 setup + + This will create 3 Monero signing wallets with indexes 1, 2 and 7 and primary + addresses matching your seed’s Monero addresses with the same indexes. (Note + that these particular indexes are arbitrary, for purposes of illustration + only. Feel free to choose your own list and/or range – or perhaps just the + number ‘1’ if one wallet is all you require). + + These signing wallets are written to volatile memory and exist only for the + duration of the signing session, just like the temporary MMGen signing wallet + they’re generated from (see ‘mmgen-autosign --help’). + + A viewkey-address file for the 3 addresses will also be written to the + removable device. The data in this file will be used to create and access + watch-only wallets on your online machine that match the signing wallets + you’ve just created. + + When the setup operation completes, extract the removable device and restart + the autosign script in wait mode: + + $ mmgen-autosign --coins=xmr --stealth-led wait + + Your only further physical interaction with the offline signing machine now + (assuming everything goes as planned) will be inserting and extracting the + removable device on it. And this is the whole point of autosigning: to make + cold signing as convenient as possible, almost like transacting with a hot + wallet. + + If your signing machine is an SoC with MMGen Wallet LED support (see + ‘mmgen-autosign --help’), a quickly flashing LED will indicate that signing + is in progress, a slowly flashing LED an error condition, and no LED that the + program is idle and waiting for device insertion. + + On your online machine, start monerod, wait until it’s fully synced with the + network, insert the removable device and execute: + + $ mmgen-xmrwallet --autosign --restore-height=current create + + This will create 3 watch-only wallets matching your 3 offline signing wallets + and write them to the current directory (an alternate wallet directory may be + specified with the --wallet-dir option). + + Note that --restore-height=current is required to prevent a time-consuming + full sync of the wallets from the Genesis block, a meaningless waste of time + in this case since the wallets contain no funds. + + Also make note of the --autosign option, a requirement for ALL autosigning + operations with ‘mmgen-xmrwallet’. + + Now list your newly created wallets: + + $ mmgen-xmrwallet --autosign list + + Note that you can also use the ‘sync’ operation here, which produces more + abbreviated output than ‘list’. + + Send some XMR (preferably a tiny amount) to the primary address of wallet #7. + Once the transaction has confirmed, invoke ‘sync’ or ‘list’ again to verify + the funds have arrived. + + Since offline wallet #7 has no knowledge of the funds received by its online + counterpart, we need to update its state. Export the outputs of watch-only + wallet #7 as follows: + + $ mmgen-xmrwallet --autosign export-outputs 7 + + The outputs are now saved to the removable device and will be imported into + offline wallet #7 when you sign your first transaction. + + Now you’re ready to begin transacting. Let’s start by sweeping your funds in + wallet #7’s primary address (account 0) to a new address in the same account: + + $ mmgen-xmrwallet --autosign sweep 7:0 + + This operation creates an unsigned sweep transaction and saves it to the + removable device. + + Now extract the removable device and insert it on the offline machine. Wait + for the quick LED flashing to stop (or the blue ‘safe to extract’ message, in + the absence of LED support), signalling that signing is complete. + + Note that the offline wallet has performed two operations in one go here: + an import of wallet outputs from the previous step and the signing of your + just-created sweep transaction. + + Extract the removable device, insert it on your online machine and submit the + signed sweep transaction to the watch-only wallet, which will broadcast it to + the network: + + $ mmgen-xmrwallet --autosign submit + + Note that you may also relay the transaction to a remote daemon, optionally + via a Tor proxy, using the --tx-relay-daemon option documented above. + + Once your transaction has confirmed, invoke ‘list’ or ‘sync’ to view your + wallets’ balances. + + Congratulations, you’ve performed your first autosigned Monero transaction! + + For other examples, consult the EXAMPLES section above, noting the following + differences that apply to autosigning: + + 1) The --autosign option must always be included. + 2) The key-address file argument must always be omitted. + 3) The ‘relay’ operation is replaced by ‘submit’, with TX filename omitted. + 4) Always remember to sign your transactions after a ‘sweep’ or ‘transfer’ + operation. + 5) Always remember to export a wallet’s outputs when it has received funds + from an outside source. + + + Exporting Outputs + + Exporting outputs from a watch-only wallet is generally required in only + three cases: + + a) at the start of each signing session (after ‘mmgen-autosign setup’); + b) after the wallet has received funds from an outside source or another + wallet; and + c) after performing a ‘resubmit’ operation. + + You might also need to do it, however, if an offline wallet is unable to sign + a transaction due to missing outputs. + + At the start of a new signing session, you must export outputs from ALL + wallets you intend to transact with. This is necessary because the offline + signing wallets have just been created and know nothing about the state of + their online counterparts. + + Export outputs from a wallet as follows (for all wallets, omit the index): + + $ mmgen-xmrwallet --autosign export-outputs + + Then insert the removable device on the offline machine. This will import + the outputs into the corresponding signing wallet(s) (and optionally redo any + failed transaction signing operation). + + Following a ‘resubmit’, use the ‘export-outputs-sign’ operation instead, and + add the --rescan-spent option: + + $ mmgen-xmrwallet --autosign --rescan-spent export-outputs-sign + + Here the offline signing wallet(s) will also create signed key images. Insert + the removable device on your online machine and import the signed key images + into your online wallet as follows: + + $ mmgen-xmrwallet --autosign import-key-images + + Usually, this is all that is required. However, if your wallet continues to + show an incorrect balance after the import operation, you’ll need to re-run + ‘export-outputs-sign’ with the --rescan-blockchain option, followed by another + offline signing and online key image import. Note that blockchain rescans can + take a long time, so patience is required here. + + + Replacing Existing Hot Wallets with Watch-Only Wallets + + If you have an existing MMGen Monero hot wallet setup, you can migrate to + offline transaction signing by ‘cloning’ your existing hot wallets as + watch-only ones via the ‘dump’ and ‘restore’ operations described below. + + For additional security, it’s also wise to create new watch-only wallets that + have never had keys exposed on an online machine and gradually transfer all + funds from your ‘cloned’ wallets to them. The creation of new wallets is + explained in the Tutorial above. + + Start the cloning process by making dump files of your hot wallets’ metadata + (accounts, subaddresses and labels). ‘cd’ to the wallet directory (or use + --wallet-dir) and execute: + + $ mmgen-xmrwallet dump /path/to/key-address-file.akeys{.mmenc} + + If you’ve been transacting with the wallets, you know where their key-address + file is along with its encryption password, if any. Supply an additional + index range and/or list at the end of the command line if the key-address + file contains more wallets than exist on disk or there are wallets you wish + to ignore. + + Do a directory listing to verify that the dump files are present alongside + their source wallet files ending with ‘MoneroWallet’. Then execute: + + $ mmgen-xmrwallet --watch-only restore /path/to/key-address-file.akeys{.mmenc} + + This will create watch-only wallets that “mirror” the old hot wallets and + populate them with the metadata saved in the dump files. + + Note that watch-only wallet filenames end with ‘MoneroWatchOnlyWallet’. Your + old hot wallets will be ignored from here on. Eventually, you’ll want to + destroy them. + + Your new wallets must now be synced with the blockchain. Begin by starting + monerod and synchronizing with the network. + + Mount ‘/mnt/mmgen_autosign’ and locate the file in the ‘xmr’ directory with + the .vkeys extension, which contains the passwords you’ll need to log into + the wallets. This is a plain text file viewable with ‘cat’, ‘less’ or your + favorite text editor. + + Then log into each watch-only wallet in turn as follows: + + $ monero-wallet-cli --wallet + + Upon login, each wallet will begin syncing, a process which can take more + than an hour depending on your hardware. Note, however, that the process + is interruptible: you may exit ‘monero-wallet-cli’ at any point, log back + in again and resume where you left off. + + Once your watch-only wallets are synced, you need to export their outputs: + + $ mmgen-xmrwallet --autosign export-outputs-sign + + Now insert the removable device on the offline machine and wait until the LED + stops flashing (or ‘safe to extract’). The wallet outputs are now imported + into the signing wallets and corresponding signed key images have been + written to the removable device. + + Insert the removable device on your online machine and import the key images + into your watch-only wallets: + + $ mmgen-xmrwallet --autosign import-key-images + + Congratulations, your watch-only wallets are now complete and you may begin + transacting! First perform a ‘sync’ or ‘list’ to ensure that your balances + are correct. Then you might try sweeping some funds as described in the + Tutorial above. + + Once you’ve gained proficiency with the autosigning process and feel ready + to delete your old hot wallets, make sure to do so securely using ‘shred’, + ‘wipe’ or some other secure deletion utility. + + MMGEN v15.1.dev17 February 2025 MMGEN-XMRWALLET(1) +```