Lux Docs

Netrunner supports custom network topologies to simulate different deployment configurations. Define the connectivity between nodes using a YAML topology file.

Topology File Format

nodes:
  - id: node-0
    role: bootstrap
    connections: [node-1, node-2, node-3, node-4]
  - id: node-1
    connections: [node-0, node-2]
  - id: node-2
    connections: [node-0, node-3]
  - id: node-3
    connections: [node-0, node-4]
  - id: node-4
    connections: [node-0, node-1]
latency: 10ms
bandwidth: 100mbps

Built-in Topologies

Topology	Description	Use Case
`mesh`	Every node connects to every other	Default, best finality
`star`	All nodes connect through a central hub	Test hub failure scenarios
`ring`	Each node connects to two neighbors	Minimal connectivity
`hierarchical`	Tree structure with bootstrap root	Realistic deployment sim

Use a Custom Topology

netrunner control start \
  --number-of-nodes=5 \
  --node-path=/path/to/luxd \
  --topology=my-topology.yaml

Network Conditions

Add realistic network conditions per link:

nodes:
  - id: node-0
    connections:
      - target: node-1
        latency: 5ms
      - target: node-2
        latency: 50ms
      - target: node-3
        latency: 200ms

defaults:
  latency: 10ms
  bandwidth: 100mbps
  packet_loss: 0.1%

Node Roles

Role	Description
`bootstrap`	First node started, other nodes connect to it
`validator`	Normal validator node (default)
`api`	API-only node, no validation
`observer`	Read-only node, no consensus participation

Topology Visualization

After starting a network with a custom topology, view the actual connectivity:

netrunner control status --topology

This displays which nodes are connected and the measured latency between them.