From d6ffbf04cfcccb664ed59f3bb687aa31b1e3fd60 Mon Sep 17 00:00:00 2001 From: crProductGuy <95465010+crProductGuy@users.noreply.github.com> Date: Thu, 6 Jan 2022 15:41:41 -0800 Subject: [PATCH] Cr product guy ironfish cli documentation enhancements (#633) * Update README.md * Documentation only; no code changes, so no tests added, and no breaking changes. * Include the critical "cd ironfish-cli" command that several testnet users have not figured out, which prevented them from starting nodes and miners without help in Discord * Enrich mining examples with --threads directive, again to enable rapid user success and reduce support burden * Enhance description of mining output to include the new H/s display and a performance example on a current CPU chip to enable potential users to predict what hashrate their HW might achieve. * Update README.md * Proofreading Co-authored-by: Derek Guenther --- ironfish-cli/README.md | 65 ++++++++++++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/ironfish-cli/README.md b/ironfish-cli/README.md index 1252e88519..a5f4538750 100644 --- a/ironfish-cli/README.md +++ b/ironfish-cli/README.md @@ -4,37 +4,66 @@ The main entry point for an Iron Fish CLI that is capable of mining blocks and s ## Starting the CLI -Build, run, and restart when the code changes: +If you're still in the `ironfish` directory in your terminal window, run `cd ironfish-cli`. + * Otherwise, you'll get a "Command not found" error. -- `yarn start` +Next, start the CLI with one of these commands: -Build, then run the CLI without watching for changes: +* Build, run, and restart when the code changes: + - `yarn start` -- `yarn start:once` +* Build, then run the CLI without watching for changes: + - `yarn start:once` -## Use Scenarios -### Starting a single node -Run these command in the terminal: +## Usage Scenarios +### Starting a single node +Run this command in the terminal: - `yarn start start` -Interact with the node in a new tab: -- `yarn start accounts:balance` +Interact with the node in a new terminal window: +- `yarn start status` + - Show your node's status +- `yarn start accounts:balance` + - Show the balance of your account, including $IRON from blocks you've mined + - Tentative balance includes all known transactions. Spending balance includes only transactions on blocks on the main chain - `yarn start faucet` + - Request a small amount of $IRON for testing payments - `yarn start accounts:pay` + - Send $IRON to another account -### Mining -Then run these commands in two different terminals: - -- `yarn start start -d default -p 9033` -- `yarn start miners:start` - -You should see messages in the second terminal indicating that blocks are mined. +### Start a node and start mining +Run these commands in two different terminals: -You can increase the number of threads by adding `--threads `. Use `-1` to use all available threads. +- `yarn start start` + - Defaults to port 9033 + - This is equivalent to `yarn start start -d default -p 9033` -- `yarn start miners:start --threads 2` +- `yarn start miners:start` + - The default thread count is 1. + - You can increase the number of threads by adding `--threads `. Use `-1` to autodetect threads based on your CPU cores. + + - Examples: + - `yarn start miners:start --threads 4` + - To use 4 physical CPU cores + - `yarn start miners:start --threads -1` + - To use all the cores on your CPU + - This may make your machine unresponsive or perform worse than a lesser number. + - You may want to start with a low thread count and increase it until your hashrate stops increasing. + - Note: Hyperthreading (2 miner threads per CPU core) is not fully optimized yet + +You should see messages in the second terminal indicating that the miner is running: + - `Starting to mine with 8 threads` + - `Mining block 6261 on request 1264... \ 1105974 H/s` + - The H/s number corresponds to the hash rate power of your machine with the given number of mining threads. + - Performance reference: 8-core 3.8+ GHz AMD Ryzen 7 4700G with 8 threads gave the above 1.1 M H/s. + +When a block is mined, you will see a status line in the node's terminal (the first terminal): + - `Successfully mined block xxx (6543) has 1 transactions` + - Mining 1 block can take several hours or days, depending on your machine's hashrate. + - Your miner may display `Submitting hash for block`, but this does not necessarily mean you've mined a block. The block still needs to be created, validated, and checked to be heavier by the node before it can be added to the main chain. + - In these cases, your node will display "Discarding block" or "Failed to add block". ### Multiple Nodes