mmgen/mmgen-wallet
1
0
Fork 0
Code Issues Pull requests Projects Releases 28 Packages Wiki Activity

doc/wiki: update mmgen-autosign command help

Browse source
This commit is contained in:
The MMGen Project 2026-05-07 17:52:59 +00:00
commit b3bdc76eb7
Signed by: mmgen
GPG key ID: 3F8B1861E32B7DA2
2 changed files with 181 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

224
doc/wiki/cmds/command-help-autosign.md
View file

@ -1,6 +1,8 @@
```text
MMGEN-AUTOSIGN: Auto-sign MMGen transactions, message files and XMR wallet output files
USAGE: mmgen-autosign [opts] [operation]
USAGE: mmgen-autosign [opts] [operation]
OPTIONS:
-h, --help Print this help message
--longhelp Print help message for long (global) options
@ -12,7 +14,8 @@
the file in volatile memory for use during the signing
session, thus permitting the deletion of the original
file for increased security.
-l, --seed-len N Specify wallet seed length of ‘N’ bits (for setup only)
-l, --seed-len N Specify wallet seed length of ‘N’ bits (for setup with
mnemonic seed phrase only)
-L, --led Use status LED to signal standby, busy and error
-m, --mountpoint M Specify an alternate mountpoint 'M'
(default: '/mnt/mmgen_autosign')
@ -35,10 +38,11 @@
(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
-x, --xmrwallets L Range or list of wallet numbers to be used for XMR
autosigning (see XMR SIGNING SESSION SETUP below)
OPERATIONS
OPERATIONS
clean - clean the removable device of unneeded files, removing only non-
essential data
@ -63,42 +67,107 @@
signing transactions or stealing the user’s seed impossible.
The operation is intended as a ‘kill switch’ and thus performed
without prompting
list_led - list boards with tested LED signaling support
test_led - test the current board for LED signaling support
USAGE NOTES
DESCRIPTION
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.
This program is intended to be run on an offline signing computer, preferably
air-gapped and with no or disabled RF devices (e.g. wi-fi and bluetooth).
Memory, storage and CPU requirements for signing operations are modest, so an
old laptop is suitable for the job, or better yet, a Raspberry Pi or Pi clone
from among the list of supported devices (see LED SIGNALING SUPPORT below).
OS support is currently limited to Linux and macOS.
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.
Before using the program, a removable device (typically a USB flash drive)
must first be prepared and the current signing session set up, both as
described below.
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.
If run with no arguments, the program mounts the removable device, signs any
unsigned MMGen signables (transactions, message files, and/or XMR wallet
output files) on the device, unmounts the device and exits.
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.
If invoked with ‘wait’, the program waits in a loop: mounting, signing and
unmounting every time the removable device is inserted. Wait mode permits
“hands-free” operation, i.e. repeated signing of signables with no keyboard
input, by simply inserting the removable device and then removing it when the
program indicates that signing is complete (see LED SIGNALING SUPPORT below).
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:
Signing is performed with a temporary session wallet written in volatile
memory in the directory ‘/dev/shm/autosign’ (as currently configured). The
wallet is encrypted with a random password saved in the file ‘autosign.key’
on the removable device.
By default, the session wallet is created from the user’s default MMGen
wallet, if it exists. However, the user may optionally generate the session
wallet by interactively entering a seed phrase during session setup. Thus it
is possible to perform signing and other wallet operations with no seed data
ever written to disk, even in encrypted form (“wallet-less” operation).
Depending on the coin, signing is performed either internally by MMGen Wallet
or using an external backend, according to the table below. Thus you must
install the corresponding backend executable, if any, for each coin you wish
to transact and start it with the listed command, if any, at the beginning of
each signing session. It’s recommended to install the executables into
‘/usr/local/bin’.
Coin Backend Executable Command
---- ------- ---------- -------
BTC Bitcoin Core bitcoind bitcoind --listen=0 --daemon
LTC Litecoin Core litecoind litecoind --listen=0 --daemon
BCH Bitcoin Cash Node bitcoind-bchn* bitcoind-bchn --daemon --listen=0 --rpcport=8432 --datadir=$HOME/.bitcoin-bchn
XMR Monero CLI Wallet monero-wallet-rpc -
ETH,ETC,ERC20 none - -
RUNE none - -
* Executable must be renamed from the default ‘bitcoind’
LED SIGNALING SUPPORT
On supported platforms (selected Orange Pi, Rock Pi, Banana Pi, Nano Pi and
Raspberry Pi boards), a flashing LED indicates whether signing is in progress
or the program is in standby mode, i.e. ready for device insertion or removal.
In the absence of LED support, the user must observe the signing progress
on-screen and wait for the “safe to extract” message to appear.
The operation ‘test_led’ tests the current installation for LED support, while
‘list_led’ displays a list of supported board/OS combinations. Note that this
list is not exhaustive: signaling may work with other boards, especially those
produced by the listed manufacturers. If ‘test_led’ reports that your board is
not supported, please submit an issue to the mmgen-wallet repository on Github
or via e-mail, including the board model, OS version and output of the
following shell command:
ls -RH /sys/class/leds/{*status*,*led*}
PREPARING THE REMOVABLE DEVICE
Create a partition on the removable device with a filesystem labeled ‘MMGEN_TX’
and a user-writable root directory. For interoperability between different
operating systems, it’s recommended to use the exFAT filesystem.
On both the offline and online machines, create the mountpoint ‘/mnt/mmgen_autosign’
(as currently configured) and, for Linux, the following entry in ‘/etc/fstab’:
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.
If your Linux distribution mounts volumes automatically, it’s advisable to
disable that functionality.
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.
SETTING UP A SIGNING SESSION
Invoke ‘mmgen-autosign setup’ with the removable device inserted. This will
create the temporary session wallet from the user’s default MMGen wallet (if
it exists) or, optionally, a seed phrase. In addition, the session wallet
password is created and written to the removable device. Additional options
may be required. See OPTIONS above and EXAMPLES below.
ALTERNATIVE (MANUAL) SESSION SETUP
Alternatively, the password and temporary wallet may be created separately by
first invoking ‘mmgen-autosign gen_key’ and then creating and encrypting the
@ -108,30 +177,97 @@
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).
file path to the end of the command line. Multiple session wallets may
be created in this way (note, however, that for XMR operations only one
session wallet is supported).
Autosigning is currently supported on Linux and macOS only.
XMR SIGNING SESSION SETUP
To set up an XMR signing session, run ‘setup’ with the --xmrwallets option,
supplying an integer, range, or comma-separated list of integers as the
option’s parameter. Each integer in the list or range represents a wallet
number. For each wallet number, the program generates a Monero address and
creates a temporary session Monero signing wallet in volatile memory under
‘/dev/shm/autosign’ with this number and base address. In addition, data is
written to the removable device which will allow the online installation to
create a watch-only wallet matching the session signing wallet when the user
runs ‘mmgen-addrimport --coin=xmr’ on the online machine with the removable
device inserted (type ‘mmgen-addrimport --coin=xmr --help’ for details).
The use of multiple Monero wallets can help protect against certain known
deanonymization attacks such as the Janus attack. However, since wallet
creation and online syncing of multiple wallets, as well as switching among
them during the signing process, are all time-consuming, it’s recommended to
limit the number of wallets created. First-time users are thus advised to
begin with ‘--xmrwallets=1’. More wallets may be added in later signing
sessions if necessary. See EXAMPLES below.
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.
By placing the session 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 or steal the user’s seed. 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,
it’s good practice to lock the signing machine’s screen when unattended.
For Monero, passwords for the watch-only wallets are also stored on the
removable device, meaning that a local attacker must gain access to the latter
not only to sign transactions but also to observe the user’s XMR balances and
transaction history (a remote attacker could possibly observe these, but
extracting the removable device when it’s not in use makes such an attack
less feasible).
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.
volatile memory where the session wallets reside and prevent a signing or
seed-stealing attack, even if the attacker has gained control of the removable
device.
Always remember to power off the signing machine when your signing session
is over.
MMGEN-WALLET 16.0.0 September 2025 MMGEN-AUTOSIGN(1)
After each signing operation, this program displays a summary showing each
transaction’s non-wallet destination address(es) and amount(s). As an extra
security measure, it’s a good idea to compare these with the address(es) and
amount(s) displayed by your online installation. A discrepancy would indicate
that your online setup has been compromised.
EXAMPLES
Set up a signing session:
$ mmgen-autosign setup
Start the Bitcoin Core daemon:
$ bitcoind --daemon --listen=0
Start the signing loop (BTC-only signing):
$ mmgen-autosign wait # exit loop with Ctrl-C
Set up a signing session with one XMR wallet:
$ mmgen-autosign --xmrwallets=1 setup
In a later signing session, add two more XMR wallets:
$ mmgen-autosign --xmrwallets=1-3 setup
Start the Litecoin Core daemon:
$ litecoind --daemon --listen=0
Start the signing loop (BTC, LTC and XMR signing):
$ mmgen-autosign --coins=btc,ltc,xmr wait
Set up a signing session with 3 XMR wallets, prompting for a 12-word BIP39 seed phrase:
$ mmgen-autosign --xmrwallets=2,5,8 --mnemonic-fmt=bip39 --seed-len=128 setup
Start the signing loop in stealth LED mode with full TX summary (LTC, RUNE and XMR signing):
$ mmgen-autosign --coins=ltc,rune,xmr --stealth-led --full-summary wait
Generate a list of 10 LTC Bech32 addresses using your session wallet:
$ mount /mnt/mmgen_autosign
$ mmgen-addrgen -P /mnt/mmgen_autosign/autosign.key --coin=ltc --type=B /dev/shm/autosign/*.mmdat 1-10
MMGEN-WALLET 16.1.dev38 May 2026 MMGEN-AUTOSIGN(1)
```

2
mmgen/data/version
View file

@ -1 +1 @@
16.1.dev37
16.1.dev38