Merge branch 'pratik/otel-phase6-statsd' into pratik/otel-phase7-native-metrics

# Conflicts:
#	.codecov.yml
#	.github/scripts/levelization/results/ordering.txt
#	.github/workflows/reusable-clang-tidy-files.yml
#	CMakeLists.txt
#	OpenTelemetryPlan/00-tracing-fundamentals.md
#	OpenTelemetryPlan/01-architecture-analysis.md
#	OpenTelemetryPlan/02-design-decisions.md
#	OpenTelemetryPlan/03-implementation-strategy.md
#	OpenTelemetryPlan/04-code-samples.md
#	OpenTelemetryPlan/05-configuration-reference.md
#	OpenTelemetryPlan/06-implementation-phases.md
#	OpenTelemetryPlan/07-observability-backends.md
#	OpenTelemetryPlan/08-appendix.md
#	OpenTelemetryPlan/09-data-collection-reference.md
#	OpenTelemetryPlan/OpenTelemetryPlan.md
#	OpenTelemetryPlan/POC_taskList.md
#	OpenTelemetryPlan/Phase2_taskList.md
#	OpenTelemetryPlan/Phase3_taskList.md
#	OpenTelemetryPlan/Phase4_taskList.md
#	OpenTelemetryPlan/Phase5_IntegrationTest_taskList.md
#	OpenTelemetryPlan/Phase5_taskList.md
#	OpenTelemetryPlan/presentation.md
#	cfg/xrpld-example.cfg
#	conan.lock
#	conanfile.py
#	cspell.config.yaml
#	docker/telemetry/TESTING.md
#	docker/telemetry/docker-compose.yml
#	docker/telemetry/grafana/dashboards/consensus-health.json
#	docker/telemetry/grafana/dashboards/transaction-overview.json
#	docker/telemetry/grafana/provisioning/dashboards/dashboards.yaml
#	docker/telemetry/grafana/provisioning/datasources/tempo.yaml
#	docker/telemetry/integration-test.sh
#	docker/telemetry/otel-collector-config.yaml
#	docker/telemetry/tempo.yaml
#	docker/telemetry/xrpld-telemetry.cfg
#	docs/build/telemetry.md
#	docs/telemetry-runbook.md
#	include/xrpl/core/ServiceRegistry.h
#	include/xrpl/protocol/detail/features.macro
#	include/xrpl/telemetry/SpanGuard.h
#	include/xrpl/telemetry/Telemetry.h
#	include/xrpl/telemetry/TraceContextPropagator.h
#	src/libxrpl/basics/MallocTrim.cpp
#	src/libxrpl/nodestore/backend/MemoryFactory.cpp
#	src/libxrpl/nodestore/backend/NuDBFactory.cpp
#	src/libxrpl/nodestore/backend/RocksDBFactory.cpp
#	src/libxrpl/telemetry/NullTelemetry.cpp
#	src/libxrpl/telemetry/Telemetry.cpp
#	src/libxrpl/telemetry/TelemetryConfig.cpp
#	src/tests/libxrpl/basics/MallocTrim.cpp
#	src/tests/libxrpl/telemetry/TelemetryConfig.cpp
#	src/xrpld/app/consensus/RCLConsensus.cpp
#	src/xrpld/app/consensus/RCLConsensus.h
#	src/xrpld/app/ledger/detail/BuildLedger.cpp
#	src/xrpld/app/ledger/detail/LedgerMaster.cpp
#	src/xrpld/app/main/Application.cpp
#	src/xrpld/app/misc/NetworkOPs.cpp
#	src/xrpld/consensus/Consensus.h
#	src/xrpld/overlay/detail/PeerImp.cpp
#	src/xrpld/rpc/detail/RPCHandler.cpp
#	src/xrpld/rpc/detail/ServerHandler.cpp

.clang-format

@@ -50,20 +50,21 @@ ForEachMacros: [Q_FOREACH, BOOST_FOREACH]
 IncludeBlocks: Regroup
 IncludeCategories:
   - Regex: "^<(test)/"
-    Priority: 0
-  - Regex: "^<(xrpld)/"
     Priority: 1
-  - Regex: "^<(xrpl)/"
+  - Regex: "^<(xrpld)/"
     Priority: 2
-  - Regex: "^<(boost)/"
+  - Regex: "^<(xrpl)/"
     Priority: 3
-  - Regex: "^.*/"
+  - Regex: "^<(boost)/"
     Priority: 4
-  - Regex: '^.*\.h'
+  - Regex: "^.*/"
     Priority: 5
-  - Regex: ".*"
+  - Regex: '^.*\.h'
     Priority: 6
+  - Regex: ".*"
+    Priority: 7
 IncludeIsMainRegex: "$"
+MainIncludeChar: AngleBracket
 IndentCaseLabels: true
 IndentFunctionDeclarationAfterType: false
 IndentRequiresClause: true

.clang-tidy

@@ -1,4 +1,6 @@
 ---
+# This entire group of checks was applied to all cpp files but not all header files.
+# ---
 Checks: "-*,
   bugprone-argument-comment,
   bugprone-assert-side-effect,
@@ -64,7 +66,7 @@ Checks: "-*,
   bugprone-terminating-continue,
   bugprone-throw-keyword-missing,
   bugprone-too-small-loop-variable,
-  # bugprone-unchecked-optional-access, # see https://github.com/XRPLF/rippled/pull/6502
+  bugprone-unchecked-optional-access,
   bugprone-undefined-memory-manipulation,
   bugprone-undelegated-constructor,
   bugprone-unhandled-exception-at-new,
@@ -85,18 +87,40 @@ Checks: "-*,
   cppcoreguidelines-use-default-member-init,
   cppcoreguidelines-virtual-class-destructor,
   hicpp-ignored-remove-result,
+  misc-const-correctness,
   misc-definitions-in-headers,
   misc-header-include-cycle,
+  misc-include-cleaner,
   misc-misplaced-const,
+  misc-redundant-expression,
   misc-static-assert,
   misc-throw-by-value-catch-by-reference,
   misc-unused-alias-decls,
   misc-unused-using-decls,
-  modernize-deprecated-headers,
+  modernize-concat-nested-namespaces,
   modernize-make-shared,
   modernize-make-unique,
+  modernize-pass-by-value,
+  modernize-type-traits,
+  modernize-use-designated-initializers,
+  modernize-use-emplace,
+  modernize-use-equals-default,
+  modernize-use-equals-delete,
+  modernize-use-nodiscard,
+  modernize-use-override,
+  modernize-use-ranges,
+  modernize-use-starts-ends-with,
+  modernize-use-std-numbers,
+  modernize-use-using,
+  modernize-deprecated-headers,
+  llvm-namespace-comment,
+  performance-faster-string-find,
+  performance-for-range-copy,
   performance-implicit-conversion-in-loop,
+  performance-inefficient-vector-operation,
+  performance-move-const-arg,
   performance-move-constructor-init,
+  performance-no-automatic-move,
   performance-trivially-destructible,
   readability-avoid-nested-conditional-operator,
   readability-avoid-return-with-void-value,
@@ -125,35 +149,11 @@ Checks: "-*,
   readability-use-std-min-max
   "
 # ---
-# checks that have some issues that need to be resolved:
-#
-# llvm-namespace-comment,
-# misc-const-correctness,
-# misc-include-cleaner,
-# misc-redundant-expression,
+# other checks that have issues that need to be resolved:
 #
 # readability-inconsistent-declaration-parameter-name, # in this codebase this check will break a lot of arg names
 # readability-static-accessed-through-instance,        # this check is probably unnecessary. it makes the code less readable
-# readability-identifier-naming,
-#
-# modernize-concat-nested-namespaces,
-# modernize-pass-by-value,
-# modernize-type-traits,
-# modernize-use-designated-initializers,
-# modernize-use-emplace,
-# modernize-use-equals-default,
-# modernize-use-equals-delete,
-# modernize-use-override,
-# modernize-use-ranges,
-# modernize-use-starts-ends-with,
-# modernize-use-std-numbers,
-# modernize-use-using,
-#
-# performance-faster-string-find,
-# performance-for-range-copy,
-# performance-inefficient-vector-operation,
-# performance-move-const-arg,
-# performance-no-automatic-move,
+# readability-identifier-naming,                       # https://github.com/XRPLF/rippled/pull/6571
 # ---
 #
 CheckOptions:
@@ -193,7 +193,8 @@ CheckOptions:
   #   readability-identifier-naming.FunctionIgnoredRegexp: ".*tag_invoke.*"
   bugprone-unsafe-functions.ReportMoreUnsafeFunctions: true
   bugprone-unused-return-value.CheckedReturnTypes: ::std::error_code;::std::error_condition;::std::errc
-#   misc-include-cleaner.IgnoreHeaders: '.*/(detail|impl)/.*;.*(expected|unexpected).*;.*ranges_lower_bound\.h;time.h;stdlib.h;__chrono/.*;fmt/chrono.h;boost/uuid/uuid_hash.hpp'
+  misc-include-cleaner.IgnoreHeaders: ".*/(detail|impl)/.*;.*fwd\\.h(pp)?;time.h;stdlib.h;sqlite3.h;netinet/in\\.h;sys/resource\\.h;sys/sysinfo\\.h;linux/sysinfo\\.h;__chrono/.*;bits/.*;_abort\\.h;boost/uuid/uuid_hash.hpp;boost/beast/core/flat_buffer\\.hpp;boost/beast/http/field\\.hpp;boost/beast/http/dynamic_body\\.hpp;boost/beast/http/message\\.hpp;boost/beast/http/read\\.hpp;boost/beast/http/write\\.hpp;openssl/obj_mac\\.h"
 #
-# HeaderFilterRegex: '^.*/(src|tests)/.*\.(h|hpp)$'
+HeaderFilterRegex: '^.*/(test|xrpl|xrpld)/.*\.(h|hpp)$'
+ExcludeHeaderFilterRegex: '^.*/protocol_autogen/.*\.(h|hpp)$'
 WarningsAsErrors: "*"

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,7 +1,7 @@
 ---
 name: Feature Request
-about: Suggest a new feature for the rippled project
-title: "[Title with short description] (Version: [rippled version])"
+about: Suggest a new feature for the xrpld project
+title: "[Title with short description] (Version: [xrpld version])"
 labels: Feature Request
 assignees: ""
 ---

.github/scripts/check-pr-description.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+
+"""
+Checks that a pull request description has been customized from the
+pull_request_template.md. Exits with code 1 if the description is empty
+or identical to the template (ignoring HTML comments and whitespace).
+
+Usage:
+    python check-pr-description.py --template-file TEMPLATE --pr-body-file BODY
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+def normalize(text: str) -> str:
+    """Strip HTML comments, trim lines, and remove blank lines."""
+    # Remove HTML comments (possibly multi-line)
+    text = re.sub(r"<!--.*?-->", "", text, flags=re.DOTALL)
+    # Strip each line and drop empties
+    lines = [line.strip() for line in text.splitlines()]
+    lines = [line for line in lines if line]
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Check that a PR description differs from the template."
+    )
+    parser.add_argument(
+        "--template-file",
+        type=Path,
+        required=True,
+        help="Path to the pull request template file.",
+    )
+    parser.add_argument(
+        "--pr-body-file",
+        type=Path,
+        required=True,
+        help="Path to a file containing the PR body text.",
+    )
+    args = parser.parse_args()
+
+    template_path: Path = args.template_file
+    pr_body_path: Path = args.pr_body_file
+
+    if not template_path.is_file():
+        print(f"::error::Template file {template_path} not found")
+        return 1
+
+    if not pr_body_path.is_file():
+        print(f"::error::PR body file {pr_body_path} not found")
+        return 1
+
+    template = template_path.read_text(encoding="utf-8")
+    pr_body = pr_body_path.read_text(encoding="utf-8")
+
+    # Check if the PR body is empty or whitespace-only
+    if not pr_body.strip():
+        print(
+            "::error::PR description is empty. "
+            "Please fill in the pull request template."
+        )
+        return 1
+
+    norm_template = normalize(template)
+    norm_pr_body = normalize(pr_body)
+
+    if norm_pr_body == norm_template:
+        print(
+            "::error::PR description (ignoring HTML comments) is identical"
+            " to the template. Please fill in the details of your change."
+            f"\n\nVisible template content:\n---\n{norm_template}\n---"
+            f"\n\nVisible PR description content:\n---\n{norm_pr_body}\n---"
+        )
+        return 1
+
+    print("PR description has been customized from the template.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/levelization/README.md

@@ -1,14 +1,14 @@
 # Levelization
 
-Levelization is the term used to describe efforts to prevent rippled from
+Levelization is the term used to describe efforts to prevent xrpld from
 having or creating cyclic dependencies.
 
-rippled code is organized into directories under `src/xrpld`, `src/libxrpl` (and
+xrpld code is organized into directories under `src/xrpld`, `src/libxrpl` (and
 `src/test`) representing modules. The modules are intended to be
 organized into "tiers" or "levels" such that a module from one level can
 only include code from lower levels. Additionally, a module
 in one level should never include code in an `impl` or `detail` folder of any level
-other than it's own.
+other than its own.
 
 The codebase is split into two main areas:
 
@@ -22,7 +22,7 @@ levelization violations they find (by moving files or individual
 classes). At the very least, don't make things worse.
 
 The table below summarizes the _desired_ division of modules, based on the current
-state of the rippled code. The levels are numbered from
+state of the xrpld code. The levels are numbered from
 the bottom up with the lower level, lower numbered, more independent
 modules listed first, and the higher level, higher numbered modules with
 more dependencies listed later.
@@ -72,10 +72,10 @@ that `test` code should _never_ be included in `xrpl` or `xrpld` code.)
 
 The [levelization](generate.py) script takes no parameters,
 reads no environment variables, and can be run from any directory,
-as long as it is in the expected location in the rippled repo.
+as long as it is in the expected location in the xrpld repo.
 It can be run at any time from within a checked out repo, and will
 do an analysis of all the `#include`s in
-the rippled source. The only caveat is that it runs much slower
+the xrpld source. The only caveat is that it runs much slower
 under Windows than in Linux. It hasn't yet been tested under MacOS.
 It generates many files of [results](results):
 

.github/scripts/levelization/results/loops.txt

@@ -2,19 +2,25 @@ Loop: test.jtx test.toplevel
   test.toplevel > test.jtx
 
 Loop: test.jtx test.unit_test
-  test.unit_test == test.jtx
+  test.unit_test ~= test.jtx
+
+Loop: xrpl.telemetry xrpld.rpc
+  xrpld.rpc > xrpl.telemetry
 
 Loop: xrpld.app xrpld.overlay
-  xrpld.overlay ~= xrpld.app
+  xrpld.app > xrpld.overlay
 
 Loop: xrpld.app xrpld.peerfinder
-  xrpld.peerfinder == xrpld.app
+  xrpld.peerfinder ~= xrpld.app
 
 Loop: xrpld.app xrpld.rpc
   xrpld.rpc > xrpld.app
 
 Loop: xrpld.app xrpld.shamap
-  xrpld.shamap ~= xrpld.app
+  xrpld.shamap > xrpld.app
+
+Loop: xrpld.app xrpld.telemetry
+  xrpld.telemetry ~= xrpld.app
 
 Loop: xrpld.overlay xrpld.rpc
   xrpld.rpc ~= xrpld.overlay

.github/scripts/levelization/results/ordering.txt

@@ -3,13 +3,17 @@ libxrpl.conditions > xrpl.basics
 libxrpl.conditions > xrpl.conditions
 libxrpl.core > xrpl.basics
 libxrpl.core > xrpl.core
+libxrpl.core > xrpl.json
 libxrpl.crypto > xrpl.basics
 libxrpl.json > xrpl.basics
 libxrpl.json > xrpl.json
 libxrpl.ledger > xrpl.basics
 libxrpl.ledger > xrpl.json
 libxrpl.ledger > xrpl.ledger
+libxrpl.ledger > xrpl.nodestore
 libxrpl.ledger > xrpl.protocol
+libxrpl.ledger > xrpl.server
+libxrpl.ledger > xrpl.shamap
 libxrpl.net > xrpl.basics
 libxrpl.net > xrpl.net
 libxrpl.nodestore > xrpl.basics
@@ -19,19 +23,22 @@ libxrpl.nodestore > xrpl.protocol
 libxrpl.protocol > xrpl.basics
 libxrpl.protocol > xrpl.json
 libxrpl.protocol > xrpl.protocol
-libxrpl.protocol_autogen > xrpl.protocol_autogen
 libxrpl.rdb > xrpl.basics
 libxrpl.rdb > xrpl.core
 libxrpl.rdb > xrpl.rdb
 libxrpl.resource > xrpl.basics
 libxrpl.resource > xrpl.json
+libxrpl.resource > xrpl.protocol
 libxrpl.resource > xrpl.resource
 libxrpl.server > xrpl.basics
+libxrpl.server > xrpl.core
 libxrpl.server > xrpl.json
 libxrpl.server > xrpl.protocol
 libxrpl.server > xrpl.rdb
+libxrpl.server > xrpl.resource
 libxrpl.server > xrpl.server
 libxrpl.shamap > xrpl.basics
+libxrpl.shamap > xrpl.nodestore
 libxrpl.shamap > xrpl.protocol
 libxrpl.shamap > xrpl.shamap
 libxrpl.telemetry > xrpl.basics
@@ -45,12 +52,11 @@ libxrpl.tx > xrpl.protocol
 libxrpl.tx > xrpl.server
 libxrpl.tx > xrpl.tx
 test.app > test.jtx
-test.app > test.rpc
-test.app > test.toplevel
 test.app > test.unit_test
 test.app > xrpl.basics
 test.app > xrpl.core
 test.app > xrpld.app
+test.app > xrpld.consensus
 test.app > xrpld.core
 test.app > xrpld.overlay
 test.app > xrpld.rpc
@@ -58,9 +64,9 @@ test.app > xrpl.json
 test.app > xrpl.ledger
 test.app > xrpl.nodestore
 test.app > xrpl.protocol
-test.app > xrpl.rdb
 test.app > xrpl.resource
 test.app > xrpl.server
+test.app > xrpl.shamap
 test.app > xrpl.tx
 test.basics > test.jtx
 test.basics > test.unit_test
@@ -73,21 +79,23 @@ test.beast > xrpl.basics
 test.conditions > xrpl.basics
 test.conditions > xrpl.conditions
 test.consensus > test.csf
+test.consensus > test.jtx
 test.consensus > test.toplevel
 test.consensus > test.unit_test
 test.consensus > xrpl.basics
 test.consensus > xrpld.app
 test.consensus > xrpld.consensus
-test.consensus > xrpl.json
 test.consensus > xrpl.ledger
+test.consensus > xrpl.protocol
+test.consensus > xrpl.shamap
 test.consensus > xrpl.tx
 test.core > test.jtx
-test.core > test.toplevel
 test.core > test.unit_test
 test.core > xrpl.basics
 test.core > xrpl.core
 test.core > xrpld.core
 test.core > xrpl.json
+test.core > xrpl.protocol
 test.core > xrpl.rdb
 test.core > xrpl.server
 test.csf > xrpl.basics
@@ -95,7 +103,6 @@ test.csf > xrpld.consensus
 test.csf > xrpl.json
 test.csf > xrpl.ledger
 test.csf > xrpl.protocol
-test.csf > xrpl.telemetry
 test.json > test.jtx
 test.json > xrpl.json
 test.jtx > xrpl.basics
@@ -111,27 +118,32 @@ test.jtx > xrpl.resource
 test.jtx > xrpl.server
 test.jtx > xrpl.tx
 test.ledger > test.jtx
-test.ledger > test.toplevel
 test.ledger > xrpl.basics
+test.ledger > xrpl.core
+test.ledger > xrpld.app
 test.ledger > xrpld.core
+test.ledger > xrpl.json
 test.ledger > xrpl.ledger
 test.ledger > xrpl.protocol
 test.nodestore > test.jtx
-test.nodestore > test.toplevel
 test.nodestore > test.unit_test
 test.nodestore > xrpl.basics
+test.nodestore > xrpld.core
 test.nodestore > xrpl.nodestore
+test.nodestore > xrpl.protocol
 test.nodestore > xrpl.rdb
 test.overlay > test.jtx
-test.overlay > test.toplevel
 test.overlay > test.unit_test
 test.overlay > xrpl.basics
 test.overlay > xrpld.app
+test.overlay > xrpld.core
 test.overlay > xrpld.overlay
 test.overlay > xrpld.peerfinder
-test.overlay > xrpl.ledger
+test.overlay > xrpl.json
 test.overlay > xrpl.nodestore
 test.overlay > xrpl.protocol
+test.overlay > xrpl.resource
+test.overlay > xrpl.server
 test.overlay > xrpl.shamap
 test.peerfinder > test.beast
 test.peerfinder > test.unit_test
@@ -139,7 +151,7 @@ test.peerfinder > xrpl.basics
 test.peerfinder > xrpld.core
 test.peerfinder > xrpld.peerfinder
 test.peerfinder > xrpl.protocol
-test.protocol > test.toplevel
+test.protocol > test.jtx
 test.protocol > test.unit_test
 test.protocol > xrpl.basics
 test.protocol > xrpl.json
@@ -148,7 +160,6 @@ test.resource > test.unit_test
 test.resource > xrpl.basics
 test.resource > xrpl.resource
 test.rpc > test.jtx
-test.rpc > test.toplevel
 test.rpc > xrpl.basics
 test.rpc > xrpl.core
 test.rpc > xrpld.app
@@ -162,13 +173,12 @@ test.rpc > xrpl.resource
 test.rpc > xrpl.server
 test.rpc > xrpl.tx
 test.server > test.jtx
-test.server > test.toplevel
 test.server > test.unit_test
 test.server > xrpl.basics
 test.server > xrpld.app
 test.server > xrpld.core
-test.server > xrpld.rpc
 test.server > xrpl.json
+test.server > xrpl.protocol
 test.server > xrpl.server
 test.shamap > test.unit_test
 test.shamap > xrpl.basics
@@ -180,7 +190,6 @@ test.toplevel > xrpl.json
 test.unit_test > xrpl.basics
 test.unit_test > xrpl.protocol
 tests.libxrpl > xrpl.basics
-tests.libxrpl > xrpld.telemetry
 tests.libxrpl > xrpl.json
 tests.libxrpl > xrpl.net
 tests.libxrpl > xrpl.protocol
@@ -229,7 +238,6 @@ xrpld.app > xrpl.basics
 xrpld.app > xrpl.core
 xrpld.app > xrpld.consensus
 xrpld.app > xrpld.core
-xrpld.app > xrpld.telemetry
 xrpld.app > xrpl.json
 xrpld.app > xrpl.ledger
 xrpld.app > xrpl.net
@@ -242,27 +250,28 @@ xrpld.app > xrpl.shamap
 xrpld.app > xrpl.telemetry
 xrpld.app > xrpl.tx
 xrpld.consensus > xrpl.basics
-xrpld.consensus > xrpld.telemetry
 xrpld.consensus > xrpl.json
 xrpld.consensus > xrpl.ledger
 xrpld.consensus > xrpl.protocol
 xrpld.consensus > xrpl.telemetry
 xrpld.core > xrpl.basics
 xrpld.core > xrpl.core
-xrpld.core > xrpl.json
 xrpld.core > xrpl.net
 xrpld.core > xrpl.protocol
 xrpld.core > xrpl.rdb
 xrpld.overlay > xrpl.basics
 xrpld.overlay > xrpl.core
+xrpld.overlay > xrpld.consensus
 xrpld.overlay > xrpld.core
 xrpld.overlay > xrpld.peerfinder
 xrpld.overlay > xrpld.telemetry
 xrpld.overlay > xrpl.json
+xrpld.overlay > xrpl.ledger
 xrpld.overlay > xrpl.protocol
-xrpld.overlay > xrpl.rdb
 xrpld.overlay > xrpl.resource
 xrpld.overlay > xrpl.server
+xrpld.overlay > xrpl.shamap
+xrpld.overlay > xrpl.telemetry
 xrpld.overlay > xrpl.tx
 xrpld.peerfinder > xrpl.basics
 xrpld.peerfinder > xrpld.core
@@ -272,10 +281,10 @@ xrpld.perflog > xrpl.basics
 xrpld.perflog > xrpl.core
 xrpld.perflog > xrpld.rpc
 xrpld.perflog > xrpl.json
+xrpld.perflog > xrpl.protocol
 xrpld.rpc > xrpl.basics
 xrpld.rpc > xrpl.core
 xrpld.rpc > xrpld.core
-xrpld.rpc > xrpld.telemetry
 xrpld.rpc > xrpl.json
 xrpld.rpc > xrpl.ledger
 xrpld.rpc > xrpl.net
@@ -284,6 +293,11 @@ xrpld.rpc > xrpl.protocol
 xrpld.rpc > xrpl.rdb
 xrpld.rpc > xrpl.resource
 xrpld.rpc > xrpl.server
+xrpld.rpc > xrpl.shamap
 xrpld.rpc > xrpl.tx
+xrpld.shamap > xrpl.basics
+xrpld.shamap > xrpld.core
+xrpld.shamap > xrpl.protocol
 xrpld.shamap > xrpl.shamap
+xrpld.telemetry > xrpl.basics
 xrpld.telemetry > xrpl.telemetry

.github/scripts/rename/README.md

@@ -1,11 +1,11 @@
 ## Renaming ripple(d) to xrpl(d)
 
 In the initial phases of development of the XRPL, the open source codebase was
-called "rippled" and it remains with that name even today. Today, over 1000
+called "xrpld" and it remains with that name even today. Today, over 1000
 nodes run the application, and code contributions have been submitted by
 developers located around the world. The XRPL community is larger than ever.
 In light of the decentralized and diversified nature of XRPL, we will rename any
-references to `ripple` and `rippled` to `xrpl` and `xrpld`, when appropriate.
+references to `ripple` and `xrpld` to `xrpl` and `xrpld`, when appropriate.
 
 See [here](https://xls.xrpl.org/xls/XLS-0095-rename-rippled-to-xrpld.html) for
 more information.
@@ -22,18 +22,20 @@ run from the repository root.
 2. `.github/scripts/rename/copyright.sh`: This script will remove superfluous
    copyright notices.
 3. `.github/scripts/rename/cmake.sh`: This script will rename all CMake files
-   from `RippleXXX.cmake` or `RippledXXX.cmake` to `XrplXXX.cmake`, and any
-   references to `ripple` and `rippled` (with or without capital letters) to
+   from `RippleXXX.cmake` or `XrpldXXX.cmake` to `XrplXXX.cmake`, and any
+   references to `ripple` and `xrpld` (with or without capital letters) to
    `xrpl` and `xrpld`, respectively. The name of the binary will remain as-is,
    and will only be renamed to `xrpld` by a later script.
 4. `.github/scripts/rename/binary.sh`: This script will rename the binary from
-   `rippled` to `xrpld`, and reverses the symlink so that `rippled` points to
+   `xrpld` to `xrpld`, and reverses the symlink so that `xrpld` points to
    the `xrpld` binary.
 5. `.github/scripts/rename/namespace.sh`: This script will rename the C++
    namespaces from `ripple` to `xrpl`.
 6. `.github/scripts/rename/config.sh`: This script will rename the config from
-   `rippled.cfg` to `xrpld.cfg`, and updating the code accordingly. The old
+   `xrpld.cfg` to `xrpld.cfg`, and updating the code accordingly. The old
    filename will still be accepted.
+7. `.github/scripts/rename/docs.sh`: This script will rename any lingering
+   references of `ripple(d)` to `xrpl(d)` in code, comments, and documentation.
 
 You can run all these scripts from the repository root as follows:
 
@@ -44,4 +46,5 @@ You can run all these scripts from the repository root as follows:
 ./.github/scripts/rename/binary.sh .
 ./.github/scripts/rename/namespace.sh .
 ./.github/scripts/rename/config.sh .
+./.github/scripts/rename/docs.sh .
 ```

.github/scripts/rename/binary.sh

@@ -6,11 +6,11 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-  if ! command -v gsed &> /dev/null; then
-      echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
-      exit 1
-  fi
-  SED_COMMAND=gsed
+    if ! command -v gsed &> /dev/null; then
+        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
+        exit 1
+    fi
+    SED_COMMAND=gsed
 fi
 
 # This script changes the binary name from `rippled` to `xrpld`, and reverses
@@ -29,7 +29,7 @@ if [ ! -d "${DIRECTORY}" ]; then
     echo "Error: Directory '${DIRECTORY}' does not exist."
     exit 1
 fi
-pushd ${DIRECTORY}
+pushd "${DIRECTORY}"
 
 # Remove the binary name override added by the cmake.sh script.
 ${SED_COMMAND} -z -i -E 's@\s+# For the time being.+"rippled"\)@@' cmake/XrplCore.cmake
@@ -49,6 +49,7 @@ ${SED_COMMAND} -i -E 's@ripple/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@xrpld \(`xrpld`\)@xrpld@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' CONTRIBUTING.md
+${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/build/install.md
 
 popd
 echo "Processing complete."

.github/scripts/rename/cmake.sh

@@ -8,16 +8,16 @@ set -e
 SED_COMMAND=sed
 HEAD_COMMAND=head
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-  if ! command -v gsed &> /dev/null; then
-      echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
-      exit 1
-  fi
-  SED_COMMAND=gsed
-  if ! command -v ghead &> /dev/null; then
-      echo "Error: ghead is not installed. Please install it using 'brew install coreutils'."
-      exit 1
-  fi
-  HEAD_COMMAND=ghead
+    if ! command -v gsed &> /dev/null; then
+        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
+        exit 1
+    fi
+    SED_COMMAND=gsed
+    if ! command -v ghead &> /dev/null; then
+        echo "Error: ghead is not installed. Please install it using 'brew install coreutils'."
+        exit 1
+    fi
+    HEAD_COMMAND=ghead
 fi
 
 # This script renames CMake files from `RippleXXX.cmake` or `RippledXXX.cmake`
@@ -38,16 +38,16 @@ if [ ! -d "${DIRECTORY}" ]; then
     echo "Error: Directory '${DIRECTORY}' does not exist."
     exit 1
 fi
-pushd ${DIRECTORY}
+pushd "${DIRECTORY}"
 
 # Rename the files.
 find cmake -type f -name 'Rippled*.cmake' -exec bash -c 'mv "${1}" "${1/Rippled/Xrpl}"' - {} \;
 find cmake -type f -name 'Ripple*.cmake' -exec bash -c 'mv "${1}" "${1/Ripple/Xrpl}"' - {} \;
 if [ -e cmake/xrpl_add_test.cmake ]; then
-  mv cmake/xrpl_add_test.cmake cmake/XrplAddTest.cmake
+    mv cmake/xrpl_add_test.cmake cmake/XrplAddTest.cmake
 fi
 if [ -e include/xrpl/proto/ripple.proto ]; then
-  mv include/xrpl/proto/ripple.proto include/xrpl/proto/xrpl.proto
+    mv include/xrpl/proto/ripple.proto include/xrpl/proto/xrpl.proto
 fi
 
 # Rename inside the files.
@@ -71,14 +71,14 @@ ${SED_COMMAND} -i 's@xrpl/validator-keys-tool@ripple/validator-keys-tool@' cmake
 # Ensure the name of the binary and config remain 'rippled' for now.
 ${SED_COMMAND} -i -E 's/xrpld(-example)?\.cfg/rippled\1.cfg/g' cmake/XrplInstall.cmake
 if grep -q '"xrpld"' cmake/XrplCore.cmake; then
-  # The script has been rerun, so just restore the name of the binary.
-  ${SED_COMMAND} -i 's/"xrpld"/"rippled"/' cmake/XrplCore.cmake
+    # The script has been rerun, so just restore the name of the binary.
+    ${SED_COMMAND} -i 's/"xrpld"/"rippled"/' cmake/XrplCore.cmake
 elif ! grep -q '"rippled"' cmake/XrplCore.cmake; then
-  ${HEAD_COMMAND} -n -1 cmake/XrplCore.cmake > cmake.tmp
-  echo '  # For the time being, we will keep the name of the binary as it was.' >> cmake.tmp
-  echo '  set_target_properties(xrpld PROPERTIES OUTPUT_NAME "rippled")' >> cmake.tmp
-  tail -1 cmake/XrplCore.cmake >> cmake.tmp
-  mv cmake.tmp cmake/XrplCore.cmake
+    ${HEAD_COMMAND} -n -1 cmake/XrplCore.cmake > cmake.tmp
+    echo '  # For the time being, we will keep the name of the binary as it was.' >> cmake.tmp
+    echo '  set_target_properties(xrpld PROPERTIES OUTPUT_NAME "rippled")' >> cmake.tmp
+    tail -1 cmake/XrplCore.cmake >> cmake.tmp
+    mv cmake.tmp cmake/XrplCore.cmake
 fi
 
 # Restore the symlink from 'xrpld' to 'rippled'.

.github/scripts/rename/config.sh

@@ -6,11 +6,11 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-  if ! command -v gsed &> /dev/null; then
-      echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
-      exit 1
-  fi
-  SED_COMMAND=gsed
+    if ! command -v gsed &> /dev/null; then
+        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
+        exit 1
+    fi
+    SED_COMMAND=gsed
 fi
 
 # This script renames the config from `rippled.cfg` to `xrpld.cfg`, and updates
@@ -28,40 +28,39 @@ if [ ! -d "${DIRECTORY}" ]; then
     echo "Error: Directory '${DIRECTORY}' does not exist."
     exit 1
 fi
-pushd ${DIRECTORY}
+pushd "${DIRECTORY}"
 
 # Add the xrpld.cfg to the .gitignore.
 if ! grep -q 'xrpld.cfg' .gitignore; then
-  ${SED_COMMAND} -i '/rippled.cfg/a\
+    ${SED_COMMAND} -i '/rippled.cfg/a\
 /xrpld.cfg' .gitignore
 fi
 
 # Rename the files.
 if [ -e rippled.cfg ]; then
-  mv rippled.cfg xrpld.cfg
+    mv rippled.cfg xrpld.cfg
 fi
 if [ -e cfg/rippled-example.cfg ]; then
-  mv cfg/rippled-example.cfg cfg/xrpld-example.cfg
+    mv cfg/rippled-example.cfg cfg/xrpld-example.cfg
 fi
 
 # Rename inside the files.
 DIRECTORIES=("cfg" "cmake" "include" "src")
 for DIRECTORY in "${DIRECTORIES[@]}"; do
-  echo "Processing directory: ${DIRECTORY}"
+    echo "Processing directory: ${DIRECTORY}"
 
-  find "${DIRECTORY}" -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.ipp" -o -name "*.cpp" -o -name "*.cmake" -o -name "*.txt" -o -name "*.cfg" -o -name "*.md" \) | while read -r FILE; do
-      echo "Processing file: ${FILE}"
-      ${SED_COMMAND} -i -E 's/rippled(-example)?[ .]cfg/xrpld\1.cfg/g' "${FILE}"
-  done
+    find "${DIRECTORY}" -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.ipp" -o -name "*.cpp" -o -name "*.cmake" -o -name "*.txt" -o -name "*.cfg" -o -name "*.md" \) | while read -r FILE; do
+        echo "Processing file: ${FILE}"
+        ${SED_COMMAND} -i -E 's/rippled(-example)?[ .]cfg/xrpld\1.cfg/g' "${FILE}"
+        ${SED_COMMAND} -i 's/rippleConfig/xrpldConfig/g' "${FILE}"
+    done
 done
 ${SED_COMMAND} -i 's/rippled/xrpld/g' cfg/xrpld-example.cfg
 ${SED_COMMAND} -i 's/rippled/xrpld/g' src/test/core/Config_test.cpp
 ${SED_COMMAND} -i 's/ripplevalidators/xrplvalidators/g' src/test/core/Config_test.cpp # cspell: disable-line
-${SED_COMMAND} -i 's/rippleConfig/xrpldConfig/g' src/test/core/Config_test.cpp
 ${SED_COMMAND} -i 's@ripple/@xrpld/@g' src/test/core/Config_test.cpp
 ${SED_COMMAND} -i 's/Rippled/File/g' src/test/core/Config_test.cpp
 
-
 # Restore the old config file name in the code that maintains support for now.
 ${SED_COMMAND} -i 's/configLegacyName = "xrpld.cfg"/configLegacyName = "rippled.cfg"/g' src/xrpld/core/detail/Config.cpp
 

.github/scripts/rename/copyright.sh

@@ -6,11 +6,11 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-  if ! command -v gsed &> /dev/null; then
-      echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
-      exit 1
-  fi
-  SED_COMMAND=gsed
+    if ! command -v gsed &> /dev/null; then
+        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
+        exit 1
+    fi
+    SED_COMMAND=gsed
 fi
 
 # This script removes superfluous copyright notices in source and header files
@@ -31,7 +31,7 @@ if [ ! -d "${DIRECTORY}" ]; then
     echo "Error: Directory '${DIRECTORY}' does not exist."
     exit 1
 fi
-pushd ${DIRECTORY}
+pushd "${DIRECTORY}"
 
 # Prevent sed and echo from removing newlines and tabs in string literals by
 # temporarily replacing them with placeholders. This only affects one file.
@@ -43,56 +43,56 @@ ${SED_COMMAND} -i -E "s@\\\t@${PLACEHOLDER_TAB}@g" src/test/rpc/ValidatorInfo_te
 # Process the include/ and src/ directories.
 DIRECTORIES=("include" "src")
 for DIRECTORY in "${DIRECTORIES[@]}"; do
-  echo "Processing directory: ${DIRECTORY}"
+    echo "Processing directory: ${DIRECTORY}"
 
-  find "${DIRECTORY}" -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.ipp" -o -name "*.cpp" -o -name "*.macro" \) | while read -r FILE; do
-      echo "Processing file: ${FILE}"
-      # Handle the cases where the copyright notice is enclosed in /* ... */
-      # and usually surrounded by //---- and //======.
-      ${SED_COMMAND} -z -i -E 's@^//-------+\n+@@' "${FILE}"
-      ${SED_COMMAND} -z -i -E 's@^.*Copyright.+(Ripple|Bougalis|Falco|Hinnant|Null|Ritchford|XRPLF).+PERFORMANCE OF THIS SOFTWARE\.\n\*/\n+@@' "${FILE}" # cspell: ignore Bougalis Falco Hinnant Ritchford
-      ${SED_COMMAND} -z -i -E 's@^//=======+\n+@@' "${FILE}"
+    find "${DIRECTORY}" -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.ipp" -o -name "*.cpp" -o -name "*.macro" \) | while read -r FILE; do
+        echo "Processing file: ${FILE}"
+        # Handle the cases where the copyright notice is enclosed in /* ... */
+        # and usually surrounded by //---- and //======.
+        ${SED_COMMAND} -z -i -E 's@^//-------+\n+@@' "${FILE}"
+        ${SED_COMMAND} -z -i -E 's@^.*Copyright.+(Ripple|Bougalis|Falco|Hinnant|Null|Ritchford|XRPLF).+PERFORMANCE OF THIS SOFTWARE\.\n\*/\n+@@' "${FILE}" # cspell: ignore Bougalis Falco Hinnant Ritchford
+        ${SED_COMMAND} -z -i -E 's@^//=======+\n+@@' "${FILE}"
 
-      # Handle the cases where the copyright notice is commented out with //.
-      ${SED_COMMAND} -z -i -E 's@^//\n// Copyright.+Falco \(vinnie dot falco at gmail dot com\)\n//\n+@@' "${FILE}" # cspell: ignore Vinnie Falco
-  done
+        # Handle the cases where the copyright notice is commented out with //.
+        ${SED_COMMAND} -z -i -E 's@^//\n// Copyright.+Falco \(vinnie dot falco at gmail dot com\)\n//\n+@@' "${FILE}" # cspell: ignore Vinnie Falco
+    done
 done
 
 # Restore copyright notices that were removed from specific files, without
 # restoring the verbiage that is already present in LICENSE.md. Ensure that if
 # the script is run multiple times, duplicate notices are not added.
 if ! grep -q 'Raw Material Software' include/xrpl/beast/core/CurrentThreadName.h; then
-  echo -e "// Portions of this file are from JUCE (http://www.juce.com).\n// Copyright (c) 2013 - Raw Material Software Ltd.\n// Please visit http://www.juce.com\n\n$(cat include/xrpl/beast/core/CurrentThreadName.h)" > include/xrpl/beast/core/CurrentThreadName.h
+    echo -e "// Portions of this file are from JUCE (http://www.juce.com).\n// Copyright (c) 2013 - Raw Material Software Ltd.\n// Please visit http://www.juce.com\n\n$(cat include/xrpl/beast/core/CurrentThreadName.h)" > include/xrpl/beast/core/CurrentThreadName.h
 fi
 if ! grep -q 'Dev Null' src/test/app/NetworkID_test.cpp; then
-  echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/NetworkID_test.cpp)" > src/test/app/NetworkID_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/NetworkID_test.cpp)" > src/test/app/NetworkID_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/app/tx/apply_test.cpp; then
-  echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/tx/apply_test.cpp)" > src/test/app/tx/apply_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/tx/apply_test.cpp)" > src/test/app/tx/apply_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/rpc/ManifestRPC_test.cpp; then
-  echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ManifestRPC_test.cpp)" > src/test/rpc/ManifestRPC_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ManifestRPC_test.cpp)" > src/test/rpc/ManifestRPC_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/rpc/ValidatorInfo_test.cpp; then
-  echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ValidatorInfo_test.cpp)" > src/test/rpc/ValidatorInfo_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ValidatorInfo_test.cpp)" > src/test/rpc/ValidatorInfo_test.cpp
 fi
-if ! grep -q 'Dev Null' src/xrpld/rpc/handlers/DoManifest.cpp; then
-  echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/DoManifest.cpp)" > src/xrpld/rpc/handlers/DoManifest.cpp
+if ! grep -q 'Dev Null' src/xrpld/rpc/handlers/server_info/Manifest.cpp; then
+    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/server_info/Manifest.cpp)" > src/xrpld/rpc/handlers/server_info/Manifest.cpp
 fi
-if ! grep -q 'Dev Null' src/xrpld/rpc/handlers/ValidatorInfo.cpp; then
-  echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/ValidatorInfo.cpp)" > src/xrpld/rpc/handlers/ValidatorInfo.cpp
+if ! grep -q 'Dev Null' src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp; then
+    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp)" > src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/SlabAllocator.h; then
-  echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/SlabAllocator.h)" > include/xrpl/basics/SlabAllocator.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/SlabAllocator.h)" > include/xrpl/basics/SlabAllocator.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/spinlock.h; then
-  echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/spinlock.h)" > include/xrpl/basics/spinlock.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/spinlock.h)" > include/xrpl/basics/spinlock.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/tagged_integer.h; then
-  echo -e "// Copyright (c) 2014, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/tagged_integer.h)" > include/xrpl/basics/tagged_integer.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2014, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/tagged_integer.h)" > include/xrpl/basics/tagged_integer.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Ritchford' include/xrpl/beast/utility/Zero.h; then
-  echo -e "// Copyright (c) 2014, Tom Ritchford <tom@swirly.com>\n\n$(cat include/xrpl/beast/utility/Zero.h)" > include/xrpl/beast/utility/Zero.h # cspell: ignore Ritchford
+    echo -e "// Copyright (c) 2014, Tom Ritchford <tom@swirly.com>\n\n$(cat include/xrpl/beast/utility/Zero.h)" > include/xrpl/beast/utility/Zero.h # cspell: ignore Ritchford
 fi
 
 # Restore newlines and tabs in string literals in the affected file.

.github/scripts/rename/definitions.sh

@@ -6,11 +6,11 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-  if ! command -v gsed &> /dev/null; then
-      echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
-      exit 1
-  fi
-  SED_COMMAND=gsed
+    if ! command -v gsed &> /dev/null; then
+        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
+        exit 1
+    fi
+    SED_COMMAND=gsed
 fi
 
 # This script renames definitions, such as include guards, in this project.

.github/scripts/rename/docs.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+
+# Exit the script as soon as an error occurs.
+set -e
+
+# On MacOS, ensure that GNU sed is installed and available as `gsed`.
+SED_COMMAND=sed
+if [[ "${OSTYPE}" == 'darwin'* ]]; then
+    if ! command -v gsed &> /dev/null; then
+        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
+        exit 1
+    fi
+    SED_COMMAND=gsed
+fi
+
+# This script renames all remaining references to `ripple` and `rippled` to
+# `xrpl` and `xrpld`, respectively, in code, comments, and documentation.
+# Usage: .github/scripts/rename/docs.sh <repository directory>
+
+if [ "$#" -ne 1 ]; then
+    echo "Usage: $0 <repository directory>"
+    exit 1
+fi
+
+DIRECTORY=$1
+echo "Processing directory: ${DIRECTORY}"
+if [ ! -d "${DIRECTORY}" ]; then
+    echo "Error: Directory '${DIRECTORY}' does not exist."
+    exit 1
+fi
+pushd "${DIRECTORY}"
+
+find . -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.ipp" -o -name "*.cpp" -o -name "*.txt" -o -name "*.cfg" -o -name "*.md" -o -name "*.proto" \) -not -path "./.github/scripts/*" | while read -r FILE; do
+    echo "Processing file: ${FILE}"
+    ${SED_COMMAND} -i 's/rippleLockEscrowMPT/lockEscrowMPT/g' "${FILE}"
+    ${SED_COMMAND} -i 's/rippleUnlockEscrowMPT/unlockEscrowMPT/g' "${FILE}"
+    ${SED_COMMAND} -i 's/rippleCredit/directSendNoFee/g' "${FILE}"
+    ${SED_COMMAND} -i 's/rippleSend/directSendNoLimit/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's@([^/+-])rippled@\1xrpld@g' "${FILE}"
+    ${SED_COMMAND} -i -E 's@([^/+-])Rippled@\1Xrpld@g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/^rippled/xrpld/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/^Rippled/Xrpld/g' "${FILE}"
+    # cspell: disable
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (a|A)ddress/XRPL address/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (a|A)ccount/XRPL account/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (a|A)lgorithm/XRPL algorithm/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (c|C)lient/XRPL client/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (c|C)luster/XRPL cluster/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (c|C)onsensus/XRPL consensus/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (d|D)efault/XRPL default/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (e|E)poch/XRPL epoch/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (f|F)eature/XRPL feature/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (n|N)etwork/XRPL network/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (p|P)ayment/XRPL payment/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (p|P)rotocol/XRPL protocol/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (r|R)epository/XRPL repository/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple RPC/XRPL RPC/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (s|S)erialization/XRPL serialization/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (s|S)erver/XRPL server/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (s|S)pecific/XRPL specific/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple Source/XRPL Source/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (t|T)imestamp/XRPL timestamp/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple uses the consensus/XRPL uses the consensus/g' "${FILE}"
+    ${SED_COMMAND} -i -E 's/(r|R)ipple (v|V)alidator/XRPL validator/g' "${FILE}"
+    # cspell: enable
+    ${SED_COMMAND} -i 's/RippleLib/XrplLib/g' "${FILE}"
+    ${SED_COMMAND} -i 's/ripple-lib/XrplLib/g' "${FILE}"
+    ${SED_COMMAND} -i 's@opt/ripple/@opt/xrpld/@g' "${FILE}"
+    ${SED_COMMAND} -i 's@src/ripple/@src/xrpld/@g' "${FILE}"
+    ${SED_COMMAND} -i 's@ripple/app/@xrpld/app/@g' "${FILE}"
+    ${SED_COMMAND} -i 's@github.com/ripple/rippled@github.com/XRPLF/rippled@g' "${FILE}"
+    ${SED_COMMAND} -i 's/\ba xrpl/an xrpl/g' "${FILE}"
+    ${SED_COMMAND} -i 's/\ba XRPL/an XRPL/g' "${FILE}"
+done
+${SED_COMMAND} -i 's/ripple_libs/xrpl_libs/' BUILD.md
+${SED_COMMAND} -i 's/Ripple integrators/XRPL developers/' README.md
+${SED_COMMAND} -i 's/sanitizer-configuration-for-rippled/sanitizer-configuration-for-xrpld/' docs/build/sanitizers.md
+${SED_COMMAND} -i 's/rippled/xrpld/g' .github/scripts/levelization/README.md
+${SED_COMMAND} -i 's/rippled/xrpld/g' .github/scripts/strategy-matrix/generate.py
+${SED_COMMAND} -i 's@/rippled@/xrpld@g' docs/build/install.md
+${SED_COMMAND} -i 's@github.com/XRPLF/xrpld@github.com/XRPLF/rippled@g' docs/build/install.md
+${SED_COMMAND} -i 's/rippled/xrpld/g' docs/Doxyfile
+${SED_COMMAND} -i 's/ripple_basics/basics/' include/xrpl/basics/CountedObject.h
+${SED_COMMAND} -i 's/<ripple/<xrpl/' include/xrpl/protocol/AccountID.h
+${SED_COMMAND} -i 's/Ripple:/the XRPL:/g' include/xrpl/protocol/SecretKey.h
+${SED_COMMAND} -i 's/Ripple:/the XRPL:/g' include/xrpl/protocol/Seed.h
+${SED_COMMAND} -i 's/ripple/xrpl/g' src/test/README.md
+${SED_COMMAND} -i 's/www.ripple.com/www.xrpl.org/g' src/test/protocol/Seed_test.cpp
+
+# Restore specific changes.
+${SED_COMMAND} -i 's@b5efcc/src/xrpld@b5efcc/src/ripple@' include/xrpl/protocol/README.md
+${SED_COMMAND} -i 's/dbPrefix_ = "xrpldb"/dbPrefix_ = "rippledb"/' src/xrpld/app/misc/SHAMapStoreImp.h # cspell: disable-line
+${SED_COMMAND} -i 's/configLegacyName = "xrpld.cfg"/configLegacyName = "rippled.cfg"/' src/xrpld/core/detail/Config.cpp
+
+popd
+echo "Renaming complete."

.github/scripts/rename/include.sh

@@ -23,8 +23,8 @@ fi
 find "${DIRECTORY}" -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.ipp" \) | while read -r FILE; do
     echo "Processing file: ${FILE}"
     if grep -q "#ifndef XRPL_" "${FILE}"; then
-      echo "Please replace all include guards by #pragma once."
-      exit 1
+        echo "Please replace all include guards by #pragma once."
+        exit 1
     fi
 done
 echo "Checking complete."

.github/scripts/rename/namespace.sh

@@ -6,11 +6,11 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-  if ! command -v gsed &> /dev/null; then
-      echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
-      exit 1
-  fi
-  SED_COMMAND=gsed
+    if ! command -v gsed &> /dev/null; then
+        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
+        exit 1
+    fi
+    SED_COMMAND=gsed
 fi
 
 # This script renames the `ripple` namespace to `xrpl` in this project.
@@ -31,18 +31,19 @@ if [ ! -d "${DIRECTORY}" ]; then
     echo "Error: Directory '${DIRECTORY}' does not exist."
     exit 1
 fi
-pushd ${DIRECTORY}
+pushd "${DIRECTORY}"
 
 DIRECTORIES=("include" "src" "tests")
 for DIRECTORY in "${DIRECTORIES[@]}"; do
-  echo "Processing directory: ${DIRECTORY}"
+    echo "Processing directory: ${DIRECTORY}"
 
-  find "${DIRECTORY}" -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.ipp" -o -name "*.cpp" \) | while read -r FILE; do
-      echo "Processing file: ${FILE}"
-      ${SED_COMMAND} -i 's/namespace ripple/namespace xrpl/g' "${FILE}"
-      ${SED_COMMAND} -i 's/ripple::/xrpl::/g' "${FILE}"
-      ${SED_COMMAND} -i -E 's/(BEAST_DEFINE_TESTSUITE.+)ripple(.+)/\1xrpl\2/g' "${FILE}"
-  done
+    find "${DIRECTORY}" -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.ipp" -o -name "*.cpp" -o -name "*.macro" \) | while read -r FILE; do
+        echo "Processing file: ${FILE}"
+        ${SED_COMMAND} -i 's/namespace ripple/namespace xrpl/g' "${FILE}"
+        ${SED_COMMAND} -i 's/ripple::/xrpl::/g' "${FILE}"
+        ${SED_COMMAND} -i 's/"ripple:/"xrpl::/g' "${FILE}"
+        ${SED_COMMAND} -i -E 's/(BEAST_DEFINE_TESTSUITE.+)ripple(.+)/\1xrpl\2/g' "${FILE}"
+    done
 done
 
 # Special case for NuDBFactory that has ripple twice in the test suite name.

.github/scripts/strategy-matrix/generate.py

@@ -51,20 +51,21 @@ def generate_strategy_matrix(all: bool, config: Config) -> list:
         # Only generate a subset of configurations in PRs.
         if not all:
             # Debian:
-            # - Bookworm using GCC 13: Release on linux/amd64, set the reference
-            #   fee to 500.
-            # - Bookworm using GCC 15: Debug on linux/amd64, enable code
-            #   coverage (which will be done below).
+            # - Bookworm using GCC 13: Debug on linux/amd64, set the reference
+            #   fee to 500 and enable code coverage (which will be done below).
+            # - Bookworm using GCC 15: Debug on linux/amd64, enable Address and
+            #   UB sanitizers (which will be done below).
             # - Bookworm using Clang 16: Debug on linux/amd64, enable voidstar.
             # - Bookworm using Clang 17: Release on linux/amd64, set the
             #   reference fee to 1000.
-            # - Bookworm using Clang 20: Debug on linux/amd64.
+            # - Bookworm using Clang 20: Debug on linux/amd64, enable Address
+            #   and UB sanitizers (which will be done below).
             if os["distro_name"] == "debian":
                 skip = True
                 if os["distro_version"] == "bookworm":
                     if (
                         f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-13"
-                        and build_type == "Release"
+                        and build_type == "Debug"
                         and architecture["platform"] == "linux/amd64"
                     ):
                         cmake_args = f"-DUNIT_TEST_REFERENCE_FEE=500 {cmake_args}"
@@ -193,11 +194,11 @@ def generate_strategy_matrix(all: bool, config: Config) -> list:
         ):
             continue
 
-        # Enable code coverage for Debian Bookworm using GCC 15 in Debug on
-        # linux/amd64
+        # Enable code coverage for Debian Bookworm using GCC 13 in Debug on
+        # linux/amd64.
         if (
             f"{os['distro_name']}-{os['distro_version']}" == "debian-bookworm"
-            and f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-15"
+            and f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-13"
             and build_type == "Debug"
             and architecture["platform"] == "linux/amd64"
         ):
@@ -234,23 +235,39 @@ def generate_strategy_matrix(all: bool, config: Config) -> list:
         # Add the configuration to the list, with the most unique fields first,
         # so that they are easier to identify in the GitHub Actions UI, as long
         # names get truncated.
-        # Add Address and Thread (both coupled with UB) sanitizers for specific bookworm distros.
-        # GCC-Asan rippled-embedded tests are failing because of https://github.com/google/sanitizers/issues/856
-        if (
-            os["distro_version"] == "bookworm"
-            and f"{os['compiler_name']}-{os['compiler_version']}" == "clang-20"
-        ):
-            # Add ASAN + UBSAN configuration.
+        # Add Address and UB sanitizers as separate configurations for specific
+        # bookworm distros. Thread sanitizer is currently disabled (see below).
+        # GCC-Asan xrpld-embedded tests are failing because of https://github.com/google/sanitizers/issues/856
+        if os[
+            "distro_version"
+        ] == "bookworm" and f"{os['compiler_name']}-{os['compiler_version']}" in [
+            "gcc-15",
+            "clang-20",
+        ]:
+            # Add ASAN configuration.
             configurations.append(
                 {
-                    "config_name": config_name + "-asan-ubsan",
+                    "config_name": config_name + "-asan",
                     "cmake_args": cmake_args,
                     "cmake_target": cmake_target,
                     "build_only": build_only,
                     "build_type": build_type,
                     "os": os,
                     "architecture": architecture,
-                    "sanitizers": "address,undefinedbehavior",
+                    "sanitizers": "address",
+                }
+            )
+            # Add UBSAN configuration.
+            configurations.append(
+                {
+                    "config_name": config_name + "-ubsan",
+                    "cmake_args": cmake_args,
+                    "cmake_target": cmake_target,
+                    "build_only": build_only,
+                    "build_type": build_type,
+                    "os": os,
+                    "architecture": architecture,
+                    "sanitizers": "undefinedbehavior",
                 }
             )
             # TSAN is deactivated due to seg faults with latest compilers.

.github/workflows/check-pr-commits.yml

@@ -1,7 +1,7 @@
 name: Check PR commits
 
 on:
-  pull_request:
+  pull_request_target:
 
 # The action needs to have write permissions to post comments on the PR.
 permissions:
@@ -10,4 +10,4 @@ permissions:
 
 jobs:
   check_commits:
-    uses: XRPLF/actions/.github/workflows/check-pr-commits.yml@481048b78b94ac3343d1292b4ef125a813879f2b
+    uses: XRPLF/actions/.github/workflows/check-pr-commits.yml@e2c7f400d1e85ae65dad552fd425169fbacca4a3

.github/workflows/check-pr-description.yml

@@ -0,0 +1,30 @@
+name: Check PR description
+
+on:
+  merge_group:
+    types:
+      - checks_requested
+  pull_request:
+    types: [opened, edited, reopened, synchronize, ready_for_review]
+    branches: [develop]
+
+jobs:
+  check_description:
+    if: ${{ github.event.pull_request.draft != true }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Write PR body to file
+        env:
+          PR_BODY: ${{ github.event.pull_request.body }}
+        if: ${{ github.event_name == 'pull_request' }}
+        run: printenv PR_BODY > pr_body.md
+
+      - name: Check PR description differs from template
+        if: ${{ github.event_name == 'pull_request' }}
+        run: >
+          python .github/scripts/check-pr-description.py
+          --template-file .github/pull_request_template.md
+          --pr-body-file pr_body.md

.github/workflows/check-pr-title.yml

@@ -11,4 +11,4 @@ on:
 jobs:
   check_title:
     if: ${{ github.event.pull_request.draft != true }}
-    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@e2c7f400d1e85ae65dad552fd425169fbacca4a3
+    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@a5d8dd35be543365e90a11358447130c8763871d

.github/workflows/on-pr.yml

@@ -46,7 +46,7 @@ jobs:
         # that Github considers any skipped jobs to have passed, and in
         # turn the required checks as well.
         id: changes
-        uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
         with:
           files: |
             # These paths are unique to `on-pr.yml`.

.github/workflows/pre-commit.yml

@@ -14,7 +14,7 @@ on:
 jobs:
   # Call the workflow in the XRPLF/actions repo that runs the pre-commit hooks.
   run-hooks:
-    uses: XRPLF/actions/.github/workflows/pre-commit.yml@e7896f15cc60d0da1a272c77ee5c4026b424f9c7
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@9307df762265e15c745ddcdb38a581c989f7f349
     with:
       runs_on: ubuntu-latest
       container: '{ "image": "ghcr.io/xrplf/ci/tools-rippled-pre-commit:sha-41ec7c1" }'

.github/workflows/publish-docs.yml

@@ -36,7 +36,7 @@ env:
   BUILD_DIR: build
   # ubuntu-latest has only 2 CPUs for private repositories
   # https://docs.github.com/en/actions/reference/runners/github-hosted-runners#standard-github-hosted-runners-for--private-repositories
-  NPROC_SUBTRACT: ${{ github.event.repository.private && '1' || '2' }}
+  NPROC_SUBTRACT: ${{ github.event.repository.visibility == 'public' && '2' || '1' }}
 
 jobs:
   build:
@@ -47,7 +47,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@2bbc2dc1abeec7bfaa886804ab86871ac201764e
+        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
         with:
           enable_ccache: false
 
@@ -81,13 +81,13 @@ jobs:
           cmake --build . --target docs --parallel ${BUILD_NPROC}
 
       - name: Create documentation artifact
-        if: ${{ github.event_name == 'push' }}
-        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        if: ${{ github.event.repository.visibility == 'public' && github.event_name == 'push' }}
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: ${{ env.BUILD_DIR }}/docs/html
 
   deploy:
-    if: ${{ github.event_name == 'push' }}
+    if: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' }}
     needs: build
     runs-on: ubuntu-latest
     permissions:

.github/workflows/reusable-build-test-config.yml

@@ -107,7 +107,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@2bbc2dc1abeec7bfaa886804ab86871ac201764e
+        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
         with:
           enable_ccache: ${{ inputs.ccache_enabled }}
 
@@ -153,6 +153,32 @@ jobs:
             ${CMAKE_ARGS} \
             ..
 
+      - name: Check protocol autogen files are up-to-date
+        working-directory: ${{ env.BUILD_DIR }}
+        env:
+          MESSAGE: |
+
+            The generated protocol wrapper classes are out of date.
+
+            This typically happens when the macro files or generator scripts
+            have changed but the generated files were not regenerated.
+
+            To fix this:
+              1. Run: cmake --build . --target setup_code_gen
+              2. Run: cmake --build . --target code_gen
+              3. Commit and push the regenerated files
+        run: |
+          set -e
+          cmake --build . --target setup_code_gen
+          cmake --build . --target code_gen
+          DIFF=$(git -C .. status --porcelain -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen)
+          if [ -n "${DIFF}" ]; then
+            echo "::error::Generated protocol files are out of date"
+            git -C .. diff -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen
+            echo "${MESSAGE}"
+            exit 1
+          fi
+
       - name: Build the binary
         working-directory: ${{ env.BUILD_DIR }}
         env:
@@ -166,29 +192,6 @@ jobs:
             --parallel "${BUILD_NPROC}" \
             --target "${CMAKE_TARGET}"
 
-      - name: Check protocol autogen files are up-to-date
-        env:
-          MESSAGE: |
-
-            The generated protocol wrapper classes are out of date.
-
-            This typically happens when your branch is behind develop and
-            the macro files or generator scripts have changed.
-
-            To fix this:
-              1. Update your branch from develop (merge or rebase)
-              2. Build with code generation enabled (XRPL_NO_CODEGEN=OFF)
-              3. Commit and push the regenerated files
-        run: |
-          set -e
-          DIFF=$(git status --porcelain -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen)
-          if [ -n "${DIFF}" ]; then
-            echo "::error::Generated protocol files are out of date"
-            git diff -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen
-            echo "${MESSAGE}"
-            exit 1
-          fi
-
       - name: Show ccache statistics
         if: ${{ inputs.ccache_enabled }}
         run: |
@@ -200,13 +203,29 @@ jobs:
 
       - name: Upload the binary (Linux)
         if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: xrpld-${{ inputs.config_name }}
           path: ${{ env.BUILD_DIR }}/xrpld
           retention-days: 3
           if-no-files-found: error
 
+      - name: Export server definitions
+        if: ${{ runner.os != 'Windows' && !inputs.build_only && env.VOIDSTAR_ENABLED != 'true' }}
+        working-directory: ${{ env.BUILD_DIR }}
+        run: |
+          set -o pipefail
+          ./xrpld --definitions | python3 -m json.tool > server_definitions.json
+
+      - name: Upload server definitions
+        if: ${{ github.event.repository.visibility == 'public' && inputs.config_name == 'debian-bookworm-gcc-13-amd64-release' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: server-definitions
+          path: ${{ env.BUILD_DIR }}/server_definitions.json
+          retention-days: 3
+          if-no-files-found: error
+
       - name: Check linking (Linux)
         if: ${{ runner.os == 'Linux' && env.SANITIZERS_ENABLED == 'false' }}
         working-directory: ${{ env.BUILD_DIR }}

.github/workflows/reusable-check-rename.yml

@@ -33,6 +33,8 @@ jobs:
         run: .github/scripts/rename/config.sh .
       - name: Check include guards
         run: .github/scripts/rename/include.sh .
+      - name: Check documentation
+        run: .github/scripts/rename/docs.sh .
       - name: Check for differences
         env:
           MESSAGE: |

.github/workflows/reusable-clang-tidy-files.yml

@@ -35,7 +35,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@2bbc2dc1abeec7bfaa886804ab86871ac201764e
+        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
         with:
           enable_ccache: false
 
@@ -78,20 +78,33 @@ jobs:
         id: run_clang_tidy
         continue-on-error: true
         env:
-          FILES: ${{ inputs.files }}
+          TARGETS: ${{ inputs.files != '' && inputs.files || 'src tests' }}
         run: |
-          run-clang-tidy -j ${{ steps.nproc.outputs.nproc }} -p "$BUILD_DIR" $FILES 2>&1 | tee clang-tidy-output.txt
+          run-clang-tidy -j ${{ steps.nproc.outputs.nproc }} -p "${BUILD_DIR}" -quiet -fix -allow-no-checks ${TARGETS} 2>&1 | tee clang-tidy-output.txt
 
       - name: Upload clang-tidy output
         if: ${{ github.event.repository.visibility == 'public' && steps.run_clang_tidy.outcome != 'success' }}
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: clang-tidy-results
           path: clang-tidy-output.txt
           retention-days: 30
 
+      - name: Generate git diff
+        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
+        run: |
+          git diff | tee clang-tidy-git-diff.txt
+
+      - name: Upload clang-tidy diff output
+        if: ${{ github.event.repository.visibility == 'public' && steps.run_clang_tidy.outcome != 'success' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: clang-tidy-git-diff
+          path: clang-tidy-git-diff.txt
+          retention-days: 30
+
       - name: Create an issue
-        if: steps.run_clang_tidy.outcome != 'success' && inputs.create_issue_on_failure
+        if: ${{ steps.run_clang_tidy.outcome != 'success' && inputs.create_issue_on_failure }}
         id: create_issue
         shell: bash
         env:
@@ -156,7 +169,7 @@ jobs:
           rm -f create_issue.log issue.md clang-tidy-output.txt
 
       - name: Fail the workflow if clang-tidy failed
-        if: steps.run_clang_tidy.outcome != 'success'
+        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
         run: |
           echo "Clang-tidy check failed!"
           exit 1

.github/workflows/reusable-clang-tidy.yml

@@ -31,7 +31,7 @@ jobs:
 
       - name: Get changed C++ files
         id: changed_files
-        uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
         with:
           files: |
             **/*.cpp
@@ -41,7 +41,7 @@ jobs:
 
       - name: Get changed clang-tidy configuration
         id: changed_clang_tidy
-        uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
+        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
         with:
           files: |
             .clang-tidy

.github/workflows/upload-conan-deps.yml

@@ -70,7 +70,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@2bbc2dc1abeec7bfaa886804ab86871ac201764e
+        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
         with:
           enable_ccache: false
 

.gitignore

@@ -13,6 +13,7 @@
 Debug/
 Release/
 /.build/
+/.venv/
 /build/
 /db/
 /out.txt

.pre-commit-config.yaml

@@ -17,10 +17,25 @@ repos:
         args: [--maxkb=400, --enforce-all]
       - id: trailing-whitespace
       - id: end-of-file-fixer
-      - id: mixed-line-ending
       - id: check-merge-conflict
         args: [--assume-in-merge]
 
+  - repo: local
+    hooks:
+      - id: clang-tidy
+        name: "clang-tidy (enable with: TIDY=1)"
+        entry: ./bin/pre-commit/clang_tidy_check.py
+        language: python
+        types_or: [c++, c]
+        exclude: ^include/xrpl/protocol_autogen
+        pass_filenames: false # script determines the staged files itself
+      - id: fix-include-style
+        name: fix include style
+        entry: ./bin/pre-commit/fix_include_style.py
+        language: python
+        types_or: [c++, c]
+        exclude: ^include/xrpl/protocol_autogen/(transactions|ledger_entries)/
+
   - repo: https://github.com/pre-commit/mirrors-clang-format
     rev: cd481d7b0bfb5c7b3090c21846317f9a8262e891 # frozen: v22.1.0
     hooks:
@@ -38,12 +53,19 @@ repos:
     rev: c2bc67fe8f8f549cc489e00ba8b45aa18ee713b1 # frozen: v3.8.1
     hooks:
       - id: prettier
+        args: [--end-of-line=auto]
 
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: ea488cebbfd88a5f50b8bd95d5c829d0bb76feb8 # frozen: 26.1.0
     hooks:
       - id: black
 
+  - repo: https://github.com/openstack/bashate
+    rev: 5798d24d571676fc407e81df574c1ef57b520f23 # frozen: 2.1.1
+    hooks:
+      - id: bashate
+        args: ["--ignore=E006"]
+
   - repo: https://github.com/streetsidesoftware/cspell-cli
     rev: a42085ade523f591dca134379a595e7859986445 # frozen: v9.7.0
     hooks:

API-CHANGELOG.md

@@ -4,23 +4,23 @@ This changelog is intended to list all updates to the [public API methods](https
 
 For info about how [API versioning](https://xrpl.org/request-formatting.html#api-versioning) works, including examples, please view the [XLS-22d spec](https://github.com/XRPLF/XRPL-Standards/discussions/54). For details about the implementation of API versioning, view the [implementation PR](https://github.com/XRPLF/rippled/pull/3155). API versioning ensures existing integrations and users continue to receive existing behavior, while those that request a higher API version will experience new behavior.
 
-The API version controls the API behavior you see. This includes what properties you see in responses, what parameters you're permitted to send in requests, and so on. You specify the API version in each of your requests. When a breaking change is introduced to the `rippled` API, a new version is released. To avoid breaking your code, you should set (or increase) your version when you're ready to upgrade.
+The API version controls the API behavior you see. This includes what properties you see in responses, what parameters you're permitted to send in requests, and so on. You specify the API version in each of your requests. When a breaking change is introduced to the `xrpld` API, a new version is released. To avoid breaking your code, you should set (or increase) your version when you're ready to upgrade.
 
 The [commandline](https://xrpl.org/docs/references/http-websocket-apis/api-conventions/request-formatting/#commandline-format) always uses the latest API version. The command line is intended for ad-hoc usage by humans, not programs or automated scripts. The command line is not meant for use in production code.
 
-For a log of breaking changes, see the **API Version [number]** headings. In general, breaking changes are associated with a particular API Version number. For non-breaking changes, scroll to the **XRP Ledger version [x.y.z]** headings. Non-breaking changes are associated with a particular XRP Ledger (`rippled`) release.
+For a log of breaking changes, see the **API Version [number]** headings. In general, breaking changes are associated with a particular API Version number. For non-breaking changes, scroll to the **XRP Ledger version [x.y.z]** headings. Non-breaking changes are associated with a particular XRP Ledger (`xrpld`) release.
 
 ## API Version 3 (Beta)
 
-API version 3 is currently a beta API. It requires enabling `[beta_rpc_api]` in the rippled configuration to use. See [API-VERSION-3.md](API-VERSION-3.md) for the full list of changes in API version 3.
+API version 3 is currently a beta API. It requires enabling `[beta_rpc_api]` in the xrpld configuration to use. See [API-VERSION-3.md](API-VERSION-3.md) for the full list of changes in API version 3.
 
 ## API Version 2
 
-API version 2 is available in `rippled` version 2.0.0 and later. See [API-VERSION-2.md](API-VERSION-2.md) for the full list of changes in API version 2.
+API version 2 is available in `xrpld` version 2.0.0 and later. See [API-VERSION-2.md](API-VERSION-2.md) for the full list of changes in API version 2.
 
 ## API Version 1
 
-This version is supported by all `rippled` versions. For WebSocket and HTTP JSON-RPC requests, it is currently the default API version used when no `api_version` is specified.
+This version is supported by all `xrpld` versions. For WebSocket and HTTP JSON-RPC requests, it is currently the default API version used when no `api_version` is specified.
 
 ## Unreleased
 
@@ -38,6 +38,8 @@ This section contains changes targeting a future version.
 ### Bugfixes
 
 - Peer Crawler: The `port` field in `overlay.active[]` now consistently returns an integer instead of a string for outbound peers. [#6318](https://github.com/XRPLF/rippled/pull/6318)
+- `ping`: The `ip` field is no longer returned as an empty string for proxied connections without a forwarded-for header. It is now omitted, consistent with the behavior for identified connections. [#6730](https://github.com/XRPLF/rippled/pull/6730)
+- gRPC `GetLedgerDiff`: Fixed error message that incorrectly said "base ledger not validated" when the desired ledger was not validated. [#6730](https://github.com/XRPLF/rippled/pull/6730)
 
 ## XRP Ledger server version 3.1.0
 

API-VERSION-2.md

@@ -1,6 +1,6 @@
 # API Version 2
 
-API version 2 is available in `rippled` version 2.0.0 and later. To use this API, clients specify `"api_version" : 2` in each request.
+API version 2 is available in `xrpld` version 2.0.0 and later. To use this API, clients specify `"api_version" : 2` in each request.
 
 For info about how [API versioning](https://xrpl.org/request-formatting.html#api-versioning) works, including examples, please view the [XLS-22d spec](https://github.com/XRPLF/XRPL-Standards/discussions/54). For details about the implementation of API versioning, view the [implementation PR](https://github.com/XRPLF/rippled/pull/3155). API versioning ensures existing integrations and users continue to receive existing behavior, while those that request a higher API version will experience new behavior.
 

API-VERSION-3.md

@@ -1,6 +1,6 @@
 # API Version 3
 
-API version 3 is currently a **beta API**. It requires enabling `[beta_rpc_api]` in the rippled configuration to use. To use this API, clients specify `"api_version" : 3` in each request.
+API version 3 is currently a **beta API**. It requires enabling `[beta_rpc_api]` in the xrpld configuration to use. To use this API, clients specify `"api_version" : 3` in each request.
 
 For info about how [API versioning](https://xrpl.org/request-formatting.html#api-versioning) works, including examples, please view the [XLS-22d spec](https://github.com/XRPLF/XRPL-Standards/discussions/54). For details about the implementation of API versioning, view the [implementation PR](https://github.com/XRPLF/rippled/pull/3155). API versioning ensures existing integrations and users continue to receive existing behavior, while those that request a higher API version will experience new behavior.
 

BUILD.md

@@ -141,7 +141,7 @@ Alternatively, you can pull our recipes from the repository and export them loca
 
 ```bash
 # Define which recipes to export.
-recipes=('abseil' 'ed25519' 'grpc' 'm4' 'mpt-crypto' 'nudb' 'openssl' 'secp256k1' 'snappy' 'soci' 'wasm-xrplf' 'wasmi')
+recipes=('abseil' 'ed25519' 'grpc' 'm4' 'mpt-crypto' 'openssl' 'secp256k1' 'snappy' 'soci' 'wasm-xrplf' 'wasmi')
 
 # Selectively check out the recipes from our CCI fork.
 cd external
@@ -459,6 +459,21 @@ install ccache --version 4.11.3 --allow-downgrade`.
    The location of `xrpld` binary in your build directory depends on your
    CMake generator. Pass `--help` to see the rest of the command line options.
 
+## Code generation
+
+The protocol wrapper classes in `include/xrpl/protocol_autogen/` are generated
+from macro definition files in `include/xrpl/protocol/detail/`. If you modify
+the macro files (e.g. `transactions.macro`, `ledger_entries.macro`) or the
+generation scripts/templates in `cmake/scripts/codegen/`, you need to regenerate the
+files:
+
+```
+cmake --build . --target setup_code_gen  # create venv and install dependencies (once)
+cmake --build . --target code_gen        # regenerate code
+```
+
+The regenerated files should be committed alongside your changes.
+
 ## Coverage report
 
 The coverage report is intended for developers using compilers GCC
@@ -603,8 +618,8 @@ If you want to experiment with a new package, follow these steps:
      `default_options` property (with syntax `'$package:$option': $value`).
 3. Modify [`CMakeLists.txt`](./CMakeLists.txt):
    - Add a call to `find_package($package REQUIRED)`.
-   - Link a library from the package to the target `ripple_libs`
-     (search for the existing call to `target_link_libraries(ripple_libs INTERFACE ...)`).
+   - Link a library from the package to the target `xrpl_libs`
+     (search for the existing call to `target_link_libraries(xrpl_libs INTERFACE ...)`).
 4. Start coding! Don't forget to include whatever headers you need from the package.
 
 [1]: https://github.com/conan-io/conan-center-index/issues/13168

CMakeLists.txt

@@ -119,7 +119,7 @@ endif()
 
 # OpenTelemetry distributed tracing (optional).
 # When ON, links against opentelemetry-cpp and defines XRPL_ENABLE_TELEMETRY
-# so that tracing macros in TracingInstrumentation.h are compiled in.
+# so that SpanGuard factory methods produce real OTel spans.
 # When OFF (default), all tracing code compiles to no-ops with zero overhead.
 # Enable via: conan install -o telemetry=True, or cmake -Dtelemetry=ON.
 option(telemetry "Enable OpenTelemetry tracing" OFF)
@@ -144,6 +144,7 @@ if(coverage)
 endif()
 
 include(XrplCore)
+include(XrplProtocolAutogen)
 include(XrplInstall)
 include(XrplValidatorKeys)
 

CONTRIBUTING.md

@@ -267,17 +267,37 @@ See the [environment setup guide](./docs/build/environment.md#clang-tidy) for pl
 
 Before running clang-tidy, you must build the project to generate required files (particularly protobuf headers). Refer to [`BUILD.md`](./BUILD.md) for build instructions.
 
+#### Via pre-commit (recommended)
+
+If you have already installed the pre-commit hooks (see above), you can run clang-tidy on your staged files using:
+
+```
+TIDY=1 pre-commit run clang-tidy
+```
+
+This runs clang-tidy locally with the same configuration/flags as CI, scoped to your staged C++ files. The `TIDY=1` environment variable is required to opt in — without it the hook is skipped.
+
+You can also have clang-tidy run automatically on every `git commit` by setting `TIDY=1` in your shell environment:
+
+```
+export TIDY=1
+```
+
+With this set, the hook will run as part of `git commit` alongside the other pre-commit checks.
+
+#### Manually
+
 Then run clang-tidy on your local changes:
 
 ```
-run-clang-tidy -p build src include tests
+run-clang-tidy -p build -allow-no-checks src tests
 ```
 
 This will check all source files in the `src`, `include` and `tests` directories using the compile commands from your `build` directory.
 If you wish to automatically fix whatever clang-tidy finds _and_ is capable of fixing, add `-fix` to the above command:
 
 ```
-run-clang-tidy -p build -fix src include tests
+run-clang-tidy -p build -quiet -fix -allow-no-checks src tests
 ```
 
 ## Contracts and instrumentation
@@ -533,7 +553,7 @@ All releases, including release candidates and betas, are handled
 differently from typical PRs. Most importantly, never use
 the Github UI to merge a release.
 
-Rippled uses a linear workflow model that can be summarized as:
+Xrpld uses a linear workflow model that can be summarized as:
 
 1. In between releases, developers work against the `develop` branch.
 2. Periodically, a maintainer will build and tag a beta version from

OpenTelemetryPlan/00-tracing-fundamentals.md

@@ -406,7 +406,7 @@ flowchart TB
 
 ## Distributed Traces Across Nodes
 
-In distributed systems like rippled, traces span **multiple independent nodes**. The trace context must be propagated in network messages:
+In distributed systems like xrpld, traces span **multiple independent nodes**. The trace context must be propagated in network messages:
 
 ```mermaid
 sequenceDiagram
@@ -492,7 +492,7 @@ traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
              └── Version
 ```
 
-### Protocol Buffers (rippled P2P messages)
+### Protocol Buffers (xrpld P2P messages)
 
 ```protobuf
 message TMTransaction {
@@ -534,7 +534,7 @@ Trace completes → Collector evaluates:
 
 ---
 
-## Key Benefits for rippled
+## Key Benefits for xrpld
 
 | Challenge                          | How Tracing Helps                        |
 | ---------------------------------- | ---------------------------------------- |

OpenTelemetryPlan/01-architecture-analysis.md

@@ -5,15 +5,15 @@
 
 ---
 
-## 1.1 Current rippled Architecture Overview
+## 1.1 Current xrpld Architecture Overview
 
 > **WS** = WebSocket | **UNL** = Unique Node List | **TxQ** = Transaction Queue | **StatsD** = Statistics Daemon
 
-The rippled node software consists of several interconnected components that need instrumentation for distributed tracing:
+The xrpld node software consists of several interconnected components that need instrumentation for distributed tracing:
 
 ```mermaid
 flowchart TB
-    subgraph rippled["rippled Node"]
+    subgraph xrpld["xrpld Node"]
         subgraph services["Core Services"]
             RPC["RPC Server<br/>(HTTP/WS/gRPC)"]
             Overlay["Overlay<br/>(P2P Network)"]
@@ -47,7 +47,7 @@ flowchart TB
         JobQueue --> appservices
     end
 
-    style rippled fill:#424242,stroke:#212121,color:#ffffff
+    style xrpld fill:#424242,stroke:#212121,color:#ffffff
     style services fill:#1565c0,stroke:#0d47a1,color:#ffffff
     style processing fill:#2e7d32,stroke:#1b5e20,color:#ffffff
     style appservices fill:#6a1b9a,stroke:#4a148c,color:#ffffff
@@ -56,7 +56,7 @@ flowchart TB
 
 **Reading the diagram:**
 
-- **Core Services (blue)**: The entry points into rippled -- RPC Server handles client requests, Overlay manages peer-to-peer networking, Consensus drives agreement, and ValidatorList manages trusted validators.
+- **Core Services (blue)**: The entry points into xrpld -- RPC Server handles client requests, Overlay manages peer-to-peer networking, Consensus drives agreement, and ValidatorList manages trusted validators.
 - **JobQueue (center)**: The asynchronous thread pool that decouples Core Services from the Processing and Application layers. All work flows through it.
 - **Processing Layer (green)**: Core business logic -- NetworkOPs processes transactions, LedgerMaster manages ledger state, NodeStore handles persistence, and InboundLedgers synchronizes missing data.
 - **Application Services (purple)**: Higher-level features -- PathFinding computes payment routes, TxQ manages fee-based queuing, and LoadManager tracks server load.
@@ -71,7 +71,7 @@ flowchart TB
 
 | Who (Plain English)                       | Technical Term             |
 | ----------------------------------------- | -------------------------- |
-| Network node running XRPL software        | rippled node               |
+| Network node running XRPL software        | xrpld node                 |
 | External client submitting requests       | RPC Client                 |
 | Network neighbor sharing data             | Peer (PeerImp)             |
 | Request handler for client queries        | RPC Server (ServerHandler) |
@@ -354,17 +354,17 @@ After implementing OpenTelemetry, operators and developers will gain visibility
 
 ### 1.8.1 What You Will See: Traces
 
-| Trace Type                 | Description                                                                                 | Example Query in Grafana/Tempo                         |
-| -------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| **Transaction Lifecycle**  | Full journey from RPC submission through validation, relay, consensus, and ledger inclusion | `{service.name="rippled" && xrpl.tx.hash="ABC123..."}` |
-| **Cross-Node Propagation** | Transaction path across multiple rippled nodes with timing                                  | `{xrpl.tx.relay_count > 0}`                            |
-| **Consensus Rounds**       | Complete round with all phases (open, establish, accept)                                    | `{span.name=~"consensus.round.*"}`                     |
-| **RPC Request Processing** | Individual command execution with timing breakdown                                          | `{xrpl.rpc.command="account_info"}`                    |
-| **Ledger Acquisition**     | Peer-to-peer ledger data requests and responses                                             | `{span.name="ledger.acquire"}`                         |
-| **PathFinding Latency**    | Path computation time and cache effectiveness for payment RPCs                              | `{span.name="pathfind.compute"}`                       |
-| **TxQ Behavior**           | Queue depth, eviction patterns, fee escalation during congestion                            | `{span.name=~"txq.*"}`                                 |
-| **Ledger Sync**            | Full acquisition timeline including delta and transaction fetches                           | `{span.name=~"ledger.acquire.*"}`                      |
-| **Validator Health**       | UNL fetch success, manifest updates, stale list detection                                   | `{span.name=~"validator.*"}`                           |
+| Trace Type                 | Description                                                                                 | Example Query in Grafana/Tempo                       |
+| -------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| **Transaction Lifecycle**  | Full journey from RPC submission through validation, relay, consensus, and ledger inclusion | `{service.name="xrpld" && xrpl.tx.hash="ABC123..."}` |
+| **Cross-Node Propagation** | Transaction path across multiple xrpld nodes with timing                                    | `{xrpl.tx.relay_count > 0}`                          |
+| **Consensus Rounds**       | Complete round with all phases (open, establish, accept)                                    | `{span.name=~"consensus.round.*"}`                   |
+| **RPC Request Processing** | Individual command execution with timing breakdown                                          | `{xrpl.rpc.command="account_info"}`                  |
+| **Ledger Acquisition**     | Peer-to-peer ledger data requests and responses                                             | `{span.name="ledger.acquire"}`                       |
+| **PathFinding Latency**    | Path computation time and cache effectiveness for payment RPCs                              | `{span.name="pathfind.compute"}`                     |
+| **TxQ Behavior**           | Queue depth, eviction patterns, fee escalation during congestion                            | `{span.name=~"txq.*"}`                               |
+| **Ledger Sync**            | Full acquisition timeline including delta and transaction fetches                           | `{span.name=~"ledger.acquire.*"}`                    |
+| **Validator Health**       | UNL fetch success, manifest updates, stale list detection                                   | `{span.name=~"validator.*"}`                         |
 
 ### 1.8.2 What You Will See: Metrics (Derived from Traces)
 

OpenTelemetryPlan/02-design-decisions.md

@@ -25,10 +25,10 @@
 
 **Manual Instrumentation** (recommended):
 
-| Approach   | Pros                                                              | Cons                                                    |
-| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
-| **Manual** | Precise control, optimized placement, rippled-specific attributes | More development effort                                 |
-| **Auto**   | Less code, automatic coverage                                     | Less control, potential overhead, limited customization |
+| Approach   | Pros                                                            | Cons                                                    |
+| ---------- | --------------------------------------------------------------- | ------------------------------------------------------- |
+| **Manual** | Precise control, optimized placement, xrpld-specific attributes | More development effort                                 |
+| **Auto**   | Less code, automatic coverage                                   | Less control, potential overhead, limited customization |
 
 ---
 
@@ -38,10 +38,10 @@
 
 ```mermaid
 flowchart TB
-    subgraph nodes["rippled Nodes"]
-        node1["rippled<br/>Node 1"]
-        node2["rippled<br/>Node 2"]
-        node3["rippled<br/>Node 3"]
+    subgraph nodes["xrpld Nodes"]
+        node1["xrpld<br/>Node 1"]
+        node2["xrpld<br/>Node 2"]
+        node3["xrpld<br/>Node 3"]
     end
 
     collector["OpenTelemetry<br/>Collector<br/>(sidecar or standalone)"]
@@ -65,7 +65,7 @@ flowchart TB
 
 **Reading the diagram:**
 
-- **rippled Nodes (blue)**: The source of telemetry data. Each rippled node exports spans via OTLP/gRPC on port 4317.
+- **xrpld Nodes (blue)**: The source of telemetry data. Each xrpld node exports spans via OTLP/gRPC on port 4317.
 - **OpenTelemetry Collector (red)**: The central aggregation point that receives spans from all nodes. Can run as a sidecar (per-node) or standalone (shared). Handles batching, filtering, and routing.
 - **Observability Backends (green)**: The storage and visualization destinations. Tempo is the recommended backend for both development and production, and Elastic APM is an alternative. The Collector routes to one or more backends.
 - **Arrows (nodes to collector to backends)**: The data pipeline -- spans flow from nodes to the Collector over gRPC, then the Collector fans out to the configured backends.
@@ -203,11 +203,11 @@ job:
 
 ```cpp
 // Standard OpenTelemetry semantic conventions
-resource::SemanticConventions::SERVICE_NAME        = "rippled"
+resource::SemanticConventions::SERVICE_NAME        = "xrpld"
 resource::SemanticConventions::SERVICE_VERSION     = BuildInfo::getVersionString()
 resource::SemanticConventions::SERVICE_INSTANCE_ID = <node_public_key_base58>
 
-// Custom rippled attributes
+// Custom xrpld attributes
 "xrpl.network.id"      = <network_id>           // e.g., 0 for mainnet
 "xrpl.network.type"    = "mainnet" | "testnet" | "devnet" | "standalone"
 "xrpl.node.type"       = "validator" | "stock" | "reporting"
@@ -251,8 +251,8 @@ resource::SemanticConventions::SERVICE_INSTANCE_ID = <node_public_key_base58>
 "xrpl.consensus.proposers_total"   = int64    // Total peer positions
 "xrpl.consensus.agree_count"       = int64    // Peers that agree (haveConsensus)
 "xrpl.consensus.disagree_count"    = int64    // Peers that disagree
-"xrpl.consensus.threshold_percent" = int64    // Current threshold (50/65/70/95)
-"xrpl.consensus.result"            = string   // "yes", "no", "moved_on"
+"xrpl.consensus.threshold_percent" = int64    // Close-time consensus threshold (avCT_CONSENSUS_PCT = 75%)
+"xrpl.consensus.result"            = string   // "yes", "no", "moved_on", "expired"
 "xrpl.consensus.mode.old"          = string   // Previous consensus mode
 "xrpl.consensus.mode.new"          = string   // New consensus mode
 ```
@@ -406,7 +406,7 @@ processors:
 
 #### Configuration Options for Privacy
 
-In `rippled.cfg`, operators can control data collection granularity:
+In `xrpld.cfg`, operators can control data collection granularity:
 
 ```ini
 [telemetry]
@@ -423,7 +423,7 @@ redact_account=1      # Hash account addresses before export
 redact_peer_address=1 # Remove peer IP addresses
 ```
 
-> **Note**: The `redact_account` configuration in `rippled.cfg` controls SDK-level redaction before export, while collector-level filtering (see [Collector-Level Data Protection](#collector-level-data-protection) above) provides an additional defense-in-depth layer. Both can operate independently.
+> **Note**: The `redact_account` configuration in `xrpld.cfg` controls SDK-level redaction before export, while collector-level filtering (see [Collector-Level Data Protection](#collector-level-data-protection) above) provides an additional defense-in-depth layer. Both can operate independently.
 
 > **Key Principle**: Telemetry collects **operational metadata** (timing, counts, hashes) — never **sensitive content** (keys, balances, amounts, raw payloads).
 
@@ -433,12 +433,91 @@ redact_peer_address=1 # Remove peer IP addresses
 
 > **WS** = WebSocket
 
+### 2.5.0 Deterministic Trace ID Strategy
+
+Both transaction and consensus tracing use **deterministic trace IDs** derived from
+a globally known hash, so all nodes handling the same workflow independently produce
+spans under the same `trace_id`. This is combined with protobuf `span_id` propagation
+for parent-child relay ordering when available.
+
+#### Transactions — `trace_id = txHash[0:16]`
+
+Every node that handles a transaction knows its `txID` (the `uint256` transaction
+hash). The first 16 bytes of this hash are used as the OTel `trace_id`:
+
+```
+uint256 txHash:  A1B2C3D4 E5F6A7B8 C9D0E1F2 A3B4C5D6  E7F8A9B0 C1D2E3F4 A5B6C7D8 E9F0A1B2
+                 |---------- trace_id (16 bytes) ---------|  (remaining 16 bytes unused)
+```
+
+Each node generates a **random 8-byte `span_id`** so its span is unique within the
+shared trace. When protobuf `TraceContext` is present in the incoming `TMTransaction`,
+the sender's `span_id` is extracted and used as the parent — preserving the relay
+chain as a parent-child tree. When absent (older peers, first hop from client), the
+span appears as a root in the same trace — correlation is preserved, only the tree
+structure degrades.
+
+```
+Node A (submitter)        Node B (relay)          Node C (relay)
+trace_id: A1B2...         trace_id: A1B2...       trace_id: A1B2...
+span_id:  1234 (random)   span_id:  5678 (random) span_id:  9ABC (random)
+parent:   (none)          parent:   1234 (proto)   parent:   5678 (proto)
+                               ↑                        ↑
+                       protobuf propagation      protobuf propagation
+```
+
+If protobuf propagation fails at Node B (old peer):
+
+```
+Node A                    Node B (old peer)       Node C
+trace_id: A1B2...         trace_id: A1B2...       trace_id: A1B2...
+span_id:  1234            span_id:  5678          span_id:  9ABC
+parent:   (none)          parent:   (none)        parent:   5678 (proto)
+                          ↑ no parent, but same trace_id — still grouped
+```
+
+#### Consensus — `trace_id = prevLedgerHash[0:16]`
+
+All validators in the same consensus round share the same `previousLedger.id()`.
+The first 16 bytes are used as trace_id. See [Phase 4a implementation status](./06-implementation-phases.md)
+and `createDeterministicContext()` in `RCLConsensus.cpp` for the implementation.
+
+Switchable via `consensus_trace_strategy` config:
+`"deterministic"` (default) or `"attribute"` (random trace_id, correlation via attribute queries).
+
+#### Why Not Random IDs with Propagation Only?
+
+Random trace IDs require **unbroken context propagation** across every hop. In a
+mixed-version network (common during upgrades), older peers silently drop the
+`trace_context` protobuf field. The trace splits and downstream spans become
+impossible to find. Deterministic IDs make correlation **propagation-resilient** — the trace
+backend groups all spans for the same transaction/round regardless of whether
+propagation succeeded.
+
+#### Why Keep Protobuf Propagation?
+
+Deterministic trace IDs alone provide correlation (all spans grouped) but not
+**causality** (which node relayed to which). Protobuf `span_id` propagation adds
+parent-child ordering that shows the exact relay path. The two mechanisms complement
+each other:
+
+| Mechanism                    | Provides                    | Fails when                             |
+| ---------------------------- | --------------------------- | -------------------------------------- |
+| Deterministic trace_id       | Cross-node correlation      | Never (hash is always known)           |
+| Protobuf span_id propagation | Parent-child relay ordering | Older peer drops `trace_context` field |
+
+#### Implementation Reference
+
+The utility function `createDeterministicTxContext(uint256 const& txHash)` follows
+the same pattern as `createDeterministicContext(uint256 const& ledgerId)` in
+`RCLConsensus.cpp`. See [Phase 3 Task 3.9](./Phase3_taskList.md) for the full spec.
+
 ### 2.5.1 Propagation Boundaries
 
 ```mermaid
 flowchart TB
     subgraph http["HTTP/WebSocket (RPC)"]
-        w3c["W3C Trace Context Headers:<br/>traceparent:<br/>00-trace_id-span_id-flags<br/>tracestate: rippled=..."]
+        w3c["W3C Trace Context Headers:<br/>traceparent:<br/>00-trace_id-span_id-flags<br/>tracestate: xrpld=..."]
     end
 
     subgraph protobuf["Protocol Buffers (P2P)"]
@@ -457,7 +536,7 @@ flowchart TB
 **Reading the diagram:**
 
 - **HTTP/WebSocket - RPC (blue)**: For client-facing RPC requests, trace context is propagated using the W3C `traceparent` header. This is the standard approach and works with any OTel-compatible client.
-- **Protocol Buffers - P2P (green)**: For peer-to-peer messages between rippled nodes, trace context is embedded as a protobuf `TraceContext` message carrying trace_id, span_id, flags, and optional trace_state.
+- **Protocol Buffers - P2P (green)**: For peer-to-peer messages between xrpld nodes, trace context is embedded as a protobuf `TraceContext` message carrying trace_id, span_id, flags, and optional trace_state.
 - **JobQueue - Internal Async (red)**: For asynchronous work within a single node, the OTel context is captured when a job is created and restored when the job executes on a worker thread. This bridges the async gap so spans remain linked.
 
 ---
@@ -468,7 +547,7 @@ flowchart TB
 
 ### 2.6.1 Existing Frameworks Comparison
 
-rippled already has two observability mechanisms. OpenTelemetry complements (not replaces) them:
+xrpld already has two observability mechanisms. OpenTelemetry complements (not replaces) them:
 
 | Aspect                | PerfLog                       | Beast Insight (StatsD)       | OpenTelemetry             |
 | --------------------- | ----------------------------- | ---------------------------- | ------------------------- |
@@ -517,7 +596,7 @@ rippled already has two observability mechanisms. OpenTelemetry complements (not
   - Single-node perspective
 
 ```cpp
-// Example StatsD usage in rippled
+// Example StatsD usage in xrpld
 insight.increment("rpc.submit.count");
 insight.gauge("ledger.age", age);
 insight.timing("consensus.round", duration);
@@ -556,11 +635,9 @@ span->SetAttribute("peer.id", peerId);
 
 ### 2.6.4 Coexistence Strategy
 
-> **Note**: Phase 7 replaces the StatsD bridge with native OTel Metrics SDK export. The diagram below shows the Phase 6 intermediate state. See [Phase7_taskList.md](./Phase7_taskList.md) for the migration design where Beast Insight emits via OTLP instead of StatsD.
-
 ```mermaid
 flowchart TB
-    subgraph rippled["rippled Process"]
+    subgraph xrpld["xrpld Process"]
         perflog["PerfLog<br/>(JSON to file)"]
         insight["Beast Insight<br/>(StatsD)"]
         otel["OpenTelemetry<br/>(Tracing)"]
@@ -574,20 +651,18 @@ flowchart TB
     statsd --> grafana
     collector --> grafana
 
-    style rippled fill:#212121,stroke:#0a0a0a,color:#ffffff
+    style xrpld fill:#212121,stroke:#0a0a0a,color:#ffffff
     style grafana fill:#bf360c,stroke:#8c2809,color:#ffffff
 ```
 
 **Reading the diagram:**
 
-- **rippled Process (dark gray)**: The single rippled node running all three observability frameworks side by side. Each framework operates independently with no interference.
+- **xrpld Process (dark gray)**: The single xrpld node running all three observability frameworks side by side. Each framework operates independently with no interference.
 - **PerfLog to perf.log**: PerfLog writes JSON-formatted event logs to a local file. Grafana can ingest these via Loki or a file-based datasource.
 - **Beast Insight to StatsD Server**: Insight sends aggregated metrics (counters, gauges) over UDP to a StatsD server. Grafana reads from StatsD-compatible backends like Graphite or Prometheus (via StatsD exporter).
 - **OpenTelemetry to OTLP Collector**: OTel exports spans over OTLP/gRPC to a Collector, which then forwards to a trace backend (Tempo).
 - **Grafana (red, unified UI)**: All three data streams converge in Grafana, enabling operators to correlate logs, metrics, and traces in a single dashboard.
 
-**Phase 7 target state**: Beast Insight routes to `OTelCollector` (new `Collector` implementation) which exports via OTLP/HTTP to the same collector endpoint as traces. StatsD UDP path becomes a deprecated fallback (`[insight] server=statsd`). See [06-implementation-phases.md §6.8](./06-implementation-phases.md) and [Phase7_taskList.md](./Phase7_taskList.md) for details.
-
 ### 2.6.5 Correlation with PerfLog
 
 Trace IDs can be correlated with existing PerfLog entries for comprehensive debugging:

OpenTelemetryPlan/03-implementation-strategy.md

@@ -7,28 +7,24 @@
 
 ## 3.1 Directory Structure
 
-The telemetry implementation follows rippled's existing code organization pattern:
+The telemetry implementation follows xrpld's existing code organization pattern:
 
 ```
 include/xrpl/
 ├── telemetry/
-│   ├── Telemetry.h              # Main telemetry interface
+│   ├── Telemetry.h              # Main telemetry interface (global singleton)
 │   ├── TelemetryConfig.h        # Configuration structures
 │   ├── TraceContext.h           # Context propagation utilities
-│   ├── SpanGuard.h              # RAII span management
+│   ├── SpanGuard.h              # RAII span management with factory methods + discard()
+│   ├── DiscardFlag.h            # Thread-local discard flag
 │   └── SpanAttributes.h         # Attribute helper functions
 
 src/libxrpl/
 ├── telemetry/
-│   ├── Telemetry.cpp            # Implementation
+│   ├── Telemetry.cpp            # Implementation + FilteringSpanProcessor
 │   ├── TelemetryConfig.cpp      # Config parsing
 │   ├── TraceContext.cpp         # Context serialization
 │   └── NullTelemetry.cpp        # No-op implementation
-
-src/xrpld/
-├── telemetry/
-│   ├── TracingInstrumentation.h # Instrumentation macros
-│   └── TracingInstrumentation.cpp
 ```
 
 ---
@@ -314,20 +310,20 @@ flowchart TD
 
 ### 3.7.3 Conditional Instrumentation
 
-```cpp
-// Compile-time feature flag
-#ifndef XRPL_ENABLE_TELEMETRY
-// Zero-cost when disabled
-#define XRPL_TRACE_SPAN(t, n) ((void)0)
-#endif
+SpanGuard's static factory methods handle both compile-time and runtime
+checks internally. When `XRPL_ENABLE_TELEMETRY` is not defined, the
+entire SpanGuard class compiles to a no-op stub with empty method bodies.
+When it is defined, the factory methods check the global Telemetry
+instance and the relevant component filter before creating a span:
 
-// Runtime component filtering
-if (telemetry.shouldTracePeer())
-{
-    XRPL_TRACE_SPAN(telemetry, "peer.message.receive");
-    // ... instrumentation
-}
-// No overhead when component tracing disabled
+```cpp
+// SpanGuard factory methods handle all conditional logic internally.
+// When XRPL_ENABLE_TELEMETRY is not defined, these are no-ops.
+// When defined, they check Telemetry::getInstance() and the
+// component filter (e.g. shouldTracePeer()) at runtime.
+auto span = telemetry::SpanGuard::peerSpan("peer.message.receive");
+span.setAttribute("xrpl.peer.id", peerId);
+// No overhead when telemetry is disabled at compile time or runtime
 ```
 
 ---
@@ -344,13 +340,13 @@ if (telemetry.shouldTracePeer())
 
 > **TxQ** = Transaction Queue
 
-This section provides a detailed assessment of how intrusive the OpenTelemetry integration is to the existing rippled codebase.
+This section provides a detailed assessment of how intrusive the OpenTelemetry integration is to the existing xrpld codebase.
 
 ### 3.9.1 Files Modified Summary
 
 | Component             | Files Modified | Lines Added | Lines Changed | Architectural Impact |
 | --------------------- | -------------- | ----------- | ------------- | -------------------- |
-| **Core Telemetry**    | 5 new files    | ~800        | 0             | None (new module)    |
+| **Core Telemetry**    | 7 new files    | ~800        | 0             | None (new module)    |
 | **Application Init**  | 2 files        | ~30         | ~5            | Minimal              |
 | **RPC Layer**         | 3 files        | ~80         | ~20           | Minimal              |
 | **Transaction Relay** | 4 files        | ~120        | ~40           | Low                  |
@@ -360,7 +356,7 @@ This section provides a detailed assessment of how intrusive the OpenTelemetry i
 | **PathFinding**       | 2              | ~80         | ~5            | Minimal              |
 | **TxQ/Fee**           | 2              | ~60         | ~5            | Minimal              |
 | **Validator/Amend**   | 3              | ~40         | ~5            | Minimal              |
-| **Total**             | **~28 files**  | **~1,490**  | **~120**      | **Low**              |
+| **Total**             | **~27 files**  | **~1,490**  | **~120**      | **Low**              |
 
 ### 3.9.2 Detailed File Impact
 
@@ -380,22 +376,22 @@ pie title Code Changes by Component
 
 #### New Files (No Impact on Existing Code)
 
-| File                                           | Lines | Purpose              |
-| ---------------------------------------------- | ----- | -------------------- |
-| `include/xrpl/telemetry/Telemetry.h`           | ~160  | Main interface       |
-| `include/xrpl/telemetry/SpanGuard.h`           | ~120  | RAII wrapper         |
-| `include/xrpl/telemetry/TraceContext.h`        | ~80   | Context propagation  |
-| `src/xrpld/telemetry/TracingInstrumentation.h` | ~60   | Macros               |
-| `src/libxrpl/telemetry/Telemetry.cpp`          | ~200  | Implementation       |
-| `src/libxrpl/telemetry/TelemetryConfig.cpp`    | ~60   | Config parsing       |
-| `src/libxrpl/telemetry/NullTelemetry.cpp`      | ~40   | No-op implementation |
+| File                                        | Lines | Purpose                                               |
+| ------------------------------------------- | ----- | ----------------------------------------------------- |
+| `include/xrpl/telemetry/Telemetry.h`        | ~160  | Main interface (global singleton)                     |
+| `include/xrpl/telemetry/SpanGuard.h`        | ~250  | RAII wrapper + factory methods + discard + no-op stub |
+| `include/xrpl/telemetry/DiscardFlag.h`      | ~28   | Thread-local discard flag                             |
+| `include/xrpl/telemetry/TraceContext.h`     | ~80   | Context propagation                                   |
+| `src/libxrpl/telemetry/Telemetry.cpp`       | ~400  | Implementation + FilteringSpanProcessor               |
+| `src/libxrpl/telemetry/TelemetryConfig.cpp` | ~60   | Config parsing                                        |
+| `src/libxrpl/telemetry/NullTelemetry.cpp`   | ~40   | No-op implementation                                  |
 
-#### Modified Files (Existing Rippled Code)
+#### Modified Files (Existing Xrpld Code)
 
 | File                                              | Lines Added | Lines Changed | Risk Level |
 | ------------------------------------------------- | ----------- | ------------- | ---------- |
 | `src/xrpld/app/main/Application.cpp`              | ~15         | ~3            | Low        |
-| `include/xrpl/app/main/Application.h`             | ~5          | ~2            | Low        |
+| `include/xrpl/core/ServiceRegistry.h`             | ~5          | ~2            | Low        |
 | `src/xrpld/rpc/detail/ServerHandler.cpp`          | ~40         | ~10           | Low        |
 | `src/xrpld/rpc/handlers/*.cpp`                    | ~30         | ~8            | Low        |
 | `src/xrpld/overlay/detail/PeerImp.cpp`            | ~60         | ~15           | Medium     |
@@ -491,18 +487,24 @@ void ServerHandler::onRequest(...) {
     send(result);
 }
 
-// After (only ~10 lines added)
+// After (only ~4 lines added)
 void ServerHandler::onRequest(...) {
-    XRPL_TRACE_RPC(app_.getTelemetry(), "rpc.request");  // +1 line
-    XRPL_TRACE_SET_ATTR("xrpl.rpc.command", command);     // +1 line
+    auto span = telemetry::SpanGuard::rpcSpan("rpc.request");   // +1 line
+    span.setAttribute("xrpl.rpc.command", command);              // +1 line
 
     auto result = processRequest(req);
 
-    XRPL_TRACE_SET_ATTR("xrpl.rpc.status", status);       // +1 line
+    span.setAttribute("xrpl.rpc.status", status);                // +1 line
     send(result);
 }
 ```
 
+SpanGuard factory methods (`rpcSpan`, `txSpan`, `consensusSpan`, etc.)
+access the global `Telemetry` instance internally and check the relevant
+component filter (`shouldTraceRpc()`, etc.) before creating a span. The
+public SpanGuard header has zero `opentelemetry/` includes -- all OTel
+types are hidden behind the pimpl idiom.
+
 **Consensus Instrumentation (Medium Intrusiveness):**
 
 ```cpp
@@ -513,11 +515,11 @@ void RCLConsensusAdaptor::startRound(...) {
 
 // After (context storage required)
 void RCLConsensusAdaptor::startRound(...) {
-    XRPL_TRACE_CONSENSUS(app_.getTelemetry(), "consensus.round");
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.ledger.seq", seq);
+    auto span = telemetry::SpanGuard::consensusSpan("consensus.round");
+    span.setAttribute("xrpl.consensus.ledger.seq", seq);
 
     // Store context for child spans in phase transitions
-    currentRoundContext_ = _xrpl_guard_->context();  // New member variable
+    currentRoundContext_ = span.context();  // New member variable
 
     // ... existing logic unchanged
 }

OpenTelemetryPlan/04-code-samples.md

@@ -30,7 +30,7 @@ namespace telemetry {
 /**
  * Main telemetry interface for OpenTelemetry integration.
  *
- * This class provides the primary API for distributed tracing in rippled.
+ * This class provides the primary API for distributed tracing in xrpld.
  * It manages the OpenTelemetry SDK lifecycle and provides convenience
  * methods for creating spans and propagating context.
  */
@@ -43,7 +43,7 @@ public:
     struct Setup
     {
         bool enabled = false;
-        std::string serviceName = "rippled";
+        std::string serviceName = "xrpld";
         std::string serviceVersion;
         std::string serviceInstanceId;  // Node public key
 
@@ -98,7 +98,7 @@ public:
 
     /** Get the tracer for creating spans */
     virtual opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer>
-    getTracer(std::string_view name = "rippled") = 0;
+    getTracer(std::string_view name = "xrpld") = 0;
 
     // ═══════════════════════════════════════════════════════════════════════
     // SPAN CREATION (Convenience Methods)
@@ -181,271 +181,227 @@ setup_Telemetry(
 
 ---
 
-## 4.2 RAII Span Guard
+## 4.2 RAII Span Guard with Factory Methods
+
+SpanGuard is a self-contained RAII wrapper that creates, activates, and
+ends trace spans. It uses the pimpl idiom to hide all OpenTelemetry
+types -- the public header has **zero `opentelemetry/` includes**.
+Callers never interact with OTel SDK types directly.
+
+SpanGuard provides static factory methods (`rpcSpan()`, `txSpan()`,
+`consensusSpan()`, etc.) that access the global `Telemetry` singleton
+internally. Each factory checks both the runtime enable flag and the
+relevant component filter before creating a span.
+
+When `XRPL_ENABLE_TELEMETRY` is **not** defined, the entire SpanGuard
+class compiles to a no-op stub with empty inline method bodies, giving
+zero compile-time and runtime cost.
 
 ```cpp
 // include/xrpl/telemetry/SpanGuard.h
+//
+// Public API -- no opentelemetry/ includes.
+// OTel types are hidden behind the pimpl (Impl struct, defined in the
+// #ifdef XRPL_ENABLE_TELEMETRY section at the bottom of the header).
 #pragma once
 
-#include <opentelemetry/trace/span.h>
-#include <opentelemetry/trace/scope.h>
-#include <opentelemetry/trace/status.h>
-
+#include <memory>
 #include <string_view>
-#include <exception>
 
 namespace xrpl {
 namespace telemetry {
 
-/**
- * RAII guard for OpenTelemetry spans.
- *
- * Automatically ends the span on destruction and makes it the current
- * span in the thread-local context.
- */
+#ifdef XRPL_ENABLE_TELEMETRY
+
 class SpanGuard
 {
-    opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span> span_;
-    opentelemetry::trace::Scope scope_;
+    struct Impl;                         // pimpl -- defined in .cpp or
+    std::unique_ptr<Impl> impl_;         // in the guarded section below
 
 public:
-    /**
-     * Construct guard with span.
-     * The span becomes the current span in thread-local context.
-     *
-     * @note If span is nullptr (e.g., telemetry disabled), the guard
-     * becomes a no-op. All methods safely check for null before access.
-     */
-    explicit SpanGuard(
-        opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span> span)
-        : span_(span ? std::move(span) : nullptr)
-        , scope_(span_ ? opentelemetry::trace::Scope(span_)
-                       : opentelemetry::trace::Scope(
-                           opentelemetry::nostd::shared_ptr<
-                               opentelemetry::trace::Span>(nullptr)))
-    {
-    }
+    // ═══════════════════════════════════════════════════════════════════
+    // FACTORY METHODS  (access global Telemetry internally)
+    // ═══════════════════════════════════════════════════════════════════
 
-    // Non-copyable, non-movable
+    /** Create a span for RPC request handling.
+     *  Returns a no-op guard if telemetry is disabled or
+     *  shouldTraceRpc() is false.
+     */
+    static SpanGuard rpcSpan(std::string_view name);
+
+    /** Create a span for transaction processing. */
+    static SpanGuard txSpan(std::string_view name);
+
+    /** Create a span for consensus rounds. */
+    static SpanGuard consensusSpan(std::string_view name);
+
+    /** Create a span for peer-to-peer messages. */
+    static SpanGuard peerSpan(std::string_view name);
+
+    /** Create a span for ledger operations. */
+    static SpanGuard ledgerSpan(std::string_view name);
+
+    /** Create an uncategorized span (always created when enabled). */
+    static SpanGuard span(std::string_view name);
+
+    // ═══════════════════════════════════════════════════════════════════
+    // INSTANCE METHODS
+    // ═══════════════════════════════════════════════════════════════════
+
+    SpanGuard();                         // constructs a no-op guard
+    ~SpanGuard();
+    SpanGuard(SpanGuard&& other) noexcept;
+    SpanGuard& operator=(SpanGuard&&) = delete;
     SpanGuard(SpanGuard const&) = delete;
     SpanGuard& operator=(SpanGuard const&) = delete;
-    SpanGuard(SpanGuard&&) = delete;
-    SpanGuard& operator=(SpanGuard&&) = delete;
 
-    ~SpanGuard()
-    {
-        if (span_)
-            span_->End();
-    }
+    /** Mark the span status as OK. */
+    void setOk();
 
-    /** Access the underlying span */
-    opentelemetry::trace::Span& span() { return *span_; }
-    opentelemetry::trace::Span const& span() const { return *span_; }
+    /** Set an explicit status code. */
+    void setStatus(int code, std::string_view description = "");
 
-    /** Set span status to OK */
-    void setOk()
-    {
-        span_->SetStatus(opentelemetry::trace::StatusCode::kOk);
-    }
-
-    /** Set span status with code and description */
-    void setStatus(
-        opentelemetry::trace::StatusCode code,
-        std::string_view description = "")
-    {
-        span_->SetStatus(code, std::string(description));
-    }
-
-    /** Set an attribute on the span */
+    /** Set a key-value attribute on the span. */
     template<typename T>
-    void setAttribute(std::string_view key, T&& value)
-    {
-        span_->SetAttribute(
-            opentelemetry::nostd::string_view(key.data(), key.size()),
-            std::forward<T>(value));
-    }
+    void setAttribute(std::string_view key, T&& value);
 
-    /** Add an event to the span */
-    void addEvent(std::string_view name)
-    {
-        span_->AddEvent(std::string(name));
-    }
+    /** Add an event to the span timeline. */
+    void addEvent(std::string_view name);
 
-    /** Record an exception on the span */
-    void recordException(std::exception const& e)
-    {
-        span_->RecordException(e);
-        span_->SetStatus(
-            opentelemetry::trace::StatusCode::kError,
-            e.what());
-    }
+    /** Record an exception and set error status. */
+    void recordException(std::exception const& e);
 
-    /** Get the current trace context */
-    opentelemetry::context::Context context() const
-    {
-        return opentelemetry::context::RuntimeContext::GetCurrent();
-    }
+    /** Get the current trace context (for cross-thread propagation). */
+    // Returns an opaque context handle.
+    auto context() const;
+
+    /** Discard this span -- dropped before export. */
+    void discard();
 };
 
-/**
- * No-op span guard for when tracing is disabled.
- * Provides the same interface but does nothing.
- */
-class NullSpanGuard
+#else  // XRPL_ENABLE_TELEMETRY not defined -- zero-cost stub
+
+class SpanGuard
 {
 public:
-    NullSpanGuard() = default;
+    // Factory methods -- all return no-op guards
+    static SpanGuard rpcSpan(std::string_view) { return {}; }
+    static SpanGuard txSpan(std::string_view) { return {}; }
+    static SpanGuard consensusSpan(std::string_view) { return {}; }
+    static SpanGuard peerSpan(std::string_view) { return {}; }
+    static SpanGuard ledgerSpan(std::string_view) { return {}; }
+    static SpanGuard span(std::string_view) { return {}; }
 
+    // Instance methods -- all no-ops
     void setOk() {}
-    void setStatus(opentelemetry::trace::StatusCode, std::string_view = "") {}
+    void setStatus(int, std::string_view = "") {}
 
     template<typename T>
     void setAttribute(std::string_view, T&&) {}
 
     void addEvent(std::string_view) {}
     void recordException(std::exception const&) {}
-
-    /** Return a default empty context (matches SpanGuard interface) */
-    opentelemetry::context::Context context() const
-    {
-        return opentelemetry::context::Context{};
-    }
+    void discard() {}
 };
 
+#endif  // XRPL_ENABLE_TELEMETRY
+
 } // namespace telemetry
 } // namespace xrpl
 ```
 
 ---
 
-## 4.3 Instrumentation Macros
+## 4.3 SpanGuard API Reference
+
+The previous macro-based approach (`TracingInstrumentation.h` with
+`XRPL_TRACE_*` macros) has been replaced by SpanGuard's static factory
+methods. This eliminates preprocessor macros from instrumentation call
+sites and provides a cleaner, type-safe API.
+
+### 4.3.1 Factory Methods
+
+Each factory method accesses the global `Telemetry::getInstance()`
+singleton internally and checks the corresponding component filter.
+If telemetry is disabled (compile-time or runtime) or the component
+filter is off, the factory returns a no-op guard whose methods are
+all empty inlines.
+
+| Factory Method                   | Component Filter            | Typical Span Names                   |
+| -------------------------------- | --------------------------- | ------------------------------------ |
+| `SpanGuard::rpcSpan(name)`       | `shouldTraceRpc()`          | `rpc.request`, `rpc.command.submit`  |
+| `SpanGuard::txSpan(name)`        | `shouldTraceTransactions()` | `tx.receive`, `tx.validate`          |
+| `SpanGuard::consensusSpan(name)` | `shouldTraceConsensus()`    | `consensus.round`, `consensus.phase` |
+| `SpanGuard::peerSpan(name)`      | `shouldTracePeer()`         | `peer.message.receive`               |
+| `SpanGuard::ledgerSpan(name)`    | `shouldTraceLedger()`       | `ledger.close`, `ledger.accept`      |
+| `SpanGuard::span(name)`          | (always, if enabled)        | `job.execute`, custom spans          |
+
+### 4.3.2 Usage Pattern
 
 ```cpp
-// src/xrpld/telemetry/TracingInstrumentation.h
-#pragma once
-
-#include <xrpl/telemetry/Telemetry.h>
 #include <xrpl/telemetry/SpanGuard.h>
 
-namespace xrpl {
-namespace telemetry {
+void ServerHandler::onRequest(...)
+{
+    // Factory creates a span if RPC tracing is enabled, no-op otherwise.
+    // No Telemetry& reference needed -- accessed via global singleton.
+    auto span = telemetry::SpanGuard::rpcSpan("rpc.request");
+    span.setAttribute("xrpl.rpc.command", command);
 
-// ═══════════════════════════════════════════════════════════════════════════
-// INSTRUMENTATION MACROS
-// ═══════════════════════════════════════════════════════════════════════════
+    auto result = processRequest(req);
 
-#ifdef XRPL_ENABLE_TELEMETRY
+    span.setAttribute("xrpl.rpc.status", result.status());
+    span.setOk();
+    // span ended automatically when it goes out of scope
+}
+```
 
-// Start a span that is automatically ended when guard goes out of scope
-#define XRPL_TRACE_SPAN(telemetry, name) \
-    auto _xrpl_span_ = (telemetry).startSpan(name); \
-    ::xrpl::telemetry::SpanGuard _xrpl_guard_(_xrpl_span_)
+### 4.3.3 Compile-Time Disabled Behavior
 
-// Start a span with specific kind
-#define XRPL_TRACE_SPAN_KIND(telemetry, name, kind) \
-    auto _xrpl_span_ = (telemetry).startSpan(name, kind); \
-    ::xrpl::telemetry::SpanGuard _xrpl_guard_(_xrpl_span_)
+When `XRPL_ENABLE_TELEMETRY` is **not** defined, SpanGuard compiles to
+a zero-cost no-op stub. All factory methods return a default-constructed
+guard, and all instance methods have empty bodies:
 
-// Conditional span based on component
-#define XRPL_TRACE_TX(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceTransactions()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
+```cpp
+// When XRPL_ENABLE_TELEMETRY is not defined:
+class SpanGuard
+{
+public:
+    static SpanGuard rpcSpan(std::string_view) { return {}; }
+    static SpanGuard txSpan(std::string_view) { return {}; }
+    static SpanGuard consensusSpan(std::string_view) { return {}; }
+    static SpanGuard peerSpan(std::string_view) { return {}; }
+    static SpanGuard ledgerSpan(std::string_view) { return {}; }
+    static SpanGuard span(std::string_view) { return {}; }
 
-#define XRPL_TRACE_CONSENSUS(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceConsensus()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
+    void setOk() {}
+    void setStatus(int, std::string_view = "") {}
+    template<typename T>
+    void setAttribute(std::string_view, T&&) {}
+    void addEvent(std::string_view) {}
+    void recordException(std::exception const&) {}
+    void discard() {}
+};
+```
 
-#define XRPL_TRACE_RPC(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceRpc()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
+The compiler optimizes away all calls to these empty methods, producing
+the same binary as if no instrumentation code were present.
 
-#define XRPL_TRACE_PEER(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTracePeer()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
+### 4.3.4 Discard Support
 
-#define XRPL_TRACE_LEDGER(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceLedger()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
+SpanGuard supports discarding a span before it is exported. This is
+useful for filtering out uninteresting spans (e.g. successful
+preflight checks) after the span has been started:
 
-#define XRPL_TRACE_PATHFIND(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTracePathfind()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
-
-#define XRPL_TRACE_TXQ(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceTxQ()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
-
-#define XRPL_TRACE_VALIDATOR(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceValidator()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
-
-#define XRPL_TRACE_AMENDMENT(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceAmendment()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
-
-// Set attribute on current span (if exists).
-// Works with both std::optional<SpanGuard> (from conditional macros)
-// and bare SpanGuard (from XRPL_TRACE_SPAN). Uses 'if constexpr'-like
-// dispatch via a helper that checks for .has_value().
-#define XRPL_TRACE_SET_ATTR(key, value) \
-    do { \
-        if constexpr (requires { _xrpl_guard_.has_value(); }) { \
-            if (_xrpl_guard_.has_value()) \
-                _xrpl_guard_->setAttribute(key, value); \
-        } else { \
-            _xrpl_guard_.setAttribute(key, value); \
-        } \
-    } while(0)
-
-// Record exception on current span
-#define XRPL_TRACE_EXCEPTION(e) \
-    do { \
-        if constexpr (requires { _xrpl_guard_.has_value(); }) { \
-            if (_xrpl_guard_.has_value()) \
-                _xrpl_guard_->recordException(e); \
-        } else { \
-            _xrpl_guard_.recordException(e); \
-        } \
-    } while(0)
-
-#else  // XRPL_ENABLE_TELEMETRY not defined
-
-#define XRPL_TRACE_SPAN(telemetry, name) ((void)0)
-#define XRPL_TRACE_SPAN_KIND(telemetry, name, kind) ((void)0)
-#define XRPL_TRACE_TX(telemetry, name) ((void)0)
-#define XRPL_TRACE_CONSENSUS(telemetry, name) ((void)0)
-#define XRPL_TRACE_RPC(telemetry, name) ((void)0)
-#define XRPL_TRACE_PEER(telemetry, name) ((void)0)
-#define XRPL_TRACE_LEDGER(telemetry, name) ((void)0)
-#define XRPL_TRACE_PATHFIND(telemetry, name) ((void)0)
-#define XRPL_TRACE_TXQ(telemetry, name) ((void)0)
-#define XRPL_TRACE_VALIDATOR(telemetry, name) ((void)0)
-#define XRPL_TRACE_AMENDMENT(telemetry, name) ((void)0)
-#define XRPL_TRACE_SET_ATTR(key, value) ((void)0)
-#define XRPL_TRACE_EXCEPTION(e) ((void)0)
-
-#endif  // XRPL_ENABLE_TELEMETRY
-
-} // namespace telemetry
-} // namespace xrpl
+```cpp
+auto span = telemetry::SpanGuard::txSpan("tx.process");
+auto result = preflight(tx);
+if (result != tesSUCCESS)
+{
+    // Span is dropped before entering the batch export queue.
+    span.discard();
+    return result;
+}
 ```
 
 ---
@@ -457,7 +413,7 @@ namespace telemetry {
 Add to `src/xrpld/overlay/detail/ripple.proto`:
 
 ```protobuf
-// Note: rippled uses proto2 syntax. The 'optional' keyword below is valid
+// Note: xrpld uses proto2 syntax. The 'optional' keyword below is valid
 // in proto2 (it is the default field rule) and is included for clarity.
 
 // Trace context for distributed tracing across nodes
@@ -644,7 +600,7 @@ TraceContextPropagator::inject(
 ```cpp
 // src/xrpld/overlay/detail/PeerImp.cpp (modified)
 
-#include <xrpl/telemetry/TracingInstrumentation.h>
+#include <xrpl/telemetry/SpanGuard.h>
 
 void
 PeerImp::handleTransaction(
@@ -724,7 +680,7 @@ PeerImp::handleTransaction(
                 relayGuard.context(), protoCtx);
 
             // Relay to other peers
-            app_.overlay().relay(
+            app_.getOverlay().relay(
                 stx->getTransactionID(),
                 *m,
                 protoCtx,  // Pass trace context
@@ -749,7 +705,7 @@ PeerImp::handleTransaction(
 ```cpp
 // src/xrpld/app/consensus/RCLConsensus.cpp (modified)
 
-#include <xrpl/telemetry/TracingInstrumentation.h>
+#include <xrpl/telemetry/SpanGuard.h>
 
 void
 RCLConsensusAdaptor::startRound(
@@ -759,20 +715,18 @@ RCLConsensusAdaptor::startRound(
     hash_set<NodeID> const& peers,
     bool proposing)
 {
-    XRPL_TRACE_CONSENSUS(app_.getTelemetry(), "consensus.round");
+    auto span = telemetry::SpanGuard::consensusSpan("consensus.round");
 
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.ledger.prev", to_string(prevLedgerHash));
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.ledger.seq",
+    span.setAttribute("xrpl.consensus.ledger.prev", to_string(prevLedgerHash));
+    span.setAttribute("xrpl.consensus.ledger.seq",
         static_cast<int64_t>(prevLedger.seq() + 1));
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.proposers",
+    span.setAttribute("xrpl.consensus.proposers",
         static_cast<int64_t>(peers.size()));
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.mode",
+    span.setAttribute("xrpl.consensus.mode",
         proposing ? "proposing" : "observing");
 
     // Store trace context for use in phase transitions
-    currentRoundContext_ = _xrpl_guard_.has_value()
-        ? _xrpl_guard_->context()
-        : opentelemetry::context::Context{};
+    currentRoundContext_ = span.context();
 
     // ... existing implementation ...
 }
@@ -844,34 +798,22 @@ RCLConsensusAdaptor::peerProposal(
 ```cpp
 // src/xrpld/rpc/detail/ServerHandler.cpp (modified)
 
-#include <xrpl/telemetry/TracingInstrumentation.h>
+#include <xrpl/telemetry/SpanGuard.h>
 
 void
 ServerHandler::onRequest(
     http_request_type&& req,
     std::function<void(http_response_type&&)>&& send)
 {
-    // Extract trace context from HTTP headers (W3C Trace Context)
-    auto parentCtx = telemetry::TraceContextPropagator::extractFromHeaders(
-        [&req](std::string_view name) -> std::optional<std::string> {
-            // Beast's find() accepts a string_view for custom header lookup
-            auto it = req.find(name);
-            if (it != req.end())
-                return std::string(it->value());
-            return std::nullopt;
-        });
-
-    // Start request span
-    auto span = app_.getTelemetry().startSpan(
-        "rpc.request",
-        parentCtx,
-        opentelemetry::trace::SpanKind::kServer);
-    telemetry::SpanGuard guard(span);
+    // SpanGuard::rpcSpan() accesses the global Telemetry instance
+    // and checks shouldTraceRpc() internally. Returns a no-op guard
+    // if tracing is disabled.
+    auto span = telemetry::SpanGuard::rpcSpan("rpc.request");
 
     // Add HTTP attributes
-    guard.setAttribute("http.method", std::string(req.method_string()));
-    guard.setAttribute("http.target", std::string(req.target()));
-    guard.setAttribute("http.user_agent",
+    span.setAttribute("http.method", std::string(req.method_string()));
+    span.setAttribute("http.target", std::string(req.target()));
+    span.setAttribute("http.user_agent",
         std::string(req[boost::beast::http::field::user_agent]));
 
     auto const startTime = std::chrono::steady_clock::now();
@@ -885,8 +827,8 @@ ServerHandler::onRequest(
 
         if (!reader.parse(body, jv))
         {
-            guard.setStatus(
-                opentelemetry::trace::StatusCode::kError,
+            span.setStatus(
+                /* kError */ 2,
                 "Invalid JSON");
             sendError(send, "Invalid JSON");
             return;
@@ -899,13 +841,12 @@ ServerHandler::onRequest(
                 ? jv["method"].asString()
                 : "unknown";
 
-        guard.setAttribute("xrpl.rpc.command", command);
+        span.setAttribute("xrpl.rpc.command", command);
 
         // Create child span for command execution
-        auto cmdSpan = app_.getTelemetry().startSpan(
-            "rpc.command." + command);
         {
-            telemetry::SpanGuard cmdGuard(cmdSpan);
+            auto cmdSpan = telemetry::SpanGuard::rpcSpan(
+                "rpc.command." + command);
 
             // Execute RPC command
             auto result = processRequest(jv);
@@ -913,42 +854,42 @@ ServerHandler::onRequest(
             // Record result attributes
             if (result.isMember("status"))
             {
-                cmdGuard.setAttribute("xrpl.rpc.status",
+                cmdSpan.setAttribute("xrpl.rpc.status",
                     result["status"].asString());
             }
 
             if (result["status"].asString() == "error")
             {
-                cmdGuard.setStatus(
-                    opentelemetry::trace::StatusCode::kError,
+                cmdSpan.setStatus(
+                    /* kError */ 2,
                     result.isMember("error_message")
                         ? result["error_message"].asString()
                         : "RPC error");
             }
             else
             {
-                cmdGuard.setOk();
+                cmdSpan.setOk();
             }
         }
 
         auto const duration = std::chrono::steady_clock::now() - startTime;
-        guard.setAttribute("http.duration_ms",
+        span.setAttribute("http.duration_ms",
             std::chrono::duration<double, std::milli>(duration).count());
 
         // Inject trace context into response headers
         http_response_type resp;
         telemetry::TraceContextPropagator::injectToHeaders(
-            guard.context(),
+            span.context(),
             [&resp](std::string_view name, std::string_view value) {
                 resp.set(std::string(name), std::string(value));
             });
 
-        guard.setOk();
+        span.setOk();
         send(std::move(resp));
     }
     catch (std::exception const& e)
     {
-        guard.recordException(e);
+        span.recordException(e);
         JLOG(journal_.error()) << "RPC request failed: " << e.what();
         sendError(send, e.what());
     }
@@ -957,62 +898,43 @@ ServerHandler::onRequest(
 
 ### 4.5.4 JobQueue Context Propagation
 
+> **Architecture note**: `JobQueue` and its inner `Workers` class do not
+> hold an `Application&` or `ServiceRegistry&`. They receive a
+> `perf::PerfLog*` at construction. Because SpanGuard's factory methods
+> access the global `Telemetry` instance directly, no `Telemetry&`
+> reference needs to be threaded into `JobQueue`.
+>
+> The approach below captures trace context at job-creation time and
+> restores it when the job executes, so that any spans created _inside_
+> the job body automatically become children of the original caller's
+> trace.
+
 ```cpp
-// src/xrpld/core/JobQueue.h (modified)
+// src/libxrpl/core/detail/JobQueue.cpp (modified -- processTask)
 
-#include <opentelemetry/context/context.h>
-
-class Job
-{
-    // ... existing members ...
-
-    // Captured trace context at job creation
-    opentelemetry::context::Context traceContext_;
-
-public:
-    // Constructor captures current trace context
-    Job(JobType type, std::function<void()> func, ...)
-        : type_(type)
-        , func_(std::move(func))
-        , traceContext_(opentelemetry::context::RuntimeContext::GetCurrent())
-        // ... other initializations ...
-    {
-    }
-
-    // Get trace context for restoration during execution
-    opentelemetry::context::Context const&
-    traceContext() const { return traceContext_; }
-};
-
-// src/xrpld/core/JobQueue.cpp (modified)
+#include <xrpl/telemetry/SpanGuard.h>
 
 void
-Worker::run()
+JobQueue::processTask(int instance)
 {
-    while (auto job = getJob())
+    // ... existing job dequeue logic ...
+
+    // SpanGuard::span() uses the global Telemetry instance --
+    // no Telemetry& member needed on JobQueue.
+    auto span = telemetry::SpanGuard::span("job.execute");
+    span.setAttribute("xrpl.job.type", to_string(job.type()));
+    span.setAttribute("xrpl.job.worker",
+        static_cast<int64_t>(instance));
+
+    try
     {
-        // Restore trace context from job creation
-        auto token = opentelemetry::context::RuntimeContext::Attach(
-            job->traceContext());
-
-        // Start execution span
-        auto span = app_.getTelemetry().startSpan("job.execute");
-        telemetry::SpanGuard guard(span);
-
-        guard.setAttribute("xrpl.job.type", to_string(job->type()));
-        guard.setAttribute("xrpl.job.queue_ms", job->queueTimeMs());
-        guard.setAttribute("xrpl.job.worker", workerId_);
-
-        try
-        {
-            job->execute();
-            guard.setOk();
-        }
-        catch (std::exception const& e)
-        {
-            guard.recordException(e);
-            JLOG(journal_.error()) << "Job execution failed: " << e.what();
-        }
+        job.execute();
+        span.setOk();
+    }
+    catch (std::exception const& e)
+    {
+        span.recordException(e);
+        JLOG(journal_.error()) << "Job execution failed: " << e.what();
     }
 }
 ```
@@ -1029,7 +951,7 @@ flowchart TB
         submit["Submit TX"]
     end
 
-    subgraph NodeA["rippled Node A"]
+    subgraph NodeA["xrpld Node A"]
         rpcA["rpc.request"]
         cmdA["rpc.command.submit"]
         txRecvA["tx.receive"]
@@ -1037,13 +959,13 @@ flowchart TB
         txRelayA["tx.relay"]
     end
 
-    subgraph NodeB["rippled Node B"]
+    subgraph NodeB["xrpld Node B"]
         txRecvB["tx.receive"]
         txValB["tx.validate"]
         txRelayB["tx.relay"]
     end
 
-    subgraph NodeC["rippled Node C"]
+    subgraph NodeC["xrpld Node C"]
         txRecvC["tx.receive"]
         consensusC["consensus.round"]
         phaseC["consensus.phase.establish"]

OpenTelemetryPlan/05-configuration-reference.md

@@ -5,7 +5,7 @@
 
 ---
 
-## 5.1 rippled Configuration
+## 5.1 xrpld Configuration
 
 > **OTLP** = OpenTelemetry Protocol | **TxQ** = Transaction Queue
 
@@ -61,8 +61,16 @@ Add to `cfg/xrpld-example.cfg`:
 # trace_validator=0        # Validator list and manifest updates (low volume)
 # trace_amendment=0        # Amendment voting (very low volume)
 #
+# # Trace ID strategies for cross-node correlation
+# # "deterministic" (default) derives trace_id from a workflow hash
+# #   (txHash for transactions, prevLedgerHash for consensus) so all nodes
+# #   produce spans under the same trace_id for the same workflow.
+# # "attribute" uses random trace_id; correlation via attribute queries.
+# tx_trace_strategy=deterministic
+# consensus_trace_strategy=deterministic
+#
 # # Service identification (automatically detected if not specified)
-# # service_name=rippled
+# # service_name=xrpld
 # # service_instance_id=<node_public_key>
 
 [telemetry]
@@ -71,28 +79,30 @@ enabled=0
 
 ### 5.1.2 Configuration Options Summary
 
-| Option                | Type   | Default          | Description                               |
-| --------------------- | ------ | ---------------- | ----------------------------------------- |
-| `enabled`             | bool   | `false`          | Enable/disable telemetry                  |
-| `exporter`            | string | `"otlp_grpc"`    | Exporter type: otlp_grpc, otlp_http, none |
-| `endpoint`            | string | `localhost:4317` | OTLP collector endpoint                   |
-| `use_tls`             | bool   | `false`          | Enable TLS for exporter connection        |
-| `tls_ca_cert`         | string | `""`             | Path to CA certificate file               |
-| `sampling_ratio`      | float  | `1.0`            | Sampling ratio (0.0-1.0)                  |
-| `batch_size`          | uint   | `512`            | Spans per export batch                    |
-| `batch_delay_ms`      | uint   | `5000`           | Max delay before sending batch (ms)       |
-| `max_queue_size`      | uint   | `2048`           | Maximum queued spans                      |
-| `trace_transactions`  | bool   | `true`           | Enable transaction tracing                |
-| `trace_consensus`     | bool   | `true`           | Enable consensus tracing                  |
-| `trace_rpc`           | bool   | `true`           | Enable RPC tracing                        |
-| `trace_peer`          | bool   | `false`          | Enable peer message tracing (high volume) |
-| `trace_ledger`        | bool   | `true`           | Enable ledger tracing                     |
-| `trace_pathfind`      | bool   | `true`           | Enable path computation tracing           |
-| `trace_txq`           | bool   | `true`           | Enable transaction queue tracing          |
-| `trace_validator`     | bool   | `false`          | Enable validator list/manifest tracing    |
-| `trace_amendment`     | bool   | `false`          | Enable amendment voting tracing           |
-| `service_name`        | string | `"rippled"`      | Service name for traces                   |
-| `service_instance_id` | string | `<node_pubkey>`  | Instance identifier                       |
+| Option                     | Type   | Default           | Description                                                                                                |
+| -------------------------- | ------ | ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| `enabled`                  | bool   | `false`           | Enable/disable telemetry                                                                                   |
+| `exporter`                 | string | `"otlp_grpc"`     | Exporter type: otlp_grpc, otlp_http, none                                                                  |
+| `endpoint`                 | string | `localhost:4317`  | OTLP collector endpoint                                                                                    |
+| `use_tls`                  | bool   | `false`           | Enable TLS for exporter connection                                                                         |
+| `tls_ca_cert`              | string | `""`              | Path to CA certificate file                                                                                |
+| `sampling_ratio`           | float  | `1.0`             | Sampling ratio (0.0-1.0)                                                                                   |
+| `batch_size`               | uint   | `512`             | Spans per export batch                                                                                     |
+| `batch_delay_ms`           | uint   | `5000`            | Max delay before sending batch (ms)                                                                        |
+| `max_queue_size`           | uint   | `2048`            | Maximum queued spans                                                                                       |
+| `trace_transactions`       | bool   | `true`            | Enable transaction tracing                                                                                 |
+| `trace_consensus`          | bool   | `true`            | Enable consensus tracing                                                                                   |
+| `trace_rpc`                | bool   | `true`            | Enable RPC tracing                                                                                         |
+| `trace_peer`               | bool   | `false`           | Enable peer message tracing (high volume)                                                                  |
+| `trace_ledger`             | bool   | `true`            | Enable ledger tracing                                                                                      |
+| `trace_pathfind`           | bool   | `true`            | Enable path computation tracing                                                                            |
+| `trace_txq`                | bool   | `true`            | Enable transaction queue tracing                                                                           |
+| `trace_validator`          | bool   | `false`           | Enable validator list/manifest tracing                                                                     |
+| `trace_amendment`          | bool   | `false`           | Enable amendment voting tracing                                                                            |
+| `tx_trace_strategy`        | string | `"deterministic"` | TX trace ID strategy: `"deterministic"` (trace_id = txHash[0:16]) or `"attribute"` (random)                |
+| `consensus_trace_strategy` | string | `"deterministic"` | Consensus trace ID strategy: `"deterministic"` (trace_id = prevLedgerHash[0:16]) or `"attribute"` (random) |
+| `service_name`             | string | `"xrpld"`         | Service name for traces                                                                                    |
+| `service_instance_id`      | string | `<node_pubkey>`   | Instance identifier                                                                                        |
 
 ---
 
@@ -119,7 +129,7 @@ setup_Telemetry(
 
     // Basic settings
     setup.enabled = section.value_or("enabled", false);
-    setup.serviceName = section.value_or("service_name", "rippled");
+    setup.serviceName = section.value_or("service_name", "xrpld");
     setup.serviceVersion = version;
     setup.serviceInstanceId = section.value_or(
         "service_instance_id", nodePublicKey);
@@ -173,87 +183,97 @@ setup_Telemetry(
 
 ### 5.3.1 ApplicationImp Changes
 
+> **Deferred identity**: The node public key (`nodeIdentity_`) is not
+> available during `ApplicationImp`'s member initializer list — it is
+> resolved later in `setup()`. The `Telemetry` object is therefore
+> constructed with an empty `serviceInstanceId` and patched via
+> `setServiceInstanceId()` once `setup()` has called `getNodeIdentity()`.
+
 ```cpp
 // src/xrpld/app/main/Application.cpp (modified)
 
 #include <xrpl/telemetry/Telemetry.h>
 
-class ApplicationImp : public Application
+class ApplicationImp : public Application, public BasicApp
 {
-    // ... existing members ...
+    // ... existing members (perfLog_, etc.) ...
 
-    // Telemetry (must be constructed early, destroyed late)
+    // Telemetry — constructed in the member initializer list with
+    // an empty serviceInstanceId, patched in setup().
     std::unique_ptr<telemetry::Telemetry> telemetry_;
 
-public:
-    ApplicationImp(...)
+    // Member initializer list (excerpt):
+    // ...
+    // , telemetry_(
+    //       telemetry::make_Telemetry(
+    //           telemetry::setup_Telemetry(
+    //               config_->section("telemetry"),
+    //               "",  // Updated later via setServiceInstanceId()
+    //               BuildInfo::getVersionString()),
+    //           logs_->journal("Telemetry")))
+    // ...
+
+    bool setup(...) override
     {
-        // Initialize telemetry early (before other components)
-        auto telemetrySection = config_->section("telemetry");
-        auto telemetrySetup = telemetry::setup_Telemetry(
-            telemetrySection,
-            toBase58(TokenType::NodePublic, nodeIdentity_.publicKey()),
-            BuildInfo::getVersionString());
+        // ... existing setup code ...
 
-        // Set network attributes
-        telemetrySetup.networkId = config_->NETWORK_ID;
-        telemetrySetup.networkType = [&]() {
-            if (config_->NETWORK_ID == 0) return "mainnet";
-            if (config_->NETWORK_ID == 1) return "testnet";
-            if (config_->NETWORK_ID == 2) return "devnet";
-            return "custom";
-        }();
+        nodeIdentity_ = getNodeIdentity(*this, cmdline);
 
-        telemetry_ = telemetry::make_Telemetry(
-            telemetrySetup,
-            logs_->journal("Telemetry"));
+        // Inject node identity into telemetry resource attributes,
+        // unless the user already set a custom service_instance_id.
+        if (!config_->section("telemetry").exists("service_instance_id"))
+            telemetry_->setServiceInstanceId(
+                toBase58(TokenType::NodePublic, nodeIdentity_->first));
 
-        // ... rest of initialization ...
+        // ... rest of setup ...
     }
 
-    void start() override
+    void start(bool withTimers) override
     {
-        // Start telemetry first
-        if (telemetry_)
-            telemetry_->start();
-
         // ... existing start code ...
+        telemetry_->start();
     }
 
-    void stop() override
+    void run() override
     {
-        // ... existing stop code ...
-
-        // Stop telemetry last (to capture shutdown spans)
-        if (telemetry_)
-            telemetry_->stop();
+        // ... existing run/shutdown code ...
+        telemetry_->stop();
     }
 
-    telemetry::Telemetry& getTelemetry() override
+    telemetry::Telemetry&
+    getTelemetry() override
     {
-        assert(telemetry_);
         return *telemetry_;
     }
 };
 ```
 
-### 5.3.2 Application Interface Addition
+### 5.3.2 ServiceRegistry Interface Addition
 
 ```cpp
-// include/xrpl/app/main/Application.h (modified)
+// include/xrpl/core/ServiceRegistry.h (modified)
 
-namespace telemetry { class Telemetry; }
+namespace telemetry {
+class Telemetry;
+}  // namespace telemetry
 
-class Application
+class ServiceRegistry
 {
 public:
     // ... existing virtual methods ...
 
-    /** Get the telemetry system for distributed tracing */
-    virtual telemetry::Telemetry& getTelemetry() = 0;
+    /** Get the telemetry system for distributed tracing. */
+    virtual telemetry::Telemetry&
+    getTelemetry() = 0;
 };
 ```
 
+> **Note:** `Application` extends `ServiceRegistry`, so `getTelemetry()` is
+> available on both. Components that hold a `ServiceRegistry&` (e.g.
+> `NetworkOPsImp`) call `registry_.get().getTelemetry()`. Components that
+> still hold an `Application&` (e.g. `ServerHandler`, `PeerImp`,
+> `RCLConsensusAdaptor`) call `app_.getTelemetry()` directly.
+
 ---
 
 ## 5.4 CMake Integration
@@ -403,13 +423,7 @@ exporters:
     sampling_initial: 5
     sampling_thereafter: 200
 
-  # Tempo for trace visualization
-  otlp/tempo:
-    endpoint: tempo:4317
-    tls:
-      insecure: true
-
-  # Grafana Tempo for trace storage
+  # Tempo for trace storage
   otlp/tempo:
     endpoint: tempo:4317
     tls:
@@ -420,7 +434,7 @@ service:
     traces:
       receivers: [otlp]
       processors: [batch]
-      exporters: [logging, jaeger, otlp/tempo]
+      exporters: [logging, otlp/tempo]
 ```
 
 ### 5.5.2 Production Configuration
@@ -554,7 +568,7 @@ services:
     depends_on:
       - tempo
 
-  # Tempo for trace visualization
+  # Tempo for trace storage
   tempo:
     image: grafana/tempo:2.6.1
     container_name: tempo
@@ -562,17 +576,6 @@ services:
       - "3200:3200" # Tempo HTTP API
       - "4317" # OTLP gRPC (internal)
 
-  # Grafana Tempo for trace storage (recommended for production)
-  tempo:
-    image: grafana/tempo:2.7.2
-    container_name: tempo
-    command: ["-config.file=/etc/tempo.yaml"]
-    volumes:
-      - ./tempo.yaml:/etc/tempo.yaml:ro
-      - tempo-data:/var/tempo
-    ports:
-      - "3200:3200" # HTTP API
-
   # Grafana for dashboards
   grafana:
     image: grafana/grafana:10.2.3
@@ -586,7 +589,6 @@ services:
     ports:
       - "3000:3000"
     depends_on:
-      - jaeger
       - tempo
 
   # Prometheus for metrics (optional, for correlation)
@@ -600,7 +602,7 @@ services:
 
 networks:
   default:
-    name: rippled-telemetry
+    name: xrpld-telemetry
 ```
 
 ---
@@ -653,7 +655,7 @@ flowchart TB
 - **Configuration Sources**: `xrpld.cfg` provides runtime settings (endpoint, sampling) while the CMake flag controls whether telemetry is compiled in at all.
 - **Initialization**: `setup_Telemetry()` parses config values, then `make_Telemetry()` constructs the provider, processor, and exporter objects.
 - **Runtime Components**: The `TracerProvider` creates spans, the `BatchProcessor` buffers them, and the `OTLP Exporter` serializes and sends them over the wire.
-- **OTLP arrow to Collector**: Trace data leaves the rippled process via OTLP (gRPC or HTTP) and enters the external Collector pipeline.
+- **OTLP arrow to Collector**: Trace data leaves the xrpld process via OTLP (gRPC or HTTP) and enters the external Collector pipeline.
 - **Collector Pipeline**: `Receivers` ingest OTLP data, `Processors` apply sampling/filtering/enrichment, and `Exporters` forward traces to storage backends (Tempo, etc.).
 
 ---
@@ -662,7 +664,7 @@ flowchart TB
 
 > **APM** = Application Performance Monitoring
 
-Step-by-step instructions for integrating rippled traces with Grafana.
+Step-by-step instructions for integrating xrpld traces with Grafana.
 
 ### 5.8.1 Data Source Configuration
 
@@ -721,10 +723,10 @@ datasources:
 apiVersion: 1
 
 providers:
-  - name: "rippled-dashboards"
+  - name: "xrpld-dashboards"
     orgId: 1
-    folder: "rippled"
-    folderUid: "rippled"
+    folder: "xrpld"
+    folderUid: "xrpld"
     type: file
     disableDeletion: false
     updateIntervalSeconds: 30
@@ -736,8 +738,8 @@ providers:
 
 ```json
 {
-  "title": "rippled RPC Performance",
-  "uid": "rippled-rpc-performance",
+  "title": "xrpld RPC Performance",
+  "uid": "xrpld-rpc-performance",
   "panels": [
     {
       "title": "RPC Latency by Command",
@@ -746,7 +748,7 @@ providers:
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && span.xrpl.rpc.command != \"\"} | histogram_over_time(duration) by (span.xrpl.rpc.command)"
+          "query": "{resource.service.name=\"xrpld\" && span.xrpl.rpc.command != \"\"} | histogram_over_time(duration) by (span.xrpl.rpc.command)"
         }
       ],
       "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 }
@@ -758,7 +760,7 @@ providers:
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && status.code=error} | rate() by (span.xrpl.rpc.command)"
+          "query": "{resource.service.name=\"xrpld\" && status.code=error} | rate() by (span.xrpl.rpc.command)"
         }
       ],
       "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 }
@@ -770,7 +772,7 @@ providers:
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && span.xrpl.rpc.command != \"\"} | avg(duration) by (span.xrpl.rpc.command) | topk(10)"
+          "query": "{resource.service.name=\"xrpld\" && span.xrpl.rpc.command != \"\"} | avg(duration) by (span.xrpl.rpc.command) | topk(10)"
         }
       ],
       "gridPos": { "h": 8, "w": 24, "x": 0, "y": 8 }
@@ -782,7 +784,7 @@ providers:
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\"}"
+          "query": "{resource.service.name=\"xrpld\"}"
         }
       ],
       "gridPos": { "h": 8, "w": 24, "x": 0, "y": 16 }
@@ -795,8 +797,8 @@ providers:
 
 ```json
 {
-  "title": "rippled Transaction Tracing",
-  "uid": "rippled-tx-tracing",
+  "title": "xrpld Transaction Tracing",
+  "uid": "xrpld-tx-tracing",
   "panels": [
     {
       "title": "Transaction Throughput",
@@ -805,7 +807,7 @@ providers:
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.receive\"} | rate()"
+          "query": "{resource.service.name=\"xrpld\" && name=\"tx.receive\"} | rate()"
         }
       ],
       "gridPos": { "h": 4, "w": 6, "x": 0, "y": 0 }
@@ -817,7 +819,7 @@ providers:
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.relay\"} | avg(span.xrpl.tx.relay_count)"
+          "query": "{resource.service.name=\"xrpld\" && name=\"tx.relay\"} | avg(span.xrpl.tx.relay_count)"
         }
       ],
       "gridPos": { "h": 8, "w": 12, "x": 0, "y": 4 }
@@ -829,7 +831,7 @@ providers:
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.validate\" && status.code=error}"
+          "query": "{resource.service.name=\"xrpld\" && name=\"tx.validate\" && status.code=error}"
         }
       ],
       "gridPos": { "h": 8, "w": 12, "x": 12, "y": 4 }
@@ -840,26 +842,26 @@ providers:
 
 ### 5.8.5 TraceQL Query Examples
 
-Common queries for rippled traces:
+Common queries for xrpld traces:
 
 ```
 # Find all traces for a specific transaction hash
-{resource.service.name="rippled" && span.xrpl.tx.hash="ABC123..."}
+{resource.service.name="xrpld" && span.xrpl.tx.hash="ABC123..."}
 
 # Find slow RPC commands (>100ms)
-{resource.service.name="rippled" && name=~"rpc.command.*"} | duration > 100ms
+{resource.service.name="xrpld" && name=~"rpc.command.*"} | duration > 100ms
 
 # Find consensus rounds taking >5 seconds
-{resource.service.name="rippled" && name="consensus.round"} | duration > 5s
+{resource.service.name="xrpld" && name="consensus.round"} | duration > 5s
 
 # Find failed transactions with error details
-{resource.service.name="rippled" && name="tx.validate" && status.code=error}
+{resource.service.name="xrpld" && name="tx.validate" && status.code=error}
 
 # Find transactions relayed to many peers
-{resource.service.name="rippled" && name="tx.relay"} | span.xrpl.tx.relay_count > 10
+{resource.service.name="xrpld" && name="tx.relay"} | span.xrpl.tx.relay_count > 10
 
 # Compare latency across nodes
-{resource.service.name="rippled" && name="rpc.command.account_info"} | avg(duration) by (resource.service.instance.id)
+{resource.service.name="xrpld" && name="rpc.command.account_info"} | avg(duration) by (resource.service.instance.id)
 ```
 
 ### 5.8.6 Correlation with PerfLog
@@ -871,12 +873,12 @@ To correlate OpenTelemetry traces with existing PerfLog data:
 ```yaml
 # promtail-config.yaml
 scrape_configs:
-  - job_name: rippled-perflog
+  - job_name: xrpld-perflog
     static_configs:
       - targets:
           - localhost
         labels:
-          job: rippled
+          job: xrpld
           __path__: /var/log/rippled/perf*.log
     pipeline_stages:
       - json:
@@ -921,22 +923,18 @@ jsonData:
     filterBySpanID: false
 ```
 
-### 5.8.7 Correlation with Insight/OTel System Metrics
+### 5.8.7 Correlation with Insight/StatsD Metrics
 
-To correlate traces with Beast Insight system metrics:
+To correlate traces with existing Beast Insight metrics:
 
 **Step 1: Export Insight metrics to Prometheus**
 
-Beast Insight metrics are exported natively via OTLP to the OTel Collector,
-which exposes them on the Prometheus endpoint alongside spanmetrics. No
-separate StatsD exporter is needed when using `server=otel`.
-
-```ini
-# xrpld.cfg — native OTel metrics (recommended)
-[insight]
-server=otel
-endpoint=http://localhost:4318/v1/metrics
-prefix=rippled
+```yaml
+# prometheus.yaml
+scrape_configs:
+  - job_name: "xrpld-statsd"
+    static_configs:
+      - targets: ["statsd-exporter:9102"]
 ```
 
 **Step 2: Add exemplars to metrics**
@@ -962,7 +960,7 @@ jsonData:
   "datasource": "Prometheus",
   "targets": [
     {
-      "expr": "histogram_quantile(0.99, rate(rippled_rpc_duration_seconds_bucket[5m]))",
+      "expr": "histogram_quantile(0.99, rate(xrpld_rpc_duration_seconds_bucket[5m]))",
       "exemplar": true
     }
   ]

OpenTelemetryPlan/06-implementation-phases.md

@@ -46,10 +46,8 @@ gantt
     Consensus Tracing         :p4, after p3, 2w
     Consensus Round Spans     :p4a, after p3, 3d
     Proposal Handling         :p4b, after p4a, 3d
-    Validator List & Manifest Tracing :p4f, after p4b, 2d
-    Amendment Voting Tracing  :p4g, after p4f, 2d
-    SHAMap Sync Tracing       :p4h, after p4g, 2d
-    Validation Tests          :p4c, after p4h, 4d
+    Establish Phase (4a)      :p4f, after p4b, 3d
+    Validation Tests          :p4c, after p4f, 4d
     Buffer & Review           :p4e, after p4c, 4d
 
     section Phase 5
@@ -118,21 +116,31 @@ gantt
 
 ## 6.4 Phase 3: Transaction Tracing (Weeks 5-6)
 
-**Objective**: Trace transaction lifecycle across network
+**Objective**: Trace transaction lifecycle across network with deterministic cross-node correlation
 
 ### Tasks
 
-| Task | Description                                          |
-| ---- | ---------------------------------------------------- |
-| 3.1  | Define `TraceContext` Protocol Buffer message        |
-| 3.2  | Implement protobuf context serialization             |
-| 3.3  | Instrument `PeerImp::handleTransaction()`            |
-| 3.4  | Instrument `NetworkOPs::submitTransaction()`         |
-| 3.5  | Instrument HashRouter integration                    |
-| 3.6  | Fee escalation instrumentation (`fee.escalate` span) |
-| 3.7  | Implement relay context propagation                  |
-| 3.8  | Integration tests (multi-node)                       |
-| 3.9  | Performance benchmarks                               |
+| Task | Description                                                    |
+| ---- | -------------------------------------------------------------- |
+| 3.1  | Define `TraceContext` Protocol Buffer message                  |
+| 3.2  | Implement protobuf context serialization                       |
+| 3.3  | Instrument `PeerImp::handleTransaction()`                      |
+| 3.4  | Instrument `NetworkOPs::submitTransaction()`                   |
+| 3.5  | Instrument HashRouter integration                              |
+| 3.6  | Fee escalation instrumentation (`fee.escalate` span)           |
+| 3.7  | Implement relay context propagation                            |
+| 3.8  | Integration tests (multi-node)                                 |
+| 3.9  | Deterministic transaction trace ID (`trace_id = txHash[0:16]`) |
+| 3.10 | Performance benchmarks                                         |
+
+### Deterministic Trace ID (Task 3.9)
+
+Transaction spans use **deterministic trace IDs** derived from the transaction hash:
+`trace_id = txHash[0:16]`. All nodes handling the same transaction independently
+produce spans under the same trace_id. Protobuf `span_id` propagation (Task 3.7)
+additionally provides parent-child relay ordering when available. See
+[02-design-decisions.md §2.5.0](./02-design-decisions.md) for the design rationale
+and [Phase3_taskList.md Task 3.9](./Phase3_taskList.md) for the full implementation spec.
 
 ### Exit Criteria
 
@@ -141,6 +149,8 @@ gantt
 - [ ] HashRouter deduplication visible in traces
 - [ ] Multi-node integration tests passing
 - [ ] <5% overhead on transaction throughput
+- [ ] Deterministic trace_id: all nodes produce same trace_id for same transaction
+- [ ] Protobuf span_id propagation preserves parent-child ordering when available
 
 ---
 
@@ -150,38 +160,44 @@ gantt
 
 ### Tasks
 
-| Task | Description                                    |
-| ---- | ---------------------------------------------- |
-| 4.1  | Instrument `RCLConsensusAdaptor::startRound()` |
-| 4.2  | Instrument phase transitions                   |
-| 4.3  | Instrument proposal handling                   |
-| 4.4  | Instrument validation handling                 |
-| 4.5  | Add consensus-specific attributes              |
-| 4.6  | Correlate with transaction traces              |
-| 4.7  | Validator list and manifest tracing            |
-| 4.8  | Amendment voting tracing                       |
-| 4.9  | SHAMap sync tracing                            |
-| 4.10 | Multi-validator integration tests              |
-| 4.11 | Performance validation                         |
+| Task | Description                                    | Status             |
+| ---- | ---------------------------------------------- | ------------------ |
+| 4.1  | Instrument `RCLConsensusAdaptor::startRound()` | ✅ Done (via 4a.2) |
+| 4.2  | Instrument phase transitions                   | ✅ Done            |
+| 4.3  | Instrument proposal handling                   | ✅ Done            |
+| 4.4  | Instrument validation handling                 | ✅ Done            |
+| 4.5  | Add consensus-specific attributes              | ✅ Done            |
+| 4.6  | Correlate with transaction traces              | ✅ Done            |
+| 4.7  | Build verification and testing                 | ✅ Done            |
+| 4.8  | Validation span enrichment (ext. dashboard)    | ❌ Not done        |
+
+**Note**: The original plan doc listed tasks 4.7-4.11 as "Validator list tracing",
+"Amendment voting tracing", "SHAMap sync tracing", "Multi-validator integration tests",
+and "Performance validation". These were descoped and replaced by the tasklist's 4.7
+(build verification) and 4.8 (validation span enrichment). Validator, amendment, and
+SHAMap tracing are not implemented.
 
 ### Spans Produced
 
 | Span Name                   | Location               | Attributes                                                                                                                                                                                                            |
 | --------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `consensus.proposal.send`   | `RCLConsensus.cpp:177` | `xrpl.consensus.round`                                                                                                                                                                                                |
-| `consensus.ledger_close`    | `RCLConsensus.cpp:282` | `xrpl.consensus.ledger.seq`, `xrpl.consensus.mode`                                                                                                                                                                    |
-| `consensus.accept`          | `RCLConsensus.cpp:395` | `xrpl.consensus.proposers`, `xrpl.consensus.round_time_ms`                                                                                                                                                            |
-| `consensus.accept.apply`    | `RCLConsensus.cpp:521` | `xrpl.consensus.close_time`, `close_time_correct`, `close_resolution_ms`, `state`, `proposing`, `round_time_ms`, `ledger.seq`, `parent_close_time`, `close_time_self`, `close_time_vote_bins`, `resolution_direction` |
-| `consensus.validation.send` | `RCLConsensus.cpp:753` | `xrpl.consensus.proposing`                                                                                                                                                                                            |
+| `consensus.phase.open`      | `Consensus.h:707`      | _(none)_                                                                                                                                                                                                              |
+| `consensus.proposal.send`   | `RCLConsensus.cpp:232` | `xrpl.consensus.round`                                                                                                                                                                                                |
+| `consensus.ledger_close`    | `RCLConsensus.cpp:341` | `xrpl.consensus.ledger.seq`, `xrpl.consensus.mode`                                                                                                                                                                    |
+| `consensus.accept`          | `RCLConsensus.cpp:492` | `xrpl.consensus.proposers`, `xrpl.consensus.round_time_ms`, `xrpl.consensus.quorum`                                                                                                                                   |
+| `consensus.accept.apply`    | `RCLConsensus.cpp:541` | `xrpl.consensus.close_time`, `close_time_correct`, `close_resolution_ms`, `state`, `proposing`, `round_time_ms`, `ledger.seq`, `parent_close_time`, `close_time_self`, `close_time_vote_bins`, `resolution_direction` |
+| `consensus.validation.send` | `RCLConsensus.cpp:900` | `xrpl.consensus.ledger.seq`, `xrpl.consensus.proposing`                                                                                                                                                               |
 
 ### Exit Criteria
 
 - [x] Complete consensus round traces
-- [x] Phase transitions visible
-- [x] Proposals and validations traced
+- [x] Phase transitions visible (open, establish, close, accept)
+- [x] Proposals and validations traced — send and receive; relay deferred to Phase 4b
 - [x] Close time agreement tracked (per `avCT_CONSENSUS_PCT`)
 - [x] No impact on consensus timing
 - [ ] Multi-validator test network validated
+- [x] Transaction-consensus correlation (Task 4.6) — `tx.included` events in doAccept
+- [ ] Validation span enrichment (Task 4.8) — not implemented
 
 ### Implementation Status — Phase 4a Complete
 
@@ -212,44 +228,47 @@ See [Phase4_taskList.md](./Phase4_taskList.md) for the full spec and implementat
 **Objective**: Fill tracing gaps in the establish phase and establish cross-node
 correlation using deterministic trace IDs derived from `previousLedger.id()`.
 
-**Approach**: Direct instrumentation in `Consensus.h`. Long-lived spans use
-direct SpanGuard members; short-lived scoped spans use `XRPL_TRACE_*` macros.
+**Approach**: Direct instrumentation in `Consensus.h` and `RCLConsensus.cpp`.
+All spans use `SpanGuard` factory methods (`span()`, `hashSpan()`, `linkedSpan()`)
+with `TraceCategory::Consensus` gating. No macros used — all tracing via direct
+`SpanGuard` API calls.
 
 ### Tasks
 
-| Task | Description                                      | Effort | Risk   |
-| ---- | ------------------------------------------------ | ------ | ------ |
-| 4a.0 | Prerequisites: extend SpanGuard & Telemetry APIs | 1d     | Medium |
-| 4a.1 | Adaptor `getTelemetry()` method                  | 0.5d   | Low    |
-| 4a.2 | Switchable round span with deterministic traceID | 2d     | High   |
-| 4a.3 | Span members in `Consensus.h`                    | 0.5d   | Medium |
-| 4a.4 | Instrument `phaseEstablish()`                    | 1d     | Medium |
-| 4a.5 | Instrument `updateOurPositions()`                | 1d     | Medium |
-| 4a.6 | Instrument `haveConsensus()` (thresholds)        | 1d     | Medium |
-| 4a.7 | Instrument mode changes                          | 0.5d   | Low    |
-| 4a.8 | Reparent existing spans under round              | 0.5d   | Low    |
-| 4a.9 | Build verification and testing                   | 1d     | Low    |
+| Task | Description                                      | Effort | Risk   | Status                   |
+| ---- | ------------------------------------------------ | ------ | ------ | ------------------------ |
+| 4a.0 | Prerequisites: extend SpanGuard & Telemetry APIs | 1d     | Medium | ✅ Done (no macros)      |
+| 4a.1 | Adaptor `getTelemetry()` method                  | 0.5d   | Low    | ⏭️ Skipped (not needed)  |
+| 4a.2 | Switchable round span with deterministic traceID | 2d     | High   | ✅ Done                  |
+| 4a.3 | Span members in `Consensus.h`                    | 0.5d   | Medium | ✅ Done (with deviation) |
+| 4a.4 | Instrument `phaseEstablish()`                    | 1d     | Medium | ✅ Done                  |
+| 4a.5 | Instrument `updateOurPositions()`                | 1d     | Medium | ✅ Done                  |
+| 4a.6 | Instrument `haveConsensus()` (thresholds)        | 1d     | Medium | ✅ Done                  |
+| 4a.7 | Instrument mode changes                          | 0.5d   | Low    | ✅ Done                  |
+| 4a.8 | Reparent existing spans under round              | 0.5d   | Low    | ✅ Done                  |
+| 4a.9 | Build verification and testing                   | 1d     | Low    | ✅ Done                  |
 
 **Total Effort**: 9 days
 
 ### Spans Produced
 
-| Span Name                    | Location           | Key Attributes                                                   |
-| ---------------------------- | ------------------ | ---------------------------------------------------------------- |
-| `consensus.round`            | `RCLConsensus.cpp` | `round_id`, `ledger_id`, `ledger.seq`, `mode`; link → prev round |
-| `consensus.establish`        | `Consensus.h`      | `converge_percent`, `establish_count`, `proposers`               |
-| `consensus.update_positions` | `Consensus.h`      | `disputes_count`, `converge_percent`, `proposers_agreed/total`   |
-| `consensus.check`            | `Consensus.h`      | `agree/disagree_count`, `threshold_percent`, `result`            |
-| `consensus.mode_change`      | `RCLConsensus.cpp` | `mode.old`, `mode.new`                                           |
+| Span Name                    | Location           | Key Attributes (actually set)                                                                                                 |
+| ---------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `consensus.round`            | `RCLConsensus.cpp` | `round_id`, `ledger_id`, `ledger.seq`, `mode`, `trace_strategy`                                                               |
+| `consensus.establish`        | `Consensus.h`      | `converge_percent`, `establish_count`, `proposers`                                                                            |
+| `consensus.update_positions` | `Consensus.h`      | `converge_percent`, `proposers`, `have_close_time_consensus`, `close_time_threshold`, `disputes_count`, `avalanche_threshold` |
+| `consensus.check`            | `Consensus.h`      | `agree/disagree_count`, `converge_percent`, `have_close_time_consensus`, `threshold_percent`, `result`                        |
+| `consensus.mode_change`      | `RCLConsensus.cpp` | `mode.old`, `mode.new`                                                                                                        |
 
 ### Exit Criteria
 
-- [ ] Establish phase internals fully traced (disputes, convergence, thresholds)
-- [ ] Cross-node correlation works via deterministic trace_id
-- [ ] Strategy switchable via config (`deterministic` / `attribute`)
-- [ ] Consecutive rounds linked via follows-from spans
-- [ ] Build passes with telemetry ON and OFF
-- [ ] No impact on consensus timing
+- [x] Establish phase internals traced (establish, update_positions, check spans)
+- [x] Establish phase fully traced — `disputes_count`, `avalanche_threshold`, dispute `yays`/`nays` all implemented
+- [x] Cross-node correlation works via deterministic trace_id
+- [x] Strategy switchable via config (`deterministic` / `attribute`)
+- [x] Consecutive rounds linked via follows-from spans
+- [x] Build passes with telemetry ON and OFF
+- [x] No impact on consensus timing
 
 See [Phase4_taskList.md](./Phase4_taskList.md) for full task details.
 
@@ -261,7 +280,7 @@ See [Phase4_taskList.md](./Phase4_taskList.md) for full task details.
 validations) to enable true distributed tracing between nodes.
 
 **Status**: Design documented, NOT implemented. Protobuf fields (field 1001)
-and `TraceContextPropagator` class exist. Wiring deferred until Phase 4a is
+and `TraceContextPropagator` free functions exist. Wiring deferred until Phase 4a is
 validated in a multi-node environment.
 
 **Prerequisites**: Phase 4a complete and validated.
@@ -276,25 +295,25 @@ See [Phase4_taskList.md § Phase 4b](./Phase4_taskList.md) for full design.
 
 ### Tasks
 
-| Task | Description                   |
-| ---- | ----------------------------- |
-| 5.1  | Operator runbook              |
-| 5.2  | Grafana dashboards            |
-| 5.3  | Alert definitions             |
-| 5.4  | Collector deployment examples |
-| 5.5  | Developer documentation       |
-| 5.6  | Training materials            |
-| 5.7  | Final integration testing     |
+| Task | Description                   | Status              |
+| ---- | ----------------------------- | ------------------- |
+| 5.1  | Operator runbook              | Complete            |
+| 5.2  | Grafana dashboards            | Complete            |
+| 5.3  | Alert definitions             | Deferred — post-MVP |
+| 5.4  | Collector deployment examples | Complete            |
+| 5.5  | Developer documentation       | Complete            |
+| 5.6  | Training materials            | Deferred — post-MVP |
+| 5.7  | Final integration testing     | Complete            |
 
 ---
 
 ## 6.7 Phase 6: StatsD Metrics Integration (Week 10)
 
-**Objective**: Bridge rippled's existing `beast::insight` StatsD metrics into the OpenTelemetry collection pipeline, exposing 300+ pre-existing metrics alongside span-derived RED metrics in Prometheus/Grafana.
+**Objective**: Bridge xrpld's existing `beast::insight` StatsD metrics into the OpenTelemetry collection pipeline, exposing 300+ pre-existing metrics alongside span-derived RED metrics in Prometheus/Grafana.
 
 ### Background
 
-rippled has a mature metrics framework (`beast::insight`) that emits StatsD-format metrics over UDP. These metrics cover node health, peer networking, RPC performance, job queue, and overlay traffic — data that **does not** overlap with the span-based instrumentation from Phases 1-5. By adding a StatsD receiver to the OTel Collector, both metric sources converge in Prometheus.
+xrpld has a mature metrics framework (`beast::insight`) that emits StatsD-format metrics over UDP. These metrics cover node health, peer networking, RPC performance, job queue, and overlay traffic — data that **does not** overlap with the span-based instrumentation from Phases 1-5. By adding a StatsD receiver to the OTel Collector, both metric sources converge in Prometheus.
 
 ### Metric Inventory
 
@@ -324,8 +343,8 @@ rippled has a mature metrics framework (`beast::insight`) that emits StatsD-form
 | 6.2  | Add `statsd` receiver to OTel Collector config                                                                  |
 | 6.3  | Expose UDP port 8125 in docker-compose.yml                                                                      |
 | 6.4  | Add `[insight]` config to integration test node configs                                                         |
-| 6.5  | Create "Node Health" Grafana dashboard (8 panels)                                                               |
-| 6.6  | Create "Network Traffic" Grafana dashboard (8 panels)                                                           |
+| 6.5  | Create "Node Health" Grafana dashboard (16 panels)                                                              |
+| 6.6  | Create "Network Traffic" Grafana dashboard (10 panels)                                                          |
 | 6.7  | Create "RPC & Pathfinding (StatsD)" Grafana dashboard (8 panels)                                                |
 | 6.8  | Update integration test to verify StatsD metrics in Prometheus                                                  |
 | 6.9  | Update TESTING.md and telemetry-runbook.md                                                                      |
@@ -338,204 +357,24 @@ The `StatsDMeterImpl` in `StatsDCollector.cpp:706` sends metrics with `|m` suffi
 
 ### New Grafana Dashboards
 
-**Node Health** (`statsd-node-health.json`, uid: `rippled-statsd-node-health`):
+**Node Health** (`statsd-node-health.json`, uid: `xrpld-statsd-node-health`):
 
-- Validated/Published Ledger Age, Operating Mode Duration/Transitions, I/O Latency, Job Queue Depth, Ledger Fetch Rate, Ledger History Mismatches
+- Validated/Published Ledger Age, Operating Mode Duration/Transitions, I/O Latency, Job Queue Depth, Ledger Fetch Rate, Ledger History Mismatches, Key Jobs Execution/Dequeue Time, FullBelowCache Size/Hit Rate, Ledger Publish Gap, State Duration Rate, All Jobs Detail
 
-**Network Traffic** (`statsd-network-traffic.json`, uid: `rippled-statsd-network`):
+**Network Traffic** (`statsd-network-traffic.json`, uid: `xrpld-statsd-network`):
 
-- Active Inbound/Outbound Peers, Peer Disconnects, Total Bytes/Messages In/Out, Transaction/Proposal/Validation Traffic, Top Traffic Categories
+- Active Inbound/Outbound Peers, Peer Disconnects, Total Bytes/Messages In/Out, Transaction/Proposal/Validation Traffic, Top Traffic Categories, Duplicate Traffic, All Traffic Categories Detail
 
-**RPC & Pathfinding (StatsD)** (`statsd-rpc-pathfinding.json`, uid: `rippled-statsd-rpc`):
+**RPC & Pathfinding (StatsD)** (`statsd-rpc-pathfinding.json`, uid: `xrpld-statsd-rpc`):
 
 - RPC Request Rate, Response Time p95/p50, Response Size p95/p50, Pathfinding Fast/Full Duration, Resource Warnings/Drops, Response Time Heatmap
 
 ### Exit Criteria
 
-- [ ] StatsD metrics visible in Prometheus (`curl localhost:9090/api/v1/query?query=rippled_LedgerMaster_Validated_Ledger_Age`)
+- [ ] StatsD metrics visible in Prometheus (`curl localhost:9090/api/v1/query?query=xrpld_LedgerMaster_Validated_Ledger_Age`)
 - [ ] All 3 new Grafana dashboards load without errors
 - [ ] Integration test verifies at least core StatsD metrics (ledger age, peer counts, RPC requests)
-- [ ] ~~Meter metrics (`warn`, `drop`) flow correctly after `|m` → `|c` fix~~ — DEFERRED (breaking change, tracked separately; resolved by Phase 7's OTel Counter mapping)
-
----
-
-## 6.8 Phase 7: Native OTel Metrics Migration (Weeks 11-12)
-
-**Objective**: Replace `StatsDCollector` with a native OpenTelemetry Metrics SDK implementation behind the existing `beast::insight::Collector` interface, eliminating the StatsD UDP dependency and unifying traces and metrics into a single OTLP pipeline.
-
-### Motivation: Why Migrate from StatsD to Native OTel Metrics
-
-The Phase 6 StatsD bridge was a pragmatic first step, but it retains inherent limitations that native OTel export resolves.
-
-#### What We Gain
-
-1. **Unified telemetry pipeline** — Traces and metrics export via the same OTLP/HTTP endpoint to the same OTel Collector. One protocol, one endpoint, one config. Eliminates the split-brain architecture of "OTLP for traces, StatsD UDP for metrics."
-
-2. **Eliminates StatsD UDP limitations** — StatsD is fire-and-forget over UDP with no delivery guarantees, no backpressure, 1472-byte MTU packet fragmentation, and text-based encoding overhead. OTLP uses HTTP/gRPC with retries, binary protobuf encoding, and connection-level flow control.
-
-3. **Fixes the `|m` wire format issue** — The `StatsDMeterImpl` uses non-standard `|m` StatsD type that the OTel StatsD receiver silently drops. Native OTel counters eliminate this problem entirely (Phase 6 Task 6.1 — DEFERRED becomes resolved).
-
-4. **Richer metric semantics** — OTel Metrics SDK supports explicit histogram bucket boundaries, exemplars (linking metrics to traces), resource attributes, and metric views. StatsD has no concept of these.
-
-5. **Removes infrastructure dependency** — No more StatsD receiver needed in the OTel Collector. One less receiver to configure, monitor, and debug. Simplifies the collector YAML.
-
-6. **Metric-to-trace correlation** — OTel metrics and traces share the same resource attributes (service.name, service.instance.id). Grafana can link from a metric spike directly to the traces that caused it — impossible with StatsD-sourced metrics.
-
-7. **Production-grade export** — OTel's `PeriodicMetricReader` provides configurable export intervals, batch sizes, timeout handling, and graceful shutdown — all built into the SDK rather than hand-rolled in `StatsDCollectorImp`.
-
-#### What We Lose
-
-1. **StatsD ecosystem compatibility** — Operators using external StatsD-compatible backends (Datadog Agent, Graphite, Telegraph) will need to switch to OTLP-compatible backends or keep `server=statsd` as a fallback.
-
-2. **Simplicity of UDP** — StatsD's UDP fire-and-forget model is dead simple and has zero connection management. OTLP/HTTP requires a TCP connection, TLS negotiation (in production), and retry logic. The OTel SDK handles this, but it's more moving parts.
-
-3. **Slightly higher memory** — OTel SDK maintains internal aggregation state for metrics before export. StatsD just formats and sends strings. Expected overhead: ~1-2 MB additional for metric state.
-
-4. **Dependency on OTel C++ Metrics SDK stability** — The Metrics SDK is GA since 1.0 and on version 1.18.0, but it's less battle-tested than the tracing SDK in the C++ ecosystem.
-
-#### Decision
-
-The gains (unified pipeline, delivery guarantees, metric-trace correlation, simpler collector config) significantly outweigh the losses. `StatsDCollector` is retained as a fallback via `server=statsd` for operators who need StatsD ecosystem compatibility during the transition period.
-
-### Architecture
-
-#### Class Hierarchy (after Phase 7)
-
-```
-beast::insight::Collector (abstract interface — unchanged)
-    |
-    +-- StatsDCollector        (existing — retained as fallback, deprecated)
-    |     +-- StatsDCounterImpl    -> StatsD |c over UDP
-    |     +-- StatsDGaugeImpl      -> StatsD |g over UDP
-    |     +-- StatsDMeterImpl      -> StatsD |m over UDP (non-standard)
-    |     +-- StatsDEventImpl      -> StatsD |ms over UDP
-    |     +-- StatsDHookImpl       -> 1s periodic callback
-    |
-    +-- NullCollector          (existing — unchanged, used when disabled)
-    |     +-- NullCounterImpl      -> no-op
-    |     +-- NullGaugeImpl        -> no-op
-    |     +-- NullMeterImpl        -> no-op
-    |     +-- NullEventImpl        -> no-op
-    |     +-- NullHookImpl         -> no-op
-    |
-    +-- OTelCollector          (NEW — Phase 7)
-          +-- OTelCounterImpl      -> otel::Counter<int64_t>
-          +-- OTelGaugeImpl        -> otel::ObservableGauge<uint64_t>
-          +-- OTelMeterImpl        -> otel::Counter<uint64_t>
-          +-- OTelEventImpl        -> otel::Histogram<double>
-          +-- OTelHookImpl         -> 1s periodic callback (same pattern)
-```
-
-#### Data Flow (after Phase 7)
-
-```mermaid
-graph LR
-    subgraph rippledNode["rippled Node"]
-        A["Trace Macros<br/>XRPL_TRACE_SPAN"]
-        B["beast::insight<br/>OTelCollector"]
-    end
-
-    subgraph collector["OTel Collector  :4317 / :4318"]
-        direction TB
-        R1["OTLP Receiver<br/>:4317 gRPC  |  :4318 HTTP"]
-        BP["Batch Processor"]
-        SM["SpanMetrics Connector"]
-
-        R1 --> BP
-        BP --> SM
-    end
-
-    subgraph backends["Trace Backends"]
-        D["Jaeger / Tempo"]
-    end
-
-    subgraph metrics["Metrics Stack"]
-        E["Prometheus  :9090<br/>scrapes :8889<br/>span-derived + native OTel metrics"]
-    end
-
-    subgraph viz["Visualization"]
-        F["Grafana  :3000"]
-    end
-
-    A -->|"OTLP/HTTP :4318<br/>(traces)"| R1
-    B -->|"OTLP/HTTP :4318<br/>(metrics)"| R1
-
-    BP -->|"OTLP/gRPC"| D
-    SM -->|"RED metrics"| E
-    R1 -->|"rippled_* metrics<br/>(native OTLP)"| E
-
-    E --> F
-    D --> F
-
-    style A fill:#4a90d9,color:#fff,stroke:#2a6db5
-    style B fill:#d9534f,color:#fff,stroke:#b52d2d
-    style R1 fill:#5cb85c,color:#fff,stroke:#3d8b3d
-    style BP fill:#449d44,color:#fff,stroke:#2d6e2d
-    style SM fill:#449d44,color:#fff,stroke:#2d6e2d
-    style D fill:#f0ad4e,color:#000,stroke:#c78c2e
-    style E fill:#f0ad4e,color:#000,stroke:#c78c2e
-    style F fill:#5bc0de,color:#000,stroke:#3aa8c1
-    style rippledNode fill:#1a2633,color:#ccc,stroke:#4a90d9
-    style collector fill:#1a3320,color:#ccc,stroke:#5cb85c
-    style backends fill:#332a1a,color:#ccc,stroke:#f0ad4e
-    style metrics fill:#332a1a,color:#ccc,stroke:#f0ad4e
-    style viz fill:#1a2d33,color:#ccc,stroke:#5bc0de
-```
-
-**Key change**: StatsD receiver removed from collector. Both traces and metrics enter via OTLP receiver on the same port.
-
-#### Configuration
-
-```ini
-# [insight] section — new "otel" server option
-[insight]
-server=otel              # NEW: uses OTel OTLP metrics exporter
-prefix=rippled           # metric name prefix (preserved)
-
-# Endpoint and auth inherited from [telemetry] section:
-[telemetry]
-enabled=1
-endpoint=http://localhost:4318/v1/traces
-```
-
-The `OTelCollector` reads the OTLP endpoint from `[telemetry]` config (replacing `/v1/traces` with `/v1/metrics` for the metrics exporter). No additional config keys needed.
-
-**Backward compatibility**: `server=statsd` continues to work exactly as before.
-
-See [Phase7_taskList.md](./Phase7_taskList.md) for detailed per-task breakdown.
-
-### Instrument Type Mapping
-
-| beast::insight         | OTel Metrics SDK                 | Rationale                                                        |
-| ---------------------- | -------------------------------- | ---------------------------------------------------------------- |
-| Counter (int64, `\|c`) | `Counter<int64_t>`               | Direct 1:1 mapping                                               |
-| Gauge (uint64, `\|g`)  | `ObservableGauge<uint64_t>`      | Async callback matches existing Hook polling pattern             |
-| Meter (uint64, `\|m`)  | `Counter<uint64_t>`              | Fixes non-standard wire format; meters are semantically counters |
-| Event (ms, `\|ms`)     | `Histogram<double>`              | Duration distributions with explicit bucket boundaries           |
-| Hook (1s callback)     | `PeriodicMetricReader` alignment | Same 1s collection interval                                      |
-
-### Tasks
-
-| Task | Description                                                               |
-| ---- | ------------------------------------------------------------------------- |
-| 7.1  | Add OTel Metrics SDK to build deps (conan/cmake)                          |
-| 7.2  | Implement `OTelCollector` class (~400-500 lines)                          |
-| 7.3  | Update `CollectorManager` — add `server=otel`                             |
-| 7.4  | Update OTel Collector YAML (add metrics pipeline, remove StatsD receiver) |
-| 7.5  | Preserve metric names in Prometheus (naming strategy)                     |
-| 7.6  | Update Grafana dashboards (if names change)                               |
-| 7.7  | Update integration tests                                                  |
-| 7.8  | Update documentation (runbook, reference docs)                            |
-
-### Exit Criteria
-
-- [ ] All 255+ metrics visible in Prometheus via OTLP pipeline (no StatsD receiver)
-- [ ] `server=otel` is the default in development docker-compose
-- [ ] `server=statsd` still works as a fallback
-- [ ] Existing Grafana dashboards display data correctly
-- [ ] Integration test passes with OTLP-only metrics pipeline
-- [ ] No performance regression vs StatsD baseline (< 1% CPU overhead)
-- [ ] Deferred Task 6.1 (`|m` wire format) no longer relevant
+- [ ] ~~Meter metrics (`warn`, `drop`) flow correctly after `|m` → `|c` fix~~ — DEFERRED (breaking change, tracked separately)
 
 ---
 
@@ -607,7 +446,7 @@ flowchart TB
 
     subgraph run["🏃 RUN (Week 6-9)"]
         direction LR
-        r1[Consensus Tracing] ~~~ r2[Validator, Amendment,<br/>SHAMap Tracing] ~~~ r3[Full Correlation] ~~~ r4[Production Deploy]
+        r1[Consensus Tracing] ~~~ r2[Establish Phase<br/>& Cross-Node Correlation] ~~~ r3[StatsD Integration] ~~~ r4[Production Deploy]
     end
 
     crawl --> walk --> run
@@ -635,7 +474,7 @@ flowchart TB
 
 - **CRAWL (Weeks 1-2)**: Minimal investment -- set up the SDK, instrument RPC and PathFinding/TxQ handlers, and verify on a single node. Delivers immediate latency visibility.
 - **WALK (Weeks 3-5)**: Expand to transaction lifecycle tracing, fee escalation, cross-node context propagation, and basic Grafana dashboards. This is where distributed tracing starts working.
-- **RUN (Weeks 6-9)**: Full consensus instrumentation, validator/amendment/SHAMap tracing, end-to-end correlation, and production deployment with sampling and alerting.
+- **RUN (Weeks 6-9)**: Full consensus instrumentation, establish-phase gap fill, cross-node correlation, StatsD integration, and production deployment with sampling and alerting.
 - **Arrows (crawl → walk → run)**: Each phase builds on the prior one; you cannot skip ahead because later phases depend on infrastructure established earlier.
 
 ### 6.9.2 Quick Wins (Immediate Value)
@@ -700,17 +539,17 @@ flowchart TB
 - Complete consensus round visibility
 - Phase transition timing
 - Validator proposal tracking
-- Validator list and manifest tracing
-- Amendment voting tracing
-- SHAMap sync tracing
-- Full end-to-end traces (client → RPC → TX → consensus → ledger)
+- ~~Validator list and manifest tracing~~ — descoped
+- ~~Amendment voting tracing~~ — descoped
+- ~~SHAMap sync tracing~~ — descoped
+- Full end-to-end traces (client → RPC → TX → consensus → ledger) — partial (tx-consensus correlation not yet done)
 
-**Code Changes**: ~100 lines across 3 consensus files, plus validator/amendment/SHAMap modules
+**Code Changes**: ~100 lines across 3 consensus files
 
 **Why Do This Last**:
 
 - Highest complexity (consensus is critical path)
-- Validator, amendment, and SHAMap components are lower priority
+- Validator, amendment, and SHAMap components were descoped (lower priority)
 - Requires thorough testing
 - Lower relative value (consensus issues are rarer)
 
@@ -736,7 +575,6 @@ quadrantChart
 
 ---
 
-
 ## 6.13 Definition of Done
 
 > **TxQ** = Transaction Queue | **HA** = High Availability
@@ -745,7 +583,6 @@ Clear, measurable criteria for each phase.
 
 ### 6.13.1 Phase 1: Core Infrastructure
 
-
 | Criterion       | Measurement                                                | Target                       |
 | --------------- | ---------------------------------------------------------- | ---------------------------- |
 | SDK Integration | `cmake --build` succeeds with `-DXRPL_ENABLE_TELEMETRY=ON` | ✅ Compiles                  |
@@ -756,10 +593,8 @@ Clear, measurable criteria for each phase.
 
 **Definition of Done**: All criteria met, PR merged, no regressions in CI.
 
-
 ### 6.13.2 Phase 2: RPC Tracing
 
-
 | Criterion          | Measurement                        | Target                     |
 | ------------------ | ---------------------------------- | -------------------------- |
 | Coverage           | All RPC commands instrumented      | 100% of commands           |
@@ -770,24 +605,23 @@ Clear, measurable criteria for each phase.
 
 **Definition of Done**: RPC traces visible in Tempo for all commands, dashboard shows latency distribution.
 
-
 ### 6.13.3 Phase 3: Transaction Tracing
 
+| Criterion             | Measurement                                       | Target                                                   |
+| --------------------- | ------------------------------------------------- | -------------------------------------------------------- |
+| Local Trace           | Submit → validate → TxQ traced                    | Single-node test passes                                  |
+| Cross-Node            | Context propagates via protobuf                   | Multi-node test passes                                   |
+| Deterministic TraceID | Same trace_id on all nodes for same tx            | Multi-node test: query by txHash[0:16] returns all spans |
+| Relay Ordering        | Protobuf span_id propagation creates parent-child | Tempo trace tree shows relay chain                       |
+| Graceful Degradation  | Old peer drops trace_context                      | Spans still grouped by deterministic trace_id            |
+| Relay Visibility      | relay_count attribute correct                     | Spot check 100 txs                                       |
+| HashRouter            | Deduplication visible in trace                    | Duplicate txs show suppressed=true                       |
+| Performance           | TX throughput overhead                            | <5% degradation                                          |
 
-| Criterion        | Measurement                     | Target                             |
-| ---------------- | ------------------------------- | ---------------------------------- |
-| Local Trace      | Submit → validate → TxQ traced  | Single-node test passes            |
-| Cross-Node       | Context propagates via protobuf | Multi-node test passes             |
-| Relay Visibility | relay_count attribute correct   | Spot check 100 txs                 |
-| HashRouter       | Deduplication visible in trace  | Duplicate txs show suppressed=true |
-| Performance      | TX throughput overhead          | <5% degradation                    |
-
-**Definition of Done**: Transaction traces span 3+ nodes in test network, performance within bounds.
-
+**Definition of Done**: Transaction traces span 3+ nodes in test network with deterministic trace_id correlation, parent-child ordering via protobuf propagation, and performance within bounds.
 
 ### 6.13.4 Phase 4: Consensus Tracing
 
-
 | Criterion            | Measurement                   | Target                    |
 | -------------------- | ----------------------------- | ------------------------- |
 | Round Tracing        | startRound creates root span  | Unit test passes          |
@@ -798,10 +632,8 @@ Clear, measurable criteria for each phase.
 
 **Definition of Done**: Consensus rounds fully traceable, no impact on consensus timing.
 
-
 ### 6.13.5 Phase 5: Production Deployment
 
-
 | Criterion    | Measurement                  | Target                     |
 | ------------ | ---------------------------- | -------------------------- |
 | Collector HA | Multiple collectors deployed | No single point of failure |
@@ -813,18 +645,15 @@ Clear, measurable criteria for each phase.
 
 **Definition of Done**: Telemetry running in production, operators trained, alerts active.
 
-
 ### 6.13.6 Success Metrics Summary
 
-| Phase   | Primary Metric               | Secondary Metric            | Deadline       |
-| ------- | ---------------------------- | --------------------------- | -------------- |
-| Phase 1 | SDK compiles and runs        | Zero overhead when disabled | End of Week 2  |
-| Phase 2 | 100% RPC coverage            | <1ms latency overhead       | End of Week 4  |
-| Phase 3 | Cross-node traces work       | <5% throughput impact       | End of Week 6  |
-| Phase 4 | Consensus fully traced       | No consensus timing impact  | End of Week 8  |
-| Phase 5 | Production deployment        | Operators trained           | End of Week 9  |
-| Phase 6 | StatsD metrics in Prometheus | 3 dashboards operational    | End of Week 10 |
-| Phase 7 | All metrics via OTLP         | No StatsD dependency        | End of Week 12 |
+| Phase   | Primary Metric         | Secondary Metric            | Deadline      |
+| ------- | ---------------------- | --------------------------- | ------------- |
+| Phase 1 | SDK compiles and runs  | Zero overhead when disabled | End of Week 2 |
+| Phase 2 | 100% RPC coverage      | <1ms latency overhead       | End of Week 4 |
+| Phase 3 | Cross-node traces work | <5% throughput impact       | End of Week 6 |
+| Phase 4 | Consensus fully traced | No consensus timing impact  | End of Week 8 |
+| Phase 5 | Production deployment  | Operators trained           | End of Week 9 |
 
 ---
 

OpenTelemetryPlan/07-observability-backends.md

@@ -92,13 +92,13 @@ flowchart TD
 ```mermaid
 flowchart TB
     subgraph validators["Validator Nodes"]
-        v1[rippled<br/>Validator 1]
-        v2[rippled<br/>Validator 2]
+        v1[xrpld<br/>Validator 1]
+        v2[xrpld<br/>Validator 2]
     end
 
     subgraph stock["Stock Nodes"]
-        s1[rippled<br/>Stock 1]
-        s2[rippled<br/>Stock 2]
+        s1[xrpld<br/>Stock 1]
+        s2[xrpld<br/>Stock 2]
     end
 
     subgraph collector["OTel Collector Cluster"]
@@ -140,7 +140,7 @@ flowchart TB
 
 **Reading the diagram:**
 
-- **Validator / Stock Nodes**: All rippled nodes emit trace data via OTLP. Validators and stock nodes are grouped separately because they may reside in different network zones.
+- **Validator / Stock Nodes**: All xrpld nodes emit trace data via OTLP. Validators and stock nodes are grouped separately because they may reside in different network zones.
 - **Collector Cluster (DC1, DC2)**: Regional collectors receive OTLP from nodes in their datacenter, apply processing (sampling, enrichment), and fan out to multiple backends.
 - **Storage Backends**: Tempo and Elastic provide queryable trace storage; S3/GCS Archive provides long-term cold storage for compliance or post-incident analysis.
 - **Grafana Dashboards**: The single visualization layer that queries both Tempo and Elastic, giving operators a unified view of all traces.
@@ -160,7 +160,7 @@ flowchart TB
 | **DaemonSet** | Collector per host   | Shared resources         | Complexity              |
 | **Gateway**   | Central collector(s) | Centralized processing   | Single point of failure |
 
-**Recommendation**: Use **Gateway** pattern with regional collectors for rippled networks:
+**Recommendation**: Use **Gateway** pattern with regional collectors for xrpld networks:
 
 - One collector cluster per datacenter/region
 - Tail-based sampling at collector level
@@ -197,7 +197,7 @@ flowchart LR
 
 **Reading the diagram:**
 
-- **Head Sampling (Node)**: The first filter -- each rippled node decides whether to sample a trace at creation time (default 100%, recommended 10% in production). This controls the volume leaving the node.
+- **Head Sampling (Node)**: The first filter -- each xrpld node decides whether to sample a trace at creation time (default 100%, recommended 10% in production). This controls the volume leaving the node.
 - **Tail Sampling (Collector)**: The second filter -- the collector inspects completed traces and applies rules: keep all errors, keep anything slower than 5 seconds, and keep 10% of the remainder.
 - **Arrow head → tail**: All head-sampled traces flow to the collector, where tail sampling further reduces volume while preserving the most valuable data.
 - **Final Traces**: The output after both sampling stages; this is what gets stored and queried. The two-stage approach balances cost with debuggability.
@@ -226,15 +226,15 @@ flowchart LR
 
 ## 7.6 Grafana Dashboard Examples
 
-Pre-built dashboards for rippled observability.
+Pre-built dashboards for xrpld observability.
 
 ### 7.6.1 Consensus Health Dashboard
 
 ```json
 {
-  "title": "rippled Consensus Health",
-  "uid": "rippled-consensus-health",
-  "tags": ["rippled", "consensus", "tracing"],
+  "title": "xrpld Consensus Health",
+  "uid": "xrpld-consensus-health",
+  "tags": ["xrpld", "consensus", "tracing"],
   "panels": [
     {
       "title": "Consensus Round Duration",
@@ -243,7 +243,7 @@ Pre-built dashboards for rippled observability.
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"consensus.round\"} | avg(duration) by (resource.service.instance.id)"
+          "query": "{resource.service.name=\"xrpld\" && name=\"consensus.round\"} | avg(duration) by (resource.service.instance.id)"
         }
       ],
       "fieldConfig": {
@@ -267,7 +267,7 @@ Pre-built dashboards for rippled observability.
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=~\"consensus.phase.*\"} | avg(duration) by (name)"
+          "query": "{resource.service.name=\"xrpld\" && name=~\"consensus.phase.*\"} | avg(duration) by (name)"
         }
       ],
       "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 }
@@ -279,7 +279,7 @@ Pre-built dashboards for rippled observability.
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"consensus.round\"} | avg(span.xrpl.consensus.proposers)"
+          "query": "{resource.service.name=\"xrpld\" && name=\"consensus.round\"} | avg(span.xrpl.consensus.proposers)"
         }
       ],
       "gridPos": { "h": 4, "w": 6, "x": 0, "y": 8 }
@@ -291,7 +291,7 @@ Pre-built dashboards for rippled observability.
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"consensus.round\"} | duration > 5s"
+          "query": "{resource.service.name=\"xrpld\" && name=\"consensus.round\"} | duration > 5s"
         }
       ],
       "gridPos": { "h": 8, "w": 24, "x": 0, "y": 12 }
@@ -304,8 +304,8 @@ Pre-built dashboards for rippled observability.
 
 ```json
 {
-  "title": "rippled Node Overview",
-  "uid": "rippled-node-overview",
+  "title": "xrpld Node Overview",
+  "uid": "xrpld-node-overview",
   "panels": [
     {
       "title": "Active Nodes",
@@ -314,7 +314,7 @@ Pre-built dashboards for rippled observability.
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\"} | count_over_time() by (resource.service.instance.id) | count()"
+          "query": "{resource.service.name=\"xrpld\"} | count_over_time() by (resource.service.instance.id) | count()"
         }
       ],
       "gridPos": { "h": 4, "w": 4, "x": 0, "y": 0 }
@@ -326,7 +326,7 @@ Pre-built dashboards for rippled observability.
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.receive\"} | count()"
+          "query": "{resource.service.name=\"xrpld\" && name=\"tx.receive\"} | count()"
         }
       ],
       "gridPos": { "h": 4, "w": 4, "x": 4, "y": 0 }
@@ -338,7 +338,7 @@ Pre-built dashboards for rippled observability.
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && status.code=error} | rate() / {resource.service.name=\"rippled\"} | rate() * 100"
+          "query": "{resource.service.name=\"xrpld\" && status.code=error} | rate() / {resource.service.name=\"xrpld\"} | rate() * 100"
         }
       ],
       "fieldConfig": {
@@ -373,8 +373,8 @@ Pre-built dashboards for rippled observability.
 apiVersion: 1
 
 groups:
-  - name: rippled-tracing-alerts
-    folder: rippled
+  - name: xrpld-tracing-alerts
+    folder: xrpld
     interval: 1m
     rules:
       - uid: consensus-slow
@@ -385,7 +385,7 @@ groups:
             datasourceUid: tempo
             model:
               queryType: traceql
-              query: '{resource.service.name="rippled" && name="consensus.round"} | avg(duration) > 5s'
+              query: '{resource.service.name="xrpld" && name="consensus.round"} | avg(duration) > 5s'
               # Note: Verify TraceQL aggregate queries are supported by your
               # Tempo version. Aggregate alerting (e.g., avg(duration)) requires
               # Tempo 2.3+ with TraceQL metrics enabled.
@@ -404,7 +404,7 @@ groups:
             datasourceUid: tempo
             model:
               queryType: traceql
-              query: '{resource.service.name="rippled" && name=~"rpc.command.*" && status.code=error} | rate() > 0.05'
+              query: '{resource.service.name="xrpld" && name=~"rpc.command.*" && status.code=error} | rate() > 0.05'
               # Note: Verify TraceQL aggregate queries are supported by your
               # Tempo version. Aggregate alerting (e.g., rate()) requires
               # Tempo 2.3+ with TraceQL metrics enabled.
@@ -422,7 +422,7 @@ groups:
             datasourceUid: tempo
             model:
               queryType: traceql
-              query: '{resource.service.name="rippled" && name="tx.receive"} | rate() < 10'
+              query: '{resource.service.name="xrpld" && name="tx.receive"} | rate() < 10'
         for: 10m
         annotations:
           summary: Transaction throughput below threshold
@@ -436,13 +436,13 @@ groups:
 
 > **OTLP** = OpenTelemetry Protocol
 
-How to correlate OpenTelemetry traces with existing rippled observability.
+How to correlate OpenTelemetry traces with existing xrpld observability.
 
 ### 7.7.1 Correlation Architecture
 
 ```mermaid
 flowchart TB
-    subgraph rippled["rippled Node"]
+    subgraph xrpld["xrpld Node"]
         otel[OpenTelemetry<br/>Spans]
         perflog[PerfLog<br/>JSON Logs]
         insight[Beast Insight<br/>StatsD Metrics]
@@ -479,7 +479,7 @@ flowchart TB
     logs --> corr
     metrics --> corr
 
-    style rippled fill:#0d47a1,stroke:#082f6a,color:#fff
+    style xrpld fill:#0d47a1,stroke:#082f6a,color:#fff
     style collectors fill:#bf360c,stroke:#8c2809,color:#fff
     style storage fill:#1b5e20,stroke:#0d3d14,color:#fff
     style grafana fill:#4a148c,stroke:#2e0d57,color:#fff
@@ -500,7 +500,7 @@ flowchart TB
 
 **Reading the diagram:**
 
-- **rippled Node (three sources)**: A single node emits three independent data streams -- OpenTelemetry spans, PerfLog JSON logs, and Beast Insight StatsD metrics.
+- **xrpld Node (three sources)**: A single node emits three independent data streams -- OpenTelemetry spans, PerfLog JSON logs, and Beast Insight StatsD metrics.
 - **Data Collection layer**: Each stream has its own collector -- OTel Collector for spans, Promtail/Fluentd for logs, and a StatsD exporter for metrics. They operate independently.
 - **Storage layer (Tempo, Loki, Prometheus)**: Each data type lands in a purpose-built store optimized for its query patterns (trace search, log grep, metric aggregation).
 - **Grafana Correlation Panel**: The key integration point -- Grafana queries all three stores and links them via shared fields (`trace_id`, `xrpl.tx.hash`, `ledger_seq`), enabling a single-pane debugging experience.
@@ -522,7 +522,7 @@ flowchart TB
 
 ```
 # In Grafana Explore with Tempo
-{resource.service.name="rippled" && span.xrpl.tx.hash="ABC123..."}
+{resource.service.name="xrpld" && span.xrpl.tx.hash="ABC123..."}
 ```
 
 **Step 2: Get the trace_id from the trace view**
@@ -535,14 +535,14 @@ Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736
 
 ```
 # In Grafana Explore with Loki
-{job="rippled"} |= "4bf92f3577b34da6a3ce929d0e0e4736"
+{job="xrpld"} |= "4bf92f3577b34da6a3ce929d0e0e4736"
 ```
 
 **Step 4: Check Insight metrics for the time window**
 
 ```
 # In Grafana with Prometheus
-rate(rippled_tx_applied_total[1m])
+rate(xrpld_tx_applied_total[1m])
   @ timestamp_from_trace
 ```
 
@@ -550,8 +550,8 @@ rate(rippled_tx_applied_total[1m])
 
 ```json
 {
-  "title": "rippled Unified Observability",
-  "uid": "rippled-unified",
+  "title": "xrpld Unified Observability",
+  "uid": "xrpld-unified",
   "panels": [
     {
       "title": "Transaction Latency (Traces)",
@@ -560,7 +560,7 @@ rate(rippled_tx_applied_total[1m])
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.receive\"} | histogram_over_time(duration)"
+          "query": "{resource.service.name=\"xrpld\" && name=\"tx.receive\"} | histogram_over_time(duration)"
         }
       ],
       "gridPos": { "h": 6, "w": 8, "x": 0, "y": 0 }
@@ -571,7 +571,7 @@ rate(rippled_tx_applied_total[1m])
       "datasource": "Prometheus",
       "targets": [
         {
-          "expr": "rate(rippled_tx_received_total[5m])",
+          "expr": "rate(xrpld_tx_received_total[5m])",
           "legendFormat": "{{ instance }}"
         }
       ],
@@ -580,7 +580,7 @@ rate(rippled_tx_applied_total[1m])
           "links": [
             {
               "title": "View traces",
-              "url": "/explore?left={\"datasource\":\"Tempo\",\"query\":\"{resource.service.name=\\\"rippled\\\" && name=\\\"tx.receive\\\"}\"}"
+              "url": "/explore?left={\"datasource\":\"Tempo\",\"query\":\"{resource.service.name=\\\"xrpld\\\" && name=\\\"tx.receive\\\"}\"}"
             }
           ]
         }
@@ -593,7 +593,7 @@ rate(rippled_tx_applied_total[1m])
       "datasource": "Loki",
       "targets": [
         {
-          "expr": "{job=\"rippled\"} | json"
+          "expr": "{job=\"xrpld\"} | json"
         }
       ],
       "gridPos": { "h": 6, "w": 8, "x": 16, "y": 0 }
@@ -605,7 +605,7 @@ rate(rippled_tx_applied_total[1m])
       "targets": [
         {
           "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\"}"
+          "query": "{resource.service.name=\"xrpld\"}"
         }
       ],
       "fieldConfig": {
@@ -622,7 +622,7 @@ rate(rippled_tx_applied_total[1m])
                   },
                   {
                     "title": "View logs",
-                    "url": "/explore?left={\"datasource\":\"Loki\",\"query\":\"{job=\\\"rippled\\\"} |= \\\"${__value.raw}\\\"\"}"
+                    "url": "/explore?left={\"datasource\":\"Loki\",\"query\":\"{job=\\\"xrpld\\\"} |= \\\"${__value.raw}\\\"\"}"
                   }
                 ]
               }

OpenTelemetryPlan/08-appendix.md

@@ -26,7 +26,7 @@
 | **Resource**          | Entity producing telemetry (service, host, etc.)           |
 | **Instrumentation**   | Code that creates telemetry data                           |
 
-### rippled-Specific Terms
+### xrpld-Specific Terms
 
 | Term              | Definition                                                    |
 | ----------------- | ------------------------------------------------------------- |
@@ -36,8 +36,8 @@
 | **Validation**    | Validator's signature on a closed ledger                      |
 | **HashRouter**    | Component for transaction deduplication                       |
 | **JobQueue**      | Thread pool for asynchronous task execution                   |
-| **PerfLog**       | Existing performance logging system in rippled                |
-| **Beast Insight** | Existing metrics framework in rippled                         |
+| **PerfLog**       | Existing performance logging system in xrpld                  |
+| **Beast Insight** | Existing metrics framework in xrpld                           |
 | **PathFinding**   | Payment path computation engine for cross-currency payments   |
 | **TxQ**           | Transaction queue managing fee-based prioritization           |
 | **LoadManager**   | Dynamic fee escalation based on network load                  |
@@ -146,13 +146,13 @@ flowchart TB
 6. [W3C Baggage](https://www.w3.org/TR/baggage/)
 7. [Protocol Buffers](https://protobuf.dev/)
 
-### rippled Resources
+### xrpld Resources
 
-8. [rippled Source Code](https://github.com/XRPLF/rippled)
+8. [xrpld Source Code](https://github.com/XRPLF/rippled)
 9. [XRP Ledger Documentation](https://xrpl.org/docs/)
-10. [rippled Overlay README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/overlay/README.md)
-11. [rippled RPC README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/rpc/README.md)
-12. [rippled Consensus README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/app/consensus/README.md)
+10. [xrpld Overlay README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/overlay/README.md)
+11. [xrpld RPC README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/rpc/README.md)
+12. [xrpld Consensus README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/app/consensus/README.md)
 
 ---
 
@@ -174,11 +174,11 @@ flowchart TB
 | -------------------------------------------------------------------- | -------------------------------------------- |
 | [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)                       | Master overview and executive summary        |
 | [00-tracing-fundamentals.md](./00-tracing-fundamentals.md)           | Distributed tracing concepts and OTel primer |
-| [01-architecture-analysis.md](./01-architecture-analysis.md)         | rippled architecture and trace points        |
+| [01-architecture-analysis.md](./01-architecture-analysis.md)         | xrpld architecture and trace points          |
 | [02-design-decisions.md](./02-design-decisions.md)                   | SDK selection, exporters, span conventions   |
 | [03-implementation-strategy.md](./03-implementation-strategy.md)     | Directory structure, performance analysis    |
 | [04-code-samples.md](./04-code-samples.md)                           | C++ code examples for all components         |
-| [05-configuration-reference.md](./05-configuration-reference.md)     | rippled config, CMake, Collector configs     |
+| [05-configuration-reference.md](./05-configuration-reference.md)     | xrpld config, CMake, Collector configs       |
 | [06-implementation-phases.md](./06-implementation-phases.md)         | Timeline, tasks, risks, success metrics      |
 | [07-observability-backends.md](./07-observability-backends.md)       | Backend selection and architecture           |
 | [08-appendix.md](./08-appendix.md)                                   | Glossary, references, version history        |
@@ -195,7 +195,6 @@ flowchart TB
 | [Phase4_taskList.md](./Phase4_taskList.md)                                 | Transaction lifecycle tracing                       |
 | [Phase5_taskList.md](./Phase5_taskList.md)                                 | Ledger processing & advanced tracing                |
 | [Phase5_IntegrationTest_taskList.md](./Phase5_IntegrationTest_taskList.md) | Observability stack integration tests               |
-| [Phase7_taskList.md](./Phase7_taskList.md)                                 | Native OTel metrics migration                       |
 | [presentation.md](./presentation.md)                                       | Presentation slides for OpenTelemetry plan overview |
 
 ---

OpenTelemetryPlan/OpenTelemetryPlan.md

@@ -1,10 +1,10 @@
-# [OpenTelemetry](00-tracing-fundamentals.md) Distributed Tracing Implementation Plan for rippled (xrpld)
+# [OpenTelemetry](00-tracing-fundamentals.md) Distributed Tracing Implementation Plan for xrpld (xrpld)
 
 ## Executive Summary
 
 > **OTLP** = OpenTelemetry Protocol
 
-This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the rippled XRP Ledger node software. The plan addresses the unique challenges of a decentralized peer-to-peer system where trace context must propagate across network boundaries between independent nodes.
+This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the xrpld XRP Ledger node software. The plan addresses the unique challenges of a decentralized peer-to-peer system where trace context must propagate across network boundaries between independent nodes.
 
 ### Key Benefits
 
@@ -101,11 +101,11 @@ flowchart TB
 | Section | Document                                                       | Description                                                            |
 | ------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
 | **0**   | [Tracing Fundamentals](./00-tracing-fundamentals.md)           | Distributed tracing concepts, span relationships, context propagation  |
-| **1**   | [Architecture Analysis](./01-architecture-analysis.md)         | rippled component analysis, trace points, instrumentation priorities   |
+| **1**   | [Architecture Analysis](./01-architecture-analysis.md)         | xrpld component analysis, trace points, instrumentation priorities     |
 | **2**   | [Design Decisions](./02-design-decisions.md)                   | SDK selection, exporters, span naming, attributes, context propagation |
 | **3**   | [Implementation Strategy](./03-implementation-strategy.md)     | Directory structure, key principles, performance optimization          |
 | **4**   | [Code Samples](./04-code-samples.md)                           | C++ implementation examples for core infrastructure and key modules    |
-| **5**   | [Configuration Reference](./05-configuration-reference.md)     | rippled config, CMake integration, Collector configurations            |
+| **5**   | [Configuration Reference](./05-configuration-reference.md)     | xrpld config, CMake integration, Collector configurations              |
 | **6**   | [Implementation Phases](./06-implementation-phases.md)         | 5-phase timeline, tasks, risks, success metrics                        |
 | **7**   | [Observability Backends](./07-observability-backends.md)       | Backend selection guide and production architecture                    |
 | **8**   | [Appendix](./08-appendix.md)                                   | Glossary, references, version history                                  |
@@ -116,7 +116,7 @@ flowchart TB
 
 ## 0. Tracing Fundamentals
 
-This document introduces distributed tracing concepts for readers unfamiliar with the domain. It covers what traces and spans are, how parent-child and follows-from relationships model causality, how context propagates across service boundaries, and how sampling controls data volume. It also maps these concepts to rippled-specific scenarios like transaction relay and consensus.
+This document introduces distributed tracing concepts for readers unfamiliar with the domain. It covers what traces and spans are, how parent-child and follows-from relationships model causality, how context propagates across service boundaries, and how sampling controls data volume. It also maps these concepts to xrpld-specific scenarios like transaction relay and consensus.
 
 ➡️ **[Read Tracing Fundamentals](./00-tracing-fundamentals.md)**
 
@@ -126,7 +126,7 @@ This document introduces distributed tracing concepts for readers unfamiliar wit
 
 > **WS** = WebSocket | **TxQ** = Transaction Queue
 
-The rippled node consists of several key components that require instrumentation for comprehensive distributed tracing. The main areas include the RPC server (HTTP/WebSocket), Overlay P2P network, Consensus mechanism (RCLConsensus), JobQueue for async task execution, PathFinding, Transaction Queue (TxQ), fee escalation (LoadManager), ledger acquisition, validator management, and existing observability infrastructure (PerfLog, Insight/StatsD, Journal logging).
+The xrpld node consists of several key components that require instrumentation for comprehensive distributed tracing. The main areas include the RPC server (HTTP/WebSocket), Overlay P2P network, Consensus mechanism (RCLConsensus), JobQueue for async task execution, PathFinding, Transaction Queue (TxQ), fee escalation (LoadManager), ledger acquisition, validator management, and existing observability infrastructure (PerfLog, Insight/StatsD, Journal logging).
 
 Key trace points span across transaction submission via RPC, peer-to-peer message propagation, consensus round execution, ledger building, path computation, transaction queue behavior, fee escalation, and validator health. The implementation prioritizes high-value, low-risk components first: RPC handlers provide immediate value with minimal risk, while consensus tracing requires careful implementation to avoid timing impacts.
 
@@ -150,7 +150,7 @@ Span naming follows a hierarchical `<component>.<operation>` convention (e.g., `
 
 ## 3. Implementation Strategy
 
-The telemetry code is organized under `include/xrpl/telemetry/` for headers and `src/libxrpl/telemetry/` for implementation. Key principles include RAII-based span management via `SpanGuard`, conditional compilation with `XRPL_ENABLE_TELEMETRY`, and minimal runtime overhead through batch processing and efficient sampling.
+The telemetry code is organized under `include/xrpl/telemetry/` for headers and `src/libxrpl/telemetry/` for implementation. Key principles include RAII-based span management via `SpanGuard` (with `discard()` for dropping unwanted spans), a `FilteringSpanProcessor` that intercepts `OnEnd()` to prevent discarded spans from entering the export pipeline, conditional compilation with `XRPL_ENABLE_TELEMETRY`, and minimal runtime overhead through batch processing and efficient sampling.
 
 Performance optimization strategies include probabilistic head sampling (10% default), tail-based sampling at the collector for errors and slow traces, batch export to reduce network overhead, and conditional instrumentation that compiles to no-ops when disabled.
 
@@ -163,8 +163,9 @@ Performance optimization strategies include probabilistic head sampling (10% def
 C++ implementation examples are provided for the core telemetry infrastructure and key modules:
 
 - `Telemetry.h` - Core interface for tracer access and span creation
-- `SpanGuard.h` - RAII wrapper for automatic span lifecycle management
-- `TracingInstrumentation.h` - Macros for conditional instrumentation
+- `SpanGuard.h` - RAII wrapper for automatic span lifecycle management with `discard()` support
+- `DiscardFlag.h` - Thread-local flag for span discard signaling between SpanGuard and FilteringSpanProcessor
+- `SpanGuard.cpp` - Pimpl implementation confining all OTel SDK types
 - Protocol Buffer extensions for trace context propagation
 - Module-specific instrumentation (RPC, Consensus, P2P, JobQueue)
 - Remaining modules (PathFinding, TxQ, Validator, etc.) follow the same patterns
@@ -187,19 +188,17 @@ OpenTelemetry Collector configurations are provided for development and producti
 
 ## 6. Implementation Phases
 
-The implementation spans 12 weeks across 7 phases:
+The implementation spans 9 weeks across 5 phases:
 
-| Phase | Duration    | Focus                 | Key Deliverables                                            |
-| ----- | ----------- | --------------------- | ----------------------------------------------------------- |
-| 1     | Weeks 1-2   | Core Infrastructure   | SDK integration, Telemetry interface, Configuration         |
-| 2     | Weeks 3-4   | RPC Tracing           | HTTP context extraction, Handler instrumentation            |
-| 3     | Weeks 5-6   | Transaction Tracing   | Protocol Buffer context, Relay propagation                  |
-| 4     | Weeks 7-8   | Consensus Tracing     | Round spans, Proposal/validation tracing                    |
-| 5     | Week 9      | Documentation         | Runbook, Dashboards, Training                               |
-| 6     | Week 10     | StatsD Metrics Bridge | OTel Collector StatsD receiver, 3 Grafana dashboards        |
-| 7     | Weeks 11-12 | Native OTel Metrics   | OTelCollector impl, OTLP metrics export, StatsD deprecation |
+| Phase | Duration  | Focus               | Key Deliverables                                    |
+| ----- | --------- | ------------------- | --------------------------------------------------- |
+| 1     | Weeks 1-2 | Core Infrastructure | SDK integration, Telemetry interface, Configuration |
+| 2     | Weeks 3-4 | RPC Tracing         | HTTP context extraction, Handler instrumentation    |
+| 3     | Weeks 5-6 | Transaction Tracing | Protocol Buffer context, Relay propagation          |
+| 4     | Weeks 7-8 | Consensus Tracing   | Round spans, Proposal/validation tracing            |
+| 5     | Week 9    | Documentation       | Runbook, Dashboards, Training                       |
 
-**Total Effort**: 60.6 developer-days with 2 developers
+**Total Effort**: 47 person-days (2 developers working in parallel)
 
 ➡️ **[View full Implementation Phases](./06-implementation-phases.md)**
 
@@ -219,7 +218,7 @@ The recommended production architecture uses a gateway collector pattern with re
 
 ## 8. Appendix
 
-The appendix contains a glossary of OpenTelemetry and rippled-specific terms, references to external documentation and specifications, version history for this implementation plan, and a complete document index.
+The appendix contains a glossary of OpenTelemetry and xrpld-specific terms, references to external documentation and specifications, version history for this implementation plan, and a complete document index.
 
 ➡️ **[View Appendix](./08-appendix.md)**
 
@@ -227,7 +226,7 @@ The appendix contains a glossary of OpenTelemetry and rippled-specific terms, re
 
 ## 9. Data Collection Reference
 
-A single-source-of-truth reference documenting every piece of telemetry data collected by rippled. Covers all 16 OpenTelemetry spans with their 22 attributes, all StatsD metrics (gauges, counters, histograms, overlay traffic), SpanMetrics-derived Prometheus metrics, and all 8 Grafana dashboards. Includes Jaeger search guides and Prometheus query examples.
+A single-source-of-truth reference documenting every piece of telemetry data collected by xrpld. Covers all 16 OpenTelemetry spans with their 22 attributes, all StatsD metrics (gauges, counters, histograms, overlay traffic), SpanMetrics-derived Prometheus metrics, and all 10 Grafana dashboards. Includes Jaeger search guides and Prometheus query examples.
 
 ➡️ **[View Data Collection Reference](./09-data-collection-reference.md)**
 
@@ -235,10 +234,10 @@ A single-source-of-truth reference documenting every piece of telemetry data col
 
 ## POC Task List
 
-A step-by-step task list for building a minimal end-to-end proof of concept that demonstrates distributed tracing in rippled. The POC scope is limited to RPC tracing — showing request traces flowing from rippled through an OpenTelemetry Collector into Tempo, viewable in Grafana.
+A step-by-step task list for building a minimal end-to-end proof of concept that demonstrates distributed tracing in xrpld. The POC scope is limited to RPC tracing — showing request traces flowing from xrpld through an OpenTelemetry Collector into Tempo, viewable in Grafana.
 
 ➡️ **[View POC Task List](./POC_taskList.md)**
 
 ---
 
-_This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the rippled XRP Ledger node software. For detailed information on any section, follow the links to the corresponding sub-documents._
+_This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the xrpld XRP Ledger node software. For detailed information on any section, follow the links to the corresponding sub-documents._

OpenTelemetryPlan/POC_taskList.md

@@ -1,21 +1,21 @@
 # OpenTelemetry POC Task List
 
-> **Goal**: Build a minimal end-to-end proof of concept that demonstrates distributed tracing in rippled. A successful POC will show RPC request traces flowing from rippled through an OTel Collector into Tempo, viewable in Grafana.
+> **Goal**: Build a minimal end-to-end proof of concept that demonstrates distributed tracing in xrpld. A successful POC will show RPC request traces flowing from xrpld through an OTel Collector into Tempo, viewable in Grafana.
 >
 > **Scope**: RPC tracing only (highest value, lowest risk per the [CRAWL phase](./06-implementation-phases.md#6102-quick-wins-immediate-value) in the implementation phases). No cross-node P2P context propagation or consensus tracing in the POC.
 
 ### Related Plan Documents
 
-| Document                                                         | Relevance to POC                                                                                                                                          |
-| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [00-tracing-fundamentals.md](./00-tracing-fundamentals.md)       | Core concepts: traces, spans, context propagation, sampling                                                                                               |
-| [01-architecture-analysis.md](./01-architecture-analysis.md)     | RPC request flow (§1.5), key trace points (§1.6), instrumentation priority (§1.7)                                                                         |
-| [02-design-decisions.md](./02-design-decisions.md)               | SDK selection (§2.1), exporter config (§2.2), span naming (§2.3), attribute schema (§2.4), coexistence with PerfLog/Insight (§2.6)                        |
-| [03-implementation-strategy.md](./03-implementation-strategy.md) | Directory structure (§3.1), key principles (§3.2), performance overhead (§3.3-3.6), conditional compilation (§3.7.3), code intrusiveness (§3.9)           |
-| [04-code-samples.md](./04-code-samples.md)                       | Telemetry interface (§4.1), SpanGuard (§4.2), macros (§4.3), RPC instrumentation (§4.5.3)                                                                 |
-| [05-configuration-reference.md](./05-configuration-reference.md) | rippled config (§5.1), config parser (§5.2), Application integration (§5.3), CMake (§5.4), Collector config (§5.5), Docker Compose (§5.6), Grafana (§5.8) |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 1 core tasks (§6.2), Phase 2 RPC tasks (§6.3), quick wins (§6.10), definition of done (§6.11)                                                       |
-| [07-observability-backends.md](./07-observability-backends.md)   | Tempo dev setup (§7.1), Grafana dashboards (§7.6), alert rules (§7.6.3)                                                                                   |
+| Document                                                         | Relevance to POC                                                                                                                                        |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [00-tracing-fundamentals.md](./00-tracing-fundamentals.md)       | Core concepts: traces, spans, context propagation, sampling                                                                                             |
+| [01-architecture-analysis.md](./01-architecture-analysis.md)     | RPC request flow (§1.5), key trace points (§1.6), instrumentation priority (§1.7)                                                                       |
+| [02-design-decisions.md](./02-design-decisions.md)               | SDK selection (§2.1), exporter config (§2.2), span naming (§2.3), attribute schema (§2.4), coexistence with PerfLog/Insight (§2.6)                      |
+| [03-implementation-strategy.md](./03-implementation-strategy.md) | Directory structure (§3.1), key principles (§3.2), performance overhead (§3.3-3.6), conditional compilation (§3.7.3), code intrusiveness (§3.9)         |
+| [04-code-samples.md](./04-code-samples.md)                       | Telemetry interface (§4.1), SpanGuard factory methods (§4.2-4.3), RPC instrumentation (§4.5.3)                                                          |
+| [05-configuration-reference.md](./05-configuration-reference.md) | xrpld config (§5.1), config parser (§5.2), Application integration (§5.3), CMake (§5.4), Collector config (§5.5), Docker Compose (§5.6), Grafana (§5.8) |
+| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 1 core tasks (§6.2), Phase 2 RPC tasks (§6.3), quick wins (§6.10), definition of done (§6.11)                                                     |
+| [07-observability-backends.md](./07-observability-backends.md)   | Tempo dev setup (§7.1), Grafana dashboards (§7.6), alert rules (§7.6.3)                                                                                 |
 
 ---
 
@@ -137,7 +137,7 @@
     - `virtual void start() = 0;`
     - `virtual void stop() = 0;`
     - `virtual bool isEnabled() const = 0;`
-    - `virtual nostd::shared_ptr<Tracer> getTracer(string_view name = "rippled") = 0;`
+    - `virtual nostd::shared_ptr<Tracer> getTracer(string_view name = "xrpld") = 0;`
     - `virtual nostd::shared_ptr<Span> startSpan(string_view name, SpanKind kind = kInternal) = 0;`
     - `virtual nostd::shared_ptr<Span> startSpan(string_view name, Context const& parentContext, SpanKind kind = kInternal) = 0;`
     - `virtual bool shouldTraceRpc() const = 0;`
@@ -147,9 +147,11 @@
   - Config parser: `Telemetry::Setup setup_Telemetry(Section const&, std::string const& nodePublicKey, std::string const& version);`
 
 - Create `include/xrpl/telemetry/SpanGuard.h`:
-  - RAII guard that takes an `nostd::shared_ptr<Span>`, creates a `Scope`, and calls `span->End()` in destructor.
-  - Convenience: `setAttribute()`, `setOk()`, `setStatus()`, `addEvent()`, `recordException()`, `context()`
-  - See [04-code-samples.md](./04-code-samples.md) §4.2 for the full implementation.
+  - RAII guard with static factory methods (`rpcSpan()`, `txSpan()`, `consensusSpan()`, etc.) that access the global `Telemetry::getInstance()` singleton internally.
+  - Uses pimpl idiom to hide all OTel types -- the public header has zero `opentelemetry/` includes.
+  - Convenience instance methods: `setAttribute()`, `setOk()`, `setStatus()`, `addEvent()`, `recordException()`, `context()`, `discard()`
+  - When `XRPL_ENABLE_TELEMETRY` is not defined, the entire class compiles to a no-op stub.
+  - See [04-code-samples.md](./04-code-samples.md) §4.2-4.3 for the full API reference.
 
 - Create `src/libxrpl/telemetry/NullTelemetry.cpp`:
   - Implements `Telemetry` with all no-ops.
@@ -167,7 +169,7 @@
 **Reference**:
 
 - [04-code-samples.md §4.1](./04-code-samples.md) — Full `Telemetry` interface with `Setup` struct, lifecycle, tracer access, span creation, and component filtering methods
-- [04-code-samples.md §4.2](./04-code-samples.md) — Full `SpanGuard` RAII implementation and `NullSpanGuard` no-op class
+- [04-code-samples.md §4.2-4.3](./04-code-samples.md) — SpanGuard with factory methods, pimpl design, no-op stub, and discard support
 - [03-implementation-strategy.md §3.1](./03-implementation-strategy.md) — Directory structure: `include/xrpl/telemetry/` for headers, `src/libxrpl/telemetry/` for implementation
 - [03-implementation-strategy.md §3.7.3](./03-implementation-strategy.md) — Conditional instrumentation and zero-cost compile-time disabled pattern
 
@@ -225,43 +227,59 @@
 
 ## Task 4: Integrate Telemetry into Application Lifecycle
 
-**Objective**: Wire the `Telemetry` object into `Application` so all components can access it.
+**Objective**: Wire the `Telemetry` object into the `ServiceRegistry` / `Application` so all components can access it.
 
 **What to do**:
 
-- Edit `src/xrpld/app/main/Application.h`:
-  - Forward-declare `namespace xrpl::telemetry { class Telemetry; }`
+- Edit `include/xrpl/core/ServiceRegistry.h`:
+  - Forward-declare `namespace telemetry { class Telemetry; }` inside `namespace xrpl`
   - Add pure virtual method: `virtual telemetry::Telemetry& getTelemetry() = 0;`
+  - (`Application` extends `ServiceRegistry`, so this is automatically available on `Application` too)
 
 - Edit `src/xrpld/app/main/Application.cpp` (the `ApplicationImp` class):
   - Add member: `std::unique_ptr<telemetry::Telemetry> telemetry_;`
-  - In the constructor, after config is loaded and node identity is known:
+  - In the member initializer list, construct telemetry with an empty
+    `serviceInstanceId` (node identity is not yet known):
     ```cpp
-    auto const telemetrySection = config_->section("telemetry");
-    auto telemetrySetup = telemetry::setup_Telemetry(
-        telemetrySection,
-        toBase58(TokenType::NodePublic, nodeIdentity_.publicKey()),
-        BuildInfo::getVersionString());
-    telemetry_ = telemetry::make_Telemetry(telemetrySetup, logs_->journal("Telemetry"));
+    , telemetry_(
+          telemetry::make_Telemetry(
+              telemetry::setup_Telemetry(
+                  config_->section("telemetry"),
+                  "",  // Updated later via setServiceInstanceId()
+                  BuildInfo::getVersionString()),
+              logs_->journal("Telemetry")))
     ```
-  - In `start()`: call `telemetry_->start()` early
-  - In `stop()` or destructor: call `telemetry_->stop()` late (to flush pending spans)
+  - In `setup()`, after `nodeIdentity_` is resolved, inject the node
+    public key as the service instance ID:
+    ```cpp
+    if (!config_->section("telemetry").exists("service_instance_id"))
+        telemetry_->setServiceInstanceId(
+            toBase58(TokenType::NodePublic, nodeIdentity_->first));
+    ```
+  - In `start()`: call `telemetry_->start()`
+  - In `run()` (shutdown path): call `telemetry_->stop()` (to flush pending spans)
   - Implement `getTelemetry()` override: return `*telemetry_`
 
-- Add `[telemetry]` section to the example config `cfg/rippled-example.cfg`:
+- Add `[telemetry]` section to the example config `cfg/xrpld-example.cfg`:
   ```ini
   # [telemetry]
   # enabled=1
-  # endpoint=localhost:4317
+  # endpoint=http://localhost:4318/v1/traces
   # sampling_ratio=1.0
   # trace_rpc=1
   ```
 
+> **Access patterns**: Components holding `ServiceRegistry&` (e.g.
+> `NetworkOPsImp`) call `registry_.get().getTelemetry()`. Components
+> holding `Application&` (e.g. `ServerHandler`, `PeerImp`,
+> `RCLConsensusAdaptor`) call `app_.getTelemetry()` directly. Both
+> resolve to the same `Telemetry` instance.
+
 **Key modified files**:
 
-- `src/xrpld/app/main/Application.h`
+- `include/xrpl/core/ServiceRegistry.h`
 - `src/xrpld/app/main/Application.cpp`
-- `cfg/rippled-example.cfg` (or equivalent example config)
+- `cfg/xrpld-example.cfg` (example config)
 
 **Reference**:
 
@@ -271,47 +289,37 @@
 
 ---
 
-## Task 5: Create Instrumentation Macros
+## Task 5: Add SpanGuard Factory Methods
 
-**Objective**: Define convenience macros that make instrumenting code one-liners, and that compile to zero-cost no-ops when telemetry is disabled.
+**Objective**: Add static factory methods to SpanGuard that provide type-safe, one-liner instrumentation and compile to zero-cost no-ops when telemetry is disabled. This replaces the earlier macro-based approach (`TracingInstrumentation.h` has been removed).
 
 **What to do**:
 
-- Create `src/xrpld/telemetry/TracingInstrumentation.h`:
-  - When `XRPL_ENABLE_TELEMETRY` is defined:
+- Update `include/xrpl/telemetry/SpanGuard.h`:
+  - Add static factory methods that access the global `Telemetry::getInstance()` singleton and check the relevant component filter before creating a span:
 
     ```cpp
-    #define XRPL_TRACE_SPAN(telemetry, name) \
-        auto _xrpl_span_ = (telemetry).startSpan(name); \
-        ::xrpl::telemetry::SpanGuard _xrpl_guard_(_xrpl_span_)
-
-    #define XRPL_TRACE_RPC(telemetry, name) \
-        std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-        if ((telemetry).shouldTraceRpc()) { \
-            _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-        }
-
-    #define XRPL_TRACE_SET_ATTR(key, value) \
-        if (_xrpl_guard_.has_value()) { \
-            _xrpl_guard_->setAttribute(key, value); \
-        }
-
-    #define XRPL_TRACE_EXCEPTION(e) \
-        if (_xrpl_guard_.has_value()) { \
-            _xrpl_guard_->recordException(e); \
-        }
+    // Each factory checks the global Telemetry instance internally.
+    // No Telemetry& reference needed at the call site.
+    auto span = telemetry::SpanGuard::rpcSpan("rpc.request");
+    span.setAttribute("xrpl.rpc.command", command);
+    span.setAttribute("xrpl.rpc.status", status);
     ```
 
-  - When `XRPL_ENABLE_TELEMETRY` is NOT defined, all macros expand to `((void)0)`
+  - Factory methods: `rpcSpan()`, `txSpan()`, `consensusSpan()`, `peerSpan()`, `ledgerSpan()`, `span()`
+  - Use the pimpl idiom to hide all OTel types from the public header (zero `opentelemetry/` includes)
+  - When `XRPL_ENABLE_TELEMETRY` is NOT defined, the entire class compiles to a no-op stub with empty inline method bodies
 
-**Key new file**:
+- No separate `TracingInstrumentation.h` file is needed. All instrumentation call sites use `#include <xrpl/telemetry/SpanGuard.h>` directly.
 
-- `src/xrpld/telemetry/TracingInstrumentation.h`
+**Key modified file**:
+
+- `include/xrpl/telemetry/SpanGuard.h`
 
 **Reference**:
 
-- [04-code-samples.md §4.3](./04-code-samples.md) — Full macro definitions for `XRPL_TRACE_SPAN`, `XRPL_TRACE_RPC`, `XRPL_TRACE_CONSENSUS`, `XRPL_TRACE_SET_ATTR`, `XRPL_TRACE_EXCEPTION` with both enabled and disabled branches
-- [03-implementation-strategy.md §3.7.3](./03-implementation-strategy.md) — Conditional instrumentation pattern: compile-time `#ifndef` and runtime `shouldTrace*()` checks
+- [04-code-samples.md §4.3](./04-code-samples.md) — SpanGuard API reference: factory methods, usage patterns, compile-time disabled behavior, and discard support
+- [03-implementation-strategy.md §3.7.3](./03-implementation-strategy.md) — Conditional instrumentation pattern: factory methods handle compile-time and runtime checks internally
 - [03-implementation-strategy.md §3.9.7](./03-implementation-strategy.md) — Before/after code examples showing minimal intrusiveness (~1-3 lines per instrumentation point)
 
 ---
@@ -325,17 +333,17 @@
 **What to do**:
 
 - Edit `src/xrpld/rpc/detail/ServerHandler.cpp`:
-  - `#include` the `TracingInstrumentation.h` header
+  - `#include <xrpl/telemetry/SpanGuard.h>`
   - In `ServerHandler::onRequest(Session& session)`:
-    - At the top of the method, add: `XRPL_TRACE_RPC(app_.getTelemetry(), "rpc.request");`
-    - After the RPC command name is extracted, set attribute: `XRPL_TRACE_SET_ATTR("xrpl.rpc.command", command);`
-    - After the response status is known, set: `XRPL_TRACE_SET_ATTR("http.status_code", static_cast<int64_t>(statusCode));`
-    - Wrap error paths with: `XRPL_TRACE_EXCEPTION(e);`
+    - At the top of the method, add: `auto span = telemetry::SpanGuard::rpcSpan("rpc.request");`
+    - After the RPC command name is extracted, set attribute: `span.setAttribute("xrpl.rpc.command", command);`
+    - After the response status is known, set: `span.setAttribute("http.status_code", static_cast<int64_t>(statusCode));`
+    - Wrap error paths with: `span.recordException(e);`
   - In `ServerHandler::processRequest(...)`:
-    - Add a child span: `XRPL_TRACE_RPC(app_.getTelemetry(), "rpc.process");`
-    - Set method attribute: `XRPL_TRACE_SET_ATTR("xrpl.rpc.method", request_method);`
+    - Add a child span: `auto span = telemetry::SpanGuard::rpcSpan("rpc.process");`
+    - Set method attribute: `span.setAttribute("xrpl.rpc.method", request_method);`
   - In `ServerHandler::onWSMessage(...)` (WebSocket path):
-    - Add: `XRPL_TRACE_RPC(app_.getTelemetry(), "rpc.ws.message");`
+    - Add: `auto span = telemetry::SpanGuard::rpcSpan("rpc.ws.message");`
 
 - The goal is to see spans like:
   ```
@@ -350,7 +358,7 @@
 
 **Reference**:
 
-- [04-code-samples.md §4.5.3](./04-code-samples.md) — Complete `ServerHandler::onRequest()` instrumented code sample with W3C header extraction, span creation, attribute setting, and error handling
+- [04-code-samples.md §4.5.3](./04-code-samples.md) — Complete `ServerHandler::onRequest()` instrumented code sample using SpanGuard factory methods
 - [01-architecture-analysis.md §1.5](./01-architecture-analysis.md) — RPC request flow diagram: HTTP request -> attributes -> jobqueue.enqueue -> rpc.command -> response
 - [01-architecture-analysis.md §1.6](./01-architecture-analysis.md) — Key trace points table: `rpc.request` in `ServerHandler.cpp::onRequest()` (Priority: High)
 - [02-design-decisions.md §2.3](./02-design-decisions.md) — Span naming convention: `rpc.request`, `rpc.command.*`
@@ -366,15 +374,15 @@
 **What to do**:
 
 - Edit `src/xrpld/rpc/detail/RPCHandler.cpp`:
-  - `#include` the `TracingInstrumentation.h` header
+  - `#include <xrpl/telemetry/SpanGuard.h>`
   - In `doCommand(RPC::JsonContext& context, Json::Value& result)`:
-    - At the top: `XRPL_TRACE_RPC(context.app.getTelemetry(), "rpc.command." + context.method);`
+    - At the top: `auto span = telemetry::SpanGuard::rpcSpan("rpc.command." + context.method);`
     - Set attributes:
-      - `XRPL_TRACE_SET_ATTR("xrpl.rpc.command", context.method);`
-      - `XRPL_TRACE_SET_ATTR("xrpl.rpc.version", static_cast<int64_t>(context.apiVersion));`
-      - `XRPL_TRACE_SET_ATTR("xrpl.rpc.role", (context.role == Role::ADMIN) ? "admin" : "user");`
-    - On success: `XRPL_TRACE_SET_ATTR("xrpl.rpc.status", "success");`
-    - On error: `XRPL_TRACE_SET_ATTR("xrpl.rpc.status", "error");` and set the error message
+      - `span.setAttribute("xrpl.rpc.command", context.method);`
+      - `span.setAttribute("xrpl.rpc.version", static_cast<int64_t>(context.apiVersion));`
+      - `span.setAttribute("xrpl.rpc.role", (context.role == Role::ADMIN) ? "admin" : "user");`
+    - On success: `span.setAttribute("xrpl.rpc.status", "success");`
+    - On error: `span.setAttribute("xrpl.rpc.status", "error");` and set the error message
 
 - After this, traces in Tempo/Grafana should look like:
   ```
@@ -402,7 +410,7 @@
 
 > **OTLP** = OpenTelemetry Protocol
 
-**Objective**: Prove the full pipeline works: rippled emits traces -> OTel Collector receives them -> Tempo stores them for Grafana visualization.
+**Objective**: Prove the full pipeline works: xrpld emits traces -> OTel Collector receives them -> Tempo stores them for Grafana visualization.
 
 **What to do**:
 
@@ -414,7 +422,7 @@
 
    Verify Collector health: `curl http://localhost:13133`
 
-2. **Build rippled with telemetry**:
+2. **Build xrpld with telemetry**:
 
    ```bash
    # Adjust for your actual build workflow
@@ -423,8 +431,8 @@
    cmake --build --preset default
    ```
 
-3. **Configure rippled**:
-   Add to `rippled.cfg` (or your local test config):
+3. **Configure xrpld**:
+   Add to `xrpld.cfg` (or your local test config):
 
    ```ini
    [telemetry]
@@ -434,10 +442,10 @@
    trace_rpc=1
    ```
 
-4. **Start rippled** in standalone mode:
+4. **Start xrpld** in standalone mode:
 
    ```bash
-   ./rippled --conf rippled.cfg -a --start
+   ./rippled --conf xrpld.cfg -a --start
    ```
 
 5. **Generate RPC traffic**:
@@ -462,21 +470,21 @@
 6. **Verify in Grafana (Tempo)**:
    - Open `http://localhost:3000`
    - Navigate to Explore → select Tempo datasource
-   - Search for service `rippled`
+   - Search for service `xrpld`
    - Confirm you see traces with spans: `rpc.request` -> `rpc.process` -> `rpc.command.server_info`
    - Click into a trace and verify attributes: `xrpl.rpc.command`, `xrpl.rpc.status`, `xrpl.rpc.version`
 
 7. **Verify zero-overhead when disabled**:
    - Rebuild with `XRPL_ENABLE_TELEMETRY=OFF`, or set `enabled=0` in config
    - Run the same RPC calls
-   - Confirm no new traces appear and no errors in rippled logs
+   - Confirm no new traces appear and no errors in xrpld logs
 
 **Verification Checklist**:
 
 - [ ] Docker stack starts without errors
-- [ ] rippled builds with `-DXRPL_ENABLE_TELEMETRY=ON`
-- [ ] rippled starts and connects to OTel Collector (check rippled logs for telemetry messages)
-- [ ] Traces appear in Grafana/Tempo under service "rippled"
+- [ ] xrpld builds with `-DXRPL_ENABLE_TELEMETRY=ON`
+- [ ] xrpld starts and connects to OTel Collector (check xrpld logs for telemetry messages)
+- [ ] Traces appear in Grafana/Tempo under service "xrpld"
 - [ ] Span hierarchy is correct (parent-child relationships)
 - [ ] Span attributes are populated (`xrpl.rpc.command`, `xrpl.rpc.status`, etc.)
 - [ ] Error spans show error status and message
@@ -502,13 +510,13 @@
 **What to do**:
 
 - Take screenshots of Grafana/Tempo showing:
-  - The service list with "rippled"
+  - The service list with "xrpld"
   - A trace with the full span tree
   - Span detail view showing attributes
 - Document any issues encountered (build issues, SDK quirks, missing attributes)
 - Note performance observations (build time impact, any noticeable runtime overhead)
 - Write a short summary of what the POC proves and what it doesn't cover yet:
-  - **Proves**: OTel SDK integrates with rippled, OTLP export works, RPC traces visible
+  - **Proves**: OTel SDK integrates with xrpld, OTLP export works, RPC traces visible
   - **Doesn't cover**: Cross-node P2P context propagation, consensus tracing, protobuf trace context, W3C traceparent header extraction, tail-based sampling, production deployment
 - Outline next steps (mapping to the full plan phases):
   - [Phase 2](./06-implementation-phases.md) completion: [W3C header extraction](./02-design-decisions.md) (§2.5), WebSocket tracing, all [RPC handlers](./01-architecture-analysis.md) (§1.6)
@@ -537,7 +545,7 @@
 | 2    | Core Telemetry interface + NullImpl  | 3         | 0              | 1          |
 | 3    | OTel-backed Telemetry implementation | 2         | 1              | 1, 2       |
 | 4    | Application lifecycle integration    | 0         | 3              | 2, 3       |
-| 5    | Instrumentation macros               | 1         | 0              | 2          |
+| 5    | SpanGuard factory methods            | 0         | 1              | 2          |
 | 6    | Instrument RPC ServerHandler         | 0         | 1              | 4, 5       |
 | 7    | Instrument RPC command execution     | 0         | 1              | 4, 5       |
 | 8    | End-to-end verification              | 0         | 0              | 0-7        |
@@ -615,6 +623,6 @@ Issues encountered during POC implementation that inform future work:
 | Conan package only builds OTLP HTTP exporter, not gRPC                                             | Switched from gRPC to HTTP exporter (`localhost:4318/v1/traces`)              | HTTP exporter is the default; gRPC requires custom Conan profile |
 | CMake target `opentelemetry-cpp::api` etc. don't exist in Conan package                            | Use umbrella target `opentelemetry-cpp::opentelemetry-cpp`                    | Conan targets differ from upstream CMake targets                 |
 | OTel Collector `logging` exporter deprecated                                                       | Renamed to `debug` exporter                                                   | Use `debug` in all collector configs going forward               |
-| Macro parameter `telemetry` collided with `::xrpl::telemetry::` namespace                          | Renamed macro params to `_tel_obj_`, `_span_name_`                            | Avoid common words as macro parameter names                      |
+| Macro parameter `telemetry` collided with `::xrpl::telemetry::` namespace                          | Replaced macros with SpanGuard factory methods (no macros needed)             | Factory methods avoid macro hygiene issues entirely              |
 | `opentelemetry::trace::Scope` creates new context on move                                          | Store scope as member, create once in constructor                             | SpanGuard move semantics need care with Scope lifecycle          |
 | `TracerProviderFactory::Create` returns `unique_ptr<sdk::TracerProvider>`, not `nostd::shared_ptr` | Use `std::shared_ptr` member, wrap in `nostd::shared_ptr` for global provider | OTel SDK factory return types don't match API provider types     |

OpenTelemetryPlan/Phase2_taskList.md

@@ -1,10 +1,10 @@
 # Phase 2: RPC Tracing Completion Task List
 
-> **Goal**: Complete full RPC tracing coverage with W3C Trace Context propagation, unit tests, and performance validation. Build on the POC foundation to achieve production-quality RPC observability.
+> **Goal**: Complete RPC tracing coverage with unit tests, Grafana search filters, node health attributes, and config hardening. Build on the Phase 1c SpanGuard factory foundation to achieve production-quality RPC observability.
 >
-> **Scope**: W3C header extraction, TraceContext propagation utilities, unit tests for core telemetry, integration tests for RPC tracing, and performance benchmarks.
+> **Scope**: Unit tests for core telemetry, Grafana Tempo search filters, node health span attributes, config validation (`std::clamp`).
 >
-> **Branch**: `pratik/otel-phase2-rpc-tracing` (from `pratik/OpenTelemetry_and_DistributedTracing_planning`)
+> **Branch**: `pratik/otel-phase2-rpc-tracing` (from `pratik/otel-phase1c-rpc-integration`)
 
 ### Related Plan Documents
 
@@ -16,59 +16,23 @@
 
 ---
 
-## Task 2.1: Implement W3C Trace Context HTTP Header Extraction
+## Task 2.1: W3C Trace Context HTTP Header Extraction
 
-**Objective**: Extract `traceparent` and `tracestate` headers from incoming HTTP RPC requests so external callers can propagate their trace context into rippled.
+**Status**: DEFERRED → Phase 3
 
-**What to do**:
+**Reason**: W3C context propagation (`traceparent`/`tracestate` headers) requires a consumer — in Phase 2, RPC spans are entirely local to the node. Phase 3 introduces cross-node transaction tracing via protobuf context propagation, which is the first use case for extracted trace context. Implementing it here without a consumer would be dead code.
 
-- Create `include/xrpl/telemetry/TraceContextPropagator.h`:
-  - `extractFromHeaders(headerGetter)` - extract W3C traceparent/tracestate from HTTP headers
-  - `injectToHeaders(ctx, headerSetter)` - inject trace context into response headers
-  - Use OTel's `TextMapPropagator` with `W3CTraceContextPropagator` for standards compliance
-  - Only compiled when `XRPL_ENABLE_TELEMETRY` is defined
-
-- Create `src/libxrpl/telemetry/TraceContextPropagator.cpp`:
-  - Implement a simple `TextMapCarrier` adapter for HTTP headers
-  - Use `opentelemetry::context::propagation::GlobalTextMapPropagator` for extraction/injection
-  - Register the W3C propagator in `TelemetryImpl::start()`
-
-- Modify `src/xrpld/rpc/detail/ServerHandler.cpp`:
-  - In the HTTP request handler, extract parent context from headers before creating span
-  - Pass extracted context to `startSpan()` as parent
-  - Inject trace context into response headers
-
-**Key new files**:
-
-- `include/xrpl/telemetry/TraceContextPropagator.h`
-- `src/libxrpl/telemetry/TraceContextPropagator.cpp`
-
-**Key modified files**:
-
-- `src/xrpld/rpc/detail/ServerHandler.cpp`
-- `src/libxrpl/telemetry/Telemetry.cpp` (register W3C propagator)
-
-**Reference**:
-
-- [04-code-samples.md §4.4.2](./04-code-samples.md) — TraceContextPropagator with extractFromHeaders/injectToHeaders
-- [02-design-decisions.md §2.5](./02-design-decisions.md) — W3C Trace Context propagation design
+**Implemented in**: `pratik/otel-phase3-tx-tracing` — `TraceContextPropagator.h/.cpp`
 
 ---
 
-## Task 2.2: Add XRPL_TRACE_PEER Macro
+## Task 2.2: Per-Category Span Creation
 
-**Objective**: Add the missing peer-tracing macro for future Phase 3 use and ensure macro completeness.
+**Status**: COMPLETE (superseded by Phase 1c design)
 
-**What to do**:
+**Original plan**: Add `XRPL_TRACE_PEER` and `XRPL_TRACE_LEDGER` macros.
 
-- Edit `src/xrpld/telemetry/TracingInstrumentation.h`:
-  - Add `XRPL_TRACE_PEER(_tel_obj_, _span_name_)` macro that checks `shouldTracePeer()`
-  - Add `XRPL_TRACE_LEDGER(_tel_obj_, _span_name_)` macro (for future ledger tracing)
-  - Ensure disabled variants expand to `((void)0)`
-
-**Key modified file**:
-
-- `src/xrpld/telemetry/TracingInstrumentation.h`
+**Actual implementation**: Phase 1c replaced all tracing macros with the `SpanGuard::span(TraceCategory, prefix, name)` factory pattern. The `TraceCategory` enum (`Rpc`, `Transactions`, `Consensus`, `Peer`, `Ledger`) serves the same conditional-creation purpose without macros. No separate task needed — the factory already supports all categories.
 
 ---
 
@@ -95,59 +59,41 @@
 
 ## Task 2.4: Unit Tests for Core Telemetry Infrastructure
 
+**Status**: COMPLETE
+
 **Objective**: Add unit tests for the core telemetry abstractions to validate correctness and catch regressions.
 
-**What to do**:
+**Implemented**:
 
-- Create `src/test/telemetry/Telemetry_test.cpp`:
-  - Test NullTelemetry: verify all methods return expected no-op values
-  - Test Setup defaults: verify all Setup fields have correct defaults
-  - Test setup_Telemetry config parser: verify parsing of [telemetry] section
-  - Test enabled/disabled factory paths
-  - Test shouldTrace\* methods respect config flags
+- `src/tests/libxrpl/telemetry/TelemetryConfig.cpp`:
+  - Test Setup defaults (all fields have correct initial values)
+  - Test `setup_Telemetry` config parser (empty section, full section, edge cases)
+  - Test `samplingRatio` clamping (values outside 0.0-1.0)
 
-- Create `src/test/telemetry/SpanGuard_test.cpp`:
-  - Test SpanGuard RAII lifecycle (span ends on destruction)
-  - Test move constructor works correctly
-  - Test setAttribute, setOk, setStatus, addEvent, recordException
-  - Test context() returns valid context
+- `src/tests/libxrpl/telemetry/SpanGuardFactory.cpp`:
+  - Test null guard methods are safe (setAttribute, setOk, setError, addEvent on null)
+  - Test category span returns null when telemetry disabled
+  - Test child/linked span null when no parent context
+  - Test move construction transfers ownership
+  - Test recordException safe on null guard
+  - Test discard() safe on null guard
 
-- Add test files to CMake build
-
-**Key new files**:
-
-- `src/test/telemetry/Telemetry_test.cpp`
-- `src/test/telemetry/SpanGuard_test.cpp`
-
-**Reference**:
-
-- [06-implementation-phases.md §6.11.1](./06-implementation-phases.md) — Phase 1 exit criteria (unit tests passing)
+- `src/tests/libxrpl/telemetry/main.cpp` — GTest runner
+- `src/tests/libxrpl/CMakeLists.txt` — test target with optional OTel linking
 
 ---
 
 ## Task 2.5: Enhance RPC Span Attributes
 
-**Objective**: Add additional attributes to RPC spans per the semantic conventions defined in the plan.
+**Status**: DEFERRED (low priority)
 
-**What to do**:
+**Reason**: The high-value attributes (`command`, `version`, `role`, `status`) are already set by Phase 1c. The remaining HTTP transport-level attributes (`http.method`, `net.peer.ip`, `http.status_code`) provide limited additional insight since:
 
-- Edit `src/xrpld/rpc/detail/ServerHandler.cpp`:
-  - Add `http.method` attribute for HTTP requests
-  - Add `http.status_code` attribute for responses
-  - Add `net.peer.ip` attribute for client IP (if available)
+- `http.method` is always POST for JSON-RPC
+- `net.peer.ip` is debug-level info available in logs
+- `xrpl.rpc.duration_ms` is redundant with span duration (OTel captures start/end time natively)
 
-- Edit `src/xrpld/rpc/detail/RPCHandler.cpp`:
-  - Add `xrpl.rpc.duration_ms` attribute on completion
-  - Add error message attribute on failure: `xrpl.rpc.error_message`
-
-**Key modified files**:
-
-- `src/xrpld/rpc/detail/ServerHandler.cpp`
-- `src/xrpld/rpc/detail/RPCHandler.cpp`
-
-**Reference**:
-
-- [02-design-decisions.md §2.4.2](./02-design-decisions.md) — RPC attribute schema
+These can be added later if dashboard queries specifically need them. The node health attributes (Task 2.8) provide far more operational value and were prioritized instead.
 
 ---
 
@@ -215,19 +161,49 @@ This surfaces all RPCs served during a blocked period — critical for post-inci
 
 ---
 
+## Task 2.9: PathFind RPC Instrumentation
+
+**Status**: COMPLETE
+
+**Objective**: Trace the path_find and ripple_path_find RPC handlers to capture request latency and computation cost.
+
+**Spans added**:
+
+- `pathfind.request` — wraps `doPathFind()` and `doRipplePathFind()` RPC handlers
+- `pathfind.compute` — wraps `PathRequest::doUpdate()` (fast/normal attr)
+- `pathfind.update_all` — wraps `PathRequestManager::updateAll()` on ledger close (ledger_index attr)
+- `pathfind.discover` — wraps `Pathfinder::findPaths()` graph exploration (search_level attr)
+- `pathfind.rank` — wraps `Pathfinder::computePathRanks()` liquidity validation (num_paths attr)
+
+**New file**: `src/xrpld/rpc/detail/PathFindSpanNames.h`
+
+**Modified files**:
+
+- `src/xrpld/rpc/handlers/orderbook/PathFind.cpp`
+- `src/xrpld/rpc/handlers/orderbook/RipplePathFind.cpp`
+- `src/xrpld/rpc/detail/PathRequest.cpp`
+- `src/xrpld/rpc/detail/PathRequestManager.cpp`
+- `src/xrpld/rpc/detail/Pathfinder.cpp`
+
+---
+
 ## Summary
 
-| Task | Description                                 | New Files | Modified Files | Depends On |
-| ---- | ------------------------------------------- | --------- | -------------- | ---------- |
-| 2.1  | W3C Trace Context header extraction         | 2         | 2              | POC        |
-| 2.2  | Add XRPL_TRACE_PEER/LEDGER macros           | 0         | 1              | POC        |
-| 2.3  | Add shouldTraceLedger() interface method    | 0         | 3              | POC        |
-| 2.4  | Unit tests for core telemetry               | 2         | 1              | POC        |
-| 2.5  | Enhanced RPC span attributes                | 0         | 2              | POC        |
-| 2.6  | Build verification and performance baseline | 0         | 0              | 2.1-2.5    |
-| 2.8  | RPC span attribute enrichment (node health) | 0         | 1              | 2.5        |
+| Task | Description                                 | Status              | Notes                                            |
+| ---- | ------------------------------------------- | ------------------- | ------------------------------------------------ |
+| 2.1  | W3C Trace Context header extraction         | Deferred → Phase 3  | No consumer in Phase 2; needs cross-node tracing |
+| 2.2  | Per-category span creation                  | Complete (Phase 1c) | Superseded by TraceCategory enum + SpanGuard     |
+| 2.3  | Add shouldTraceLedger() interface method    | Complete (Phase 1c) | Delivered in Phase 1c base branch                |
+| 2.4  | Unit tests for core telemetry               | Complete            | TelemetryConfig + SpanGuardFactory tests         |
+| 2.5  | Enhanced RPC span attributes (HTTP-level)   | Deferred            | Low value; span duration covers timing natively  |
+| 2.6  | Build verification and performance baseline | Complete            | Verified in CI on Phase 1c                       |
+| 2.7  | Grafana Tempo search filters                | Complete            | rpc-command, rpc-status, rpc-role filters        |
+| 2.8  | RPC span attribute enrichment (node health) | Complete            | amendment_blocked + server_state                 |
+| 2.9  | PathFind RPC instrumentation (5 spans)      | Complete            | request, compute, update_all, discover, rank     |
 
-**Parallel work**: Tasks 2.1, 2.2, 2.3 can run in parallel. Task 2.4 depends on 2.3. Task 2.5 can run in parallel with 2.4. Task 2.6 depends on all others. Task 2.8 depends on 2.5 (existing span creation must be in place).
+**Delivered in this branch**: Tasks 2.4, 2.7, 2.8, 2.9.
+**Deferred with rationale**: Tasks 2.1 (→Phase 3), 2.5 (low priority).
+**Superseded**: Task 2.2 (Phase 1c SpanGuard factory covers this).
 
 ---
 

OpenTelemetryPlan/Phase3_taskList.md

@@ -23,7 +23,7 @@
 
 **What to do**:
 
-- Edit `include/xrpl/proto/xrpl.proto` (or `src/ripple/proto/ripple.proto`, wherever the proto is):
+- Edit `include/xrpl/proto/xrpl.proto` (or `src/xrpld/proto/ripple.proto`, wherever the proto is):
   - Add `TraceContext` message definition:
     ```protobuf
     message TraceContext {
@@ -97,7 +97,8 @@
     - Inject current trace context into outgoing `TMTransaction::trace_context`
     - Set `xrpl.tx.relay_count` attribute
 
-- Include `TracingInstrumentation.h` and use `XRPL_TRACE_TX` macro
+- Use `SpanGuard::span(TraceCategory::Transactions, "tx", "receive")` factory
+  (Phase 1c replaced macros with the SpanGuard factory pattern)
 
 **Key modified files**:
 
@@ -165,27 +166,54 @@
 
 ## Task 3.6: Context Propagation in Transaction Relay
 
+**Status**: COMPLETE
+
 **Objective**: Ensure trace context flows correctly when transactions are relayed between peers, creating linked spans across nodes.
 
-**What to do**:
+**What was done**:
 
-- Verify the relay path injects trace context:
-  - When `PeerImp` relays a transaction, the `TMTransaction` message should carry `trace_context`
-  - When a remote peer receives it, the context is extracted and used as parent
+- **TX send side**: `NetworkOPs::apply()` now injects the tx.process span's trace
+  context into the outgoing `TMTransaction` protobuf before relay, using
+  `telemetry::injectSpanContext()`. The receiving node's `txReceiveSpan()` (already
+  wired in PeerImp) extracts the parent span_id and creates the tx.receive span
+  as a child of the sender's tx.process span.
 
-- Test context propagation:
-  - Manually verify with 2+ node setup that trace IDs match across nodes
-  - Confirm parent-child span relationships are correct in Tempo
+- **Proposal send/receive**: `RCLConsensus::Adaptor::propose()` injects the
+  current thread's active span context into the `TMProposeSet` protobuf via
+  `telemetry::injectToProtobuf()`. PeerImp creates a
+  `consensus.proposal.receive` span that extracts the sender's trace context
+  as parent (via `ConsensusReceiveTracing.h`).
 
-- Handle edge cases:
-  - Missing trace context (older peers): create new root span
-  - Corrupted trace context: log warning, create new root span
-  - Sampled-out traces: respect trace flags
+- **Validation send/receive**: `RCLConsensus::Adaptor::validate()` injects
+  the current thread's active span context into the `TMValidation` protobuf.
+  PeerImp creates a `consensus.validation.receive` span that extracts the
+  sender's trace context as parent.
+
+- **Edge cases**: Missing trace context (older peers) degrades gracefully to
+  standalone spans. Invalid/corrupted context is treated as absent. Trace
+  flags are propagated and respected.
+
+**New infrastructure**:
+
+- `SpanGuard::getTraceBytes()` — extracts raw trace_id/span_id/trace_flags
+  from a span without exposing OTel types. Safe to call from any thread.
+- `PropagationHelpers.h` — `injectSpanContext(SpanGuard&, proto)` bridge
+  between SpanGuard and protobuf TraceContext.
+- `TraceContextPropagator.h` — `injectToProtobuf(ctx, proto)` for
+  same-thread injection via OTel RuntimeContext (used in propose/validate).
+- `ConsensusReceiveTracing.h` — `proposalReceiveSpan()` and
+  `validationReceiveSpan()` helper functions that create receive spans with
+  optional parent context extraction from incoming protobuf messages.
 
 **Key modified files**:
 
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-- `src/xrpld/overlay/detail/OverlayImpl.cpp` (if relay method needs context param)
+- `src/xrpld/app/misc/NetworkOPs.cpp` — tx relay injection
+- `src/xrpld/app/consensus/RCLConsensus.cpp` — proposal/validation send injection
+- `src/xrpld/overlay/detail/PeerImp.cpp` — proposal/validation receive spans
+- `include/xrpl/telemetry/SpanGuard.h` — `TraceBytes` struct, `getTraceBytes()`
+- `src/libxrpl/telemetry/SpanGuard.cpp` — `getTraceBytes()` implementation
+- `src/xrpld/telemetry/PropagationHelpers.h` — inject helpers (new file)
+- `src/xrpld/telemetry/ConsensusReceiveTracing.h` — receive span helpers (new file)
 
 **Reference**:
 
@@ -223,7 +251,7 @@
 > **Upstream**: Phase 2 (RPC span infrastructure must exist).
 > **Downstream**: Phase 10 (validation checks for this attribute).
 
-**Objective**: Add the relaying peer's rippled version to `tx.receive` spans so operators can correlate transaction issues with peer version mismatches during network upgrades.
+**Objective**: Add the relaying peer's xrpld version to `tx.receive` spans so operators can correlate transaction issues with peer version mismatches during network upgrades.
 
 **What to do**:
 
@@ -234,9 +262,9 @@
 
 **New span attribute**:
 
-| Attribute           | Type   | Source               | Example           |
-| ------------------- | ------ | -------------------- | ----------------- |
-| `xrpl.peer.version` | string | `peer->getVersion()` | `"rippled-2.4.0"` |
+| Attribute           | Type   | Source               | Example         |
+| ------------------- | ------ | -------------------- | --------------- |
+| `xrpl.peer.version` | string | `peer->getVersion()` | `"xrpld-2.4.0"` |
 
 **Rationale**: Transaction relay is where version mismatches cause subtle serialization or validation bugs. Tracing "this tx came from a v2.3.0 peer" helps diagnose compatibility issues. The community dashboard tracks peer versions externally; this brings version awareness into the trace itself.
 
@@ -252,6 +280,192 @@
 
 ---
 
+## Task 3.9: Deterministic Transaction Trace ID
+
+> **Upstream**: Task 3.2 (protobuf serialization), Task 3.3 (PeerImp span exists).
+> **Downstream**: Phase 10 (workload validation can query by tx hash directly).
+> **Pattern**: Mirrors the consensus deterministic trace ID in Phase 4a
+> (`createDeterministicContext` in `RCLConsensus.cpp`), adapted for transactions.
+
+**Objective**: Derive the trace_id for transaction spans deterministically from the
+transaction hash so that all nodes handling the same transaction independently produce
+spans under the same trace_id — regardless of whether protobuf context propagation
+succeeds.
+
+**Why**: The current approach creates spans with random trace_ids and relies entirely
+on protobuf `TraceContext` propagation to link them. If any hop in the relay chain
+drops the context (older peers, message corruption, mixed-version networks), the trace
+splits and downstream spans become impossible to find. With deterministic trace_ids,
+correlation is guaranteed because every node derives the same trace_id from the same
+`txID`.
+
+**Approach — deterministic trace_id + protobuf span_id propagation**:
+
+1. Derive `trace_id = txHash[0:16]` (first 16 bytes of the 32-byte transaction hash).
+2. Generate a random 8-byte `span_id` per node (each node's span is unique within
+   the shared trace).
+3. Create the span under this deterministic context as parent.
+4. **Additionally**, if protobuf `TraceContext` is present in the incoming
+   `TMTransaction` message, extract the sender's `span_id` and use it as the span's
+   parent — this preserves parent-child ordering in the trace tree.
+5. If protobuf context is absent (older peer, first hop), the span still has the
+   correct deterministic `trace_id` — it appears as a sibling root in the same trace
+   rather than being lost.
+
+This gives the best of both worlds: guaranteed cross-node correlation via deterministic
+`trace_id`, plus parent-child relay ordering via protobuf `span_id` when available.
+
+**What to do**:
+
+- Create `createDeterministicTxContext(uint256 const& txHash)` utility function:
+  - Location: shared header or file-local in `PeerImp.cpp` and `NetworkOPs.cpp`
+    (or a shared telemetry utility if both need it).
+  - Pattern: identical to `createDeterministicContext(uint256 const& ledgerId)` in
+    `RCLConsensus.cpp` — take `txHash[0:16]` as trace_id, random span_id via
+    `default_prng()`, sampled flag set, `remote=false`.
+  - Guard behind `#ifdef XRPL_ENABLE_TELEMETRY`.
+
+  ```cpp
+  opentelemetry::context::Context
+  createDeterministicTxContext(uint256 const& txHash)
+  {
+      namespace trace = opentelemetry::trace;
+
+      // First 16 bytes of the 32-byte tx hash as trace ID.
+      trace::TraceId traceId(
+          opentelemetry::nostd::span<uint8_t const, 16>(txHash.data(), 16));
+
+      // Random span_id so each node's span is unique within the trace.
+      uint8_t spanIdBytes[8];
+      auto const rval = default_prng()();
+      std::memcpy(spanIdBytes, &rval, sizeof(spanIdBytes));
+      trace::SpanId spanId(
+          opentelemetry::nostd::span<uint8_t const, 8>(spanIdBytes, 8));
+
+      trace::SpanContext syntheticCtx(
+          traceId, spanId, trace::TraceFlags(1), /* remote = */ false);
+
+      return opentelemetry::context::Context{}.SetValue(
+          trace::kSpanKey,
+          opentelemetry::nostd::shared_ptr<trace::Span>(
+              new trace::DefaultSpan(syntheticCtx)));
+  }
+  ```
+
+- Edit `src/xrpld/overlay/detail/PeerImp.cpp` — restructure `handleTransaction()`:
+  - **Move span creation after deserialization** (txID must be known first):
+    1. Deserialize `STTx` and get `txID` (existing code at line ~1382).
+    2. Create deterministic parent context: `auto detCtx = createDeterministicTxContext(txID)`.
+    3. If `m->has_trace_context()`: extract protobuf context via `extractFromProtobuf()`,
+       **combine** with deterministic trace_id — use the protobuf span_id as parent
+       to preserve relay ordering, but override trace_id with the deterministic one.
+    4. If no protobuf context: create span under `detCtx` directly.
+    5. Set all existing attributes (`hash`, `peerId`, `peerVersion`, `suppressed`, etc.).
+
+  - **Combining deterministic trace_id with protobuf parent span_id**:
+    When both are available, construct a synthetic `SpanContext` with:
+    - `trace_id` = `txHash[0:16]` (deterministic)
+    - `span_id` = extracted from protobuf (sender's span_id → becomes parent)
+    - `trace_flags` = from protobuf
+    - `remote` = true (came from another node)
+
+    ```cpp
+    // Pseudo-code for the combined context:
+    auto detTraceId = trace::TraceId(txHash.data(), 16);
+    auto remoteSpanId = /* from extractFromProtobuf */;
+    auto remoteFlags = /* from extractFromProtobuf */;
+
+    trace::SpanContext combinedCtx(
+        detTraceId, remoteSpanId, remoteFlags, /* remote = */ true);
+    // Use as parent context for the new span.
+    ```
+
+- Edit `src/xrpld/app/misc/NetworkOPs.cpp` — update `processTransaction()`:
+  - `transaction->getID()` is already available at the top of the function.
+  - Create deterministic parent context from `txID`.
+  - Create `tx.process` span under this context.
+  - No protobuf context to extract here (NetworkOPs is intra-node), so
+    deterministic context alone is sufficient.
+
+- Add `tx_trace_strategy` attribute to spans:
+  - Add `inline constexpr auto traceStrategy = join(xrplTx, makeStr("trace_strategy"));`
+    to `TxSpanNames.h`.
+  - Set on each tx span: `span.setAttribute(tx_span::attr::traceStrategy, "deterministic")`.
+
+**Key new/modified files**:
+
+- `src/xrpld/overlay/detail/PeerImp.cpp` — restructured span creation
+- `src/xrpld/app/misc/NetworkOPs.cpp` — deterministic context for tx.process
+- `src/xrpld/app/misc/TxSpanNames.h` — new `traceStrategy` attribute constant
+- New or shared utility for `createDeterministicTxContext()` (location TBD: could be
+  a shared header like `include/xrpl/telemetry/DeterministicContext.h`, or file-local
+  if only used in two places)
+
+**Interaction with existing tasks**:
+
+- **Task 3.3 (PeerImp instrumentation)**: The span creation in `handleTransaction()`
+  must be restructured — the span currently starts before `txID` is known. This task
+  moves it after deserialization.
+- **Task 3.6 (Relay context propagation)**: Protobuf injection at the relay site
+  remains the same — `injectToProtobuf()` serializes the current span's `span_id`.
+  The receiver extracts it and combines with the deterministic `trace_id`.
+- **Phase 4a (Consensus deterministic trace ID)**: This task follows the same pattern.
+  Consider extracting a shared utility (e.g., `createDeterministicContext(uint256)`)
+  that both consensus and transaction tracing use.
+
+**Exit Criteria**:
+
+- [ ] `tx.receive` and `tx.process` spans have deterministic trace_id = `txHash[0:16]`
+- [ ] All nodes handling the same transaction produce spans under the same trace_id
+- [x] Protobuf `span_id` propagation still works when available (parent-child ordering)
+- [ ] Missing protobuf context (old peer) degrades gracefully to sibling spans, not lost traces
+- [ ] `xrpl.tx.trace_strategy` attribute set to `"deterministic"` on all tx spans
+- [ ] Trace queryable by tx hash (truncate hash → trace_id → direct lookup in Tempo)
+
+**Deliverables implemented (not in original plan)**:
+
+- **`SpanGuard::txSpan()` factory method** (`include/xrpl/telemetry/SpanGuard.h`):
+  Two overloads for creating transaction spans with deterministic trace IDs:
+  - `txSpan(category, group, name, txHash)` — standalone span (deterministic
+    trace_id from `txHash[0:16]`, no parent span_id).
+  - `txSpan(category, group, name, txHash, parentCtx)` — child span (deterministic
+    trace_id combined with protobuf-extracted parent span_id for relay ordering).
+
+- **`TxTracing.h` helper functions** (`src/xrpld/overlay/detail/TxTracing.h`):
+  File-local helpers that wrap `SpanGuard::txSpan()` for the two main PeerImp call
+  sites:
+  - `txReceiveSpan(txHash, parentCtx)` — creates `tx.receive` span with
+    deterministic trace_id and optional protobuf parent context.
+  - `txProcessSpan(txHash)` — creates `tx.process` span with deterministic
+    trace_id only (no protobuf parent, used intra-node).
+  - **Note**: `TxTracing.h` includes `xrpl.pb.h` unconditionally (outside
+    `#ifdef XRPL_ENABLE_TELEMETRY`) because `protocol::TMTransaction` appears in
+    the function signatures regardless of telemetry build mode.
+
+---
+
+## Task 3.10: TxQ Instrumentation
+
+**Status**: COMPLETE
+
+**Objective**: Trace the transaction queue lifecycle — enqueue decisions, direct apply, batch clear, ledger-close accept loop, per-tx apply, and cleanup.
+
+**Spans added**:
+
+- `txq.enqueue` — wraps `TxQ::apply()` with tx_hash attribute
+- `txq.apply_direct` — wraps `TxQ::tryDirectApply()` fast-path
+- `txq.batch_clear` — wraps `TxQ::tryClearAccountQueueUpThruTx()`
+- `txq.accept` — wraps `TxQ::accept()` ledger-close dequeue with queue_size attr
+- `txq.accept_tx` — per-tx span inside accept loop with tx_hash, ter_code,
+  retries_remaining attributes
+- `txq.cleanup` — wraps `TxQ::processClosedLedger()` with ledger_seq attribute
+
+**New file**: `src/xrpld/app/misc/detail/TxQSpanNames.h`
+
+**Modified file**: `src/xrpld/app/misc/detail/TxQ.cpp`
+
+---
+
 ## Summary
 
 | Task | Description                         | New Files | Modified Files | Depends On |
@@ -264,34 +478,24 @@
 | 3.6  | Relay context propagation           | 0         | 1-2            | 3.3, 3.5   |
 | 3.7  | Build verification and testing      | 0         | 0              | 3.1-3.6    |
 | 3.8  | TX span peer version attribute      | 0         | 1              | 3.3        |
+| 3.9  | Deterministic transaction trace ID  | 0-1       | 3              | 3.2, 3.3   |
+| 3.10 | TxQ instrumentation (6 spans)       | 1         | 1              | 3.4        |
 
-**Parallel work**: Tasks 3.1 and 3.4 can start in parallel. Task 3.2 depends on 3.1. Tasks 3.3 and 3.5 depend on 3.2. Task 3.6 depends on 3.3 and 3.5. Task 3.8 depends on 3.3 (span must exist).
+**Parallel work**: Tasks 3.1 and 3.4 can start in parallel. Task 3.2 depends on 3.1. Tasks 3.3 and 3.5 depend on 3.2. Task 3.6 depends on 3.3 and 3.5. Task 3.8 depends on 3.3 (span must exist). Task 3.9 depends on 3.2 and 3.3. Task 3.10 depends on 3.4 (tx.process span must exist).
 
 **Exit Criteria** (from [06-implementation-phases.md §6.11.3](./06-implementation-phases.md)):
 
-- [ ] Transaction traces span across nodes
-- [ ] Trace context in Protocol Buffer messages
+- [x] Transaction traces span across nodes
+- [x] Trace context in Protocol Buffer messages
 - [ ] HashRouter deduplication visible in traces
 - [ ] <5% overhead on transaction throughput
+- [x] Deterministic trace_id: same trace_id for same tx across all nodes
+- [x] Protobuf span_id propagation preserves parent-child ordering when available
 
 ---
 
 ## Known Issues / Future Work
 
-### Propagation utilities not yet wired into P2P flow
-
-`extractFromProtobuf()` and `injectToProtobuf()` in `TraceContextPropagator.h`
-are implemented and tested but not called from production code. To enable
-cross-node distributed traces:
-
-- Call `injectToProtobuf()` in `PeerImp` when sending `TMTransaction` /
-  `TMProposeSet` messages
-- Call `extractFromProtobuf()` in the corresponding message handlers to
-  reconstruct the parent span context, then pass it to `startSpan()` as the
-  parent
-
-This was deferred to validate single-node tracing performance first.
-
 ### Unused trace_state proto field
 
 The `TraceContext.trace_state` field (field 4) in `xrpl.proto` is reserved for

OpenTelemetryPlan/Phase4_taskList.md

@@ -17,30 +17,25 @@
 
 ---
 
-## Task 4.1: Instrument Consensus Round Start
+## Task 4.1: Instrument Consensus Round Start ✅
 
 **Objective**: Create a root span for each consensus round that captures the round's key parameters.
 
-**What to do**:
+**Status**: DONE (implemented via Task 4a.2 `startRoundTracing()` helper).
 
-- Edit `src/xrpld/app/consensus/RCLConsensus.cpp`:
-  - In `RCLConsensus::startRound()` (or the Adaptor's startRound):
-    - Create `consensus.round` span using `XRPL_TRACE_CONSENSUS` macro
-    - Set attributes:
-      - `xrpl.consensus.ledger.prev` — previous ledger hash
-      - `xrpl.consensus.ledger.seq` — target ledger sequence
-      - `xrpl.consensus.proposers` — number of trusted proposers
-      - `xrpl.consensus.mode` — "proposing" or "observing"
-    - Store the span context for use by child spans in phase transitions
+**What was done**:
 
-- Add a member to hold current round trace context:
-  - `opentelemetry::context::Context currentRoundContext_` (guarded by `#ifdef`)
-  - Updated at round start, used by phase transition spans
+- `RCLConsensus::Adaptor::startRoundTracing()` creates `consensus.round` span
+  via `SpanGuard::hashSpan()` (deterministic) or `SpanGuard::span()` (attribute strategy)
+- Attributes set: `xrpl.consensus.ledger_id`, `xrpl.consensus.ledger.seq`,
+  `xrpl.consensus.mode`, `xrpl.consensus.trace_strategy`, `xrpl.consensus.round_id`
+- Round span stored as `roundSpan_` member in `RCLConsensus::Adaptor`
+- `roundSpanContext_` snapshot captured for cross-thread span linking
 
 **Key modified files**:
 
 - `src/xrpld/app/consensus/RCLConsensus.cpp`
-- `src/xrpld/app/consensus/RCLConsensus.h` (add context member)
+- `src/xrpld/app/consensus/RCLConsensus.h` (span and context members)
 
 **Reference**:
 
@@ -49,30 +44,27 @@
 
 ---
 
-## Task 4.2: Instrument Phase Transitions
+## Task 4.2: Instrument Phase Transitions ✅
 
 **Objective**: Create child spans for each consensus phase (open, establish, accept) to show timing breakdown.
 
-**What to do**:
+**Status**: DONE. All consensus phases are now instrumented:
 
-- Edit `src/xrpld/app/consensus/RCLConsensus.cpp`:
-  - Identify where phase transitions occur (the `Consensus<Adaptor>` template drives this)
-  - For each phase entry:
-    - Create span as child of `currentRoundContext_`: `consensus.phase.open`, `consensus.phase.establish`, `consensus.phase.accept`
-    - Set `xrpl.consensus.phase` attribute
-    - Add `phase.enter` event at start, `phase.exit` event at end
-    - Record phase duration in milliseconds
+- `consensus.establish` — created in `Consensus.h::startEstablishTracing()`
+- `consensus.ledger_close` — created in `RCLConsensus.cpp::onClose()`
+- `consensus.accept` / `consensus.accept.apply` — created in `onAccept()` / `doAccept()`
+- `consensus.phase.open` — `openSpan_` member in `Consensus.h`, created in `startRoundInternal()`, ended in `closeLedger()`
 
-  - In the `onClose` adaptor method:
-    - Create `consensus.ledger_close` span
-    - Set attributes: close_time, mode, transaction count in initial position
+**Design notes**:
 
-  - Note: The Consensus template class in `src/xrpld/consensus/Consensus.h` drives phase transitions — Phase 4a instruments directly in the template
+- `xrpl.consensus.phase` attribute — phases are distinguished by span names instead
+- `phase.enter` / `phase.exit` events — not added (span start/end serves this purpose)
+- `xrpl.consensus.phase_duration_ms` attribute — not set (span duration captures this)
 
 **Key modified files**:
 
 - `src/xrpld/app/consensus/RCLConsensus.cpp`
-- Possibly `include/xrpl/consensus/Consensus.h` (for template-level phase tracking)
+- `src/xrpld/consensus/Consensus.h` (template-level establish phase tracking)
 
 **Reference**:
 
@@ -80,25 +72,26 @@
 
 ---
 
-## Task 4.3: Instrument Proposal Handling
+## Task 4.3: Instrument Proposal Handling ✅
 
 **Objective**: Trace proposal send and receive to show validator coordination.
 
-**What to do**:
+**Status**: DONE. Both send and receive paths are instrumented.
 
-- Edit `src/xrpld/app/consensus/RCLConsensus.cpp`:
-  - In `Adaptor::propose()`:
-    - Create `consensus.proposal.send` span
-    - Set attributes: `xrpl.consensus.round` (proposal sequence), proposal hash
-    - Inject trace context into outgoing `TMProposeSet::trace_context` (from Phase 3 protobuf)
+**What was done**:
 
-  - In `Adaptor::peerProposal()` (or wherever peer proposals are received):
-    - Extract trace context from incoming `TMProposeSet::trace_context`
-    - Create `consensus.proposal.receive` span as child of extracted context
-    - Set attributes: `xrpl.consensus.proposer` (node ID), `xrpl.consensus.round`
+- In `Adaptor::propose()`:
+  - Creates `consensus.proposal.send` span via `SpanGuard::span()`
+  - Sets `xrpl.consensus.round` attribute
 
-  - In `Adaptor::share(RCLCxPeerPos)`:
-    - Create `consensus.proposal.relay` span for relaying peer proposals
+- In `PeerImp::onMessage(TMProposeSet)`:
+  - Creates `consensus.proposal.receive` span
+  - Sets `xrpl.consensus.proposal.trusted` attribute (bool)
+
+**Not implemented** (deferred to Phase 4b — cross-node propagation):
+
+- `consensus.proposal.relay` span in `share(RCLCxPeerPos)` — requires trace context injection
+- Trace context injection/extraction for `TMProposeSet::trace_context`
 
 **Key modified files**:
 
@@ -111,73 +104,84 @@
 
 ---
 
-## Task 4.4: Instrument Validation Handling
+## Task 4.4: Instrument Validation Handling ✅
 
 **Objective**: Trace validation send and receive to show ledger validation flow.
 
-**What to do**:
+**Status**: DONE. Both send and receive paths are instrumented.
 
-- Edit `src/xrpld/app/consensus/RCLConsensus.cpp` (or the validation handler):
-  - When sending our validation:
-    - Create `consensus.validation.send` span
-    - Set attributes: validated ledger hash, sequence, signing time
+**What was done**:
 
-  - When receiving a peer validation:
-    - Extract trace context from `TMValidation::trace_context` (if present)
-    - Create `consensus.validation.receive` span
-    - Set attributes: `xrpl.consensus.validator` (node ID), ledger hash
+- In `Adaptor::validate()` (called from `doAccept()`):
+  - Creates `consensus.validation.send` span via `Adaptor::createValidationSpan()`
+  - Uses `SpanGuard::linkedSpan()` to create a follows-from link to the round span
+  - Thread-safe: uses `roundSpanContext_` snapshot (captured on consensus thread,
+    read on jtACCEPT thread)
+  - Sets `xrpl.consensus.ledger.seq` and `xrpl.consensus.proposing` attributes
+
+- In `PeerImp::onMessage(TMValidation)`:
+  - Creates `consensus.validation.receive` span
+  - Sets `xrpl.consensus.validation.trusted` attribute (bool)
+  - Sets `xrpl.consensus.validation.ledger_seq` attribute
+
+**Not implemented** (deferred to Phase 4b — cross-node propagation):
+
+- Validated ledger hash, signing time attributes on send span (see Task 4.8)
 
 **Key modified files**:
 
 - `src/xrpld/app/consensus/RCLConsensus.cpp`
-- `src/xrpld/app/misc/NetworkOPs.cpp` (if validation handling is here)
 
 ---
 
-## Task 4.5: Add Consensus-Specific Attributes
+## Task 4.5: Add Consensus-Specific Attributes ✅
 
 **Objective**: Enrich consensus spans with detailed attributes for debugging and analysis.
 
-**What to do**:
+**Status**: DONE. All core attributes are set across various spans, including the previously missing `tx_count` and `disputes_count`.
 
-- Review all consensus spans and ensure they include:
-  - `xrpl.consensus.ledger.seq` — target ledger sequence number
-  - `xrpl.consensus.round` — consensus round number
-  - `xrpl.consensus.mode` — proposing/observing/wrongLedger
-  - `xrpl.consensus.phase` — current phase name
-  - `xrpl.consensus.phase_duration_ms` — time spent in phase
-  - `xrpl.consensus.proposers` — number of trusted proposers
-  - `xrpl.consensus.tx_count` — transactions in proposed set
-  - `xrpl.consensus.disputes` — number of disputed transactions
-  - `xrpl.consensus.converge_percent` — convergence percentage
+**Implemented attributes** (across various spans):
+
+- `xrpl.consensus.ledger.seq` — on `consensus.round`, `consensus.accept.apply`
+- `xrpl.consensus.round` — on `consensus.proposal.send`
+- `xrpl.consensus.mode` — on `consensus.round`, `consensus.ledger_close`
+- `xrpl.consensus.proposers` — on `consensus.accept`, `consensus.establish`, `consensus.update_positions`
+- `xrpl.consensus.converge_percent` — on `consensus.establish`, `consensus.update_positions`, `consensus.check`
+- `xrpl.consensus.tx_count` — on `consensus.accept.apply` span (in `doAccept()`)
+- `xrpl.consensus.disputes_count` — on `consensus.update_positions` span (in `updateOurPositions()`)
+
+**Design notes**:
+
+- `xrpl.consensus.phase` — phases distinguished by span names instead
+- `xrpl.consensus.phase_duration_ms` — span duration captures this
 
 **Key modified files**:
 
 - `src/xrpld/app/consensus/RCLConsensus.cpp`
+- `src/xrpld/consensus/Consensus.h`
 
 ---
 
-## Task 4.6: Correlate Transaction and Consensus Traces
+## Task 4.6: Correlate Transaction and Consensus Traces ✅
 
 **Objective**: Link transaction traces from Phase 3 with consensus traces so you can follow a transaction from submission through consensus into the ledger.
 
-**What to do**:
+**Status**: DONE. Transaction-consensus correlation implemented via `tx.included` events in `doAccept()`.
 
-- In `onClose()` or `onAccept()`:
-  - When building the consensus position, link the round span to individual transaction spans using span links (if OTel SDK supports it) or events
-  - At minimum, record the transaction hashes included in the consensus set as span events: `tx.included` with `xrpl.tx.hash` attribute
+**What was done**:
 
-- In `processTransactionSet()` (NetworkOPs):
-  - If the consensus round span context is available, create child spans for each transaction applied to the ledger
+- In `doAccept()` (RCLConsensus.cpp):
+  - Records `tx.included` events on the `consensus.accept.apply` span for each transaction in the accepted set
+  - Each event includes `xrpl.tx.id` attribute with the transaction hash
+  - This links consensus traces to individual transactions
 
 **Key modified files**:
 
 - `src/xrpld/app/consensus/RCLConsensus.cpp`
-- `src/xrpld/app/misc/NetworkOPs.cpp`
 
 ---
 
-## Task 4.7: Build Verification and Testing
+## Task 4.7: Build Verification and Testing ✅
 
 **Objective**: Verify all Phase 4 changes compile and don't affect consensus timing.
 
@@ -186,20 +190,20 @@
 1. Build with `telemetry=ON` — verify no compilation errors
 2. Build with `telemetry=OFF` — verify no regressions (critical for consensus code)
 3. Run existing consensus-related unit tests
-4. Verify that all macros expand to no-ops when disabled
+4. Verify that `SpanGuard` factory methods compile to no-ops when disabled
 5. Check that no consensus-critical code paths are affected by instrumentation overhead
 
 **Verification Checklist**:
 
-- [ ] Build succeeds with telemetry ON
-- [ ] Build succeeds with telemetry OFF
-- [ ] Existing consensus tests pass
-- [ ] No new includes in consensus headers when telemetry is OFF
-- [ ] Phase timing instrumentation doesn't use blocking operations
+- [x] Build succeeds with telemetry ON
+- [x] Build succeeds with telemetry OFF
+- [x] Existing consensus tests pass
+- [x] `SpanGuard` no-op implementation prevents overhead when telemetry is OFF
+- [x] Phase timing instrumentation doesn't use blocking operations
 
 ---
 
-## Task 4.8: Consensus Validation Span Enrichment — External Dashboard Parity
+## Task 4.8: Consensus Validation Span Enrichment — NOT DONE
 
 > **Source**: [External Dashboard Parity](../docs/superpowers/specs/2026-03-30-external-dashboard-parity-design.md) — adds validation agreement context inspired by the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
 >
@@ -208,6 +212,8 @@
 
 **Objective**: Add ledger hash, validation type, and quorum data to consensus validation spans on both send and receive paths. This enables trace-level validation agreement analysis — filter by ledger hash to see which validators agreed for a given ledger.
 
+**Status**: Not implemented. None of the enrichment attributes are set. The `consensus.validation.send` span only has `ledger.seq` and `proposing`. The `consensus.accept` span has `quorum` set to `result.proposers` (not the actual validator quorum from `app_.validators().quorum()`). No `PeerImp.cpp` changes were made.
+
 **What to do**:
 
 - Edit `src/xrpld/app/consensus/RCLConsensus.cpp`:
@@ -242,7 +248,7 @@
 
 Phase 7's `ValidationTracker` builds metric-level aggregation (1h/24h agreement %) on top of this data.
 
-**Key modified files**:
+**Key modified files (not yet modified)**:
 
 - `src/xrpld/app/consensus/RCLConsensus.cpp`
 - `src/xrpld/overlay/detail/PeerImp.cpp`
@@ -259,16 +265,16 @@ Phase 7's `ValidationTracker` builds metric-level aggregation (1h/24h agreement
 
 ## Summary
 
-| Task | Description                                 | New Files | Modified Files | Depends On    |
-| ---- | ------------------------------------------- | --------- | -------------- | ------------- |
-| 4.1  | Consensus round start instrumentation       | 0         | 2              | Phase 3       |
-| 4.2  | Phase transition instrumentation            | 0         | 1-2            | 4.1           |
-| 4.3  | Proposal handling instrumentation           | 0         | 1              | 4.1           |
-| 4.4  | Validation handling instrumentation         | 0         | 1-2            | 4.1           |
-| 4.5  | Consensus-specific attributes               | 0         | 1              | 4.2, 4.3, 4.4 |
-| 4.6  | Transaction-consensus correlation           | 0         | 2              | 4.2, Phase 3  |
-| 4.7  | Build verification and testing              | 0         | 0              | 4.1-4.6       |
-| 4.8  | Validation span enrichment (ext. dashboard) | 0         | 2              | 4.4           |
+| Task | Description                                 | Status      | New Files | Modified Files | Depends On    |
+| ---- | ------------------------------------------- | ----------- | --------- | -------------- | ------------- |
+| 4.1  | Consensus round start instrumentation       | ✅ Done     | 0         | 2              | Phase 3       |
+| 4.2  | Phase transition instrumentation            | ✅ Done     | 0         | 1-2            | 4.1           |
+| 4.3  | Proposal handling instrumentation           | ✅ Done     | 0         | 2              | 4.1           |
+| 4.4  | Validation handling instrumentation         | ✅ Done     | 0         | 2              | 4.1           |
+| 4.5  | Consensus-specific attributes               | ✅ Done     | 0         | 2              | 4.2, 4.3, 4.4 |
+| 4.6  | Transaction-consensus correlation           | ✅ Done     | 0         | 1              | 4.2, Phase 3  |
+| 4.7  | Build verification and testing              | ✅ Done     | 0         | 0              | 4.1-4.6       |
+| 4.8  | Validation span enrichment (ext. dashboard) | ❌ Not done | 0         | 2              | 4.4           |
 
 **Parallel work**: Tasks 4.2, 4.3, and 4.4 can run in parallel after 4.1 is complete. Task 4.5 depends on all three. Task 4.6 depends on 4.2 and Phase 3. Task 4.8 depends on 4.4 (validation spans must exist).
 
@@ -301,10 +307,12 @@ driven by `avCT_CONSENSUS_PCT` (75% validator agreement threshold):
 **Exit Criteria** (from [06-implementation-phases.md §6.11.4](./06-implementation-phases.md)):
 
 - [x] Complete consensus round traces
-- [x] Phase transitions visible
-- [x] Proposals and validations traced
+- [x] Phase transitions visible (open, establish, close, accept)
+- [x] Proposals and validations traced — send and receive; relay deferred to Phase 4b
 - [x] Close time agreement tracked (per `avCT_CONSENSUS_PCT`)
 - [x] No impact on consensus timing
+- [x] Transaction-consensus correlation (Task 4.6) — `tx.included` events in doAccept
+- [ ] Validation span enrichment (Task 4.8) — not implemented
 
 ---
 
@@ -314,14 +322,13 @@ driven by `avCT_CONSENSUS_PCT` (75% validator agreement threshold):
 > threshold escalation, mode changes) and establish cross-node correlation using a
 > deterministic shared trace ID derived from `previousLedger.id()`.
 >
-> **Approach**: Direct instrumentation in `Consensus.h` — the generic consensus
-> template has full access to internal state (`convergePercent_`, `result_->disputes`,
-> `mode_`, threshold logic). Telemetry access comes via a single new adaptor
-> method `getTelemetry()`. Long-lived spans (round, establish) are stored as
-> class members using `SpanGuard` directly — NOT the `XRPL_TRACE_*` convenience
-> macros (which create local variables named `_xrpl_guard_`). Short-lived
-> scoped spans (update_positions, check) can use the macros. All code compiles
-> to no-ops when `XRPL_ENABLE_TELEMETRY` is not defined.
+> **Approach**: Direct instrumentation in `Consensus.h` and `RCLConsensus.cpp`.
+> All spans use `SpanGuard` factory methods (`span()`, `hashSpan()`, `linkedSpan()`)
+> with `TraceCategory::Consensus` gating. Long-lived spans (round, establish) are
+> stored as `std::optional<SpanGuard>` class members. Short-lived scoped spans
+> (update_positions, check) are local variables. No macros are used — all tracing
+> is via direct `SpanGuard` API calls. `SpanGuard` compiles to no-ops when
+> telemetry is disabled.
 >
 > **Branch**: `pratik/otel-phase4-consensus-tracing`
 
@@ -356,6 +363,9 @@ on every consensus span. Correlation happens at query time via Tempo/Grafana
 consensus_trace_strategy=deterministic
 ```
 
+The C++ API to query this at runtime is `Telemetry::getConsensusTraceStrategy()`,
+which returns a `std::string const&` (`"deterministic"` or `"attribute"`).
+
 ### Implementation
 
 In `RCLConsensus::Adaptor::startRound()`:
@@ -409,267 +419,252 @@ consensus.round  (root — created in RCLConsensus::startRound, closed at accept
 
 ---
 
-## Task 4a.0: Prerequisites — Extend SpanGuard and Telemetry APIs
+## Task 4a.0: Prerequisites — Extend SpanGuard and Telemetry APIs ✅
 
 **Objective**: Add missing API surface needed by later tasks.
 
-**What to do**:
+**Status**: Done, but implemented differently than originally planned. The macro-based
+approach (`XRPL_TRACE_CONSENSUS`, `XRPL_TRACE_ADD_EVENT`, `XRPL_TRACE_SET_ATTR`) was
+**not used**. Instead, all consensus tracing uses `SpanGuard` factory methods and
+direct method calls, which is cleaner and avoids macro control-flow issues.
 
-1. **Add `SpanGuard::addEvent()` with attributes** (needed by Task 4a.5):
-   The current `addEvent(string_view name)` only accepts a name. Add an
-   overload that accepts key-value attributes:
+**What was done**:
+
+1. **`SpanGuard::addEvent()` with attributes** — implemented as planned:
 
    ```cpp
+   using EventAttribute = std::pair<std::string_view, std::string_view>;
+
    void addEvent(std::string_view name,
-       std::initializer_list<
-           std::pair<opentelemetry::nostd::string_view,
-                     opentelemetry::common::AttributeValue>> attributes)
-   {
-       span_->AddEvent(std::string(name), attributes);
-   }
+       std::initializer_list<EventAttribute> attrs);
    ```
 
-2. **Add a `Telemetry::startSpan()` overload that accepts span links** (needed by Tasks 4a.2, 4a.8):
-   The current `startSpan()` has no span link support. Add an overload that
-   accepts a vector of `SpanContext` links for follows-from relationships:
+   Callers pass plain `string_view` pairs; the implementation converts internally.
 
    ```cpp
-   virtual opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span>
-   startSpan(
-       std::string_view name,
-       opentelemetry::context::Context const& parentContext,
-       std::vector<opentelemetry::trace::SpanContext> const& links,
-       opentelemetry::trace::SpanKind kind = opentelemetry::trace::SpanKind::kInternal) = 0;
+   // Actual usage in Consensus.h::updateOurPositions():
+   span.addEvent(
+       "dispute.resolve",
+       {{cons_span::attr::txId, to_string(txId)},
+        {cons_span::attr::disputeOurVote, dispute.getOurVote() ? "yes" : "no"}});
    ```
 
-3. **Add `XRPL_TRACE_ADD_EVENT` macro** (needed by Task 4a.5):
-   Add to `TracingInstrumentation.h` to expose `addEvent(name, attrs)` through
-   the macro interface (consistent with `XRPL_TRACE_SET_ATTR` pattern):
+2. **Span link support** — implemented via `SpanGuard::linkedSpan()` static factory
+   instead of a `Telemetry::startSpan()` overload:
+
    ```cpp
-   #ifdef XRPL_ENABLE_TELEMETRY
-   #define XRPL_TRACE_ADD_EVENT(name, ...)               \
-       if (_xrpl_guard_.has_value())                     \
-       {                                                 \
-           _xrpl_guard_->addEvent(name, __VA_ARGS__);   \
-       }
-   #else
-   #define XRPL_TRACE_ADD_EVENT(name, ...) ((void)0)
-   #endif
+   static SpanGuard linkedSpan(
+       std::string_view name, SpanContext const& linkTarget);
    ```
 
+3. **No macros added** — `TracingInstrumentation.h` was not created. The `XRPL_TRACE_CONSENSUS`,
+   `XRPL_TRACE_ADD_EVENT`, and `XRPL_TRACE_SET_ATTR` macros from the original plan were
+   not implemented. All consensus tracing uses direct `SpanGuard` API:
+   - `SpanGuard::span()` — create scoped spans
+   - `SpanGuard::hashSpan()` — create spans with deterministic trace IDs
+   - `SpanGuard::linkedSpan()` — create spans with follows-from links
+   - `span.setAttribute()` — set attributes directly
+   - `span.addEvent()` — add events directly
+
 **Key modified files**:
 
-- `include/xrpl/telemetry/SpanGuard.h` — add `addEvent()` overload
-- `include/xrpl/telemetry/Telemetry.h` — add `startSpan()` with links
-- `src/xrpld/telemetry/Telemetry.cpp` — implement new overload
-- `src/xrpld/telemetry/NullTelemetry.cpp` — no-op implementation
-- `src/xrpld/telemetry/TracingInstrumentation.h` — add `XRPL_TRACE_ADD_EVENT` macro
+- `include/xrpl/telemetry/SpanGuard.h` — `addEvent()` overload, `EventAttribute` type alias
+- `src/libxrpl/telemetry/SpanGuard.cpp` — `addEvent()` implementation
 
 ---
 
-## Task 4a.1: Adaptor `getTelemetry()` Method
+## Task 4a.1: Adaptor `getTelemetry()` Method — NOT DONE (Not Needed)
 
 **Objective**: Give `Consensus.h` access to the telemetry subsystem without
 coupling the generic template to OTel headers.
 
-**What to do**:
+**Status**: Not implemented as specified. The `getTelemetry()` adaptor method was
+not needed because `SpanGuard::span()` is a static factory method that internally
+checks telemetry state via the global `Telemetry` singleton. `Consensus.h` creates
+spans by calling `SpanGuard::span(TraceCategory::Consensus, ...)` directly, without
+needing adaptor access. Only `RCLConsensus::Adaptor` uses `app_.getTelemetry()`
+directly (for `getConsensusTraceStrategy()` in `startRoundTracing()`).
 
-- Add `getTelemetry()` method to the Adaptor concept (returns
-  `xrpl::telemetry::Telemetry&`). The return type is already forward-declared
-  behind `#ifdef XRPL_ENABLE_TELEMETRY`.
-- Implement in `RCLConsensus::Adaptor` — delegates to `app_.getTelemetry()`.
-- In `Consensus.h`, the `XRPL_TRACE_*` macros call
-  `adaptor_.getTelemetry()` — when telemetry is disabled, the macros expand to
-  `((void)0)` and the method is never called.
-
-**Key modified files**:
-
-- `src/xrpld/app/consensus/RCLConsensus.h` — declare `getTelemetry()`
-- `src/xrpld/app/consensus/RCLConsensus.cpp` — implement `getTelemetry()`
+**Key insight**: The `XRPL_TRACE_*` macro approach would have required
+`adaptor_.getTelemetry()`. Since macros were not used, this task became unnecessary.
 
 ---
 
-## Task 4a.2: Switchable Round Span with Deterministic Trace ID
+## Task 4a.2: Switchable Round Span with Deterministic Trace ID ✅
 
 **Objective**: Create a `consensus.round` root span in `startRound()` that uses
 the switchable correlation strategy. Store span context as a member for child
 spans in `Consensus.h`.
 
-**What to do**:
+**Status**: Done. Implemented in `Adaptor::startRoundTracing()`.
 
-- In `RCLConsensus::Adaptor::startRound()` (or a new helper):
-  - Read `consensus_trace_strategy` from config.
-  - **Deterministic**: compute `trace_id = SHA256(prevLedgerID)[0:16]`.
-    Construct a `SpanContext` with this trace_id, then start
-    `consensus.round` span as child of that context.
-  - **Attribute**: start normal `consensus.round` span.
-  - Set attributes on both: `xrpl.consensus.round_id`,
-    `xrpl.consensus.ledger_id`, `xrpl.consensus.ledger.seq`,
-    `xrpl.consensus.mode`.
-  - Store the round span in `Consensus` as a member (see Task 4a.3).
-  - If a previous round's span context is available, add a **span link**
-    (follows-from) to establish the round chain.
+**What was done**:
 
-- Add `createDeterministicTraceId(hash)` utility to
-  `include/xrpl/telemetry/Telemetry.h` (returns 16-byte trace ID from a
-  256-bit hash by truncation).
+- `RCLConsensus::Adaptor::startRoundTracing()` helper:
+  - Reads `consensus_trace_strategy` via `app_.getTelemetry().getConsensusTraceStrategy()`
+  - **Deterministic**: uses `SpanGuard::hashSpan()` with `prevLgr.id()` data
+  - **Attribute**: uses `SpanGuard::span(TraceCategory::Consensus, seg::consensus, "round")`
+  - Sets attributes: `ledger_id`, `ledger.seq`, `mode`, `trace_strategy`, `round_id`
+  - Captures `roundSpanContext_` snapshot for cross-thread span linking
+  - Saves `prevRoundContext_` from previous round for follows-from links
+
+- **`SpanGuard::hashSpan()` factory**: encapsulates deterministic trace ID logic:
 
-- Add `consensus_trace_strategy` to `Telemetry::Setup` and
-  `TelemetryConfig.cpp` parser:
   ```cpp
-  /** Cross-node correlation strategy: "deterministic" or "attribute". */
-  std::string consensusTraceStrategy = "deterministic";
+  static SpanGuard hashSpan(
+      TraceCategory cat, std::string_view name,
+      std::uint8_t const* hashData, std::size_t hashSize);
   ```
 
+  Derives `trace_id = hashData[0:16]` so all nodes in the same round share
+  the same trace_id. Compiles to no-op when telemetry is disabled.
+
+- `consensus_trace_strategy` config parsed in `TelemetryConfig.cpp`,
+  stored in `Telemetry::Setup`, accessible via `Telemetry::getConsensusTraceStrategy()`
+
 **Key modified files**:
 
-- `src/xrpld/app/consensus/RCLConsensus.cpp`
-- `include/xrpl/telemetry/Telemetry.h` — `createDeterministicTraceId()`
-- `src/xrpld/telemetry/TelemetryConfig.cpp` — parse new config option
+- `src/xrpld/app/consensus/RCLConsensus.cpp` — `startRoundTracing()` implementation
+- `src/xrpld/app/consensus/ConsensusSpanNames.h` — **(new)** compile-time span name and attribute key constants
+- `include/xrpl/telemetry/Telemetry.h` — `consensusTraceStrategy` in Setup, `getConsensusTraceStrategy()`
+- `src/libxrpl/telemetry/TelemetryConfig.cpp` — parse new config option
 
 ---
 
-## Task 4a.3: Span Members in `Consensus.h`
+## Task 4a.3: Span Members in `Consensus.h` ✅
 
 **Objective**: Add span storage to the `Consensus` class so that spans created
 in `startRound()` (adaptor) are accessible from `phaseEstablish()`,
 `updateOurPositions()`, and `haveConsensus()` (template methods).
 
-**What to do**:
+**Status**: Done with documented plan deviation.
+
+**What was done**:
+
+- `establishSpan_` added to `Consensus` private members (as planned):
 
-- Add to `Consensus` private members (guarded by `#ifdef XRPL_ENABLE_TELEMETRY`):
   ```cpp
-  #ifdef XRPL_ENABLE_TELEMETRY
-  std::optional<xrpl::telemetry::SpanGuard> roundSpan_;
   std::optional<xrpl::telemetry::SpanGuard> establishSpan_;
-  opentelemetry::context::Context prevRoundContext_;
-  #endif
   ```
-- `roundSpan_` is created in `startRound()` via the adaptor and stored.
-  Its `SpanGuard::Scope` member keeps the span active on the thread context
-  for the entire round lifetime.
-- `establishSpan_` is created when entering phaseEstablish and cleared on accept.
-  It becomes a child of `roundSpan_` via OTel's thread-local context propagation.
-- `prevRoundContext_` stores the previous round's context for follows-from links.
 
-**Threading assumption**: `startRound()`, `phaseEstablish()`, `updateOurPositions()`,
-and `haveConsensus()` all run on the same thread (the consensus job queue thread).
-This is required for the `SpanGuard::Scope`-based parent-child hierarchy to work.
-The `Consensus` class documentation confirms it is NOT thread-safe and calls are
-serialized by the application.
+- **Plan deviation**: `roundSpan_`, `prevRoundContext_`, and `roundSpanContext_`
+  are stored in `RCLConsensus::Adaptor` (not `Consensus.h`) because the adaptor
+  has access to telemetry config for the deterministic trace ID strategy.
 
-- Add conditional include at top of `Consensus.h`:
+- **No `#ifdef XRPL_ENABLE_TELEMETRY` guards**: Members use `std::optional<SpanGuard>`
+  and `SpanContext` which have no-op implementations when telemetry is disabled,
+  so `#ifdef` guards are unnecessary. The members are always present in the class
+  layout but incur negligible overhead.
+
+- Includes added unconditionally to `Consensus.h`:
   ```cpp
-  #ifdef XRPL_ENABLE_TELEMETRY
   #include <xrpl/telemetry/SpanGuard.h>
-  #include <xrpld/telemetry/TracingInstrumentation.h>
-  #endif
+  #include <xrpld/app/consensus/ConsensusSpanNames.h>
   ```
+  No `TracingInstrumentation.h` include (file doesn't exist; macros not used).
 
 **Key modified files**:
 
 - `src/xrpld/consensus/Consensus.h`
+- `src/xrpld/app/consensus/RCLConsensus.h` (round span and context members)
 
 ---
 
-## Task 4a.4: Instrument `phaseEstablish()`
+## Task 4a.4: Instrument `phaseEstablish()` ✅
 
 **Objective**: Create `consensus.establish` span wrapping the establish phase,
 with attributes for convergence progress.
 
-**What to do**:
+**Status**: Done. Implemented via three private helpers in `Consensus.h`.
 
-- At the start of `phaseEstablish()` (line 1298), if `establishSpan_` is not
-  yet created, create it as child of `roundSpan_` using the **direct API**
-  (NOT the `XRPL_TRACE_CONSENSUS` macro, which creates a local variable):
+**What was done**:
 
-  ```cpp
-  #ifdef XRPL_ENABLE_TELEMETRY
-  if (!establishSpan_ && adaptor_.getTelemetry().shouldTraceConsensus())
-  {
-      establishSpan_.emplace(
-          adaptor_.getTelemetry().startSpan("consensus.establish"));
-  }
-  #endif
-  ```
+- `startEstablishTracing()` — creates `consensus.establish` span via
+  `SpanGuard::span(TraceCategory::Consensus, seg::consensus, "establish")`.
+  Called once at start of establish phase. No `#ifdef` guards needed —
+  `SpanGuard::span()` returns a no-op guard when telemetry is disabled.
 
-- Set attributes on each call:
+- `updateEstablishTracing()` — sets attributes on each `phaseEstablish()` call:
   - `xrpl.consensus.converge_percent` — `convergePercent_`
   - `xrpl.consensus.establish_count` — `establishCounter_`
   - `xrpl.consensus.proposers` — `currPeerPositions_.size()`
 
-- On phase exit (transition to accept), close the establish span and record
-  final duration.
+- `endEstablishTracing()` — calls `establishSpan_.reset()` on phase exit.
 
 **Key modified files**:
 
-- `src/xrpld/consensus/Consensus.h` — `phaseEstablish()` method
+- `src/xrpld/consensus/Consensus.h` — `phaseEstablish()` method + 3 helper methods
 
 ---
 
-## Task 4a.5: Instrument `updateOurPositions()`
+## Task 4a.5: Instrument `updateOurPositions()` ✅
 
 **Objective**: Trace each position update cycle including dispute resolution
 details.
 
-**What to do**:
+**Status**: DONE. Span, dispute events with yays/nays, and disputes_count attribute are all implemented.
 
-- At the start of `updateOurPositions()` (line 1418), create a scoped child
-  span. This method is called and returns within a single `phaseEstablish()`
-  call, so the `XRPL_TRACE_CONSENSUS` macro works here (scoped local):
+**What was done**:
+
+- Creates `consensus.update_positions` scoped span via
+  `SpanGuard::span(TraceCategory::Consensus, seg::consensus, "update_positions")`:
 
   ```cpp
-  XRPL_TRACE_CONSENSUS(adaptor_.getTelemetry(), "consensus.update_positions");
+  auto span = SpanGuard::span(TraceCategory::Consensus, seg::consensus, "update_positions");
   ```
 
-- Set attributes:
-  - `xrpl.consensus.disputes_count` — `result_->disputes.size()`
+- Attributes set:
   - `xrpl.consensus.converge_percent` — current convergence
-  - `xrpl.consensus.proposers_agreed` — count of peers with same position
-  - `xrpl.consensus.proposers_total` — total peer positions
+  - `xrpl.consensus.proposers` — `currPeerPositions_.size()`
+  - `xrpl.consensus.have_close_time_consensus` — close time consensus state
+  - `xrpl.consensus.close_time_threshold` — `avCT_CONSENSUS_PCT`
+  - `xrpl.consensus.disputes_count` — number of active disputes
 
-- Inside the dispute resolution loop, for each dispute that changes our vote,
-  add an **event** with attributes using `XRPL_TRACE_ADD_EVENT` (from Task 4a.0):
+- Dispute events recorded via direct `span.addEvent()` call with yays/nays:
   ```cpp
-  XRPL_TRACE_ADD_EVENT("dispute.resolve", {
-      {"xrpl.tx.id", std::string(tx_id)},
-      {"xrpl.dispute.our_vote", our_vote},
-      {"xrpl.dispute.yays", static_cast<int64_t>(yays)},
-      {"xrpl.dispute.nays", static_cast<int64_t>(nays)}
-  });
+  span.addEvent(
+      "dispute.resolve",
+      {{cons_span::attr::txId, to_string(txId)},
+       {cons_span::attr::disputeOurVote, dispute.getOurVote() ? "yes" : "no"},
+       {cons_span::attr::disputeYays, std::to_string(dispute.getYays())},
+       {cons_span::attr::disputeNays, std::to_string(dispute.getNays())}});
   ```
 
+**Not implemented**:
+
+- `xrpl.consensus.proposers_agreed` / `xrpl.consensus.proposers_total` attributes — not set
+
 **Key modified files**:
 
 - `src/xrpld/consensus/Consensus.h` — `updateOurPositions()` method
+- `src/xrpld/consensus/DisputedTx.h` — added `getYays()` / `getNays()` (currently unused)
 
 ---
 
-## Task 4a.6: Instrument `haveConsensus()` (Threshold & Convergence)
+## Task 4a.6: Instrument `haveConsensus()` (Threshold & Convergence) ✅
 
-**Objective**: Trace consensus checking including threshold escalation
-(`ConsensusParms::AvalancheState::{init, mid, late, stuck}`).
+**Objective**: Trace consensus checking including threshold escalation.
 
-**What to do**:
+**Status**: DONE. The `consensus.check` span is created with all planned attributes
+including the avalanche threshold.
 
-- At the start of `haveConsensus()` (line 1598), create a scoped child span:
+**What was done**:
+
+- Creates `consensus.check` scoped span via
+  `SpanGuard::span(TraceCategory::Consensus, seg::consensus, "check")`:
 
   ```cpp
-  XRPL_TRACE_CONSENSUS(adaptor_.getTelemetry(), "consensus.check");
+  auto span = SpanGuard::span(TraceCategory::Consensus, seg::consensus, "check");
   ```
 
-- Set attributes:
+- Attributes set:
   - `xrpl.consensus.agree_count` — peers that agree with our position
   - `xrpl.consensus.disagree_count` — peers that disagree
   - `xrpl.consensus.converge_percent` — convergence percentage
-  - `xrpl.consensus.result` — ConsensusState result (Yes/No/MovedOn)
-
-- The free function `checkConsensus()` in `Consensus.cpp` (line 151) determines
-  thresholds based on `currentAgreeTime`. Threshold values come from
-  `ConsensusParms::avalancheCutoffs` (defined in `ConsensusParms.h`).
-  The escalation states are `ConsensusParms::AvalancheState::{init, mid, late, stuck}`.
-  Record the effective threshold as an attribute on the span:
-  - `xrpl.consensus.threshold_percent` — current threshold from `avalancheCutoffs`
+  - `xrpl.consensus.have_close_time_consensus` — close time consensus state
+  - `xrpl.consensus.threshold_percent` — set to `avCT_CONSENSUS_PCT` (75%)
+  - `xrpl.consensus.result` — "yes", "no", or "moved_on"
+  - `xrpl.consensus.avalanche_threshold` — the escalated weight from `getNeededWeight()` on the `consensus.update_positions` span
 
 **Key modified files**:
 
@@ -677,29 +672,26 @@ details.
 
 ---
 
-## Task 4a.7: Instrument Mode Changes
+## Task 4a.7: Instrument Mode Changes ✅
 
 **Objective**: Trace consensus mode transitions (proposing ↔ observing,
 wrongLedger, switchedLedger).
 
-**What to do**:
+**Status**: Done.
 
-Mode changes are rare (typically 0-1 per round), so a **standalone short-lived
-span** is appropriate (not an event). This captures timing of the mode change
-itself.
+**What was done**:
 
-- In `RCLConsensus::Adaptor::onModeChange()`, create a scoped span:
+- In `RCLConsensus::Adaptor::onModeChange()`, creates a scoped span via direct
+  `SpanGuard::span()` call:
 
   ```cpp
-  XRPL_TRACE_CONSENSUS(app_.getTelemetry(), "consensus.mode_change");
-  XRPL_TRACE_SET_ATTR("xrpl.consensus.mode.old", to_string(before).c_str());
-  XRPL_TRACE_SET_ATTR("xrpl.consensus.mode.new", to_string(after).c_str());
+  auto span = telemetry::SpanGuard::span(
+      telemetry::TraceCategory::Consensus, telemetry::seg::consensus, "mode_change");
+  span.setAttribute(cons_span::attr::modeOld, to_string(before).c_str());
+  span.setAttribute(cons_span::attr::modeNew, to_string(after).c_str());
   ```
 
-- Note: `MonitoredMode::set()` (line 304 in `Consensus.h`) calls
-  `adaptor_.onModeChange(before, after)` — so the span is created in the
-  adaptor, which already has telemetry access. No instrumentation needed
-  in `Consensus.h` for this task.
+- `MonitoredMode::set()` in `Consensus.h` calls `adaptor_.onModeChange(before, after)`.
 
 **Key modified files**:
 
@@ -707,31 +699,36 @@ itself.
 
 ---
 
-## Task 4a.8: Reparent Existing Spans Under Round
+## Task 4a.8: Reparent Existing Spans Under Round ✅
 
 **Objective**: Make existing consensus spans (`consensus.accept`,
 `consensus.accept.apply`, `consensus.validation.send`) children of the
 `consensus.round` root span instead of being standalone.
 
-**What to do**:
+**Status**: DONE. All three spans are now parented under the round span.
 
-- The existing spans in `onAccept()`, `doAccept()`, and `validate()` use
-  `XRPL_TRACE_CONSENSUS(app_.getTelemetry(), ...)` which creates standalone
-  spans on the current thread's context.
-- After Task 4a.2 creates the round span and stores it, these methods run on
-  the same thread within the round span's scope, so they automatically become
-  children. Verify this works correctly.
-- For `consensus.validation.send`: add a **span link** (follows-from) to the
-  round span context, since the validation may be processed after the round
-  completes.
+**What was done**:
+
+- `consensus.validation.send` uses `SpanGuard::linkedSpan()` to create a
+  follows-from link to `roundSpanContext_`. This is thread-safe because
+  `roundSpanContext_` is a lightweight `SpanContext` snapshot captured on the
+  consensus thread and read on the jtACCEPT worker thread.
+
+- `consensus.accept` and `consensus.accept.apply` now use
+  `SpanGuard::childSpan(name, roundSpanContext_)` instead of `SpanGuard::span()`
+  to explicitly parent under the round span context. This solves the cross-thread
+  parenting problem:
+  - `doAccept()` runs on the jtACCEPT worker thread (not the consensus thread)
+  - `childSpan()` explicitly passes the parent context, bypassing OTel's
+    thread-local context propagation
 
 **Key modified files**:
 
-- `src/xrpld/app/consensus/RCLConsensus.cpp` — verify parent-child hierarchy
+- `src/xrpld/app/consensus/RCLConsensus.cpp`
 
 ---
 
-## Task 4a.9: Build Verification and Testing
+## Task 4a.9: Build Verification and Testing ✅
 
 **Objective**: Verify all Phase 4a changes compile cleanly with telemetry ON
 and OFF, and don't affect consensus timing.
@@ -739,11 +736,9 @@ and OFF, and don't affect consensus timing.
 **What to do**:
 
 1. Build with `telemetry=ON` — verify no compilation errors
-2. Build with `telemetry=OFF` — verify macros expand to no-ops, no new includes
-   leak into `Consensus.h` when disabled
+2. Build with `telemetry=OFF` — verify `SpanGuard` compiles to no-ops
 3. Run existing consensus unit tests
-4. Verify `#ifdef XRPL_ENABLE_TELEMETRY` guards on all new members in
-   `Consensus.h`
+4. Verify `SpanGuard` / `SpanContext` members have negligible overhead when disabled
 5. Run `pccl` pre-commit checks
 
 **Verification Checklist**:
@@ -751,7 +746,7 @@ and OFF, and don't affect consensus timing.
 - [x] Build succeeds with telemetry ON
 - [x] Build succeeds with telemetry OFF
 - [x] Existing consensus tests pass
-- [x] `Consensus.h` has zero OTel includes when telemetry is OFF
+- [x] `SpanGuard` no-op path verified (no `#ifdef` needed — disabled at runtime)
 - [x] No new virtual calls in hot consensus paths
 - [x] `pccl` passes
 
@@ -759,74 +754,91 @@ and OFF, and don't affect consensus timing.
 
 ## Phase 4a Summary
 
-| Task | Description                                      | New Files | Modified Files | Depends On |
-| ---- | ------------------------------------------------ | --------- | -------------- | ---------- |
-| 4a.0 | Prerequisites: extend SpanGuard & Telemetry APIs | 0         | 4              | Phase 4    |
-| 4a.1 | Adaptor `getTelemetry()` method                  | 0         | 2              | Phase 4    |
-| 4a.2 | Switchable round span with deterministic traceID | 0         | 3              | 4a.0, 4a.1 |
-| 4a.3 | Span members in `Consensus.h`                    | 0         | 1              | 4a.1       |
-| 4a.4 | Instrument `phaseEstablish()`                    | 0         | 1              | 4a.3       |
-| 4a.5 | Instrument `updateOurPositions()`                | 0         | 1              | 4a.0, 4a.3 |
-| 4a.6 | Instrument `haveConsensus()` (thresholds)        | 0         | 1              | 4a.3       |
-| 4a.7 | Instrument mode changes                          | 0         | 1              | 4a.1       |
-| 4a.8 | Reparent existing spans under round              | 0         | 1              | 4a.0, 4a.2 |
-| 4a.9 | Build verification and testing                   | 0         | 0              | 4a.0-4a.8  |
+| Task | Description                                      | Status                   | New Files | Modified Files | Depends On |
+| ---- | ------------------------------------------------ | ------------------------ | --------- | -------------- | ---------- |
+| 4a.0 | Prerequisites: extend SpanGuard & Telemetry APIs | ✅ Done (no macros)      | 0         | 2              | Phase 4    |
+| 4a.1 | Adaptor `getTelemetry()` method                  | ⏭️ Skipped (not needed)  | 0         | 0              | Phase 4    |
+| 4a.2 | Switchable round span with deterministic traceID | ✅ Done                  | 1         | 3              | 4a.0       |
+| 4a.3 | Span members in `Consensus.h`                    | ✅ Done (with deviation) | 0         | 2              | —          |
+| 4a.4 | Instrument `phaseEstablish()`                    | ✅ Done                  | 0         | 1              | 4a.3       |
+| 4a.5 | Instrument `updateOurPositions()`                | ✅ Done                  | 0         | 2              | 4a.0, 4a.3 |
+| 4a.6 | Instrument `haveConsensus()` (thresholds)        | ✅ Done                  | 0         | 1              | 4a.3       |
+| 4a.7 | Instrument mode changes                          | ✅ Done                  | 0         | 1              | —          |
+| 4a.8 | Reparent existing spans under round              | ✅ Done                  | 0         | 1              | 4a.0, 4a.2 |
+| 4a.9 | Build verification and testing                   | ✅ Done                  | 0         | 0              | 4a.0-4a.8  |
 
 **Parallel work**: Tasks 4a.0 and 4a.1 can run in parallel. Tasks 4a.4, 4a.5, 4a.6, and 4a.7 can run in parallel after 4a.3 (and 4a.0 for 4a.5).
 
 ### New Spans (Phase 4a)
 
-| Span Name                    | Location           | Key Attributes                                                                     |
-| ---------------------------- | ------------------ | ---------------------------------------------------------------------------------- |
-| `consensus.round`            | `RCLConsensus.cpp` | `round_id`, `ledger_id`, `ledger.seq`, `mode`; link → prev round                   |
-| `consensus.establish`        | `Consensus.h`      | `converge_percent`, `establish_count`, `proposers`                                 |
-| `consensus.update_positions` | `Consensus.h`      | `disputes_count`, `converge_percent`, `proposers_agreed`, `proposers_total`        |
-| `consensus.check`            | `Consensus.h`      | `agree_count`, `disagree_count`, `converge_percent`, `result`, `threshold_percent` |
-| `consensus.mode_change`      | `RCLConsensus.cpp` | `mode.old`, `mode.new`                                                             |
+| Span Name                    | Location           | Key Attributes (actually set)                                                                                                 |
+| ---------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `consensus.round`            | `RCLConsensus.cpp` | `round_id`, `ledger_id`, `ledger.seq`, `mode`, `trace_strategy`                                                               |
+| `consensus.establish`        | `Consensus.h`      | `converge_percent`, `establish_count`, `proposers`                                                                            |
+| `consensus.update_positions` | `Consensus.h`      | `converge_percent`, `proposers`, `have_close_time_consensus`, `close_time_threshold`, `disputes_count`, `avalanche_threshold` |
+| `consensus.check`            | `Consensus.h`      | `agree_count`, `disagree_count`, `converge_percent`, `have_close_time_consensus`, `threshold_percent`, `result`               |
+| `consensus.mode_change`      | `RCLConsensus.cpp` | `mode.old`, `mode.new`                                                                                                        |
 
 ### New Events (Phase 4a)
 
-| Event Name        | Parent Span                  | Attributes                          |
+| Event Name        | Parent Span                  | Attributes (actually set)           |
 | ----------------- | ---------------------------- | ----------------------------------- |
 | `dispute.resolve` | `consensus.update_positions` | `tx_id`, `our_vote`, `yays`, `nays` |
+| `tx.included`     | `consensus.accept.apply`     | `tx_id`                             |
 
 ### New Attributes (Phase 4a)
 
 ```cpp
-// Round-level (on consensus.round)
+// Round-level (on consensus.round) — ALL IMPLEMENTED
 "xrpl.consensus.round_id"              = int64    // Consensus round number
 "xrpl.consensus.ledger_id"             = string   // previousLedger.id() hash
 "xrpl.consensus.trace_strategy"        = string   // "deterministic" or "attribute"
 
-// Establish-level
+// Establish-level — IMPLEMENTED
 "xrpl.consensus.converge_percent"      = int64    // Convergence % (0-100+)
 "xrpl.consensus.establish_count"       = int64    // Number of establish iterations
-"xrpl.consensus.disputes_count"        = int64    // Active disputes
-"xrpl.consensus.proposers_agreed"      = int64    // Peers agreeing with us
-"xrpl.consensus.proposers_total"       = int64    // Total peer positions
 "xrpl.consensus.agree_count"           = int64    // Peers that agree (haveConsensus)
 "xrpl.consensus.disagree_count"        = int64    // Peers that disagree
-"xrpl.consensus.threshold_percent"     = int64    // Current threshold (50/65/70/95)
+"xrpl.consensus.threshold_percent"     = int64    // Current threshold (avCT_CONSENSUS_PCT = 75%)
 "xrpl.consensus.result"                = string   // "yes", "no", "moved_on"
+"xrpl.consensus.have_close_time_consensus" = bool // Close time consensus reached
+"xrpl.consensus.close_time_threshold"  = int64    // Close time voting threshold
 
-// Mode change
+// Establish-level — IMPLEMENTED
+"xrpl.consensus.disputes_count"        = int64    // Active disputes (on update_positions)
+"xrpl.consensus.avalanche_threshold"   = int64    // Escalated weight (on update_positions)
+
+// Establish-level — NOT IMPLEMENTED
+// "xrpl.consensus.proposers_agreed"   = int64    // Peers agreeing with us — not set
+// "xrpl.consensus.proposers_total"    = int64    // Total peer positions — not set (not defined)
+
+// Mode change — ALL IMPLEMENTED
 "xrpl.consensus.mode.old"              = string   // Previous mode
 "xrpl.consensus.mode.new"              = string   // New mode
 ```
 
 ### Implementation Notes
 
+- **No macros**: The planned `XRPL_TRACE_CONSENSUS`, `XRPL_TRACE_ADD_EVENT`, and
+  `XRPL_TRACE_SET_ATTR` macros were not implemented. All consensus tracing uses
+  `SpanGuard` factory methods (`span()`, `hashSpan()`, `linkedSpan()`) and direct
+  method calls (`setAttribute()`, `addEvent()`). This avoids macro control-flow
+  issues and is cleaner than the planned approach.
 - **Separation of concerns**: All non-trivial telemetry code extracted to private
   helpers (`startRoundTracing`, `createValidationSpan`, `startEstablishTracing`,
   `updateEstablishTracing`, `endEstablishTracing`). Business logic methods contain
-  only single-line `#ifdef` blocks calling these helpers.
+  single-line calls to these helpers.
 - **Thread safety**: `createValidationSpan()` runs on the jtACCEPT worker thread.
   Instead of accessing `roundSpan_` across threads, a `roundSpanContext_` snapshot
   (lightweight `SpanContext` value type) is captured on the consensus thread in
   `startRoundTracing()` and read by `createValidationSpan()`. The job queue
   provides the happens-before guarantee.
-- **Macro safety**: `XRPL_TRACE_ADD_EVENT` uses `do { } while (0)` to prevent
-  dangling-else issues.
+- **No `#ifdef` guards**: Span members use `std::optional<SpanGuard>` and `SpanContext`
+  which have no-op implementations when telemetry is disabled. No `#ifdef XRPL_ENABLE_TELEMETRY`
+  guards needed around members or includes.
+- **No `getTelemetry()` adaptor method**: `SpanGuard::span()` is a static factory that
+  internally checks telemetry state, so `Consensus.h` doesn't need adaptor access
+  for span creation. Only `RCLConsensus::Adaptor` accesses `app_.getTelemetry()` directly.
 - **Config validation**: `consensus_trace_strategy` is validated to be either
   `"deterministic"` or `"attribute"`, falling back to `"deterministic"` for
   unrecognised values.
@@ -891,6 +903,6 @@ share the same trace_id. P2P propagation adds **span-level** linking:
 ## Prerequisites
 
 - Phase 4a (this task list) — establish phase tracing must be in place
-- `TraceContextPropagator` class (already exists in
+- `TraceContextPropagator` free functions (already exist in
   `include/xrpl/telemetry/TraceContextPropagator.h`)
 - Protobuf `TraceContext` message (already exists, field 1001)

OpenTelemetryPlan/Phase5_IntegrationTest_taskList.md

@@ -178,7 +178,7 @@ Tempo/Prometheus.
 **Verification**:
 
 - [ ] Script completes with all checks passing
-- [ ] Tempo UI shows rippled service with all expected span names
+- [ ] Tempo UI shows xrpld service with all expected span names
 - [ ] Grafana dashboards load and show data
 
 ---

OpenTelemetryPlan/Phase5_taskList.md

@@ -175,7 +175,7 @@
 **What to do**:
 
 - Create `docs/telemetry-runbook.md`:
-  - **Setup**: How to enable telemetry in rippled
+  - **Setup**: How to enable telemetry in xrpld
   - **Configuration**: All config options with descriptions
   - **Collector Deployment**: Docker Compose vs. Kubernetes vs. bare metal
   - **Troubleshooting**: Common issues and resolutions
@@ -199,7 +199,7 @@
 **What to do**:
 
 1. Start full Docker stack (Collector, Tempo, Grafana, Prometheus)
-2. Build rippled with `telemetry=ON`
+2. Build xrpld with `telemetry=ON`
 3. Run in standalone mode with telemetry enabled
 4. Generate RPC traffic and verify traces in Tempo
 5. Verify dashboards populate in Grafana

OpenTelemetryPlan/presentation.md

@@ -1,4 +1,4 @@
-# OpenTelemetry Distributed Tracing for rippled
+# OpenTelemetry Distributed Tracing for xrpld
 
 ---
 
@@ -10,7 +10,7 @@
 
 OpenTelemetry is an open-source, CNCF-backed observability framework for distributed tracing, metrics, and logs.
 
-### Why OpenTelemetry for rippled?
+### Why OpenTelemetry for xrpld?
 
 - **End-to-End Transaction Visibility**: Track transactions from submission → consensus → ledger inclusion
 - **Cross-Node Correlation**: Follow requests across multiple independent nodes using a unique `trace_id`
@@ -59,13 +59,13 @@ flowchart LR
 
 ## Slide 3: Adoption Scope — Traces Only (Current Plan)
 
-OpenTelemetry supports three signal types: **Traces**, **Metrics**, and **Logs**. rippled already captures metrics (StatsD via Beast Insight) and logs (Journal/PerfLog). The question is: how much of OTel do we adopt?
+OpenTelemetry supports three signal types: **Traces**, **Metrics**, and **Logs**. xrpld already captures metrics (StatsD via Beast Insight) and logs (Journal/PerfLog). The question is: how much of OTel do we adopt?
 
 > **Scenario A**: Add distributed tracing. Keep StatsD for metrics and Journal for logs.
 
 ```mermaid
 flowchart LR
-    subgraph rippled["rippled Process"]
+    subgraph xrpld["xrpld Process"]
         direction TB
         OTel["OTel SDK<br/>(Traces)"]
         Insight["Beast Insight<br/>(StatsD Metrics)"]
@@ -80,7 +80,7 @@ flowchart LR
     StatsD --> Graphite["Graphite / Grafana"]
     LogFile --> Loki["Loki (optional)"]
 
-    style rippled fill:#424242,stroke:#212121,color:#fff
+    style xrpld fill:#424242,stroke:#212121,color:#fff
     style OTel fill:#2e7d32,stroke:#1b5e20,color:#fff
     style Insight fill:#1565c0,stroke:#0d47a1,color:#fff
     style Journal fill:#e65100,stroke:#bf360c,color:#fff
@@ -106,7 +106,7 @@ flowchart LR
 
 ```mermaid
 flowchart LR
-    subgraph rippled["rippled Process"]
+    subgraph xrpld["xrpld Process"]
         direction TB
         OTel["OTel SDK<br/>(Traces + Metrics)"]
         Journal["Journal + PerfLog<br/>(Logging)"]
@@ -119,7 +119,7 @@ flowchart LR
     Collector --> Prom["Prometheus<br/>(Metrics)"]
     LogFile --> Loki["Loki (optional)"]
 
-    style rippled fill:#424242,stroke:#212121,color:#fff
+    style xrpld fill:#424242,stroke:#212121,color:#fff
     style OTel fill:#2e7d32,stroke:#1b5e20,color:#fff
     style Journal fill:#e65100,stroke:#bf360c,color:#fff
     style Collector fill:#2e7d32,stroke:#1b5e20,color:#fff
@@ -136,7 +136,7 @@ flowchart LR
 
 ```mermaid
 flowchart LR
-    subgraph rippled["rippled Process"]
+    subgraph xrpld["xrpld Process"]
         OTel["OTel SDK<br/>(Traces + Metrics + Logs)"]
     end
 
@@ -146,7 +146,7 @@ flowchart LR
     Collector --> Prom["Prometheus<br/>(Metrics)"]
     Collector --> Loki["Loki / Elastic<br/>(Logs)"]
 
-    style rippled fill:#424242,stroke:#212121,color:#fff
+    style xrpld fill:#424242,stroke:#212121,color:#fff
     style OTel fill:#2e7d32,stroke:#1b5e20,color:#fff
     style Collector fill:#2e7d32,stroke:#1b5e20,color:#fff
 ```
@@ -177,7 +177,7 @@ flowchart LR
 
 ---
 
-## Slide 5: Comparison with rippled's Existing Solutions
+## Slide 5: Comparison with xrpld's Existing Solutions
 
 ### Current Observability Stack
 
@@ -211,7 +211,7 @@ flowchart LR
 
 ```mermaid
 flowchart TB
-    subgraph rippled["rippled Node"]
+    subgraph xrpld["xrpld Node"]
         subgraph services["Core Services"]
             direction LR
             RPC["RPC Server<br/>(HTTP/WS)"] ~~~ Overlay["Overlay<br/>(P2P Network)"] ~~~ Consensus["Consensus<br/>(RCLConsensus)"]
@@ -227,7 +227,7 @@ flowchart TB
     Collector --> Tempo["Grafana Tempo"]
     Collector --> Elastic["Elastic APM"]
 
-    style rippled fill:#424242,stroke:#212121,color:#fff
+    style xrpld fill:#424242,stroke:#212121,color:#fff
     style services fill:#1565c0,stroke:#0d47a1,color:#fff
     style Telemetry fill:#2e7d32,stroke:#1b5e20,color:#fff
     style Collector fill:#e65100,stroke:#bf360c,color:#fff
@@ -236,9 +236,9 @@ flowchart TB
 **Reading the diagram:**
 
 - **Core Services (blue, top)**: RPC Server, Overlay, and Consensus are the three primary components that generate trace data — they represent the entry points for client requests, peer messages, and consensus rounds respectively.
-- **Telemetry Module (green, middle)**: The OpenTelemetry SDK sits below the core services and receives span data from all three; it acts as a single collection point within the rippled process.
-- **OTel Collector (orange, center)**: An external process that receives spans over OTLP/gRPC from the Telemetry Module; it decouples rippled from backend choices and handles batching, sampling, and routing.
-- **Backends (bottom row)**: Tempo and Elastic APM are interchangeable — the Collector fans out to any combination, so operators can switch backends without modifying rippled code.
+- **Telemetry Module (green, middle)**: The OpenTelemetry SDK sits below the core services and receives span data from all three; it acts as a single collection point within the xrpld process.
+- **OTel Collector (orange, center)**: An external process that receives spans over OTLP/gRPC from the Telemetry Module; it decouples xrpld from backend choices and handles batching, sampling, and routing.
+- **Backends (bottom row)**: Tempo and Elastic APM are interchangeable — the Collector fans out to any combination, so operators can switch backends without modifying xrpld code.
 - **Top-to-bottom flow**: Data flows from instrumented code down through the SDK, out over the network to the Collector, and finally into storage/visualization backends.
 
 ### Context Propagation
@@ -496,7 +496,7 @@ flowchart LR
 
 | Aspect                        | Details                                                                                                                                                                                                  |
 | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Where it runs**             | Inside rippled (SDK-level). Configured via `sampling_ratio` in `rippled.cfg`.                                                                                                                            |
+| **Where it runs**             | Inside xrpld (SDK-level). Configured via `sampling_ratio` in `xrpld.cfg`.                                                                                                                                |
 | **When the decision happens** | At trace creation time — before the first span is even populated.                                                                                                                                        |
 | **How it works**              | `sampling_ratio=0.1` means each trace has a 10% probability of being recorded. Dropped traces incur near-zero overhead (no spans created, no attributes set, no export).                                 |
 | **Propagation**               | Once a trace is sampled, the `trace_flags` field (1 byte in the context header) tells downstream nodes to also sample it. Unsampled traces propagate `trace_flags=0`, so downstream nodes skip them too. |
@@ -504,7 +504,7 @@ flowchart LR
 | **Cons**                      | **Blind** — it doesn't know if the trace will be interesting. A rare error or slow consensus round has only a 10% chance of being captured.                                                              |
 | **Best for**                  | High-volume, steady-state traffic where most traces look similar (e.g., routine RPC requests).                                                                                                           |
 
-**rippled configuration**:
+**xrpld configuration**:
 
 ```ini
 [telemetry]
@@ -538,16 +538,16 @@ flowchart TB
     style E fill:#4a148c,stroke:#2e0d57,color:#fff
 ```
 
-| Aspect                        | Details                                                                                                                                                                                                   |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Where it runs**             | In the **OTel Collector** (external process), not inside rippled. rippled exports 100% of traces; the Collector decides what to keep.                                                                     |
-| **When the decision happens** | After the Collector has received all spans for a trace (waits `decision_wait=10s` for stragglers).                                                                                                        |
-| **How it works**              | Policy rules evaluate the completed trace: keep all errors, keep slow operations above a threshold, keep all consensus rounds, then probabilistically sample the rest at 10%.                             |
-| **Pros**                      | **Never misses important traces**. Errors, slow requests, and consensus anomalies are always captured regardless of probability.                                                                          |
-| **Cons**                      | Higher resource usage — rippled must export 100% of spans to the Collector, which buffers them in memory before deciding. The Collector needs more RAM (configured via `num_traces` and `decision_wait`). |
-| **Best for**                  | Production troubleshooting where you can't afford to miss errors or anomalies.                                                                                                                            |
+| Aspect                        | Details                                                                                                                                                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Where it runs**             | In the **OTel Collector** (external process), not inside xrpld. xrpld exports 100% of traces; the Collector decides what to keep.                                                                       |
+| **When the decision happens** | After the Collector has received all spans for a trace (waits `decision_wait=10s` for stragglers).                                                                                                      |
+| **How it works**              | Policy rules evaluate the completed trace: keep all errors, keep slow operations above a threshold, keep all consensus rounds, then probabilistically sample the rest at 10%.                           |
+| **Pros**                      | **Never misses important traces**. Errors, slow requests, and consensus anomalies are always captured regardless of probability.                                                                        |
+| **Cons**                      | Higher resource usage — xrpld must export 100% of spans to the Collector, which buffers them in memory before deciding. The Collector needs more RAM (configured via `num_traces` and `decision_wait`). |
+| **Best for**                  | Production troubleshooting where you can't afford to miss errors or anomalies.                                                                                                                          |
 
-**Collector configuration** (tail sampling rules for rippled):
+**Collector configuration** (tail sampling rules for xrpld):
 
 ```yaml
 processors:
@@ -576,22 +576,22 @@ processors:
 
 |                               | Head Sampling                            | Tail Sampling                                    |
 | ----------------------------- | ---------------------------------------- | ------------------------------------------------ |
-| **Decision point**            | Trace start (inside rippled)             | Trace end (in OTel Collector)                    |
+| **Decision point**            | Trace start (inside xrpld)               | Trace end (in OTel Collector)                    |
 | **Knows trace content?**      | No (random coin flip)                    | Yes (evaluates completed trace)                  |
-| **Overhead on rippled**       | Lowest (dropped traces = no-op)          | Higher (must export 100% to Collector)           |
+| **Overhead on xrpld**         | Lowest (dropped traces = no-op)          | Higher (must export 100% to Collector)           |
 | **Collector resource usage**  | Low (receives only sampled traces)       | Higher (buffers all traces before deciding)      |
 | **Captures all errors?**      | No (only if trace was randomly selected) | **Yes** (error policy catches them)              |
 | **Captures slow operations?** | No (random)                              | **Yes** (latency policy catches them)            |
-| **Configuration**             | `rippled.cfg`: `sampling_ratio=0.1`      | `otel-collector.yaml`: `tail_sampling` processor |
+| **Configuration**             | `xrpld.cfg`: `sampling_ratio=0.1`        | `otel-collector.yaml`: `tail_sampling` processor |
 | **Best for**                  | High-throughput steady-state             | Troubleshooting & anomaly detection              |
 
-### Recommended Strategy for rippled
+### Recommended Strategy for xrpld
 
 Use **both** in a layered approach:
 
 ```mermaid
 flowchart LR
-    subgraph rippled["rippled (Head Sampling)"]
+    subgraph xrpld["xrpld (Head Sampling)"]
         HS["sampling_ratio=1.0<br/>(export everything)"]
     end
 
@@ -603,14 +603,14 @@ flowchart LR
         ST["Only interesting traces<br/>stored long-term"]
     end
 
-    rippled -->|"100% of spans"| collector -->|"~15-20% kept"| storage
+    xrpld -->|"100% of spans"| collector -->|"~15-20% kept"| storage
 
-    style rippled fill:#424242,stroke:#212121,color:#fff
+    style xrpld fill:#424242,stroke:#212121,color:#fff
     style collector fill:#1565c0,stroke:#0d47a1,color:#fff
     style storage fill:#2e7d32,stroke:#1b5e20,color:#fff
 ```
 
-> **Why this works**: rippled exports everything (no blind drops), the Collector applies intelligent filtering (keep errors/slow/anomalies, sample the rest), and only ~15-20% of traces reach storage. If Collector resource usage becomes a concern, add head sampling at `sampling_ratio=0.5` to halve the export volume while still giving the Collector enough data for good tail-sampling decisions.
+> **Why this works**: xrpld exports everything (no blind drops), the Collector applies intelligent filtering (keep errors/slow/anomalies, sample the rest), and only ~15-20% of traces reach storage. If Collector resource usage becomes a concern, add head sampling at `sampling_ratio=0.5` to halve the export volume while still giving the Collector enough data for good tail-sampling decisions.
 
 ---
 

README.md

@@ -8,11 +8,11 @@ The [XRP Ledger](https://xrpl.org/) is a decentralized cryptographic ledger powe
 
 [XRP](https://xrpl.org/xrp.html) is a public, counterparty-free crypto-asset native to the XRP Ledger, and is designed as a gas token for network services and to bridge different currencies. XRP is traded on the open-market and is available for anyone to access. The XRP Ledger was created in 2012 with a finite supply of 100 billion units of XRP.
 
-## rippled
+## xrpld
 
-The server software that powers the XRP Ledger is called `rippled` and is available in this repository under the permissive [ISC open-source license](LICENSE.md). The `rippled` server software is written primarily in C++ and runs on a variety of platforms. The `rippled` server software can run in several modes depending on its [configuration](https://xrpl.org/rippled-server-modes.html).
+The server software that powers the XRP Ledger is called `xrpld` and is available in this repository under the permissive [ISC open-source license](LICENSE.md). The `xrpld` server software is written primarily in C++ and runs on a variety of platforms. The `xrpld` server software can run in several modes depending on its [configuration](https://xrpl.org/rippled-server-modes.html).
 
-If you are interested in running an **API Server** (including a **Full History Server**), take a look at [Clio](https://github.com/XRPLF/clio). (rippled Reporting Mode has been replaced by Clio.)
+If you are interested in running an **API Server** (including a **Full History Server**), take a look at [Clio](https://github.com/XRPLF/clio). (xrpld Reporting Mode has been replaced by Clio.)
 
 ### Build from Source
 
@@ -41,19 +41,19 @@ If you are interested in running an **API Server** (including a **Full History S
 
 Here are some good places to start learning the source code:
 
-- Read the markdown files in the source tree: `src/ripple/**/*.md`.
+- Read the markdown files in the source tree: `src/xrpld/**/*.md`.
 - Read [the levelization document](.github/scripts/levelization) to get an idea of the internal dependency graph.
 - In the big picture, the `main` function constructs an `ApplicationImp` object, which implements the `Application` virtual interface. Almost every component in the application takes an `Application&` parameter in its constructor, typically named `app` and stored as a member variable `app_`. This allows most components to depend on any other component.
 
 ### Repository Contents
 
-| Folder     | Contents                                         |
-| :--------- | :----------------------------------------------- |
-| `./bin`    | Scripts and data files for Ripple integrators.   |
-| `./Builds` | Platform-specific guides for building `rippled`. |
-| `./docs`   | Source documentation files and doxygen config.   |
-| `./cfg`    | Example configuration files.                     |
-| `./src`    | Source code.                                     |
+| Folder     | Contents                                       |
+| :--------- | :--------------------------------------------- |
+| `./bin`    | Scripts and data files for XRPL developers.    |
+| `./Builds` | Platform-specific guides for building `xrpld`. |
+| `./docs`   | Source documentation files and doxygen config. |
+| `./cfg`    | Example configuration files.                   |
+| `./src`    | Source code.                                   |
 
 Some of the directories under `src` are external repositories included using
 git-subtree. See those directories' README files for more details.

SECURITY.md

@@ -6,7 +6,7 @@ For more details on operating an XRP Ledger server securely, please visit https:
 
 ## Supported Versions
 
-Software constantly evolves. In order to focus resources, we only generally only accept vulnerability reports that affect recent and current versions of the software. We always accept reports for issues present in the **master**, **release** or **develop** branches, and with proposed, [open pull requests](https://github.com/ripple/rippled/pulls).
+Software constantly evolves. In order to focus resources, we generally only accept vulnerability reports that affect recent and current versions of the software. We always accept reports for issues present in the **master**, **release** or **develop** branches, and with proposed, [open pull requests](https://github.com/XRPLF/rippled/pulls).
 
 ## Identifying and Reporting Vulnerabilities
 
@@ -22,117 +22,10 @@ Responsible investigation includes, but isn't limited to, the following:
 - Not targeting physical security measures, or attempting to use social engineering, spam, distributed denial of service (DDOS) attacks, etc.
 - Investigating bugs in a way that makes a reasonable, good faith effort not to be disruptive or harmful to the XRP Ledger and the broader ecosystem.
 
-### Responsible Disclosure
-
-If you discover a vulnerability or potential threat, or if you _think_
-you have, please reach out by dropping an email using the contact
-information below.
-
-Your report should include the following:
-
-- Your contact information (typically, an email address);
-- The description of the vulnerability;
-- The attack scenario (if any);
-- The steps to reproduce the vulnerability;
-- Any other relevant details or artifacts, including code, scripts or patches.
-
-In your email, please describe the issue or potential threat. If possible, include a "repro" (code that can reproduce the issue) or describe the best way to reproduce and replicate the issue. Please make your report as detailed and comprehensive as possible.
-
-For more information on responsible disclosure, please read this [Wikipedia article](https://en.wikipedia.org/wiki/Responsible_disclosure).
-
-## Report Handling Process
-
-Please report the bug directly to us and limit further disclosure. If you want to prove that you knew the bug as of a given time, consider using a cryptographic pre-commitment: hash the content of your report and publish the hash on a medium of your choice (e.g. on Twitter or as a memo in a transaction) as "proof" that you had written the text at a given point in time.
-
-Once we receive a report, we:
-
-1. Assign two people to independently evaluate the report;
-2. Consider their recommendations;
-3. If action is necessary, formulate a plan to address the issue;
-4. Communicate privately with the reporter to explain our plan.
-5. Prepare, test and release a version which fixes the issue; and
-6. Announce the vulnerability publicly.
-
-We will triage and respond to your disclosure within 24 hours. Beyond that, we will work to analyze the issue in more detail, formulate, develop and test a fix.
-
-While we commit to responding with 24 hours of your initial report with our triage assessment, we cannot guarantee a response time for the remaining steps. We will communicate with you throughout this process, letting you know where we are and keeping you updated on the timeframe.
-
 ## Bug Bounty Program
 
-[Ripple](https://ripple.com) is generously sponsoring a bug bounty program for vulnerabilities in [`rippled`](https://github.com/XRPLF/rippled) (and other related projects, like [`xrpl.js`](https://github.com/XRPLF/xrpl.js), [`xrpl-py`](https://github.com/XRPLF/xrpl-py), [`xrpl4j`](https://github.com/XRPLF/xrpl4j)).
+[Ripple](https://ripple.com) is generously sponsoring a bug bounty program for vulnerabilities in [`xrpld`](https://github.com/XRPLF/rippled) (and other related projects, like [`Clio`](https://github.com/XRPLF/clio), [`xrpl.js`](https://github.com/XRPLF/xrpl.js), [`xrpl-py`](https://github.com/XRPLF/xrpl-py), [`xrpl4j`](https://github.com/XRPLF/xrpl4j)).
 
-This program allows us to recognize and reward individuals or groups that identify and report bugs. In summary, in order to qualify for a bounty, the bug must be:
+This program allows us to recognize and reward individuals or groups that identify and report bugs.
 
-1. **In scope**. Only bugs in software under the scope of the program qualify. Currently, that means `rippled`, `xrpl.js`, `xrpl-py`, `xrpl4j`.
-2. **Relevant**. A security issue, posing a danger to user funds, privacy, or the operation of the XRP Ledger.
-3. **Original and previously unknown**. Bugs that are already known and discussed in public do not qualify. Previously reported bugs, even if publicly unknown, are not eligible.
-4. **Specific**. We welcome general security advice or recommendations, but we cannot pay bounties for that.
-5. **Fixable**. There has to be something we can do to permanently fix the problem. Note that bugs in other people’s software may still qualify in some cases. For example, if you find a bug in a library that we use which can compromise the security of software that is in scope and we can get it fixed, you may qualify for a bounty.
-6. **Unused**. If you use the exploit to attack the XRP Ledger, you do not qualify for a bounty. If you report a vulnerability used in an ongoing or past attack and there is specific, concrete evidence that suggests you are the attacker we reserve the right not to pay a bounty.
-
-The amount paid varies dramatically. Vulnerabilities that are harmless on their own, but could form part of a critical exploit will usually receive a bounty. Full-blown exploits can receive much higher bounties. Please don’t hold back partial vulnerabilities while trying to construct a full-blown exploit. We will pay a bounty to anyone who reports a complete chain of vulnerabilities even if they have reported each component of the exploit separately and those vulnerabilities have been fixed in the meantime. However, to qualify for a the full bounty, you must to have been the first to report each of the partial exploits.
-
-### Contacting Us
-
-To report a qualifying bug, please send a detailed report to:
-
-| Email Address | bugs@ripple.com                                     |
-| :-----------: | :-------------------------------------------------- |
-| Short Key ID  | `0xA9F514E0`                                        |
-|  Long Key ID  | `0xD900855AA9F514E0`                                |
-|  Fingerprint  | `B72C 0654 2F2A E250 2763 A268 D900 855A A9F5 14E0` |
-
-The full PGP key for this address, which is also available on several key servers (e.g. on [keyserver.ubuntu.com](https://keyserver.ubuntu.com)), is:
-
-```
------BEGIN PGP PUBLIC KEY BLOCK-----
-mQINBGkSZAQBEACprU199OhgdsOsygNjiQV4msuN3vDOUooehL+NwfsGfW79Tbqq
-Q2u7uQ3NZjW+M2T4nsDwuhkr7pe7xSReR5W8ssaczvtUyxkvbMClilcgZ2OSCAuC
-N9tzJsqOqkwBvXoNXkn//T2jnPz0ZU2wSF+NrEibq5FeuyGdoX3yXXBxq9pW9HzK
-HkQll63QSl6BzVSGRQq+B6lGgaZGLwf3mzmIND9Z5VGLNK2jKynyz9z091whNG/M
-kV+E7/r/bujHk7WIVId07G5/COTXmSr7kFnNEkd2Umw42dkgfiNKvlmJ9M7c1wLK
-KbL9Eb4ADuW6rRc5k4s1e6GT8R4/VPliWbCl9SE32hXH8uTkqVIFZP2eyM5WRRHs
-aKzitkQG9UK9gcb0kdgUkxOvvgPHAe5IuZlcHFzU4y0dBbU1VEFWVpiLU0q+IuNw
-5BRemeHc59YNsngkmAZ+/9zouoShRusZmC8Wzotv75C2qVBcjijPvmjWAUz0Zunm
-Lsr+O71vqHE73pERjD07wuD/ISjiYRYYE/bVrXtXLZijC7qAH4RE3nID+2ojcZyO
-/2jMQvt7un56RsGH4UBHi3aBHi9bUoDGCXKiQY981cEuNaOxpou7Mh3x/ONzzSvk
-sTV6nl1LOZHykN1JyKwaNbTSAiuyoN+7lOBqbV04DNYAHL88PrT21P83aQARAQAB
-tB1SaXBwbGUgTGFicyA8YnVnc0ByaXBwbGUuY29tPokCTgQTAQgAOBYhBLcsBlQv
-KuJQJ2OiaNkAhVqp9RTgBQJpEmQEAhsDBQsJCAcCBhUKCQgLAgQWAgMBAh4BAheA
-AAoJENkAhVqp9RTgBzgP/i7y+aDWl1maig1XMdyb+o0UGusumFSW4Hmj278wlKVv
-usgLPihYgHE0PKrv6WRyKOMC1tQEcYYN93M+OeQ1vFhS2YyURq6RCMmh4zq/awXG
-uZbG36OURB5NH8lGBOHiN/7O+nY0CgenBT2JWm+GW3nEOAVOVm4+r5GlpPlv+Dp1
-NPBThcKXFMnH73++NpSQoDzTfRYHPxhDAX3jkLi/moXfSanOLlR6l94XNNN0jBHW
-Quao0rzf4WSXq9g6AS224xhAA5JyIcFl8TX7hzj5HaFn3VWo3COoDu4U7H+BM0fl
-85yqiMQypp7EhN2gxpMMWaHY5TFM85U/bFXFYfEgihZ4/gt4uoIzsNI9jlX7mYvG
-KFdDij+oTlRsuOxdIy60B3dKcwOH9nZZCz0SPsN/zlRWgKzK4gDKdGhFkU9OlvPu
-94ZqscanoiWKDoZkF96+sjgfjkuHsDK7Lwc1Xi+T4drHG/3aVpkYabXox+lrKB/S
-yxZjeqOIQzWPhnLgCaLyvsKo5hxKzL0w3eURu8F3IS7RgOOlljv4M+Me9sEVcdNV
-aN3/tQwbaomSX1X5D5YXqhBwC3rU3wXwamsscRTGEpkV+JCX6KUqGP7nWmxCpAly
-FL05XuOd5SVHJjXLeuje0JqLUpN514uL+bThWwDbDTdAdwW3oK/2WbXz7IfJRLBj
-uQINBGkSZAQBEADdI3SL2F72qkrgFqXWE6HSRBu9bsAvTE5QrRPWk7ux6at537r4
-S4sIw2dOwLvbyIrDgKNq3LQ5wCK88NO/NeCOFm4AiCJSl3pJHXYnTDoUxTrrxx+o
-vSRI4I3fHEql/MqzgiAb0YUezjgFdh3vYheMPp/309PFbOLhiFqEcx80Mx5h06UH
-gDzu1qNj3Ec+31NLic5zwkrAkvFvD54d6bqYR3SEgMau6aYEewpGHbWBi2pLqSi2
-lQcAeOFixqGpTwDmAnYR8YtjBYepy0MojEAdTHcQQlOYSDk4q4elG+io2N8vECfU
-rD6ORecN48GXdZINYWTAdslrUeanmBdgQrYkSpce8TSghgT9P01SNaXxmyaehVUO
-lqI4pcg5G2oojAE8ncNS3TwDtt7daTaTC3bAdr4PXDVAzNAiewjMNZPB7xidkDGQ
-Y4W1LxTMXyJVWxehYOH7tsbBRKninlfRnLgYzmtIbNRAAvNcsxU6ihv3AV0WFknN
-YbSzotEv1Xq/5wk309x8zCDe+sP0cQicvbXafXmUzPAZzeqFg+VLFn7F9MP1WGlW
-B1u7VIvBF1Mp9Nd3EAGBAoLRdRu+0dVWIjPTQuPIuD9cCatJA0wVaKUrjYbBMl88
-a12LixNVGeSFS9N7ADHx0/o7GNT6l88YbaLP6zggUHpUD/bR+cDN7vllIQARAQAB
-iQI2BBgBCAAgFiEEtywGVC8q4lAnY6Jo2QCFWqn1FOAFAmkSZAQCGwwACgkQ2QCF
-Wqn1FOAfAA/8CYq4p0p4bobY20CKEMsZrkBTFJyPDqzFwMeTjgpzqbD7Y3Qq5QCK
-OBbvY02GWdiIsNOzKdBxiuam2xYP9WHZj4y7/uWEvT0qlPVmDFu+HXjoJ43oxwFd
-CUp2gMuQ4cSL3X94VRJ3BkVL+tgBm8CNY0vnTLLOO3kum/R69VsGJS1JSGUWjNM+
-4qwS3mz+73xJu1HmERyN2RZF/DGIZI2PyONQQ6aH85G1Dd2ohu2/DBAkQAMBrPbj
-FrbDaBLyFhODxU3kTWqnfLlaElSm2EGdIU2yx7n4BggEa//NZRMm5kyeo4vzhtlQ
-YIVUMLAOLZvnEqDnsLKp+22FzNR/O+htBQC4lPywl53oYSALdhz1IQlcAC1ru5KR
-XPzhIXV6IIzkcx9xNkEclZxmsuy5ERXyKEmLbIHAlzFmnrldlt2ZgXDtzaorLmxj
-klKibxd5tF50qOpOivz+oPtFo7n+HmFa1nlVAMxlDCUdM0pEVeYDKI5zfVwalyhZ
-NnjpakdZSXMwgc7NP/hH9buF35hKDp7EckT2y3JNYwHsDdy1icXN2q40XZw5tSIn
-zkPWdu3OUY8PISohN6Pw4h0RH4ZmoX97E8sEfmdKaT58U4Hf2aAv5r9IWCSrAVqY
-u5jvac29CzQR9Kal0A+8phHAXHNFD83SwzIC0syaT9ficAguwGH8X6Q=
-=nGuD
------END PGP PUBLIC KEY BLOCK-----
-```
+We have partnered with Bugcrowd to manage this program. It is a private program, and security researchers can participate based on invitation. If you need access to the program, please email bugs@ripple.com with your Bugcrowd handle or Bugcrowd registered email, and we will get you added to the program. Once you have been added, please submit vulnerability reports through Bugcrowd, not by email. The detailed bug bounty policy is available on the Bugcrowd website.

bin/git/setup-upstreams.sh

@@ -1,14 +1,13 @@
 #!/bin/bash
 
-if [[ $# -ne 1 || "$1" == "--help" || "$1" == "-h" ]]
-then
-  name=$( basename $0 )
-  cat <<- USAGE
-  Usage: $name <username>
+if [[ $# -ne 1 || "$1" == "--help" || "$1" == "-h" ]]; then
+    name=$( basename $0 )
+    cat <<- USAGE
+    Usage: $name <username>
 
-  Where <username> is the Github username of the upstream repo. e.g. XRPLF
+    Where <username> is the Github username of the upstream repo. e.g. XRPLF
 USAGE
-  exit 0
+    exit 0
 fi
 
 # Create upstream remotes based on origin
@@ -16,10 +15,9 @@ shift
 user="$1"
 # Get the origin URL. Expect it be an SSH-style URL
 origin=$( git remote get-url origin )
-if [[ "${origin}" == "" ]]
-then
-  echo Invalid origin remote >&2
-  exit 1
+if [[ "${origin}" == "" ]]; then
+    echo Invalid origin remote >&2
+    exit 1
 fi
 # echo "Origin: ${origin}"
 # Parse the origin
@@ -30,11 +28,9 @@ IFS='@' read sshuser server <<< "${remote}"
 # echo "SSHUser: ${sshuser}, Server: ${server}"
 IFS='/' read originuser repo <<< "${originpath}"
 # echo "Originuser: ${originuser}, Repo: ${repo}"
-if [[ "${sshuser}" == "" || "${server}" == "" || "${originuser}" == ""
-  || "${repo}" == "" ]]
-then
-  echo "Can't parse origin URL: ${origin}" >&2
-  exit 1
+if [[ "${sshuser}" == "" || "${server}" == "" || "${originuser}" == "" || "${repo}" == "" ]]; then
+    echo "Can't parse origin URL: ${origin}" >&2
+    exit 1
 fi
 upstream="https://${server}/${user}/${repo}"
 upstreampush="${remote}:${user}/${repo}"
@@ -42,42 +38,34 @@ upstreamgroup="upstream upstream-push"
 current=$( git remote get-url upstream 2>/dev/null )
 currentpush=$( git remote get-url upstream-push 2>/dev/null )
 currentgroup=$( git config remotes.upstreams )
-if [[ "${current}" == "${upstream}" ]]
-then
-  echo "Upstream already set up correctly. Skip"
-elif [[ -n "${current}" && "${current}" != "${upstream}" &&
-  "${current}" != "${upstreampush}" ]]
-then
-  echo "Upstream already set up as: ${current}. Skip"
+if [[ "${current}" == "${upstream}" ]]; then
+    echo "Upstream already set up correctly. Skip"
+elif [[ -n "${current}" && "${current}" != "${upstream}" && "${current}" != "${upstreampush}" ]]; then
+    echo "Upstream already set up as: ${current}. Skip"
 else
-  if [[ "${current}" == "${upstreampush}" ]]
-  then
-    echo "Upstream set to dangerous push URL. Update."
-    _run git remote rename upstream upstream-push || \
-    _run git remote remove upstream
-    currentpush=$( git remote get-url upstream-push 2>/dev/null )
-  fi
-  _run git remote add upstream "${upstream}"
+    if [[ "${current}" == "${upstreampush}" ]]; then
+        echo "Upstream set to dangerous push URL. Update."
+        _run git remote rename upstream upstream-push || \
+        _run git remote remove upstream
+        currentpush=$( git remote get-url upstream-push 2>/dev/null )
+    fi
+    _run git remote add upstream "${upstream}"
 fi
 
-if [[ "${currentpush}" == "${upstreampush}" ]]
-then
-  echo "upstream-push already set up correctly. Skip"
-elif [[ -n "${currentpush}" && "${currentpush}" != "${upstreampush}" ]]
-then
-  echo "upstream-push already set up as: ${currentpush}. Skip"
+if [[ "${currentpush}" == "${upstreampush}" ]]; then
+    echo "upstream-push already set up correctly. Skip"
+elif [[ -n "${currentpush}" && "${currentpush}" != "${upstreampush}" ]]; then
+    echo "upstream-push already set up as: ${currentpush}. Skip"
 else
-  _run git remote add upstream-push "${upstreampush}"
+    _run git remote add upstream-push "${upstreampush}"
 fi
 
-if [[ "${currentgroup}" == "${upstreamgroup}" ]]
-then
-  echo "Upstreams group already set up correctly. Skip"
-elif [[ -n "${currentgroup}" && "${currentgroup}" != "${upstreamgroup}" ]]
-then
-  echo "Upstreams group already set up as: ${currentgroup}. Skip"
+if [[ "${currentgroup}" == "${upstreamgroup}" ]]; then
+    echo "Upstreams group already set up correctly. Skip"
+elif [[ -n "${currentgroup}" && "${currentgroup}" != "${upstreamgroup}" ]]; then
+    echo "Upstreams group already set up as: ${currentgroup}. Skip"
 else
-  _run git config --add remotes.upstreams "${upstreamgroup}"
+    _run git config --add remotes.upstreams "${upstreamgroup}"
 fi
 
 _run git fetch --jobs=$(nproc) upstreams

bin/git/squash-branches.sh

@@ -1,17 +1,16 @@
 #!/bin/bash
 
-if [[ $# -lt 3 || "$1" == "--help" || "$1" = "-h" ]]
-then
-  name=$( basename $0 )
-  cat <<- USAGE
-  Usage: $name workbranch base/branch user/branch [user/branch [...]]
+if [[ $# -lt 3 || "$1" == "--help" || "$1" = "-h" ]]; then
+    name=$( basename $0 )
+    cat <<- USAGE
+    Usage: $name workbranch base/branch user/branch [user/branch [...]]
 
-  * workbranch will be created locally from base/branch
-  * base/branch and user/branch may be specified as user:branch to allow
-    easy copying from Github PRs
-  * Remotes for each user must already be set up
+    * workbranch will be created locally from base/branch
+    * base/branch and user/branch may be specified as user:branch to allow
+        easy copying from Github PRs
+    * Remotes for each user must already be set up
 USAGE
-exit 0
+    exit 0
 fi
 
 work="$1"
@@ -24,9 +23,8 @@ unset branches[0]
 set -e
 
 users=()
-for b in "${branches[@]}"
-do
-  users+=( $( echo $b | cut -d/ -f1 ) )
+for b in "${branches[@]}"; do
+    users+=( $( echo $b | cut -d/ -f1 ) )
 done
 
 users=( $( printf '%s\n' "${users[@]}" | sort -u ) )
@@ -34,10 +32,9 @@ users=( $( printf '%s\n' "${users[@]}" | sort -u ) )
 git fetch --multiple upstreams "${users[@]}"
 git checkout -B "$work" --no-track "$base"
 
-for b in "${branches[@]}"
-do
-  git merge --squash "${b}"
-  git commit -S # Use the commit message provided on the PR
+for b in "${branches[@]}"; do
+    git merge --squash "${b}"
+    git commit -S # Use the commit message provided on the PR
 done
 
 # Make sure the commits look right
@@ -47,13 +44,11 @@ parts=( $( echo $base | sed "s/\// /" ) )
 repo="${parts[0]}"
 b="${parts[1]}"
 push=$repo
-if [[ "$push" == "upstream" ]]
-then
-  push="upstream-push"
+if [[ "$push" == "upstream" ]]; then
+    push="upstream-push"
 fi
-if [[ "$repo" == "upstream" ]]
-then
-  repo="upstreams"
+if [[ "$repo" == "upstream" ]]; then
+    repo="upstreams"
 fi
 cat << PUSH
 

bin/git/update-version.sh

@@ -1,17 +1,16 @@
 #!/bin/bash
 
-if [[ $# -ne 3 || "$1" == "--help" || "$1" = "-h" ]]
-then
-  name=$( basename $0 )
-  cat <<- USAGE
-  Usage: $name workbranch base/branch version
+if [[ $# -ne 3 || "$1" == "--help" || "$1" = "-h" ]]; then
+    name=$( basename $0 )
+    cat <<- USAGE
+    Usage: $name workbranch base/branch version
 
-  * workbranch will be created locally from base/branch. If it exists,
-    it will be reused, so make sure you don't overwrite any work.
-  * base/branch may be specified as user:branch to allow easy copying
-    from Github PRs.
+    * workbranch will be created locally from base/branch. If it exists,
+        it will be reused, so make sure you don't overwrite any work.
+    * base/branch may be specified as user:branch to allow easy copying
+        from Github PRs.
 USAGE
-exit 0
+    exit 0
 fi
 
 work="$1"
@@ -30,10 +29,9 @@ git fetch upstreams
 git checkout -B "${work}" --no-track "${base}"
 
 push=$( git rev-parse --abbrev-ref --symbolic-full-name '@{push}' \
-              2>/dev/null ) || true
-if [[ "${push}" != "" ]]
-then
-  echo "Warning: ${push} may already exist."
+    2>/dev/null ) || true
+if [[ "${push}" != "" ]]; then
+    echo "Warning: ${push} may already exist."
 fi
 
 build=$( find -name BuildInfo.cpp )

bin/pre-commit/clang_tidy_check.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Pre-commit hook that runs clang-tidy on changed files using run-clang-tidy."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+HEADER_EXTENSIONS = {".h", ".hpp", ".ipp"}
+SOURCE_EXTENSIONS = {".cpp"}
+INCLUDE_RE = re.compile(r"^\s*#\s*include\s*[<\"]([^>\"]+)[>\"]")
+
+
+def find_run_clang_tidy() -> str | None:
+    for candidate in ("run-clang-tidy-21", "run-clang-tidy"):
+        if path := shutil.which(candidate):
+            return path
+    return None
+
+
+def find_build_dir(repo_root: Path) -> Path | None:
+    for name in (".build", "build"):
+        candidate = repo_root / name
+        if (candidate / "compile_commands.json").exists():
+            return candidate
+    return None
+
+
+def build_include_graph(build_dir: Path, repo_root: Path) -> tuple[dict, set]:
+    """
+    Scan all files reachable from compile_commands.json and build an inverted include graph.
+
+    Returns:
+        inverted: header_path -> set of files that include it
+        source_files: set of all TU paths from compile_commands.json
+    """
+    with open(build_dir / "compile_commands.json") as f:
+        db = json.load(f)
+
+    source_files = {Path(e["file"]).resolve() for e in db}
+    include_roots = [repo_root / "include", repo_root / "src"]
+    inverted: dict[Path, set[Path]] = defaultdict(set)
+
+    to_scan: set[Path] = set(source_files)
+    scanned: set[Path] = set()
+
+    while to_scan:
+        file = to_scan.pop()
+        if file in scanned or not file.exists():
+            continue
+        scanned.add(file)
+
+        content = file.read_text()
+
+        for line in content.splitlines():
+            m = INCLUDE_RE.match(line)
+            if not m:
+                continue
+            for root in include_roots:
+                candidate = (root / m.group(1)).resolve()
+                if candidate.exists():
+                    inverted[candidate].add(file)
+                    if candidate not in scanned:
+                        to_scan.add(candidate)
+                    break
+
+    return inverted, source_files
+
+
+def find_tus_for_headers(
+    headers: list[Path],
+    inverted: dict[Path, set[Path]],
+    source_files: set[Path],
+) -> set[Path]:
+    """
+    For each header, pick one TU that transitively includes it.
+    Prefers a TU whose stem matches the header's stem, otherwise picks the first found.
+    """
+    result: set[Path] = set()
+
+    for header in headers:
+        preferred: Path | None = None
+        visited: set[Path] = {header}
+        stack: list[Path] = [header]
+
+        while stack:
+            h = stack.pop()
+            for inc in inverted.get(h, ()):
+                if inc in source_files:
+                    if inc.stem == header.stem:
+                        preferred = inc
+                        break
+                    if preferred is None:
+                        preferred = inc
+                if inc not in visited:
+                    visited.add(inc)
+                    stack.append(inc)
+            if preferred is not None and preferred.stem == header.stem:
+                break
+
+        if preferred is not None:
+            result.add(preferred)
+
+    return result
+
+
+def resolve_files(
+    input_files: list[str], build_dir: Path, repo_root: Path
+) -> list[str]:
+    """
+    Split input into source files and headers. Source files are passed through;
+    headers are resolved to the TUs that transitively include them.
+    """
+    sources: list[Path] = []
+    headers: list[Path] = []
+
+    for f in input_files:
+        p = Path(f).resolve()
+        if p.suffix in SOURCE_EXTENSIONS:
+            sources.append(p)
+        elif p.suffix in HEADER_EXTENSIONS:
+            headers.append(p)
+
+    if not headers:
+        return [str(p) for p in sources]
+
+    print(
+        f"Resolving {len(headers)} header(s) to compilation units...", file=sys.stderr
+    )
+    inverted, source_files = build_include_graph(build_dir, repo_root)
+    tus = find_tus_for_headers(headers, inverted, source_files)
+
+    if not tus:
+        print(
+            "Warning: no compilation units found that include the modified headers; "
+            "skipping clang-tidy for headers.",
+            file=sys.stderr,
+        )
+
+    return sorted({str(p) for p in (*sources, *tus)})
+
+
+def staged_files(repo_root: Path) -> list[str]:
+    result = subprocess.run(
+        ["git", "diff", "--staged", "--name-only", "--diff-filter=d"],
+        capture_output=True,
+        text=True,
+        cwd=repo_root,
+    )
+    if result.returncode != 0:
+        print(
+            "clang-tidy check failed: 'git diff --staged' command failed.",
+            file=sys.stderr,
+        )
+        if result.stderr:
+            print(result.stderr, file=sys.stderr)
+        sys.exit(result.returncode or 1)
+    return [str(repo_root / p) for p in result.stdout.splitlines() if p]
+
+
+def main():
+    if not os.environ.get("TIDY"):
+        return 0
+
+    repo_root = Path(__file__).parent.parent
+    files = staged_files(repo_root)
+    if not files:
+        return 0
+
+    run_clang_tidy = find_run_clang_tidy()
+    if not run_clang_tidy:
+        print(
+            "clang-tidy check failed: TIDY is enabled but neither "
+            "'run-clang-tidy-21' nor 'run-clang-tidy' was found in PATH.",
+            file=sys.stderr,
+        )
+        return 1
+
+    build_dir = find_build_dir(repo_root)
+    if not build_dir:
+        print(
+            "clang-tidy check failed: no build directory with compile_commands.json found "
+            "(looked for .build/ and build/)",
+            file=sys.stderr,
+        )
+        return 1
+
+    tidy_files = resolve_files(files, build_dir, repo_root)
+    if not tidy_files:
+        return 0
+
+    result = subprocess.run(
+        [run_clang_tidy, "-quiet", "-p", str(build_dir), "-fix", "-allow-no-checks"]
+        + tidy_files
+    )
+    return result.returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bin/pre-commit/fix_include_style.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+
+"""
+Converts quoted includes (#include "...") to angle-bracket includes
+(#include <...>), which is the required style in this project.
+
+Usage: ./bin/pre-commit/fix_include_style.py <file1> <file2> ...
+"""
+
+import re
+import sys
+from pathlib import Path
+
+PATTERN = re.compile(r'^(\s*#include\s*)"([^"]+)"', re.MULTILINE)
+
+
+def fix_includes(path: Path) -> bool:
+    original = path.read_text(encoding="utf-8")
+    fixed = PATTERN.sub(r"\1<\2>", original)
+    if fixed != original:
+        path.write_text(fixed, encoding="utf-8")
+        return False
+    return True
+
+
+def main() -> int:
+    files = [Path(f) for f in sys.argv[1:]]
+    success = True
+
+    for path in files:
+        success &= fix_includes(path)
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cfg/validators-example.txt

@@ -28,7 +28,7 @@
 #    https://vl.ripple.com
 #    https://unl.xrplf.org
 #    http://127.0.0.1:8000
-#    file:///etc/opt/ripple/vl.txt
+#    file:///etc/opt/xrpld/vl.txt
 #
 # [validator_list_keys]
 #
@@ -43,11 +43,11 @@
 #    ED307A760EE34F2D0CAA103377B1969117C38B8AA0AA1E2A24DAC1F32FC97087ED
 #
 
-# The default validator list publishers that the rippled instance
+# The default validator list publishers that the xrpld instance
 # trusts.
 #
-# WARNING: Changing these values can cause your rippled instance to see a
-#          validated ledger that contradicts other rippled instances'
+# WARNING: Changing these values can cause your xrpld instance to see a
+#          validated ledger that contradicts other xrpld instances'
 #          validated ledgers (aka a ledger fork) if your validator list(s)
 #          do not sufficiently overlap with the list(s) used by others.
 #          See: https://arxiv.org/pdf/1802.07242.pdf

cfg/xrpld-example.cfg

@@ -9,7 +9,7 @@
 #
 #   2. Peer Protocol
 #
-#   3. Ripple Protocol
+#   3. XRPL protocol
 #
 #   4. HTTPS Client
 #
@@ -383,7 +383,7 @@
 #
 #   These settings control security and access attributes of the Peer to Peer
 #   server section of the xrpld process. Peer Protocol implements the
-#   Ripple Payment protocol. It is over peer connections that transactions
+#   XRPL payment protocol. It is over peer connections that transactions
 #   and validations are passed from to machine to machine, to determine the
 #   contents of validated ledgers.
 #
@@ -406,7 +406,7 @@
 #
 # [ips]
 #
-#   List of hostnames or ips where the Ripple protocol is served.  A default
+#   List of hostnames or ips where the XRPL protocol is served.  A default
 #   starter list is included in the code and used if no other hostnames are
 #   available.
 #
@@ -435,7 +435,7 @@
 #   List of IP addresses or hostnames to which xrpld should always attempt to
 #   maintain peer connections with. This is useful for manually forming private
 #   networks, for example to configure a validation server that connects to the
-#   Ripple network through a public-facing server, or for building a set
+#   XRPL network through a public-facing server, or for building a set
 #   of cluster peers.
 #
 #   One address or domain names per line is allowed. A port must be specified
@@ -748,8 +748,8 @@
 #   the folder in which the xrpld.cfg file is located.
 #
 #   Examples:
-#    /home/ripple/validators.txt
-#    C:/home/ripple/validators.txt
+#    /home/username/validators.txt
+#    C:/home/username/validators.txt
 #
 #   Example content:
 #    [validators]
@@ -840,7 +840,7 @@
 #
 #   0: Disable the ledger replay feature [default]
 #   1: Enable the ledger replay feature. With this feature enabled, when
-#      acquiring a ledger from the network, a xrpld node only downloads
+#      acquiring a ledger from the network, an xrpld node only downloads
 #      the ledger header and the transactions instead of the whole ledger.
 #      And the ledger is built by applying the transactions to the parent
 #      ledger.
@@ -853,7 +853,7 @@
 #
 #   The xrpld server instance uses HTTPS GET requests in a variety of
 #   circumstances, including but not limited to contacting trusted domains to
-#   fetch information such as mapping an email address to a Ripple Payment
+#   fetch information such as mapping an email address to an XRPL payment
 #   Network address.
 #
 # [ssl_verify]
@@ -1227,7 +1227,7 @@
 #
 #----------
 #
-#   The vote settings configure settings for the entire Ripple network.
+#   The vote settings configure settings for the entire XRPL network.
 #   While a single instance of xrpld cannot unilaterally enforce network-wide
 #   settings, these choices become part of the instance's vote during the
 #   consensus process for each voting ledger.
@@ -1416,6 +1416,12 @@
 #       in this section to a comma-separated list of the addresses
 #       of your Clio servers, in order to bypass xrpld's rate limiting.
 #
+#       TLS/SSL can be enabled for gRPC by specifying ssl_cert and ssl_key.
+#       Both parameters must be provided together. The ssl_cert_chain parameter
+#       is optional and provides intermediate CA certificates for the certificate
+#       chain. The ssl_client_ca parameter is optional and enables mutual TLS
+#       (client certificate verification).
+#
 #   This port is commented out but can be enabled by removing
 #   the '#' from each corresponding line including the entry under [server]
 #
@@ -1465,11 +1471,74 @@ admin = 127.0.0.1
 protocol = ws
 send_queue_limit = 500
 
+# gRPC TLS/SSL Configuration
+#
+#   The gRPC port supports optional TLS/SSL encryption. When TLS is not
+#   configured, the gRPC server will accept unencrypted connections.
+#
+#   ssl_cert = <filename>
+#   ssl_key = <filename>
+#
+#       To enable TLS for gRPC, both ssl_cert and ssl_key must be specified.
+#       If only one is provided, xrpld will fail to start.
+#
+#       ssl_cert: Path to the server's SSL certificate file in PEM format.
+#       ssl_key:  Path to the server's SSL private key file in PEM format.
+#
+#       When configured, the gRPC server will only accept TLS-encrypted
+#       connections. Clients must use TLS (secure) channel credentials rather
+#       than plaintext / insecure connections.
+#
+#   ssl_cert_chain = <filename>
+#
+#       Optional. Path to intermediate CA certificate(s) in PEM format that
+#       complete the server's certificate chain.
+#
+#       This file should contain the intermediate CA certificate(s) needed
+#       to build a trust chain from the server certificate (ssl_cert) to a
+#       root CA that clients trust. Multiple certificates should be
+#       concatenated in PEM format.
+#
+#       This is needed when your server certificate was signed by an
+#       intermediate CA rather than directly by a root CA. Without this,
+#       clients may fail to verify your server certificate.
+#
+#       If not specified, only the server certificate from ssl_cert will be
+#       presented to clients.
+#
+#   ssl_client_ca = <filename>
+#
+#       Optional. Path to a CA certificate file in PEM format for verifying
+#       client certificates (mutual TLS / mTLS).
+#
+#       When specified, the gRPC server will verify client certificates
+#       against this CA. This enables mutual authentication where both the
+#       server and client verify each other's identity.
+#
+#       This is typically NOT needed for public-facing gRPC servers. Only
+#       use this if you want to restrict access to clients with valid
+#       certificates signed by the specified CA.
+#
+#       If not specified, the server will use one-way TLS (server
+#       authentication only) and will accept connections from any client.
+#
 [port_grpc]
 port = 50051
 ip = 127.0.0.1
 secure_gateway = 127.0.0.1
 
+# Optional TLS/SSL configuration for gRPC
+# To enable TLS, uncomment and configure both ssl_cert and ssl_key:
+#ssl_cert = /etc/ssl/certs/grpc-server.crt
+#ssl_key = /etc/ssl/private/grpc-server.key
+
+# Optional: Include intermediate CA certificates for complete certificate chain
+#ssl_cert_chain = /etc/ssl/certs/grpc-intermediate-ca.crt
+
+# Optional: Enable mutual TLS (client certificate verification)
+# Uncomment to require and verify client certificates:
+#ssl_client_ca = /etc/ssl/certs/grpc-client-ca.crt
+
 #[port_ws_public]
 #port = 6005
 #ip = 127.0.0.1
@@ -1544,31 +1613,82 @@ validators.txt
 #
 #   Enable or disable telemetry at runtime. Default: 0 (disabled).
 #
+# service_name=xrpld
+#
+#   OTel resource attribute `service.name`. Default: xrpld.
+#   The node's network ID (from [network_id]) is automatically added
+#   as the `xrpl.network.id` and `xrpl.network.type` resource attributes.
+#
+# service_instance_id=<node_public_key>
+#
+#   OTel resource attribute `service.instance.id`. Uniquely identifies
+#   this node. Default: the node's public key (auto-detected).
+#
 # endpoint=http://localhost:4318/v1/traces
 #
-#   The OpenTelemetry Collector endpoint (OTLP/HTTP). Default: http://localhost:4318/v1/traces.
+#   The OTLP/HTTP exporter endpoint. The server sends trace data as
+#   protobuf-encoded HTTP POST requests to this URL.
+#   Default: http://localhost:4318/v1/traces.
 #
-# exporter=otlp_http
+# --- TLS settings for the OTLP exporter connection ---
 #
-#   Exporter type: otlp_http. Default: otlp_http.
+# use_tls=0
+#
+#   Enable TLS for the OTLP/HTTP exporter connection. Default: 0 (off).
+#
+# tls_ca_cert=
+#
+#   Path to a PEM-encoded CA certificate bundle for TLS verification.
+#   Only used when use_tls=1. Default: empty (system CA store).
 #
 # sampling_ratio=1.0
 #
-#   Fraction of traces to sample (0.0 to 1.0). Default: 1.0 (all traces).
+#   Head-based sampling ratio using TraceIdRatioBasedSampler. The decision
+#   to record or drop a trace is made at span creation time, before the
+#   span starts, based on the trace ID. Values in [0.0, 1.0].
+#   1.0 = trace everything, 0.1 = sample ~10% of traces. Default: 1.0.
+#   For tail-based (post-hoc) filtering — where you decide to drop a span
+#   after inspecting its content — use SpanGuard::discard() in code.
 #
 # trace_rpc=1
 #
-#   Enable RPC request tracing. Default: 1.
+#   Enable tracing for JSON-RPC and WebSocket API request handling —
+#   command parsing, execution, and response serialization. Default: 1.
 #
 # trace_transactions=1
 #
-#   Enable transaction lifecycle tracing. Default: 1.
+#   Enable tracing for the transaction lifecycle — submission, validation,
+#   application to ledgers, and final disposition. Default: 1.
 #
 # trace_consensus=1
 #
-#   Enable consensus round tracing. Default: 1.
+#   Enable tracing for the consensus round lifecycle — proposals,
+#   validations, mode changes, and ledger acceptance. Default: 1.
 #
 # trace_peer=0
 #
-#   Enable peer message tracing (high volume). Default: 0.
+#   Enable tracing for peer-to-peer protocol messages — overlay message
+#   send/receive, peer handshakes, and routing. High volume; disabled
+#   by default. Default: 0.
+#
+# trace_ledger=1
+#
+#   Enable tracing for ledger close and accept operations — ledger
+#   building, state hashing, and write-back to the node store. Default: 1.
+#
+# --- Batch processor tuning ---
+#
+# batch_size=512
+#
+#   Maximum number of spans exported in a single batch. Default: 512.
+#
+# batch_delay_ms=5000
+#
+#   Maximum delay (milliseconds) before a partial batch is flushed.
+#   Default: 5000 (5 seconds).
+#
+# max_queue_size=2048
+#
+#   Maximum number of spans queued in memory before drops occur.
+#   Default: 2048.
 #

cmake/XrplCompiler.cmake

@@ -118,7 +118,7 @@ if(MSVC)
             NOMINMAX
             # TODO: Resolve these warnings, don't just silence them
             _SILENCE_ALL_CXX17_DEPRECATION_WARNINGS
-            $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>,$<NOT:$<BOOL:${is_ci}>>>:_CRTDBG_MAP_ALLOC>
+            $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>>:_CRTDBG_MAP_ALLOC>
     )
     target_link_libraries(common INTERFACE -errorreport:none -machine:X64)
 else()

cmake/XrplCore.cmake

@@ -115,24 +115,12 @@ target_link_libraries(
 )
 
 # Level 05
-## Set up code generation for protocol_autogen module
-include(XrplProtocolAutogen)
-# Must call setup_protocol_autogen before add_module so that:
-# 1. Stale generated files are cleared before GLOB runs
-# 2. Output file list is known for custom commands
-setup_protocol_autogen()
-
 add_module(xrpl protocol_autogen)
 target_link_libraries(
     xrpl.libxrpl.protocol_autogen
     PUBLIC xrpl.libxrpl.protocol
 )
 
-# Ensure code generation runs before compiling protocol_autogen
-if(TARGET protocol_autogen_generate)
-    add_dependencies(xrpl.libxrpl.protocol_autogen protocol_autogen_generate)
-endif()
-
 # Level 06
 add_module(xrpl core)
 target_link_libraries(

cmake/XrplProtocolAutogen.cmake

@@ -2,308 +2,145 @@
    Protocol Autogen - Code generation for protocol wrapper classes
 #]===================================================================]
 
-# Options for code generation
-option(
-    XRPL_NO_CODEGEN
-    "Disable code generation (use pre-generated files from repository)"
-    OFF
-)
 set(CODEGEN_VENV_DIR
-    ""
+    "${CMAKE_CURRENT_SOURCE_DIR}/.venv"
     CACHE PATH
-    "Path to Python virtual environment for code generation. If provided, automatic venv setup is skipped."
+    "Path to a Python virtual environment for code generation. A venv will be created here by setup_code_gen and used to run generation scripts."
 )
 
-# Function to set up code generation for protocol_autogen module
-# This runs at configure time to generate C++ wrapper classes from macro files
-function(setup_protocol_autogen)
-    # Directory paths
-    set(MACRO_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include/xrpl/protocol/detail")
-    set(AUTOGEN_HEADER_DIR
-        "${CMAKE_CURRENT_SOURCE_DIR}/include/xrpl/protocol_autogen"
-    )
-    set(AUTOGEN_TEST_DIR
-        "${CMAKE_CURRENT_SOURCE_DIR}/src/tests/libxrpl/protocol_autogen"
-    )
-    set(SCRIPTS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/scripts")
+# Directory paths
+set(MACRO_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include/xrpl/protocol/detail")
+set(AUTOGEN_HEADER_DIR
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/xrpl/protocol_autogen"
+)
+set(AUTOGEN_TEST_DIR
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/tests/libxrpl/protocol_autogen"
+)
+set(SCRIPTS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/cmake/scripts/codegen")
 
-    # Input macro files
-    set(TRANSACTIONS_MACRO "${MACRO_DIR}/transactions.macro")
-    set(LEDGER_ENTRIES_MACRO "${MACRO_DIR}/ledger_entries.macro")
-    set(SFIELDS_MACRO "${MACRO_DIR}/sfields.macro")
+# Input macro files
+set(TRANSACTIONS_MACRO "${MACRO_DIR}/transactions.macro")
+set(LEDGER_ENTRIES_MACRO "${MACRO_DIR}/ledger_entries.macro")
+set(SFIELDS_MACRO "${MACRO_DIR}/sfields.macro")
 
-    # Python scripts and templates
-    set(GENERATE_TX_SCRIPT "${SCRIPTS_DIR}/generate_tx_classes.py")
-    set(GENERATE_LEDGER_SCRIPT "${SCRIPTS_DIR}/generate_ledger_classes.py")
-    set(REQUIREMENTS_FILE "${SCRIPTS_DIR}/requirements.txt")
-    set(MACRO_PARSER_COMMON "${SCRIPTS_DIR}/macro_parser_common.py")
-    set(TX_TEMPLATE "${SCRIPTS_DIR}/templates/Transaction.h.mako")
-    set(TX_TEST_TEMPLATE "${SCRIPTS_DIR}/templates/TransactionTests.cpp.mako")
-    set(LEDGER_TEMPLATE "${SCRIPTS_DIR}/templates/LedgerEntry.h.mako")
-    set(LEDGER_TEST_TEMPLATE
-        "${SCRIPTS_DIR}/templates/LedgerEntryTests.cpp.mako"
+# Python scripts and templates
+set(GENERATE_TX_SCRIPT "${SCRIPTS_DIR}/generate_tx_classes.py")
+set(GENERATE_LEDGER_SCRIPT "${SCRIPTS_DIR}/generate_ledger_classes.py")
+set(REQUIREMENTS_FILE "${SCRIPTS_DIR}/requirements.txt")
+set(MACRO_PARSER_COMMON "${SCRIPTS_DIR}/macro_parser_common.py")
+set(TX_TEMPLATE "${SCRIPTS_DIR}/templates/Transaction.h.mako")
+set(TX_TEST_TEMPLATE "${SCRIPTS_DIR}/templates/TransactionTests.cpp.mako")
+set(LEDGER_TEMPLATE "${SCRIPTS_DIR}/templates/LedgerEntry.h.mako")
+set(LEDGER_TEST_TEMPLATE "${SCRIPTS_DIR}/templates/LedgerEntryTests.cpp.mako")
+set(ALL_INPUT_FILES
+    "${TRANSACTIONS_MACRO}"
+    "${LEDGER_ENTRIES_MACRO}"
+    "${SFIELDS_MACRO}"
+    "${GENERATE_TX_SCRIPT}"
+    "${GENERATE_LEDGER_SCRIPT}"
+    "${REQUIREMENTS_FILE}"
+    "${MACRO_PARSER_COMMON}"
+    "${TX_TEMPLATE}"
+    "${TX_TEST_TEMPLATE}"
+    "${LEDGER_TEMPLATE}"
+    "${LEDGER_TEST_TEMPLATE}"
+)
+
+# Create output directories
+file(MAKE_DIRECTORY "${AUTOGEN_HEADER_DIR}/transactions")
+file(MAKE_DIRECTORY "${AUTOGEN_HEADER_DIR}/ledger_entries")
+file(MAKE_DIRECTORY "${AUTOGEN_TEST_DIR}/ledger_entries")
+file(MAKE_DIRECTORY "${AUTOGEN_TEST_DIR}/transactions")
+
+# Find Python3
+if(NOT Python3_EXECUTABLE)
+    find_package(Python3 COMPONENTS Interpreter QUIET)
+endif()
+
+if(NOT Python3_EXECUTABLE)
+    find_program(Python3_EXECUTABLE NAMES python3 python)
+endif()
+
+if(NOT Python3_EXECUTABLE)
+    message(
+        WARNING
+        "Python3 not found. The 'code_gen' and 'setup_code_gen' targets will not be available."
     )
+    return()
+endif()
 
-    # Check if code generation is disabled
-    if(XRPL_NO_CODEGEN)
+# Warn if pip is configured with a non-default index (may need VPN).
+execute_process(
+    COMMAND ${Python3_EXECUTABLE} -m pip config get global.index-url
+    OUTPUT_VARIABLE PIP_INDEX_URL
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET
+    RESULT_VARIABLE PIP_CONFIG_RESULT
+)
+if(PIP_CONFIG_RESULT EQUAL 0 AND PIP_INDEX_URL)
+    if(
+        NOT PIP_INDEX_URL STREQUAL "https://pypi.org/simple"
+        AND NOT PIP_INDEX_URL STREQUAL "https://pypi.python.org/simple"
+    )
         message(
             WARNING
-            "Protocol autogen: Code generation is disabled (XRPL_NO_CODEGEN=ON). "
-            "Generated files may be out of date."
+            "Private pip index URL detected: ${PIP_INDEX_URL}\n"
+            "You may need to connect to VPN to access this URL."
         )
-        return()
     endif()
+endif()
 
-    # Create output directories
-    file(MAKE_DIRECTORY "${AUTOGEN_HEADER_DIR}/transactions")
-    file(MAKE_DIRECTORY "${AUTOGEN_HEADER_DIR}/ledger_entries")
-    file(MAKE_DIRECTORY "${AUTOGEN_TEST_DIR}/ledger_entries")
-    file(MAKE_DIRECTORY "${AUTOGEN_TEST_DIR}/transactions")
-
-    # Find Python3 - check if already found by Conan or find it ourselves
-    if(NOT Python3_EXECUTABLE)
-        find_package(Python3 COMPONENTS Interpreter QUIET)
-    endif()
-
-    if(NOT Python3_EXECUTABLE)
-        # Try finding python3 executable directly
-        find_program(Python3_EXECUTABLE NAMES python3 python)
-    endif()
-
-    if(NOT Python3_EXECUTABLE)
-        message(
-            FATAL_ERROR
-            "Python3 not found. Code generation cannot proceed.\n"
-            "Please install Python 3, or set -DXRPL_NO_CODEGEN=ON to use existing generated files."
-        )
-        return()
-    endif()
-
-    message(STATUS "Using Python3 for code generation: ${Python3_EXECUTABLE}")
-
-    # Set up Python virtual environment for code generation
-    if(CODEGEN_VENV_DIR)
-        # User-provided venv - skip automatic setup
-        set(VENV_DIR "${CODEGEN_VENV_DIR}")
-        message(STATUS "Using user-provided Python venv: ${VENV_DIR}")
-    else()
-        # Use default venv in build directory
-        set(VENV_DIR "${CMAKE_CURRENT_BINARY_DIR}/codegen_venv")
-    endif()
-
-    # Determine the Python executable path in the venv
+# Determine which Python interpreter to use for code generation.
+if(CODEGEN_VENV_DIR)
     if(WIN32)
-        set(VENV_PYTHON "${VENV_DIR}/Scripts/python.exe")
-        set(VENV_PIP "${VENV_DIR}/Scripts/pip.exe")
+        set(CODEGEN_PYTHON "${CODEGEN_VENV_DIR}/Scripts/python.exe")
     else()
-        set(VENV_PYTHON "${VENV_DIR}/bin/python")
-        set(VENV_PIP "${VENV_DIR}/bin/pip")
+        set(CODEGEN_PYTHON "${CODEGEN_VENV_DIR}/bin/python")
     endif()
-
-    # Only auto-setup venv if not user-provided
-    if(NOT CODEGEN_VENV_DIR)
-        # Check if venv needs to be created or updated
-        set(VENV_NEEDS_UPDATE FALSE)
-        if(NOT EXISTS "${VENV_PYTHON}")
-            set(VENV_NEEDS_UPDATE TRUE)
-            message(
-                STATUS
-                "Creating Python virtual environment for code generation..."
-            )
-        elseif(
-            "${REQUIREMENTS_FILE}"
-                IS_NEWER_THAN
-                "${VENV_DIR}/.requirements_installed"
-        )
-            set(VENV_NEEDS_UPDATE TRUE)
-            message(
-                STATUS
-                "Updating Python virtual environment (requirements changed)..."
-            )
-        endif()
-
-        # Create/update virtual environment if needed
-        if(VENV_NEEDS_UPDATE)
-            message(
-                STATUS
-                "Setting up Python virtual environment at ${VENV_DIR}"
-            )
-            execute_process(
-                COMMAND ${Python3_EXECUTABLE} -m venv "${VENV_DIR}"
-                RESULT_VARIABLE VENV_RESULT
-                ERROR_VARIABLE VENV_ERROR
-            )
-            if(NOT VENV_RESULT EQUAL 0)
-                message(
-                    FATAL_ERROR
-                    "Failed to create virtual environment: ${VENV_ERROR}"
-                )
-            endif()
-
-            # Check pip index URL configuration
-            execute_process(
-                COMMAND ${VENV_PIP} config get global.index-url
-                OUTPUT_VARIABLE PIP_INDEX_URL
-                OUTPUT_STRIP_TRAILING_WHITESPACE
-                ERROR_QUIET
-            )
-
-            # Default PyPI URL
-            set(DEFAULT_PIP_INDEX "https://pypi.org/simple")
-
-            # Show warning if using non-default index
-            if(PIP_INDEX_URL AND NOT PIP_INDEX_URL STREQUAL "")
-                if(NOT PIP_INDEX_URL STREQUAL DEFAULT_PIP_INDEX)
-                    message(
-                        WARNING
-                        "Private pip index URL detected: ${PIP_INDEX_URL}\n"
-                        "You may need to connect to VPN to access this URL."
-                    )
-                endif()
-            endif()
-
-            message(STATUS "Installing Python dependencies...")
-            execute_process(
-                COMMAND ${VENV_PIP} install --upgrade pip
-                RESULT_VARIABLE PIP_UPGRADE_RESULT
-                OUTPUT_QUIET
-                ERROR_VARIABLE PIP_UPGRADE_ERROR
-            )
-            if(NOT PIP_UPGRADE_RESULT EQUAL 0)
-                message(WARNING "Failed to upgrade pip: ${PIP_UPGRADE_ERROR}")
-            endif()
-
-            execute_process(
-                COMMAND ${VENV_PIP} install -r "${REQUIREMENTS_FILE}"
-                RESULT_VARIABLE PIP_INSTALL_RESULT
-                ERROR_VARIABLE PIP_INSTALL_ERROR
-            )
-            if(NOT PIP_INSTALL_RESULT EQUAL 0)
-                message(
-                    FATAL_ERROR
-                    "Failed to install Python dependencies: ${PIP_INSTALL_ERROR}"
-                )
-            endif()
-
-            # Mark requirements as installed
-            file(TOUCH "${VENV_DIR}/.requirements_installed")
-            message(STATUS "Python virtual environment ready")
-        endif()
-    endif()
-
-    # At configure time - get list of output files for transactions
-    execute_process(
-        COMMAND
-            ${VENV_PYTHON} "${GENERATE_TX_SCRIPT}" "${TRANSACTIONS_MACRO}"
-            --header-dir "${AUTOGEN_HEADER_DIR}/transactions" --test-dir
-            "${AUTOGEN_TEST_DIR}/transactions" --list-outputs
-        OUTPUT_VARIABLE TX_OUTPUT_FILES
-        OUTPUT_STRIP_TRAILING_WHITESPACE
-        RESULT_VARIABLE TX_LIST_RESULT
-        ERROR_VARIABLE TX_LIST_ERROR
+else()
+    set(CODEGEN_PYTHON "${Python3_EXECUTABLE}")
+    message(
+        WARNING
+        "CODEGEN_VENV_DIR is not set. Dependencies will be installed globally.\n"
+        "If this is not intended, reconfigure with:\n"
+        "  cmake . -UCODEGEN_VENV_DIR"
     )
-    if(NOT TX_LIST_RESULT EQUAL 0)
-        message(
-            FATAL_ERROR
-            "Failed to list transaction output files:\n${TX_LIST_ERROR}"
-        )
-    endif()
-    # Convert newline-separated list to CMake list
-    string(REPLACE "\\" "/" TX_OUTPUT_FILES "${TX_OUTPUT_FILES}")
-    string(REPLACE "\n" ";" TX_OUTPUT_FILES "${TX_OUTPUT_FILES}")
+endif()
 
-    # At configure time - get list of output files for ledger entries
-    execute_process(
-        COMMAND
-            ${VENV_PYTHON} "${GENERATE_LEDGER_SCRIPT}" "${LEDGER_ENTRIES_MACRO}"
-            --header-dir "${AUTOGEN_HEADER_DIR}/ledger_entries" --test-dir
-            "${AUTOGEN_TEST_DIR}/ledger_entries" --list-outputs
-        OUTPUT_VARIABLE LEDGER_OUTPUT_FILES
-        OUTPUT_STRIP_TRAILING_WHITESPACE
-        RESULT_VARIABLE LEDGER_LIST_RESULT
-        ERROR_VARIABLE LEDGER_LIST_ERROR
-    )
-    if(NOT LEDGER_LIST_RESULT EQUAL 0)
-        message(
-            FATAL_ERROR
-            "Failed to list ledger entry output files:\n${LEDGER_LIST_ERROR}"
-        )
-    endif()
-    # Convert newline-separated list to CMake list
-    string(REPLACE "\\" "/" LEDGER_OUTPUT_FILES "${LEDGER_OUTPUT_FILES}")
-    string(REPLACE "\n" ";" LEDGER_OUTPUT_FILES "${LEDGER_OUTPUT_FILES}")
-
-    # Custom command to generate transaction classes at build time
-    add_custom_command(
-        OUTPUT ${TX_OUTPUT_FILES}
-        COMMAND
-            ${VENV_PYTHON} "${GENERATE_TX_SCRIPT}" "${TRANSACTIONS_MACRO}"
-            --header-dir "${AUTOGEN_HEADER_DIR}/transactions" --test-dir
-            "${AUTOGEN_TEST_DIR}/transactions" --sfields-macro
-            "${SFIELDS_MACRO}"
-        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
-        DEPENDS
-            "${TRANSACTIONS_MACRO}"
-            "${SFIELDS_MACRO}"
-            "${GENERATE_TX_SCRIPT}"
-            "${MACRO_PARSER_COMMON}"
-            "${TX_TEMPLATE}"
-            "${TX_TEST_TEMPLATE}"
-            "${REQUIREMENTS_FILE}"
-        COMMENT "Generating transaction classes from transactions.macro..."
-        VERBATIM
-    )
-
-    # Custom command to generate ledger entry classes at build time
-    add_custom_command(
-        OUTPUT ${LEDGER_OUTPUT_FILES}
-        COMMAND
-            ${VENV_PYTHON} "${GENERATE_LEDGER_SCRIPT}" "${LEDGER_ENTRIES_MACRO}"
-            --header-dir "${AUTOGEN_HEADER_DIR}/ledger_entries" --test-dir
-            "${AUTOGEN_TEST_DIR}/ledger_entries" --sfields-macro
-            "${SFIELDS_MACRO}"
-        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
-        DEPENDS
-            "${LEDGER_ENTRIES_MACRO}"
-            "${SFIELDS_MACRO}"
-            "${GENERATE_LEDGER_SCRIPT}"
-            "${MACRO_PARSER_COMMON}"
-            "${LEDGER_TEMPLATE}"
-            "${LEDGER_TEST_TEMPLATE}"
-            "${REQUIREMENTS_FILE}"
-        COMMENT "Generating ledger entry classes from ledger_entries.macro..."
-        VERBATIM
-    )
-
-    # Create a custom target that depends on all generated files
+# Custom target to create a venv and install Python dependencies.
+# Run manually with: cmake --build . --target setup_code_gen
+if(CODEGEN_VENV_DIR)
     add_custom_target(
-        protocol_autogen_generate
-        DEPENDS ${TX_OUTPUT_FILES} ${LEDGER_OUTPUT_FILES}
-        COMMENT "Protocol autogen code generation"
+        setup_code_gen
+        COMMAND ${Python3_EXECUTABLE} -m venv "${CODEGEN_VENV_DIR}"
+        COMMAND ${CODEGEN_PYTHON} -m pip install -r "${REQUIREMENTS_FILE}"
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+        COMMENT "Creating venv and installing code generation dependencies..."
     )
+else()
+    add_custom_target(
+        setup_code_gen
+        COMMAND ${Python3_EXECUTABLE} -m pip install -r "${REQUIREMENTS_FILE}"
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+        COMMENT "Installing code generation dependencies..."
+    )
+endif()
 
-    # Extract test files from output lists (files ending in Tests.cpp)
-    set(PROTOCOL_AUTOGEN_TEST_SOURCES "")
-    foreach(FILE ${TX_OUTPUT_FILES} ${LEDGER_OUTPUT_FILES})
-        if(FILE MATCHES "Tests\\.cpp$")
-            list(APPEND PROTOCOL_AUTOGEN_TEST_SOURCES "${FILE}")
-        endif()
-    endforeach()
-    # Export test sources to parent scope for use in test CMakeLists.txt
-    set(PROTOCOL_AUTOGEN_TEST_SOURCES
-        "${PROTOCOL_AUTOGEN_TEST_SOURCES}"
-        CACHE INTERNAL
-        "Generated protocol_autogen test sources"
-    )
-
-    # Register dependencies so CMake reconfigures when macro files change
-    # (to update the list of output files)
-    set_property(
-        DIRECTORY
-        APPEND
-        PROPERTY
-            CMAKE_CONFIGURE_DEPENDS
-                "${TRANSACTIONS_MACRO}"
-                "${LEDGER_ENTRIES_MACRO}"
-    )
-endfunction()
+# Custom target for code generation, excluded from ALL.
+# Run manually with: cmake --build . --target code_gen
+add_custom_target(
+    code_gen
+    COMMAND
+        ${CMAKE_COMMAND} -DCODEGEN_PYTHON=${CODEGEN_PYTHON}
+        -DGENERATE_TX_SCRIPT=${GENERATE_TX_SCRIPT}
+        -DGENERATE_LEDGER_SCRIPT=${GENERATE_LEDGER_SCRIPT}
+        -DTRANSACTIONS_MACRO=${TRANSACTIONS_MACRO}
+        -DLEDGER_ENTRIES_MACRO=${LEDGER_ENTRIES_MACRO}
+        -DSFIELDS_MACRO=${SFIELDS_MACRO}
+        -DAUTOGEN_HEADER_DIR=${AUTOGEN_HEADER_DIR}
+        -DAUTOGEN_TEST_DIR=${AUTOGEN_TEST_DIR} -P
+        "${CMAKE_CURRENT_SOURCE_DIR}/cmake/XrplProtocolAutogenRun.cmake"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+    COMMENT "Running protocol code generation..."
+    SOURCES ${ALL_INPUT_FILES}
+)

cmake/XrplProtocolAutogenRun.cmake

@@ -0,0 +1,39 @@
+#[===================================================================[
+   Protocol Autogen - Run script invoked by the 'code_gen' target
+#]===================================================================]
+
+# Generate transaction classes.
+execute_process(
+    COMMAND
+        ${CODEGEN_PYTHON} "${GENERATE_TX_SCRIPT}" "${TRANSACTIONS_MACRO}"
+        --header-dir "${AUTOGEN_HEADER_DIR}/transactions" --test-dir
+        "${AUTOGEN_TEST_DIR}/transactions" --sfields-macro "${SFIELDS_MACRO}"
+    RESULT_VARIABLE TX_RESULT
+    OUTPUT_VARIABLE TX_OUTPUT
+    ERROR_VARIABLE TX_ERROR
+)
+if(NOT TX_RESULT EQUAL 0)
+    message(
+        FATAL_ERROR
+        "Transaction code generation failed:\n${TX_OUTPUT}\n${TX_ERROR}\n${TX_RESULT}"
+    )
+endif()
+
+# Generate ledger entry classes.
+execute_process(
+    COMMAND
+        ${CODEGEN_PYTHON} "${GENERATE_LEDGER_SCRIPT}" "${LEDGER_ENTRIES_MACRO}"
+        --header-dir "${AUTOGEN_HEADER_DIR}/ledger_entries" --test-dir
+        "${AUTOGEN_TEST_DIR}/ledger_entries" --sfields-macro "${SFIELDS_MACRO}"
+    RESULT_VARIABLE LEDGER_RESULT
+    OUTPUT_VARIABLE LEDGER_OUTPUT
+    ERROR_VARIABLE LEDGER_ERROR
+)
+if(NOT LEDGER_RESULT EQUAL 0)
+    message(
+        FATAL_ERROR
+        "Ledger entry code generation failed:\n${LEDGER_OUTPUT}\n${LEDGER_ERROR}\n${TX_RESULT}"
+    )
+endif()
+
+message(STATUS "Protocol autogen: code generation complete")

cmake/scripts/codegen/generate_ledger_classes.py

@@ -138,28 +138,12 @@ def main():
         "--sfields-macro",
         help="Path to sfields.macro (default: auto-detect from macro_path)",
     )
-    parser.add_argument(
-        "--list-outputs",
-        action="store_true",
-        help="List output files without generating (one per line)",
-    )
-
+    parser.add_argument("--venv-dir", help=argparse.SUPPRESS)
     args = parser.parse_args()
 
     # Parse the macro file to get ledger entry names
     entries = parse_macro_file(args.macro_path)
 
-    # If --list-outputs, just print the output file paths and exit
-    if args.list_outputs:
-        header_dir = Path(args.header_dir)
-        for entry in entries:
-            print(header_dir / f"{entry['name']}.h")
-        if args.test_dir:
-            test_dir = Path(args.test_dir)
-            for entry in entries:
-                print(test_dir / f"{entry['name']}Tests.cpp")
-        return
-
     # Auto-detect sfields.macro path if not provided
     if args.sfields_macro:
         sfields_path = Path(args.sfields_macro)

cmake/scripts/codegen/generate_tx_classes.py

@@ -147,28 +147,12 @@ def main():
         "--sfields-macro",
         help="Path to sfields.macro (default: auto-detect from macro_path)",
     )
-    parser.add_argument(
-        "--list-outputs",
-        action="store_true",
-        help="List output files without generating (one per line)",
-    )
-
+    parser.add_argument("--venv-dir", help=argparse.SUPPRESS)
     args = parser.parse_args()
 
     # Parse the macro file to get transaction names
     transactions = parse_macro_file(args.macro_path)
 
-    # If --list-outputs, just print the output file paths and exit
-    if args.list_outputs:
-        header_dir = Path(args.header_dir)
-        for tx in transactions:
-            print(header_dir / f"{tx['name']}.h")
-        if args.test_dir:
-            test_dir = Path(args.test_dir)
-            for tx in transactions:
-                print(test_dir / f"{tx['name']}Tests.cpp")
-        return
-
     # Auto-detect sfields.macro path if not provided
     if args.sfields_macro:
         sfields_path = Path(args.sfields_macro)

conan.lock

@@ -3,16 +3,16 @@
     "requires": [
         "zlib/1.3.1#cac0f6daea041b0ccf42934163defb20%1774439233.809",
         "xxhash/0.8.3#681d36a0a6111fc56e5e45ea182c19cc%1765850149.987",
-        "sqlite3/3.51.0#66aa11eabd0e34954c5c1c061ad44abe%1763899256.358",
+        "sqlite3/3.51.0#66aa11eabd0e34954c5c1c061ad44abe%1774467355.988",
         "soci/4.0.3#fe32b9ad5eb47e79ab9e45a68f363945%1774450067.231",
         "snappy/1.1.10#968fef506ff261592ec30c574d4a7809%1765850147.878",
         "secp256k1/0.7.1#481881709eb0bdd0185a12b912bbe8ad%1770910500.329",
         "rocksdb/10.5.1#4a197eca381a3e5ae8adf8cffa5aacd0%1765850186.86",
         "re2/20251105#8579cfd0bda4daf0683f9e3898f964b4%1774398111.888",
-        "protobuf/6.33.5#d96d52ba5baaaa532f47bda866ad87a5%1773224203.27",
+        "protobuf/6.33.5#d96d52ba5baaaa532f47bda866ad87a5%1774467363.12",
         "opentelemetry-cpp/1.18.0#efd9851e173f8a13b9c7d35232de8cf1%1750409186.472",
         "openssl/3.6.1#e6399de266349245a4542fc5f6c71552%1774458290.139",
-        "nudb/2.0.9#0432758a24204da08fee953ec9ea03cb%1769436073.32",
+        "nudb/2.0.9#11149c73f8f2baff9a0198fe25971fc7%1774883011.384",
         "nlohmann_json/3.11.3#45828be26eb619a2e04ca517bb7b828d%1701220705.259",
         "lz4/1.10.0#59fc63cac7f10fbe8e05c7e62c2f3504%1765850143.914",
         "libiconv/1.17#1e65319e945f2d31941a9d28cc13c058%1765842973.492",
@@ -21,7 +21,7 @@
         "libarchive/3.8.1#ffee18995c706e02bf96e7a2f7042e0d%1765850144.736",
         "jemalloc/5.3.0#e951da9cf599e956cebc117880d2d9f8%1729241615.244",
         "gtest/1.17.0#5224b3b3ff3b4ce1133cbdd27d53ee7d%1768312129.152",
-        "grpc/1.78.1#b1a9e74b145cc471bed4dc64dc6eb2c1%1772623605.068",
+        "grpc/1.78.1#b1a9e74b145cc471bed4dc64dc6eb2c1%1774467387.342",
         "ed25519/2015.03#ae761bdc52730a843f0809bdf6c1b1f6%1765850143.772",
         "date/3.0.4#862e11e80030356b53c2c38599ceb32b%1765850143.772",
         "c-ares/1.34.6#545240bb1c40e2cacd4362d6b8967650%1774439234.681",
@@ -32,7 +32,7 @@
     "build_requires": [
         "zlib/1.3.1#cac0f6daea041b0ccf42934163defb20%1774439233.809",
         "strawberryperl/5.32.1.1#8d114504d172cfea8ea1662d09b6333e%1774447376.964",
-        "protobuf/6.33.5#d96d52ba5baaaa532f47bda866ad87a5%1773224203.27",
+        "protobuf/6.33.5#d96d52ba5baaaa532f47bda866ad87a5%1774467363.12",
         "pkgconf/2.5.1#93c2051284cba1279494a43a4fcfeae2%1757684701.089",
         "opentelemetry-proto/1.4.0#4096a3b05916675ef9628f3ffd571f51%1732731336.11",
         "ninja/1.13.2#c8c5dc2a52ed6e4e42a66d75b4717ceb%1764096931.974",
@@ -50,16 +50,15 @@
     ],
     "python_requires": [],
     "overrides": {
-        "boost/1.90.0#d5e8defe7355494953be18524a7f135b": [
-            null,
-            "boost/1.90.0"
-        ],
         "protobuf/[>=5.27.0 <7]": [
             "protobuf/6.33.5"
         ],
         "lz4/1.9.4": [
             "lz4/1.10.0"
         ],
+        "boost/[>=1.83.0 <1.91.0]": [
+            "boost/1.90.0"
+        ],
         "sqlite3/[>=3.44 <4]": [
             "sqlite3/3.51.0"
         ],

conan/lockfile/regenerate.sh

@@ -23,14 +23,14 @@ rm -f conan.lock
 # first create command will create a new lockfile, while the subsequent create
 # commands will merge any additional dependencies into the created lockfile.
 conan lock create . \
-  --options '&:jemalloc=True' \
-  --options '&:rocksdb=True' \
-  --profile:all=conan/lockfile/linux.profile
+    --options '&:jemalloc=True' \
+    --options '&:rocksdb=True' \
+    --profile:all=conan/lockfile/linux.profile
 conan lock create . \
-  --options '&:jemalloc=True' \
-  --options '&:rocksdb=True' \
-  --profile:all=conan/lockfile/macos.profile
+    --options '&:jemalloc=True' \
+    --options '&:rocksdb=True' \
+    --profile:all=conan/lockfile/macos.profile
 conan lock create . \
-  --options '&:jemalloc=True' \
-  --options '&:rocksdb=True' \
-  --profile:all=conan/lockfile/windows.profile
+    --options '&:jemalloc=True' \
+    --options '&:rocksdb=True' \
+    --profile:all=conan/lockfile/windows.profile

conanfile.py

@@ -55,7 +55,7 @@ class Xrpl(ConanFile):
         "rocksdb": True,
         "shared": False,
         "static": True,
-        "telemetry": True,
+        "telemetry": False,
         "tests": False,
         "unity": False,
         "xrpld": False,

cspell.config.yaml

@@ -44,6 +44,10 @@ suggestWords:
 words:
   - abempty
   - AMMID
+  - AMMMPT
+  - AMMMPToken
+  - AMMMPTokens
+  - AMMXRP
   - amt
   - amts
   - asnode
@@ -98,6 +102,7 @@ words:
   - distro
   - doxyfile
   - dxrpl
+  - enabled
   - endmacro
   - EOCFG
   - exceptioned
@@ -115,6 +120,7 @@ words:
   - gpgcheck
   - gpgkey
   - hotwallet
+  - hicpp
   - hwaddress
   - hwrap
   - ifndef
@@ -151,6 +157,8 @@ words:
   - ltype
   - mcmodel
   - MEMORYSTATUSEX
+  - MPTAMM
+  - MPTDEX
   - Merkle
   - Metafuncton
   - misprediction
@@ -160,6 +168,7 @@ words:
   - mptid
   - mptissuance
   - mptissuanceid
+  - mptissue
   - mptoken
   - mptokenid
   - mptokenissuance
@@ -181,6 +190,7 @@ words:
   - nixfmt
   - nixos
   - nixpkgs
+  - NETOP
   - NOLINT
   - NOLINTNEXTLINE
   - nonxrp
@@ -200,6 +210,7 @@ words:
   - permissioned
   - pgrep
   - pkill
+  - pimpl
   - pointee
   - populator
   - pratik

docker/telemetry/TESTING.md

@@ -1,6 +1,6 @@
 # OpenTelemetry Integration Testing Guide
 
-This document describes how to verify the rippled OpenTelemetry telemetry
+This document describes how to verify the xrpld OpenTelemetry telemetry
 pipeline end-to-end, from span generation through the observability stack
 (otel-collector, Tempo, Prometheus, Grafana).
 
@@ -118,25 +118,25 @@ Wait 5 seconds for the batch export, then:
 ```bash
 TEMPO="http://localhost:3200"
 
-# Check rippled service is registered
+# Check xrpld service is registered
 curl -s "$TEMPO/api/v2/search/tag/resource.service.name/values" | jq '.tagValues[].value'
 
 # Check RPC spans
 curl -s "$TEMPO/api/search" \
-  --data-urlencode 'q={resource.service.name="rippled" && name="rpc.request"}' \
+  --data-urlencode 'q={resource.service.name="xrpld" && name="rpc.request"}' \
   --data-urlencode 'limit=5' | jq '.traces | length'
 
 curl -s "$TEMPO/api/search" \
-  --data-urlencode 'q={resource.service.name="rippled" && name="rpc.process"}' \
+  --data-urlencode 'q={resource.service.name="xrpld" && name="rpc.process"}' \
   --data-urlencode 'limit=5' | jq '.traces | length'
 
 curl -s "$TEMPO/api/search" \
-  --data-urlencode 'q={resource.service.name="rippled" && name="rpc.command.server_info"}' \
+  --data-urlencode 'q={resource.service.name="xrpld" && name="rpc.command.server_info"}' \
   --data-urlencode 'limit=5' | jq '.traces | length'
 
 # Check transaction spans
 curl -s "$TEMPO/api/search" \
-  --data-urlencode 'q={resource.service.name="rippled" && name="tx.process"}' \
+  --data-urlencode 'q={resource.service.name="xrpld" && name="tx.process"}' \
   --data-urlencode 'limit=5' | jq '.traces | length'
 ```
 
@@ -374,21 +374,27 @@ See the "Verification Queries" section below.
 
 ## Expected Span Catalog
 
-All 12 production span names instrumented across Phases 2-4:
+All 16 production span names instrumented across Phases 2-5:
 
-| Span Name                   | Source File           | Phase | Key Attributes                                                                    | How to Trigger            |
-| --------------------------- | --------------------- | ----- | --------------------------------------------------------------------------------- | ------------------------- |
-| `rpc.request`               | ServerHandler.cpp:271 | 2     | --                                                                                | Any HTTP RPC call         |
-| `rpc.process`               | ServerHandler.cpp:573 | 2     | --                                                                                | Any HTTP RPC call         |
-| `rpc.ws_message`            | ServerHandler.cpp:384 | 2     | --                                                                                | WebSocket RPC message     |
-| `rpc.command.<name>`        | RPCHandler.cpp:161    | 2     | `xrpl.rpc.command`, `xrpl.rpc.version`, `xrpl.rpc.role`                           | Any RPC command           |
-| `tx.process`                | NetworkOPs.cpp:1227   | 3     | `xrpl.tx.hash`, `xrpl.tx.local`, `xrpl.tx.path`                                   | Submit transaction        |
-| `tx.receive`                | PeerImp.cpp:1273      | 3     | `xrpl.peer.id`                                                                    | Peer relays transaction   |
-| `consensus.proposal.send`   | RCLConsensus.cpp:177  | 4     | `xrpl.consensus.round`                                                            | Consensus proposing phase |
-| `consensus.ledger_close`    | RCLConsensus.cpp:282  | 4     | `xrpl.consensus.ledger.seq`, `xrpl.consensus.mode`                                | Ledger close event        |
-| `consensus.accept`          | RCLConsensus.cpp:395  | 4     | `xrpl.consensus.proposers`, `xrpl.consensus.round_time_ms`                        | Ledger accepted           |
-| `consensus.validation.send` | RCLConsensus.cpp:753  | 4     | `xrpl.consensus.ledger.seq`, `xrpl.consensus.proposing`                           | Validation sent           |
-| `consensus.accept.apply`    | RCLConsensus.cpp:453  | 4     | `xrpl.consensus.close_time`, `close_time_correct`, `close_resolution_ms`, `state` | Ledger apply + close time |
+| Span Name                   | Source File           | Phase | Key Attributes                                                                           | How to Trigger            |
+| --------------------------- | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ------------------------- |
+| `rpc.request`               | ServerHandler.cpp:271 | 2     | --                                                                                       | Any HTTP RPC call         |
+| `rpc.process`               | ServerHandler.cpp:573 | 2     | --                                                                                       | Any HTTP RPC call         |
+| `rpc.ws_message`            | ServerHandler.cpp:384 | 2     | --                                                                                       | WebSocket RPC message     |
+| `rpc.command.<name>`        | RPCHandler.cpp:161    | 2     | `xrpl.rpc.command`, `xrpl.rpc.version`, `xrpl.rpc.role`                                  | Any RPC command           |
+| `tx.process`                | NetworkOPs.cpp:1227   | 3     | `xrpl.tx.hash`, `xrpl.tx.local`, `xrpl.tx.path`                                          | Submit transaction        |
+| `tx.receive`                | PeerImp.cpp:1273      | 3     | `xrpl.peer.id`                                                                           | Peer relays transaction   |
+| `consensus.proposal.send`   | RCLConsensus.cpp:177  | 4     | `xrpl.consensus.round`                                                                   | Consensus proposing phase |
+| `consensus.ledger_close`    | RCLConsensus.cpp:282  | 4     | `xrpl.consensus.ledger.seq`, `xrpl.consensus.mode`                                       | Ledger close event        |
+| `consensus.accept`          | RCLConsensus.cpp:395  | 4     | `xrpl.consensus.proposers`, `xrpl.consensus.round_time_ms`                               | Ledger accepted           |
+| `consensus.validation.send` | RCLConsensus.cpp:753  | 4     | `xrpl.consensus.ledger.seq`, `xrpl.consensus.proposing`                                  | Validation sent           |
+| `consensus.accept.apply`    | RCLConsensus.cpp:453  | 4     | `xrpl.consensus.close_time`, `close_time_correct`, `close_resolution_ms`, `state`        | Ledger apply + close time |
+| `tx.apply`                  | BuildLedger.cpp:88    | 5     | `xrpl.ledger.tx_count`, `xrpl.ledger.tx_failed`                                          | Ledger close (tx set)     |
+| `ledger.build`              | BuildLedger.cpp:31    | 5     | `xrpl.ledger.seq`, `xrpl.ledger.close_time`, `close_time_correct`, `close_resolution_ms` | Ledger build              |
+| `ledger.validate`           | LedgerMaster.cpp:915  | 5     | `xrpl.ledger.seq`, `xrpl.ledger.validations`                                             | Ledger validated          |
+| `ledger.store`              | LedgerMaster.cpp:409  | 5     | `xrpl.ledger.seq`                                                                        | Ledger stored             |
+| `peer.proposal.receive`     | PeerImp.cpp:1667      | 5     | `xrpl.peer.id`, `xrpl.peer.proposal.trusted`                                             | Peer sends proposal       |
+| `peer.validation.receive`   | PeerImp.cpp:2264      | 5     | `xrpl.peer.id`, `xrpl.peer.validation.trusted`                                           | Peer sends validation     |
 
 ---
 
@@ -407,12 +413,14 @@ curl -s "$TEMPO/api/v2/search/tag/resource.service.name/values" | jq '.tagValues
 # Query traces by operation
 for op in "rpc.request" "rpc.process" \
           "rpc.command.server_info" "rpc.command.server_state" "rpc.command.ledger" \
-          "tx.process" "tx.receive" \
+          "tx.process" "tx.receive" "tx.apply" \
           "consensus.proposal.send" "consensus.ledger_close" \
           "consensus.accept" "consensus.accept.apply" \
-          "consensus.validation.send"; do
+          "consensus.validation.send" \
+          "ledger.build" "ledger.validate" "ledger.store" \
+          "peer.proposal.receive" "peer.validation.receive"; do
   count=$(curl -s "$TEMPO/api/search" \
-    --data-urlencode "q={resource.service.name=\"rippled\" && name=\"$op\"}" \
+    --data-urlencode "q={resource.service.name=\"xrpld\" && name=\"$op\"}" \
     --data-urlencode "limit=5" \
     | jq '.traces | length')
   printf "%-35s %s traces\n" "$op" "$count"
@@ -445,9 +453,11 @@ Open http://localhost:3000 (anonymous admin access enabled).
 
 Pre-configured dashboards:
 
-- **RPC Performance**: Request rates, latency percentiles by command
-- **Transaction Overview**: Transaction processing rates and paths
-- **Consensus Health**: Consensus round duration and proposer counts
+- **RPC Performance**: Request rates, latency percentiles by command, top commands, WebSocket rate
+- **Transaction Overview**: Transaction processing rates, apply duration, peer relay, failed tx rate
+- **Consensus Health**: Consensus round duration, proposer counts, mode tracking, accept heatmap
+- **Ledger Operations**: Build/validate/store rates and durations, TX apply metrics
+- **Peer Network**: Proposal/validation receive rates, trusted vs untrusted breakdown (requires `trace_peer=1`)
 
 Pre-configured datasources:
 

docker/telemetry/docker-compose.yml

@@ -1,7 +1,7 @@
-# Docker Compose stack for rippled OpenTelemetry observability.
+# Docker Compose stack for xrpld OpenTelemetry observability.
 #
 # Provides services for local development:
-#   - otel-collector: receives OTLP traces from rippled, batches and
+#   - otel-collector: receives OTLP traces from xrpld, batches and
 #     forwards them to Tempo. Listens on ports 4317 (gRPC)
 #     and 4318 (HTTP).
 #   - tempo: Grafana Tempo tracing backend, queryable via Grafana Explore
@@ -12,42 +12,45 @@
 # Usage:
 #   docker compose -f docker/telemetry/docker-compose.yml up -d
 #
-# Configure rippled to export traces by adding to xrpld.cfg:
+# Configure xrpld to export traces by adding to xrpld.cfg:
 #   [telemetry]
 #   enabled=1
 #   endpoint=http://localhost:4318/v1/traces
 
-version: "3.8"
-
 services:
+  # OpenTelemetry Collector: receives spans from xrpld via OTLP protocol,
+  # batches them for efficiency, and forwards to Tempo for storage.
   otel-collector:
-    image: otel/opentelemetry-collector-contrib:latest
+    image: otel/opentelemetry-collector-contrib:0.121.0
     command: ["--config=/etc/otel-collector-config.yaml"]
     ports:
       - "4317:4317" # OTLP gRPC
-      - "4318:4318" # OTLP HTTP (traces + native OTel metrics)
-      - "8889:8889" # Prometheus metrics (spanmetrics + OTLP)
+      - "4318:4318" # OTLP HTTP
+      - "8125:8125/udp" # StatsD UDP (beast::insight metrics)
+      - "8889:8889" # Prometheus metrics (spanmetrics + statsd)
       - "13133:13133" # Health check
-      # StatsD UDP port removed — beast::insight now uses native OTLP.
-      # Uncomment if using server=statsd fallback:
-      # - "8125:8125/udp"
     volumes:
+      # Mount collector pipeline config (receivers → processors → exporters)
       - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
     depends_on:
       - tempo
     networks:
-      - rippled-telemetry
+      - xrpld-telemetry
 
+  # Grafana Tempo: distributed tracing backend that stores and indexes
+  # spans. Queryable via TraceQL in Grafana Explore.
   tempo:
     image: grafana/tempo:2.7.2
     command: ["-config.file=/etc/tempo.yaml"]
     ports:
-      - "3200:3200" # Tempo HTTP API (health, query)
+      - "3200:3200" # Tempo HTTP API (health check, query)
     volumes:
+      # Mount Tempo storage and ingestion config
       - ./tempo.yaml:/etc/tempo.yaml:ro
+      # Persistent volume for trace data (WAL + blocks)
       - tempo-data:/var/tempo
     networks:
-      - rippled-telemetry
+      - xrpld-telemetry
 
   prometheus:
     image: prom/prometheus:latest
@@ -58,27 +61,35 @@ services:
     depends_on:
       - otel-collector
     networks:
-      - rippled-telemetry
+      - xrpld-telemetry
 
+  # Grafana: visualization UI with Tempo pre-configured as a datasource.
+  # Anonymous admin access enabled for local development convenience.
   grafana:
-    image: grafana/grafana:latest
+    image: grafana/grafana:11.5.2
     environment:
-      - GF_AUTH_ANONYMOUS_ENABLED=true
-      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_AUTH_ANONYMOUS_ENABLED=true # No login required for local dev
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin # Full access without auth
     ports:
-      - "3000:3000"
+      - "3000:3000" # Grafana web UI
     volumes:
+      # Auto-provision Tempo datasource and search filters on startup
       - ./grafana/provisioning:/etc/grafana/provisioning:ro
       - ./grafana/dashboards:/var/lib/grafana/dashboards:ro
     depends_on:
       - tempo
       - prometheus
     networks:
-      - rippled-telemetry
+      - xrpld-telemetry
 
+# Named volume for Tempo trace storage (WAL and compacted blocks).
+# Data persists across container restarts. Remove with:
+#   docker compose -f docker/telemetry/docker-compose.yml down -v
 volumes:
   tempo-data:
 
+# Isolated bridge network so services communicate by container name
+# (e.g., the collector reaches Tempo at http://tempo:4317).
 networks:
-  rippled-telemetry:
+  xrpld-telemetry:
     driver: bridge

docker/telemetry/grafana/dashboards/consensus-health.json

@@ -29,14 +29,14 @@
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "histogram_quantile(0.95, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", span_name=\"consensus.accept\"}[5m])))",
+          "expr": "histogram_quantile(0.95, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", xrpl_consensus_mode=~\"$consensus_mode\", span_name=\"consensus.accept\"}[5m])))",
           "legendFormat": "P95 Round Duration [{{exported_instance}}]"
         },
         {
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "histogram_quantile(0.50, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", span_name=\"consensus.accept\"}[5m])))",
+          "expr": "histogram_quantile(0.50, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", xrpl_consensus_mode=~\"$consensus_mode\", span_name=\"consensus.accept\"}[5m])))",
           "legendFormat": "P50 Round Duration [{{exported_instance}}]"
         }
       ],
@@ -75,7 +75,7 @@
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "sum by (exported_instance) (rate(traces_span_metrics_calls_total{exported_instance=~\"$node\", span_name=\"consensus.proposal.send\"}[5m]))",
+          "expr": "sum by (exported_instance) (rate(traces_span_metrics_calls_total{exported_instance=~\"$node\", xrpl_consensus_mode=~\"$consensus_mode\", span_name=\"consensus.proposal.send\"}[5m]))",
           "legendFormat": "Proposals / Sec [{{exported_instance}}]"
         }
       ],
@@ -114,7 +114,7 @@
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "histogram_quantile(0.95, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", span_name=\"consensus.ledger_close\"}[5m])))",
+          "expr": "histogram_quantile(0.95, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", xrpl_consensus_mode=~\"$consensus_mode\", span_name=\"consensus.ledger_close\"}[5m])))",
           "legendFormat": "P95 Close Duration [{{exported_instance}}]"
         }
       ],
@@ -153,7 +153,7 @@
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "sum by (exported_instance) (rate(traces_span_metrics_calls_total{exported_instance=~\"$node\", span_name=\"consensus.validation.send\"}[5m]))",
+          "expr": "sum by (exported_instance) (rate(traces_span_metrics_calls_total{exported_instance=~\"$node\", xrpl_consensus_mode=~\"$consensus_mode\", span_name=\"consensus.validation.send\"}[5m]))",
           "legendFormat": "Validations / Sec [{{exported_instance}}]"
         }
       ],
@@ -179,14 +179,14 @@
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "histogram_quantile(0.95, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", span_name=\"consensus.accept.apply\"}[5m])))",
+          "expr": "histogram_quantile(0.95, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", xrpl_consensus_mode=~\"$consensus_mode\", span_name=\"consensus.accept.apply\"}[5m])))",
           "legendFormat": "P95 Apply Duration [{{exported_instance}}]"
         },
         {
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "histogram_quantile(0.50, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", span_name=\"consensus.accept.apply\"}[5m])))",
+          "expr": "histogram_quantile(0.50, sum by (le, exported_instance) (rate(traces_span_metrics_duration_milliseconds_bucket{exported_instance=~\"$node\", xrpl_consensus_mode=~\"$consensus_mode\", span_name=\"consensus.accept.apply\"}[5m])))",
           "legendFormat": "P50 Apply Duration [{{exported_instance}}]"
         }
       ],
@@ -219,8 +219,8 @@
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "sum by (exported_instance) (rate(traces_span_metrics_calls_total{exported_instance=~\"$node\", span_name=\"consensus.accept.apply\"}[5m]))",
-          "legendFormat": "Total Rounds / Sec [{{exported_instance}}]"
+          "expr": "sum by (xrpl_consensus_close_time_correct, exported_instance) (rate(traces_span_metrics_calls_total{span_name=\"consensus.accept.apply\", xrpl_consensus_mode=~\"$consensus_mode\", exported_instance=~\"$node\"}[$__rate_interval]))",
+          "legendFormat": "Close Time Correct={{xrpl_consensus_close_time_correct}} [{{exported_instance}}]"
         }
       ],
       "fieldConfig": {
@@ -397,6 +397,263 @@
           "format": "heatmap"
         }
       ]
+    },
+    {
+      "title": "Close Time: Raw Proposals (Per Node)",
+      "description": "Each node's raw proposed close time (xrpl.consensus.close_time_self) \u2014 the unrounded wall clock value at the moment the node closed its ledger. Compare across nodes to see clock drift.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 40
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "dateTimeFromNow",
+          "custom": {
+            "drawStyle": "points",
+            "pointSize": 6,
+            "showPoints": "always"
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        },
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "calcs": ["lastNotNull"]
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "tempo"
+          },
+          "queryType": "traceql",
+          "query": "{name=\"consensus.accept.apply\" && resource.service.instance.id=~\"$node\" && span.xrpl.consensus.close_time_correct=~\"$close_time_correct\"} | select(span.xrpl.consensus.close_time_self)",
+          "refId": "A"
+        }
+      ]
+    },
+    {
+      "title": "Close Time: Effective / Quantized",
+      "description": "The consensus-agreed close time after rounding to the current resolution bin (xrpl.consensus.close_time). This is the value written to the ledger header. All nodes in agreement produce the same value.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 40
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "dateTimeFromNow",
+          "custom": {
+            "drawStyle": "points",
+            "pointSize": 6,
+            "showPoints": "always"
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        },
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "calcs": ["lastNotNull"]
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "tempo"
+          },
+          "queryType": "traceql",
+          "query": "{name=\"consensus.accept.apply\" && resource.service.instance.id=~\"$node\" && span.xrpl.consensus.close_time_correct=~\"$close_time_correct\"} | select(span.xrpl.consensus.close_time)",
+          "refId": "A"
+        }
+      ]
+    },
+    {
+      "title": "Close Time Vote Bins & Resolution",
+      "description": "Number of distinct close time vote bins (xrpl.consensus.close_time_vote_bins) and the bin size / resolution in ms (xrpl.consensus.close_resolution_ms). More bins = more clock disagreement. Resolution adapts: finer (10s) when validators agree, coarser (120s) when they disagree.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 48
+      },
+      "fieldConfig": {
+        "defaults": {
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "stepAfter",
+            "pointSize": 5,
+            "showPoints": "auto"
+          }
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Vote Bins"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "short"
+              },
+              {
+                "id": "custom.axisPlacement",
+                "value": "left"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Resolution"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "ms"
+              },
+              {
+                "id": "custom.axisPlacement",
+                "value": "right"
+              }
+            ]
+          }
+        ]
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        },
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "calcs": ["mean", "max"]
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "tempo"
+          },
+          "queryType": "traceql",
+          "query": "{name=\"consensus.accept.apply\" && resource.service.instance.id=~\"$node\" && span.xrpl.consensus.close_time_correct=~\"$close_time_correct\"} | select(span.xrpl.consensus.close_time_vote_bins)",
+          "refId": "A"
+        },
+        {
+          "datasource": {
+            "type": "tempo"
+          },
+          "queryType": "traceql",
+          "query": "{name=\"consensus.accept.apply\" && resource.service.instance.id=~\"$node\" && span.xrpl.consensus.close_time_correct=~\"$close_time_correct\"} | select(span.xrpl.consensus.close_resolution_ms)",
+          "refId": "B"
+        }
+      ]
+    },
+    {
+      "title": "Close Time Resolution Direction",
+      "description": "Whether close time resolution increased (coarser bins, more disagreement), decreased (finer bins, better agreement), or stayed unchanged relative to the previous ledger. Based on xrpl.consensus.resolution_direction attribute.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 48
+      },
+      "fieldConfig": {
+        "defaults": {
+          "custom": {
+            "drawStyle": "bars",
+            "fillOpacity": 40,
+            "pointSize": 5,
+            "showPoints": "auto"
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        },
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "calcs": ["lastNotNull"]
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "tempo"
+          },
+          "queryType": "traceql",
+          "query": "{name=\"consensus.accept.apply\" && resource.service.instance.id=~\"$node\" && span.xrpl.consensus.close_time_correct=~\"$close_time_correct\" && span.xrpl.consensus.resolution_direction=~\"$resolution_direction\"} | select(span.xrpl.consensus.resolution_direction)",
+          "refId": "A"
+        }
+      ]
+    },
+    {
+      "title": "Close Time Bin Distribution",
+      "description": "Distribution of raw proposed close times across quantized bins. Shows how many nodes' proposals landed in each resolution bin per consensus round. A single dominant bin indicates good clock agreement; spread across bins indicates drift or network latency.",
+      "type": "barchart",
+      "gridPos": {
+        "h": 8,
+        "w": 24,
+        "x": 0,
+        "y": 56
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "fillOpacity": 60
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        },
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "calcs": ["sum"]
+        },
+        "xTickLabelRotation": -45,
+        "barWidth": 0.8,
+        "stacking": "normal"
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "tempo"
+          },
+          "queryType": "traceql",
+          "query": "{name=\"consensus.accept.apply\" && resource.service.instance.id=~\"$node\" && span.xrpl.consensus.close_time_correct=~\"$close_time_correct\"} | select(span.xrpl.consensus.close_time, span.xrpl.consensus.close_time_vote_bins)",
+          "refId": "A"
+        }
+      ]
     }
   ],
   "schemaVersion": 39,
@@ -406,7 +663,7 @@
       {
         "name": "node",
         "label": "Node",
-        "description": "Filter by rippled node (service.instance.id — e.g. Node-1)",
+        "description": "Filter by rippled node (service.instance.id \u2014 e.g. Node-1)",
         "type": "query",
         "query": "label_values(traces_span_metrics_calls_total, exported_instance)",
         "datasource": {
@@ -442,6 +699,71 @@
         "multi": true,
         "refresh": 2,
         "sort": 1
+      },
+      {
+        "name": "close_time_correct",
+        "label": "Close Time Agreed",
+        "type": "custom",
+        "query": "true,false",
+        "current": {
+          "text": "All",
+          "value": "$__all"
+        },
+        "includeAll": true,
+        "allValue": ".*",
+        "multi": true,
+        "options": [
+          {
+            "text": "All",
+            "value": "$__all",
+            "selected": true
+          },
+          {
+            "text": "true",
+            "value": "true",
+            "selected": false
+          },
+          {
+            "text": "false",
+            "value": "false",
+            "selected": false
+          }
+        ]
+      },
+      {
+        "name": "resolution_direction",
+        "label": "Resolution Direction",
+        "type": "custom",
+        "query": "increased,decreased,unchanged",
+        "current": {
+          "text": "All",
+          "value": "$__all"
+        },
+        "includeAll": true,
+        "allValue": ".*",
+        "multi": true,
+        "options": [
+          {
+            "text": "All",
+            "value": "$__all",
+            "selected": true
+          },
+          {
+            "text": "increased",
+            "value": "increased",
+            "selected": false
+          },
+          {
+            "text": "decreased",
+            "value": "decreased",
+            "selected": false
+          },
+          {
+            "text": "unchanged",
+            "value": "unchanged",
+            "selected": false
+          }
+        ]
       }
     ]
   },

docker/telemetry/grafana/dashboards/statsd-ledger-data-sync.json

@@ -0,0 +1,506 @@
+{
+  "annotations": {
+    "list": []
+  },
+  "description": "Ledger data exchange and object fetch traffic from beast::insight StatsD. Covers ledger sync, node data retrieval, and transaction set exchange. Requires [insight] server=statsd in rippled config.",
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "panels": [
+    {
+      "title": "Ledger Data Exchange (Bytes In)",
+      "description": "Inbound bytes for ledger data sub-categories. 'ledger_data' = aggregated ledger data, sub-types include Transaction_Set_candidate (proposed tx sets), Transaction_Node (tx tree nodes), and Account_State_Node (state tree nodes). High Account_State_Node traffic indicates state sync; high Transaction_Set_candidate indicates consensus catch-up. Sourced from TrafficCount.h ledger_data_* categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_data_get_Bytes_In",
+          "legendFormat": "Ledger Data Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_data_share_Bytes_In",
+          "legendFormat": "Ledger Data Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_data_Transaction_Set_candidate_get_Bytes_In",
+          "legendFormat": "TX Set Candidate Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_data_Transaction_Set_candidate_share_Bytes_In",
+          "legendFormat": "TX Set Candidate Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_data_Transaction_Node_get_Bytes_In",
+          "legendFormat": "TX Node Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_data_Transaction_Node_share_Bytes_In",
+          "legendFormat": "TX Node Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_data_Account_State_Node_get_Bytes_In",
+          "legendFormat": "Account State Node Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_data_Account_State_Node_share_Bytes_In",
+          "legendFormat": "Account State Node Share"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Bytes In",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Ledger Share/Get Traffic (Bytes)",
+      "description": "Legacy ledger share and get traffic by sub-type. These are the older ledger fetch protocol categories (as opposed to ledger_data_* which is the newer protocol). Sub-types: Transaction_Set_candidate, Transaction_node, Account_State_node, plus aggregate ledger_share and ledger_get. Sourced from TrafficCount.h ledger_* categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_share_Bytes_In",
+          "legendFormat": "Ledger Share In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_get_Bytes_In",
+          "legendFormat": "Ledger Get In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_Transaction_Set_candidate_share_Bytes_In",
+          "legendFormat": "TX Set Candidate Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_Transaction_Set_candidate_get_Bytes_In",
+          "legendFormat": "TX Set Candidate Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_Transaction_node_share_Bytes_In",
+          "legendFormat": "TX Node Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_Transaction_node_get_Bytes_In",
+          "legendFormat": "TX Node Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_Account_State_node_share_Bytes_In",
+          "legendFormat": "Account State Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledger_Account_State_node_get_Bytes_In",
+          "legendFormat": "Account State Get"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Bytes In",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "GetObject Traffic by Type (Bytes In)",
+      "description": "Object fetch traffic by object type. GetObject is the protocol for fetching specific SHAMap nodes. Types: Ledger (full ledger headers), Transaction (individual txs), Transaction_node (tx tree nodes), Account_State_node (state tree nodes), CAS (Content Addressable Storage objects), Fetch_Pack (batch fetch during catch-up), Transactions (bulk tx fetch). High Fetch_Pack traffic indicates a node is catching up. Sourced from TrafficCount.h getobject_* categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Ledger_get_Bytes_In",
+          "legendFormat": "Ledger Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Ledger_share_Bytes_In",
+          "legendFormat": "Ledger Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Transaction_get_Bytes_In",
+          "legendFormat": "Transaction Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Transaction_share_Bytes_In",
+          "legendFormat": "Transaction Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Transaction_node_get_Bytes_In",
+          "legendFormat": "TX Node Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Transaction_node_share_Bytes_In",
+          "legendFormat": "TX Node Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Account_State_node_get_Bytes_In",
+          "legendFormat": "Account State Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Account_State_node_share_Bytes_In",
+          "legendFormat": "Account State Share"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Bytes In",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "GetObject Aggregate & Special Types (Bytes In)",
+      "description": "Aggregate getobject traffic plus special categories: CAS (Content Addressable Storage) for SHAMap node fetch, Fetch_Pack for bulk batch downloads during catch-up, Transactions for bulk tx fetch, and the aggregate getobject_get/getobject_share totals. Sourced from TrafficCount.h getobject_* categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_CAS_get_Bytes_In",
+          "legendFormat": "CAS Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_CAS_share_Bytes_In",
+          "legendFormat": "CAS Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Fetch_Pack_share_Bytes_In",
+          "legendFormat": "Fetch Pack Share"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Fetch_Pack_get_Bytes_In",
+          "legendFormat": "Fetch Pack Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Transactions_get_Bytes_In",
+          "legendFormat": "Transactions Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_get_Bytes_In",
+          "legendFormat": "Aggregate Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_share_Bytes_In",
+          "legendFormat": "Aggregate Share"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Bytes In",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "GetObject Messages by Type",
+      "description": "Message counts for object fetch operations. Shows how many individual fetch requests and responses are exchanged per type. High message counts with low byte counts indicate small object fetches; the inverse indicates large batch transfers. Sourced from TrafficCount.h getobject_* categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Ledger_get_Messages_In",
+          "legendFormat": "Ledger Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Transaction_get_Messages_In",
+          "legendFormat": "Transaction Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Transaction_node_get_Messages_In",
+          "legendFormat": "TX Node Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Account_State_node_get_Messages_In",
+          "legendFormat": "Account State Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_CAS_get_Messages_In",
+          "legendFormat": "CAS Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Fetch_Pack_get_Messages_In",
+          "legendFormat": "Fetch Pack Get"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_getobject_Transactions_get_Messages_In",
+          "legendFormat": "Transactions Get"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Messages In",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Overlay Traffic Heatmap (All Categories, Bytes In)",
+      "description": "Bar gauge showing all overlay traffic categories ranked by inbound bytes. Provides a complete at-a-glance view of which protocol message types consume the most bandwidth across all 57+ traffic categories. Sourced from all TrafficCount.h categories via wildcard match.",
+      "type": "bargauge",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        },
+        "displayMode": "gradient",
+        "orientation": "horizontal",
+        "reduceOptions": {
+          "calcs": ["lastNotNull"],
+          "fields": "",
+          "values": false
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "topk(20, {__name__=~\"rippled_.*_Bytes_In\", __name__!~\"rippled_total_.*\"})",
+          "legendFormat": "{{__name__}}"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 1048576
+              },
+              {
+                "color": "red",
+                "value": 104857600
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    }
+  ],
+  "schemaVersion": 39,
+  "tags": ["rippled", "statsd", "ledger", "sync", "telemetry"],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "title": "Ledger Data & Sync (StatsD)",
+  "uid": "rippled-statsd-ledger-sync"
+}

docker/telemetry/grafana/dashboards/statsd-network-traffic.json

@@ -0,0 +1,784 @@
+{
+  "annotations": {
+    "list": []
+  },
+  "description": "Network traffic and peer metrics from beast::insight StatsD. Requires [insight] server=statsd in rippled config.",
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "panels": [
+    {
+      "title": "Active Peers",
+      "description": "Number of active inbound and outbound peer connections. Sourced from Peer_Finder.Active_Inbound_Peers and Peer_Finder.Active_Outbound_Peers gauges (PeerfinderManager.cpp:214-215). A healthy mainnet node typically has 10-21 outbound and 0-85 inbound peers depending on configuration.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_Peer_Finder_Active_Inbound_Peers",
+          "legendFormat": "Inbound Peers"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_Peer_Finder_Active_Outbound_Peers",
+          "legendFormat": "Outbound Peers"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Peers",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Peer Disconnects",
+      "description": "Cumulative count of peer disconnections. Sourced from the Overlay.Peer_Disconnects gauge (OverlayImpl.h:557). A rising trend indicates network instability, aggressive peer management, or resource exhaustion causing connection drops.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_Overlay_Peer_Disconnects",
+          "legendFormat": "Disconnects"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Disconnects",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Total Network Bytes",
+      "description": "Rate of total bytes sent and received across all peer connections. Sourced from the total.Bytes_In and total.Bytes_Out traffic category gauges (OverlayImpl.h:535-548). Wrapped in rate() to show throughput rather than cumulative counter values.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_total_Bytes_In[5m])",
+          "legendFormat": "Bytes In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_total_Bytes_Out[5m])",
+          "legendFormat": "Bytes Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "Bps",
+          "custom": {
+            "axisLabel": "Throughput",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Total Network Messages",
+      "description": "Total messages sent and received across all peer connections. Sourced from the total.Messages_In and total.Messages_Out traffic category gauges (OverlayImpl.h:535-548). Shows the overall message throughput of the overlay network.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_total_Messages_In",
+          "legendFormat": "Messages In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_total_Messages_Out",
+          "legendFormat": "Messages Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Messages",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Transaction Traffic",
+      "description": "Bytes and messages for transaction-related overlay traffic. Includes the transactions traffic category (OverlayImpl/TrafficCount.h). Spikes indicate high transaction volume on the network or transaction flooding.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_transactions_Messages_In",
+          "legendFormat": "TX Messages In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_transactions_Messages_Out",
+          "legendFormat": "TX Messages Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_transactions_duplicate_Messages_In",
+          "legendFormat": "TX Duplicate In"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Messages",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Proposal Traffic",
+      "description": "Messages for consensus proposal overlay traffic. Includes proposals, proposals_untrusted, and proposals_duplicate categories (TrafficCount.h). High untrusted or duplicate counts may indicate UNL misconfiguration or network spam.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_proposals_Messages_In",
+          "legendFormat": "Proposals In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_proposals_Messages_Out",
+          "legendFormat": "Proposals Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_proposals_untrusted_Messages_In",
+          "legendFormat": "Untrusted In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_proposals_duplicate_Messages_In",
+          "legendFormat": "Duplicate In"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Messages",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Validation Traffic",
+      "description": "Messages for validation overlay traffic. Includes validations, validations_untrusted, and validations_duplicate categories (TrafficCount.h). Monitoring trusted vs untrusted validation traffic helps detect UNL health issues.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 24
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_validations_Messages_In",
+          "legendFormat": "Validations In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_validations_Messages_Out",
+          "legendFormat": "Validations Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_validations_untrusted_Messages_In",
+          "legendFormat": "Untrusted In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_validations_duplicate_Messages_In",
+          "legendFormat": "Duplicate In"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Messages",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Overlay Traffic by Category (Bytes In)",
+      "description": "Top traffic categories by inbound bytes. Includes all 57 overlay traffic categories from TrafficCount.h. Shows which protocol message types consume the most bandwidth. Categories include transactions, proposals, validations, ledger data, getobject, and overlay overhead.",
+      "type": "bargauge",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 24
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "topk(10, {__name__=~\"rippled_.*_Bytes_In\", __name__!~\"rippled_total_.*\"})",
+          "legendFormat": "{{__name__}}"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes"
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_transactions_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Transactions"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_proposals_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Proposals"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_validations_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Validations"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_overhead_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Overhead"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_overhead_overlay_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Overhead Overlay"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ping_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Ping"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_status_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Status"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_getObject_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Get Object"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_haveTxSet_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Have Tx Set"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledgerData_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Ledger Data"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_share_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Ledger Share"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_data_get_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Ledger Data Get"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_data_share_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Ledger Data Share"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_data_Account_State_Node_get_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Account State Node Get"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_data_Account_State_Node_share_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Account State Node Share"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_data_Transaction_Node_get_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Transaction Node Get"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_data_Transaction_Node_share_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Transaction Node Share"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_data_Transaction_Set_candidate_get_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Tx Set Candidate Get"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_Account_State_node_share_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Account State Node Share (Legacy)"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_Transaction_Set_candidate_share_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Tx Set Candidate Share"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_ledger_Transaction_node_share_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Transaction Node Share (Legacy)"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "rippled_set_get_Bytes_In"
+            },
+            "properties": [
+              {
+                "id": "displayName",
+                "value": "Set Get"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "title": "Duplicate Traffic (Wasted Bandwidth)",
+      "description": "Rate of duplicate overlay traffic across transaction, proposal, and validation categories. Duplicate messages are messages the node has already seen and discards. High duplicate rates indicate inefficient message routing or network topology issues causing redundant relays.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 32
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_transactions_duplicate_Bytes_In[5m])",
+          "legendFormat": "TX Duplicate In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_transactions_duplicate_Bytes_Out[5m])",
+          "legendFormat": "TX Duplicate Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_proposals_duplicate_Bytes_In[5m])",
+          "legendFormat": "Proposals Duplicate In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_proposals_duplicate_Bytes_Out[5m])",
+          "legendFormat": "Proposals Duplicate Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_validations_duplicate_Bytes_In[5m])",
+          "legendFormat": "Validations Duplicate In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_validations_duplicate_Bytes_Out[5m])",
+          "legendFormat": "Validations Duplicate Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "Bps",
+          "custom": {
+            "axisLabel": "Throughput",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "All Traffic Categories (Detail)",
+      "description": "Top 15 traffic categories by inbound byte rate, excluding the total aggregate. Provides a detailed timeseries view of which overlay message types are consuming the most bandwidth over time. Complements the bar gauge snapshot view in the Overlay Traffic panel.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 32
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "topk(15, rate({__name__=~\"rippled_.*_Bytes_In\", __name__!~\"rippled_total_.*\"}[5m]))",
+          "legendFormat": "{{__name__}}"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "Bps",
+          "custom": {
+            "axisLabel": "Throughput",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    }
+  ],
+  "schemaVersion": 39,
+  "tags": ["rippled", "statsd", "network", "telemetry"],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "title": "Network Traffic (StatsD)",
+  "uid": "rippled-statsd-network"
+}

docker/telemetry/grafana/dashboards/statsd-node-health.json

@@ -0,0 +1,930 @@
+{
+  "annotations": {
+    "list": []
+  },
+  "description": "Node health metrics from beast::insight StatsD. Requires [insight] server=statsd in rippled config.",
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "panels": [
+    {
+      "title": "Validated Ledger Age",
+      "description": "Age of the most recently validated ledger in seconds. Sourced from the LedgerMaster.Validated_Ledger_Age gauge (LedgerMaster.h:373) which is updated every collection interval via the insight hook. Values above 20s indicate the node is falling behind the network.",
+      "type": "stat",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_LedgerMaster_Validated_Ledger_Age",
+          "legendFormat": "Validated Age"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s",
+          "thresholds": {
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 10
+              },
+              {
+                "color": "red",
+                "value": 20
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Published Ledger Age",
+      "description": "Age of the most recently published ledger in seconds. Sourced from the LedgerMaster.Published_Ledger_Age gauge (LedgerMaster.h:374). Published ledger age should track close to validated ledger age. A growing gap indicates publish pipeline backlog.",
+      "type": "stat",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_LedgerMaster_Published_Ledger_Age",
+          "legendFormat": "Published Age"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s",
+          "thresholds": {
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 10
+              },
+              {
+                "color": "red",
+                "value": 20
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Operating Mode Duration",
+      "description": "Cumulative time spent in each operating mode (Disconnected, Connected, Syncing, Tracking, Full). Sourced from State_Accounting.*_duration gauges (NetworkOPs.cpp:774-778). A healthy node should spend the vast majority of time in Full mode.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Full_duration",
+          "legendFormat": "Full"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Tracking_duration",
+          "legendFormat": "Tracking"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Syncing_duration",
+          "legendFormat": "Syncing"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Connected_duration",
+          "legendFormat": "Connected"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Disconnected_duration",
+          "legendFormat": "Disconnected"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s",
+          "custom": {
+            "axisLabel": "Duration (Sec)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Operating Mode Transitions",
+      "description": "Count of transitions into each operating mode. Sourced from State_Accounting.*_transitions gauges (NetworkOPs.cpp:780-786). Frequent transitions out of Full mode indicate instability. Transitions to Disconnected or Syncing warrant investigation.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Full_transitions",
+          "legendFormat": "Full"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Tracking_transitions",
+          "legendFormat": "Tracking"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Syncing_transitions",
+          "legendFormat": "Syncing"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Connected_transitions",
+          "legendFormat": "Connected"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_State_Accounting_Disconnected_transitions",
+          "legendFormat": "Disconnected"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Transitions",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "I/O Latency",
+      "description": "P95 and P50 of the I/O service loop latency in milliseconds. Sourced from the ios_latency event (Application.cpp:438) which measures how long it takes for the io_context to process a timer callback. Values above 10ms are logged; above 500ms trigger warnings. High values indicate thread pool saturation or blocking operations.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ios_latency{quantile=\"0.95\"}",
+          "legendFormat": "P95 I/O Latency"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ios_latency{quantile=\"0.5\"}",
+          "legendFormat": "P50 I/O Latency"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Latency (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Job Queue Depth",
+      "description": "Current number of jobs waiting in the job queue. Sourced from the job_count gauge (JobQueue.cpp:26). A sustained high value indicates the node cannot process work fast enough — common during ledger replay or heavy RPC load.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_job_count",
+          "legendFormat": "Job Queue Depth"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Jobs",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Ledger Fetch Rate",
+      "description": "Rate of ledger fetch requests initiated by the node. Sourced from the ledger_fetches counter (InboundLedgers.cpp:44) which increments each time the node requests a ledger from a peer. High rates indicate the node is catching up or missing ledgers.",
+      "type": "stat",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 24
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_ledger_fetches_total[5m])",
+          "legendFormat": "Fetches / Sec"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ops"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Ledger History Mismatches",
+      "description": "Rate of ledger history hash mismatches. Sourced from the ledger.history.mismatch counter (LedgerHistory.cpp:16) which increments when a built ledger hash does not match the expected validated hash. Non-zero values indicate consensus divergence or database corruption.",
+      "type": "stat",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 24
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_ledger_history_mismatch_total[5m])",
+          "legendFormat": "Mismatches / Sec"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ops",
+          "thresholds": {
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "red",
+                "value": 0.01
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Key Jobs Execution Time",
+      "description": "Execution time for critical job types at the selected quantile. Sourced from per-job-type events in JobTypeData (JobTypeData.h:48). Shows how long key consensus, transaction, and maintenance jobs take to execute. Spikes indicate processing bottlenecks.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 32
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_acceptLedger{quantile=\"$quantile\"}",
+          "legendFormat": "Accept Ledger [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_advanceLedger{quantile=\"$quantile\"}",
+          "legendFormat": "Advance Ledger [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_transaction{quantile=\"$quantile\"}",
+          "legendFormat": "Transaction [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_writeObjects{quantile=\"$quantile\"}",
+          "legendFormat": "Write Objects [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_heartbeat{quantile=\"$quantile\"}",
+          "legendFormat": "Heartbeat [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_sweep{quantile=\"$quantile\"}",
+          "legendFormat": "Sweep [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_trustedValidation{quantile=\"$quantile\"}",
+          "legendFormat": "Trusted Validation [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_trustedProposal{quantile=\"$quantile\"}",
+          "legendFormat": "Trusted Proposal [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_publishNewLedger{quantile=\"$quantile\"}",
+          "legendFormat": "Publish New Ledger [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_clientRPC{quantile=\"$quantile\"}",
+          "legendFormat": "Client RPC [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledgerData{quantile=\"$quantile\"}",
+          "legendFormat": "Ledger Data [{{quantile}}]"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Duration (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Key Jobs Dequeue Wait Time",
+      "description": "Time spent waiting in the job queue before execution for critical job types. Sourced from per-job-type dequeue events (JobTypeData.h:47). High dequeue times indicate the job queue is backlogged and jobs are waiting too long to be scheduled.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 32
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_acceptLedger_q{quantile=\"$quantile\"}",
+          "legendFormat": "Accept Ledger [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_advanceLedger_q{quantile=\"$quantile\"}",
+          "legendFormat": "Advance Ledger [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_transaction_q{quantile=\"$quantile\"}",
+          "legendFormat": "Transaction [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_writeObjects_q{quantile=\"$quantile\"}",
+          "legendFormat": "Write Objects [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_heartbeat_q{quantile=\"$quantile\"}",
+          "legendFormat": "Heartbeat [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_sweep_q{quantile=\"$quantile\"}",
+          "legendFormat": "Sweep [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_trustedValidation_q{quantile=\"$quantile\"}",
+          "legendFormat": "Trusted Validation [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_trustedProposal_q{quantile=\"$quantile\"}",
+          "legendFormat": "Trusted Proposal [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_publishNewLedger_q{quantile=\"$quantile\"}",
+          "legendFormat": "Publish New Ledger [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_clientRPC_q{quantile=\"$quantile\"}",
+          "legendFormat": "Client RPC [{{quantile}}]"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_ledgerData_q{quantile=\"$quantile\"}",
+          "legendFormat": "Ledger Data [{{quantile}}]"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Wait Time (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "FullBelowCache Size",
+      "description": "Number of entries in the FullBelowCache. Sourced from the TaggedCache size gauge (TaggedCache.h:183) for the Node family full below cache (NodeFamily.cpp:29). This cache tracks which SHAMap nodes have all children present locally, avoiding redundant fetches during ledger acquisition.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 40
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_Node_family_full_below_cache_size",
+          "legendFormat": "FullBelowCache Size"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Entries",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "FullBelowCache Hit Rate",
+      "description": "Hit rate percentage for the FullBelowCache. Sourced from the TaggedCache hit_rate gauge (TaggedCache.h:184). A high hit rate means the node is efficiently reusing cached knowledge about complete SHAMap subtrees. Low hit rates during steady state warrant investigation.",
+      "type": "gauge",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 40
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_Node_family_full_below_cache_hit_rate",
+          "legendFormat": "Hit Rate"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "thresholds": {
+            "steps": [
+              {
+                "color": "red",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 25
+              },
+              {
+                "color": "green",
+                "value": 50
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Ledger Publish Gap",
+      "description": "Difference between published and validated ledger ages. Computed as Published_Ledger_Age minus Validated_Ledger_Age. A value near zero means the publish pipeline keeps up with validation. A growing gap indicates the publish pipeline is falling behind, potentially causing stale data for subscribers.",
+      "type": "stat",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 48
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_LedgerMaster_Published_Ledger_Age - rippled_LedgerMaster_Validated_Ledger_Age",
+          "legendFormat": "Publish Gap"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s",
+          "thresholds": {
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 5
+              },
+              {
+                "color": "red",
+                "value": 10
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "State Duration Rate (Full vs Tracking)",
+      "description": "Rate of change of time spent in Full and Tracking operating modes, normalized to seconds. Sourced from State_Accounting duration gauges (NetworkOPs.cpp:774-778). In steady state the Full duration rate should be close to 1.0 (gaining one second of Full-mode time per wall-clock second). A drop below 1.0 means the node is spending time in other modes.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 48
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_State_Accounting_Full_duration[5m]) / 1000000",
+          "legendFormat": "Full Mode Rate"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_State_Accounting_Tracking_duration[5m]) / 1000000",
+          "legendFormat": "Tracking Mode Rate"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Rate (s/s)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "All Jobs Execution Time (Detail)",
+      "description": "Execution time for ALL non-special job types at the selected quantile. Shows the complete picture of job execution performance. Use the Key Jobs panel for a focused view of the most critical jobs.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 24,
+        "x": 0,
+        "y": 56
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "{__name__=~\"rippled_(makeFetchPack|publishAcqLedger|untrustedValidation|manifest|localTransaction|ledgerReplayRequest|ledgerRequest|untrustedProposal|ledgerReplayTask|ledgerData|clientCommand|clientSubscribe|clientFeeChange|clientConsensus|clientAccountHistory|clientRPC|clientWebsocket|RPC|updatePaths|transaction|batch|advanceLedger|publishNewLedger|fetchTxnData|writeAhead|trustedValidation|writeObjects|acceptLedger|trustedProposal|sweep|clusterReport|heartbeat|administration|handleHaveTransactions|doTransactions)\", quantile=\"$quantile\"}",
+          "legendFormat": "{{__name__}} [{{quantile}}]"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Duration (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "All Jobs Dequeue Wait (Detail)",
+      "description": "Dequeue wait time for ALL non-special job types at the selected quantile. Shows the complete picture of job queue waiting times. High wait times across many job types indicate systemic job queue congestion.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 24,
+        "x": 0,
+        "y": 64
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "{__name__=~\"rippled_(makeFetchPack_q|publishAcqLedger_q|untrustedValidation_q|manifest_q|localTransaction_q|ledgerReplayRequest_q|ledgerRequest_q|untrustedProposal_q|ledgerReplayTask_q|ledgerData_q|clientCommand_q|clientSubscribe_q|clientFeeChange_q|clientConsensus_q|clientAccountHistory_q|clientRPC_q|clientWebsocket_q|RPC_q|updatePaths_q|transaction_q|batch_q|advanceLedger_q|publishNewLedger_q|fetchTxnData_q|writeAhead_q|trustedValidation_q|writeObjects_q|acceptLedger_q|trustedProposal_q|sweep_q|clusterReport_q|heartbeat_q|administration_q|handleHaveTransactions_q|doTransactions_q)\", quantile=\"$quantile\"}",
+          "legendFormat": "{{__name__}} [{{quantile}}]"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Wait Time (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    }
+  ],
+  "schemaVersion": 39,
+  "tags": ["rippled", "statsd", "node-health", "telemetry"],
+  "templating": {
+    "list": [
+      {
+        "name": "quantile",
+        "label": "Quantile",
+        "type": "custom",
+        "query": "0.5,0.9,0.95,0.99",
+        "current": {
+          "selected": true,
+          "text": "0.95",
+          "value": "0.95"
+        },
+        "options": [
+          {
+            "selected": false,
+            "text": "0.5",
+            "value": "0.5"
+          },
+          {
+            "selected": false,
+            "text": "0.9",
+            "value": "0.9"
+          },
+          {
+            "selected": true,
+            "text": "0.95",
+            "value": "0.95"
+          },
+          {
+            "selected": false,
+            "text": "0.99",
+            "value": "0.99"
+          }
+        ],
+        "multi": false,
+        "includeAll": false
+      }
+    ]
+  },
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "title": "Node Health (StatsD)",
+  "uid": "rippled-statsd-node-health"
+}

docker/telemetry/grafana/dashboards/statsd-overlay-traffic-detail.json

@@ -0,0 +1,566 @@
+{
+  "annotations": {
+    "list": []
+  },
+  "description": "Detailed overlay traffic breakdown for categories not covered by the main Network Traffic dashboard. Includes squelch, overhead, validator lists, object fetch, ledger sync, and protocol negotiation traffic. Requires [insight] server=statsd in rippled config.",
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "panels": [
+    {
+      "title": "Squelch Traffic (Messages)",
+      "description": "Squelch-related overlay messages. Squelch is the peer traffic management protocol that suppresses redundant message forwarding. 'squelch' = squelch control messages, 'squelch_suppressed' = messages suppressed by squelch, 'squelch_ignored' = squelch directives that were ignored. High suppressed counts indicate effective bandwidth savings; high ignored counts may indicate misconfigured peers. Sourced from TrafficCount.h squelch categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_squelch_Messages_In",
+          "legendFormat": "Squelch In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_squelch_Messages_Out",
+          "legendFormat": "Squelch Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_squelch_suppressed_Messages_In",
+          "legendFormat": "Suppressed In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_squelch_suppressed_Messages_Out",
+          "legendFormat": "Suppressed Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_squelch_ignored_Messages_In",
+          "legendFormat": "Ignored In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_squelch_ignored_Messages_Out",
+          "legendFormat": "Ignored Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Messages",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Overhead Traffic Breakdown (Bytes)",
+      "description": "Overlay protocol overhead by sub-category. 'overhead' = base protocol overhead (ping, status, etc.), 'overhead_cluster' = intra-cluster communication overhead, 'overhead_manifest' = validator manifest distribution overhead. High cluster overhead may indicate frequent cluster state syncs; high manifest overhead occurs during UNL changes. Sourced from TrafficCount.h overhead categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_overhead_Bytes_In",
+          "legendFormat": "Base Overhead In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_overhead_Bytes_Out",
+          "legendFormat": "Base Overhead Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_overhead_cluster_Bytes_In",
+          "legendFormat": "Cluster In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_overhead_cluster_Bytes_Out",
+          "legendFormat": "Cluster Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_overhead_manifest_Bytes_In",
+          "legendFormat": "Manifest In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_overhead_manifest_Bytes_Out",
+          "legendFormat": "Manifest Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Bytes",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Validator List Traffic",
+      "description": "Validator list (UNL) distribution traffic. Validator lists are exchanged when peers share their trusted validator configurations. Spikes occur during UNL updates or when new peers connect. Sourced from TrafficCount.h validator_lists category.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_validator_lists_Bytes_In",
+          "legendFormat": "Bytes In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_validator_lists_Bytes_Out",
+          "legendFormat": "Bytes Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_validator_lists_Messages_In",
+          "legendFormat": "Messages In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_validator_lists_Messages_Out",
+          "legendFormat": "Messages Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Count",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byRegexp",
+              "options": "/Bytes/"
+            },
+            "properties": [
+              {
+                "id": "custom.axisPlacement",
+                "value": "right"
+              },
+              {
+                "id": "unit",
+                "value": "decbytes"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "title": "Set Get/Share Traffic (Bytes)",
+      "description": "Transaction set get and share traffic. 'set_get' = requests to fetch transaction sets (sent during ledger close), 'set_share' = responses sharing transaction sets. High set_get traffic indicates peers frequently requesting missing transaction sets, which may signal sync delays. Sourced from TrafficCount.h set_get/set_share categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_set_get_Bytes_In",
+          "legendFormat": "Set Get In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_set_get_Bytes_Out",
+          "legendFormat": "Set Get Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_set_share_Bytes_In",
+          "legendFormat": "Set Share In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_set_share_Bytes_Out",
+          "legendFormat": "Set Share Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Bytes",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Have/Requested Transactions (Messages)",
+      "description": "Transaction availability protocol messages. 'have_transactions' = advertisements that a peer has specific transactions available, 'requested_transactions' = explicit requests for transaction data. A high ratio of requested to have may indicate peers are behind on transaction propagation. Sourced from TrafficCount.h have_transactions/requested_transactions categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_have_transactions_Messages_In",
+          "legendFormat": "Have TX In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_have_transactions_Messages_Out",
+          "legendFormat": "Have TX Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_requested_transactions_Messages_In",
+          "legendFormat": "Requested TX In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_requested_transactions_Messages_Out",
+          "legendFormat": "Requested TX Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Messages",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Unknown / Unclassified Traffic",
+      "description": "Traffic that does not match any known overlay message category. Non-zero values may indicate protocol version mismatches, corrupted messages, or new message types not yet classified. Sourced from TrafficCount.h unknown category.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_unknown_Bytes_In",
+          "legendFormat": "Unknown Bytes In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_unknown_Bytes_Out",
+          "legendFormat": "Unknown Bytes Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_unknown_Messages_In",
+          "legendFormat": "Unknown Messages In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_unknown_Messages_Out",
+          "legendFormat": "Unknown Messages Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "axisLabel": "Count",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byRegexp",
+              "options": "/Bytes/"
+            },
+            "properties": [
+              {
+                "id": "custom.axisPlacement",
+                "value": "right"
+              },
+              {
+                "id": "unit",
+                "value": "decbytes"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "title": "Proof Path Traffic",
+      "description": "Proof path request/response traffic for ledger state proof exchange. Used by peers to verify specific ledger entries without downloading the full ledger. High request volume may indicate peers validating state during catch-up. Sourced from TrafficCount.h proof_path_request/proof_path_response categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 24
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_proof_path_request_Bytes_In",
+          "legendFormat": "Request Bytes In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_proof_path_request_Bytes_Out",
+          "legendFormat": "Request Bytes Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_proof_path_response_Bytes_In",
+          "legendFormat": "Response Bytes In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_proof_path_response_Bytes_Out",
+          "legendFormat": "Response Bytes Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Bytes",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Replay Delta Traffic",
+      "description": "Replay delta request/response traffic for ledger replay protocol. Used during catch-up to efficiently replay ledger state changes. Sourced from TrafficCount.h replay_delta_request/replay_delta_response categories.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 24
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_replay_delta_request_Bytes_In",
+          "legendFormat": "Request Bytes In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_replay_delta_request_Bytes_Out",
+          "legendFormat": "Request Bytes Out"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_replay_delta_response_Bytes_In",
+          "legendFormat": "Response Bytes In"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_replay_delta_response_Bytes_Out",
+          "legendFormat": "Response Bytes Out"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Bytes",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    }
+  ],
+  "schemaVersion": 39,
+  "tags": ["rippled", "statsd", "overlay", "network", "telemetry"],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "title": "Overlay Traffic Detail (StatsD)",
+  "uid": "rippled-statsd-overlay-detail"
+}

docker/telemetry/grafana/dashboards/statsd-rpc-pathfinding.json

@@ -0,0 +1,396 @@
+{
+  "annotations": {
+    "list": []
+  },
+  "description": "RPC and pathfinding metrics from beast::insight StatsD. Requires [insight] server=statsd in rippled config.",
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "panels": [
+    {
+      "title": "RPC Request Rate (StatsD)",
+      "description": "Rate of RPC requests as counted by the beast::insight counter. Sourced from rpc.requests (ServerHandler.cpp:108) which increments on every HTTP and WebSocket RPC request. Compare with the span-based rpc.request rate in the RPC Performance dashboard for cross-validation.",
+      "type": "stat",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_rpc_requests_total[5m])",
+          "legendFormat": "Requests / Sec"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "reqps"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "RPC Response Time (StatsD)",
+      "description": "P95 and P50 of RPC response time from the beast::insight timer. Sourced from the rpc.time event (ServerHandler.cpp:110) which records elapsed milliseconds for each RPC response. This measures the full HTTP handler time, not just command execution. Compare with span-based rpc.request duration.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_rpc_time{quantile=\"0.95\"}",
+          "legendFormat": "P95 Response Time"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_rpc_time{quantile=\"0.5\"}",
+          "legendFormat": "P50 Response Time"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Latency (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "RPC Response Size",
+      "description": "P95 and P50 of RPC response payload size in bytes. Sourced from the rpc.size event (ServerHandler.cpp:109) which records the byte length of each RPC JSON response. Large responses may indicate expensive queries (e.g. account_tx with many results) or API misuse.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_rpc_size{quantile=\"0.95\"}",
+          "legendFormat": "P95 Response Size"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_rpc_size{quantile=\"0.5\"}",
+          "legendFormat": "P50 Response Size"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "decbytes",
+          "custom": {
+            "axisLabel": "Size (Bytes)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "RPC Response Time Distribution",
+      "description": "Distribution of RPC response times from the beast::insight timer showing P50, P90, P95, and P99 quantiles. Sourced from the rpc.time event (ServerHandler.cpp:110). Useful for detecting bimodal latency or long-tail requests.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_rpc_time{quantile=\"0.5\"}",
+          "legendFormat": "P50"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_rpc_time{quantile=\"0.9\"}",
+          "legendFormat": "P90"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_rpc_time{quantile=\"0.95\"}",
+          "legendFormat": "P95"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_rpc_time{quantile=\"0.99\"}",
+          "legendFormat": "P99"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Latency (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Pathfinding Fast Duration",
+      "description": "P95 and P50 of fast pathfinding execution time. Sourced from the pathfind_fast event (PathRequests.h:23) which records the duration of the fast pathfinding algorithm. Fast pathfinding uses a simplified search that trades accuracy for speed.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_pathfind_fast{quantile=\"0.95\"}",
+          "legendFormat": "P95 Fast Pathfind"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_pathfind_fast{quantile=\"0.5\"}",
+          "legendFormat": "P50 Fast Pathfind"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Duration (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Pathfinding Full Duration",
+      "description": "P95 and P50 of full pathfinding execution time. Sourced from the pathfind_full event (PathRequests.h:24) which records the duration of the exhaustive pathfinding search. Full pathfinding is more expensive and can take significantly longer than fast mode.",
+      "type": "timeseries",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_pathfind_full{quantile=\"0.95\"}",
+          "legendFormat": "P95 Full Pathfind"
+        },
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rippled_pathfind_full{quantile=\"0.5\"}",
+          "legendFormat": "P50 Full Pathfind"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ms",
+          "custom": {
+            "axisLabel": "Duration (ms)",
+            "spanNulls": true,
+            "insertNulls": false,
+            "showPoints": "auto",
+            "pointSize": 3
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Resource Warnings Rate",
+      "description": "Rate of resource warning events from the Resource Manager. Sourced from the warn meter (Logic.h:33) which increments when a consumer (peer or RPC client) exceeds the warning threshold for resource usage. A rising rate indicates aggressive clients that may need throttling. NOTE: This panel will show no data until the |m -> |c fix is applied in StatsDCollector.cpp:706 (Phase 6 Task 6.1).",
+      "type": "stat",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 24
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_warn_total[5m])",
+          "legendFormat": "Warnings / Sec"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ops",
+          "thresholds": {
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 0.1
+              },
+              {
+                "color": "red",
+                "value": 1
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "title": "Resource Drops Rate",
+      "description": "Rate of resource drop events from the Resource Manager. Sourced from the drop meter (Logic.h:34) which increments when a consumer is disconnected or blocked due to excessive resource usage. Non-zero values mean the node is actively rejecting abusive connections. NOTE: This panel will show no data until the |m -> |c fix is applied in StatsDCollector.cpp:706 (Phase 6 Task 6.1).",
+      "type": "stat",
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 24
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "datasource": {
+            "type": "prometheus"
+          },
+          "expr": "rate(rippled_drop_total[5m])",
+          "legendFormat": "Drops / Sec"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "ops",
+          "thresholds": {
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 0.01
+              },
+              {
+                "color": "red",
+                "value": 0.1
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    }
+  ],
+  "schemaVersion": 39,
+  "tags": ["rippled", "statsd", "rpc", "pathfinding", "telemetry"],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "title": "RPC & Pathfinding (StatsD)",
+  "uid": "rippled-statsd-rpc"
+}

docker/telemetry/grafana/dashboards/transaction-overview.json

@@ -147,8 +147,8 @@
           "datasource": {
             "type": "prometheus"
           },
-          "expr": "sum by (exported_instance) (rate(traces_span_metrics_calls_total{exported_instance=~\"$node\", span_name=\"tx.receive\"}[5m]))",
-          "legendFormat": "Total Received [{{exported_instance}}]"
+          "expr": "sum by (xrpl_tx_suppressed, exported_instance) (rate(traces_span_metrics_calls_total{span_name=\"tx.receive\", exported_instance=~\"$node\"}[$__rate_interval]))",
+          "legendFormat": "Suppressed={{xrpl_tx_suppressed}} [{{exported_instance}}]"
         }
       ],
       "fieldConfig": {

docker/telemetry/grafana/provisioning/dashboards/dashboards.yaml

@@ -1,9 +1,9 @@
 apiVersion: 1
 
 providers:
-  - name: rippled-telemetry
+  - name: xrpld-telemetry
     orgId: 1
-    folder: rippled
+    folder: xrpld
     type: file
     disableDeletion: false
     editable: true

docker/telemetry/grafana/provisioning/datasources/tempo.yaml

@@ -1,7 +1,7 @@
 # Grafana datasource provisioning for Grafana Tempo.
 # Auto-configures Tempo as a trace data source on Grafana startup.
 # Access Grafana at http://localhost:3000, then use Explore -> Tempo
-# to browse rippled traces using TraceQL.
+# to browse xrpld traces using TraceQL.
 #
 # Search filters provide pre-configured dropdowns in the Explore UI.
 # Each phase adds filters for the span attributes it introduces.
@@ -21,6 +21,9 @@ datasources:
     jsonData:
       nodeGraph:
         enabled: true
+      # Service map and traces-to-metrics require a Prometheus datasource
+      # (not included in this stack). These features are inactive until a
+      # Prometheus service is added to docker-compose.yml.
       serviceMap:
         datasourceUid: prometheus
       tracesToMetrics:
@@ -30,7 +33,7 @@ datasources:
       search:
         filters:
           # --- Node identification filters ---
-          # service.name: logical service name (default: "rippled").
+          # service.name: logical service name (default: "xrpld").
           #   Useful when running multiple service types in the same collector.
           - id: service-name
             tag: service.name
@@ -45,7 +48,7 @@ datasources:
             operator: "="
             scope: resource
             type: static
-          # service.version: rippled build version (e.g., "2.4.0-b1").
+          # service.version: xrpld build version (e.g., "2.4.0-b1").
           #   Filter traces from specific software releases.
           - id: node-version
             tag: service.version
@@ -54,29 +57,36 @@ datasources:
             type: dynamic
           # xrpl.network.id: numeric network identifier
           #   (0 = mainnet, 1 = testnet, 2 = devnet, etc.).
+          #   Derived from the [network_id] config section.
           - id: network-id
             tag: xrpl.network.id
             operator: "="
             scope: resource
             type: dynamic
-          # xrpl.network.type: human-readable network name
-          #   ("mainnet", "testnet", "devnet", "standalone").
+          # xrpl.network.type: human-readable network name derived from
+          #   network ID ("mainnet", "testnet", "devnet", "unknown").
           - id: network-type
             tag: xrpl.network.type
             operator: "="
             scope: resource
             type: static
           # --- Span intrinsic filters ---
+          # name: the span operation name (e.g., "rpc.command.server_info").
+          #   Use to find traces for a specific RPC command or subsystem.
           - id: span-name
             tag: name
             operator: "="
             scope: intrinsic
             type: static
+          # status: span completion status ("ok", "error", "unset").
+          #   Filter for failed operations to diagnose errors.
           - id: span-status
             tag: status
             operator: "="
             scope: intrinsic
             type: static
+          # duration: span wall-clock duration. Use with ">" operator
+          #   to find slow operations (e.g., duration > 500ms).
           - id: span-duration
             tag: duration
             operator: ">"
@@ -98,6 +108,17 @@ datasources:
             operator: "="
             scope: span
             type: dynamic
+          # Phase 2: Node health filters (Task 2.8)
+          - id: node-amendment-blocked
+            tag: xrpl.node.amendment_blocked
+            operator: "="
+            scope: span
+            type: static
+          - id: node-server-state
+            tag: xrpl.node.server_state
+            operator: "="
+            scope: span
+            type: dynamic
           # Phase 3: Transaction tracing filters
           - id: tx-hash
             tag: xrpl.tx.hash
@@ -145,3 +166,54 @@ datasources:
             operator: "="
             scope: span
             type: dynamic
+          - id: consensus-proposers
+            tag: xrpl.consensus.proposers
+            operator: "="
+            scope: span
+            type: dynamic
+          - id: consensus-result
+            tag: xrpl.consensus.result
+            operator: "="
+            scope: span
+            type: dynamic
+          - id: consensus-mode-old
+            tag: xrpl.consensus.mode.old
+            operator: "="
+            scope: span
+            type: dynamic
+          - id: consensus-mode-new
+            tag: xrpl.consensus.mode.new
+            operator: "="
+            scope: span
+            type: dynamic
+          - id: consensus-ledger-id
+            tag: xrpl.consensus.ledger_id
+            operator: "="
+            scope: span
+            type: static
+          # Phase 3/4: Additional transaction and queue filters
+          - id: tx-path
+            tag: xrpl.tx.path
+            operator: "="
+            scope: span
+            type: dynamic
+          - id: tx-suppressed
+            tag: xrpl.tx.suppressed
+            operator: "="
+            scope: span
+            type: dynamic
+          - id: peer-version
+            tag: xrpl.peer.version
+            operator: "="
+            scope: span
+            type: dynamic
+          - id: txq-status
+            tag: xrpl.txq.status
+            operator: "="
+            scope: span
+            type: dynamic
+          - id: txq-ter-code
+            tag: xrpl.txq.ter_code
+            operator: "="
+            scope: span
+            type: dynamic

docker/telemetry/integration-test.sh

@@ -314,8 +314,8 @@ trace_peer=1
 trace_ledger=1
 
 [insight]
-server=otel
-endpoint=http://localhost:4318/v1/metrics
+server=statsd
+address=127.0.0.1:8125
 prefix=rippled
 
 [rpc_startup]
@@ -438,18 +438,8 @@ seq_num=$(echo "$acct_result" | jq -r '.result.account_data.Sequence' 2>/dev/nul
 log "  Genesis account sequence: $seq_num"
 
 # Submit payment
-submit_result=$(curl -sf "http://localhost:$RPC_PORT_BASE" -d "{
-  \"method\": \"submit\",
-  \"params\": [{
-    \"secret\": \"$GENESIS_SEED\",
-    \"tx_json\": {
-      \"TransactionType\": \"Payment\",
-      \"Account\": \"$GENESIS_ACCOUNT\",
-      \"Destination\": \"$DEST_ACCOUNT\",
-      \"Amount\": \"10000000\"
-    }
-  }]
-}")
+submit_result=$(curl -sf "http://localhost:$RPC_PORT_BASE" \
+    -d "{\"method\":\"submit\",\"params\":[{\"secret\":\"$GENESIS_SEED\",\"tx_json\":{\"TransactionType\":\"Payment\",\"Account\":\"$GENESIS_ACCOUNT\",\"Destination\":\"$DEST_ACCOUNT\",\"Amount\":\"10000000\"}}]}")
 
 engine_result=$(echo "$submit_result" | jq -r '.result.engine_result' 2>/dev/null || echo "unknown")
 tx_hash=$(echo "$submit_result" | jq -r '.result.tx_json.hash' 2>/dev/null || echo "unknown")
@@ -542,52 +532,42 @@ else
 fi
 
 # ---------------------------------------------------------------------------
-# Step 10b: Verify native OTel metrics in Prometheus (beast::insight)
+# Step 10b: Verify StatsD metrics in Prometheus
 # ---------------------------------------------------------------------------
 log ""
-log "--- Phase 7: Native OTel Metrics (beast::insight via OTLP) ---"
-log "Waiting 20s for OTLP metric export + Prometheus scrape..."
+log "--- Phase 6: StatsD Metrics (beast::insight) ---"
+log "Waiting 20s for StatsD aggregation + Prometheus scrape..."
 sleep 20
 
-check_otel_metric() {
+check_statsd_metric() {
     local metric_name="$1"
     local result
     result=$(curl -sf "$PROM/api/v1/query?query=$metric_name" \
         | jq '.data.result | length' 2>/dev/null || echo 0)
     if [ "$result" -gt 0 ]; then
-        ok "OTel: $metric_name ($result series)"
+        ok "StatsD: $metric_name ($result series)"
     else
-        fail "OTel: $metric_name (0 series)"
+        fail "StatsD: $metric_name (0 series)"
     fi
 }
 
-# Node health gauges (ObservableGauge — no _total suffix)
-check_otel_metric "rippled_LedgerMaster_Validated_Ledger_Age"
-check_otel_metric "rippled_LedgerMaster_Published_Ledger_Age"
-check_otel_metric "rippled_job_count"
+# Node health gauges
+check_statsd_metric "rippled_LedgerMaster_Validated_Ledger_Age"
+check_statsd_metric "rippled_LedgerMaster_Published_Ledger_Age"
+check_statsd_metric "rippled_job_count"
 
 # State accounting
-check_otel_metric "rippled_State_Accounting_Full_duration"
+check_statsd_metric "rippled_State_Accounting_Full_duration"
 
 # Peer finder
-check_otel_metric "rippled_Peer_Finder_Active_Inbound_Peers"
-check_otel_metric "rippled_Peer_Finder_Active_Outbound_Peers"
+check_statsd_metric "rippled_Peer_Finder_Active_Inbound_Peers"
+check_statsd_metric "rippled_Peer_Finder_Active_Outbound_Peers"
 
-# RPC counters (Counter — Prometheus adds _total suffix automatically)
-check_otel_metric "rippled_rpc_requests_total"
+# RPC counters (only if RPC was exercised — should be true from Steps 5-8)
+check_statsd_metric "rippled_rpc_requests"
 
 # Overlay traffic
-check_otel_metric "rippled_total_Bytes_In"
-
-# Verify StatsD receiver is NOT required (no statsd receiver in pipeline)
-log ""
-log "--- Verify StatsD receiver is not required ---"
-statsd_port_check=$(curl -sf "http://localhost:8125" 2>&1 || echo "refused")
-if echo "$statsd_port_check" | grep -qi "refused\|error\|connection"; then
-    ok "StatsD port 8125 is not listening (not required)"
-else
-    fail "StatsD port 8125 appears to be listening (should not be needed)"
-fi
+check_statsd_metric "rippled_total_Bytes_In"
 
 # ---------------------------------------------------------------------------
 # Step 11: Summary

docker/telemetry/otel-collector-config.yaml

@@ -1,12 +1,16 @@
-# OpenTelemetry Collector configuration for rippled development.
+# OpenTelemetry Collector configuration for xrpld development.
 #
 # Pipelines:
 #   traces: OTLP receiver -> batch processor -> debug + Tempo + spanmetrics
-#   metrics: spanmetrics connector -> Prometheus exporter
+#   metrics: StatsD receiver + spanmetrics connector -> Prometheus exporter
 #
-# rippled sends traces via OTLP/HTTP to port 4318. The collector batches
+# xrpld sends traces via OTLP/HTTP to port 4318. The collector batches
 # them, forwards to Tempo, and derives RED metrics via the spanmetrics
 # connector, which Prometheus scrapes on port 8889.
+#
+# xrpld's beast::insight framework sends StatsD UDP metrics to port 8125.
+# The StatsD receiver aggregates them and exports to Prometheus alongside
+# the span-derived metrics.
 
 receivers:
   otlp:
@@ -15,6 +19,20 @@ receivers:
         endpoint: 0.0.0.0:4317
       http:
         endpoint: 0.0.0.0:4318
+  statsd:
+    endpoint: "0.0.0.0:8125"
+    aggregation_interval: 15s
+    enable_metric_type: true
+    is_monotonic_counter: true
+    timer_histogram_mapping:
+      - statsd_type: "timing"
+        observer_type: "summary"
+        summary:
+          percentiles: [0, 50, 90, 95, 99, 100]
+      - statsd_type: "histogram"
+        observer_type: "summary"
+        summary:
+          percentiles: [0, 50, 90, 95, 99, 100]
 
 processors:
   batch:
@@ -34,7 +52,9 @@ connectors:
       - name: xrpl.rpc.command
       - name: xrpl.rpc.status
       - name: xrpl.consensus.mode
+      - name: xrpl.consensus.close_time_correct
       - name: xrpl.tx.local
+      - name: xrpl.tx.suppressed
       - name: xrpl.peer.proposal.trusted
       - name: xrpl.peer.validation.trusted
 
@@ -48,12 +68,17 @@ exporters:
   prometheus:
     endpoint: 0.0.0.0:8889
 
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133
+
 service:
+  extensions: [health_check]
   pipelines:
     traces:
       receivers: [otlp]
       processors: [batch]
       exporters: [debug, otlp/tempo, spanmetrics]
     metrics:
-      receivers: [spanmetrics]
+      receivers: [spanmetrics, statsd]
       exporters: [prometheus]

docker/telemetry/tempo.yaml

@@ -1,4 +1,4 @@
-# Grafana Tempo configuration for rippled telemetry stack.
+# Grafana Tempo configuration for xrpld telemetry stack.
 #
 # Runs in single-binary mode for local development.
 # Receives traces via OTLP/gRPC from the OTel Collector and stores
@@ -40,8 +40,10 @@ metrics_generator:
       source: tempo
   storage:
     path: /var/tempo/generator/wal
-    remote_write:
-      - url: http://prometheus:9090/api/v1/write
+    # Uncomment and add a Prometheus service to docker-compose.yml
+    # to enable remote_write for service graph metrics:
+    # remote_write:
+    #   - url: http://prometheus:9090/api/v1/write
 
 overrides:
   defaults:

docker/telemetry/xrpld-telemetry.cfg

@@ -46,7 +46,7 @@ docker/telemetry/data/debug.log
 # --- OpenTelemetry tracing ---
 [telemetry]
 enabled=1
-service_instance_id=rippled-standalone
+service_instance_id=xrpld-standalone
 endpoint=http://localhost:4318/v1/traces
 exporter=otlp_http
 sampling_ratio=1.0

docs/0001-negative-unl/README.md

@@ -558,7 +558,7 @@ network delay. A test case specifies:
 1. a UNL with different number of validators for different test cases,
 1. a network with zero or more non-validator nodes,
 1. a sequence of validator reliability change events (by killing/restarting
-   nodes, or by running modified rippled that does not send all validation
+   nodes, or by running modified xrpld that does not send all validation
    messages),
 1. the correct outcomes.
 
@@ -566,7 +566,7 @@ For all the test cases, the correct outcomes are verified by examining logs. We
 will grep the log to see if the correct negative UNLs are generated, and whether
 or not the network is making progress when it should be. The ripdtop tool will
 be helpful for monitoring validators' states and ledger progress. Some of the
-timing parameters of rippled will be changed to have faster ledger time. Most if
+timing parameters of xrpld will be changed to have faster ledger time. Most if
 not all test cases do not need client transactions.
 
 For example, the test cases for the prototype:
@@ -583,7 +583,7 @@ For example, the test cases for the prototype:
 
 We considered testing with the current unit test framework, specifically the
 [Consensus Simulation
-Framework](https://github.com/ripple/rippled/blob/develop/src/test/csf/README.md)
+Framework](https://github.com/XRPLF/rippled/blob/develop/src/test/csf/README.md)
 (CSF). However, the CSF currently can only test the generic consensus algorithm
 as in the paper: [Analysis of the XRP Ledger Consensus
 Protocol](https://arxiv.org/abs/1802.07242).

docs/0001-negative-unl/negativeUNLSqDiagram.puml

@@ -4,7 +4,7 @@ skinparam sequenceArrowThickness 2
 skinparam roundcorner 20
 skinparam maxmessagesize 160
 
-actor "Rippled Start" as RS
+actor "Xrpld Start" as RS
 participant "Timer" as T
 participant "NetworkOPs" as NOP
 participant "ValidatorList" as VL #lightgreen

docs/Docker.md

@@ -1,5 +1,5 @@
-# `rippled` Docker Image
+# `xrpld` Docker Image
 
 - Some info relating to Docker containers can be found here: [../Builds/containers](../Builds/containers)
-- Images for building and testing rippled can be found here: [thejohnfreeman/rippled-docker](https://github.com/thejohnfreeman/rippled-docker/)
-  - These images do not have rippled. They have all the tools necessary to build rippled.
+- Images for building and testing xrpld can be found here: [thejohnfreeman/rippled-docker](https://github.com/thejohnfreeman/rippled-docker/)
+  - These images do not have xrpld. They have all the tools necessary to build xrpld.

docs/Doxyfile

@@ -2,7 +2,7 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = "rippled"
+PROJECT_NAME           = "xrpld"
 PROJECT_NUMBER         =
 PROJECT_BRIEF          =
 PROJECT_LOGO           =

docs/HeapProfiling.md

@@ -1,4 +1,4 @@
-## Heap profiling of rippled with jemalloc
+## Heap profiling of xrpld with jemalloc
 
 The jemalloc library provides a good API for doing heap analysis,
 including a mechanism to dump a description of the heap from within the
@@ -7,26 +7,26 @@ activity in general, as well as how to acquire the software, are available on
 the jemalloc site:
 [https://github.com/jemalloc/jemalloc/wiki/Use-Case:-Heap-Profiling](https://github.com/jemalloc/jemalloc/wiki/Use-Case:-Heap-Profiling)
 
-jemalloc is acquired separately from rippled, and is not affiliated
+jemalloc is acquired separately from xrpld, and is not affiliated
 with Ripple Labs. If you compile and install jemalloc from the
 source release with default options, it will install the library and header
 under `/usr/local/lib` and `/usr/local/include`, respectively. Heap
-profiling has been tested with rippled on a Linux platform. It should
-work on platforms on which both rippled and jemalloc are available.
+profiling has been tested with xrpld on a Linux platform. It should
+work on platforms on which both xrpld and jemalloc are available.
 
-To link rippled with jemalloc, the argument
+To link xrpld with jemalloc, the argument
 `profile-jemalloc=<jemalloc_dir>` is provided after the optional target.
 The `<jemalloc_dir>` argument should be the same as that of the
 `--prefix` parameter passed to the jemalloc configure script when building.
 
 ## Examples:
 
-Build rippled with jemalloc library under /usr/local/lib and
+Build xrpld with jemalloc library under /usr/local/lib and
 header under /usr/local/include:
 
     $ scons profile-jemalloc=/usr/local
 
-Build rippled using clang with the jemalloc library under /opt/local/lib
+Build xrpld using clang with the jemalloc library under /opt/local/lib
 and header under /opt/local/include:
 
     $ scons clang profile-jemalloc=/opt/local

docs/README.md

@@ -1,61 +0,0 @@
-# Building documentation
-
-## Dependencies
-
-Install these dependencies:
-
-- [Doxygen](http://www.doxygen.nl): All major platforms have [official binary
-  distributions](http://www.doxygen.nl/download.html#srcbin), or you can
-  build from [source](http://www.doxygen.nl/download.html#srcbin).
-  - MacOS: We recommend installing via Homebrew: `brew install doxygen`.
-    The executable will be installed in `/usr/local/bin` which is already
-    in the default `PATH`.
-
-    If you use the official binary distribution, then you'll need to make
-    Doxygen available to your command line. You can do this by adding
-    a symbolic link from `/usr/local/bin` to the `doxygen` executable. For
-    example,
-
-    ```
-    $ ln -s /Applications/Doxygen.app/Contents/Resources/doxygen /usr/local/bin/doxygen
-    ```
-
-- [PlantUML](http://plantuml.com):
-  1. Install a functioning Java runtime, if you don't already have one.
-  2. Download [`plantuml.jar`](http://sourceforge.net/projects/plantuml/files/plantuml.jar/download).
-
-- [Graphviz](https://www.graphviz.org):
-  - Linux: Install from your package manager.
-  - Windows: Use an [official installer](https://graphviz.gitlab.io/_pages/Download/Download_windows.html).
-  - MacOS: Install via Homebrew: `brew install graphviz`.
-
-## Docker
-
-Instead of installing the above dependencies locally, you can use the official
-build environment Docker image, which has all of them installed already.
-
-1. Install [Docker](https://docs.docker.com/engine/installation/)
-2. Pull the image:
-
-```
-sudo docker pull rippleci/rippled-ci-builder:2944b78d22db
-```
-
-3. Run the image from the project folder:
-
-```
-sudo docker run -v $PWD:/opt/rippled --rm rippleci/rippled-ci-builder:2944b78d22db
-```
-
-## Build
-
-There is a `docs` target in the CMake configuration.
-
-```
-mkdir build
-cd build
-cmake -Donly_docs=ON ..
-cmake --build . --target docs --parallel
-```
-
-The output will be in `build/docs/html`.