Skip to content

Commit

Permalink
docs: clean up documentation (#5878)
Browse files Browse the repository at this point in the history 
Description
---
Updates the main `readme` with various nits and grammatical fixes.

Motivation and Context
---
[Good grammar is
essential.](https://www.youtube.com/watch?v=V21aZ_ZuoJM)

How Has This Been Tested?
---
It looks good.

What process can a PR reviewer use to test or verify this change?
---
Read it carefully!
  • Loading branch information
@AaronFeickert
AaronFeickert committed Oct 27, 2023
1 parent 4159b76 commit 879e1e1
Showing 1 changed file with 43 additions and 47 deletions.
90 changes: 43 additions & 47 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The recommended running versions of each network are:
| Nextnet | 0.51.0-rc.1 |
| Esmeralda | 0.52.0-pre.1 |

For more detail about versioning see [Release Ideology](https://github.com/tari-project/tari/blob/development/docs/src/branching_releases.md)
For more detail about versioning, see [Release Ideology](https://github.com/tari-project/tari/blob/development/docs/src/branching_releases.md).

### Download

Expand Down Expand Up @@ -54,7 +54,7 @@ After you have downloaded the binaries, you need to install them. This is easy t

#### On \*Nix

Assuming you want to install the Tari applications into your home folder, then, from within a terminal:
Assuming you want to install the Tari applications into your home folder, run the following:

cd ~
tar -xf <PATH_TO_BINARY_INSTALL_FILE>
Expand Down Expand Up @@ -96,7 +96,7 @@ depending on the choices you make when prompted:

- Depending on your choice of mining:

- SHA3 stand-alone mining
- SHA3 standalone mining
- Execute the `start_minotari_miner` soft link/shortcut.
- Merge mining with Monero
- Execute the `start_minotari_merge_mining_proxy` soft link/shortcut.
Expand All @@ -120,9 +120,9 @@ brew install --cask powershell

#### (macOS M1 chipset)
It is important to note that RandomX does not work on Xcode version 14.1 and newer. To compile Tari and run properly you need to run XCode version 14.0 or earlier.
To run multiple versions of XCode you can use this guide [here](https://hacknicity.medium.com/working-with-multiple-versions-of-xcode-e331c01aa6bc)
To run multiple versions of XCode, you can use this guide [here](https://hacknicity.medium.com/working-with-multiple-versions-of-xcode-e331c01aa6bc).

If randomX unit tests are still failing, please update the Mac to ensure its running at least `Darwin Kernel Version 22.3.0`
If RandomX unit tests are still failing, please update the Mac to ensure it's running at least `Darwin Kernel Version 22.3.0`.


#### (Ubuntu 18.04, including WSL-2 on Windows)
Expand Down Expand Up @@ -178,31 +178,31 @@ First you'll need to make sure you have a full development environment set up:
#### Install Rust (\*nix)

You can follow along at [The Rust Website](https://www.rust-lang.org/tools/install) or just follow these steps to get
Rust installed on your machine.
Rust installed on your machine:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then make sure that `cargo` has been added to your path.
Then make sure that `cargo` has been added to your path:

export PATH="$HOME/.cargo/bin:$PATH"

#### Install Rust (Windows 10)

Follow the installation process for Windows at [The Rust Website](https://www.rust-lang.org/tools/install). Then make
sure that `cargo` and `rustc` has been added to your path:
sure that `cargo` and `rustc` have been added to your path:

cargo --version
rustc --version

### Checkout the source code

In your directory of choice (e.g. `%USERPROFILE%\Code` on Windows), clone the Tari repo
In your directory of choice (_e.g._ `%USERPROFILE%\Code` on Windows), clone the Tari repo:

git clone https://github.com/tari-project/tari.git

### Build

Grab a cup of coffee and begin the Tari build
Grab a cup of coffee and begin the Tari build.

(\*nix)

Expand All @@ -218,7 +218,7 @@ build, which will create the executable inside your `%USERPROFILE%\Code\tari\tar
cd %USERPROFILE%\Code\tari
cargo build --release

A successful build should output something as follows
A successful build should output something like this:

```
Compiling minotari_wallet v0.0.9 (.../tari/base_layer/wallet)
Expand All @@ -228,15 +228,15 @@ A successful build should output something as follows
Finished release [optimized] target(s) in 12m 24s
```

Compiled executable can be found by following path:
Compiled executables can be found at these paths::

./target/release/minotari_node
./target/release/minotari_console_wallet
./target/release/minotari_merge_mining_proxy
./target/release/minotari_miner

Alternatively, cargo can build and install the executable into `~/.cargo/bin` (`%USERPROFILE%\.cargo\bin` on Windows), so it will be executable from anywhere
on your system.
Alternatively, `cargo` can build and install the executable into `~/.cargo/bin` (`%USERPROFILE%\.cargo\bin` on Windows), so it will be executable from anywhere
on your system:

cargo install --path=applications/minotari_node --force
cargo install --path=applications/minotari_console_wallet --force
Expand All @@ -245,8 +245,8 @@ on your system.

---

Alternatively, cargo can build and install the executable into `%USERPROFILE%\.cargo\bin`, so it will be executable from
anywhere on your system.
Alternatively, `cargo` can build and install the executable into `%USERPROFILE%\.cargo\bin`, so it will be executable from
anywhere on your system:

cargo install --path=applications/minotari_node --force
cargo install --path=applications/minotari_console_wallet --force
Expand All @@ -259,11 +259,11 @@ The executables will either be inside your `~/tari/target/release` (on Linux) or
(on Windows) directory, or alternatively, inside your `~/.cargo/bin` (on Linux) `%USERPROFILE%\.cargo\bin` (on Windows)
directory, depending on the build choice above, and must be run from the command line. If the former build method was
used, you can run it from that directory, or you more likely want to copy it somewhere more convenient. Make sure to
start Tor service `~/tari/applications/minotari_node/osx/start_tor` (on Mac),
start the Tor service `~/tari/applications/minotari_node/osx/start_tor` (on Mac),
`~/tari/applications/minotari_node/linux/start_tor` (on Linux) or
`%USERPROFILE%\Code\tari\applications\minotari_node\windows\start_tor.lnk` (on Windows).

To run from any directory of your choice, where the executable is visible in the path (first time use):
To run from any directory of your choice, where the executable is visible in the path (first-time use):

minotari_node --init
minotari_node
Expand Down Expand Up @@ -296,7 +296,7 @@ flag if you want to run in debug mode (first time use):

cargo run --bin minotari_miner --release

Consecutive runs:
On consecutive runs:

cargo run --bin minotari_node --release

Expand All @@ -317,11 +317,11 @@ directory.

## Using Docker

### Running the base node with a docker image
### Running the base node with a Docker image

Minotari Base Node Docker images can be found at https://quay.io/repository/tarilabs/tari_base_node

Using `docker-compose.yaml`
Using `docker-compose.yaml`:

```
version: "3"
Expand All @@ -343,22 +343,22 @@ services:

Then run `docker-compose up -d` to start your docker service.

Check the running state with `docker-compose ps`
Check the running state with `docker-compose ps`:

```
Name Command State Ports
------------------------------------------------------------------
tbn_tari_base_node_1 start.sh Up 0.0.0.0:18142->18142/tcp
```

To connect to the console, use `docker ps` to get the container ID which to attach to the tari_base_node in docker
To connect to the console, use `docker ps` to get the container ID to which to attach the `tari_base_node`` in Docker:

```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
73427509a4bb quay.io/tarilabs/tari_base_node:v0.5.4 "start.sh" 45 minutes ago Up 26 minutes 0.0.0.0:18142->18142/tcp tbn_tari_base_node_1
```

With the container ID `73427509a4bb`, connect to the minotari_node console as follows `docker attach 73427509a4bb`
With the container ID `73427509a4bb`, connect to the `minotari_node`` console using `docker attach 73427509a4bb`:

```
>> help
Expand All @@ -381,30 +381,30 @@ Syncing 5229/5233

---

### Building a docker image
### Building a Docker image

If you don't want to use the docker images provided by the community, you can roll your own!
If you don't want to use the Docker images provided by the community, you can roll your own!

First, clone the Tari repo
First, clone the Tari repo:

```bash
git clone git@github.com:tari-project/tari.git
```

Then build the image using the dockerfile in `buildtools`. The base node docker file build the application and then
places the binary inside a small container, keeping the executable binary to a minimum.
Then build the image using the dockerfile in `buildtools`. The base node dockerfile builds the application and then
places the binary inside a small container, keeping the executable binary to a minimum:

docker build -t tari_base_node:latest -f ./buildtools/base_node.Dockerfile .

Test your image
Test your image:

docker run --rm -ti tari_base_node tari_base_node --help

Run the base node
Run the base node:

docker run -ti -v /path/to/config/dir:/root/.tari tari_base_node

Default docker builds for base x86-64 CPU. Better performing builds can be created by passing build options
Default Docker builds for base x86-64 CPU. Better performing builds can be created by passing build options:

docker build -t tari_base_node:performance --build-arg TBN_ARCH=skylake --build-arg TBN_FEATURES=avx2 -f ./buildtools/base_node.Dockerfile .

Expand All @@ -414,12 +414,12 @@ Default docker builds for base x86-64 CPU. Better performing builds can be creat

The Tari protocol supports hybrid mining; stand-alone or pooled SHA3 mining using the Minotari Miner or merged mining with
Monero using the Minotari Merge Mining Proxy in conjunction with XMRig (RandomX-based mining). Blocks to be won by
stand-alone and pooled SHA3 mining has been apportioned to approximately 40% and with Monero merged mining to approximately 60%.
standalone and pooled SHA3 mining have been apportioned to approximately 40% and with Monero merged mining to approximately 60%.
This apportionment is deeply baked into the Tari protocol and part of the consensus rules. The 40/60 split is determined
by slightly different block target times for each algorithm, that when combined will give an average block time of
approximately 120s. Each mining algorithms make use of Linear Weighted Moving Average (LWMA) maths to gracefully adjust
approximately 120 seconds. Each mining algorithm makes use of Linear Weighted Moving Average (LWMA) maths to gracefully adjust
the target difficulties to adhere to the respective target block times. Any block won by either mining algorithm will be
accepted, and when there is a tie a geometric mean calculation will be used to decide the winner. This system is
accepted, and when there is a tie, a geometric mean calculation will be used to decide the winner. This system is
completely fair without any additional empirical meddling to try force a certain outcome.

### Tari SHA3 mining
Expand Down Expand Up @@ -645,7 +645,7 @@ they are not enabled already:
base_node_grpc_address = "127.0.0.1:18142"
```

And then depending on if you are using solo mining or self-select mining you will use one of the following:
Depending on if you are using solo mining or self-select mining, you will use one of the following:

###### Solo mining

Expand Down Expand Up @@ -754,7 +754,7 @@ in JSON format:

- Result -> With `Config file`, copy or download, than save as `config.json`.

Using the public stagenet wallet address above the resulting configuration file should look like this:
Using the public stagenet wallet address above, the resulting configuration file should look like this:

```
{
Expand Down Expand Up @@ -834,7 +834,7 @@ activity for that address. The configuration file used for this exercise is show

#### Perform merge mining

Tor and the required Minotari applications must be started and preferably in this order:
Tor and the required Minotari applications must be started, preferably in this order:

- Tor:

Expand Down Expand Up @@ -920,7 +920,7 @@ and accepting jobs:
[2021-01-21 12:12:57.983] cpu accepted (1/1) diff 293330 (594 ms)
```

The `cpu: rejected` and `cpu: accepted` messages originates from stagenet or mainnet `monerod`, and shows the Monero
The `cpu: rejected` and `cpu: accepted` messages originate from stagenet or mainnet `monerod`, and show the Monero
statistics. At this point, the mined and rejected Minotari coinbases should be visible in the Minotari Wallet.

##### Pool merged mining with Monero (self select)
Expand All @@ -934,7 +934,7 @@ its reference pool implementation running [here](http://monerop.com/), and
[cryptonote.social](https://cryptonote.social/xmr). With normal self select mode, XMRig requests a Monero block
template from a third party and submits the solution to the mining pool. Minotari added a `submit-to-origin` option to the
self select mode whereby, if a solution has been found that only matches the pool difficulty, XMRig will submit the
solution to the pool only, but if the achieved difficulty meets both that of the pool and Minotari, it will be submitted to
solution to the pool only; but if the achieved difficulty meets both that of the pool and Minotari, it will be submitted to
the Merge Mining Proxy as well as to the mining pool.

###### Merge Mining Proxy configuration
Expand Down Expand Up @@ -988,22 +988,18 @@ your wallet identity under `Username:` to see your shares, or try `taritest` if
## RFC documents

The RFCs are long-form technical documents proposing changes and features to the Tari network and ecosystem.
They are hosted at https://rfc.tari.com, and the RFC repo is at https://github.com/tari-project/rfcs
They are hosted at https://rfc.tari.com, and the RFC repo is at https://github.com/tari-project/rfcs.

### Source code documentation

Run

cargo doc

to generate the documentation. The generated html sits in `target/doc/`. Alternatively, to open a specific package's documentation directly in your browser, run
to generate the documentation. The generated html sits in `target/doc/`. Alternatively, to open a specific package's documentation directly in your browser, run the following:

cargo doc -p <package> --open

## Code organisation

_Out of date as of July 2022._ TODO - Good first issue?

## Conversation channels

We're generally on [Discord](https://discord.gg/q3Sfzb8S2V)
We're generally on [Discord](https://discord.gg/q3Sfzb8S2V).

0 comments on commit 879e1e1

Please sign in to comment.