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 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. 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.

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

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]

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:

Although not recommended, this directory can be deleted without major disruption to cuprated.

The files in this directory are:

Configuration

The directory used for files related to configuration is:

The files in this directory are:

Data

The directory used for general data is:

The files in this directory are:

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.

Tier 1

Tier 1 targets can be thought of as "guaranteed to work".

Tier 2

Tier 2 targets can be thought of as "guaranteed to build".

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.

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.