Cuprate/cuprate
Cuprate/cuprate
1
0
Fork 0
mirror of https://github.com/Cuprate/cuprate.git synced 2025-04-23 06:18:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

books: user-book for cuprated 0.0.2 ()

Browse source 
* title

* fixes

* add `--version` table

* add types

* config docs

* add macro docs

* fix

* case

* Update binaries/cuprated/src/config.rs

---------

Co-authored-by: Boog900 <boog900@tutanota.com>
This commit is contained in:
hinto-janai 2025-04-08 20:12:05 -04:00 committed by GitHub
parent 3ef6a96d04
commit 550d8598e4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 261 additions and 60 deletions

42
binaries/cuprated/src/config.rs
View file

@ -49,8 +49,13 @@ const HEADER: &str = r"## ____ _
## \____\__,_| .__/|_| \__,_|\__\___|
## |_|
##
## All these config values can be set to their default by commenting them out with #.
## Some values are already commented out, to set the value remove the # at the start of the line.
## All these config values can be set to
## their default by commenting them out with '#'.
##
## Some values are already commented out,
## to set the value remove the '#' at the start of the line.
##
## For more documentation, see: <https://user.cuprate.org>.
";
@ -98,43 +103,50 @@ config_struct! {
#[derive(Debug, Deserialize, Serialize, PartialEq)]
#[serde(deny_unknown_fields, default)]
pub struct Config {
/// The network we should run on.
/// The network cuprated should run on.
///
/// Valid values: ["Mainnet", "Testnet" and "Stagenet"]
/// Valid values | "Mainnet", "Testnet", "Stagenet"
pub network: Network,
/// Enable/disable fast sync.
///
/// Fast sync skips verification of old blocks by comparing block hashes to a built-in hash file,
/// disabling this will significantly increase sync time. New blocks are still fully validated.
/// Fast sync skips verification of old blocks by
/// comparing block hashes to a built-in hash file,
/// disabling this will significantly increase sync time.
/// New blocks are still fully validated.
///
/// Type | boolean
/// Valid values | true, false
pub fast_sync: bool,
#[child = true]
/// The tracing/log output config.
/// Configuration for cuprated's logging system, tracing.
///
/// Tracing is used for logging to stdout and files.
pub tracing: TracingConfig,
#[child = true]
/// The tokio config.
/// Configuration for cuprated's asynchronous runtime system, tokio.
///
/// Tokio is the async threadpool, used for network operations and the major service inside `cuprated`.
/// Tokio is used for network operations and the major services inside `cuprated`.
pub tokio: TokioConfig,
#[child = true]
/// The rayon config.
/// Configuration for cuprated's thread-pool system, rayon.
///
/// Rayon is the CPU threadpool, used for CPU intensive tasks.
/// Rayon is used for CPU intensive tasks.
pub rayon: RayonConfig,
#[child = true]
/// The P2P network config.
/// Configuration for cuprated's P2P system.
pub p2p: P2PConfig,
#[child = true]
/// The storage config.
/// Configuration for persistent data storage.
pub storage: StorageConfig,
#[child = true]
/// The filesystem config.
/// Configuration for the file-system.
pub fs: FileSystemConfig,
}
}

23
binaries/cuprated/src/config/fs.rs
View file

@ -13,10 +13,33 @@ config_struct! {
pub struct FileSystemConfig {
#[comment_out = true]
/// The data directory.
///
/// This directory store the blockchain, transaction pool,
/// log files, and any misc data files.
///
/// The default directories for each OS:
///
/// | OS | Path |
/// |---------|-----------------------------------------------------|
/// | Windows | "C:\Users\Alice\AppData\Roaming\Cuprate\" |
/// | macOS | "/Users/Alice/Library/Application Support/Cuprate/" |
/// | Linux | "/home/alice/.local/share/cuprate/" |
pub data_directory: PathBuf,
#[comment_out = true]
/// The cache directory.
///
/// This directory store cache files.
/// Although not recommended, this directory can be
/// deleted without major disruption to cuprated.
///
/// The default directories for each OS:
///
/// | OS | Path |
/// |---------|-----------------------------------------|
/// | Windows | "C:\Users\Alice\AppData\Local\Cuprate\" |
/// | macOS | "/Users/Alice/Library/Caches/Cuprate/" |
/// | Linux | "/home/alice/.cache/cuprate/" |
pub cache_directory: PathBuf,
}
}

51
binaries/cuprated/src/config/macros.rs
View file

@ -8,6 +8,57 @@ use toml_edit::TableLike;
/// - `#[child = true]`: writes the doc comments for all fields in the child struct.
/// - `#[inline = true]`: inlines the struct into `{}` instead of having a separate `[]` header.
/// - `#[comment_out = true]`: comments out the field.
///
/// # Documentation
/// Consider using the following style when adding documentation:
///
/// ```rust
/// struct Config {
/// /// BRIEF DESCRIPTION.
/// ///
/// /// (optional) LONGER DESCRIPTION.
// ///
/// /// Type | (optional) FIELD TYPE
/// /// Valid values | EXPRESSION REPRESENTING VALID VALUES
/// /// Examples | (optional) A FEW EXAMPLE VALUES
/// field: (),
/// }
/// ```
///
/// For example:
/// ```rust
/// struct Config {
/// /// Enable/disable fast sync.
/// ///
/// /// Fast sync skips verification of old blocks by
/// /// comparing block hashes to a built-in hash file,
/// /// disabling this will significantly increase sync time.
/// /// New blocks are still fully validated.
/// ///
/// /// Type | boolean
/// /// Valid values | true, false
/// fast_sync: bool,
/// }
/// ```
///
/// Language for types:
///
/// | Rust type | Wording used in user-book |
/// |--------------|---------------------------|
/// | bool | boolean
/// | u{8-64} | Number
/// | i{8-64} | Signed number
/// | f{32,64} | Floating point number
/// | str, String | String
/// | enum, struct | `DataStructureName` (e.g. `Duration`) or $DESCRIPTION (e.g. `IP address`)
///
/// If some fields are redundant or unnecessary, do not add them.
///
/// # Field documentation length
/// In order to prevent wrapping/scrollbars in the user book and in editors,
/// add newlines when a documentation line crosses ~70 characters, around this long:
///
/// `----------------------------------------------------------------------`
macro_rules! config_struct {
(
$(#[$meta:meta])*

94
binaries/cuprated/src/config/p2p.rs
View file

@ -32,28 +32,47 @@ config_struct! {
#[serde(deny_unknown_fields, default)]
pub struct BlockDownloaderConfig {
#[comment_out = true]
/// The size in bytes of the buffer between the block downloader and the place which
/// is consuming the downloaded blocks (`cuprated`).
/// The size in bytes of the buffer between the block downloader
/// and the place which is consuming the downloaded blocks (`cuprated`).
///
/// This value is an absolute maximum, once this is reached the block downloader will pause.
/// This value is an absolute maximum,
/// once this is reached the block downloader will pause.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 1_000_000_000, 5_500_000_000, 500_000_000
pub buffer_bytes: usize,
#[comment_out = true]
/// The size of the in progress queue (in bytes) at which we stop requesting more blocks.
/// The size of the in progress queue (in bytes)
/// at which cuprated stops requesting more blocks.
///
/// The value is _NOT_ an absolute maximum, the in progress queue could get much larger. This value
/// is only the value we stop requesting more blocks, if we still have requests in progress we will
/// still accept the response and add the blocks to the queue.
/// The value is _NOT_ an absolute maximum,
/// the in-progress queue could get much larger.
/// This value is only the value cuprated stops requesting more blocks,
/// if cuprated still has requests in progress,
/// it will still accept the response and add the blocks to the queue.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 500_000_000, 1_000_000_000,
pub in_progress_queue_bytes: usize,
#[inline = true]
/// The [`Duration`] between checking the client pool for free peers.
/// The duration between checking the client pool for free peers.
///
/// Type | Duration
/// Examples | { secs = 30, nanos = 0 }, { secs = 35, nano = 123 }
pub check_client_pool_interval: Duration,
#[comment_out = true]
/// The target size of a single batch of blocks (in bytes).
///
/// This value must be below 100_000_000, it is not recommended to set it above 30_000_000.
/// This value must be below 100_000,000,
/// it is not recommended to set it above 30_000_000.
///
/// Type | Number
/// Valid values | 0..100_000,000
pub target_batch_bytes: usize,
}
}
@ -86,7 +105,10 @@ config_struct! {
#[derive(Debug, Deserialize, Serialize, PartialEq)]
#[serde(deny_unknown_fields, default)]
pub struct ClearNetConfig {
/// The IP address we should bind to to listen to connections on.
/// The IP address to bind and listen for connections on.
///
/// Type | IPv4/IPv6 address
/// Examples | "0.0.0.0", "192.168.1.50", "::"
pub listen_on: IpAddr,
#[flatten = true]
@ -113,24 +135,48 @@ config_struct! {
#[comment_out = true]
/// The number of outbound connections to make and try keep.
///
/// Recommended to keep this value above 12.
/// It's recommended to keep this value above 12.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 12, 32, 64, 100, 500
pub outbound_connections: usize,
#[comment_out = true]
/// The amount of extra connections we can make if we are under load from the rest of Cuprate.
/// The amount of extra connections to make if cuprated is under load.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 0, 12, 32, 64, 100, 500
pub extra_outbound_connections: usize,
#[comment_out = true]
/// The maximum amount of inbound connections we should allow.
/// The maximum amount of inbound connections to allow.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 0, 12, 32, 64, 100, 500
pub max_inbound_connections: usize,
#[comment_out = true]
/// The percent of connections that should be to peers we haven't connected to before.
/// The percent of connections that should be
/// to peers that haven't connected to before.
///
/// 0.0 is 0%.
/// 1.0 is 100%.
///
/// Type | Floating point number
/// Valid values | 0.0..1.0
/// Examples | 0.0, 0.5, 0.123, 0.999, 1.0
pub gray_peers_percent: f64,
/// port to use to accept p2p connections.
/// The port to use to accept incoming P2P connections.
///
/// Set to 0 if you do not want to accept P2P connections.
/// Setting this to 0 will disable incoming P2P connections.
///
/// Type | Number
/// Valid values | 0..65534
/// Examples | 18080, 9999, 5432
pub p2p_port: u16,
#[child = true]
@ -175,16 +221,28 @@ config_struct! {
pub struct AddressBookConfig {
/// The size of the white peer list.
///
/// The white list holds peers we have connected to before.
/// The white list holds peers that have been connected to before.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 1000, 500, 241
pub max_white_list_length: usize,
/// The size of the gray peer list.
///
/// The gray peer list holds peers we have been told about but not connected to ourself.
/// The gray peer list holds peers that have been
/// told about but not connected to cuprated.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 1000, 500, 241
pub max_gray_list_length: usize,
#[inline = true]
/// The time period between address book saves.
///
/// Type | Duration
/// Examples | { secs = 90, nanos = 0 }, { secs = 100, nano = 123 }
pub peer_save_period: Duration,
}
}

4
binaries/cuprated/src/config/rayon.rs
View file

@ -8,7 +8,9 @@ config_struct! {
#[serde(deny_unknown_fields, default)]
pub struct RayonConfig {
#[comment_out = true]
/// The number of threads to use for the rayon thread pool.
/// Type | Number
/// Valid values | >= 1
/// Examples | 1, 8, 14
pub threads: usize,
}
}

15
binaries/cuprated/src/config/storage.rs
View file

@ -17,6 +17,10 @@ config_struct! {
/// The amount of reader threads to spawn for the tx-pool and blockchain.
///
/// The tx-pool and blockchain both share a single threadpool.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 1, 16, 10
pub reader_threads: usize,
#[child = true]
@ -62,6 +66,10 @@ config_struct! {
pub shared: SharedStorageConfig,
/// The maximum size of the tx-pool.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 100_000_000, 50_000_000
pub max_txpool_byte_size: usize,
}
}
@ -83,10 +91,11 @@ config_struct! {
#[comment_out = true]
/// The sync mode of the database.
///
/// Changing this value could make the DB a lot slower when writing data, although
/// using "Safe" makes the DB more durable if there was an unexpected crash.
/// Using "Safe" makes the DB less likely to corrupt
/// if there is an unexpected crash, although it will
/// make DB writes much slower.
///
/// Valid values: ["Fast", "Safe"].
/// Valid values | "Fast", "Safe"
pub sync_mode: SyncMode,
}
}

6
binaries/cuprated/src/config/tokio.rs
View file

@ -8,7 +8,11 @@ config_struct! {
#[serde(deny_unknown_fields, default)]
pub struct TokioConfig {
#[comment_out = true]
/// The amount of threads to spawn for the async thread-pool
/// The amount of threads to spawn for the tokio thread-pool.
///
/// Type | Number
/// Valid values | >= 1
/// Examples | 1, 8, 14
pub threads: usize,
}
}

31
binaries/cuprated/src/config/tracing_config.rs
View file

@ -9,11 +9,11 @@ config_struct! {
#[serde(deny_unknown_fields, default)]
pub struct TracingConfig {
#[child = true]
/// The stdout logging config.
/// Configuration for cuprated's stdout logging system.
pub stdout: StdoutTracingConfig,
#[child = true]
/// The file logging config.
/// Configuration for cuprated's file logging system.
pub file: FileTracingConfig,
}
}
@ -22,7 +22,14 @@ config_struct! {
#[derive(Debug, Deserialize, Serialize, Eq, PartialEq)]
#[serde(deny_unknown_fields, default)]
pub struct StdoutTracingConfig {
/// The default minimum log level.
/// The minimum log level for stdout.
///
/// Levels below this one will not be shown.
/// "error" is the highest level only showing errors,
/// "trace" is the lowest showing as much as possible.
///
/// Type | Level
/// Valid values | "error", "warn", "info", "debug", "trace"
##[serde(with = "level_filter_serde")]
pub level: LevelFilter,
}
@ -40,12 +47,24 @@ config_struct! {
#[derive(Debug, Deserialize, Serialize, Eq, PartialEq)]
#[serde(deny_unknown_fields, default)]
pub struct FileTracingConfig {
/// The default minimum log level.
/// The minimum log level for file logs.
///
/// Levels below this one will not be shown.
/// "error" is the highest level only showing errors,
/// "trace" is the lowest showing as much as possible.
///
/// Type | Level
/// Valid values | "error", "warn", "info", "debug", "trace"
##[serde(with = "level_filter_serde")]
pub level: LevelFilter,
/// The maximum amount of log files to keep, once this number is passed the oldest file
/// will be deleted.
/// The maximum amount of log files to keep.
///
/// Once this number is passed the oldest file will be deleted.
///
/// Type | Number
/// Valid values | >= 0
/// Examples | 0, 7, 200
pub max_log_files: usize,
}
}

2
books/user/book.toml
View file

@ -3,7 +3,7 @@ authors = ["hinto-janai"]
language = "en"
multilingual = false
src = "src"
title = "Cuprate User Book - v0.0.1"
title = "Cuprate User Book - v0.0.2"
git-repository-url = "https://github.com/Cuprate/cuprate/books/user"
[output.html]

5
books/user/src/SUMMARY.md
View file

@ -11,6 +11,7 @@
- [Running](getting-started/run.md)
- [Configuration](config.md)
- [Command line](cli.md)
- [Resources](resources/intro.md)
@ -19,4 +20,6 @@
- [IP](resources/ip.md)
- [Platform support](platform.md)
- [License](license.md)
- [License](license.md)
<!-- TODO: - [Glossary](glossary/intro.md) or maybe a wiki? -->

22
books/user/src/cli.md
View file

@ -13,5 +13,23 @@ Usage: `cuprated [OPTIONS]`
| `--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 | |
| `--version` | Print misc version information in JSON | |
| `--help` | Print help | |
## `--version`
The `--version` flag outputs the following info in JSON.
| Field | Type | Description |
|-------------------------|--------|-------------|
| `major_version` | Number | Major version of `cuprated` |
| `minor_version` | Number | Minor version of `cuprated` |
| `patch_version` | Number | Patch version of `cuprated` |
| `rpc_major_version` | Number | Major RPC version (follows `monerod`) |
| `rpc_minor_version` | Number | Minor RPC version (follows `monerod`) |
| `rpc_version` | Number | RPC version (follows `monerod`) |
| `hardfork` | Number | Current hardfork version |
| `blockchain_db_version` | Number | Blockchain database version (separate from `monerod`) |
| `semantic_version` | String | Semantic version of `cuprated` |
| `build` | String | Build of `cuprated`, either `debug` or `release` |
| `commit` | String | `git` commit hash of `cuprated` |
| `killswitch_timestamp` | Number | Timestamp at which `cuprated`'s killswitch activates |

12
books/user/src/getting-started/download.md
View file

@ -1,12 +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).
Cuprate offers pre-built binaries for `cuprated` for the platforms listed in [`Platform support`](../platform.md) **using GitHub CI in a non-reproducible way** for convenience; 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/cuprated-0.0.1/cuprated-0.0.1-windows-x64.zip>
| macOS x86_64 | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.1/cuprated-0.0.1-macos-x64.tar.gz>
| macOS ARM64 | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.1/cuprated-0.0.1-macos-arm64.tar.gz>
| Linux x86_64 (glibc >= 2.36) | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.1/cuprated-0.0.1-linux-x64.tar.gz>
| Linux ARM64 (glibc >= 2.36) | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.1/cuprated-0.0.1-linux-arm64.tar.gz>
| Windows x86_64 | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.2/cuprated-0.0.2-windows-x64.zip>
| macOS x86_64 | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.2/cuprated-0.0.2-macos-x64.tar.gz>
| macOS ARM64 | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.2/cuprated-0.0.2-macos-arm64.tar.gz>
| Linux x86_64 (glibc >= 2.36) | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.2/cuprated-0.0.2-linux-x64.tar.gz>
| Linux ARM64 (glibc >= 2.36) | <https://github.com/Cuprate/cuprate/releases/download/cuprated-0.0.2/cuprated-0.0.2-linux-arm64.tar.gz>
All release files are archived and also available at <https://archive.hinto.rs>.

2
books/user/src/getting-started/source.md
View file

@ -18,7 +18,7 @@ Install the required system dependencies:
```bash
# Debian/Ubuntu
sudo apt install -y build-essentials cmake git
sudo apt install -y build-essential cmake git
# Arch
sudo pacman -Syu base-devel cmake git

2
books/user/src/introduction.md
View file

@ -39,7 +39,7 @@ No.
## 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.
`cuprated` is fine to run for non-serious 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.

4
books/user/src/platform.md
View file

@ -29,6 +29,7 @@ Tier 2 targets can be thought of as "guaranteed to build".
| Target | Notes |
|-----------------------------|--------|
| `x86_64-pc-windows-msvc` | x64 Windows (MSVC, Windows Server 2022+)
| `x86_64-apple-darwin` | x64 macOS
## Tier 3
@ -42,5 +43,4 @@ Official builds are not available, but may eventually be planned.
| `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
| `aarch64-pc-windows-msvc` | ARM64 Windows (MSVC, Windows Server 2022+)

6
books/user/src/resources/ports.md
View file

@ -1,5 +1,7 @@
# 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.
By default, this port is `18080`.
See the [`p2p_port` option in the config file](../config.md) to manually set this port.
Setting the port to `0` will disable incoming P2P connections.