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

Supports both XRPL and Xahau protocols.

Install

pip install xrpld-lab

Quick start

# Standalone Xahau ledger
xrpld-lab up:standalone --protocol xahau

# 3-validator XRPL network (Docker image from rippleci)
xrpld-lab create:network --protocol xrpl --num_validators 3 --num_peers 1

# XRPL network from a custom GitHub branch (local binary)
xrpld-lab create:network \
  --protocol xrpl \
  --build_server "https://github.com/XRPLF/xrpld/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 xahau --local --binary_name xahaud

# Ansible deployment to remote servers
xrpld-lab create:ansible \
  --protocol xahau \
  --build_version 2025.7.9-release+1951 \
  --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 \
  --nodedb_type rwdb --genesis True --quorum 3

Commands

up:standalone -- Create and start a standalone ledger

xrpld-lab up:standalone [OPTIONS]

Option	Default	Description
--protocol	xahau	xrpl or xahau
--version	latest	Build version
--build_type	binary	image or binary
--log_level	trace	warning, debug, trace
--network_id	21339	Network identifier
--nodedb_type	NuDB	NuDB (persistent) or Memory (fast)
--ipfs	false	Include IPFS server
--server	auto	Build server URL
--public_key	default	Validator list public key
--import_key	auto	Import VL key
--config_overrides	none	Path to YAML/JSON config overrides

create:network -- Create a multi-node network

xrpld-lab create:network [OPTIONS]

Option	Default	Description
--protocol	xahau	xrpl or xahau
--num_validators	3	Number of validator nodes
--num_peers	1	Number of peer nodes
--build_version	latest	Build version or commit hash
--build_server	auto	Build server URL or GitHub branch URL
--network_id	21339	Network identifier
--log_level	trace	warning, debug, trace
--genesis	false	Genesis mode
--quorum	n-1	Consensus quorum
--nodedb_type	NuDB	NuDB, Memory, or rwdb
--local	off	Run as native processes (no Docker for nodes)
--binary_name	xrpld	Binary name for local networks
--binary_path	./xrpld	Path to pre-built binary (GitHub URL mode)
--config_overrides	none	Path to YAML/JSON config overrides
--ansible	off	Also generate ansible deployment files
--vips	none	Validator IPs (for ansible)
--pips	none	Peer IPs (for ansible)

Build server modes:

• Xahau: --build_server defaults to https://build.xahau.tech. Downloads binary from server.
• 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 xahau \
  --vips 10.0.0.1 10.0.0.2 10.0.0.3 \
  --pips 10.0.0.4 \
  [OPTIONS]

Option	Default	Description
--vips	required	Validator IP addresses
--pips	required	Peer IP addresses
--ssh_port	20	SSH port for ansible
--ssh_user	ubuntu	SSH user
--ssh_key	~/.ssh/id_rsa	SSH private key path
--ansible_config	none	YAML file with full ansible config (services, etc.)

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.5
    name: infra
    nginx:
      domain: example.com
      ssl_org: MyOrg
    redis: {}
    faucet:
      ws_url: ws://10.0.0.4:6016
      network_id: "21339"
      seed: sEdxxxxxxxxx

deploy:ansible -- Run ansible deployment

xrpld-lab deploy:ansible --name <cluster>

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

Operational commands

xrpld-lab up --name <network>      # Start a network
xrpld-lab down --name <network>    # Stop a network
xrpld-lab remove --name <network>  # Remove a network

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

The merge order is: hardcoded defaults -> repo config (downloaded from GitHub at the build commit) -> your local overrides.

Architecture

xrpld_lab/
  models.py           # Dataclasses: Protocol, NodeConfig, LabConfig, PortSet, etc.
  protocol.py         # ProtocolSpec: all xrpl-vs-xahau differences 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
  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/Transia-RnD/xrpld-lab
cd xrpld-lab
poetry install
poetry run pytest tests/ -v

Current versions

• XRPL: 3.1.1
• Xahau: 2025.7.9-release+1951

License

See repository for license details.