diff --git a/binaries/cuprated/src/config.rs b/binaries/cuprated/src/config.rs index 2647cf5bf..d319e24ba 100644 --- a/binaries/cuprated/src/config.rs +++ b/binaries/cuprated/src/config.rs @@ -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: . "; @@ -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, } } diff --git a/binaries/cuprated/src/config/fs.rs b/binaries/cuprated/src/config/fs.rs index 3f96818ef..fa85f7d5b 100644 --- a/binaries/cuprated/src/config/fs.rs +++ b/binaries/cuprated/src/config/fs.rs @@ -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, } } diff --git a/binaries/cuprated/src/config/macros.rs b/binaries/cuprated/src/config/macros.rs index 1818cc28c..c950c0ca2 100644 --- a/binaries/cuprated/src/config/macros.rs +++ b/binaries/cuprated/src/config/macros.rs @@ -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])* diff --git a/binaries/cuprated/src/config/p2p.rs b/binaries/cuprated/src/config/p2p.rs index 725cae3b2..20f66c247 100644 --- a/binaries/cuprated/src/config/p2p.rs +++ b/binaries/cuprated/src/config/p2p.rs @@ -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 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. /// - /// 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. + /// 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. + /// + /// Setting this to 0 will disable incoming P2P connections. /// - /// Set to 0 if you do not want to accept 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, } } diff --git a/binaries/cuprated/src/config/rayon.rs b/binaries/cuprated/src/config/rayon.rs index d30ddbe2b..471506e83 100644 --- a/binaries/cuprated/src/config/rayon.rs +++ b/binaries/cuprated/src/config/rayon.rs @@ -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, } } diff --git a/binaries/cuprated/src/config/storage.rs b/binaries/cuprated/src/config/storage.rs index f3af760c5..f5e997c0f 100644 --- a/binaries/cuprated/src/config/storage.rs +++ b/binaries/cuprated/src/config/storage.rs @@ -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, } } diff --git a/binaries/cuprated/src/config/tokio.rs b/binaries/cuprated/src/config/tokio.rs index 4e2011ab4..89ae25a10 100644 --- a/binaries/cuprated/src/config/tokio.rs +++ b/binaries/cuprated/src/config/tokio.rs @@ -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, } } diff --git a/binaries/cuprated/src/config/tracing_config.rs b/binaries/cuprated/src/config/tracing_config.rs index 0cdd2048c..1a697d96a 100644 --- a/binaries/cuprated/src/config/tracing_config.rs +++ b/binaries/cuprated/src/config/tracing_config.rs @@ -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, } } diff --git a/books/user/book.toml b/books/user/book.toml index e4d661896..200ecb101 100644 --- a/books/user/book.toml +++ b/books/user/book.toml @@ -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] diff --git a/books/user/src/SUMMARY.md b/books/user/src/SUMMARY.md index 6eeb3f579..af7fde9e2 100644 --- a/books/user/src/SUMMARY.md +++ b/books/user/src/SUMMARY.md @@ -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) \ No newline at end of file +- [License](license.md) + + diff --git a/books/user/src/cli.md b/books/user/src/cli.md index 8bb8686c0..72518d791 100644 --- a/books/user/src/cli.md +++ b/books/user/src/cli.md @@ -13,5 +13,23 @@ Usage: `cuprated [OPTIONS]` | `--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 +| `--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 | diff --git a/books/user/src/getting-started/download.md b/books/user/src/getting-started/download.md index a21a9b55a..22266ee23 100644 --- a/books/user/src/getting-started/download.md +++ b/books/user/src/getting-started/download.md @@ -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 | -| macOS x86_64 | -| macOS ARM64 | -| Linux x86_64 (glibc >= 2.36) | -| Linux ARM64 (glibc >= 2.36) | +| Windows x86_64 | +| macOS x86_64 | +| macOS ARM64 | +| Linux x86_64 (glibc >= 2.36) | +| Linux ARM64 (glibc >= 2.36) | All release files are archived and also available at . diff --git a/books/user/src/getting-started/source.md b/books/user/src/getting-started/source.md index cbb10e45d..fb0c45727 100644 --- a/books/user/src/getting-started/source.md +++ b/books/user/src/getting-started/source.md @@ -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 diff --git a/books/user/src/introduction.md b/books/user/src/introduction.md index 6a00e2557..9a225c188 100644 --- a/books/user/src/introduction.md +++ b/books/user/src/introduction.md @@ -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. diff --git a/books/user/src/platform.md b/books/user/src/platform.md index e8888bdae..b4d7d70b4 100644 --- a/books/user/src/platform.md +++ b/books/user/src/platform.md @@ -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+) \ No newline at end of file diff --git a/books/user/src/resources/ports.md b/books/user/src/resources/ports.md index 64684dbfd..47270c405 100644 --- a/books/user/src/resources/ports.md +++ b/books/user/src/resources/ports.md @@ -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. \ No newline at end of file +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. \ No newline at end of file