diff --git a/Install-MMGen-on-Linux.md b/Install-MMGen-on-Linux.md index 9aa6f5f..b92c35f 100644 --- a/Install-MMGen-on-Linux.md +++ b/Install-MMGen-on-Linux.md @@ -26,6 +26,11 @@ $ sudo pacman -S curl git gcc libtool make autoconf automake autogen pcre python $ python3 -m pip install --user --upgrade pip setuptools build wheel ``` +If you get an ‘externally-managed-environment’ error (with Debian bookworm, +for example), add --break-system-packages to the command line. Note that this +will not in fact break any system packages, as pip installs all packages under +the user’s home directory when --user is in effect. + #### Install MMGen: Make sure that `~/.local/bin` is in `PATH`. Existing MMGen users should delete diff --git a/Install-MMGen-on-Microsoft-Windows.md b/Install-MMGen-on-Microsoft-Windows.md index e6eaba8..194f9f7 100644 --- a/Install-MMGen-on-Microsoft-Windows.md +++ b/Install-MMGen-on-Microsoft-Windows.md @@ -273,38 +273,18 @@ Thanks to a faulty implementation of the `scrypt` function included in Python’ password hashing, i.e. hash presets greater than `3`. Installing the package is therefore highly recommended. -On your online machine, download the tar archive: +On your online machine, clone the Py-Scrypt source repository: ```text -$ pip3 download --no-deps scrypt==0.8.20 +$ git clone https://github.com/holgern/py-scrypt.git ``` -On your offline machine, unpack and enter the archive: - -```text -$ tar fax scrypt-0.8.20.tar.gz -$ cd scrypt-0.8.20 -``` - -Open the file `setup.py` in your text editor. Right before the line reading: - -```python -elif sys.platform.startswith('win32'): -``` - -insert the following lines, carefully preserving indentation: - -```python -elif os.environ.get('MSYSTEM') == 'MSYS': - define_macros = [] - includes = ['/mingw64/include'] - libraries = ['libcrypto'] - CFLAGS.append('-O2') -``` - -Save the file and exit the editor. Now build and install: +Copy the cloned repo to your offline machine. + +On both online and offline machines, enter the repo root and install: ```text +$ cd py-scrypt $ python3 setup.py install --user ``` diff --git a/Test-Suite.md b/Test-Suite.md index fb8fce6..772e6ba 100644 --- a/Test-Suite.md +++ b/Test-Suite.md @@ -74,7 +74,7 @@ $ test/test.py clean Run the test suite in fast mode, skipping altcoin tests: ```text -$ test/test-release.sh -F noalt +$ test/test-release.sh -FA ``` ### Complete testing (BTC plus all supported altcoins) diff --git a/command-help-addrgen.md b/command-help-addrgen.md index 4278f35..cc2f748 100644 --- a/command-help-addrgen.md +++ b/command-help-addrgen.md @@ -115,5 +115,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-ADDRGEN(1) + MMGEN v13.3.dev55 May 2023 MMGEN-ADDRGEN(1) ``` diff --git a/command-help-addrimport.md b/command-help-addrimport.md index 2a5c9a4..9d2139d 100644 --- a/command-help-addrimport.md +++ b/command-help-addrimport.md @@ -31,5 +31,5 @@ It’s recommended to use ‘--rpc-backend=aio’ with ‘--rescan’. - MMGEN v13.2.0 August 2022 MMGEN-ADDRIMPORT(1) + MMGEN v13.3.dev55 May 2023 MMGEN-ADDRIMPORT(1) ``` diff --git a/command-help-autosign.md b/command-help-autosign.md index 98559a3..b6d117d 100644 --- a/command-help-autosign.md +++ b/command-help-autosign.md @@ -1,13 +1,15 @@ ```text - MMGEN-AUTOSIGN: Auto-sign MMGen transactions and message files - USAGE: mmgen-autosign [opts] [command] + 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 options (common options) -c, --coins c Coins to sign for (comma-separated list) + -C, --clean Remove unneeded files on the removable device -I, --no-insert-check Don’t check for device insertion -l, --led Use status LED to signal standby, busy and error - -m, --mountpoint M Specify an alternate mountpoint 'M' (default: '/mnt/tx') + -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 @@ -18,22 +20,27 @@ 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') + -x, --xmrwallets L Range or list of wallets to be used for XMR autosigning - COMMANDS + OPERATIONS - gen_key - generate the wallet encryption key and copy it to '/mnt/tx' - setup - generate the wallet encryption key and wallet + gen_key - generate the wallet encryption key and copy it to the mountpoint + PosixPath('/mnt/mmgen_autosign') (as currently configured) + setup - generate both wallet encryption key and temporary signing wallet wait - start in loop mode: wait-mount-sign-unmount-wait - USAGE NOTES + USAGE NOTES - If invoked with no command, the program mounts a removable device containing - unsigned MMGen transactions and/or message files, signs them, unmounts the - removable device and exits. + 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 + 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. @@ -42,35 +49,58 @@ ready for device insertion or removal. The removable device must have a partition labeled MMGEN_TX with a user- - writable root directory and a directory named '/tx', where unsigned MMGen - transactions are placed. Optionally, the directory '/msg' may also be created - and unsigned message files created by `mmgen-msg` placed in this directory. + writable root directory and a directory named ‘/tx’, where unsigned MMGen + transactions are placed. Optionally, the directory ‘/msg’ may be created + and unsigned message files produced by ‘mmgen-msg’ placed there. - On the signing machine the mount point '/mnt/tx' must exist and /etc/fstab - must contain the following entry: + On both the signing and online machines the mountpoint ‘/mnt/mmgen_autosign’ + (as currently configured) must exist and ‘/etc/fstab’ must contain the + following entry: - LABEL='MMGEN_TX' /mnt/tx auto noauto,user 0 0 + LABEL=MMGEN_TX /mnt/mmgen_autosign auto noauto,user 0 0 - Transactions are signed with a wallet on the signing machine (in the directory - '/dev/shm/autosign') encrypted with a 64-character hexadecimal password saved - in the file `autosign.key` in the root of the removable device partition. + 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 wallet can be created in one operation by invoking the - command with 'setup' with the removable device inserted. In this case, the - user will be prompted for a seed mnemonic. + 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 wallet can be created separately by first - invoking the command with 'gen_key' and then creating and encrypting the + 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 -r0 -q -iwords -d/dev/shm/autosign -p1 -P/mnt/tx/autosign.key -Llabel + $ mmgen-walletconv -iwords -d/dev/shm/autosign -p1 -N -P/mnt/mmgen_autosign/autosign.key -Lfoo - Note that the hash preset must be '1'. Multiple wallets are permissible. + 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). - For good security, it's advisable to re-generate a new wallet and key for - each signing session. + Autosigning is currently available only on Linux-based platforms. - This command is currently available only on Linux-based platforms. - MMGEN v13.2.0 August 2022 MMGEN-AUTOSIGN(1) + 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 v13.3.dev55 May 2023 MMGEN-AUTOSIGN(1) ``` diff --git a/command-help-keygen.md b/command-help-keygen.md index 08d7f0f..f0df1d2 100644 --- a/command-help-keygen.md +++ b/command-help-keygen.md @@ -31,6 +31,7 @@ (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 @@ -119,5 +120,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-KEYGEN(1) + MMGEN v13.3.dev55 May 2023 MMGEN-KEYGEN(1) ``` diff --git a/command-help-msg.md b/command-help-msg.md index 0f257e4..3cf08eb 100644 --- a/command-help-msg.md +++ b/command-help-msg.md @@ -104,5 +104,5 @@ Verify and display the exported JSON signature data: $ mmgen-msg verify signatures.json - MMGEN v13.2.0 August 2022 MMGEN-MSG(1) + MMGEN v13.3.dev55 May 2023 MMGEN-MSG(1) ``` diff --git a/command-help-passchg.md b/command-help-passchg.md index 845be70..715996e 100644 --- a/command-help-passchg.md +++ b/command-help-passchg.md @@ -22,6 +22,7 @@ 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) @@ -51,5 +52,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-PASSCHG(1) + MMGEN v13.3.dev55 May 2023 MMGEN-PASSCHG(1) ``` diff --git a/command-help-passgen.md b/command-help-passgen.md index ecf9569..92138cd 100644 --- a/command-help-passgen.md +++ b/command-help-passgen.md @@ -100,5 +100,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-PASSGEN(1) + MMGEN v13.3.dev55 May 2023 MMGEN-PASSGEN(1) ``` diff --git a/command-help-regtest.md b/command-help-regtest.md index 1b6105b..8b1072d 100644 --- a/command-help-regtest.md +++ b/command-help-regtest.md @@ -24,5 +24,5 @@ wallet_cli - execute a wallet RPC call with supplied arguments (wallet is first argument) - MMGEN v13.2.0 August 2022 MMGEN-REGTEST(1) + MMGEN v13.3.dev55 May 2023 MMGEN-REGTEST(1) ``` diff --git a/command-help-seedjoin.md b/command-help-seedjoin.md index 27faa5f..fe2c525 100644 --- a/command-help-seedjoin.md +++ b/command-help-seedjoin.md @@ -61,5 +61,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-SEEDJOIN(1) + MMGEN v13.3.dev55 May 2023 MMGEN-SEEDJOIN(1) ``` diff --git a/command-help-seedsplit.md b/command-help-seedsplit.md index f5d27b7..590bfc7 100644 --- a/command-help-seedsplit.md +++ b/command-help-seedsplit.md @@ -23,6 +23,7 @@ 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) @@ -142,5 +143,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-SEEDSPLIT(1) + MMGEN v13.3.dev55 May 2023 MMGEN-SEEDSPLIT(1) ``` diff --git a/command-help-subwalletgen.md b/command-help-subwalletgen.md index 09af473..b2e0721 100644 --- a/command-help-subwalletgen.md +++ b/command-help-subwalletgen.md @@ -25,6 +25,7 @@ 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) @@ -95,5 +96,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-SUBWALLETGEN(1) + MMGEN v13.3.dev55 May 2023 MMGEN-SUBWALLETGEN(1) ``` diff --git a/command-help-tool(detail).md b/command-help-tool(detail).md index 068197d..0156821 100644 --- a/command-help-tool(detail).md +++ b/command-help-tool(detail).md @@ -725,6 +725,18 @@ 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 @@ -1209,5 +1221,5 @@ Optional KEYWORD ARGS (type and default value shown in square brackets): ``` ```text -MMGEN v13.3.dev24 December 2022 MMGEN-TOOL(DETAIL)(1) +MMGEN v13.3.dev55 May 2023 MMGEN-TOOL(DETAIL)(1) ``` diff --git a/command-help-tool(usage).md b/command-help-tool(usage).md index 4a07609..481b292 100644 --- a/command-help-tool(usage).md +++ b/command-help-tool(usage).md @@ -103,10 +103,11 @@ GENERAL USAGE INFORMATION FOR MMGEN-TOOL COMMANDS Utilities for viewing/checking MMGen address and transaction files: - addrfile_chksum mmgen_addrfile [str] - keyaddrfile_chksum mmgen_keyaddrfile [str] - passwdfile_chksum mmgen_passwdfile [str] - txview mmgen_tx_file(s) [str] pager [bool=False] terse [bool=False] sort [str='addr'] filesort [str='mtime'] + 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: @@ -185,5 +186,5 @@ EXAMPLES: Same as above, but supply input via STDIN: $ echo "deadbeefcafe" | mmgen-tool hexreverse - - MMGEN v13.3.dev24 December 2022 MMGEN-TOOL(USAGE)(1) + MMGEN v13.3.dev55 May 2023 MMGEN-TOOL(USAGE)(1) ``` diff --git a/command-help-tool.md b/command-help-tool.md index cced73c..c5653ab 100644 --- a/command-help-tool.md +++ b/command-help-tool.md @@ -129,11 +129,12 @@ 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 - passwdfile_chksum - compute checksum for MMGen password file - txview - display specified raw or signed MMGen transaction - files in human-readable form + 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: @@ -196,5 +197,5 @@ Type ‘mmgen-tool help ’ for help on a particular command - MMGEN v13.3.dev23 November 2022 MMGEN-TOOL(1) + MMGEN v13.3.dev55 May 2023 MMGEN-TOOL(1) ``` diff --git a/command-help-txbump.md b/command-help-txbump.md index 64bed0f..8106b13 100644 --- a/command-help-txbump.md +++ b/command-help-txbump.md @@ -87,5 +87,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.3.dev23 November 2022 MMGEN-TXBUMP(1) + MMGEN v13.3.dev55 May 2023 MMGEN-TXBUMP(1) ``` diff --git a/command-help-txcreate.md b/command-help-txcreate.md index 9b3c27b..0520cc5 100644 --- a/command-help-txcreate.md +++ b/command-help-txcreate.md @@ -22,7 +22,8 @@ -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, --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 @@ -97,5 +98,5 @@ $ mmgen-txcreate S - MMGEN v13.3.dev23 November 2022 MMGEN-TXCREATE(1) + MMGEN v13.3.dev55 May 2023 MMGEN-TXCREATE(1) ``` diff --git a/command-help-txdo.md b/command-help-txdo.md index 411c1b2..85b55ae 100644 --- a/command-help-txdo.md +++ b/command-help-txdo.md @@ -33,7 +33,8 @@ -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, --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- @@ -163,5 +164,5 @@ $ mmgen-txdo S - MMGEN v13.3.dev23 November 2022 MMGEN-TXDO(1) + MMGEN v13.3.dev55 May 2023 MMGEN-TXDO(1) ``` diff --git a/command-help-txsend.md b/command-help-txsend.md index 2fd6044..5a88561 100644 --- a/command-help-txsend.md +++ b/command-help-txsend.md @@ -9,5 +9,5 @@ -s, --status Get status of a sent transaction -y, --yes Answer 'yes' to prompts, suppress non-essential output - MMGEN v13.2.0 August 2022 MMGEN-TXSEND(1) + MMGEN v13.3.dev55 May 2023 MMGEN-TXSEND(1) ``` diff --git a/command-help-txsign.md b/command-help-txsign.md index 8e8084e..2a12eea 100644 --- a/command-help-txsign.md +++ b/command-help-txsign.md @@ -79,5 +79,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-TXSIGN(1) + MMGEN v13.3.dev55 May 2023 MMGEN-TXSIGN(1) ``` diff --git a/command-help-walletchk.md b/command-help-walletchk.md index 63e89d9..08694e3 100644 --- a/command-help-walletchk.md +++ b/command-help-walletchk.md @@ -50,5 +50,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-WALLETCHK(1) + MMGEN v13.3.dev55 May 2023 MMGEN-WALLETCHK(1) ``` diff --git a/command-help-walletconv.md b/command-help-walletconv.md index a8790eb..30abebc 100644 --- a/command-help-walletconv.md +++ b/command-help-walletconv.md @@ -25,6 +25,7 @@ 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) @@ -60,5 +61,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-WALLETCONV(1) + MMGEN v13.3.dev55 May 2023 MMGEN-WALLETCONV(1) ``` diff --git a/command-help-walletgen.md b/command-help-walletgen.md index bf3190a..273fb1a 100644 --- a/command-help-walletgen.md +++ b/command-help-walletgen.md @@ -53,5 +53,5 @@ MMGenWallet .mmdat wallet,w PlainHexSeedFile .hex hex,rawhex,plainhex - MMGEN v13.2.0 August 2022 MMGEN-WALLETGEN(1) + MMGEN v13.3.dev55 May 2023 MMGEN-WALLETGEN(1) ``` diff --git a/command-help-xmrwallet.md b/command-help-xmrwallet.md index 613b993..8c424e8 100644 --- a/command-help-xmrwallet.md +++ b/command-help-xmrwallet.md @@ -1,18 +1,28 @@ ```text - MMGEN-XMRWALLET: Perform various Monero wallet operations for addresses - in an MMGen XMR key-address file - USAGE: mmgen-xmrwallet [opts] create [wallets] - mmgen-xmrwallet [opts] sync [wallets] - mmgen-xmrwallet [opts] list [wallets] - mmgen-xmrwallet [opts] new NEW_ADDRESS_SPEC - mmgen-xmrwallet [opts] transfer TRANSFER_SPEC - mmgen-xmrwallet [opts] sweep SWEEP_SPEC + 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 | 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 [xmr_keyaddrfile] SWEEP_SPEC + mmgen-xmrwallet [opts] submit [TX_file] mmgen-xmrwallet [opts] relay - mmgen-xmrwallet [opts] txview ... + mmgen-xmrwallet [opts] resubmit + mmgen-xmrwallet [opts] txview | txlist [TX_file] ... + mmgen-xmrwallet [opts] export-outputs [wallets] + mmgen-xmrwallet [opts] import-key-images [wallets] OPTIONS: -h, --help Print this help message --longhelp Print help message for long options (common 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. + -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 @@ -22,20 +32,28 @@ -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') - -r, --restore-height H Scan from height 'H' when creating wallets + -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 - -H, --wallet-rpc-host host Wallet RPC hostname (default: 'localhost') - -U, --wallet-rpc-user user Wallet RPC username (default: 'monero') - -P, --wallet-rpc-password pass Wallet RPC password (default: '') + -U, --wallet-rpc-user user Wallet RPC username (currently: 'monero') + -P, --wallet-rpc-password pass Wallet RPC password (currently: [scrubbed]) - All operations except for ‘relay’ require a running Monero daemon. Unless - --daemon is specified, the monerod is assumed to be listening on localhost at - the default RPC port. + 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_HOST:PROXY_PORT, if specified, may @@ -47,29 +65,43 @@ SUPPORTED OPERATIONS - create - create wallet for all or specified addresses in key-address file - sync - sync wallet for all or specified addresses in key-address file - list - same as 'sync', but also list detailed address info for accounts + create - create wallets for all or specified addresses in key-address file + sync - sync wallets for all or specified addresses in key-address file + list - same as ‘sync’, 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 account in another wallet - relay - relay a transaction from a transaction file created using 'sweep' - or 'transfer' with the --no-relay option - txview - view a transaction file or files created using 'sweep' or - 'transfer' with the --no-relay option + 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) + 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 later import + into their corresponding offline wallets + import-key-images - import key images signed by offline wallets into their + corresponding watch-only wallets - 'CREATE', 'SYNC' AND 'LIST' OPERATION NOTES + ‘LABEL’ OPERATION NOTES - These operations take an optional `wallets` argument: one or more address - indexes (expressed as a comma-separated list, hyphenated range, or both) - in the specified key-address file, each corresponding to a Monero wallet - to be created, synced or listed. If omitted, all wallets are operated upon. + 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 + ‘NEW’ OPERATION NOTES This operation takes a NEW_ADDRESS_SPEC arg with the following format: @@ -81,7 +113,7 @@ appended to the spec following a comma. - 'TRANSFER' OPERATION NOTES + ‘TRANSFER’ OPERATION NOTES The transfer operation takes a TRANSFER_SPEC arg with the following format: @@ -91,7 +123,7 @@ and AMOUNT the destination Monero address and XMR amount, respectively. - 'SWEEP' OPERATION NOTES + ‘SWEEP’ OPERATION NOTES The sweep operation takes a SWEEP_SPEC arg with the following format: @@ -112,24 +144,49 @@ in an account. - 'RELAY' OPERATION NOTES + ‘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. - WARNING - To avoid exposing your private keys on a network-connected machine, you’re - strongly advised to create all transactions offline using the --no-relay - option. For this, a monerod with a fully synced blockchain must be running - on the offline machine. The resulting transaction files are then sent using - the 'relay' operation. + ‘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 @@ -168,5 +225,244 @@ to pager: $ mmgen-xmrwallet --pager txview *XMR*.sigtx - MMGEN v13.3.dev16 November 2022 MMGEN-XMRWALLET(1) + + 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 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. + + Export outputs from a wallet as follows (note that the --rescan-blockchain + option is required only after a ‘resubmit’ – otherwise it should be omitted): + + $ mmgen-xmrwallet --autosign --rescan-blockchain export-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 watch-only counterparts. + + Then insert the removable device on the offline machine to import the outputs + into the corresponding signing wallet(s) (and optionally redo any failed + transaction signing operation). The signing wallet(s) will also create + signed key images. + + Following a ‘resubmit’, you must then import the signed key images into your + online wallet as follows: + + $ mmgen-xmrwallet --autosign import-key-images + + + 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 + + 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 v13.3.dev55 May 2023 MMGEN-XMRWALLET(1) ```