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 non-serious 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-05-01T22:17:10.270002Z  INFO incoming_block{height=3402413 txs=66}: Successfully added block hash="e93464a7feea9b472dd734e61574e295f4b8f809c48ff78ef76d12111992ada7"

How big is the database?

As of May 1st 2025, cuprated's database is ~270GB in size.

monerod's database is ~225GB in size.

This is 1.2x larger.

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.

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

Cuprate offers pre-built binaries for cuprated for the platforms listed in Platform support using GitHub CI in a non-reproducible way for convenience; 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-essential 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.

If cuprated is started with no --options, then the configuration used will be equivalent to this config file.

Some values may be different for your exact system, generate the config with cuprated --generate-config to see the defaults for your system.

##     ____                      _
##    / ___|   _ _ __  _ __ __ _| |_ ___
##   | |  | | | | '_ \| '__/ _` | __/ _ \
##   | |__| |_| | |_) | | | (_| | ||  __/
##    \____\__,_| .__/|_|  \__,_|\__\___|
##              |_|
##
## 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>.

## The network cuprated should run on.
##
## Valid values | "Mainnet", "Testnet", "Stagenet"
network = "Mainnet"
## 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 = true

## Configuration for cuprated's stdout logging system.
[tracing.stdout]
## 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"
level = "info"

## Configuration for cuprated's file logging system.
[tracing.file]
## 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"
level = "debug"
## 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
max_log_files = 7

## Configuration for cuprated's asynchronous runtime system, tokio.
##
## Tokio is used for network operations and the major services inside `cuprated`.
[tokio]
## The amount of threads to spawn for the tokio thread-pool.
##
## Type         | Number
## Valid values | >= 1
## Examples     | 1, 8, 14
#threads = 3

## Configuration for cuprated's thread-pool system, rayon.
##
## Rayon is used for CPU intensive tasks.
[rayon]
## Type         | Number
## Valid values | >= 1
## Examples     | 1, 8, 14
#threads = 3

## The clear-net P2P config.
[p2p.clear_net]
## The IP address to bind and listen for connections on.
##
## Type     | IPv4/IPv6 address
## Examples | "0.0.0.0", "192.168.1.50", "::"
listen_on = "0.0.0.0"
## The number of outbound connections to make and try keep.
##
## It's recommended to keep this value above 12.
##
## Type         | Number
## Valid values | >= 0
## Examples     | 12, 32, 64, 100, 500
#outbound_connections = 32
## The amount of extra connections to make if cuprated is under load.
##
## Type         | Number
## Valid values | >= 0
## Examples     | 0, 12, 32, 64, 100, 500
#extra_outbound_connections = 8
## The maximum amount of inbound connections to allow.
##
## Type         | Number
## Valid values | >= 0
## Examples     | 0, 12, 32, 64, 100, 500
#max_inbound_connections = 128
## 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
#gray_peers_percent = 0.7
## The port to use to accept incoming P2P connections.
##
## Setting this to 0 will disable incoming P2P connections.
##
## Type         | Number
## Valid values | 0..65534
## Examples     | 18080, 9999, 5432
p2p_port = 18080

## The address book config.
[p2p.clear_net.address_book_config]
## The size of the white peer list.
##
## The white list holds peers that have been connected to before.
##
## Type         | Number
## Valid values | >= 0
## Examples     | 1000, 500, 241
max_white_list_length = 1000
## The size of the gray peer list.
##
## 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
max_gray_list_length = 5000
## The time period between address book saves.
##
## Type     | Duration
## Examples | { secs = 90, nanos = 0 }, { secs = 100, nano = 123 }
peer_save_period = { secs = 90, nanos = 0 }

## Block downloader config.
##
## The block downloader handles downloading old blocks from peers when we are behind.
[p2p.block_downloader]
## 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.
##
## Type         | Number
## Valid values | >= 0
## Examples     | 1_000_000_000, 5_500_000_000, 500_000_000
#buffer_bytes = 1000000000
## 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.
##
## Type         | Number
## Valid values | >= 0
## Examples     | 500_000_000, 1_000_000_000,
#in_progress_queue_bytes = 500000000
## 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.
##
## Type         | Number
## Valid values | 0..100_000,000
#target_batch_bytes = 15000000
## The duration between checking the client pool for free peers.
##
## Type     | Duration
## Examples | { secs = 30, nanos = 0 }, { secs = 35, nano = 123 }
check_client_pool_interval = { secs = 30, nanos = 0 }

## Configuration for persistent data storage.
[storage]
## 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
#reader_threads = 1

## The tx-pool config.
[storage.txpool]
## The sync mode of the database.
##
## 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"
#sync_mode = "Fast"
## The maximum size of the tx-pool.
##
## Type         | Number
## Valid values | >= 0
## Examples     | 100_000_000, 50_000_000
max_txpool_byte_size = 100000000

## The blockchain config.
[storage.blockchain]
## The sync mode of the database.
##
## 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"
#sync_mode = "Fast"

## Configuration for the file-system.
[fs]
## 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/"                 |
#data_directory = "/home/runner/.local/share/cuprate"
## 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/"           |
#cache_directory = "/home/runner/.cache/cuprate"

Command line

Command line options will override any overlapping config values.

Usage: cuprated [OPTIONS]

--version

The --version flag outputs the following info in JSON.

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 18080. See the p2p_port option in the config file to manually set this port.

Setting the port to 0 will disable incoming P2P connections.

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.

Deployment

This section covers ways of deploying cuprated.

systemd

cuprated can be ran as a systemd service, the below are commands to setup a relatively hardened deployment.

# Create the `cuprate` user
sudo useradd --system --shell /sbin/nologin --home-dir /home/cuprate cuprate

# Move `cuprated` and the config file
# into the appropriate location.
mv cuprated Cuprated.toml /home/cuprate/

# Move the service file to the appropriate location.
sudo mv cuprated.service /etc/systemd/system/

# Start the `cuprated` service.
sudo systemctl daemon-reload
sudo systemctl start cuprated

# (Optional) start `cuprated` upon boot.
sudo systemctl enable cuprated

A relatively hardened systemd service file for cuprated:

## cuprated.service
##
## This file is a relatively hardened systemd
## service for `cuprated`, it:
##
## - requires a `cuprate` user exists
## - restricts filesystem access to `/home/cuprate`
## - requires `/home/cuprate/cuprated`
##   and `/home/cuprate/Cuprated.toml` exist
##
## For service file documentation, see:
## <https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html>

[Unit]
Description=Cuprate Monero Node
StartLimitIntervalSec=300
StartLimitBurst=5

[Service]
## User.
User=cuprate
Group=cuprate
Type=simple

## Max memory.
MemoryAccounting=yes
MemoryHigh=4G
MemoryMax=4G

## Start command.
ExecStart=/home/cuprate/cuprated --config-file /home/cuprate/Cuprated.toml

## Restart every 5s on failure.
KillSignal=SIGINT
Restart=on-failure
RestartSec=5s

## Open file limit.
LimitNOFILE=16384

## On exit, wait 1 minute before sending SIGKILL.
TimeoutStopSec=60s
SendSIGKILL=true

## Restrict filesystem access.
BindPaths=/home/cuprate

## Security hardening.
SystemCallFilter=@system-service
SystemCallFilter=~@privileged @resources

CapabilityBoundingSet=
DeviceAllow=
LockPersonality=true
NoNewPrivileges=true
ProcSubset=pid
RemoveIPC=true
SystemCallArchitectures=native
UMask=0077

PrivateDevices=true
PrivateTmp=true
PrivateUsers=true

ProtectClock=true
ProtectControlGroups=true
ProtectHome=read-only
ProtectHostname=true
ProtectKernelLogs=true
ProtectKernelModules=true
ProtectKernelTunables=true
ProtectProc=invisible
ProtectSystem=strict

RestrictNamespaces=true
RestrictRealtime=true
RestrictSUIDSGID=true

[Install]
WantedBy=multi-user.target

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.