Proposal: Extended VALIDATOR_SPEC Fields for XRPL Validator TOML

[bigcjat]

Proposal: Extended VALIDATOR_SPEC Fields for XRPL Validator TOML

Summary

This proposal suggests extending the current VALIDATOR_SPEC section of XRPL TOML files with structured, explicit hardware and environment fields. The goal is to improve clarity, enable automated parsing, and provide consistent metadata for validator nodes, while maintaining backward compatibility with the existing simple style.

---

Current Status

The current widely-used format for VALIDATOR_SPEC typically uses summary strings for CPU, memory, disk, OS, and connectivity, for example:

[[VALIDATOR_SPEC]]
CPU = "2 x Xeon E5-2667V4 8-Core 3.2 GHz"
MEMORY = "64GB DDR4 2666 Mhz PC4 R"
DISK = "2 x 1TB SSD SATA 6GB/s (RAID 1)"
OS = "Linux"
CONNECTIVITY = "1 Gbps"

While simple, this format:

• Is not machine-parseable without complex string processing
• Omits important details like CPU brand, core count, or disk IOPS
• Lacks guidance on how to measure or collect these values

---

Proposed Extension

Validators SHOULD provide an extended, structured VALIDATOR_SPEC section alongside or instead of the simple format, with the following fields and detailed documentation:

[[VALIDATOR_SPEC]]

Public Key (If more than one validator listed in the toml)

PUBLIC_KEY = "nHBWa56Vr7csoFcCnEPzCCKVvnDQw3L28mATgHYQMGtbEfUjuYyB"

Machine model or name

Examples: "Dell PowerEdge R620", "MacBook Pro 2021", "Raspberry Pi 4"

MACHINE = "Dell PowerEdge R620"

Deployment type / host environment

Examples: "Bare Metal", "Virtualized", "Shared Cloud", "Dedicated Cloud", "Consumer Desktop", "Laptop or mini-form pc", "SBC"

DEPLOYMENT_TYPE = "Bare Metal"

CPU brand, model, count, cores per CPU, clock speed (GHz)

CPU_BRAND = "Intel"
CPU_MODEL = "Xeon E5-2667 v4"
CPU_COUNT = 2
CPU_CORES = 8
CPU_CLOCK_GHZ = 3.20

Memory type, clock speed (MHz), and total amount (GB)

MEMORY_TYPE = "DDR4"
MEMORY_CLOCK_MHZ = 2666
MEMORY_AMOUNT_GB = 64

Disk count, size per drive (TB), type, RAID level, and speed (IOPS)

DISK_QTY = 2
DISK_SIZE_TB = 1
DISK_TYPE = "SSD SATA 6Gb/s"
DISK_RAID = "RAID 1"
DISK_SPEED_IOPS = 95000

Operating system description

OS = "Debian 12"

Network connectivity speed in Gbps

CONNECTIVITY_GBPS = 1

---

Backward Compatibility

Validators MAY continue to provide the simple flat string keys (CPU, MEMORY, DISK, OS, CONNECTIVITY) for compatibility with existing tooling. Parsers SHOULD support both styles gracefully.

---

Guidance for Operators

Operators are encouraged to fill in values accurately. To assist, here are suggested methods to retrieve each value on common operating systems:

• Machine model:

  • Linux: sudo dmidecode -s system-product-name
  • Windows PowerShell: Get-CimInstance -ClassName Win32_ComputerSystem | Select-Object -ExpandProperty Model
  • macOS: sysctl hw.model

• Deployment type: Operator defined (no direct query)

• CPU information:

  • Linux/macOS: lscpu
  • Windows PowerShell: Get-CimInstance Win32_Processor

• Memory:

  • Linux: sudo dmidecode -t memory, free -g
  • Windows: Get-CimInstance Win32_PhysicalMemory
  • macOS: system_profiler SPMemoryDataType

• Disk:

  • Linux: lsblk -d -o NAME,SIZE,ROTA
  • Windows: Get-PhysicalDisk
  • macOS: diskutil list, system_profiler SPStorageDataType
  • RAID: operator-defined or check cat /proc/mdstat (Linux software RAID)

• Disk Speed (IOPS):

  • Prefer manufacturer specs.
  • If unknown, benchmark with minimal background load (stop services like rippled).
  • Tools:
    • Linux/macOS: fio
    • Windows: DiskSpd

• OS:

  • Linux: lsb_release -d or cat /etc/os-release
  • Windows: Get-ComputerInfo
  • macOS: sw_vers

• Connectivity:

  • Linux/macOS: ethtool
  • Windows: Get-NetAdapter

---

Rationale

Providing structured validator hardware metadata:

• Improves transparency and auditability
• Enables tooling to parse and display consistent info
• Helps identify performance characteristics and bottlenecks
• Supports future metrics (e.g., IOPS) with clear guidance

---

Example

[[VALIDATOR_SPEC]]
PUBLIC_KEY = "nHBWa56Vr7csoFcCnEPzCCKVvnDQw3L28mATgHYQMGtbEfUjuYyB"
MACHINE = "Dell PowerEdge R620"
DEPLOYMENT_TYPE = "Bare Metal"
CPU_BRAND = "Intel"
CPU_MODEL = "Xeon E5-2667 v4"
CPU_COUNT = 2
CPU_CORES = 8
CPU_CLOCK_GHZ = 3.20
MEMORY_TYPE = "DDR4"
MEMORY_CLOCK_MHZ = 2666
MEMORY_AMOUNT_GB = 64
DISK_QTY = 2
DISK_SIZE_TB = 1
DISK_TYPE = "SSD SATA 6Gb/s"
DISK_RAID = "RAID 1"
DISK_SPEED_IOPS = 95000
OS = "Debian 12"
CONNECTIVITY_GBPS = 1

---

Thank you for considering this proposal. Feedback and improvements are welcome.

[dangell7]

You should add a bash script to do this for me. If you created a nice toml section in the console from a bash script I would be very very inclined to add it immediately.

[bigcjat]

I agree. I created a python script to do this and a webtool to help build the entire TOML file for those that like to fill out forms.
I will work on a bash script tomorrow, that's much easier to support. Thanks Denis!