From bb92ad40093e2b01ef2f693d0e4771c69f4cbd1d Mon Sep 17 00:00:00 2001 From: The MMGen Project Date: Sun, 21 May 2023 11:34:16 +0000 Subject: [PATCH] update documentation from wiki --- .../Install-MMGen-on-Microsoft-Windows.md | 163 +++++++++--------- .../Altcoin-and-Forkcoin-Support.md | 55 +++--- .../using-mmgen/Getting-Started-with-MMGen.md | 19 +- doc/wiki/using-mmgen/Test-Suite.md | 5 + 4 files changed, 125 insertions(+), 117 deletions(-) diff --git a/doc/wiki/install-mswin/Install-MMGen-on-Microsoft-Windows.md b/doc/wiki/install-mswin/Install-MMGen-on-Microsoft-Windows.md index 0c2b6cae..8cc995b2 100644 --- a/doc/wiki/install-mswin/Install-MMGen-on-Microsoft-Windows.md +++ b/doc/wiki/install-mswin/Install-MMGen-on-Microsoft-Windows.md @@ -4,20 +4,19 @@ #### [Install MSYS2 and MMGen](#a_m) * [1. Install MSYS2](#a_ms) -* [2. Set up PowerShell as your MSYS2 terminal](#a_ps) -* [3. Upgrade MSYS2](#a_ug) -* [Online users](#a_ug1) -* [Offline install](#a_ug2) -* [4. Install MSYS2 MMGen dependencies](#a_md) -* [Offline install](#a_md1) -* [5. Set up your environment](#a_ev) -* [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](#a_mm) -* [10. Install Python Ethereum dependencies (Ethereum users only)](#a_pe) -* [11. Install and launch your coin daemons](#a_cd) -* [12. You’re done!](#a_do) +* [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) @@ -26,17 +25,13 @@ ## Introduction MMGen is supported on Microsoft Windows via [MSYS2][mh], which provides a -Unix-like command-line environment within Windows. Windows 7 and later versions -are supported. +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]. -*Note: an [older version][ov] of MMGen can be run under MinGW-64 and MSYS, but -its use is deprecated. Installation instructions for MMGen under MinGW-64 and -MSYS are archived [here][di] for historical interest only.* - 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 @@ -61,20 +56,10 @@ 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. - -### 2. Set up PowerShell as your MSYS2 terminal - -MMGen is incompatible with the terminal provided by the MSYS2 project. However, -it works just fine with Windows’ native PowerShell. - -Drag or copy a PowerShell icon to the desktop, rename it to “MSYS2”, then right -click the icon and select Properties. After the existing path in the Target -text window, append a space followed by the text `C:\\msys64\usr\bin\bash.exe ---login` - -Save your changes and double click the icon to launch your MSYS2-enabled -PowerShell. From now on, all your work will be done in this terminal. +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: @@ -96,9 +81,9 @@ $ ls 'C:\\msys64\etc' # the path as seen by Windows $ pacman -Syu ``` -> Exit and restart the 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. +> 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: @@ -158,7 +143,7 @@ $ ls /var/lib/pacman/sync $ pacman -Sup > urls.txt ``` -> This command may cause your MSYS terminal window to close. If so, just +> 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 @@ -207,24 +192,25 @@ specifically required by MMGen. Install the MMGen requirements and their dependencies: ```text -$ pacman -S tar git vim autoconf automake-wrapper autogen libtool cygrunsrv \ - mingw-w64-x86_64-python-build \ - mingw-w64-x86_64-python-wheel \ - mingw-w64-x86_64-python-pip \ - mingw-w64-x86_64-libltdl \ - mingw-w64-x86_64-gcc \ - mingw-w64-x86_64-make \ - mingw-w64-x86_64-pcre \ - mingw-w64-x86_64-libsodium \ - mingw-w64-x86_64-python-cryptography \ - mingw-w64-x86_64-python-six \ - mingw-w64-x86_64-python-pexpect \ - mingw-w64-x86_64-python-gmpy2 \ - mingw-w64-x86_64-python-pynacl \ - mingw-w64-x86_64-python-pysocks \ - mingw-w64-x86_64-python-requests \ - mingw-w64-x86_64-python-aiohttp \ - mingw-w64-x86_64-python-pyreadline3 +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 ``` ### 5. Set up your environment @@ -242,12 +228,13 @@ Open your shell’s runtime configuration file in a text editor: $ nano ~/.bashrc ``` -Add the following two lines to the end of the file (if this is a Bitcoin-only -installation, you may omit the Litecoin and Bitcoin Cash Node components of the -path): +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 -export PATH="$HOMEPATH/.local/bin:/mingw64/bin:$PATH:/c/Program Files/Bitcoin/daemon:/c/Program Files/Litecoin/daemon:/c/Program Files/Bitcoin-Cash-Node/daemon" +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 ``` @@ -259,13 +246,13 @@ environment. On your online machine: ```text -$ pip3 download ecdsa +$ python3 -m pip download ecdsa ``` Copy the downloaded file to your offline machine and install: ```text -$ pip3 install --user ecdsa-*.whl +$ python3 -m pip install --user ecdsa-*.whl ``` ### 7. Install the standalone scrypt package (required for strong password hashing) @@ -283,11 +270,24 @@ $ git clone https://github.com/holgern/py-scrypt.git Copy the cloned repo to your offline machine. -On both online and offline machines, enter the repo root and install: +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: + +```text +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 setup.py install --user +$ python3 -m build --no-isolation +$ python3 -m pip install --user dist/*.whl ``` ### 8. Clone and copy the secp256k1 library (offline install only) @@ -302,9 +302,9 @@ On your offline machine, create a magic location and copy the cloned secp256k1 directory into it: ```text -$ mkdir -p ~/.cache/mmgen +$ mkdir -p ~/.cache/mmgen # the magic location $ cp -a /path/to/secp256k1/repo/secp256k1 ~/.cache/mmgen -$ ls ~/.cache/mmgen/secp256k1/autogen.sh # check that the location is correct +$ ls ~/.cache/mmgen/secp256k1/autogen.sh # check that files were correctly copied ``` ### 9. Install MMGen @@ -326,7 +326,7 @@ Enter the repo directory, build and install: $ cd mmgen $ git checkout stable_msys2 # See 'Note' below $ python3 -m build --no-isolation -$ python3 -m pip install --user --upgrade dist/*.whl +$ python3 -m pip install --user dist/*.whl ``` **Note:** if you want to use features that have appeared since the latest @@ -349,20 +349,20 @@ If you’ll be using MMGen with Ethereum, then you must install a few dependencies. From the MMGen repository root, type the following: ```text -$ pip3 install --no-deps --user -r eth-requirements.txt +$ python3 -m pip install --no-deps --user -r eth-requirements.txt ``` For an offline install, do this instead: ```text -$ pip3 download --no-deps -r eth-requirements.txt +$ 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 -$ pip3 install --no-deps --user *.whl +$ python3 -m pip install --no-deps --user *.whl ``` ### 11. Install and launch your coin daemons @@ -379,17 +379,16 @@ 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, OpenEthereum -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`, `openethereum.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: +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 might be painfully slow. +syncing the blockchain could be painfully slow. ### 12. You’re done! @@ -433,10 +432,11 @@ computer and issue the following commands: $ git checkout master $ git pull $ git checkout stable_msys2 # See 'Note' to step 9 -$ rm -rf dist build -$ rm -r /mingw64/lib/python*/site-packages/{mmgen,MMGen}* +$ rm -rf dist build *egg-info +$ rm -rf /mingw64/lib/python*/site-packages/{mmgen,MMGen}* $ python3 -m build --no-isolation -$ python3 -m pip install --upgrade dist/*.whl +$ python3 -m pip install --user dist/*.whl +$ rm -rf dist build *egg-info ``` To update your offline installation, copy the updated repository (after `git @@ -448,7 +448,6 @@ continue from the `git checkout stable_msys2` step. [mw]: https://github.com/msys2/msys2/wiki [ov]: ../releases/tag/v0.9.8 [sd]: https://download.sysinternals.com/files/SDelete.zip -[og]: https://github.com/openethereum/openethereum/releases [mr]: ../releases [di]: Deprecated-MSWin-Installation [ib]: Install-Bitcoind diff --git a/doc/wiki/using-mmgen/Altcoin-and-Forkcoin-Support.md b/doc/wiki/using-mmgen/Altcoin-and-Forkcoin-Support.md index ef22a229..db7023a3 100644 --- a/doc/wiki/using-mmgen/Altcoin-and-Forkcoin-Support.md +++ b/doc/wiki/using-mmgen/Altcoin-and-Forkcoin-Support.md @@ -4,7 +4,7 @@ #### [Ethereum (ETH), Ethereum Classic (ETC) and ERC20 Tokens](#a_eth) * [Install the Ethereum dependencies](#a_ed) -* [Install and run Geth, Parity or OpenEthereum](#a_oe) +* [Install and run Geth or Parity](#a_geth) * [Transacting and other basic operations](#a_tx) * [Creating and deploying ERC20 tokens](#a_dt) @@ -37,16 +37,15 @@ From the MMGen repository root, type: $ python3 -m pip install --no-deps --user -r eth-requirements.txt ``` -#### Install and run Geth, Parity or OpenEthereum +#### Install and run Geth or Parity -MMGen can use either Go-Ethereum (Geth) or OpenEthereum to communicate with -the Ethereum network. For information on installing Geth or OE on your -system, visit the the Geth [Github repo][ge], or the OpenEthereum [wiki][ow] -or [Github repo][og]. On Arch Linux systems, Go-Ethereum and OpenEthereum are -packages and may be installed with `pacman`. +MMGen uses Go-Ethereum (Geth) to communicate with the Ethereum network. For +information on installing Geth on your system, visit the the Geth [Github +repo][ge]. On Arch Linux systems, Go-Ethereum is a package and may be installed +with `pacman`. -Note that Ethereum daemons are not used for transaction signing, so you -needn’t install them on your offline machine. +Note that the Ethereum daemon is not used for transaction signing, so you +needn’t install it on your offline machine. For Geth, the following command-line options are required: @@ -54,19 +53,18 @@ For Geth, the following command-line options are required: --http --http.api=eth,web3,txpool --http.port=8745 ``` -Geth and OE have dropped support for Ethereum Classic, but MMGen supports -transacting ETC via the legacy [Parity][pd] daemon. Invoke Parity with -`--chain=classic --jsonrpc-port=8645`. Other command-line options are the -same as for OpenEthereum. +Geth has dropped support for Ethereum Classic, but MMGen supports transacting +ETC via the legacy [Parity][pd] daemon. Invoke Parity with `--chain=classic +--jsonrpc-port=8645`. -If you’re running OE or Parity on a different machine from MMGen, add the -following options to the daemon command line: +If you’re running Parity on a different machine from MMGen, add the following +options to the command line: ```text --jsonrpc-hosts=all --jsonrpc-interface= ``` -To run OE or Parity offline, use `--mode=offline`, otherwise `--mode=active`. +To run Parity offline, use `--mode=offline`, otherwise `--mode=active`. MMGen can also be used with Parity’s light client mode, which queries other nodes on the network for blockchain data. Add the `--light` option to the @@ -74,7 +72,7 @@ Parity command line and read the applicable note in the [Transacting](#a_tx) section below. You may require other options as well. Invoke your daemon with the `--help` -switch for more complete information. +option for more complete information. #### Transacting and other basic operations @@ -88,7 +86,7 @@ Basic operations with ETH, ETC and ERC20 tokens work as described in the * Addresses and other hexadecimal values are given without the leading `0x`. * Fees are expressed in Gas price, e.g. `12G` for 12 Gwei or `1000M` for 1000 Mwei. This works at both the command line and interactive prompt. -* When using OpenEthereum in light client mode, the `--cached-balances` option +* When using Parity in light client mode, the `--cached-balances` option will greatly speed up operations of the `mmgen-txcreate`, `mmgen-txdo` and `mmgen-tool twview` commands by reducing network queries to a minimum. If your account balances have changed, they may be refreshed interactively within @@ -231,14 +229,14 @@ commands. It’s that simple! ### Monero (XMR) MMGen’s Monero support includes automated wallet creation/syncing and -transaction creation/relaying via the `mmgen-xmrwallet` command. Make sure -that [Monerod][M] is installed and running and that `monero-wallet-rpc` is -located in your executable path. +transacting via the [`mmgen-xmrwallet`][mx] command. Make sure that +[Monerod][M] is installed and running and that `monero-wallet-rpc` is located +in your executable path. -*NOTE: by storing the Monero blockchain on a removable drive and installing -Monerod on both your online and offline machines, it’s possible to perform -wallet and transaction creation operations offline and thus avoid exposing -private data on your online machine.* +*The following instructions are applicable for a hot wallet setup. To learn +how to cold sign transactions using MMGen’s autosign feature, first +familiarize yourself with the basic concepts here and then consult the OFFLINE +AUTOSIGNING tutorial on the [`mmgen-xmrwallet`][mx] help screen.* To generate five Monero key/address pairs from your default wallet, invoke the following, making sure to answer ‘y’ at the Encrypt prompt: @@ -277,8 +275,8 @@ $ mmgen-xmrwallet sync *XMR*.akeys.mmenc No user interaction is required here either, which is very helpful when you have multiple wallets requiring long sync times. -`mmgen-xmrwallet` supports transacting via the `sweep` and `transfer` -subcommands. Type `mmgen-xmrwallet --help` for details. +To learn how to transact using your wallets, continue on to the +[`mmgen-xmrwallet`][mx] help screen. ### Key/address generation for Zcash (ZEC) @@ -349,8 +347,6 @@ received only minimal testing, or no testing at all. At startup you’ll be informed of the level of your selected coin’s support reliability as deemed by the MMGen Project. -[ow]: https://openethereum.github.io/wiki -[og]: https://github.com/openethereum/openethereum/releases [pd]: https://github.com/openethereum/parity-ethereum/releases/tag/v2.7.2 [y]: https://github.com/ethereum/pyethereum [P]: https://pypi.org/project/pip @@ -362,3 +358,4 @@ the MMGen Project. [bi]: Install-Bitcoind#a_d [p8]: Install-Bitcoind#a_r [ge]: https://github.com/ethereum/go-ethereum +[mx]: command-help-xmrwallet diff --git a/doc/wiki/using-mmgen/Getting-Started-with-MMGen.md b/doc/wiki/using-mmgen/Getting-Started-with-MMGen.md index 5998840c..5545bbda 100644 --- a/doc/wiki/using-mmgen/Getting-Started-with-MMGen.md +++ b/doc/wiki/using-mmgen/Getting-Started-with-MMGen.md @@ -6,8 +6,9 @@ * [Configuration file](#a_cf) * [Bob and Alice regtest mode](#a_ts) -#### [Basic Operations](#a_bo) -* [Generate an MMGen wallet](#a_gw) +#### [Generating an MMGen Wallet](#a_gw) + +#### [Transacting](#a_tr) * [Generate addresses](#a_ga) * [Import addresses](#a_ia) * [Create a transaction](#a_ct) @@ -109,9 +110,7 @@ it an ideal way to learn to use the MMGen wallet without risking real coins. You may wish to pause here and perform the steps in the tutorial [MMGen Quick Start with Regtest Mode][04] before continuing on. -### Basic Operations - -#### Generate an MMGen wallet (offline computer) +### Generating an MMGen Wallet *NOTE: MMGen supports a “default wallet” feature. After generating your wallet, you’ll be prompted to make it your default. If you answer ‘y’, the wallet will @@ -126,7 +125,7 @@ as it frees you from having to type your wallet filename on the command line.* If you haven’t, then you must include the path to a wallet file or other seed source in all commands where a seed source is required.* -On your offline computer, generate an MMGen wallet: +On your **offline** computer, generate an MMGen wallet: ```text $ mmgen-walletgen @@ -162,6 +161,12 @@ your seed phrase to be surprisingly easy. And the peace of mind that comes with knowing that your coins are recoverable **even if you lose all your physical backups** can’t be overestimated. +### Transacting + +*The following transacting information is applicable to BTC, BCH, LTC, ETH and +ETC. For transacting with Monero, consult [Altcoin-and-Forkcoin-Support][ax] +and the [`mmgen-xmrwallet`][mx] help screen.* + #### Generate addresses (offline computer) Now generate ten Segwit-P2SH addresses with your just-created wallet: @@ -1130,4 +1135,6 @@ $ python3 -m pip install --user --upgrade dist/*.whl [07]: command-help-autosign [08]: Install-Bitcoind [09]: Altcoin-and-Forkcoin-Support +[ax]: Altcoin-and-Forkcoin-Support#a_xmr [cp]: ../commits/master +[mx]: command-help-xmrwallet diff --git a/doc/wiki/using-mmgen/Test-Suite.md b/doc/wiki/using-mmgen/Test-Suite.md index 772e6ba7..45aa6438 100644 --- a/doc/wiki/using-mmgen/Test-Suite.md +++ b/doc/wiki/using-mmgen/Test-Suite.md @@ -55,7 +55,12 @@ $ export CORE_REPO_ROOT=/path/to/bitcoin/core/repo Install Pycoin: ```text +# online install: $ python3 -m pip install --user pycoin + +# offline install: +$ python3 -m pip download pycoin # online +$ python3 -m pip install --user --no-build-isolation pycoin-*.tar.gz # offline ``` CD to the MMGen repository root and build without installing: