Cuprate is an alternative and independent Monero node implementation that is focused on being fast, user-friendly, and backwards compatible with monerod
.
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
.
FAQ
Frequently asked questions about Cuprate.
Who?
Cuprate was started by SyntheticBird45 in early 2023 and was later joined by boog900, hinto-janai, and other contributors.
A few Cuprate contributors are funded by Monero's Community Crowdfunding System to work on Cuprate and occasionally monerod
.
What is cuprated
?
monerod
is the daemon 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
for information on what system resources cuprated
will use.
What files does cuprated
create?
See Resources/Disk
.
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.
How to see status of cuprated
?
In the terminal running cuprated
, type status
.
Use the help
command 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:
2025-03-01T22:15:52.516944Z INFO incoming_block_batch{start_height=3362022 len=29}: Successfully added block batch
start_height
is the heightcuprated
was previously atlen
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. 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
, although this is not yet available.
In the meanwhile, solutions like 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.
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 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 for more details.
What is the current progress?
See this Reddit thread for a brief report on Cuprate's progress throughout 2024.
Things are always changing so feel free to join our Matrix channel and ask questions.
What is the current roadmap?
See this GitHub issue for Cuprate's rough 2025 roadmap.
Getting started
This section contains information on downloading/building and running cuprated
.
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)
andRaspberry Pi 5 (8 GB RAM)
) - Requires tweaking the config for your system, especially if you are at either extremes of the hardware scale
Download
For convenience, Cuprate offers pre-built binaries for cuprated
for the platforms listed in Platform support
using GitHub CI in a non-reproducible way; it is highly recommended to build cuprated
from source instead, see Building from source
.
All release files are archived and also available at https://archive.hinto.rs.
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 or run:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Linux
Install the required system dependencies:
# 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:
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:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Install the required system dependencies:
brew install cmake
Clone the Cuprate repository and build:
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
.
Running
To run cuprated
:
./cuprated --config-file Cuprated.toml
cuprated
can be ran without a config file although it is recommended to use one; see Configuration
for a default config file.
Configuration
cuprated
reads its configuration file Cuprated.toml
on startup - this is in the TOML 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
Cuprated.toml
This is the default configuration file cuprated
creates and uses, sourced from here.
If cuprated
is started with no --options
, then the configuration used will be equivalent to this config file.
# ____ _
# / ___| _ _ __ _ __ __ _| |_ ___
# | | | | | | '_ \| '__/ _` | __/ _ \
# | |__| |_| | |_) | | | (_| | || __/
# \____\__,_| .__/|_| \__,_|\__\___|
# |_|
#
## The network to run on, valid values: "Mainnet", "Testnet", "Stagenet".
network = "Mainnet"
## Tracing config.
[tracing]
## The stdout logging config.
stdout = { level = "info" }
## The file output logging config.
file = { level = "debug", max_log_files = 7 }
## Clear-net config.
[p2p.clear_net]
## The number of outbound connections we should make and maintain.
outbound_connections = 64
## The number of extra connections we should make under load from the rest of Cuprate, i.e. when syncing.
extra_outbound_connections = 8
## The maximum number of incoming we should allow.
max_inbound_connections = 128
## The percent of outbound connections that should be to nodes we have not connected to before.
gray_peers_percent = 0.7
## The port to accept connections on, if left `0` no connections will be accepted.
p2p_port = 0
## The IP address to listen to connections on.
listen_on = "0.0.0.0"
## The Clear-net addressbook config.
[p2p.clear_net.address_book_config]
## The size of the white peer list, which contains peers we have made a connection to before.
max_white_list_length = 1_000
## The size of the gray peer list, which contains peers we have not made a connection to before.
max_gray_list_length = 5_000
## The amount of time between address book saves.
peer_save_period = { secs = 90, nanos = 0 }
## The block downloader config.
[p2p.block_downloader]
## The size of the buffer of sequential blocks waiting to be verified and added to the chain (bytes).
buffer_bytes = 1_000_000_000
## The size of the queue of blocks which are waiting for a parent block to be downloaded (bytes).
in_progress_queue_bytes = 500_000_000
## The target size of a batch of blocks (bytes), must not exceed 100MB.
target_batch_bytes = 10_000_000
## The amount of time between checking the pool of connected peers for free peers to download blocks.
check_client_pool_interval = { secs = 30, nanos = 0 }
## Txpool storage config.
[storage.txpool]
## The database sync mode for the txpool.
sync_mode = "Fast"
## The maximum size of all the txs in the pool (bytes).
max_txpool_byte_size = 100_000_000
## Blockchain storage config.
[storage.blockchain]
## The database sync mode for the blockchain.
sync_mode = "Fast"
Command line
Command line options will override any overlapping config values.
Usage: cuprated [OPTIONS]
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 |
Resources
This section documents the system resources cuprated
uses.
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:
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 |
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 to manually set this port.
IP
cuprated
currently binds to a single IPv4 address 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 to manually set this IP address.
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"
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 |
License
The cuprated
binary is distributed under the AGPL-3.0 license.
Much of the codebase that makes up cuprated
is under the MIT license.
See also: https://github.com/Cuprate/cuprate/blob/main/LICENSE.