From a3a06331606e917a467a627b7eeba490a8f3a4d1 Mon Sep 17 00:00:00 2001 From: The MMGen Project Date: Fri, 21 Feb 2020 13:14:35 +0000 Subject: [PATCH] new file: Test-Suite.md new file: Tool-API.md --- Test-Suite.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++ Tool-API.md | 73 +++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+) create mode 100644 Test-Suite.md create mode 100644 Tool-API.md diff --git a/Test-Suite.md b/Test-Suite.md new file mode 100644 index 0000000..6b0c5e3 --- /dev/null +++ b/Test-Suite.md @@ -0,0 +1,127 @@ +## Introduction + +In addition to low-level subsystems, the suite tests the overall operation of +MMGen's commands by running them interactively as a user would. Thus the test +suite is useful not only for ensuring the MMGen system is correctly installed +and working on your platform but also for observing how it works. + +For BTC-only testing, only Bitcoin Core need be installed. For altcoin testing, +requirements are listed below. Non-standard RPC ports and data directories are +always used, so there’s no need to stop your running node or nodes. + +On Linux/x86\_64 with a reasonably fast processor, the full suite should run in +under 15 minutes when invoked with the `-F` option. On other platforms, +performance may be much slower. + +## Quick start + +### BTC-only testing + +Clone the Bitcoin Core repo somewhere on your system: + + $ git clone https://github.com/bitcoin/bitcoin + +Install the Bitcoin Core daemon [(source)][sd] [(binaries)][bd]. + +Point the test suite to your copy of the Bitcoin Core repo: + + $ export CORE_REPO_ROOT=/path/to/bitcoin/core/repo + +Run the test suite, skipping altcoin tests: + + $ test/test-release.sh -F noalt + +### Complete testing (BTC plus all supported altcoins) + +Make sure the [Bitcoin-ABC][ad], [Litecoin][ld] and [Monero][md] +daemons are installed on your system. + +Install [Parity Ethereum and the Ethereum dependencies][pe] and the [Solidity +compiler][sc] as described on the Altcoin-and-Forkcoin-Support page. + +In addition, you must install the following helper programs and libraries (MSYS2 +users can omit MoneroPy, Zcash-Mini and Ethkey): + +#### Pycoin + + $ git clone https://github.com/richardkiss/pycoin + $ cd pycoin + $ sudo python3 ./setup.py install + $ cd .. + +#### MoneroPy + + $ git clone https://github.com/bigreddmachine/MoneroPy + $ cd MoneroPy + $ sudo python3 ./setup.py install + $ cd .. + +#### Vanitygen Plus + + $ git clone https://github.com/exploitagency/vanitygen-plus + $ cd vanitygen-plus + $ make keyconv # mingw32-make.exe keyconv on MSYS2 + $ sudo install --strip keyconv /usr/local/bin + $ cd .. + +#### Zcash-Mini + + $ sudo apt-get install golang # skip this if Go is already installed + $ git clone https://github.com/FiloSottile/zcash-mini + $ cd zcash-mini + $ make + $ sudo install --strip ./bin/zcash-mini /usr/local/bin + $ cd .. + +#### Ethkey + +Download a [binary][pb] for your architecture, or install from source: + + $ sudo apt-get install rustc # skip this if Rust is already installed + $ git clone https://github.com/paritytech/parity-ethereum + $ cd parity-ethereum + $ cargo build -p ethkey-cli --release + $ sudo install --strip ./target/release/ethkey /usr/local/bin + $ cd .. + +Now you can run the test suite for all coins: + + $ test/test-release.sh -F + +## Overview of the individual tests + +`test/test-release.sh` is just a simple shell script that invokes the test +scripts with various options and arguments to ensure complete coverage of +MMGen’s functionality. Launch the script with the `-t` option to view the +invocations without running them. + +The test scripts themselves are all located in the `test/` directory and bear +the `.py` extension. They may be run individually if desired. Each test has an +informative help screen available via the `--help` option. + +The most important test in the suite, `test/test.py`, uses the `pexpect` library +to simulate interactive operation of MMGen commands. Running `test/test.py` +with the `-e` switch will produce the same output as if the commands had been +run by a user. + +| Test | What is tested | +|:----------------------|:-----------------------------------------------------| +| `test/colortest.py` | terminfo parsing; terminal colors | +| `test/gentest.py` | key/address generation - profiling and data validity | +| `test/hashfunc.py` | native SHA2 and Keccak implementations | +| `test/objtest.py` | MMGen data objects - creation and error handling | +| `test/objattrtest.py` | MMGen data objects - immutable attributes | +| `test/scrambletest.py`| HMAC scramble strings used in key/password derivation| +| `test/test.py` | overall operation of MMGen commands | +| `test/tooltest.py` | the `mmgen-tool` utility - overall operation | +| `test/tooltest2.py` | the `mmgen-tool` utility - data validity | +| `test/unit_tests.py` | low-level subsystems | + +[sd]: Install-Bitcoind-from-Source-on-Debian-or-Ubuntu-Linux +[bd]: Install-Bitcoind +[md]: https://getmonero.org/downloads/#linux +[ad]: https://download.bitcoinabc.org/ +[ld]: https://download.litecoin.org/litecoin-0.17.1/ +[pe]: Altcoin-and-Forkcoin-Support#a_par +[sc]: Altcoin-and-Forkcoin-Support#a_dt +[pb]: https://vanity-service.parity.io/parity-binaries?format=markdown&version=v2.7.2 diff --git a/Tool-API.md b/Tool-API.md new file mode 100644 index 0000000..ffa983b --- /dev/null +++ b/Tool-API.md @@ -0,0 +1,73 @@ +The tool API provides a convenient interface to selected methods in the +mmgen.tool module. Type `pydoc3 mmgen.tool.tool_api` to view available +methods and call signatures. + +## Examples + +### Initialize: + + from mmgen.tool import tool_api + tool = tool_api() + +### Key/address generation: + + # List available coins: + print(' '.join(tool.coins)) + + # Initialize a coin/network pair: + proto = tool.init_coin('btc','mainnet') + + # Print the available address types for current coin/network, along with a + # description. If tool.addrtype is unset, the first-listed will be used: + tool.print_addrtypes() + + # Set the address type to P2PKH with compressed public key: + tool.addrtype = 'compressed' + + # Skip user entropy gathering (not recommended) + tool.usr_randchars = 0 + + # Generate a random hex secret: + hexsec = tool.randhex() + + # Generate the key and address: + wif = tool.hex2wif(hexsec) + addr = tool.wif2addr(wif) + + # Generate an LTC regtest Segwit key and address: + proto = tool.init_coin('ltc','regtest') + tool.addrtype = 'segwit' + wif = tool.hex2wif(hexsec) + addr = tool.wif2addr(wif) + + # Generate a random LTC regtest Bech32 key/address pair: + tool.addrtype = 'bech32' + wif,addr = tool.randpair() + +### Mnemonic seed phrase generation: + + # Generate an MMGen native mnemonic seed phrase: + mmgen_seed = tool.hex2mn(hexsec) + + # Generate a BIP39 mnemonic seed phrase: + bip39_seed = tool.hex2mn(hexsec,fmt='bip39') + +### Utility methods: + + # Reverse the hex string: + hexsec_rev = tool.hexreverse(hexsec) + + # Get the HASH160 of the value: + sec_hash160 = tool.hash160(hexsec) + + # Convert the value to base58 format: + sec_b58 = tool.hextob58(hexsec) + + # Convert the value to base58 check format: + sec_b58chk = tool.hextob58chk(hexsec) + + # Convert the byte specification '4G' to an integer: + four_g = tool.bytespec('4G') + + # Convert the byte specification '4GB' to an integer: + four_gb = tool.bytespec('4GB')