diff --git a/books/user/README.md b/books/user/README.md index ee2ccaef..281aeba4 100644 --- a/books/user/README.md +++ b/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> diff --git a/books/user/book.toml b/books/user/book.toml index f26e736a..5ea2d6fc 100644 --- a/books/user/book.toml +++ b/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 diff --git a/books/user/src/SUMMARY.md b/books/user/src/SUMMARY.md index 2b8615c9..750bfae1 100644 --- a/books/user/src/SUMMARY.md +++ b/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) \ No newline at end of file diff --git a/books/user/src/cli.md b/books/user/src/cli.md new file mode 100644 index 00000000..8bb8686c --- /dev/null +++ b/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 | | \ No newline at end of file diff --git a/books/user/src/config.md b/books/user/src/config.md new file mode 100644 index 00000000..14880332 --- /dev/null +++ b/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}} +``` diff --git a/books/user/src/getting-started/download.md b/books/user/src/getting-started/download.md new file mode 100644 index 00000000..05acc388 --- /dev/null +++ b/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>. diff --git a/books/user/src/getting-started/intro.md b/books/user/src/getting-started/intro.md new file mode 100644 index 00000000..ef53a194 --- /dev/null +++ b/books/user/src/getting-started/intro.md @@ -0,0 +1,2 @@ +# Getting started +This section contains information on downloading/building and running `cuprated`. \ No newline at end of file diff --git a/books/user/src/getting-started/run.md b/books/user/src/getting-started/run.md new file mode 100644 index 00000000..b3c1d355 --- /dev/null +++ b/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. diff --git a/books/user/src/getting-started/source.md b/books/user/src/getting-started/source.md new file mode 100644 index 00000000..cbb10e45 --- /dev/null +++ b/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`. diff --git a/books/user/src/getting-started/sys-req.md b/books/user/src/getting-started/sys-req.md new file mode 100644 index 00000000..90a62558 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/books/user/src/getting-started/verify.md b/books/user/src/getting-started/verify.md new file mode 100644 index 00000000..3b8988fd --- /dev/null +++ b/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. \ No newline at end of file diff --git a/books/user/src/images/CuprateLogo.svg b/books/user/src/images/CuprateLogo.svg new file mode 120000 index 00000000..248d4158 --- /dev/null +++ b/books/user/src/images/CuprateLogo.svg @@ -0,0 +1 @@ +../../../../misc/logo/CuprateLogo.svg \ No newline at end of file diff --git a/books/user/src/introduction.md b/books/user/src/introduction.md new file mode 100644 index 00000000..d3745630 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/books/user/src/license.md b/books/user/src/license.md new file mode 100644 index 00000000..f9793928 --- /dev/null +++ b/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>. \ No newline at end of file diff --git a/books/user/src/platform.md b/books/user/src/platform.md new file mode 100644 index 00000000..e8888bda --- /dev/null +++ b/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 diff --git a/books/user/src/resources/disk.md b/books/user/src/resources/disk.md new file mode 100644 index 00000000..15e57ac1 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/books/user/src/resources/intro.md b/books/user/src/resources/intro.md new file mode 100644 index 00000000..c694dff6 --- /dev/null +++ b/books/user/src/resources/intro.md @@ -0,0 +1,2 @@ +# Resources +This section documents the system resources `cuprated` uses. \ No newline at end of file diff --git a/books/user/src/resources/ip.md b/books/user/src/resources/ip.md new file mode 100644 index 00000000..965c6b5e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/books/user/src/resources/ports.md b/books/user/src/resources/ports.md new file mode 100644 index 00000000..64684dbf --- /dev/null +++ b/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. \ No newline at end of file diff --git a/books/user/src/todo.md b/books/user/src/todo.md deleted file mode 100644 index 46409041..00000000 --- a/books/user/src/todo.md +++ /dev/null @@ -1 +0,0 @@ -# TODO