books: add user-book for cuprated v0.0.1 (#165)

* apply

* add sections

* typo

* faq

* faq

* comments

* review

* update

books/user/README.md

@@ -1,5 +1,5 @@
 ## Cuprate's user book
-This book is the end-user documentation for Cuprate, aka, "how to use `cuprated`".
+This book is the end-user documentation for Cuprate.
 
 See:
 - <https://user.cuprate.org>

books/user/book.toml

@@ -3,17 +3,10 @@ authors = ["hinto-janai"]
 language = "en"
 multilingual = false
 src = "src"
-title = "Cuprate's user book"
-git-repository-url = "https://github.com/Cuprate/user-book"
+title = "Cuprate User Book - v0.0.1"
+git-repository-url = "https://github.com/Cuprate/cuprate/books/user"
 
-# TODO: fix after importing real files.
-#
-# [preprocessor.last-changed]
-# command = "mdbook-last-changed"
-# renderer = ["html"]
-#
-# [output.html]
-# default-theme = "ayu"
-# preferred-dark-theme = "ayu"
-# git-repository-url = "https://github.com/hinto-janai/cuprate-user"
-# additional-css = ["last-changed.css"]
+[output.html]
+default-theme = "ayu"
+preferred-dark-theme = "ayu"
+no-section-label = true

books/user/src/SUMMARY.md

@@ -1,3 +1,21 @@
 # Summary
 
-- [TODO](todo.md)
+[Introduction](introduction.md)
+
+- [Getting started](getting-started/intro.md)
+    - [System requirements](getting-started/sys-req.md)
+    - [Download](getting-started/download.md)
+    - [Building from source](getting-started/source.md)
+    <!-- TODO: add after reproducible builds - [Verifying](getting-started/verify.md) -->
+    - [Running](getting-started/run.md)
+
+- [Configuration](config.md)
+- [Command line](cli.md)
+
+- [Resources](resources/intro.md)
+    - [Disk](resources/disk.md)
+    - [Ports](resources/ports.md)
+    - [IP](resources/ip.md)
+
+- [Platform support](platform.md)
+- [License](license.md)

books/user/src/cli.md

@@ -0,0 +1,17 @@
+# Command line
+
+Command line options will override any overlapping [config](./config.md) values.
+
+Usage: `cuprated [OPTIONS]`
+
+<!-- TODO: automate the generation of the below table from `./cuprated --help` -->
+
+| Option | Description | Default | Possible values |
+|--------|-------------|---------|-----------------|
+| `--network <NETWORK>` | The network to run on | `mainnet` | `mainnet`, `testnet`, `stagenet`
+| `--outbound-connections <OUTBOUND_CONNECTIONS>` | The amount of outbound clear-net connections to maintain | `64` |
+| `--config-file <CONFIG_FILE>` | The PATH of the `cuprated` config file | `Cuprated.toml` |
+| `--generate-config` | Generate a config file and print it to stdout | |
+| `--skip-config-warning` | Stops the missing config warning and startup delay if a config file is missing | |
+| `-v`, `--version` | Print misc version information in JSON | |
+| `-h`, `--help` | Print help | |

books/user/src/config.md

@@ -0,0 +1,16 @@
+# Configuration
+`cuprated` reads its configuration file `Cuprated.toml` on startup - this is in the [TOML](https://toml.io) file format.
+
+`cuprated` will try to look for `Cuprated.toml` in the follow places, in order:
+- PATH specified in `--config-file`
+- Current directory: `./Cuprated.toml`
+- [OS specific directory](./resources/disk.md)
+
+## `Cuprated.toml`
+This is the default configuration file `cuprated` creates and uses, sourced from [here](https://github.com/Cuprate/cuprate/blob/main/binaries/cuprated/config/Cuprated.toml).
+
+If `cuprated` is started with no [`--options`](./cli.md), then the configuration used will be equivalent to this config file.
+
+```toml
+{{#include ../../../binaries/cuprated/config/Cuprated.toml}}
+```

books/user/src/getting-started/download.md

@@ -0,0 +1,12 @@
+# Download
+For convenience, Cuprate offers pre-built binaries for `cuprated` for the platforms listed in [`Platform support`](../platform.md) using GitHub CI in a non-reproducible way; it is highly recommended to build `cuprated` from source instead, see [`Building from source`](./source.md).
+
+| Platform                     | Download |
+|------------------------------|----------|
+| Windows x86_64               | <https://github.com/Cuprate/cuprate/releases/download/v0.0.1/cuprated-0.0.1-windows-x64.zip>
+| macOS x86_64                 | <https://github.com/Cuprate/cuprate/releases/download/v0.0.1/cuprated-0.0.1-macos-x64.tar.gz>
+| macOS ARM64                  | <https://github.com/Cuprate/cuprate/releases/download/v0.0.1/cuprated-0.0.1-macos-arm64.tar.gz>
+| Linux x86_64 (glibc >= 2.36) | <https://github.com/Cuprate/cuprate/releases/download/v0.0.1/cuprated-0.0.1-linux-x64.tar.gz>
+| Linux ARM64 (glibc >= 2.36)  | <https://github.com/Cuprate/cuprate/releases/download/v0.0.1/cuprated-0.0.1-linux-arm64.tar.gz>
+
+All release files are archived and also available at <https://archive.cuprate.org>.

books/user/src/getting-started/intro.md

@@ -0,0 +1,2 @@
+# Getting started
+This section contains information on downloading/building and running `cuprated`.

books/user/src/getting-started/run.md

@@ -0,0 +1,8 @@
+# Running
+To run `cuprated`:
+
+```bash
+./cuprated --config-file Cuprated.toml
+```
+
+`cuprated` can be ran without a config file although it is recommended to use one; see [`Configuration`](../config.md) for a default config file.

books/user/src/getting-started/source.md

@@ -0,0 +1,60 @@
+# Building from source
+To build `cuprated` from source you will need:
+
+- `git`
+- Up-to-date Rust toolchain
+- Compiler toolchain
+- Certain system dependencies
+
+To install Rust, follow [these instructions](https://www.rust-lang.org/learn/get-started) or run:
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+<!-- TODO: Windows build instruction -->
+
+## Linux
+Install the required system dependencies:
+
+```bash
+# Debian/Ubuntu
+sudo apt install -y build-essentials cmake git
+
+# Arch
+sudo pacman -Syu base-devel cmake git
+
+# Fedora
+sudo dnf install @development-tools gcc gcc-c++ cmake git
+```
+
+Clone the Cuprate repository and build:
+
+```bash
+git clone https://github.com/Cuprate/cuprate
+cd cuprate/
+cargo build --release --package cuprated
+```
+
+The built `cuprated` binary should be located at `target/release/cuprated`.
+
+## macOS
+Install [Homebrew](https://brew.sh):
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Install the required system dependencies:
+```bash
+brew install cmake
+```
+
+Clone the Cuprate repository and build:
+
+```bash
+git clone https://github.com/Cuprate/cuprate
+cd cuprate/
+cargo build --release --package cuprated
+```
+
+The built `cuprated` binary should be located at `target/release/cuprated`.

books/user/src/getting-started/sys-req.md

@@ -0,0 +1,17 @@
+# System requirements
+
+`cuprated` has the following hardware requirements.
+
+| Hardware requirement | Recommended       | Minimum |
+|----------------------|-------------------|---------|
+| CPU                  | 8+ cores          | 1 core
+| RAM                  | 8+ GB             | 2 GB
+| Disk (space)         | 500+ GB           | 300 GB
+| Disk (speed)         | 100+ MB/s writes  | ~5 MB/s writes
+| Network (speed)      | 30+ MB/s up/down  | ~1 MB/s up/down
+| Network (bandwidth)  | 1 TB+ per month   | ~300 GB per month
+
+Note that `cuprated`:
+- Benefits greatly from high-end hardware
+- Can run on weaker hardware (last tested on a `Raspberry Pi 4 (2GB RAM)` and `Raspberry Pi 5 (8 GB RAM)`)
+- Requires tweaking the config for your system, especially if you are at either extremes of the hardware scale

books/user/src/getting-started/verify.md

@@ -0,0 +1,43 @@
+# Verifying
+Verification of release files is optional but highly recommended. This ensures that you have not downloaded a tampered version of `cuprated`.
+
+To verify release files of `cuprated`, follow these instructions:
+
+<!--
+TODO:
+add some pictures, make this process easier to understand in
+general e.g. similar to bitcoin/monero's verify section.
+-->
+
+### Download verification files for latest release
+- Latest release: <https://github.com/Cuprate/cuprate/releases/latest>
+- Hashes: <https://github.com/Cuprate/cuprate/releases/download/v0.0.1/SHA256SUMS>
+- Hash signatures: <https://github.com/Cuprate/cuprate/releases/download/v0.0.1/SHA256SUMS.asc>
+
+### Verify the hashes
+After downloading the release files, compare their hashes with the `SHA256SUMS` file.
+
+```bash
+sha256sum --ignore-missing --check SHA256SUMS
+```
+
+You should see something like: `cuprate-0.0.1-linux-x64.tar.gz: OK`.
+
+### Verify the hash signatures
+Cuprate releases are signed by multiple individuals.
+
+First, import the PGP keys for all individuals:
+```bash
+# Clone the Cuprate repository.
+git clone https://github.com/Cuprate/cuprate
+
+# Import all PGP keys.
+gpg --import cuprate/misc/gpg_keys/*.asc
+```
+
+Then, confirm all signatures:
+```bash
+gpg --verify SHA256SUMS.asc
+```
+
+You should see `gpg: Good signature` for all keys.

books/user/src/images/CuprateLogo.svg

@@ -0,0 +1 @@
+../../../../misc/logo/CuprateLogo.svg

books/user/src/introduction.md

@@ -0,0 +1,132 @@
+<div align="center">
+<img src="images/CuprateLogo.svg" width="50%"/>
+
+[Cuprate](https://github.com/Cuprate/cuprate) is an alternative and independent [Monero](https://getmonero.org) node implementation that is focused on being fast, user-friendly, and backwards compatible with [`monerod`](https://github.com/monero-project/monero).
+
+This project is currently a work-in-progress; the `cuprated` node can be ran by users although it is not yet ready for production. This book contains brief sections documenting `cuprated` usage, however, be aware that it is **incomplete** and missing sections.
+
+To get started, see: [`Getting started`](./getting-started/intro.md).
+
+</div>
+
+---
+
+# FAQ
+Frequently asked questions about Cuprate.
+
+## Who?
+Cuprate was started by [SyntheticBird45](https://github.com/SyntheticBird45) in [early 2023](https://github.com/Cuprate/cuprate/commit/2c7cb27548c727550ce4684cb31d0eafcf852c8e) and was later joined by [boog900](https://github.com/boog900), [hinto-janai](https://github.com/hinto-janai), and [other contributors](https://github.com/Cuprate/cuprate/graphs/contributors).
+
+A few Cuprate contributors are funded by Monero's [Community Crowdfunding System](http://ccs.getmonero.org) to work on Cuprate and occasionally `monerod`.
+
+## What is `cuprated`?
+`monerod` is the [daemon](https://en.wikipedia.org/wiki/Daemon_(computing)) of the Monero project, the Monero node.
+
+`cuprated` is the daemon of the Cuprate project, the Cuprate node.
+
+Both operate on the same network, the Monero network, and are responsible for roughly the same tasks.
+
+For more information on the role of alternative node implementations, see:
+- <https://clientdiversity.org>
+- <https://bchfaq.com/knowledge-base/what-are-the-full-node-implementations-for-bitcoin-cash>
+- <https://zfnd.org/zebra-stable-release>
+
+## Does `cuprated` replace `monerod`?
+No.
+
+`cuprated` cannot currently replace `monerod` in production environments. With that said, there will be practical performance benefits for users to use `cuprated` eventually.
+
+## Is it safe to run `cuprated`?
+**⚠️ This project is still in development; do NOT use `cuprated` for any serious purposes ⚠️**
+
+`cuprated` is fine to run for casual purposes and has a similar attack surface to other network connected services.
+
+See [`Resources`](./resources/intro.md) for information on what system resources `cuprated` will use.
+
+## What files does `cuprated` create?
+See [`Resources/Disk`](./resources/disk.md).
+
+## What can `cuprated` currently do?
+Cuprate's node (`cuprated`) can currently:
+
+- Sync the blockchain and transaction pool
+- Broadcast and relay blocks and transactions
+- Help other peers sync their blockchain
+
+## How fast does `cuprated` sync?
+The current full verification sync timings are around ~7.5x faster than `monerod`.
+
+In real terms, 16 hour full verification syncs and 4 hour fast-sync syncs have been reported on consumer grade hardware. On faster hardware (14 threads, 10Gbps networking), sub 2 hour fast-syncs have been reported.
+
+Various testing results can be found [here](https://github.com/Cuprate/cuprate/issues/195).
+
+## How to see status of `cuprated`?
+In the terminal running `cuprated`, type `status`.
+
+Use the `help` to see the full list of commands.
+
+## How to tell `cuprated` is fully synced?
+`cuprated` emits a message when it is fully synced: `synchronised with the network`.
+
+It also logs its block height status when syncing, for example:
+
+```text
+2025-03-01T22:15:52.516944Z  INFO incoming_block_batch{start_height=3362022 len=29}: Successfully added block batch
+```
+
+- `start_height` is the height `cuprated` was previously at
+- `len` is how many blocks have been added to the blockchain
+
+`start_height` can be compared to a block height from `monerod`
+or a block explorer to see if `cuprated` is near synced.
+
+## How big is the database?
+As of March 4th 2025, `cuprated`'s database is ~240GB in size.
+
+For reference, `monerod`'s database is ~200GB in size.
+
+This is planned to be improved in the future.
+
+## Is the database compatible with `monerod`?
+No.
+
+The database `cuprated` generates and uses cannot directly be used by `monerod` and vice-versa. Supporting this is possible but there are no current plans to do so.
+
+## Can I connect a wallet to `cuprated`?
+Not yet.
+
+Wallets require the [daemon RPC API](https://docs.getmonero.org/rpc-library/monerod-rpc). This is actively being worked on to be backwards compatible with `monerod`, although this is not yet available.
+
+## Can `cuprated` be used with an anonymity network like Tor?
+Not yet (directly).
+
+Tor is planned to be integrated into `cuprated` via [`arti`](https://arti.torproject.org), although this is not yet available.
+
+In the meanwhile, solutions like [`torsocks`](https://github.com/dgoulet/torsocks)
+can redirect any program's networking through Tor, including `cuprated`.
+Note that this will slow down syncing speeds heavily.
+
+## `cuprated` won't start because of a "killswitch", why?
+The current alpha builds of `cuprated` contain killswitches that activate 1 week after the _next_ release is out. If the killswitch activates, you must upgrade to the [latest release](https://github.com/Cuprate/cuprate/releases/latest).
+
+The reasoning for why this exists can be found here: <https://github.com/Cuprate/cuprate/pull/365>.
+
+## What is the release schedule?
+New versions of `cuprated` are planned to release every 4 weeks.
+
+See [this GitHub issue](https://github.com/Cuprate/cuprate/issues/374) for more details.
+
+## What is the versioning scheme?
+`cuprated` is currently in alpha (`0.0.x`).
+
+After sufficient testing and development, `cuprated` will enter beta (`0.x.y`) then stable (`x.y.z`) releases.
+
+See [this GitHub issue](https://github.com/Cuprate/cuprate/issues/374) for more details.
+
+## What is the current progress?
+See [this Reddit thread](https://www.reddit.com/r/Monero/comments/1ij2sw6/cuprate_2024_progress_report) for a brief report on Cuprate's progress throughout 2024.
+
+Things are always changing so feel free to join our [Matrix channel](https://matrix.to/#/#cuprate:monero.social) and ask questions.
+
+## What is the current roadmap?
+See [this GitHub issue](https://github.com/Cuprate/cuprate/issues/376) for Cuprate's rough 2025 roadmap.

books/user/src/license.md

@@ -0,0 +1,6 @@
+# License
+The `cuprated` binary is distributed under the [AGPL-3.0 license](https://github.com/Cuprate/cuprate/blob/main/LICENSE-AGPL).
+
+Much of the codebase that makes up `cuprated` is under the [MIT license](https://github.com/Cuprate/cuprate/blob/main/LICENSE-MIT).
+
+See also: <https://github.com/Cuprate/cuprate/blob/main/LICENSE>.

books/user/src/platform.md

@@ -0,0 +1,46 @@
+# Platform support
+
+Support for different platforms ("targets") are organized into three tiers,
+each with a different set of guarantees. Targets are identified by the
+[Rust "target triple"](https://doc.rust-lang.org/rustc/platform-support.html)
+which is the string used when compiling `cuprated`.
+
+| Attribute           | Tier 1 | Tier 2            | Tier 3 |
+|---------------------|--------|-------------------|--------|
+| Official builds     | 🟢     | 🟢                | 🔴
+| Guaranteed to build | 🟢     | 🟢                | 🟡
+| Automated testing   | 🟢     | 🟡 (some targets) | 🔴
+| Manual testing      | 🟢     | 🟡 (sometimes)    | 🔴
+
+## Tier 1
+
+Tier 1 targets can be thought of as "guaranteed to work".
+
+| Target                      | Notes  |
+|-----------------------------|--------|
+| `x86_64-unknown-linux-gnu`  | x64 Linux (glibc 2.36+)
+| `aarch64-unknown-linux-gnu` | ARM64 Linux (glibc 2.36+)
+| `aarch64-apple-darwin`      | ARM64 macOS (11.0+)
+
+## Tier 2
+
+Tier 2 targets can be thought of as "guaranteed to build".
+
+| Target                      | Notes  |
+|-----------------------------|--------|
+| `x86_64-pc-windows-msvc`    | x64 Windows (MSVC, Windows Server 2022+)
+
+## Tier 3
+
+Tier 3 targets are those which the Cuprate codebase likely can support,
+but which Cuprate does not build or test on a regular basis, so they may or may not work.
+Official builds are not available, but may eventually be planned.
+
+| Target                       | Notes  |
+|------------------------------|--------|
+| `x86_64-unknown-linux-musl`  | x64 Linux (musl 1.2.3)
+| `aarch64-unknown-linux-musl` | ARM64 Linux (musl 1.2.3)
+| `x86_64-unknown-freebsd` 	   | x64 FreeBSD
+| `aarch64-unknown-freebsd`    | ARM64 FreeBSD
+| `aarch64-pc-windows-msvc`    | ARM64 Windows (MSVC, Windows Server 2022+)
+| `x86_64-apple-darwin`        | x64 macOS

books/user/src/resources/disk.md

@@ -0,0 +1,55 @@
+# Disk
+`cuprated` requires at least ~300 GB of disk storage for operation although 500+ GB is recommended.
+
+## Cache
+The directory used for cache files is:
+
+| OS      | Directory                              |
+|---------|----------------------------------------|
+| Windows | `C:\Users\User\AppData\Local\Cuprate\` |
+| macOS   | `/Users/User/Library/Caches/Cuprate/`  |
+| Linux   | `/home/user/.cache/cuprate/`           |
+
+Although not recommended, this directory can be deleted without major disruption to `cuprated`.
+
+The files in this directory are:
+
+| File                   | Purpose |
+|------------------------|---------|
+| `addressbook/ClearNet` | P2P state for clear-net
+
+## Configuration
+The directory used for files related to configuration is:
+
+| OS      | Directory                                          |
+|---------|----------------------------------------------------|
+| Windows | `C:\Users\User\AppData\Roaming\Cuprate\`           |
+| macOS   | `/Users/User/Library/Application Support/Cuprate/` |
+| Linux   | `/home/user/.config/cuprate/`                      |
+
+The files in this directory are:
+
+| File            | Purpose |
+|-----------------|---------|
+| `Cuprated.toml` | `cuprated` configuration file
+
+## Data
+The directory used for general data is:
+
+| OS      | Directory                                          |
+|---------|----------------------------------------------------|
+| Windows | `C:\Users\User\AppData\Roaming\Cuprate\`           |
+| macOS   | `/Users/User/Library/Application Support/Cuprate/` |
+| Linux   | `/home/user/.local/share/cuprate/`                 |
+
+The files in this directory are:
+
+<!-- TODO: document redb files -->
+
+| File                  | Purpose |
+|-----------------------|---------|
+| `blockchain/data.mdb` | Blockchain database file
+| `blockchain/lock.mdb` | Blockchain database lock
+| `txpool/data.mdb`     | Transaction pool database file
+| `txpool/lock.mdb`     | Transaction pool database lock
+| `logs/{YYYY-MM-DD}`   | Log files for each day

books/user/src/resources/intro.md

@@ -0,0 +1,2 @@
+# Resources
+This section documents the system resources `cuprated` uses.

books/user/src/resources/ip.md

@@ -0,0 +1,5 @@
+# IP
+`cuprated` currently binds to a single [IPv4 address](https://en.wikipedia.org/wiki/IPv4) for P2P connections.
+
+By default, this IP address is `0.0.0.0`, which will bind to all available interfaces.
+See the [`listen_on` option in the config file](../config.md) to manually set this IP address.

books/user/src/resources/ports.md

@@ -0,0 +1,5 @@
+# Ports
+`cuprated` currently uses a single port to accept incoming P2P connections.
+
+By default, this port is randomly selected.
+See the [`p2p_port` option in the config file](../config.md) to manually set this port.

books/user/src/todo.md

@@ -1 +0,0 @@
-# TODO