xrpld-lab

Build xrpld networks and standalone ledgers for testing and development.

What it does

xrpld-lab creates local XRPLD networks using pre-built binaries or Docker images. Instead of building rippled from source inside Docker (slow), you build natively on your machine and deploy to a multi-node network in seconds.

Four deployment modes:

• Standalone -- single-node Docker ledger for quick testing
• Network -- multi-validator Docker cluster with explorer and VL
• Local -- multi-node native processes (no Docker for nodes, fastest iteration)
• Ansible -- generate ansible playbooks for remote server deployment

Install

pip install xrpld-lab

Quick start

# Standalone XRPL ledger
xrpld-lab up:standalone

# 3-validator, 1-peer XRPL network from the rippleci/xrpld release image
xrpld-lab create:network --num_validators 3 --num_peers 1 --genesis True
xrpld-lab up --name 3.3.0-cluster

# XRPL network from a custom GitHub branch (local binary)
xrpld-lab create:network \
  --protocol xrpl \
  --build_server "https://github.com/XRPLF/rippled/tree/xrplf-smart-contracts" \
  --build_version <commit_hash> \
  --num_validators 3 --num_peers 1

# Local network (native processes, no Docker for nodes)
xrpld-lab create:network --protocol xrpl --local

# Ansible deployment to remote servers
xrpld-lab create:ansible \
  --protocol xrpl \
  --build_version 3.3.0 \
  --num_validators 6 --num_peers 2 \
  --vips 10.0.0.1 10.0.0.2 10.0.0.3 10.0.0.4 10.0.0.5 10.0.0.6 \
  --pips 10.0.0.7 10.0.0.8 \
  --genesis True --quorum 3

Commands

up:standalone -- Create and start a standalone ledger

xrpld-lab up:standalone [OPTIONS]

create:network -- Create a multi-node network

xrpld-lab create:network [OPTIONS]

Build server modes:

• XRPL Docker: --build_server defaults to rippleci. Uses Docker image rippleci/xrpld:<version>.
• XRPL GitHub: Pass --build_server "https://github.com/OWNER/repo/tree/branch" with --build_version <commit_hash>. Copies local binary, resolves features from GitHub at that commit.

create:ansible -- Create network with ansible deployment

Generates everything create:network does, plus a complete ansible directory for deploying to remote servers.

xrpld-lab create:ansible \
  --protocol xrpl \
  --vips 10.0.0.1 10.0.0.2 10.0.0.3 \
  --pips 10.0.0.4 \
  [OPTIONS]

Plus all create:network options (protocol, build_server, etc.)

Ansible config file for complex deployments with services:

ssh_port: 22
ssh_user: ubuntu
ssh_key_path: ~/.ssh/id_rsa
vips:
  - 10.0.0.1
  - 10.0.0.2
  - 10.0.0.3
pips:
  - 10.0.0.4
services:
  - ip: 10.0.0.4
    name: infra
    nginx:
      domain: example.com
      ssl_org: MyOrg
    redis: {}
    faucet:
      ws_url: ws://10.0.0.4:6018
      network_id: "1025"
      seed: sEdxxxxxxxxx
    status:
      port: 8687

hosts.txt lists every validator and peer under the nodes group, which the node playbooks (deps.yml, main.yml, clean.yml, alloy.yml, status.yml) target; each services host is its own group, targeted only by its service playbooks. A services host whose IP is not in vips or pips is therefore never touched by a node playbook; one that is also a node sits in both groups (the example host 10.0.0.4 is the peer, which status: and stream: require). vl: requires nginx: on the same host: its vhost is vl.<domain> served by that nginx, and the builder raises ValueError otherwise.

Services bind only where their clients are: redis is published on 127.0.0.1:6379 (the host's status sampler checks it; the debugstream container reaches it by container name over the docker network), and the websocketd log stream binds the default docker bridge address (docker0), which the debugstream container reaches as host.docker.internal and which is not routable from off-host. The debug.<domain> nginx vhost is the public way in.

Status service (status: on the services host, which must be one of the nodes). Every node gets node_metrics.py as the xrpld-status systemd unit: it samples /proc, the admin RPC server_info and the XDGM datagram into a SQLite ring buffer and serves a per-node dashboard plus /api/latest, /api/series, /api/events, /api/health. Each node's [datagram_monitor] is pointed at its own address and the sampler's xdgm_port (default 9999) unless --datagram_monitor names another sink. The services host's sampler also aggregates every node (/api/network, /api/network/health: 200 only when every validator is proposing and every peer full), and its bare-domain nginx vhost serves /status/ (network dashboard), /status/api/ (aggregation) and /status/nodes/<name>/ (each node's dashboard). Samplers on the other nodes bind 0.0.0.0:<port>, admitted by ufw from the services host only. Operators write /opt/xrpld-status/network.json on the services host after a deploy (last_deploy, branches, faucet, vl, amendments); the network page renders it. status.yml re-runs on every deploy; the nginx vhost is a run_once stage, so an existing deployment picks up the new locations with --force or by deleting .done_<host>_nginx.

deploy:ansible -- Run ansible deployment

xrpld-lab deploy:ansible --name <cluster> [--workspace <dir>]

Runs the generated run.sh in the cluster's ansible directory.

Operational commands

Every command below addresses a cluster directory under --workspace (default ./workspace) by --name, given either as <name> or as the full directory name <name>-cluster; both resolve to the same directory. Commands that reach a node over its admin or public RPC take --port_offset, the value the cluster was created with.

xrpld-lab up --name <cluster>                          # Start a network
xrpld-lab down --name <cluster>                        # Stop a network
xrpld-lab remove --name <cluster>                      # Stop with --remove and delete the directory
xrpld-lab update:node --name <cluster> --node_id <N> --node_type validator|peer \
  --build_version <version> (--build_server <url> | --image <image>)
xrpld-lab vote:amendment --name <cluster> --amendment_name <name> [--node_id <N>]
xrpld-lab node:stall --name <cluster> --node_id <N> --node_type validator|peer \
  [--duration_ms <ms> | --clear]
xrpld-lab node:restart --name <cluster> <node_dir> [--genesis]   # e.g. vnode2
xrpld-lab logs:local [--name <cluster>] [--node <node_dir>]
xrpld-lab health --vips <ip>... [--timeout <s>] [--interval <s>]

Config overrides

Override any xrpld config value with a YAML file:

# overrides.yaml
node_size: medium
transaction_queue:
  ledgers_in_queue: 50
  maximum_txn_in_ledger: 5000

xrpld-lab up:standalone --config_overrides overrides.yaml

Overrides apply on top of the generated config, section by section: a mapping merges into the section's keys, a list or a scalar replaces the section, and a section the generated config lacks is appended.

Architecture

xrpld_lab/
  models.py           # Dataclasses: Protocol, NodeConfig, LabConfig, PortSet, etc.
  protocol.py         # ProtocolSpec: protocol-specific defaults in one place
  config_builder.py   # XrpldCfgBuilder + ValidatorsTxtBuilder
  config.py           # INI parsing, YAML overrides, 3-layer merge, ansible config loader
  amendments.py       # C++ feature macro parsing + genesis updates
  source_resolver.py  # GitHub fetch, binary download, feature/config resolution
  node_factory.py     # Creates NodeConfig for validator/peer/standalone
  compose_builder.py  # docker-compose.yml as structured dict
  script_builder.py   # Dockerfiles + start/stop shell scripts
  workflows.py        # LabRunner: orchestrates standalone/network/local/ansible
  cli.py              # Thin CLI: argparse -> LabConfig -> LabRunner.run()
  ansible_builder.py  # Ansible playbooks, inventory, host vars, services
  services/status/    # node_metrics.py sampler + node and network dashboards
  operations.py       # Node updates, amendment enabling, log viewing
  workspace.py        # Path resolution
  utils.py            # File I/O, colors, subprocess helpers

Development

git clone https://github.com/XRPLF/xrpld-lab
cd xrpld-lab
poetry install
poetry run pytest tests

Current versions

• XRPL: 3.3.0

License

ISC. See LICENSE.