Run a node

From zero to a synced XRP Ledger node.

This page covers everything you need to get xrpld running. Types of nodes, hardware, installation, configuration, monitoring, and the things that tend to go wrong. If you have run blockchain nodes before, most of this will feel familiar. If you have not, it should still be straightforward.

What kind of node are you running

There are three ways to run xrpld, depending on what you need from it.

Non validator node. This is the default and what most people will run. The node connects to the network, downloads the current state, tracks new ledgers as they close, and serves RPC queries. It participates in the peer network by relaying transactions and validations, but it does not vote on consensus. Think of it as a read only window into the ledger with full RPC access. Good for building applications, monitoring the network, or just having your own copy of the state.

Validator node. A validator does everything a non validator does, plus it actively participates in consensus by publishing validation messages. Other nodes on the network can include your validator in their trusted list (UNL), which means your votes count toward closing ledgers. Running a validator is a responsibility. It requires stable uptime, good connectivity, and the trust of the community. The validator code paths exist in xrpld but have not been stress tested under production conditions yet. I would not recommend running one until the community has had more time with the implementation.

Full history node. By default, xrpld keeps a rolling window of recent ledger history and prunes older data automatically. A full history node keeps everything. Every ledger, every transaction, back to the beginning. This requires significantly more disk space (terabytes) and is mainly useful for analytics, research, or serving historical queries. Configure it by setting ledger_history = full in your config and disabling online deletion.

What you need to run it

The node is not lightweight during initial sync. It holds the full state tree in memory while downloading, which means RAM matters more than you might expect for the first few hours. After sync completes and the node is tracking the tip, resource usage drops considerably.

For testnet, 16 GB RAM and a 500 GB SSD will work fine. Mainnet requires 32 GB due to the size of the state tree during initial acquisition.

NVMe is strongly recommended. The NuDB database does a lot of random reads and writes, and spinning disks or even SATA SSDs will bottleneck sync badly. Disk usage grows over time as ledger history accumulates, so plan for headroom.

Supported platforms: Linux x86_64 (Ubuntu 22.04+, Debian 12+, RHEL 9+), macOS arm64 (Apple Silicon), and macOS x86_64.

The interactive installer handles most of it

The fastest way to get running is the installer script. It checks your hardware, installs dependencies, builds the binary, generates config files, and optionally sets up a systemd service. One command:

curl -sSf https://raw.githubusercontent.com/TusharPardhe/xrpld/main/install.sh -o install.sh

chmod +x install.sh

./install.sh

The installer is interactive. It will ask whether you want Docker or a local build, let you configure ports and paths, and warn you if your machine does not meet the minimum requirements. If you prefer to skip the prompts:

./install.sh -y

That runs with all defaults and builds locally.

Manual setup is also straightforward if you prefer doing things yourself. You need Rust 1.90+ and a few system libraries:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Linux dependencies:

sudo apt install build-essential pkg-config libssl-dev librocksdb-dev clang cmake

macOS dependencies:

brew install openssl rocksdb cmake

Clone and build:

git clone https://github.com/TusharPardhe/xrpld.git

cd xrpld

cargo install --path xrpld/main

This installs the binary to ~/.cargo/bin/xrpld, which is already in your PATH if you installed Rust the standard way.

The config is intentionally small

xrpld uses a single config file in INI format. The default one in the repository is minimal on purpose. Here is what a typical non validator setup looks like:

[server]
port_rpc_admin_local
port_peer

[port_rpc_admin_local]
port = 5005
ip = 127.0.0.1
protocol = http

[port_peer]
port = 51235
ip = 0.0.0.0
protocol = peer

[node_size]
medium

[node_db]
type = NuDB
path = /var/lib/xrpld/db/nudb
online_delete = 2000
advisory_delete = 0

[database_path]
/var/lib/xrpld/db

[validators_file]
validators.txt

[ips]
s1.ripple.com 51235
s2.ripple.com 51235

The [node_size] section is the main tuning knob. It controls how aggressively the node acquires ledgers during sync and how much memory it allocates for caches. Options are tiny, small, medium, large, and huge. Start with medium unless you have a specific reason not to.

You also need a validators.txt file alongside your config:

[validator_list_sites]
https://vl.ripple.com

[validator_list_keys]
ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734

This tells the node where to fetch the trusted validator list from. Without it, the node will connect to peers but never advance past the "connected" state because it cannot determine consensus.

Run it, then wait

Start the node with your config file:

RUST_LOG=info xrpld --conf xrpld.cfg

For background operation:

RUST_LOG=info nohup xrpld --conf xrpld.cfg > xrpld.log 2>&1 &

On a Linux server, you probably want a systemd service instead:

[Unit]
Description=XRP Ledger Node (Rust)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=xrpld
Group=xrpld
ExecStart=/usr/local/bin/xrpld --conf /etc/xrpld/xrpld.cfg
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target

Enable it with sudo systemctl enable --now xrpld and it will start automatically on boot.

Initial sync takes time. The node needs to download the entire current state tree from the network, which is millions of nodes. Depending on your hardware and network, expect anywhere from one to several hours before the node reaches the "full" state. This is normal. Every node implementation has a cold start cost.

How to know what the node is doing

The CLI makes this straightforward:

xrpld health

xrpld sync-status

xrpld status

xrpld peers

The node goes through several states during startup: connected (found peers), syncing (downloading state), tracking (almost there), and finally full (fully synced and serving queries). Once you see full, you are good.

You can also hit the RPC directly:

curl -s http://127.0.0.1:5005 -d '{"method":"server_info"}' | jq .result.info.server_state

The things you will use daily

xrpld ships with a built in CLI that auto discovers the local RPC port from your config file. No need to craft JSON manually.

Interactive mode with fuzzy search:

xrpld cli

Account lookup:

xrpld account rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh

Current fee:

xrpld fee

Latest validated ledger:

xrpld ledger

Specific ledger by sequence:

xrpld ledger 95000000

Database disk usage:

xrpld db-stats

Change log level at runtime (no restart needed):

xrpld log-level debug

Raw RPC call with JSON params:

xrpld rpc ledger '{"ledger_index":"validated"}'

Diagnose configuration issues:

xrpld doctor

Graceful shutdown:

xrpld stop

The interactive mode (xrpld cli) is worth trying. It gives you fuzzy search over all available commands with inline descriptions, tab completion, and command history. Useful when you cannot remember the exact name of something.

Things that tend to go wrong

Out of memory during sync. The node holds the full state tree in RAM during initial acquisition. If you have 16 GB or less, it may OOM. Either increase RAM to 32 GB or set [node_size] to small to reduce the concurrent acquisition count. After initial sync completes, memory usage drops significantly.

RocksDB build segfault. The RocksDB C++ library compiles from source by default and can exhaust memory during compilation. Install the system package instead: sudo apt install librocksdb-dev, then rebuild with ROCKSDB_LIB_DIR=/usr/lib/x86_64-linux-gnu cargo install --path xrpld/main.

Node stuck in "connected" state. This almost always means the validator list is not loading. Make sure [validators_file] in your config points to a valid file, or add [validator_list_sites] and [validator_list_keys] directly to your config. Without a trusted validator list, the node cannot determine which validations to trust and will never advance.

Slow sync. Check your disk. Spinning disks and SATA SSDs will bottleneck NuDB operations. NVMe is strongly recommended. Also ensure you have at least 100 Mbps of network bandwidth. If everything is fine hardware wise, consider raising [node_size] to large to increase the parallel acquisition count.

No peers connecting. The peer protocol runs on TCP port 51235 by default. Make sure your firewall allows inbound connections on that port. Check with lsof -i :51235 to confirm the node is actually listening.

Port already in use. Another process is binding the same port. Identify it with lsof -i :51235 or lsof -i :5005 and either stop that process or change the port in your xrpld config.

OpenSSL build failure. Missing system headers. On Ubuntu or Debian: sudo apt install libssl-dev pkg-config. On macOS: brew install openssl.

Linker error from .cargo/config.toml. The repository includes an optional lld linker config for faster builds. If lld is not installed on your system, either install it (sudo apt install lld clang) or remove the file: rm .cargo/config.toml.

When in doubt, run xrpld doctor. It checks common configuration issues and reports what it finds.