Clean up scripts

.clang-format

@@ -37,7 +37,7 @@ BinPackParameters: false
 BreakBeforeBinaryOperators: false
 BreakBeforeTernaryOperators: true
 BreakConstructorInitializersBeforeComma: true
-ColumnLimit: 100
+ColumnLimit: 80
 CommentPragmas: "^ IWYU pragma:"
 ConstructorInitializerAllOnOneLineOrOnePerLine: true
 ConstructorInitializerIndentWidth: 4

.clang-tidy

@@ -1,202 +0,0 @@
----
-Checks: "-*,
-  bugprone-argument-comment,
-  bugprone-assert-side-effect,
-  bugprone-bad-signal-to-kill-thread,
-  bugprone-bool-pointer-implicit-conversion,
-  bugprone-casting-through-void,
-  bugprone-chained-comparison,
-  bugprone-compare-pointer-to-member-virtual-function,
-  bugprone-copy-constructor-init,
-  bugprone-dangling-handle,
-  bugprone-dynamic-static-initializers,
-  bugprone-empty-catch,
-  bugprone-fold-init-type,
-  bugprone-forward-declaration-namespace,
-  bugprone-inaccurate-erase,
-  bugprone-inc-dec-in-conditions,
-  bugprone-incorrect-enable-if,
-  bugprone-incorrect-roundings,
-  bugprone-infinite-loop,
-  bugprone-integer-division,
-  bugprone-lambda-function-name,
-  bugprone-macro-parentheses,
-  bugprone-macro-repeated-side-effects,
-  bugprone-misplaced-operator-in-strlen-in-alloc,
-  bugprone-misplaced-pointer-arithmetic-in-alloc,
-  bugprone-misplaced-widening-cast,
-  bugprone-move-forwarding-reference,
-  bugprone-multi-level-implicit-pointer-conversion,
-  bugprone-multiple-new-in-one-expression,
-  bugprone-multiple-statement-macro,
-  bugprone-no-escape,
-  bugprone-non-zero-enum-to-bool-conversion,
-  bugprone-optional-value-conversion,
-  bugprone-parent-virtual-call,
-  bugprone-pointer-arithmetic-on-polymorphic-object,
-  bugprone-posix-return,
-  bugprone-redundant-branch-condition,
-  bugprone-reserved-identifier,
-  bugprone-return-const-ref-from-parameter,
-  bugprone-shared-ptr-array-mismatch,
-  bugprone-signal-handler,
-  bugprone-signed-char-misuse,
-  bugprone-sizeof-container,
-  bugprone-sizeof-expression,
-  bugprone-spuriously-wake-up-functions,
-  bugprone-standalone-empty,
-  bugprone-string-constructor,
-  bugprone-string-integer-assignment,
-  bugprone-string-literal-with-embedded-nul,
-  bugprone-stringview-nullptr,
-  bugprone-suspicious-enum-usage,
-  bugprone-suspicious-include,
-  bugprone-suspicious-memory-comparison,
-  bugprone-suspicious-memset-usage,
-  bugprone-suspicious-missing-comma,
-  bugprone-suspicious-realloc-usage,
-  bugprone-suspicious-semicolon,
-  bugprone-suspicious-string-compare,
-  bugprone-suspicious-stringview-data-usage,
-  bugprone-swapped-arguments,
-  bugprone-terminating-continue,
-  bugprone-throw-keyword-missing,
-  bugprone-too-small-loop-variable,
-  bugprone-undefined-memory-manipulation,
-  bugprone-undelegated-constructor,
-  bugprone-unhandled-exception-at-new,
-  bugprone-unhandled-self-assignment,
-  bugprone-unique-ptr-array-mismatch,
-  bugprone-unsafe-functions,
-  bugprone-unused-raii,
-  bugprone-unused-local-non-trivial-variable,
-  bugprone-virtual-near-miss,
-  cppcoreguidelines-no-suspend-with-lock,
-  cppcoreguidelines-virtual-class-destructor,
-  hicpp-ignored-remove-result,
-  misc-definitions-in-headers,
-  misc-header-include-cycle,
-  misc-misplaced-const,
-  misc-static-assert,
-  misc-throw-by-value-catch-by-reference,
-  misc-unused-alias-decls,
-  misc-unused-using-decls,
-  readability-duplicate-include,
-  readability-enum-initial-value,
-  readability-misleading-indentation,
-  readability-non-const-parameter,
-  readability-redundant-declaration,
-  readability-reference-to-constructed-temporary,
-  modernize-deprecated-headers,
-  modernize-make-shared,
-  modernize-make-unique,
-  performance-implicit-conversion-in-loop,
-  performance-move-constructor-init,
-  performance-trivially-destructible
-  "
-# ---
-# checks that have some issues that need to be resolved:
-#
-# bugprone-crtp-constructor-accessibility,
-# bugprone-move-forwarding-reference,
-# bugprone-switch-missing-default-case,
-# bugprone-unused-raii,
-# bugprone-unused-return-value,
-# bugprone-use-after-move,
-#
-# cppcoreguidelines-misleading-capture-default-by-value,
-# cppcoreguidelines-init-variables,
-# cppcoreguidelines-pro-type-member-init,
-# cppcoreguidelines-pro-type-static-cast-downcast,
-# cppcoreguidelines-use-default-member-init,
-# cppcoreguidelines-rvalue-reference-param-not-moved,
-#
-# llvm-namespace-comment,
-# misc-const-correctness,
-# misc-include-cleaner,
-# misc-redundant-expression,
-#
-# readability-avoid-nested-conditional-operator,
-# readability-avoid-return-with-void-value,
-# readability-braces-around-statements,
-# readability-container-contains,
-# readability-container-size-empty,
-# readability-convert-member-functions-to-static,
-# readability-const-return-type,
-# readability-else-after-return,
-# readability-implicit-bool-conversion,
-# readability-inconsistent-declaration-parameter-name,
-# readability-identifier-naming,
-# readability-make-member-function-const,
-# readability-math-missing-parentheses,
-# readability-redundant-inline-specifier,
-# readability-redundant-member-init,
-# readability-redundant-casting,
-# readability-redundant-string-init,
-# readability-simplify-boolean-expr,
-# readability-static-definition-in-anonymous-namespace,
-# readability-suspicious-call-argument,
-# readability-use-std-min-max,
-# readability-static-accessed-through-instance,
-#
-# 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,
-# ---
-#
-CheckOptions:
-  #   readability-braces-around-statements.ShortStatementLines: 2
-  #   readability-identifier-naming.MacroDefinitionCase: UPPER_CASE
-  #   readability-identifier-naming.ClassCase: CamelCase
-  #   readability-identifier-naming.StructCase: CamelCase
-  #   readability-identifier-naming.UnionCase: CamelCase
-  #   readability-identifier-naming.EnumCase: CamelCase
-  #   readability-identifier-naming.EnumConstantCase: CamelCase
-  #   readability-identifier-naming.ScopedEnumConstantCase: CamelCase
-  #   readability-identifier-naming.GlobalConstantCase: UPPER_CASE
-  #   readability-identifier-naming.GlobalConstantPrefix: "k"
-  #   readability-identifier-naming.GlobalVariableCase: CamelCase
-  #   readability-identifier-naming.GlobalVariablePrefix: "g"
-  #   readability-identifier-naming.ConstexprFunctionCase: camelBack
-  #   readability-identifier-naming.ConstexprMethodCase: camelBack
-  #   readability-identifier-naming.ClassMethodCase: camelBack
-  #   readability-identifier-naming.ClassMemberCase: camelBack
-  #   readability-identifier-naming.ClassConstantCase: UPPER_CASE
-  #   readability-identifier-naming.ClassConstantPrefix: "k"
-  #   readability-identifier-naming.StaticConstantCase: UPPER_CASE
-  #   readability-identifier-naming.StaticConstantPrefix: "k"
-  #   readability-identifier-naming.StaticVariableCase: UPPER_CASE
-  #   readability-identifier-naming.StaticVariablePrefix: "k"
-  #   readability-identifier-naming.ConstexprVariableCase: UPPER_CASE
-  #   readability-identifier-naming.ConstexprVariablePrefix: "k"
-  #   readability-identifier-naming.LocalConstantCase: camelBack
-  #   readability-identifier-naming.LocalVariableCase: camelBack
-  #   readability-identifier-naming.TemplateParameterCase: CamelCase
-  #   readability-identifier-naming.ParameterCase: camelBack
-  #   readability-identifier-naming.FunctionCase: camelBack
-  #   readability-identifier-naming.MemberCase: camelBack
-  #   readability-identifier-naming.PrivateMemberSuffix: _
-  #   readability-identifier-naming.ProtectedMemberSuffix: _
-  #   readability-identifier-naming.PublicMemberSuffix: ""
-  #   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'
-#
-# HeaderFilterRegex: '^.*/(src|tests)/.*\.(h|hpp)$'
-WarningsAsErrors: "*"

.codecov.yml

@@ -32,7 +32,9 @@ parsers:
 slack_app: false
 
 ignore:
-  - "src/test/"
-  - "src/tests/"
+  - ".github/scripts/"
   - "include/xrpl/beast/test/"
   - "include/xrpl/beast/unit_test/"
+  - "src/test/"
+  - "src/tests/"
+  - "tests/"

.gersemi/definitions.cmake

@@ -1,98 +0,0 @@
-# Custom CMake command definitions for gersemi formatting.
-# These stubs teach gersemi the signatures of project-specific commands
-# so it can format their invocations correctly.
-
-function(git_branch branch_val)
-endfunction()
-
-function(isolate_headers target A B scope)
-endfunction()
-
-function(create_symbolic_link target link)
-endfunction()
-
-function(xrpl_add_test name)
-endfunction()
-
-macro(exclude_from_default target_)
-endmacro()
-
-macro(exclude_if_included target_)
-endmacro()
-
-function(target_protobuf_sources target prefix)
-    set(options APPEND_PATH DESCRIPTORS)
-    set(oneValueArgs
-        LANGUAGE
-        OUT_VAR
-        EXPORT_MACRO
-        TARGET
-        PROTOC_OUT_DIR
-        PLUGIN
-        PLUGIN_OPTIONS
-        PROTOC_EXE
-    )
-    set(multiValueArgs
-        PROTOS
-        IMPORT_DIRS
-        GENERATE_EXTENSIONS
-        PROTOC_OPTIONS
-        DEPENDENCIES
-    )
-    cmake_parse_arguments(
-        THIS_FUNCTION_PREFIX
-        "${options}"
-        "${oneValueArgs}"
-        "${multiValueArgs}"
-        ${ARGN}
-    )
-endfunction()
-
-function(add_module parent name)
-endfunction()
-
-function(target_link_modules parent scope)
-endfunction()
-
-function(setup_target_for_coverage_gcovr)
-    set(options NONE)
-    set(oneValueArgs BASE_DIRECTORY NAME FORMAT)
-    set(multiValueArgs EXCLUDE EXECUTABLE EXECUTABLE_ARGS DEPENDENCIES)
-    cmake_parse_arguments(
-        THIS_FUNCTION_PREFIX
-        "${options}"
-        "${oneValueArgs}"
-        "${multiValueArgs}"
-        ${ARGN}
-    )
-endfunction()
-
-function(add_code_coverage_to_target name scope)
-endfunction()
-
-function(verbose_find_path variable name)
-    set(options
-        NO_CACHE
-        REQUIRED
-        OPTIONAL
-        NO_DEFAULT_PATH
-        NO_PACKAGE_ROOT_PATH
-        NO_CMAKE_PATH
-        NO_CMAKE_ENVIRONMENT_PATH
-        NO_SYSTEM_ENVIRONMENT_PATH
-        NO_CMAKE_SYSTEM_PATH
-        NO_CMAKE_INSTALL_PREFIX
-        CMAKE_FIND_ROOT_PATH_BOTH
-        ONLY_CMAKE_FIND_ROOT_PATH
-        NO_CMAKE_FIND_ROOT_PATH
-    )
-    set(oneValueArgs REGISTRY_VIEW VALIDATOR DOC)
-    set(multiValueArgs NAMES HINTS PATHS PATH_SUFFIXES)
-    cmake_parse_arguments(
-        THIS_FUNCTION_PREFIX
-        "${options}"
-        "${oneValueArgs}"
-        "${multiValueArgs}"
-        ${ARGN}
-    )
-endfunction()

.gersemirc

@@ -1 +0,0 @@
-definitions: [.gersemi]

.gitattributes

@@ -1,6 +1,5 @@
 # Set default behaviour, in case users don't have core.autocrlf set.
 #* text=auto
-# cspell: disable
 
 # Visual Studio
 *.sln       text eol=crlf

.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Allow anyone to review any change by default.
+*
+
+# Require the rpc-reviewers team to review changes to the rpc code.
+include/xrpl/protocol/ @xrplf/rpc-reviewers
+src/libxrpl/protocol/ @xrplf/rpc-reviewers
+src/xrpld/rpc/ @xrplf/rpc-reviewers
+src/xrpld/app/misc/ @xrplf/rpc-reviewers

.github/actions/build-deps/action.yml

@@ -18,10 +18,6 @@ inputs:
     description: "The logging verbosity."
     required: false
     default: "verbose"
-  sanitizers:
-    description: "The sanitizers to enable."
-    required: false
-    default: ""
 
 runs:
   using: composite
@@ -33,11 +29,9 @@ runs:
         BUILD_OPTION: ${{ inputs.force_build == 'true' && '*' || 'missing' }}
         BUILD_TYPE: ${{ inputs.build_type }}
         LOG_VERBOSITY: ${{ inputs.log_verbosity }}
-        SANITIZERS: ${{ inputs.sanitizers }}
       run: |
         echo 'Installing dependencies.'
         conan install \
-          --profile ci \
           --build="${BUILD_OPTION}" \
           --options:host='&:tests=True' \
           --options:host='&:xrpld=True' \

.github/actions/generate-version/action.yml

@@ -1,44 +0,0 @@
-name: Generate build version number
-description: "Generate build version number."
-
-outputs:
-  version:
-    description: "The generated build version number."
-    value: ${{ steps.version.outputs.version }}
-
-runs:
-  using: composite
-  steps:
-    # When a tag is pushed, the version is used as-is.
-    - name: Generate version for tag event
-      if: ${{ github.event_name == 'tag' }}
-      shell: bash
-      env:
-        VERSION: ${{ github.ref_name }}
-      run: echo "VERSION=${VERSION}" >> "${GITHUB_ENV}"
-
-    # When a tag is not pushed, then the version (e.g. 1.2.3-b0) is extracted
-    # from the BuildInfo.cpp file and the shortened commit hash appended to it.
-    # We use a plus sign instead of a hyphen because Conan recipe versions do
-    # not support two hyphens.
-    - name: Generate version for non-tag event
-      if: ${{ github.event_name != 'tag' }}
-      shell: bash
-      run: |
-        echo 'Extracting version from BuildInfo.cpp.'
-        VERSION="$(cat src/libxrpl/protocol/BuildInfo.cpp | grep "versionString =" | awk -F '"' '{print $2}')"
-        if [[ -z "${VERSION}" ]]; then
-          echo 'Unable to extract version from BuildInfo.cpp.'
-          exit 1
-        fi
-
-        echo 'Appending shortened commit hash to version.'
-        SHA='${{ github.sha }}'
-        VERSION="${VERSION}+${SHA:0:7}"
-
-        echo "VERSION=${VERSION}" >> "${GITHUB_ENV}"
-
-    - name: Output version
-      id: version
-      shell: bash
-      run: echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"

.github/actions/print-env/action.yml

@@ -11,6 +11,12 @@ runs:
         echo 'Checking environment variables.'
         set
 
+        echo 'Checking CMake version.'
+        cmake --version
+
+        echo 'Checking Conan version.'
+        conan --version
+
     - name: Check configuration (Linux and macOS)
       if: ${{ runner.os == 'Linux' || runner.os == 'macOS' }}
       shell: bash
@@ -21,23 +27,17 @@ runs:
         echo 'Checking environment variables.'
         env | sort
 
+        echo 'Checking CMake version.'
+        cmake --version
+
         echo 'Checking compiler version.'
         ${{ runner.os == 'Linux' && '${CC}' || 'clang' }} --version
 
+        echo 'Checking Conan version.'
+        conan --version
+
         echo 'Checking Ninja version.'
         ninja --version
 
         echo 'Checking nproc version.'
         nproc --version
-
-    - name: Check configuration (all)
-      shell: bash
-      run: |
-        echo 'Checking Ccache version.'
-        ccache --version
-
-        echo 'Checking CMake version.'
-        cmake --version
-
-        echo 'Checking Conan version.'
-        conan --version

.github/actions/setup-conan/action.yml

@@ -2,11 +2,11 @@ name: Setup Conan
 description: "Set up Conan configuration, profile, and remote."
 
 inputs:
-  remote_name:
+  conan_remote_name:
     description: "The name of the Conan remote to use."
     required: false
     default: xrplf
-  remote_url:
+  conan_remote_url:
     description: "The URL of the Conan endpoint to use."
     required: false
     default: https://conan.ripplex.io
@@ -28,19 +28,19 @@ runs:
       shell: bash
       run: |
         echo 'Installing profile.'
-        conan config install conan/profiles/ -tf $(conan config home)/profiles/
+        conan config install conan/profiles/default -tf $(conan config home)/profiles/
 
         echo 'Conan profile:'
-        conan profile show --profile ci
+        conan profile show
 
     - name: Set up Conan remote
       shell: bash
       env:
-        REMOTE_NAME: ${{ inputs.remote_name }}
-        REMOTE_URL: ${{ inputs.remote_url }}
+        CONAN_REMOTE_NAME: ${{ inputs.conan_remote_name }}
+        CONAN_REMOTE_URL: ${{ inputs.conan_remote_url }}
       run: |
-        echo "Adding Conan remote '${REMOTE_NAME}' at '${REMOTE_URL}'."
-        conan remote add --index 0 --force "${REMOTE_NAME}" "${REMOTE_URL}"
+        echo "Adding Conan remote '${CONAN_REMOTE_NAME}' at '${CONAN_REMOTE_URL}'."
+        conan remote add --index 0 --force "${CONAN_REMOTE_NAME}" "${CONAN_REMOTE_URL}"
 
         echo 'Listing Conan remotes.'
         conan remote list

.github/dependabot.yml

@@ -1,56 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: github-actions
-    directory: /
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop
-
-  - package-ecosystem: github-actions
-    directory: .github/actions/build-deps/
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop
-
-  - package-ecosystem: github-actions
-    directory: .github/actions/generate-version/
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop
-
-  - package-ecosystem: github-actions
-    directory: .github/actions/print-env/
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop
-
-  - package-ecosystem: github-actions
-    directory: .github/actions/setup-conan/
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop

.github/scripts/levelization/README.md

@@ -81,10 +81,10 @@ It generates many files of [results](results):
 
 - `rawincludes.txt`: The raw dump of the `#includes`
 - `paths.txt`: A second dump grouping the source module
-  to the destination module, de-duped, and with frequency counts.
+  to the destination module, deduped, and with frequency counts.
 - `includes/`: A directory where each file represents a module and
   contains a list of modules and counts that the module _includes_.
-- `included_by/`: Similar to `includes/`, but the other way around. Each
+- `includedby/`: Similar to `includes/`, but the other way around. Each
   file represents a module and contains a list of modules and counts
   that _include_ the module.
 - [`loops.txt`](results/loops.txt): A list of direct loops detected

.github/scripts/levelization/generate.sh

@@ -29,7 +29,7 @@ pushd results
 oldifs=${IFS}
 IFS=:
 mkdir includes
-mkdir included_by
+mkdir includedby
 echo Build levelization paths
 exec 3< ${includes} # open rawincludes.txt for input
 while read -r -u 3 file include
@@ -59,7 +59,7 @@ do
         echo $level $includelevel | tee -a paths.txt
     fi
 done
-echo Sort and deduplicate paths
+echo Sort and dedup paths
 sort -ds paths.txt | uniq -c | tee sortedpaths.txt
 mv sortedpaths.txt paths.txt
 exec 3>&- #close fd 3
@@ -71,7 +71,7 @@ exec 4<paths.txt # open paths.txt for input
 while read -r -u 4 count level include
 do
     echo ${include} ${count} | tee -a includes/${level}
-    echo ${level} ${count} | tee -a included_by/${include}
+    echo ${level} ${count} | tee -a includedby/${include}
 done
 exec 4>&- #close fd 4
 

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

@@ -4,11 +4,14 @@ Loop: test.jtx test.toplevel
 Loop: test.jtx test.unit_test
   test.unit_test == test.jtx
 
+Loop: xrpld.app xrpld.core
+  xrpld.app > xrpld.core
+
 Loop: xrpld.app xrpld.overlay
-  xrpld.overlay ~= xrpld.app
+  xrpld.overlay > xrpld.app
 
 Loop: xrpld.app xrpld.peerfinder
-  xrpld.peerfinder == xrpld.app
+  xrpld.peerfinder ~= xrpld.app
 
 Loop: xrpld.app xrpld.rpc
   xrpld.rpc > xrpld.app
@@ -16,9 +19,6 @@ Loop: xrpld.app xrpld.rpc
 Loop: xrpld.app xrpld.shamap
   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

@@ -1,6 +1,4 @@
 libxrpl.basics > xrpl.basics
-libxrpl.conditions > xrpl.basics
-libxrpl.conditions > xrpl.conditions
 libxrpl.core > xrpl.basics
 libxrpl.core > xrpl.core
 libxrpl.crypto > xrpl.basics
@@ -19,29 +17,16 @@ libxrpl.nodestore > xrpl.protocol
 libxrpl.protocol > xrpl.basics
 libxrpl.protocol > xrpl.json
 libxrpl.protocol > xrpl.protocol
-libxrpl.rdb > xrpl.basics
-libxrpl.rdb > xrpl.rdb
 libxrpl.resource > xrpl.basics
 libxrpl.resource > xrpl.json
 libxrpl.resource > xrpl.resource
 libxrpl.server > xrpl.basics
 libxrpl.server > xrpl.json
 libxrpl.server > xrpl.protocol
-libxrpl.server > xrpl.rdb
 libxrpl.server > xrpl.server
 libxrpl.shamap > xrpl.basics
 libxrpl.shamap > xrpl.protocol
 libxrpl.shamap > xrpl.shamap
-libxrpl.telemetry > xrpl.basics
-libxrpl.telemetry > xrpl.telemetry
-libxrpl.tx > xrpl.basics
-libxrpl.tx > xrpl.conditions
-libxrpl.tx > xrpl.core
-libxrpl.tx > xrpl.json
-libxrpl.tx > xrpl.ledger
-libxrpl.tx > xrpl.protocol
-libxrpl.tx > xrpl.server
-libxrpl.tx > xrpl.tx
 test.app > test.jtx
 test.app > test.rpc
 test.app > test.toplevel
@@ -56,10 +41,7 @@ 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.tx
 test.basics > test.jtx
 test.basics > test.unit_test
 test.basics > xrpl.basics
@@ -69,7 +51,7 @@ test.basics > xrpl.json
 test.basics > xrpl.protocol
 test.beast > xrpl.basics
 test.conditions > xrpl.basics
-test.conditions > xrpl.conditions
+test.conditions > xrpld.conditions
 test.consensus > test.csf
 test.consensus > test.toplevel
 test.consensus > test.unit_test
@@ -78,7 +60,6 @@ test.consensus > xrpld.app
 test.consensus > xrpld.consensus
 test.consensus > xrpl.json
 test.consensus > xrpl.ledger
-test.consensus > xrpl.tx
 test.core > test.jtx
 test.core > test.toplevel
 test.core > test.unit_test
@@ -86,7 +67,6 @@ test.core > xrpl.basics
 test.core > xrpl.core
 test.core > xrpld.core
 test.core > xrpl.json
-test.core > xrpl.rdb
 test.core > xrpl.server
 test.csf > xrpl.basics
 test.csf > xrpld.consensus
@@ -95,7 +75,6 @@ test.csf > xrpl.protocol
 test.json > test.jtx
 test.json > xrpl.json
 test.jtx > xrpl.basics
-test.jtx > xrpl.core
 test.jtx > xrpld.app
 test.jtx > xrpld.core
 test.jtx > xrpld.rpc
@@ -105,7 +84,6 @@ test.jtx > xrpl.net
 test.jtx > xrpl.protocol
 test.jtx > xrpl.resource
 test.jtx > xrpl.server
-test.jtx > xrpl.tx
 test.ledger > test.jtx
 test.ledger > test.toplevel
 test.ledger > xrpl.basics
@@ -117,8 +95,8 @@ 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.rdb
 test.overlay > test.jtx
 test.overlay > test.toplevel
 test.overlay > test.unit_test
@@ -126,7 +104,6 @@ test.overlay > xrpl.basics
 test.overlay > xrpld.app
 test.overlay > xrpld.overlay
 test.overlay > xrpld.peerfinder
-test.overlay > xrpl.nodestore
 test.overlay > xrpl.protocol
 test.overlay > xrpl.shamap
 test.peerfinder > test.beast
@@ -151,11 +128,8 @@ test.rpc > xrpld.core
 test.rpc > xrpld.overlay
 test.rpc > xrpld.rpc
 test.rpc > xrpl.json
-test.rpc > xrpl.ledger
 test.rpc > xrpl.protocol
 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
@@ -174,64 +148,41 @@ test.toplevel > test.csf
 test.toplevel > xrpl.json
 test.unit_test > xrpl.basics
 tests.libxrpl > xrpl.basics
-tests.libxrpl > xrpl.core
-tests.libxrpl > xrpld.telemetry
 tests.libxrpl > xrpl.json
 tests.libxrpl > xrpl.net
-tests.libxrpl > xrpl.telemetry
-xrpl.conditions > xrpl.basics
-xrpl.conditions > xrpl.protocol
 xrpl.core > xrpl.basics
 xrpl.core > xrpl.json
-xrpl.core > xrpl.ledger
-xrpl.core > xrpl.protocol
 xrpl.json > xrpl.basics
 xrpl.ledger > xrpl.basics
 xrpl.ledger > xrpl.protocol
-xrpl.ledger > xrpl.server
-xrpl.ledger > xrpl.shamap
 xrpl.net > xrpl.basics
 xrpl.nodestore > xrpl.basics
 xrpl.nodestore > xrpl.protocol
 xrpl.protocol > xrpl.basics
 xrpl.protocol > xrpl.json
-xrpl.rdb > xrpl.basics
-xrpl.rdb > xrpl.core
-xrpl.rdb > xrpl.protocol
 xrpl.resource > xrpl.basics
 xrpl.resource > xrpl.json
 xrpl.resource > xrpl.protocol
 xrpl.server > xrpl.basics
-xrpl.server > xrpl.core
 xrpl.server > xrpl.json
 xrpl.server > xrpl.protocol
-xrpl.server > xrpl.rdb
-xrpl.server > xrpl.resource
-xrpl.server > xrpl.shamap
 xrpl.shamap > xrpl.basics
 xrpl.shamap > xrpl.nodestore
 xrpl.shamap > xrpl.protocol
-xrpl.telemetry > xrpl.basics
-xrpl.tx > xrpl.basics
-xrpl.tx > xrpl.core
-xrpl.tx > xrpl.ledger
-xrpl.tx > xrpl.protocol
 xrpld.app > test.unit_test
 xrpld.app > xrpl.basics
 xrpld.app > xrpl.core
+xrpld.app > xrpld.conditions
 xrpld.app > xrpld.consensus
-xrpld.app > xrpld.core
 xrpld.app > xrpl.json
 xrpld.app > xrpl.ledger
 xrpld.app > xrpl.net
 xrpld.app > xrpl.nodestore
 xrpld.app > xrpl.protocol
-xrpld.app > xrpl.rdb
 xrpld.app > xrpl.resource
-xrpld.app > xrpl.server
 xrpld.app > xrpl.shamap
-xrpld.app > xrpl.telemetry
-xrpld.app > xrpl.tx
+xrpld.conditions > xrpl.basics
+xrpld.conditions > xrpl.protocol
 xrpld.consensus > xrpl.basics
 xrpld.consensus > xrpl.json
 xrpld.consensus > xrpl.protocol
@@ -240,43 +191,29 @@ 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.core
 xrpld.overlay > xrpld.peerfinder
-xrpld.overlay > xrpld.telemetry
 xrpld.overlay > xrpl.json
 xrpld.overlay > xrpl.protocol
-xrpld.overlay > xrpl.rdb
 xrpld.overlay > xrpl.resource
 xrpld.overlay > xrpl.server
-xrpld.overlay > xrpl.tx
 xrpld.peerfinder > xrpl.basics
 xrpld.peerfinder > xrpld.core
 xrpld.peerfinder > xrpl.protocol
-xrpld.peerfinder > xrpl.rdb
 xrpld.perflog > xrpl.basics
 xrpld.perflog > xrpl.core
 xrpld.perflog > xrpld.rpc
-xrpld.perflog > xrpld.telemetry
 xrpld.perflog > xrpl.json
 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
 xrpld.rpc > xrpl.nodestore
 xrpld.rpc > xrpl.protocol
-xrpld.rpc > xrpl.rdb
 xrpld.rpc > xrpl.resource
 xrpld.rpc > xrpl.server
-xrpld.rpc > xrpl.tx
 xrpld.shamap > xrpl.shamap
-xrpld.telemetry > xrpl.basics
-xrpld.telemetry > xrpl.core
-xrpld.telemetry > xrpl.nodestore
-xrpld.telemetry > xrpl.server
-xrpld.telemetry > xrpl.telemetry

.github/scripts/rename/README.md

@@ -19,7 +19,7 @@ run from the repository root.
 1. `.github/scripts/rename/definitions.sh`: This script will rename all
    definitions, such as include guards, from `RIPPLE_XXX` and `RIPPLED_XXX` to
    `XRPL_XXX`.
-2. `.github/scripts/rename/copyright.sh`: This script will remove superfluous
+2. `.github/scripts/rename/copyright.sh`: This script will remove superflous
    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
@@ -31,9 +31,6 @@ run from the repository root.
    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
-   filename will still be accepted.
 
 You can run all these scripts from the repository root as follows:
 
@@ -43,5 +40,4 @@ You can run all these scripts from the repository root as follows:
 ./.github/scripts/rename/cmake.sh .
 ./.github/scripts/rename/binary.sh .
 ./.github/scripts/rename/namespace.sh .
-./.github/scripts/rename/config.sh .
 ```

.github/scripts/rename/config.sh

@@ -1,72 +0,0 @@
-#!/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 the config from `rippled.cfg` to `xrpld.cfg`, and updates
-# the code accordingly. The old filename will still be accepted.
-# Usage: .github/scripts/rename/config.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}
-
-# Add the xrpld.cfg to the .gitignore.
-if ! grep -q 'xrpld.cfg' .gitignore; then
-  ${SED_COMMAND} -i '/rippled.cfg/a\
-/xrpld.cfg' .gitignore
-fi
-
-# Rename the files.
-if [ -e rippled.cfg ]; then
-  mv rippled.cfg xrpld.cfg
-fi
-if [ -e cfg/rippled-example.cfg ]; then
-  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}"
-
-  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
-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
-
-# Restore an URL.
-${SED_COMMAND} -i 's/connect-your-xrpld-to-the-xrp-test-net.html/connect-your-rippled-to-the-xrp-test-net.html/g' cfg/xrpld-example.cfg
-
-popd
-echo "Renaming complete."

.github/scripts/rename/copyright.sh

@@ -50,11 +50,11 @@ for DIRECTORY in "${DIRECTORIES[@]}"; do
       # 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@^.*Copyright.+(Ripple|Bougalis|Falco|Hinnant|Null|Ritchford|XRPLF).+PERFORMANCE OF THIS SOFTWARE\.\n\*/\n+@@' "${FILE}"
       ${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
+      ${SED_COMMAND} -z -i -E 's@^//\n// Copyright.+Falco \(vinnie dot falco at gmail dot com\)\n//\n+@@' "${FILE}"
   done
 done
 
@@ -83,16 +83,16 @@ 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
 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
 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
 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
 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
 fi
 
 # Restore newlines and tabs in string literals in the affected file.

.github/scripts/rename/include.sh

@@ -1,30 +0,0 @@
-#!/bin/bash
-
-# Exit the script as soon as an error occurs.
-set -e
-
-# This script checks whether there are no new include guards introduced by a new
-# PR, as header files should use "#pragma once" instead. The script assumes any
-# include guards will use "XRPL_" as prefix.
-# Usage: .github/scripts/rename/include.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
-
-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
-    fi
-done
-echo "Checking complete."

.github/scripts/strategy-matrix/README.md

@@ -0,0 +1,118 @@
+# Strategy Matrix
+
+The scripts in this directory will generate a strategy matrix for GitHub Actions
+CI, depending on the trigger that caused the workflow to run and the platform
+specified.
+
+There are several build, test, and publish settings that can be enabled for each
+configuration. The settings are combined in a Cartesian product to generate the
+full matrix, while filtering out any combinations not applicable to the trigger.
+
+## Platforms
+
+We support three platforms: Linux, macOS, and Windows.
+
+### Linux
+
+We support a variety of distributions (Debian, RHEL, and Ubuntu) and compilers
+(GCC and Clang) on Linux. As there are so many combinations, we don't run them
+all. Instead, we focus on a few key ones for PR commits and merges, while we run
+most of them on a scheduled or ad hoc basis.
+
+Some noteworthy configurations are:
+
+- The official release build is GCC 14 on Debian Bullseye.
+  - Although we generally enable assertions in release builds, we disable them
+    for the official release build.
+  - We publish .deb and .rpm packages for this build, as well as a Docker image.
+  - For PR commits we also publish packages and images for testing purposes.
+- Antithesis instrumentation is only supported on Clang 16+ on AMD64.
+  - We publish a Docker image for this build, but no packages.
+- Coverage reports are generated on Bullseye with GCC 15.
+  - It must be enabled for both commits (to show PR coverage) and merges (to
+    show default branch coverage).
+
+Note that we try to run pipelines equally across both AMD64 and ARM64, but in
+some cases we cannot build on ARM64:
+
+- All Clang 20+ builds on ARM64 are currently skipped due to a Boost build
+  error.
+- All RHEL builds on AMD64 are currently skipped due to a build failure that
+  needs further investigation.
+
+Also note that to create a Docker image we ideally build on both AMD64 and
+ARM64 to create a multi-arch image. Both configs should therefore be triggered
+by the same event. However, as the script outputs individual configs, the
+workflow must be able to run both builds separately and then merge the
+single-arch images afterward into a multi-arch image.
+
+### MacOS
+
+We support building on macOS, which uses the Apple Clang compiler and the ARM64
+architecture. We use default settings for all builds, and don't publish any
+packages or images.
+
+### Windows
+
+We also support building on Windows, which uses the MSVC compiler and the AMD64
+architecture. While we could build on ARM64, we have not yet found a suitable
+cloud machine to use as a GitHub runner. We use default settings for all builds,
+and don't publish any packages or images.
+
+## Triggers
+
+We have four triggers that can cause the workflow to run:
+
+- `commit`: A commit is pushed to a branch for which a pull request is open.
+- `merge`: A pull request is merged.
+- `label`: A label is added to a pull request.
+- `schedule`: The workflow is run on a scheduled basis.
+
+The `label` trigger is currently not used, but it is reserved for future use.
+
+The `schedule` trigger is used to run the workflow each weekday, and is also
+used for ad hoc testing via the `workflow_dispatch` event.
+
+### Dependencies
+
+The pipeline that is run for the `schedule` trigger will recompile and upload
+all Conan packages to the remote for each configuration that is enabled. In
+case any dependencies were added or updated in a recently merged PR, they will
+then be available in the remote for the following pipeline runs. It is therefore
+important that all configurations that are enabled for the `commit`, `merge`,
+and `label` triggers are also enabled for the `schedule` trigger. We run
+additional configurations in the `schedule` trigger that are not run for the
+other triggers, to get extra confidence that the codebase can compile and run on
+all supported platforms.
+
+#### Caveats
+
+There is some nuance here in that certain options affect the compilation of the
+dependencies, while others do not. This means that that same options need to be
+enabled for the `schedule` trigger as for the other triggers to ensure any
+dependency changes get cached in the Conan remote.
+
+- Build mode (`unity`): Does not affect the dependencies.
+- Build option (`coverage`, `voidstar`): Does not affect the dependencies.
+- Build option (`sanitizer asan`, `sanitizer tsan`): Affects the dependencies.
+- Build type (`debug`, `release`): Affects the dependencies.
+- Build type (`publish`): Same effect as `release` on the dependencies.
+- Test option (`reference fee`): Does not affect the dependencies.
+- Publish option (`package`, `image`): Does not affect the dependencies.
+
+## Usage
+
+Our GitHub CI pipeline uses the `generate.py` script to generate the matrix for
+the current workflow invocation. Naturally, the script can be run locally to
+generate the matrix for testing purposes, e.g.:
+
+```bash
+python3 generate.py --platform=linux --trigger=commit
+```
+
+If you want to pretty-print the output, you can pipe it to `jq` after stripping
+off the `matrix=` prefix, e.g.:
+
+```bash
+python3 generate.py --platform=linux --trigger=commit | cut -d= -f2- | jq
+```

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

@@ -1,333 +1,211 @@
 #!/usr/bin/env python3
 import argparse
+import dataclasses
 import itertools
-import json
-from dataclasses import dataclass
-from pathlib import Path
+from collections.abc import Iterator
 
-THIS_DIR = Path(__file__).parent.resolve()
+import linux
+import macos
+import windows
+from helpers.defs import *
+from helpers.enums import *
+from helpers.funcs import *
+from helpers.unique import *
+
+# The GitHub runner tags to use for the different architectures.
+RUNNER_TAGS = {
+    Arch.LINUX_AMD64: ["self-hosted", "Linux", "X64", "heavy"],
+    Arch.LINUX_ARM64: ["self-hosted", "Linux", "ARM64", "heavy-arm64"],
+    Arch.MACOS_ARM64: ["self-hosted", "macOS", "ARM64", "mac-runner-m1"],
+    Arch.WINDOWS_AMD64: ["self-hosted", "Windows", "devbox"],
+}
 
 
-@dataclass
-class Config:
-    architecture: list[dict]
-    os: list[dict]
-    build_type: list[str]
-    cmake_args: list[str]
+def generate_configs(distros: list[Distro], trigger: Trigger) -> list[Config]:
+    """Generate a strategy matrix for GitHub Actions CI.
+
+    Args:
+        distros: The distros to generate the matrix for.
+        trigger: The trigger that caused the workflow to run.
+
+    Returns:
+        list[Config]: The generated configurations.
+
+    Raises:
+        ValueError: If any of the required fields are empty or invalid.
+        TypeError: If any of the required fields are of the wrong type.
+
+    """
+
+    configs = []
+    for distro in distros:
+        for config in generate_config_for_distro(distro, trigger):
+            configs.append(config)
+
+    if not is_unique(configs):
+        raise ValueError("configs must be a list of unique Config")
+
+    return configs
 
 
-"""
-Generate a strategy matrix for GitHub Actions CI.
+def generate_config_for_distro(distro: Distro, trigger: Trigger) -> Iterator[Config]:
+    """Generate a strategy matrix for a specific distro.
 
-On each PR commit we will build a selection of Debian, RHEL, Ubuntu, MacOS, and
-Windows configurations, while upon merge into the develop or release branches,
-we will build all configurations, and test most of them.
+    Args:
+        distro: The distro to generate the matrix for.
+        trigger: The trigger that caused the workflow to run.
 
-We will further set additional CMake arguments as follows:
-- All builds will have the `tests`, `werr`, and `xrpld` options.
-- All builds will have the `wextra` option except for GCC 12 and Clang 16.
-- All release builds will have the `assert` option.
-- Certain Debian Bookworm configurations will change the reference fee, enable
-  codecov, and enable voidstar in PRs.
-"""
+    Yields:
+        Config: The next configuration to build.
 
+    Raises:
+        ValueError: If any of the required fields are empty or invalid.
+        TypeError: If any of the required fields are of the wrong type.
 
-def generate_strategy_matrix(all: bool, config: Config) -> list:
-    configurations = []
-    for architecture, os, build_type, cmake_args in itertools.product(
-        config.architecture, config.os, config.build_type, config.cmake_args
-    ):
-        # The default CMake target is 'all' for Linux and MacOS and 'install'
-        # for Windows, but it can get overridden for certain configurations.
-        cmake_target = "install" if os["distro_name"] == "windows" else "all"
-
-        # We build and test all configurations by default, except for Windows in
-        # Debug, because it is too slow, as well as when code coverage is
-        # enabled as that mode already runs the tests.
-        build_only = False
-        if os["distro_name"] == "windows" and build_type == "Debug":
-            build_only = True
-
-        # 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 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.
-            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 architecture["platform"] == "linux/amd64"
-                    ):
-                        cmake_args = f"-DUNIT_TEST_REFERENCE_FEE=500 {cmake_args}"
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-15"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-16"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        cmake_args = f"-Dvoidstar=ON {cmake_args}"
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-17"
-                        and build_type == "Release"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        cmake_args = f"-DUNIT_TEST_REFERENCE_FEE=1000 {cmake_args}"
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-20"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                if skip:
-                    continue
-
-            # RHEL:
-            # - 9 using GCC 12: Debug on linux/amd64.
-            # - 10 using Clang: Release on linux/amd64.
-            if os["distro_name"] == "rhel":
-                skip = True
-                if os["distro_version"] == "9":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-12"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                elif os["distro_version"] == "10":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-any"
-                        and build_type == "Release"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                if skip:
-                    continue
-
-            # Ubuntu:
-            # - Jammy using GCC 12: Debug on linux/arm64.
-            # - Noble using GCC 14: Release on linux/amd64.
-            # - Noble using Clang 18: Debug on linux/amd64.
-            # - Noble using Clang 19: Release on linux/arm64.
-            if os["distro_name"] == "ubuntu":
-                skip = True
-                if os["distro_version"] == "jammy":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-12"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/arm64"
-                    ):
-                        skip = False
-                elif os["distro_version"] == "noble":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-14"
-                        and build_type == "Release"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-18"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-19"
-                        and build_type == "Release"
-                        and architecture["platform"] == "linux/arm64"
-                    ):
-                        skip = False
-                if skip:
-                    continue
-
-            # MacOS:
-            # - Debug on macos/arm64.
-            if os["distro_name"] == "macos" and not (
-                build_type == "Debug" and architecture["platform"] == "macos/arm64"
-            ):
-                continue
-
-            # Windows:
-            # - Release on windows/amd64.
-            if os["distro_name"] == "windows" and not (
-                build_type == "Release" and architecture["platform"] == "windows/amd64"
-            ):
-                continue
-
-        # Additional CMake arguments.
-        cmake_args = f"{cmake_args} -Dtests=ON -Dwerr=ON -Dxrpld=ON"
-        if not f"{os['compiler_name']}-{os['compiler_version']}" in [
-            "gcc-12",
-            "clang-16",
-        ]:
-            cmake_args = f"{cmake_args} -Dwextra=ON"
-        if build_type == "Release":
-            cmake_args = f"{cmake_args} -Dassert=ON"
-
-        # We skip all RHEL on arm64 due to a build failure that needs further
-        # investigation.
-        if os["distro_name"] == "rhel" and architecture["platform"] == "linux/arm64":
+    """
+    for spec in distro.specs:
+        if trigger not in spec.triggers:
             continue
 
-        # We skip all clang 20+ on arm64 due to Boost build error.
-        if (
-            f"{os['compiler_name']}-{os['compiler_version']}"
-            in ["clang-20", "clang-21"]
-            and architecture["platform"] == "linux/arm64"
-        ):
-            continue
-
-        # Enable code coverage for Debian Bookworm using GCC 15 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 build_type == "Debug"
-            and architecture["platform"] == "linux/amd64"
-        ):
-            cmake_args = f"{cmake_args} -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0"
-
-        # Enable unity build for Ubuntu Jammy using GCC 12 in Debug on
-        # linux/amd64.
-        if (
-            f"{os['distro_name']}-{os['distro_version']}" == "ubuntu-jammy"
-            and f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-12"
-            and build_type == "Debug"
-            and architecture["platform"] == "linux/amd64"
-        ):
-            cmake_args = f"{cmake_args} -Dunity=ON"
-
-        # Generate a unique name for the configuration, e.g. macos-arm64-debug
-        # or debian-bookworm-gcc-12-amd64-release.
-        config_name = os["distro_name"]
-        if (n := os["distro_version"]) != "":
-            config_name += f"-{n}"
-        if (n := os["compiler_name"]) != "":
-            config_name += f"-{n}"
-        if (n := os["compiler_version"]) != "":
-            config_name += f"-{n}"
-        config_name += (
-            f"-{architecture['platform'][architecture['platform'].find('/')+1:]}"
+        os_name = distro.os_name
+        os_version = distro.os_version
+        compiler_name = distro.compiler_name
+        compiler_version = distro.compiler_version
+        image_sha = distro.image_sha
+        yield from generate_config_for_distro_spec(
+            os_name,
+            os_version,
+            compiler_name,
+            compiler_version,
+            image_sha,
+            spec,
+            trigger,
         )
-        config_name += f"-{build_type.lower()}"
-        if "-Dcoverage=ON" in cmake_args:
-            config_name += "-coverage"
-        if "-Dunity=ON" in cmake_args:
-            config_name += "-unity"
-
-        # 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.
-            configurations.append(
-                {
-                    "config_name": config_name + "-asan-ubsan",
-                    "cmake_args": cmake_args,
-                    "cmake_target": cmake_target,
-                    "build_only": build_only,
-                    "build_type": build_type,
-                    "os": os,
-                    "architecture": architecture,
-                    "sanitizers": "address,undefinedbehavior",
-                }
-            )
-            # TSAN is deactivated due to seg faults with latest compilers.
-            activate_tsan = False
-            if activate_tsan:
-                configurations.append(
-                    {
-                        "config_name": config_name + "-tsan-ubsan",
-                        "cmake_args": cmake_args,
-                        "cmake_target": cmake_target,
-                        "build_only": build_only,
-                        "build_type": build_type,
-                        "os": os,
-                        "architecture": architecture,
-                        "sanitizers": "thread,undefinedbehavior",
-                    }
-                )
-        else:
-            configurations.append(
-                {
-                    "config_name": config_name,
-                    "cmake_args": cmake_args,
-                    "cmake_target": cmake_target,
-                    "build_only": build_only,
-                    "build_type": build_type,
-                    "os": os,
-                    "architecture": architecture,
-                    "sanitizers": "",
-                }
-            )
-
-    return configurations
 
 
-def read_config(file: Path) -> Config:
-    config = json.loads(file.read_text())
-    if (
-        config["architecture"] is None
-        or config["os"] is None
-        or config["build_type"] is None
-        or config["cmake_args"] is None
+def generate_config_for_distro_spec(
+    os_name: str,
+    os_version: str,
+    compiler_name: str,
+    compiler_version: str,
+    image_sha: str,
+    spec: Spec,
+    trigger: Trigger,
+) -> Iterator[Config]:
+    """Generate a strategy matrix for a specific distro and spec.
+
+    Args:
+        os_name: The OS name.
+        os_version: The OS version.
+        compiler_name: The compiler name.
+        compiler_version: The compiler version.
+        image_sha: The image SHA.
+        spec: The spec to generate the matrix for.
+        trigger: The trigger that caused the workflow to run.
+
+    Yields:
+        Config: The next configuration to build.
+
+    """
+
+    for trigger_, arch, build_mode, build_type in itertools.product(
+        spec.triggers, spec.archs, spec.build_modes, spec.build_types
     ):
-        raise Exception("Invalid configuration file.")
+        if trigger_ != trigger:
+            continue
 
-    return Config(**config)
+        build_option = spec.build_option
+        test_option = spec.test_option
+        publish_option = spec.publish_option
+
+        # Determine the configuration name.
+        config_name = generate_config_name(
+            os_name,
+            os_version,
+            compiler_name,
+            compiler_version,
+            arch,
+            build_type,
+            build_mode,
+            build_option,
+        )
+
+        # Determine the CMake arguments.
+        cmake_args = generate_cmake_args(
+            compiler_name,
+            compiler_version,
+            build_type,
+            build_mode,
+            build_option,
+            test_option,
+        )
+
+        # Determine the CMake target.
+        cmake_target = generate_cmake_target(os_name, build_type)
+
+        # Determine whether to enable running tests, and to create a package
+        # and/or image.
+        enable_tests, enable_package, enable_image = generate_enable_options(
+            os_name, build_type, publish_option
+        )
+
+        # Determine the image to run in, if applicable.
+        image = generate_image_name(
+            os_name,
+            os_version,
+            compiler_name,
+            compiler_version,
+            image_sha,
+        )
+
+        # Generate the configuration.
+        yield Config(
+            config_name=config_name,
+            cmake_args=cmake_args,
+            cmake_target=cmake_target,
+            build_type=("Debug" if build_type == BuildType.DEBUG else "Release"),
+            enable_tests=enable_tests,
+            enable_package=enable_package,
+            enable_image=enable_image,
+            runs_on=RUNNER_TAGS[arch],
+            image=image,
+        )
 
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
     parser.add_argument(
-        "-a",
-        "--all",
-        help="Set to generate all configurations (generally used when merging a PR) or leave unset to generate a subset of configurations (generally used when committing to a PR).",
-        action="store_true",
+        "--platform",
+        "-p",
+        required=False,
+        type=Platform,
+        choices=list(Platform),
+        help="The platform to run on.",
     )
     parser.add_argument(
-        "-c",
-        "--config",
-        help="Path to the JSON file containing the strategy matrix configurations.",
-        required=False,
-        type=Path,
+        "--trigger",
+        "-t",
+        required=True,
+        type=Trigger,
+        choices=list(Trigger),
+        help="The trigger that caused the workflow to run.",
     )
     args = parser.parse_args()
 
-    matrix = []
-    if args.config is None or args.config == "":
-        matrix += generate_strategy_matrix(
-            args.all, read_config(THIS_DIR / "linux.json")
-        )
-        matrix += generate_strategy_matrix(
-            args.all, read_config(THIS_DIR / "macos.json")
-        )
-        matrix += generate_strategy_matrix(
-            args.all, read_config(THIS_DIR / "windows.json")
-        )
-    else:
-        matrix += generate_strategy_matrix(args.all, read_config(args.config))
+    # Collect the distros to generate configs for.
+    distros = []
+    if args.platform in [None, Platform.LINUX]:
+        distros += linux.DEBIAN_DISTROS + linux.RHEL_DISTROS + linux.UBUNTU_DISTROS
+    if args.platform in [None, Platform.MACOS]:
+        distros += macos.DISTROS
+    if args.platform in [None, Platform.WINDOWS]:
+        distros += windows.DISTROS
 
-    # Generate the strategy matrix.
-    print(f"matrix={json.dumps({'include': matrix})}")
+    # Generate the configs.
+    configs = generate_configs(distros, args.trigger)
+
+    # Convert the configs into the format expected by GitHub Actions.
+    include = []
+    for config in configs:
+        include.append(dataclasses.asdict(config))
+    print(f"matrix={json.dumps({'include': include})}")

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

@@ -0,0 +1,466 @@
+import pytest
+
+from generate import *
+
+
+@pytest.fixture
+def macos_distro():
+    return Distro(
+        os_name="macos",
+        specs=[
+            Spec(
+                archs=[Arch.MACOS_ARM64],
+                build_modes=[BuildMode.UNITY_OFF],
+                build_option=BuildOption.COVERAGE,
+                build_types=[BuildType.RELEASE],
+                publish_option=PublishOption.NONE,
+                test_option=TestOption.NONE,
+                triggers=[Trigger.COMMIT],
+            )
+        ],
+    )
+
+
+@pytest.fixture
+def windows_distro():
+    return Distro(
+        os_name="windows",
+        specs=[
+            Spec(
+                archs=[Arch.WINDOWS_AMD64],
+                build_modes=[BuildMode.UNITY_ON],
+                build_option=BuildOption.SANITIZE_ASAN,
+                build_types=[BuildType.DEBUG],
+                publish_option=PublishOption.IMAGE_ONLY,
+                test_option=TestOption.REFERENCE_FEE_500,
+                triggers=[Trigger.COMMIT, Trigger.SCHEDULE],
+            )
+        ],
+    )
+
+
+@pytest.fixture
+def linux_distro():
+    return Distro(
+        os_name="debian",
+        os_version="bookworm",
+        compiler_name="clang",
+        compiler_version="16",
+        image_sha="a1b2c3d4",
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                build_modes=[BuildMode.UNITY_OFF],
+                build_option=BuildOption.SANITIZE_TSAN,
+                build_types=[BuildType.DEBUG],
+                publish_option=PublishOption.NONE,
+                test_option=TestOption.NONE,
+                triggers=[Trigger.LABEL],
+            ),
+            Spec(
+                archs=[Arch.LINUX_AMD64, Arch.LINUX_ARM64],
+                build_modes=[BuildMode.UNITY_OFF, BuildMode.UNITY_ON],
+                build_option=BuildOption.VOIDSTAR,
+                build_types=[BuildType.PUBLISH],
+                publish_option=PublishOption.PACKAGE_AND_IMAGE,
+                test_option=TestOption.NONE,
+                triggers=[Trigger.COMMIT, Trigger.LABEL],
+            ),
+        ],
+    )
+
+
+def test_macos_generate_config_for_distro_spec_matches_trigger(macos_distro):
+    trigger = Trigger.COMMIT
+
+    distro = macos_distro
+    result = list(
+        generate_config_for_distro_spec(
+            distro.os_name,
+            distro.os_version,
+            distro.compiler_name,
+            distro.compiler_version,
+            distro.image_sha,
+            distro.specs[0],
+            trigger,
+        )
+    )
+    assert result == [
+        Config(
+            config_name="macos-coverage-release-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dassert=ON -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0",
+            cmake_target="all",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["self-hosted", "macOS", "ARM64", "mac-runner-m1"],
+            image=None,
+        )
+    ]
+
+
+def test_macos_generate_config_for_distro_spec_no_match_trigger(macos_distro):
+    trigger = Trigger.MERGE
+
+    distro = macos_distro
+    result = list(
+        generate_config_for_distro_spec(
+            distro.os_name,
+            distro.os_version,
+            distro.compiler_name,
+            distro.compiler_version,
+            distro.image_sha,
+            distro.specs[0],
+            trigger,
+        )
+    )
+    assert result == []
+
+
+def test_macos_generate_config_for_distro_matches_trigger(macos_distro):
+    trigger = Trigger.COMMIT
+
+    distro = macos_distro
+    result = list(generate_config_for_distro(distro, trigger))
+    assert result == [
+        Config(
+            config_name="macos-coverage-release-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dassert=ON -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0",
+            cmake_target="all",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["self-hosted", "macOS", "ARM64", "mac-runner-m1"],
+            image=None,
+        )
+    ]
+
+
+def test_macos_generate_config_for_distro_no_match_trigger(macos_distro):
+    trigger = Trigger.MERGE
+
+    distro = macos_distro
+    result = list(generate_config_for_distro(distro, trigger))
+    assert result == []
+
+
+def test_windows_generate_config_for_distro_spec_matches_trigger(
+    windows_distro,
+):
+    trigger = Trigger.COMMIT
+
+    distro = windows_distro
+    result = list(
+        generate_config_for_distro_spec(
+            distro.os_name,
+            distro.os_version,
+            distro.compiler_name,
+            distro.compiler_version,
+            distro.image_sha,
+            distro.specs[0],
+            trigger,
+        )
+    )
+    assert result == [
+        Config(
+            config_name="windows-asan-debug-unity-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dunity=ON -DUNIT_TEST_REFERENCE_FEE=500",
+            cmake_target="install",
+            build_type="Debug",
+            enable_tests=False,
+            enable_package=False,
+            enable_image=True,
+            runs_on=["self-hosted", "Windows", "devbox"],
+            image=None,
+        )
+    ]
+
+
+def test_windows_generate_config_for_distro_spec_no_match_trigger(
+    windows_distro,
+):
+    trigger = Trigger.MERGE
+
+    distro = windows_distro
+    result = list(
+        generate_config_for_distro_spec(
+            distro.os_name,
+            distro.os_version,
+            distro.compiler_name,
+            distro.compiler_version,
+            distro.image_sha,
+            distro.specs[0],
+            trigger,
+        )
+    )
+    assert result == []
+
+
+def test_windows_generate_config_for_distro_matches_trigger(
+    windows_distro,
+):
+    trigger = Trigger.COMMIT
+
+    distro = windows_distro
+    result = list(generate_config_for_distro(distro, trigger))
+    assert result == [
+        Config(
+            config_name="windows-asan-debug-unity-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dunity=ON -DUNIT_TEST_REFERENCE_FEE=500",
+            cmake_target="install",
+            build_type="Debug",
+            enable_tests=False,
+            enable_package=False,
+            enable_image=True,
+            runs_on=["self-hosted", "Windows", "devbox"],
+            image=None,
+        )
+    ]
+
+
+def test_windows_generate_config_for_distro_no_match_trigger(
+    windows_distro,
+):
+    trigger = Trigger.MERGE
+
+    distro = windows_distro
+    result = list(generate_config_for_distro(distro, trigger))
+    assert result == []
+
+
+def test_linux_generate_config_for_distro_spec_matches_trigger(linux_distro):
+    trigger = Trigger.LABEL
+
+    distro = linux_distro
+    result = list(
+        generate_config_for_distro_spec(
+            distro.os_name,
+            distro.os_version,
+            distro.compiler_name,
+            distro.compiler_version,
+            distro.image_sha,
+            distro.specs[1],
+            trigger,
+        )
+    )
+    assert result == [
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "X64", "heavy"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-unity-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dunity=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "X64", "heavy"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "ARM64", "heavy-arm64"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-unity-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dunity=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "ARM64", "heavy-arm64"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+    ]
+
+
+def test_linux_generate_config_for_distro_spec_no_match_trigger(linux_distro):
+    trigger = Trigger.MERGE
+
+    distro = linux_distro
+    result = list(
+        generate_config_for_distro_spec(
+            distro.os_name,
+            distro.os_version,
+            distro.compiler_name,
+            distro.compiler_version,
+            distro.image_sha,
+            distro.specs[1],
+            trigger,
+        )
+    )
+    assert result == []
+
+
+def test_linux_generate_config_for_distro_matches_trigger(linux_distro):
+    trigger = Trigger.LABEL
+
+    distro = linux_distro
+    result = list(generate_config_for_distro(distro, trigger))
+    assert result == [
+        Config(
+            config_name="debian-bookworm-clang-16-tsan-debug-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["self-hosted", "Linux", "X64", "heavy"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "X64", "heavy"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-unity-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dunity=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "X64", "heavy"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "ARM64", "heavy-arm64"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-unity-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dunity=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "ARM64", "heavy-arm64"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+    ]
+
+
+def test_linux_generate_config_for_distro_no_match_trigger(linux_distro):
+    trigger = Trigger.MERGE
+
+    distro = linux_distro
+    result = list(generate_config_for_distro(distro, trigger))
+    assert result == []
+
+
+def test_generate_configs(macos_distro, windows_distro, linux_distro):
+    trigger = Trigger.COMMIT
+
+    distros = [macos_distro, windows_distro, linux_distro]
+    result = generate_configs(distros, trigger)
+    assert result == [
+        Config(
+            config_name="macos-coverage-release-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dassert=ON -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0",
+            cmake_target="all",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["self-hosted", "macOS", "ARM64", "mac-runner-m1"],
+            image=None,
+        ),
+        Config(
+            config_name="windows-asan-debug-unity-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dunity=ON -DUNIT_TEST_REFERENCE_FEE=500",
+            cmake_target="install",
+            build_type="Debug",
+            enable_tests=False,
+            enable_package=False,
+            enable_image=True,
+            runs_on=["self-hosted", "Windows", "devbox"],
+            image=None,
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "X64", "heavy"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-unity-amd64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dunity=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "X64", "heavy"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "ARM64", "heavy-arm64"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+        Config(
+            config_name="debian-bookworm-clang-16-voidstar-publish-unity-arm64",
+            cmake_args="-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dunity=ON -Dvoidstar=ON",
+            cmake_target="install",
+            build_type="Release",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=True,
+            runs_on=["self-hosted", "Linux", "ARM64", "heavy-arm64"],
+            image="ghcr.io/xrplf/ci/debian-bookworm:clang-16-a1b2c3d4",
+        ),
+    ]
+
+
+def test_generate_configs_raises_on_duplicate_configs(macos_distro):
+    trigger = Trigger.COMMIT
+
+    distros = [macos_distro, macos_distro]
+    with pytest.raises(ValueError):
+        generate_configs(distros, trigger)

.github/scripts/strategy-matrix/helpers/defs.py

@@ -0,0 +1,190 @@
+from dataclasses import dataclass, field
+
+from helpers.enums import *
+from helpers.unique import *
+
+
+@dataclass
+class Config:
+    """Represents a configuration to include in the strategy matrix.
+
+    Raises:
+        ValueError: If any of the required fields are empty or invalid.
+        TypeError: If any of the required fields are of the wrong type.
+    """
+
+    config_name: str
+    cmake_args: str
+    cmake_target: str
+    build_type: str
+    enable_tests: bool
+    enable_package: bool
+    enable_image: bool
+    runs_on: list[str]
+    image: str | None = None
+
+    def __post_init__(self):
+        if not self.config_name:
+            raise ValueError("config_name cannot be empty")
+        if not isinstance(self.config_name, str):
+            raise TypeError("config_name must be a string")
+
+        if not self.cmake_args:
+            raise ValueError("cmake_args cannot be empty")
+        if not isinstance(self.cmake_args, str):
+            raise TypeError("cmake_args must be a string")
+
+        if not self.cmake_target:
+            raise ValueError("cmake_target cannot be empty")
+        if not isinstance(self.cmake_target, str):
+            raise TypeError("cmake_target must be a string")
+        if self.cmake_target not in ["all", "install"]:
+            raise ValueError("cmake_target must be 'all' or 'install'")
+
+        if not self.build_type:
+            raise ValueError("build_type cannot be empty")
+        if not isinstance(self.build_type, str):
+            raise TypeError("build_type must be a string")
+        if self.build_type not in ["Debug", "Release"]:
+            raise ValueError("build_type must be 'Debug' or 'Release'")
+
+        if not isinstance(self.enable_tests, bool):
+            raise TypeError("enable_tests must be a boolean")
+        if not isinstance(self.enable_package, bool):
+            raise TypeError("enable_package must be a boolean")
+        if not isinstance(self.enable_image, bool):
+            raise TypeError("enable_image must be a boolean")
+
+        if not self.runs_on:
+            raise ValueError("runs_on cannot be empty")
+        if not isinstance(self.runs_on, list):
+            raise TypeError("runs_on must be a list")
+        if not all(isinstance(runner, str) for runner in self.runs_on):
+            raise TypeError("runs_on must be a list of strings")
+        if not all(self.runs_on):
+            raise ValueError("runs_on must be a list of non-empty strings")
+        if len(self.runs_on) != len(set(self.runs_on)):
+            raise ValueError("runs_on must be a list of unique strings")
+
+        if self.image and not isinstance(self.image, str):
+            raise TypeError("image must be a string")
+
+
+@dataclass
+class Spec:
+    """Represents a specification used by a configuration.
+
+    Raises:
+        ValueError: If any of the required fields are empty.
+        TypeError: If any of the required fields are of the wrong type.
+    """
+
+    archs: list[Arch] = field(
+        default_factory=lambda: [Arch.LINUX_AMD64, Arch.LINUX_ARM64]
+    )
+    build_option: BuildOption = BuildOption.NONE
+    build_modes: list[BuildMode] = field(
+        default_factory=lambda: [BuildMode.UNITY_OFF, BuildMode.UNITY_ON]
+    )
+    build_types: list[BuildType] = field(
+        default_factory=lambda: [BuildType.DEBUG, BuildType.RELEASE]
+    )
+    publish_option: PublishOption = PublishOption.NONE
+    test_option: TestOption = TestOption.NONE
+    triggers: list[Trigger] = field(
+        default_factory=lambda: [Trigger.COMMIT, Trigger.MERGE, Trigger.SCHEDULE]
+    )
+
+    def __post_init__(self):
+        if not self.archs:
+            raise ValueError("archs cannot be empty")
+        if not isinstance(self.archs, list):
+            raise TypeError("archs must be a list")
+        if not all(isinstance(arch, str) for arch in self.archs):
+            raise TypeError("archs must be a list of Arch")
+        if len(self.archs) != len(set(self.archs)):
+            raise ValueError("archs must be a list of unique Arch")
+
+        if not isinstance(self.build_option, BuildOption):
+            raise TypeError("build_option must be a BuildOption")
+
+        if not self.build_modes:
+            raise ValueError("build_modes cannot be empty")
+        if not isinstance(self.build_modes, list):
+            raise TypeError("build_modes must be a list")
+        if not all(
+            isinstance(build_mode, BuildMode) for build_mode in self.build_modes
+        ):
+            raise TypeError("build_modes must be a list of BuildMode")
+        if len(self.build_modes) != len(set(self.build_modes)):
+            raise ValueError("build_modes must be a list of unique BuildMode")
+
+        if not self.build_types:
+            raise ValueError("build_types cannot be empty")
+        if not isinstance(self.build_types, list):
+            raise TypeError("build_types must be a list")
+        if not all(
+            isinstance(build_type, BuildType) for build_type in self.build_types
+        ):
+            raise TypeError("build_types must be a list of BuildType")
+        if len(self.build_types) != len(set(self.build_types)):
+            raise ValueError("build_types must be a list of unique BuildType")
+
+        if not isinstance(self.publish_option, PublishOption):
+            raise TypeError("publish_option must be a PublishOption")
+
+        if not isinstance(self.test_option, TestOption):
+            raise TypeError("test_option must be a TestOption")
+
+        if not self.triggers:
+            raise ValueError("triggers cannot be empty")
+        if not isinstance(self.triggers, list):
+            raise TypeError("triggers must be a list")
+        if not all(isinstance(trigger, Trigger) for trigger in self.triggers):
+            raise TypeError("triggers must be a list of Trigger")
+        if len(self.triggers) != len(set(self.triggers)):
+            raise ValueError("triggers must be a list of unique Trigger")
+
+
+@dataclass
+class Distro:
+    """Represents a Linux, Windows or macOS distribution with specifications.
+
+    Raises:
+        ValueError: If any of the required fields are empty.
+        TypeError: If any of the required fields are of the wrong type.
+    """
+
+    os_name: str
+    os_version: str = ""
+    compiler_name: str = ""
+    compiler_version: str = ""
+    image_sha: str = ""
+    specs: list[Spec] = field(default_factory=list)
+
+    def __post_init__(self):
+        if not self.os_name:
+            raise ValueError("os_name cannot be empty")
+        if not isinstance(self.os_name, str):
+            raise TypeError("os_name must be a string")
+
+        if self.os_version and not isinstance(self.os_version, str):
+            raise TypeError("os_version must be a string")
+
+        if self.compiler_name and not isinstance(self.compiler_name, str):
+            raise TypeError("compiler_name must be a string")
+
+        if self.compiler_version and not isinstance(self.compiler_version, str):
+            raise TypeError("compiler_version must be a string")
+
+        if self.image_sha and not isinstance(self.image_sha, str):
+            raise TypeError("image_sha must be a string")
+
+        if not self.specs:
+            raise ValueError("specs cannot be empty")
+        if not isinstance(self.specs, list):
+            raise TypeError("specs must be a list")
+        if not all(isinstance(spec, Spec) for spec in self.specs):
+            raise TypeError("specs must be a list of Spec")
+        if not is_unique(self.specs):
+            raise ValueError("specs must be a list of unique Spec")

.github/scripts/strategy-matrix/helpers/defs_test.py

@@ -0,0 +1,743 @@
+import pytest
+
+from helpers.defs import *
+from helpers.enums import *
+from helpers.funcs import *
+
+
+def test_config_valid_none_image():
+    assert Config(
+        config_name="config",
+        cmake_args="-Doption=ON",
+        cmake_target="all",
+        build_type="Debug",
+        enable_tests=True,
+        enable_package=False,
+        enable_image=False,
+        runs_on=["label"],
+        image=None,
+    )
+
+
+def test_config_valid_empty_image():
+    assert Config(
+        config_name="config",
+        cmake_args="-Doption=ON",
+        cmake_target="install",
+        build_type="Debug",
+        enable_tests=False,
+        enable_package=True,
+        enable_image=False,
+        runs_on=["label"],
+        image="",
+    )
+
+
+def test_config_valid_with_image():
+    assert Config(
+        config_name="config",
+        cmake_args="-Doption=ON",
+        cmake_target="install",
+        build_type="Release",
+        enable_tests=False,
+        enable_package=True,
+        enable_image=True,
+        runs_on=["label"],
+        image="image",
+    )
+
+
+def test_config_raises_on_empty_config_name():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_config_name():
+    with pytest.raises(TypeError):
+        Config(
+            config_name=123,
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_empty_cmake_args():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_cmake_args():
+    with pytest.raises(TypeError):
+        Config(
+            config_name="config",
+            cmake_args=123,
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_empty_cmake_target():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_invalid_cmake_target():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="invalid",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_cmake_target():
+    with pytest.raises(TypeError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target=123,
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_empty_build_type():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_invalid_build_type():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="invalid",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_build_type():
+    with pytest.raises(TypeError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type=123,
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_enable_tests():
+    with pytest.raises(TypeError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=123,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_enable_package():
+    with pytest.raises(TypeError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=123,
+            enable_image=False,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_enable_image():
+    with pytest.raises(TypeError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=True,
+            enable_image=123,
+            runs_on=["label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_none_runs_on():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=None,
+            image="image",
+        )
+
+
+def test_config_raises_on_empty_runs_on():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=[],
+            image="image",
+        )
+
+
+def test_config_raises_on_invalid_runs_on():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=[""],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_runs_on():
+    with pytest.raises(TypeError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=[123],
+            image="image",
+        )
+
+
+def test_config_raises_on_duplicate_runs_on():
+    with pytest.raises(ValueError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label", "label"],
+            image="image",
+        )
+
+
+def test_config_raises_on_wrong_image():
+    with pytest.raises(TypeError):
+        Config(
+            config_name="config",
+            cmake_args="-Doption=ON",
+            cmake_target="all",
+            build_type="Debug",
+            enable_tests=True,
+            enable_package=False,
+            enable_image=False,
+            runs_on=["label"],
+            image=123,
+        )
+
+
+def test_spec_valid():
+    assert Spec(
+        archs=[Arch.LINUX_AMD64],
+        build_option=BuildOption.NONE,
+        build_modes=[BuildMode.UNITY_OFF],
+        build_types=[BuildType.DEBUG],
+        publish_option=PublishOption.NONE,
+        test_option=TestOption.NONE,
+        triggers=[Trigger.COMMIT],
+    )
+
+
+def test_spec_raises_on_none_archs():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=None,
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_empty_archs():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_wrong_archs():
+    with pytest.raises(TypeError):
+        Spec(
+            archs=[123],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_duplicate_archs():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64, Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_wrong_build_option():
+    with pytest.raises(TypeError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=123,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_none_build_modes():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=None,
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_empty_build_modes():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_wrong_build_modes():
+    with pytest.raises(TypeError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[123],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_none_build_types():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=None,
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_empty_build_types():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_wrong_build_types():
+    with pytest.raises(TypeError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[123],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_duplicate_build_types():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG, BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_wrong_publish_option():
+    with pytest.raises(TypeError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=123,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_wrong_test_option():
+    with pytest.raises(TypeError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=123,
+            triggers=[Trigger.COMMIT],
+        )
+
+
+def test_spec_raises_on_none_triggers():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=None,
+        )
+
+
+def test_spec_raises_on_empty_triggers():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[],
+        )
+
+
+def test_spec_raises_on_wrong_triggers():
+    with pytest.raises(TypeError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[123],
+        )
+
+
+def test_spec_raises_on_duplicate_triggers():
+    with pytest.raises(ValueError):
+        Spec(
+            archs=[Arch.LINUX_AMD64],
+            build_option=BuildOption.NONE,
+            build_modes=[BuildMode.UNITY_OFF],
+            build_types=[BuildType.DEBUG],
+            publish_option=PublishOption.NONE,
+            test_option=TestOption.NONE,
+            triggers=[Trigger.COMMIT, Trigger.COMMIT],
+        )
+
+
+def test_distro_valid_none_image_sha():
+    assert Distro(
+        os_name="os_name",
+        os_version="os_version",
+        compiler_name="compiler_name",
+        compiler_version="compiler_version",
+        image_sha=None,
+        specs=[Spec()],  # This is valid due to the default values.
+    )
+
+
+def test_distro_valid_empty_os_compiler_image_sha():
+    assert Distro(
+        os_name="os_name",
+        os_version="",
+        compiler_name="",
+        compiler_version="",
+        image_sha="",
+        specs=[Spec()],
+    )
+
+
+def test_distro_valid_with_image():
+    assert Distro(
+        os_name="os_name",
+        os_version="os_version",
+        compiler_name="compiler_name",
+        compiler_version="compiler_version",
+        image_sha="image_sha",
+        specs=[Spec()],
+    )
+
+
+def test_distro_raises_on_empty_os_name():
+    with pytest.raises(ValueError):
+        Distro(
+            os_name="",
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=[Spec()],
+        )
+
+
+def test_distro_raises_on_wrong_os_name():
+    with pytest.raises(TypeError):
+        Distro(
+            os_name=123,
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=[Spec()],
+        )
+
+
+def test_distro_raises_on_wrong_os_version():
+    with pytest.raises(TypeError):
+        Distro(
+            os_name="os_name",
+            os_version=123,
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=[Spec()],
+        )
+
+
+def test_distro_raises_on_wrong_compiler_name():
+    with pytest.raises(TypeError):
+        Distro(
+            os_name="os_name",
+            os_version="os_version",
+            compiler_name=123,
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=[Spec()],
+        )
+
+
+def test_distro_raises_on_wrong_compiler_version():
+    with pytest.raises(TypeError):
+        Distro(
+            os_name="os_name",
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version=123,
+            image_sha="image_sha",
+            specs=[Spec()],
+        )
+
+
+def test_distro_raises_on_wrong_image_sha():
+    with pytest.raises(TypeError):
+        Distro(
+            os_name="os_name",
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha=123,
+            specs=[Spec()],
+        )
+
+
+def test_distro_raises_on_none_specs():
+    with pytest.raises(ValueError):
+        Distro(
+            os_name="os_name",
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=None,
+        )
+
+
+def test_distro_raises_on_empty_specs():
+    with pytest.raises(ValueError):
+        Distro(
+            os_name="os_name",
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=[],
+        )
+
+
+def test_distro_raises_on_invalid_specs():
+    with pytest.raises(ValueError):
+        Distro(
+            os_name="os_name",
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=[Spec(triggers=[])],
+        )
+
+
+def test_distro_raises_on_duplicate_specs():
+    with pytest.raises(ValueError):
+        Distro(
+            os_name="os_name",
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=[Spec(), Spec()],
+        )
+
+
+def test_distro_raises_on_wrong_specs():
+    with pytest.raises(TypeError):
+        Distro(
+            os_name="os_name",
+            os_version="os_version",
+            compiler_name="compiler_name",
+            compiler_version="compiler_version",
+            image_sha="image_sha",
+            specs=[123],
+        )

.github/scripts/strategy-matrix/helpers/enums.py

@@ -0,0 +1,75 @@
+from enum import StrEnum, auto
+
+
+class Arch(StrEnum):
+    """Represents architectures to build for."""
+
+    LINUX_AMD64 = "linux/amd64"
+    LINUX_ARM64 = "linux/arm64"
+    MACOS_ARM64 = "macos/arm64"
+    WINDOWS_AMD64 = "windows/amd64"
+
+
+class BuildMode(StrEnum):
+    """Represents whether to perform a unity or non-unity build."""
+
+    UNITY_OFF = auto()
+    UNITY_ON = auto()
+
+
+class BuildOption(StrEnum):
+    """Represents build options to enable."""
+
+    NONE = auto()
+    COVERAGE = auto()
+    SANITIZE_ASAN = (
+        auto()
+    )  # Address Sanitizer, also includes Undefined Behavior Sanitizer.
+    SANITIZE_TSAN = (
+        auto()
+    )  # Thread Sanitizer, also includes Undefined Behavior Sanitizer.
+    VOIDSTAR = auto()
+
+
+class BuildType(StrEnum):
+    """Represents the build type to use."""
+
+    DEBUG = auto()
+    RELEASE = auto()
+    PUBLISH = auto()  # Release build without assertions.
+
+
+class PublishOption(StrEnum):
+    """Represents whether to publish a package, an image, or both."""
+
+    NONE = auto()
+    PACKAGE_ONLY = auto()
+    IMAGE_ONLY = auto()
+    PACKAGE_AND_IMAGE = auto()
+
+
+class TestOption(StrEnum):
+    """Represents test options to enable, specifically the reference fee to use."""
+
+    __test__ = False  # Tell pytest to not consider this as a test class.
+
+    NONE = ""  # Use the default reference fee of 10.
+    REFERENCE_FEE_500 = "500"
+    REFERENCE_FEE_1000 = "1000"
+
+
+class Platform(StrEnum):
+    """Represents the platform to use."""
+
+    LINUX = "linux"
+    MACOS = "macos"
+    WINDOWS = "windows"
+
+
+class Trigger(StrEnum):
+    """Represents the trigger that caused the workflow to run."""
+
+    COMMIT = "commit"
+    LABEL = "label"
+    MERGE = "merge"
+    SCHEDULE = "schedule"

.github/scripts/strategy-matrix/helpers/funcs.py

@@ -0,0 +1,235 @@
+from helpers.defs import *
+from helpers.enums import *
+
+
+def generate_config_name(
+    os_name: str,
+    os_version: str | None,
+    compiler_name: str | None,
+    compiler_version: str | None,
+    arch: Arch,
+    build_type: BuildType,
+    build_mode: BuildMode,
+    build_option: BuildOption,
+) -> str:
+    """Create a configuration name based on the distro details and build
+    attributes.
+
+    The configuration name is used as the display name in the GitHub Actions
+    UI, and since GitHub truncates long names we have to make sure the most
+    important information is at the beginning of the name.
+
+    Args:
+        os_name (str): The OS name.
+        os_version (str): The OS version.
+        compiler_name (str): The compiler name.
+        compiler_version (str): The compiler version.
+        arch (Arch): The architecture.
+        build_type (BuildType): The build type.
+        build_mode (BuildMode): The build mode.
+        build_option (BuildOption): The build option.
+
+    Returns:
+        str: The configuration name.
+
+    Raises:
+        ValueError: If the OS name is empty.
+    """
+
+    if not os_name:
+        raise ValueError("os_name cannot be empty")
+
+    config_name = os_name
+    if os_version:
+        config_name += f"-{os_version}"
+    if compiler_name:
+        config_name += f"-{compiler_name}"
+    if compiler_version:
+        config_name += f"-{compiler_version}"
+
+    if build_option == BuildOption.COVERAGE:
+        config_name += "-coverage"
+    elif build_option == BuildOption.VOIDSTAR:
+        config_name += "-voidstar"
+    elif build_option == BuildOption.SANITIZE_ASAN:
+        config_name += "-asan"
+    elif build_option == BuildOption.SANITIZE_TSAN:
+        config_name += "-tsan"
+
+    if build_type == BuildType.DEBUG:
+        config_name += "-debug"
+    elif build_type == BuildType.RELEASE:
+        config_name += "-release"
+    elif build_type == BuildType.PUBLISH:
+        config_name += "-publish"
+
+    if build_mode == BuildMode.UNITY_ON:
+        config_name += "-unity"
+
+    config_name += f"-{arch.value.split('/')[1]}"
+
+    return config_name
+
+
+def generate_cmake_args(
+    compiler_name: str | None,
+    compiler_version: str | None,
+    build_type: BuildType,
+    build_mode: BuildMode,
+    build_option: BuildOption,
+    test_option: TestOption,
+) -> str:
+    """Create the CMake arguments based on the build type and enabled build
+    options.
+
+    - All builds will have the `tests`, `werr`, and `xrpld` options.
+    - All builds will have the `wextra` option except for GCC 12 and Clang 16.
+    - All release builds will have the `assert` option.
+    - Set the unity option if specified.
+    - Set the coverage option if specified.
+    - Set the voidstar option if specified.
+    - Set the reference fee if specified.
+
+    Args:
+        compiler_name (str): The compiler name.
+        compiler_version (str): The compiler version.
+        build_type (BuildType): The build type.
+        build_mode (BuildMode): The build mode.
+        build_option (BuildOption): The build option.
+        test_option (TestOption): The test option.
+
+    Returns:
+        str: The CMake arguments.
+
+    """
+
+    cmake_args = "-Dtests=ON -Dwerr=ON -Dxrpld=ON"
+    if not f"{compiler_name}-{compiler_version}" in [
+        "gcc-12",
+        "clang-16",
+    ]:
+        cmake_args += " -Dwextra=ON"
+
+    if build_type == BuildType.RELEASE:
+        cmake_args += " -Dassert=ON"
+
+    if build_mode == BuildMode.UNITY_ON:
+        cmake_args += " -Dunity=ON"
+
+    if build_option == BuildOption.COVERAGE:
+        cmake_args += " -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0"
+    elif build_option == BuildOption.SANITIZE_ASAN:
+        pass  # TODO: Add ASAN-UBSAN flags.
+    elif build_option == BuildOption.SANITIZE_TSAN:
+        pass  # TODO: Add TSAN-UBSAN flags.
+    elif build_option == BuildOption.VOIDSTAR:
+        cmake_args += " -Dvoidstar=ON"
+
+    if test_option != TestOption.NONE:
+        cmake_args += f" -DUNIT_TEST_REFERENCE_FEE={test_option.value}"
+
+    return cmake_args
+
+
+def generate_cmake_target(os_name: str, build_type: BuildType) -> str:
+    """Create the CMake target based on the build type.
+
+    The `install` target is used for Windows and for publishing a package, while
+    the `all` target is used for all other configurations.
+
+    Args:
+        os_name (str): The OS name.
+        build_type (BuildType): The build type.
+
+    Returns:
+        str: The CMake target.
+    """
+    if os_name == "windows" or build_type == BuildType.PUBLISH:
+        return "install"
+    return "all"
+
+
+def generate_enable_options(
+    os_name: str,
+    build_type: BuildType,
+    publish_option: PublishOption,
+) -> tuple[bool, bool, bool]:
+    """Create the enable flags based on the OS name, build option, and publish
+     option.
+
+     We build and test all configurations by default, except for Windows in
+     Debug, because it is too slow.
+
+    Args:
+        os_name (str): The OS name.
+        build_type (BuildType): The build type.
+        publish_option (PublishOption): The publish option.
+
+    Returns:
+        tuple: A tuple containing the enable test, enable package, and enable image flags.
+    """
+    enable_tests = (
+        False if os_name == "windows" and build_type == BuildType.DEBUG else True
+    )
+
+    enable_package = (
+        True
+        if publish_option
+        in [
+            PublishOption.PACKAGE_ONLY,
+            PublishOption.PACKAGE_AND_IMAGE,
+        ]
+        else False
+    )
+
+    enable_image = (
+        True
+        if publish_option
+        in [
+            PublishOption.IMAGE_ONLY,
+            PublishOption.PACKAGE_AND_IMAGE,
+        ]
+        else False
+    )
+
+    return enable_tests, enable_package, enable_image
+
+
+def generate_image_name(
+    os_name: str,
+    os_version: str,
+    compiler_name: str,
+    compiler_version: str,
+    image_sha: str,
+) -> str | None:
+    """Create the Docker image name based on the distro details.
+
+    Args:
+        os_name (str): The OS name.
+        os_version (str): The OS version.
+        compiler_name (str): The compiler name.
+        compiler_version (str): The compiler version.
+        image_sha (str): The image SHA.
+
+    Returns:
+        str: The Docker image name or None if not applicable.
+
+    Raises:
+        ValueError: If any of the arguments is empty for Linux.
+    """
+
+    if os_name == "windows" or os_name == "macos":
+        return None
+
+    if not os_name:
+        raise ValueError("os_name cannot be empty")
+    if not os_version:
+        raise ValueError("os_version cannot be empty")
+    if not compiler_name:
+        raise ValueError("compiler_name cannot be empty")
+    if not compiler_version:
+        raise ValueError("compiler_version cannot be empty")
+    if not image_sha:
+        raise ValueError("image_sha cannot be empty")
+
+    return f"ghcr.io/xrplf/ci/{os_name}-{os_version}:{compiler_name}-{compiler_version}-{image_sha}"

.github/scripts/strategy-matrix/helpers/funcs_test.py

@@ -0,0 +1,419 @@
+import pytest
+
+from helpers.enums import *
+from helpers.funcs import *
+
+
+def test_generate_config_name_a_b_c_d_debug_amd64():
+    assert (
+        generate_config_name(
+            "a",
+            "b",
+            "c",
+            "d",
+            Arch.LINUX_AMD64,
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+        )
+        == "a-b-c-d-debug-amd64"
+    )
+
+
+def test_generate_config_name_a_b_c_release_unity_arm64():
+    assert (
+        generate_config_name(
+            "a",
+            "b",
+            "c",
+            "",
+            Arch.LINUX_ARM64,
+            BuildType.RELEASE,
+            BuildMode.UNITY_ON,
+            BuildOption.NONE,
+        )
+        == "a-b-c-release-unity-arm64"
+    )
+
+
+def test_generate_config_name_a_b_coverage_publish_amd64():
+    assert (
+        generate_config_name(
+            "a",
+            "b",
+            "",
+            "",
+            Arch.LINUX_AMD64,
+            BuildType.PUBLISH,
+            BuildMode.UNITY_OFF,
+            BuildOption.COVERAGE,
+        )
+        == "a-b-coverage-publish-amd64"
+    )
+
+
+def test_generate_config_name_a_asan_debug_unity_arm64():
+    assert (
+        generate_config_name(
+            "a",
+            "",
+            "",
+            "",
+            Arch.LINUX_ARM64,
+            BuildType.DEBUG,
+            BuildMode.UNITY_ON,
+            BuildOption.SANITIZE_ASAN,
+        )
+        == "a-asan-debug-unity-arm64"
+    )
+
+
+def test_generate_config_name_a_c_tsan_release_amd64():
+    assert (
+        generate_config_name(
+            "a",
+            "",
+            "c",
+            "",
+            Arch.LINUX_AMD64,
+            BuildType.RELEASE,
+            BuildMode.UNITY_OFF,
+            BuildOption.SANITIZE_TSAN,
+        )
+        == "a-c-tsan-release-amd64"
+    )
+
+
+def test_generate_config_name_a_d_voidstar_debug_amd64():
+    assert (
+        generate_config_name(
+            "a",
+            "",
+            "",
+            "d",
+            Arch.LINUX_AMD64,
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.VOIDSTAR,
+        )
+        == "a-d-voidstar-debug-amd64"
+    )
+
+
+def test_generate_config_name_raises_on_none_os_name():
+    with pytest.raises(ValueError):
+        generate_config_name(
+            None,
+            "b",
+            "c",
+            "d",
+            Arch.LINUX_AMD64,
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+        )
+
+
+def test_generate_config_name_raises_on_empty_os_name():
+    with pytest.raises(ValueError):
+        generate_config_name(
+            "",
+            "b",
+            "c",
+            "d",
+            Arch.LINUX_AMD64,
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+        )
+
+
+def test_generate_cmake_args_a_b_debug():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+            TestOption.NONE,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON"
+    )
+
+
+def test_generate_cmake_args_gcc_12_no_wextra():
+    assert (
+        generate_cmake_args(
+            "gcc",
+            "12",
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+            TestOption.NONE,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON"
+    )
+
+
+def test_generate_cmake_args_clang_16_no_wextra():
+    assert (
+        generate_cmake_args(
+            "clang",
+            "16",
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+            TestOption.NONE,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON"
+    )
+
+
+def test_generate_cmake_args_a_b_release():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.RELEASE,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+            TestOption.NONE,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dassert=ON"
+    )
+
+
+def test_generate_cmake_args_a_b_publish():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.PUBLISH,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+            TestOption.NONE,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON"
+    )
+
+
+def test_generate_cmake_args_a_b_unity():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.DEBUG,
+            BuildMode.UNITY_ON,
+            BuildOption.NONE,
+            TestOption.NONE,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dunity=ON"
+    )
+
+
+def test_generate_cmake_args_a_b_coverage():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.COVERAGE,
+            TestOption.NONE,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0"
+    )
+
+
+def test_generate_cmake_args_a_b_voidstar():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.VOIDSTAR,
+            TestOption.NONE,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dvoidstar=ON"
+    )
+
+
+def test_generate_cmake_args_a_b_reference_fee_500():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+            TestOption.REFERENCE_FEE_500,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -DUNIT_TEST_REFERENCE_FEE=500"
+    )
+
+
+def test_generate_cmake_args_a_b_reference_fee_1000():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.DEBUG,
+            BuildMode.UNITY_OFF,
+            BuildOption.NONE,
+            TestOption.REFERENCE_FEE_1000,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -DUNIT_TEST_REFERENCE_FEE=1000"
+    )
+
+
+def test_generate_cmake_args_a_b_multiple():
+    assert (
+        generate_cmake_args(
+            "a",
+            "b",
+            BuildType.RELEASE,
+            BuildMode.UNITY_ON,
+            BuildOption.VOIDSTAR,
+            TestOption.REFERENCE_FEE_500,
+        )
+        == "-Dtests=ON -Dwerr=ON -Dxrpld=ON -Dwextra=ON -Dassert=ON -Dunity=ON -Dvoidstar=ON -DUNIT_TEST_REFERENCE_FEE=500"
+    )
+
+
+def test_generate_cmake_target_linux_debug():
+    assert generate_cmake_target("linux", BuildType.DEBUG) == "all"
+
+
+def test_generate_cmake_target_linux_release():
+    assert generate_cmake_target("linux", BuildType.RELEASE) == "all"
+
+
+def test_generate_cmake_target_linux_publish():
+    assert generate_cmake_target("linux", BuildType.PUBLISH) == "install"
+
+
+def test_generate_cmake_target_macos_debug():
+    assert generate_cmake_target("macos", BuildType.DEBUG) == "all"
+
+
+def test_generate_cmake_target_macos_release():
+    assert generate_cmake_target("macos", BuildType.RELEASE) == "all"
+
+
+def test_generate_cmake_target_macos_publish():
+    assert generate_cmake_target("macos", BuildType.PUBLISH) == "install"
+
+
+def test_generate_cmake_target_windows_debug():
+    assert generate_cmake_target("windows", BuildType.DEBUG) == "install"
+
+
+def test_generate_cmake_target_windows_release():
+    assert generate_cmake_target("windows", BuildType.DEBUG) == "install"
+
+
+def test_generate_cmake_target_windows_publish():
+    assert generate_cmake_target("windows", BuildType.DEBUG) == "install"
+
+
+def test_generate_enable_options_linux_debug_no_publish():
+    assert generate_enable_options("linux", BuildType.DEBUG, PublishOption.NONE) == (
+        True,
+        False,
+        False,
+    )
+
+
+def test_generate_enable_options_linux_release_package_only():
+    assert generate_enable_options(
+        "linux", BuildType.RELEASE, PublishOption.PACKAGE_ONLY
+    ) == (True, True, False)
+
+
+def test_generate_enable_options_linux_publish_image_only():
+    assert generate_enable_options(
+        "linux", BuildType.PUBLISH, PublishOption.IMAGE_ONLY
+    ) == (True, False, True)
+
+
+def test_generate_enable_options_macos_debug_package_only():
+    assert generate_enable_options(
+        "macos", BuildType.DEBUG, PublishOption.PACKAGE_ONLY
+    ) == (True, True, False)
+
+
+def test_generate_enable_options_macos_release_image_only():
+    assert generate_enable_options(
+        "macos", BuildType.RELEASE, PublishOption.IMAGE_ONLY
+    ) == (True, False, True)
+
+
+def test_generate_enable_options_macos_publish_package_and_image():
+    assert generate_enable_options(
+        "macos", BuildType.PUBLISH, PublishOption.PACKAGE_AND_IMAGE
+    ) == (True, True, True)
+
+
+def test_generate_enable_options_windows_debug_package_and_image():
+    assert generate_enable_options(
+        "windows", BuildType.DEBUG, PublishOption.PACKAGE_AND_IMAGE
+    ) == (False, True, True)
+
+
+def test_generate_enable_options_windows_release_no_publish():
+    assert generate_enable_options(
+        "windows", BuildType.RELEASE, PublishOption.NONE
+    ) == (True, False, False)
+
+
+def test_generate_enable_options_windows_publish_image_only():
+    assert generate_enable_options(
+        "windows", BuildType.PUBLISH, PublishOption.IMAGE_ONLY
+    ) == (True, False, True)
+
+
+def test_generate_image_name_linux():
+    assert generate_image_name("a", "b", "c", "d", "e") == "ghcr.io/xrplf/ci/a-b:c-d-e"
+
+
+def test_generate_image_name_linux_raises_on_empty_os_name():
+    with pytest.raises(ValueError):
+        generate_image_name("", "b", "c", "d", "e")
+
+
+def test_generate_image_name_linux_raises_on_empty_os_version():
+    with pytest.raises(ValueError):
+        generate_image_name("a", "", "c", "d", "e")
+
+
+def test_generate_image_name_linux_raises_on_empty_compiler_name():
+    with pytest.raises(ValueError):
+        generate_image_name("a", "b", "", "d", "e")
+
+
+def test_generate_image_name_linux_raises_on_empty_compiler_version():
+    with pytest.raises(ValueError):
+        generate_image_name("a", "b", "c", "", "e")
+
+
+def test_generate_image_name_linux_raises_on_empty_image_sha():
+    with pytest.raises(ValueError):
+        generate_image_name("a", "b", "c", "e", "")
+
+
+def test_generate_image_name_macos():
+    assert generate_image_name("macos", "", "", "", "") is None
+
+
+def test_generate_image_name_macos_extra():
+    assert generate_image_name("macos", "value", "does", "not", "matter") is None
+
+
+def test_generate_image_name_windows():
+    assert generate_image_name("windows", "", "", "", "") is None
+
+
+def test_generate_image_name_windows_extra():
+    assert generate_image_name("windows", "value", "does", "not", "matter") is None

.github/scripts/strategy-matrix/helpers/unique.py

@@ -0,0 +1,30 @@
+import json
+from dataclasses import _is_dataclass_instance, asdict
+from typing import Any
+
+
+def is_unique(items: list[Any]) -> bool:
+    """Check if a list of dataclass objects contains only unique items.
+
+    As the items may not be hashable, we convert them to JSON strings first, and
+    then check if the list of strings is the same size as the set of strings.
+
+    Args:
+        items: The list of dataclass objects to check.
+
+    Returns:
+        True if the list contains only unique items, False otherwise.
+
+    Raises:
+        TypeError: If any of the items is not a dataclass.
+    """
+
+    l = list()
+    s = set()
+    for item in items:
+        if not _is_dataclass_instance(item):
+            raise TypeError("items must be a list of dataclasses")
+        j = json.dumps(asdict(item))
+        l.append(j)
+        s.add(j)
+    return len(l) == len(s)

.github/scripts/strategy-matrix/helpers/unique_test.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+import pytest
+
+from helpers.unique import *
+
+
+@dataclass
+class ExampleInt:
+    value: int
+
+
+@dataclass
+class ExampleList:
+    values: list[int]
+
+
+def test_unique_int():
+    assert is_unique([ExampleInt(1), ExampleInt(2), ExampleInt(3)])
+
+
+def test_not_unique_int():
+    assert not is_unique([ExampleInt(1), ExampleInt(2), ExampleInt(1)])
+
+
+def test_unique_list():
+    assert is_unique(
+        [ExampleList([1, 2, 3]), ExampleList([4, 5, 6]), ExampleList([7, 8, 9])]
+    )
+
+
+def test_not_unique_list():
+    assert not is_unique(
+        [ExampleList([1, 2, 3]), ExampleList([4, 5, 6]), ExampleList([1, 2, 3])]
+    )
+
+
+def test_unique_raises_on_non_dataclass():
+    with pytest.raises(TypeError):
+        is_unique([1, 2, 3])

.github/scripts/strategy-matrix/linux.json

@@ -1,212 +0,0 @@
-{
-  "architecture": [
-    {
-      "platform": "linux/amd64",
-      "runner": ["self-hosted", "Linux", "X64", "heavy"]
-    },
-    {
-      "platform": "linux/arm64",
-      "runner": ["self-hosted", "Linux", "ARM64", "heavy-arm64"]
-    }
-  ],
-  "os": [
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "gcc",
-      "compiler_version": "12",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "gcc",
-      "compiler_version": "13",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "gcc",
-      "compiler_version": "15",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "16",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "17",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "18",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "19",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "20",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "trixie",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "trixie",
-      "compiler_name": "gcc",
-      "compiler_version": "15",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "trixie",
-      "compiler_name": "clang",
-      "compiler_version": "20",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "trixie",
-      "compiler_name": "clang",
-      "compiler_version": "21",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "8",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "8",
-      "compiler_name": "clang",
-      "compiler_version": "any",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "9",
-      "compiler_name": "gcc",
-      "compiler_version": "12",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "9",
-      "compiler_name": "gcc",
-      "compiler_version": "13",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "9",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "9",
-      "compiler_name": "clang",
-      "compiler_version": "any",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "10",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "10",
-      "compiler_name": "clang",
-      "compiler_version": "any",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "jammy",
-      "compiler_name": "gcc",
-      "compiler_version": "12",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "gcc",
-      "compiler_version": "13",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "clang",
-      "compiler_version": "16",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "clang",
-      "compiler_version": "17",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "clang",
-      "compiler_version": "18",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "clang",
-      "compiler_version": "19",
-      "image_sha": "ab4d1f0"
-    }
-  ],
-  "build_type": ["Debug", "Release"],
-  "cmake_args": [""]
-}

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

@@ -0,0 +1,385 @@
+from helpers.defs import *
+from helpers.enums import *
+
+# The default CI image SHAs to use, which can be specified per distro group and
+# can be overridden for individual distros, which is useful when debugging using
+# a locally built CI image. See https://github.com/XRPLF/ci for the images.
+DEBIAN_SHA = "sha-ca4517d"
+RHEL_SHA = "sha-ca4517d"
+UBUNTU_SHA = "sha-84afd81"
+
+# We only build a selection of configurations for the various triggers to reduce
+# pipeline runtime. Across all three operating systems we aim to cover all GCC
+# and Clang versions, while not duplicating configurations too much. See also
+# the README for more details.
+
+# The Debian distros to build configurations for.
+#
+# We have the following distros available:
+# - Debian Bullseye: GCC 12-15
+# - Debian Bookworm: GCC 13-15, Clang 16-20
+# - Debian Trixie: GCC 14-15, Clang 20-21
+DEBIAN_DISTROS = [
+    Distro(
+        os_name="debian",
+        os_version="bullseye",
+        compiler_name="gcc",
+        compiler_version="14",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                build_modes=[BuildMode.UNITY_OFF],
+                build_types=[BuildType.DEBUG],
+                publish_option=PublishOption.PACKAGE_ONLY,
+                triggers=[Trigger.COMMIT, Trigger.LABEL],
+            ),
+            Spec(
+                build_modes=[BuildMode.UNITY_OFF],
+                build_types=[BuildType.PUBLISH],
+                publish_option=PublishOption.PACKAGE_AND_IMAGE,
+                triggers=[Trigger.MERGE],
+            ),
+            Spec(
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="debian",
+        os_version="bullseye",
+        compiler_name="gcc",
+        compiler_version="15",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                build_modes=[BuildMode.UNITY_ON],
+                build_option=BuildOption.COVERAGE,
+                build_types=[BuildType.DEBUG],
+                triggers=[Trigger.COMMIT, Trigger.MERGE],
+            ),
+            Spec(
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="debian",
+        os_version="bookworm",
+        compiler_name="gcc",
+        compiler_version="15",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="debian",
+        os_version="bookworm",
+        compiler_name="clang",
+        compiler_version="16",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                build_modes=[BuildMode.UNITY_OFF],
+                build_option=BuildOption.VOIDSTAR,
+                build_types=[BuildType.DEBUG],
+                publish_option=PublishOption.IMAGE_ONLY,
+                triggers=[Trigger.COMMIT],
+            ),
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                build_modes=[BuildMode.UNITY_ON],
+                build_types=[BuildType.RELEASE],
+                triggers=[Trigger.MERGE],
+            ),
+            Spec(
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="debian",
+        os_version="bookworm",
+        compiler_name="clang",
+        compiler_version="17",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="debian",
+        os_version="bookworm",
+        compiler_name="clang",
+        compiler_version="18",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="debian",
+        os_version="bookworm",
+        compiler_name="clang",
+        compiler_version="19",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="debian",
+        os_version="trixie",
+        compiler_name="gcc",
+        compiler_version="15",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="debian",
+        os_version="trixie",
+        compiler_name="clang",
+        compiler_version="21",
+        image_sha=DEBIAN_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                build_modes=[BuildMode.UNITY_OFF],
+                build_types=[BuildType.DEBUG],
+                triggers=[Trigger.MERGE],
+            ),
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+]
+
+# The RHEL distros to build configurations for.
+#
+# We have the following distros available:
+# - RHEL 8: GCC 14, Clang "any"
+# - RHEL 9: GCC 12-14, Clang "any"
+# - RHEL 10: GCC 14, Clang "any"
+RHEL_DISTROS = [
+    Distro(
+        os_name="rhel",
+        os_version="8",
+        compiler_name="gcc",
+        compiler_version="14",
+        image_sha=RHEL_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="rhel",
+        os_version="8",
+        compiler_name="clang",
+        compiler_version="any",
+        image_sha=RHEL_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="rhel",
+        os_version="9",
+        compiler_name="gcc",
+        compiler_version="12",
+        image_sha=RHEL_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                build_modes=[BuildMode.UNITY_ON],
+                build_types=[BuildType.DEBUG],
+                triggers=[Trigger.COMMIT],
+            ),
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                build_modes=[BuildMode.UNITY_ON],
+                build_types=[BuildType.RELEASE],
+                triggers=[Trigger.MERGE],
+            ),
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="rhel",
+        os_version="9",
+        compiler_name="gcc",
+        compiler_version="13",
+        image_sha=RHEL_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="rhel",
+        os_version="10",
+        compiler_name="clang",
+        compiler_version="any",
+        image_sha=RHEL_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+]
+
+# The Ubuntu distros to build configurations for.
+#
+# We have the following distros available:
+# - Ubuntu Jammy (22.04): GCC 12
+# - Ubuntu Noble (24.04): GCC 13-14, Clang 16-20
+UBUNTU_DISTROS = [
+    Distro(
+        os_name="ubuntu",
+        os_version="jammy",
+        compiler_name="gcc",
+        compiler_version="12",
+        image_sha=UBUNTU_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="ubuntu",
+        os_version="noble",
+        compiler_name="gcc",
+        compiler_version="13",
+        image_sha=UBUNTU_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                build_modes=[BuildMode.UNITY_ON],
+                build_types=[BuildType.RELEASE],
+                triggers=[Trigger.MERGE],
+            ),
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="ubuntu",
+        os_version="noble",
+        compiler_name="gcc",
+        compiler_version="14",
+        image_sha=UBUNTU_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="ubuntu",
+        os_version="noble",
+        compiler_name="clang",
+        compiler_version="17",
+        image_sha=UBUNTU_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                build_modes=[BuildMode.UNITY_OFF],
+                build_types=[BuildType.DEBUG],
+                triggers=[Trigger.MERGE],
+            ),
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="ubuntu",
+        os_version="noble",
+        compiler_name="clang",
+        compiler_version="18",
+        image_sha=UBUNTU_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="ubuntu",
+        os_version="noble",
+        compiler_name="clang",
+        compiler_version="19",
+        image_sha=UBUNTU_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_ARM64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+    Distro(
+        os_name="ubuntu",
+        os_version="noble",
+        compiler_name="clang",
+        compiler_version="20",
+        image_sha=UBUNTU_SHA,
+        specs=[
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                build_modes=[BuildMode.UNITY_ON],
+                build_types=[BuildType.DEBUG],
+                triggers=[Trigger.COMMIT],
+            ),
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                build_modes=[BuildMode.UNITY_OFF],
+                build_types=[BuildType.RELEASE],
+                triggers=[Trigger.MERGE],
+            ),
+            Spec(
+                archs=[Arch.LINUX_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+]

.github/scripts/strategy-matrix/macos.json

@@ -1,19 +0,0 @@
-{
-  "architecture": [
-    {
-      "platform": "macos/arm64",
-      "runner": ["self-hosted", "macOS", "ARM64", "mac-runner-m1"]
-    }
-  ],
-  "os": [
-    {
-      "distro_name": "macos",
-      "distro_version": "",
-      "compiler_name": "",
-      "compiler_version": "",
-      "image_sha": ""
-    }
-  ],
-  "build_type": ["Debug", "Release"],
-  "cmake_args": ["-DCMAKE_POLICY_VERSION_MINIMUM=3.5"]
-}

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

@@ -0,0 +1,20 @@
+from helpers.defs import *
+from helpers.enums import *
+
+DISTROS = [
+    Distro(
+        os_name="macos",
+        specs=[
+            Spec(
+                archs=[Arch.MACOS_ARM64],
+                build_modes=[BuildMode.UNITY_OFF],
+                build_types=[BuildType.DEBUG],
+                triggers=[Trigger.COMMIT, Trigger.MERGE],
+            ),
+            Spec(
+                archs=[Arch.MACOS_ARM64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+]

.github/scripts/strategy-matrix/windows.json

@@ -1,19 +0,0 @@
-{
-  "architecture": [
-    {
-      "platform": "windows/amd64",
-      "runner": ["self-hosted", "Windows", "devbox"]
-    }
-  ],
-  "os": [
-    {
-      "distro_name": "windows",
-      "distro_version": "",
-      "compiler_name": "",
-      "compiler_version": "",
-      "image_sha": ""
-    }
-  ],
-  "build_type": ["Debug", "Release"],
-  "cmake_args": [""]
-}

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

@@ -0,0 +1,20 @@
+from helpers.defs import *
+from helpers.enums import *
+
+DISTROS = [
+    Distro(
+        os_name="windows",
+        specs=[
+            Spec(
+                archs=[Arch.WINDOWS_AMD64],
+                build_modes=[BuildMode.UNITY_ON],
+                build_types=[BuildType.RELEASE],
+                triggers=[Trigger.COMMIT, Trigger.MERGE],
+            ),
+            Spec(
+                archs=[Arch.WINDOWS_AMD64],
+                triggers=[Trigger.SCHEDULE],
+            ),
+        ],
+    ),
+]

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

@@ -1,10 +0,0 @@
-name: Check PR title
-
-on:
-  pull_request:
-    types: [opened, edited, reopened, synchronize]
-    branches: [develop]
-
-jobs:
-  check_title:
-    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@943eb8277e8f4b010fde0c826ce4154c36c39509

.github/workflows/on-pr.yml

@@ -1,8 +1,7 @@
 # This workflow runs all workflows to check, build and test the project on
 # various Linux flavors, as well as on MacOS and Windows, on every push to a
 # user branch. However, it will not run if the pull request is a draft unless it
-# has the 'DraftRunCI' label. For commits to PRs that target a release branch,
-# it also uploads the libxrpl recipe to the Conan remote.
+# has the 'DraftRunCI' label.
 name: PR
 
 on:
@@ -33,7 +32,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
       - name: Determine changed files
         # This step checks whether any files have changed that should
         # cause the next jobs to run. We do it this way rather than
@@ -46,7 +45,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@ed68ef82c095e0d48ec87eccea555d944a631a4c # v46.0.5
         with:
           files: |
             # These paths are unique to `on-pr.yml`.
@@ -54,23 +53,19 @@ jobs:
             .github/scripts/rename/**
             .github/workflows/reusable-check-levelization.yml
             .github/workflows/reusable-check-rename.yml
+            .github/workflows/reusable-notify-clio.yml
             .github/workflows/on-pr.yml
 
             # Keep the paths below in sync with those in `on-trigger.yml`.
             .github/actions/build-deps/**
             .github/actions/build-test/**
-            .github/actions/generate-version/**
             .github/actions/setup-conan/**
             .github/scripts/strategy-matrix/**
             .github/workflows/reusable-build.yml
             .github/workflows/reusable-build-test-config.yml
             .github/workflows/reusable-build-test.yml
-            .github/workflows/reusable-clang-tidy.yml
-            .github/workflows/reusable-clang-tidy-files.yml
             .github/workflows/reusable-strategy-matrix.yml
             .github/workflows/reusable-test.yml
-            .github/workflows/reusable-upload-recipe.yml
-            .clang-tidy
             .codecov.yml
             cmake/**
             conan/**
@@ -110,17 +105,6 @@ jobs:
     if: ${{ needs.should-run.outputs.go == 'true' }}
     uses: ./.github/workflows/reusable-check-rename.yml
 
-  clang-tidy:
-    needs: should-run
-    if: ${{ needs.should-run.outputs.go == 'true' }}
-    uses: ./.github/workflows/reusable-clang-tidy.yml
-    permissions:
-      issues: write
-      contents: read
-    with:
-      check_only_changed: true
-      create_issue_on_failure: false
-
   build-test:
     needs: should-run
     if: ${{ needs.should-run.outputs.go == 'true' }}
@@ -128,51 +112,29 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [linux, macos, windows]
+        platform: [linux, macos, windows]
     with:
-      # Enable ccache only for events targeting the XRPLF repository, since
-      # other accounts will not have access to our remote cache storage.
-      ccache_enabled: ${{ github.repository_owner == 'XRPLF' }}
-      os: ${{ matrix.os }}
+      platform: ${{ matrix.platform }}
+      trigger: commit
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-  upload-recipe:
+  notify-clio:
     needs:
       - should-run
       - build-test
-    # Only run when committing to a PR that targets a release branch.
-    if: ${{ github.repository == 'XRPLF/rippled' && needs.should-run.outputs.go == 'true' && github.event_name == 'pull_request' && startsWith(github.event.pull_request.base.ref, 'release') }}
-    uses: ./.github/workflows/reusable-upload-recipe.yml
+    if: ${{ needs.should-run.outputs.go == 'true' && (startsWith(github.base_ref, 'release') || github.base_ref == 'master') }}
+    uses: ./.github/workflows/reusable-notify-clio.yml
     secrets:
-      remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.CONAN_REMOTE_PASSWORD }}
-
-  notify-clio:
-    needs: upload-recipe
-    runs-on: ubuntu-latest
-    steps:
-      # Notify the Clio repository about the newly proposed release version, so
-      # it can be checked for compatibility before the release is actually made.
-      - name: Notify Clio
-        env:
-          GH_TOKEN: ${{ secrets.CLIO_NOTIFY_TOKEN }}
-          PR_URL: ${{ github.event.pull_request.html_url }}
-        run: |
-          gh api --method POST -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" \
-          /repos/xrplf/clio/dispatches -f "event_type=check_libxrpl" \
-          -F "client_payload[ref]=${{ needs.upload-recipe.outputs.recipe_ref }}" \
-          -F "client_payload[pr_url]=${PR_URL}"
+      clio_notify_token: ${{ secrets.CLIO_NOTIFY_TOKEN }}
+      conan_remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
+      conan_remote_password: ${{ secrets.CONAN_REMOTE_PASSWORD }}
 
   passed:
     if: failure() || cancelled()
     needs:
-      - check-levelization
-      - check-rename
-      - clang-tidy
       - build-test
-      - upload-recipe
-      - notify-clio
+      - check-levelization
     runs-on: ubuntu-latest
     steps:
       - name: Fail

.github/workflows/on-tag.yml

@@ -1,24 +0,0 @@
-# This workflow uploads the libxrpl recipe to the Conan remote when a versioned
-# tag is pushed.
-name: Tag
-
-on:
-  push:
-    tags:
-      - "v*"
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  upload-recipe:
-    if: ${{ github.repository == 'XRPLF/rippled' }}
-    uses: ./.github/workflows/reusable-upload-recipe.yml
-    secrets:
-      remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.CONAN_REMOTE_PASSWORD }}

.github/workflows/on-trigger.yml

@@ -1,7 +1,9 @@
-# This workflow runs all workflows to build and test the code on various Linux
-# flavors, as well as on MacOS and Windows, on a scheduled basis, on merge into
-# the 'develop' or 'release*' branches, or when requested manually. Upon pushes
-# to the develop branch it also uploads the libxrpl recipe to the Conan remote.
+# This workflow runs all workflows to build the dependencies required for the
+# project on various Linux flavors, as well as on MacOS and Windows, on a
+# scheduled basis, on merge into the 'develop', 'release', or 'master' branches,
+# or manually. The missing commits check is only run when the code is merged
+# into the 'develop' or 'release' branches, and the documentation is built when
+# the code is merged into the 'develop' branch.
 name: Trigger
 
 on:
@@ -9,6 +11,7 @@ on:
     branches:
       - "develop"
       - "release*"
+      - "master"
     paths:
       # These paths are unique to `on-trigger.yml`.
       - ".github/workflows/on-trigger.yml"
@@ -16,18 +19,13 @@ on:
       # Keep the paths below in sync with those in `on-pr.yml`.
       - ".github/actions/build-deps/**"
       - ".github/actions/build-test/**"
-      - ".github/actions/generate-version/**"
       - ".github/actions/setup-conan/**"
       - ".github/scripts/strategy-matrix/**"
       - ".github/workflows/reusable-build.yml"
       - ".github/workflows/reusable-build-test-config.yml"
       - ".github/workflows/reusable-build-test.yml"
-      - ".github/workflows/reusable-clang-tidy.yml"
-      - ".github/workflows/reusable-clang-tidy-files.yml"
       - ".github/workflows/reusable-strategy-matrix.yml"
       - ".github/workflows/reusable-test.yml"
-      - ".github/workflows/reusable-upload-recipe.yml"
-      - ".clang-tidy"
       - ".codecov.yml"
       - "cmake/**"
       - "conan/**"
@@ -63,38 +61,15 @@ defaults:
     shell: bash
 
 jobs:
-  clang-tidy:
-    uses: ./.github/workflows/reusable-clang-tidy.yml
-    permissions:
-      issues: write
-      contents: read
-    with:
-      check_only_changed: false
-      create_issue_on_failure: ${{ github.event_name == 'schedule' }}
-
   build-test:
     uses: ./.github/workflows/reusable-build-test.yml
     strategy:
       fail-fast: ${{ github.event_name == 'merge_group' }}
       matrix:
-        os: [linux, macos, windows]
+        platform: [linux, macos, windows]
     with:
-      # Enable ccache only for events targeting the XRPLF repository, since
-      # other accounts will not have access to our remote cache storage.
-      # However, we do not enable ccache for events targeting a release branch,
-      # to protect against the rare case that the output produced by ccache is
-      # not identical to a regular compilation.
-      ccache_enabled: ${{ github.repository_owner == 'XRPLF' && !startsWith(github.ref, 'refs/heads/release') }}
-      os: ${{ matrix.os }}
-      strategy_matrix: ${{ github.event_name == 'schedule' && 'all' || 'minimal' }}
+      platform: ${{ matrix.platform }}
+      # The workflow dispatch event uses the same trigger as the schedule event.
+      trigger: ${{ github.event_name == 'push' && 'merge' || 'schedule' }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
-  upload-recipe:
-    needs: build-test
-    # Only run when pushing to the develop branch.
-    if: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
-    uses: ./.github/workflows/reusable-upload-recipe.yml
-    secrets:
-      remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.CONAN_REMOTE_PASSWORD }}

.github/workflows/pre-commit.yml

@@ -3,15 +3,13 @@ name: Run pre-commit hooks
 on:
   pull_request:
   push:
-    branches:
-      - "develop"
-      - "release*"
+    branches: [develop, release, master]
   workflow_dispatch:
 
 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@44856eb0d6ecb7d376370244324ab3dc8b863bad
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@34790936fae4c6c751f62ec8c06696f9c1a5753a
     with:
       runs_on: ubuntu-latest
-      container: '{ "image": "ghcr.io/xrplf/ci/tools-rippled-pre-commit:sha-41ec7c1" }'
+      container: '{ "image": "ghcr.io/xrplf/ci/tools-rippled-pre-commit:sha-a8c7be1" }'

.github/workflows/publish-docs.yml

@@ -4,18 +4,6 @@ name: Build and publish documentation
 
 on:
   push:
-    branches:
-      - "develop"
-      - "release*"
-    paths:
-      - ".github/workflows/publish-docs.yml"
-      - "*.md"
-      - "**/*.md"
-      - "docs/**"
-      - "include/**"
-      - "src/libxrpl/**"
-      - "src/xrpld/**"
-  pull_request:
     paths:
       - ".github/workflows/publish-docs.yml"
       - "*.md"
@@ -35,25 +23,20 @@ defaults:
 
 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: 2
 
 jobs:
-  build:
+  publish:
     runs-on: ubuntu-latest
     container: ghcr.io/xrplf/ci/tools-rippled-documentation:sha-a8c7be1
+    permissions:
+      contents: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@2cbf481018d930656e9276fcc20dc0e3a0be5b6d
-        with:
-          enable_ccache: false
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Get number of processors
-        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
+        uses: XRPLF/actions/get-nproc@2ece4ec6ab7de266859a6f053571425b2bd684b6
         id: nproc
         with:
           subtract: ${{ env.NPROC_SUBTRACT }}
@@ -81,23 +64,9 @@ jobs:
           cmake -Donly_docs=ON ..
           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
+      - name: Publish documentation
+        if: ${{ github.ref_type == 'branch' && github.ref_name == github.event.repository.default_branch }}
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
-          path: ${{ env.BUILD_DIR }}/docs/html
-
-  deploy:
-    if: ${{ github.event_name == 'push' }}
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deploy.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deploy
-        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.BUILD_DIR }}/docs/html

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

@@ -3,21 +3,10 @@ name: Build and test configuration
 on:
   workflow_call:
     inputs:
-      build_only:
-        description: 'Whether to only build or to build and test the code ("true", "false").'
-        required: true
-        type: boolean
-
       build_type:
         description: 'The build type to use ("Debug", "Release").'
-        required: true
         type: string
-
-      ccache_enabled:
-        description: "Whether to enable ccache."
-        required: false
-        type: boolean
-        default: false
+        required: true
 
       cmake_args:
         description: "Additional arguments to pass to CMake."
@@ -27,8 +16,23 @@ on:
 
       cmake_target:
         description: "The CMake target to build."
-        required: true
         type: string
+        required: true
+
+      enable_tests:
+        description: "Whether to run the tests."
+        required: true
+        type: boolean
+
+      enable_package:
+        description: "Whether to publish a package."
+        required: true
+        type: boolean
+
+      enable_image:
+        description: "Whether to publish an image."
+        required: true
+        type: boolean
 
       runs_on:
         description: Runner to run the job on as a JSON string
@@ -51,12 +55,6 @@ on:
         type: number
         default: 2
 
-      sanitizers:
-        description: "The sanitizers to enable."
-        required: false
-        type: string
-        default: ""
-
     secrets:
       CODECOV_TOKEN:
         description: "The Codecov token to use for uploading coverage reports."
@@ -78,55 +76,31 @@ jobs:
     container: ${{ inputs.image != '' && inputs.image || null }}
     timeout-minutes: 60
     env:
-      # Use a namespace to keep the objects separate for each configuration.
-      CCACHE_NAMESPACE: ${{ inputs.config_name }}
-      # Ccache supports both Redis and HTTP endpoints.
-      # * For Redis, use the following format: redis://ip:port, see
-      #   https://github.com/ccache/ccache/wiki/Redis-storage. Note that TLS is
-      #   not directly supported by ccache, and requires use of a proxy.
-      # * For HTTP use the following format: http://ip:port/cache when using
-      #   nginx as backend or http://ip:port|layout=bazel when using Bazel
-      #   Remote Cache, see https://github.com/ccache/ccache/wiki/HTTP-storage.
-      #   Note that HTTPS is not directly supported by ccache.
-      CCACHE_REMOTE_ONLY: true
-      CCACHE_REMOTE_STORAGE: http://cache.dev.ripplex.io:8080|layout=bazel
-      # Ignore the creation and modification timestamps on files, since the
-      # header files are copied into separate directories by CMake, which will
-      # otherwise result in cache misses.
-      CCACHE_SLOPPINESS: include_file_ctime,include_file_mtime
-      # Determine if coverage and voidstar should be enabled.
-      COVERAGE_ENABLED: ${{ contains(inputs.cmake_args, '-Dcoverage=ON') }}
-      VOIDSTAR_ENABLED: ${{ contains(inputs.cmake_args, '-Dvoidstar=ON') }}
-      SANITIZERS_ENABLED: ${{ inputs.sanitizers != '' }}
+      ENABLED_VOIDSTAR: ${{ contains(inputs.cmake_args, '-Dvoidstar=ON') }}
+      ENABLED_COVERAGE: ${{ contains(inputs.cmake_args, '-Dcoverage=ON') }}
     steps:
       - name: Cleanup workspace (macOS and Windows)
         if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
-        uses: XRPLF/actions/cleanup-workspace@cf0433aa74563aead044a1e395610c96d65a37cf
+        uses: XRPLF/actions/cleanup-workspace@2ece4ec6ab7de266859a6f053571425b2bd684b6
 
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@2cbf481018d930656e9276fcc20dc0e3a0be5b6d
+        uses: XRPLF/actions/prepare-runner@2ece4ec6ab7de266859a6f053571425b2bd684b6
         with:
-          enable_ccache: ${{ inputs.ccache_enabled }}
-
-      - name: Set ccache log file
-        if: ${{ inputs.ccache_enabled && runner.debug == '1' }}
-        run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >> "${GITHUB_ENV}"
+          disable_ccache: false
 
       - name: Print build environment
         uses: ./.github/actions/print-env
 
       - name: Get number of processors
-        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
+        uses: XRPLF/actions/get-nproc@2ece4ec6ab7de266859a6f053571425b2bd684b6
         id: nproc
         with:
           subtract: ${{ inputs.nproc_subtract }}
 
       - name: Setup Conan
-        env:
-          SANITIZERS: ${{ inputs.sanitizers }}
         uses: ./.github/actions/setup-conan
 
       - name: Build dependencies
@@ -137,13 +111,11 @@ jobs:
           # Set the verbosity to "quiet" for Windows to avoid an excessive
           # amount of logs. For other OSes, the "verbose" logs are more useful.
           log_verbosity: ${{ runner.os == 'Windows' && 'quiet' || 'verbose' }}
-          sanitizers: ${{ inputs.sanitizers }}
 
       - name: Configure CMake
         working-directory: ${{ env.BUILD_DIR }}
         env:
           BUILD_TYPE: ${{ inputs.build_type }}
-          SANITIZERS: ${{ inputs.sanitizers }}
           CMAKE_ARGS: ${{ inputs.cmake_args }}
         run: |
           cmake \
@@ -166,18 +138,9 @@ jobs:
             --parallel "${BUILD_NPROC}" \
             --target "${CMAKE_TARGET}"
 
-      - name: Show ccache statistics
-        if: ${{ inputs.ccache_enabled }}
-        run: |
-          ccache --show-stats -vv
-          if [ '${{ runner.debug }}' = '1' ]; then
-            cat "${CCACHE_LOGFILE}"
-            curl ${CCACHE_REMOTE_STORAGE%|*}/status || true
-          fi
-
       - name: Upload the binary (Linux)
-        if: ${{ github.repository == 'XRPLF/rippled' && runner.os == 'Linux' }}
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        if: ${{ github.repository_owner == 'XRPLF' && runner.os == 'Linux' }}
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: xrpld-${{ inputs.config_name }}
           path: ${{ env.BUILD_DIR }}/xrpld
@@ -185,7 +148,7 @@ jobs:
           if-no-files-found: error
 
       - name: Check linking (Linux)
-        if: ${{ runner.os == 'Linux' && env.SANITIZERS_ENABLED == 'false' }}
+        if: ${{ runner.os == 'Linux' }}
         working-directory: ${{ env.BUILD_DIR }}
         run: |
           ldd ./xrpld
@@ -197,21 +160,13 @@ jobs:
           fi
 
       - name: Verify presence of instrumentation (Linux)
-        if: ${{ runner.os == 'Linux' && env.VOIDSTAR_ENABLED == 'true' }}
+        if: ${{ runner.os == 'Linux' && env.ENABLED_VOIDSTAR == 'true' }}
         working-directory: ${{ env.BUILD_DIR }}
         run: |
           ./xrpld --version | grep libvoidstar
 
-      - name: Set sanitizer options
-        if: ${{ !inputs.build_only && env.SANITIZERS_ENABLED == 'true' }}
-        run: |
-          echo "ASAN_OPTIONS=print_stacktrace=1:detect_container_overflow=0:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/asan.supp" >> ${GITHUB_ENV}
-          echo "TSAN_OPTIONS=second_deadlock_stack=1:halt_on_error=0:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/tsan.supp" >> ${GITHUB_ENV}
-          echo "UBSAN_OPTIONS=suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/ubsan.supp" >> ${GITHUB_ENV}
-          echo "LSAN_OPTIONS=suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/lsan.supp" >> ${GITHUB_ENV}
-
       - name: Run the separate tests
-        if: ${{ !inputs.build_only }}
+        if: ${{ inputs.enable_tests }}
         working-directory: ${{ env.BUILD_DIR }}
         # Windows locks some of the build files while running tests, and parallel jobs can collide
         env:
@@ -224,7 +179,7 @@ jobs:
             -j "${PARALLELISM}"
 
       - name: Run the embedded tests
-        if: ${{ !inputs.build_only }}
+        if: ${{ inputs.enable_tests }}
         working-directory: ${{ runner.os == 'Windows' && format('{0}/{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
         env:
           BUILD_NPROC: ${{ steps.nproc.outputs.nproc }}
@@ -232,7 +187,7 @@ jobs:
           ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}"
 
       - name: Debug failure (Linux)
-        if: ${{ failure() && runner.os == 'Linux' && !inputs.build_only }}
+        if: ${{ (failure() || cancelled()) && runner.os == 'Linux' && inputs.enable_tests }}
         run: |
           echo "IPv4 local port range:"
           cat /proc/sys/net/ipv4/ip_local_port_range
@@ -240,7 +195,7 @@ jobs:
           netstat -an
 
       - name: Prepare coverage report
-        if: ${{ !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
+        if: ${{ github.repository_owner == 'XRPLF' && env.ENABLED_COVERAGE == 'true' }}
         working-directory: ${{ env.BUILD_DIR }}
         env:
           BUILD_NPROC: ${{ steps.nproc.outputs.nproc }}
@@ -253,8 +208,8 @@ jobs:
             --target coverage
 
       - name: Upload coverage report
-        if: ${{ github.repository == 'XRPLF/rippled' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
-        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
+        if: ${{ github.repository_owner == 'XRPLF' && env.ENABLED_COVERAGE == 'true' }}
+        uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24 # v5.4.3
         with:
           disable_search: true
           disable_telem: true

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

@@ -8,24 +8,14 @@ name: Build and test
 on:
   workflow_call:
     inputs:
-      ccache_enabled:
-        description: "Whether to enable ccache."
+      platform:
+        description: "The platform to generate the strategy matrix for ('linux', 'macos', 'windows'). If not provided all platforms are used."
         required: false
-        type: boolean
-        default: false
-
-      os:
-        description: 'The operating system to use for the build ("linux", "macos", "windows").'
+        type: string
+      trigger:
+        description: "The trigger that caused the workflow to run ('commit', 'label', 'merge', 'schedule')."
         required: true
         type: string
-
-      strategy_matrix:
-        # TODO: Support additional strategies, e.g. "ubuntu" for generating all Ubuntu configurations.
-        description: 'The strategy matrix to use for generating the configurations ("minimal", "all").'
-        required: false
-        type: string
-        default: "minimal"
-
     secrets:
       CODECOV_TOKEN:
         description: "The Codecov token to use for uploading coverage reports."
@@ -36,8 +26,8 @@ jobs:
   generate-matrix:
     uses: ./.github/workflows/reusable-strategy-matrix.yml
     with:
-      os: ${{ inputs.os }}
-      strategy_matrix: ${{ inputs.strategy_matrix }}
+      platform: ${{ inputs.platform }}
+      trigger: ${{ inputs.trigger }}
 
   # Build and test the binary for each configuration.
   build-test-config:
@@ -49,14 +39,14 @@ jobs:
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
       max-parallel: 10
     with:
-      build_only: ${{ matrix.build_only }}
       build_type: ${{ matrix.build_type }}
-      ccache_enabled: ${{ inputs.ccache_enabled }}
       cmake_args: ${{ matrix.cmake_args }}
       cmake_target: ${{ matrix.cmake_target }}
-      runs_on: ${{ toJSON(matrix.architecture.runner) }}
-      image: ${{ contains(matrix.architecture.platform, 'linux') && format('ghcr.io/xrplf/ci/{0}-{1}:{2}-{3}-sha-{4}', matrix.os.distro_name, matrix.os.distro_version, matrix.os.compiler_name, matrix.os.compiler_version, matrix.os.image_sha) || '' }}
+      enable_tests: ${{ matrix.enable_tests }}
+      enable_package: ${{ matrix.enable_package }}
+      enable_image: ${{ matrix.enable_image }}
+      runs_on: ${{ toJson(matrix.runs_on) }}
+      image: ${{ matrix.image }}
       config_name: ${{ matrix.config_name }}
-      sanitizers: ${{ matrix.sanitizers }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

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

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
       - name: Check levelization
         run: .github/scripts/levelization/generate.sh
       - name: Check for differences

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

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
       - name: Check definitions
         run: .github/scripts/rename/definitions.sh .
       - name: Check copyright notices
@@ -29,10 +29,6 @@ jobs:
         run: .github/scripts/rename/binary.sh .
       - name: Check namespaces
         run: .github/scripts/rename/namespace.sh .
-      - name: Check config name
-        run: .github/scripts/rename/config.sh .
-      - name: Check include guards
-        run: .github/scripts/rename/include.sh .
       - name: Check for differences
         env:
           MESSAGE: |

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

@@ -1,162 +0,0 @@
-name: Run clang-tidy on files
-
-on:
-  workflow_call:
-    inputs:
-      files:
-        description: "List of files to check (empty means check all files)"
-        type: string
-        default: ""
-      create_issue_on_failure:
-        description: "Whether to create an issue if the check failed"
-        type: boolean
-        default: false
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  # Conan installs the generators in the build/generators directory, see the
-  # layout() method in conanfile.py. We then run CMake from the build directory.
-  BUILD_DIR: build
-  BUILD_TYPE: Release
-
-jobs:
-  run-clang-tidy:
-    name: Run clang tidy
-    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: "ghcr.io/xrplf/ci/debian-trixie:clang-21-sha-53033a2"
-    permissions:
-      issues: write
-      contents: read
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@2cbf481018d930656e9276fcc20dc0e3a0be5b6d
-        with:
-          enable_ccache: false
-
-      - name: Print build environment
-        uses: ./.github/actions/print-env
-
-      - name: Get number of processors
-        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
-        id: nproc
-
-      - name: Setup Conan
-        uses: ./.github/actions/setup-conan
-
-      - name: Build dependencies
-        uses: ./.github/actions/build-deps
-        with:
-          build_nproc: ${{ steps.nproc.outputs.nproc }}
-          build_type: ${{ env.BUILD_TYPE }}
-          log_verbosity: verbose
-
-      - name: Configure CMake
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          cmake \
-            -G 'Ninja' \
-            -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-            -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
-            -Dtests=ON \
-            -Dwerr=ON \
-            -Dxrpld=ON \
-            ..
-
-      # clang-tidy needs headers generated from proto files
-      - name: Build libxrpl.libpb
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          ninja -j ${{ steps.nproc.outputs.nproc }} xrpl.libpb
-
-      - name: Run clang tidy
-        id: run_clang_tidy
-        continue-on-error: true
-        env:
-          FILES: ${{ inputs.files }}
-        run: |
-          run-clang-tidy -j ${{ steps.nproc.outputs.nproc }} -p "$BUILD_DIR" $FILES 2>&1 | tee clang-tidy-output.txt
-
-      - name: Upload clang-tidy output
-        if: steps.run_clang_tidy.outcome != 'success'
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
-        with:
-          name: clang-tidy-results
-          path: clang-tidy-output.txt
-          retention-days: 30
-
-      - name: Create an issue
-        if: steps.run_clang_tidy.outcome != 'success' && inputs.create_issue_on_failure
-        id: create_issue
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          # Prepare issue body with clang-tidy output
-          cat > issue.md <<EOF
-          ## Clang-tidy Check Failed
-
-          **Workflow:** ${{ github.workflow }}
-          **Run ID:** ${{ github.run_id }}
-          **Commit:** ${{ github.sha }}
-          **Branch/Ref:** ${{ github.ref }}
-          **Triggered by:** ${{ github.actor }}
-
-          ### Clang-tidy Output:
-          \`\`\`
-          EOF
-
-          # Append clang-tidy output (filter for errors and warnings)
-          if [ -f clang-tidy-output.txt ]; then
-            # Extract lines containing 'error:', 'warning:', or 'note:'
-            grep -E '(error:|warning:|note:)' clang-tidy-output.txt > filtered-output.txt || true
-
-            # If filtered output is empty, use original (might be a different error format)
-            if [ ! -s filtered-output.txt ]; then
-              cp clang-tidy-output.txt filtered-output.txt
-            fi
-
-            # Truncate if too large
-            head -c 60000 filtered-output.txt >> issue.md
-            if [ "$(wc -c < filtered-output.txt)" -gt 60000 ]; then
-              echo "" >> issue.md
-              echo "... (output truncated, see artifacts for full output)" >> issue.md
-            fi
-
-            rm filtered-output.txt
-          else
-            echo "No output file found" >> issue.md
-          fi
-
-          cat >> issue.md <<EOF
-          \`\`\`
-
-          **Workflow run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-
-          ---
-          *This issue was automatically created by the clang-tidy workflow.*
-          EOF
-
-          # Create the issue
-          gh issue create \
-            --label "Bug,Clang-tidy" \
-            --title "Clang-tidy check failed" \
-            --body-file ./issue.md \
-            > create_issue.log
-
-          created_issue="$(sed 's|.*/||' create_issue.log)"
-          echo "created_issue=$created_issue" >> $GITHUB_OUTPUT
-          echo "Created issue #$created_issue"
-
-          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'
-        run: |
-          echo "Clang-tidy check failed!"
-          exit 1

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

@@ -1,55 +0,0 @@
-name: Clang-tidy check
-
-on:
-  workflow_call:
-    inputs:
-      check_only_changed:
-        description: "Check only changed files in PR. If false, checks all files in the repository."
-        type: boolean
-        default: false
-      create_issue_on_failure:
-        description: "Whether to create an issue if the check failed"
-        type: boolean
-        default: false
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  determine-files:
-    name: Determine files to check
-    if: ${{ inputs.check_only_changed }}
-    runs-on: ubuntu-latest
-    outputs:
-      clang_tidy_config_changed: ${{ steps.changed_clang_tidy.outputs.any_changed }}
-      any_cpp_changed: ${{ steps.changed_files.outputs.any_changed }}
-      all_changed_files: ${{ steps.changed_files.outputs.all_changed_files }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Get changed C++ files
-        id: changed_files
-        uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
-        with:
-          files: |
-            **/*.cpp
-            **/*.h
-            **/*.ipp
-          separator: " "
-
-      - name: Get changed clang-tidy configuration
-        id: changed_clang_tidy
-        uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
-        with:
-          files: |
-            .clang-tidy
-
-  run-clang-tidy:
-    needs: [determine-files]
-    if: ${{ always() && !cancelled() && (!inputs.check_only_changed || needs.determine-files.outputs.any_cpp_changed == 'true' || needs.determine-files.outputs.clang_tidy_config_changed == 'true') }}
-    uses: ./.github/workflows/reusable-clang-tidy-files.yml
-    with:
-      files: ${{ needs.determine-files.outputs.clang_tidy_config_changed == 'true' && '' || (inputs.check_only_changed && needs.determine-files.outputs.all_changed_files || '') }}
-      create_issue_on_failure: ${{ inputs.create_issue_on_failure }}

.github/workflows/reusable-notify-clio.yml

@@ -0,0 +1,91 @@
+# This workflow exports the built libxrpl package to the Conan remote on a
+# a channel named after the pull request, and notifies the Clio repository about
+# the new version so it can check for compatibility.
+name: Notify Clio
+
+# This workflow can only be triggered by other workflows.
+on:
+  workflow_call:
+    inputs:
+      conan_remote_name:
+        description: "The name of the Conan remote to use."
+        required: false
+        type: string
+        default: xrplf
+      conan_remote_url:
+        description: "The URL of the Conan endpoint to use."
+        required: false
+        type: string
+        default: https://conan.ripplex.io
+    secrets:
+      clio_notify_token:
+        description: "The GitHub token to notify Clio about new versions."
+        required: true
+      conan_remote_username:
+        description: "The username for logging into the Conan remote."
+        required: true
+      conan_remote_password:
+        description: "The password for logging into the Conan remote."
+        required: true
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-clio
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  upload:
+    if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    container: ghcr.io/xrplf/ci/ubuntu-noble:gcc-13-sha-5dd7158
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+      - name: Generate outputs
+        id: generate
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          echo 'Generating user and channel.'
+          echo "user=clio" >> "${GITHUB_OUTPUT}"
+          echo "channel=pr_${PR_NUMBER}" >> "${GITHUB_OUTPUT}"
+          echo 'Extracting version.'
+          echo "version=$(cat src/libxrpl/protocol/BuildInfo.cpp | grep "versionString =" | awk -F '"' '{print $2}')" >> "${GITHUB_OUTPUT}"
+      - name: Calculate conan reference
+        id: conan_ref
+        run: |
+          echo "conan_ref=${{ steps.generate.outputs.version }}@${{ steps.generate.outputs.user }}/${{ steps.generate.outputs.channel }}" >> "${GITHUB_OUTPUT}"
+      - name: Set up Conan
+        uses: ./.github/actions/setup-conan
+        with:
+          conan_remote_name: ${{ inputs.conan_remote_name }}
+          conan_remote_url: ${{ inputs.conan_remote_url }}
+      - name: Log into Conan remote
+        env:
+          CONAN_REMOTE_NAME: ${{ inputs.conan_remote_name }}
+        run: conan remote login "${CONAN_REMOTE_NAME}" "${{ secrets.conan_remote_username }}" --password "${{ secrets.conan_remote_password }}"
+      - name: Upload package
+        env:
+          CONAN_REMOTE_NAME: ${{ inputs.conan_remote_name }}
+        run: |
+          conan export --user=${{ steps.generate.outputs.user }} --channel=${{ steps.generate.outputs.channel }} .
+          conan upload --confirm --check --remote="${CONAN_REMOTE_NAME}" xrpl/${{ steps.conan_ref.outputs.conan_ref }}
+    outputs:
+      conan_ref: ${{ steps.conan_ref.outputs.conan_ref }}
+
+  notify:
+    needs: upload
+    runs-on: ubuntu-latest
+    steps:
+      - name: Notify Clio
+        env:
+          GH_TOKEN: ${{ secrets.clio_notify_token }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+        run: |
+          gh api --method POST -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" \
+          /repos/xrplf/clio/dispatches -f "event_type=check_libxrpl" \
+          -F "client_payload[conan_ref]=${{ needs.upload.outputs.conan_ref }}" \
+          -F "client_payload[pr_url]=${PR_URL}"

.github/workflows/reusable-strategy-matrix.yml

@@ -3,16 +3,14 @@ name: Generate strategy matrix
 on:
   workflow_call:
     inputs:
-      os:
-        description: 'The operating system to use for the build ("linux", "macos", "windows").'
+      platform:
+        description: "The platform to generate the strategy matrix for ('linux', 'macos', 'windows'). If not provided all platforms are used."
         required: false
         type: string
-      strategy_matrix:
-        # TODO: Support additional strategies, e.g. "ubuntu" for generating all Ubuntu configurations.
-        description: 'The strategy matrix to use for generating the configurations ("minimal", "all").'
-        required: false
+      trigger:
+        description: "The trigger that caused the workflow to run ('commit', 'label', 'merge', 'schedule')."
+        required: true
         type: string
-        default: "minimal"
     outputs:
       matrix:
         description: "The generated strategy matrix."
@@ -29,10 +27,10 @@ jobs:
       matrix: ${{ steps.generate.outputs.matrix }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: 3.13
 
@@ -40,6 +38,6 @@ jobs:
         working-directory: .github/scripts/strategy-matrix
         id: generate
         env:
-          GENERATE_CONFIG: ${{ inputs.os != '' && format('--config={0}.json', inputs.os) || '' }}
-          GENERATE_OPTION: ${{ inputs.strategy_matrix == 'all' && '--all' || '' }}
-        run: ./generate.py ${GENERATE_OPTION} ${GENERATE_CONFIG} >> "${GITHUB_OUTPUT}"
+          PLATFORM: ${{ inputs.platform != '' && format('--platform={0}', inputs.platform) || '' }}
+          TRIGGER: ${{ format('--trigger={0}', inputs.trigger) }}
+        run: ./generate.py ${PLATFORM} ${TRIGGER} >> "${GITHUB_OUTPUT}"

.github/workflows/reusable-upload-recipe.yml

@@ -1,103 +0,0 @@
-# This workflow exports the built libxrpl package to the Conan remote.
-name: Upload Conan recipe
-
-# This workflow can only be triggered by other workflows.
-on:
-  workflow_call:
-    inputs:
-      remote_name:
-        description: "The name of the Conan remote to use."
-        required: false
-        type: string
-        default: xrplf
-      remote_url:
-        description: "The URL of the Conan endpoint to use."
-        required: false
-        type: string
-        default: https://conan.ripplex.io
-
-    secrets:
-      remote_username:
-        description: "The username for logging into the Conan remote."
-        required: true
-      remote_password:
-        description: "The password for logging into the Conan remote."
-        required: true
-
-    outputs:
-      recipe_ref:
-        description: "The Conan recipe reference ('name/version') that was uploaded."
-        value: ${{ jobs.upload.outputs.ref }}
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}-upload-recipe
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  upload:
-    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/ci/ubuntu-noble:gcc-13-sha-5dd7158
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Generate build version number
-        id: version
-        uses: ./.github/actions/generate-version
-
-      - name: Set up Conan
-        uses: ./.github/actions/setup-conan
-        with:
-          remote_name: ${{ inputs.remote_name }}
-          remote_url: ${{ inputs.remote_url }}
-
-      - name: Log into Conan remote
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
-          REMOTE_USERNAME: ${{ secrets.remote_username }}
-          REMOTE_PASSWORD: ${{ secrets.remote_password }}
-        run: conan remote login "${REMOTE_NAME}" "${REMOTE_USERNAME}" --password "${REMOTE_PASSWORD}"
-
-      - name: Upload Conan recipe (version)
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
-        run: |
-          conan export . --version=${{ steps.version.outputs.version }}
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/${{ steps.version.outputs.version }}
-
-      # When this workflow is triggered by a push event, it will always be when merging into the
-      # 'develop' branch, see on-trigger.yml.
-      - name: Upload Conan recipe (develop)
-        if: ${{ github.event_name == 'push' }}
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
-        run: |
-          conan export . --version=develop
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/develop
-
-      # When this workflow is triggered by a pull request event, it will always be when merging into
-      # one of the 'release' branches, see on-pr.yml.
-      - name: Upload Conan recipe (rc)
-        if: ${{ github.event_name == 'pull_request' }}
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
-        run: |
-          conan export . --version=rc
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/rc
-
-      # When this workflow is triggered by a tag event, it will always be when tagging a final
-      # release, see on-tag.yml.
-      - name: Upload Conan recipe (release)
-        if: ${{ github.event_name == 'tag' }}
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
-        run: |
-          conan export . --version=release
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/release
-
-    outputs:
-      ref: xrpl/${{ steps.version.outputs.version }}

.github/workflows/telemetry-validation.yml

@@ -1,194 +0,0 @@
-# Telemetry Validation CI Workflow
-#
-# Builds rippled with telemetry enabled, runs the multi-node workload
-# harness, validates all telemetry data, and runs performance benchmarks.
-#
-# This is a separate workflow from the main CI. It runs:
-#   - On manual dispatch (workflow_dispatch)
-#   - On pushes to telemetry-related branches
-#
-# The workflow is intentionally heavyweight (builds rippled, starts Docker
-# services, runs a multi-node cluster) — it validates the full telemetry
-# stack end-to-end rather than individual unit tests.
-#
-# The build steps mirror the main CI pipeline (reusable-build-test-config.yml):
-#   - setup-conan action → build-deps action → cmake configure → cmake build
-# This ensures dependency resolution, toolchain generation, and compiler
-# flags are identical to what the PR workflow uses.
-
-name: Telemetry Validation
-
-on:
-  workflow_dispatch:
-    inputs:
-      rpc_rate:
-        description: "RPC load rate (requests per second)"
-        required: false
-        default: "50"
-      rpc_duration:
-        description: "RPC load duration (seconds)"
-        required: false
-        default: "120"
-      tx_tps:
-        description: "Transaction submit rate (TPS)"
-        required: false
-        default: "5"
-      tx_duration:
-        description: "Transaction submit duration (seconds)"
-        required: false
-        default: "120"
-      run_benchmark:
-        description: "Run performance benchmarks"
-        required: false
-        type: boolean
-        default: false
-
-  push:
-    branches:
-      - "pratik/otel-phase*"
-      - "feature/otel-*"
-      - "feature/telemetry-*"
-    paths:
-      - "docker/telemetry/**"
-      - "include/xrpl/basics/Telemetry*.h"
-      - "src/xrpld/app/misc/Telemetry*"
-
-concurrency:
-  group: telemetry-validation-${{ github.ref }}
-  cancel-in-progress: true
-
-env:
-  BUILD_DIR: build
-
-jobs:
-  validate-telemetry:
-    name: Telemetry Stack Validation
-    runs-on: ubuntu-latest
-    timeout-minutes: 90
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Install system dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y curl jq bc python3 python3-pip ninja-build
-
-      - name: Install Python dependencies
-        run: pip3 install -r docker/telemetry/workload/requirements.txt
-
-      - name: Install Conan
-        run: pip3 install conan
-
-      # ── Build steps (mirrors main CI: setup-conan → build-deps → cmake) ──
-
-      - name: Set up Conan
-        uses: ./.github/actions/setup-conan
-
-      - name: Cache Conan packages
-        uses: actions/cache@v4
-        with:
-          path: ~/.conan2/p
-          key: telemetry-conan-${{ runner.os }}-${{ hashFiles('conanfile.py') }}
-          restore-keys: |
-            telemetry-conan-${{ runner.os }}-
-
-      # Use the same build-deps action as the main CI pipeline.
-      # This runs conan install with --options:host='&:xrpld=True' which
-      # sets xrpld=ON and telemetry=True (default) in the generated
-      # CMake toolchain — no manual -D flags needed.
-      - name: Build dependencies
-        uses: ./.github/actions/build-deps
-        with:
-          build_nproc: 4
-          build_type: Release
-
-      - name: Configure CMake
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          cmake \
-            -G Ninja \
-            -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-            -DCMAKE_BUILD_TYPE=Release \
-            ..
-
-      - name: Build xrpld
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          cmake \
-            --build . \
-            --config Release \
-            --parallel $(nproc) \
-            --target xrpld
-
-      # ── Telemetry validation steps ──
-
-      - name: Make scripts executable
-        run: chmod +x docker/telemetry/workload/*.sh
-
-      - name: Run full telemetry validation
-        id: validation
-        env:
-          XRPLD: ${{ env.BUILD_DIR }}/xrpld
-        run: |
-          ARGS="--xrpld ${{ env.BUILD_DIR }}/xrpld --skip-loki"
-          ARGS="$ARGS --rpc-rate ${{ github.event.inputs.rpc_rate || '50' }}"
-          ARGS="$ARGS --rpc-duration ${{ github.event.inputs.rpc_duration || '120' }}"
-          ARGS="$ARGS --tx-tps ${{ github.event.inputs.tx_tps || '5' }}"
-          ARGS="$ARGS --tx-duration ${{ github.event.inputs.tx_duration || '120' }}"
-          if [ "${{ github.event.inputs.run_benchmark }}" = "true" ]; then
-            ARGS="$ARGS --with-benchmark"
-          fi
-          docker/telemetry/workload/run-full-validation.sh $ARGS
-        continue-on-error: true
-
-      - name: Upload validation reports
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: telemetry-validation-reports
-          path: /tmp/xrpld-validation/reports/
-          retention-days: 30
-
-      - name: Upload node logs
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: xrpld-node-logs
-          path: /tmp/xrpld-validation/node*/debug.log
-          retention-days: 7
-
-      - name: Print validation summary
-        if: always()
-        run: |
-          REPORT="/tmp/xrpld-validation/reports/validation-report.json"
-          if [ -f "$REPORT" ]; then
-            echo "## Telemetry Validation Results" >> "$GITHUB_STEP_SUMMARY"
-            echo "" >> "$GITHUB_STEP_SUMMARY"
-            TOTAL=$(jq '.summary.total' "$REPORT")
-            PASSED=$(jq '.summary.passed' "$REPORT")
-            FAILED=$(jq '.summary.failed' "$REPORT")
-            echo "| Metric | Value |" >> "$GITHUB_STEP_SUMMARY"
-            echo "|--------|-------|" >> "$GITHUB_STEP_SUMMARY"
-            echo "| Total Checks | $TOTAL |" >> "$GITHUB_STEP_SUMMARY"
-            echo "| Passed | $PASSED |" >> "$GITHUB_STEP_SUMMARY"
-            echo "| Failed | $FAILED |" >> "$GITHUB_STEP_SUMMARY"
-            echo "" >> "$GITHUB_STEP_SUMMARY"
-            if [ "$FAILED" -gt 0 ]; then
-              echo "### Failed Checks" >> "$GITHUB_STEP_SUMMARY"
-              echo "" >> "$GITHUB_STEP_SUMMARY"
-              jq -r '.checks[] | select(.passed == false) | "- **\(.name)**: \(.message)"' "$REPORT" >> "$GITHUB_STEP_SUMMARY"
-            fi
-          fi
-
-      - name: Cleanup
-        if: always()
-        run: |
-          docker/telemetry/workload/run-full-validation.sh --cleanup 2>/dev/null || true
-
-      - name: Check validation result
-        if: steps.validation.outcome == 'failure'
-        run: |
-          echo "Telemetry validation failed. Check the uploaded reports for details."
-          exit 1

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

@@ -19,17 +19,17 @@ on:
     branches: [develop]
     paths:
       # This allows testing changes to the upload workflow in a PR
-      - .github/workflows/upload-conan-deps.yml
+      - ".github/workflows/upload-conan-deps.yml"
   push:
     branches: [develop]
     paths:
-      - .github/workflows/upload-conan-deps.yml
-      - .github/workflows/reusable-strategy-matrix.yml
-      - .github/actions/build-deps/action.yml
-      - .github/actions/setup-conan/action.yml
+      - ".github/workflows/upload-conan-deps.yml"
+      - ".github/workflows/reusable-strategy-matrix.yml"
+      - ".github/actions/build-deps/action.yml"
+      - ".github/actions/setup-conan/action.yml"
       - ".github/scripts/strategy-matrix/**"
-      - conanfile.py
-      - conan.lock
+      - "conanfile.py"
+      - "conan.lock"
 
 env:
   CONAN_REMOTE_NAME: xrplf
@@ -49,7 +49,8 @@ jobs:
   generate-matrix:
     uses: ./.github/workflows/reusable-strategy-matrix.yml
     with:
-      strategy_matrix: ${{ github.event_name == 'pull_request' && 'minimal' || 'all' }}
+      # The workflow dispatch event uses the same trigger as the schedule event.
+      trigger: ${{ github.event_name == 'pull_request' && 'commit' || (github.event_name == 'push' && 'merge' || 'schedule') }}
 
   # Build and upload the dependencies for each configuration.
   run-upload-conan-deps:
@@ -59,37 +60,35 @@ jobs:
       fail-fast: false
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
       max-parallel: 10
-    runs-on: ${{ matrix.architecture.runner }}
-    container: ${{ contains(matrix.architecture.platform, 'linux') && format('ghcr.io/xrplf/ci/{0}-{1}:{2}-{3}-sha-{4}', matrix.os.distro_name, matrix.os.distro_version, matrix.os.compiler_name, matrix.os.compiler_version, matrix.os.image_sha) || null }}
+    runs-on: ${{ matrix.runs_on }}
+    container: ${{ matrix.image }}
     steps:
       - name: Cleanup workspace (macOS and Windows)
         if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
-        uses: XRPLF/actions/cleanup-workspace@cf0433aa74563aead044a1e395610c96d65a37cf
+        uses: XRPLF/actions/cleanup-workspace@2ece4ec6ab7de266859a6f053571425b2bd684b6
 
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@2cbf481018d930656e9276fcc20dc0e3a0be5b6d
+        uses: XRPLF/actions/prepare-runner@2ece4ec6ab7de266859a6f053571425b2bd684b6
         with:
-          enable_ccache: false
+          disable_ccache: false
 
       - name: Print build environment
         uses: ./.github/actions/print-env
 
       - name: Get number of processors
-        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
+        uses: XRPLF/actions/get-nproc@2ece4ec6ab7de266859a6f053571425b2bd684b6
         id: nproc
         with:
           subtract: ${{ env.NPROC_SUBTRACT }}
 
       - name: Setup Conan
-        env:
-          SANITIZERS: ${{ matrix.sanitizers }}
         uses: ./.github/actions/setup-conan
         with:
-          remote_name: ${{ env.CONAN_REMOTE_NAME }}
-          remote_url: ${{ env.CONAN_REMOTE_URL }}
+          conan_remote_name: ${{ env.CONAN_REMOTE_NAME }}
+          conan_remote_url: ${{ env.CONAN_REMOTE_URL }}
 
       - name: Build dependencies
         uses: ./.github/actions/build-deps
@@ -100,14 +99,13 @@ jobs:
           # Set the verbosity to "quiet" for Windows to avoid an excessive
           # amount of logs. For other OSes, the "verbose" logs are more useful.
           log_verbosity: ${{ runner.os == 'Windows' && 'quiet' || 'verbose' }}
-          sanitizers: ${{ matrix.sanitizers }}
 
       - name: Log into Conan remote
-        if: ${{ github.repository == 'XRPLF/rippled' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
+        if: ${{ github.repository_owner == 'XRPLF' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
         run: conan remote login "${CONAN_REMOTE_NAME}" "${{ secrets.CONAN_REMOTE_USERNAME }}" --password "${{ secrets.CONAN_REMOTE_PASSWORD }}"
 
       - name: Upload Conan packages
-        if: ${{ github.repository == 'XRPLF/rippled' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
+        if: ${{ github.repository_owner == 'XRPLF' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
         env:
           FORCE_OPTION: ${{ github.event.inputs.force_upload == 'true' && '--force' || '' }}
         run: conan upload "*" --remote="${CONAN_REMOTE_NAME}" --confirm ${FORCE_OPTION}

.gitignore

@@ -1,5 +1,4 @@
 # .gitignore
-# cspell: disable
 
 # Macintosh Desktop Services Store files.
 .DS_Store
@@ -20,6 +19,7 @@ Release/
 /tmp/
 CMakeSettings.json
 CMakeUserPresets.json
+__pycache__
 
 # Coverage files.
 *.gcno
@@ -36,15 +36,11 @@ gmon.out
 
 # Customized configs.
 /rippled.cfg
-/xrpld.cfg
 /validators.txt
 
 # Locally patched Conan recipes
 external/conan-center-index/
 
-# Local conan directory
-.conan
-
 # XCode IDE.
 *.pbxuser
 !default.pbxuser
@@ -67,16 +63,7 @@ DerivedData
 /.vs/
 /.vscode/
 
-# zed IDE.
-/.zed/
-
 # AI tools.
 /.augment
 /.claude
 /CLAUDE.md
-
-# Direnv's directory
-/.direnv
-
-# clangd cache
-/.cache

.pre-commit-config.yaml

@@ -20,60 +20,22 @@ repos:
         args: [--assume-in-merge]
 
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: cd481d7b0bfb5c7b3090c21846317f9a8262e891 # frozen: v22.1.0
+    rev: 7d85583be209cb547946c82fbe51f4bc5dd1d017 # frozen: v18.1.8
     hooks:
       - id: clang-format
         args: [--style=file]
         "types_or": [c++, c, proto]
 
-  - repo: https://github.com/BlankSpruce/gersemi
-    rev: 0.26.0
-    hooks:
-      - id: gersemi
-
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: c2bc67fe8f8f549cc489e00ba8b45aa18ee713b1 # frozen: v3.8.1
+    rev: 5ba47274f9b181bce26a5150a725577f3c336011 # frozen: v3.6.2
     hooks:
       - id: prettier
 
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: ea488cebbfd88a5f50b8bd95d5c829d0bb76feb8 # frozen: 26.1.0
+    rev: 25.11.0
     hooks:
       - id: black
 
-  - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: a42085ade523f591dca134379a595e7859986445 # frozen: v9.7.0
-    hooks:
-      - id: cspell # Spell check changed files
-        exclude: .config/cspell.config.yaml
-      - id: cspell # Spell check the commit message
-        name: check commit message spelling
-        args:
-          - --no-must-find-files
-          - --no-progress
-          - --no-summary
-          - --files
-          - .git/COMMIT_EDITMSG
-        stages: [commit-msg]
-
-  - repo: local
-    hooks:
-      - id: nix-fmt
-        name: Format Nix files
-        entry: |
-          bash -c '
-            if command -v nix &> /dev/null || [ "$GITHUB_ACTIONS" = "true" ]; then
-              nix --extra-experimental-features "nix-command flakes" fmt "$@"
-            else
-              echo "Skipping nix-fmt: nix not installed and not in GitHub Actions"
-              exit 0
-            fi
-          ' --
-        language: system
-        types:
-          - nix
-        pass_filenames: true
-
 exclude: |
   (?x)^(
       external/.*|

API-CHANGELOG.md

@@ -6,98 +6,90 @@ For info about how [API versioning](https://xrpl.org/request-formatting.html#api
 
 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 [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.
 
-## 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 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 `rippled` version 2.0.0 and later. To use this API, clients specify `"api_version" : 2` in each request.
+
+#### Removed methods
+
+In API version 2, the following deprecated methods are no longer available: (https://github.com/XRPLF/rippled/pull/4759)
+
+- `tx_history` - Instead, use other methods such as `account_tx` or `ledger` with the `transactions` field set to `true`.
+- `ledger_header` - Instead, use the `ledger` method.
+
+#### Modifications to JSON transaction element in V2
+
+In API version 2, JSON elements for transaction output have been changed and made consistent for all methods which output transactions. (https://github.com/XRPLF/rippled/pull/4775)
+This helps to unify the JSON serialization format of transactions. (https://github.com/XRPLF/clio/issues/722, https://github.com/XRPLF/rippled/issues/4727)
+
+- JSON transaction element is named `tx_json`
+- Binary transaction element is named `tx_blob`
+- JSON transaction metadata element is named `meta`
+- Binary transaction metadata element is named `meta_blob`
+
+Additionally, these elements are now consistently available next to `tx_json` (i.e. sibling elements), where possible:
+
+- `hash` - Transaction ID. This data was stored inside transaction output in API version 1, but in API version 2 is a sibling element.
+- `ledger_index` - Ledger index (only set on validated ledgers)
+- `ledger_hash` - Ledger hash (only set on closed or validated ledgers)
+- `close_time_iso` - Ledger close time expressed in ISO 8601 time format (only set on validated ledgers)
+- `validated` - Bool element set to `true` if the transaction is in a validated ledger, otherwise `false`
+
+This change affects the following methods:
+
+- `tx` - Transaction data moved into element `tx_json` (was inline inside `result`) or, if binary output was requested, moved from `tx` to `tx_blob`. Renamed binary transaction metadata element (if it was requested) from `meta` to `meta_blob`. Changed location of `hash` and added new elements
+- `account_tx` - Renamed transaction element from `tx` to `tx_json`. Renamed binary transaction metadata element (if it was requested) from `meta` to `meta_blob`. Changed location of `hash` and added new elements
+- `transaction_entry` - Renamed transaction metadata element from `metadata` to `meta`. Changed location of `hash` and added new elements
+- `subscribe` - Renamed transaction element from `transaction` to `tx_json`. Changed location of `hash` and added new elements
+- `sign`, `sign_for`, `submit` and `submit_multisigned` - Changed location of `hash` element.
+
+#### Modification to `Payment` transaction JSON schema
+
+When reading Payments, the `Amount` field should generally **not** be used. Instead, use [delivered_amount](https://xrpl.org/partial-payments.html#the-delivered_amount-field) to see the amount that the Payment delivered. To clarify its meaning, the `Amount` field is being renamed to `DeliverMax`. (https://github.com/XRPLF/rippled/pull/4733)
+
+- In `Payment` transaction type, JSON RPC field `Amount` is renamed to `DeliverMax`. To enable smooth client transition, `Amount` is still handled, as described below: (https://github.com/XRPLF/rippled/pull/4733)
+  - On JSON RPC input (e.g. `submit_multisigned` etc. methods), `Amount` is recognized as an alias to `DeliverMax` for both API version 1 and version 2 clients.
+  - On JSON RPC input, submitting both `Amount` and `DeliverMax` fields is allowed _only_ if they are identical; otherwise such input is rejected with `rpcINVALID_PARAMS` error.
+  - On JSON RPC output (e.g. `subscribe`, `account_tx` etc. methods), `DeliverMax` is present in both API version 1 and version 2.
+  - On JSON RPC output, `Amount` is only present in API version 1 and _not_ in version 2.
+
+#### Modifications to account_info response
+
+- `signer_lists` is returned in the root of the response. (In API version 1, it was nested under `account_data`.) (https://github.com/XRPLF/rippled/pull/3770)
+- When using an invalid `signer_lists` value, the API now returns an "invalidParams" error. (https://github.com/XRPLF/rippled/pull/4585)
+  - (`signer_lists` must be a boolean. In API version 1, strings were accepted and may return a normal response - i.e. as if `signer_lists` were `true`.)
+
+#### Modifications to [account_tx](https://xrpl.org/account_tx.html#account_tx) response
+
+- Using `ledger_index_min`, `ledger_index_max`, and `ledger_index` returns `invalidParams` because if you use `ledger_index_min` or `ledger_index_max`, then it does not make sense to also specify `ledger_index`. In API version 1, no error was returned. (https://github.com/XRPLF/rippled/pull/4571)
+  - The same applies for `ledger_index_min`, `ledger_index_max`, and `ledger_hash`. (https://github.com/XRPLF/rippled/issues/4545#issuecomment-1565065579)
+- Using a `ledger_index_min` or `ledger_index_max` beyond the range of ledgers that the server has:
+  - returns `lgrIdxMalformed` in API version 2. Previously, in API version 1, no error was returned. (https://github.com/XRPLF/rippled/issues/4288)
+- Attempting to use a non-boolean value (such as a string) for the `binary` or `forward` parameters returns `invalidParams` (`rpcINVALID_PARAMS`). Previously, in API version 1, no error was returned. (https://github.com/XRPLF/rippled/pull/4620)
+
+#### Modifications to [noripple_check](https://xrpl.org/noripple_check.html#noripple_check) response
+
+- Attempting to use a non-boolean value (such as a string) for the `transactions` parameter returns `invalidParams` (`rpcINVALID_PARAMS`). Previously, in API version 1, no error was returned. (https://github.com/XRPLF/rippled/pull/4620)
 
 ## 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.
 
-## Unreleased
+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.
 
-This section contains changes targeting a future version.
+### Inconsistency: server_info - network_id
 
-### Additions
-
-- `server_definitions`: Added the following new sections to the response ([#6321](https://github.com/XRPLF/rippled/pull/6321)):
-  - `TRANSACTION_FORMATS`: Describes the fields and their optionality for each transaction type, including common fields shared across all transactions.
-  - `LEDGER_ENTRY_FORMATS`: Describes the fields and their optionality for each ledger entry type, including common fields shared across all ledger entries.
-  - `TRANSACTION_FLAGS`: Maps transaction type names to their supported flags and flag values.
-  - `LEDGER_ENTRY_FLAGS`: Maps ledger entry type names to their flags and flag values.
-  - `ACCOUNT_SET_FLAGS`: Maps AccountSet flag names (asf flags) to their numeric values.
-
-## XRP Ledger server version 3.1.0
-
-[Version 3.1.0](https://github.com/XRPLF/rippled/releases/tag/3.1.0) was released on Jan 27, 2026.
-
-### Additions in 3.1.0
-
-- `vault_info`: New RPC method to retrieve information about a specific vault (part of XLS-66 Lending Protocol). ([#6156](https://github.com/XRPLF/rippled/pull/6156))
-
-## XRP Ledger server version 3.0.0
-
-[Version 3.0.0](https://github.com/XRPLF/rippled/releases/tag/3.0.0) was released on Dec 9, 2025.
-
-### Additions in 3.0.0
-
-- `ledger_entry`: Supports all ledger entry types with dedicated parsers. ([#5237](https://github.com/XRPLF/rippled/pull/5237))
-- `ledger_entry`: New error codes `entryNotFound` and `unexpectedLedgerType` for more specific error handling. ([#5237](https://github.com/XRPLF/rippled/pull/5237))
-- `ledger_entry`: Improved error messages with more context (e.g., specifying which field is invalid or missing). ([#5237](https://github.com/XRPLF/rippled/pull/5237))
-- `ledger_entry`: Assorted bug fixes in RPC processing. ([#5237](https://github.com/XRPLF/rippled/pull/5237))
-- `simulate`: Supports additional metadata in the response. ([#5754](https://github.com/XRPLF/rippled/pull/5754))
-
-## XRP Ledger server version 2.6.2
-
-[Version 2.6.2](https://github.com/XRPLF/rippled/releases/tag/2.6.2) was released on Nov 19, 2025.
-
-This release contains bug fixes only and no API changes.
-
-## XRP Ledger server version 2.6.1
-
-[Version 2.6.1](https://github.com/XRPLF/rippled/releases/tag/2.6.1) was released on Sep 30, 2025.
-
-This release contains bug fixes only and no API changes.
-
-## XRP Ledger server version 2.6.0
-
-[Version 2.6.0](https://github.com/XRPLF/rippled/releases/tag/2.6.0) was released on Aug 27, 2025.
-
-### Additions in 2.6.0
-
-- `account_info`: Added `allowTrustLineLocking` flag in response. ([#5525](https://github.com/XRPLF/rippled/pull/5525))
-- `ledger`: Removed the type filter from the RPC command. ([#4934](https://github.com/XRPLF/rippled/pull/4934))
-- `subscribe` (`validations` stream): `network_id` is now included. ([#5579](https://github.com/XRPLF/rippled/pull/5579))
-- `subscribe` (`transactions` stream): `nftoken_id`, `nftoken_ids`, and `offer_id` are now included in transaction metadata. ([#5230](https://github.com/XRPLF/rippled/pull/5230))
-
-## XRP Ledger server version 2.5.1
-
-[Version 2.5.1](https://github.com/XRPLF/rippled/releases/tag/2.5.1) was released on Sep 17, 2025.
-
-This release contains bug fixes only and no API changes.
+The `network_id` field was added in the `server_info` response in version 1.5.0 (2019), but it is not returned in [reporting mode](https://xrpl.org/rippled-server-modes.html#reporting-mode). However, use of reporting mode is now discouraged, in favor of using [Clio](https://github.com/XRPLF/clio) instead.
 
 ## XRP Ledger server version 2.5.0
 
-[Version 2.5.0](https://github.com/XRPLF/rippled/releases/tag/2.5.0) was released on Jun 24, 2025.
+As of 2025-04-04, version 2.5.0 is in development. You can use a pre-release version by building from source or [using the `nightly` package](https://xrpl.org/docs/infrastructure/installation/install-rippled-on-ubuntu).
 
 ### Additions and bugfixes in 2.5.0
 
-- `tx`: Added `ctid` field to the response and improved error handling. ([#4738](https://github.com/XRPLF/rippled/pull/4738))
-- `ledger_entry`: Improved error messages in `permissioned_domain`. ([#5344](https://github.com/XRPLF/rippled/pull/5344))
-- `simulate`: Improved multi-sign usage. ([#5479](https://github.com/XRPLF/rippled/pull/5479))
-- `channel_authorize`: If `signing_support` is not enabled in the config, the RPC is disabled. ([#5385](https://github.com/XRPLF/rippled/pull/5385))
-- `subscribe` (admin): Removed webhook queue limit to prevent dropping notifications; reduced HTTP timeout from 10 minutes to 30 seconds. ([#5163](https://github.com/XRPLF/rippled/pull/5163))
-- `ledger_data` (gRPC): Fixed crashing issue with some invalid markers. ([#5137](https://github.com/XRPLF/rippled/pull/5137))
-- `account_lines`: Fixed error with `no_ripple` and `no_ripple_peer` sometimes showing up incorrectly. ([#5345](https://github.com/XRPLF/rippled/pull/5345))
-- `account_tx`: Fixed issue with incorrect CTIDs. ([#5408](https://github.com/XRPLF/rippled/pull/5408))
+- `channel_authorize`: If `signing_support` is not enabled in the config, the RPC is disabled.
 
 ## XRP Ledger server version 2.4.0
 
@@ -105,19 +97,11 @@ This release contains bug fixes only and no API changes.
 
 ### Additions and bugfixes in 2.4.0
 
-- `simulate`: A new RPC that executes a [dry run of a transaction submission](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0069d-simulate#2-rpc-simulate). ([#5069](https://github.com/XRPLF/rippled/pull/5069))
-- Signing methods (`sign`, `sign_for`, `submit`): Autofill fees better, properly handle transactions without a base fee, and autofill the `NetworkID` field. ([#5069](https://github.com/XRPLF/rippled/pull/5069))
-- `ledger_entry`: `state` is added as an alias for `ripple_state`. ([#5199](https://github.com/XRPLF/rippled/pull/5199))
-- `ledger`, `ledger_data`, `account_objects`: Support filtering ledger entry types by their canonical names (case-insensitive). ([#5271](https://github.com/XRPLF/rippled/pull/5271))
-- `validators`: Added new field `validator_list_threshold` in response. ([#5112](https://github.com/XRPLF/rippled/pull/5112))
-- `server_info`: Added git commit hash info on admin connection. ([#5225](https://github.com/XRPLF/rippled/pull/5225))
-- `server_definitions`: Changed larger `UInt` serialized types to `Hash`. ([#5231](https://github.com/XRPLF/rippled/pull/5231))
-
-## XRP Ledger server version 2.3.1
-
-[Version 2.3.1](https://github.com/XRPLF/rippled/releases/tag/2.3.1) was released on Jan 29, 2025.
-
-This release contains bug fixes only and no API changes.
+- `ledger_entry`: `state` is added an alias for `ripple_state`.
+- `ledger_entry`: Enables case-insensitive filtering by canonical name in addition to case-sensitive filtering by RPC name.
+- `validators`: Added new field `validator_list_threshold` in response.
+- `simulate`: A new RPC that executes a [dry run of a transaction submission](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0069d-simulate#2-rpc-simulate)
+- Signing methods autofill fees better and properly handle transactions that don't have a base fee, and will also autofill the `NetworkID` field.
 
 ## XRP Ledger server version 2.3.0
 
@@ -125,30 +109,19 @@ This release contains bug fixes only and no API changes.
 
 ### Breaking changes in 2.3.0
 
-- `book_changes`: If the requested ledger version is not available on this node, a `ledgerNotFound` error is returned and the node does not attempt to acquire the ledger from the p2p network (as with other non-admin RPCs). Admins can still attempt to retrieve old ledgers with the `ledger_request` RPC.
+- `book_changes`: If the requested ledger version is not available on this node, a `ledgerNotFound` error is returned and the node does not attempt to acquire the ledger from the p2p network (as with other non-admin RPCs).
+
+Admins can still attempt to retrieve old ledgers with the `ledger_request` RPC.
 
 ### Additions and bugfixes in 2.3.0
 
-- `book_changes`: Returns a `validated` field in its response. ([#5096](https://github.com/XRPLF/rippled/pull/5096))
-- `book_changes`: Accepts shortcut strings (`current`, `closed`, `validated`) for the `ledger_index` parameter. ([#5096](https://github.com/XRPLF/rippled/pull/5096))
-- `server_definitions`: Include `index` in response. ([#5190](https://github.com/XRPLF/rippled/pull/5190))
-- `account_nfts`: Fix issue where unassociated marker would return incorrect results. ([#5045](https://github.com/XRPLF/rippled/pull/5045))
-- `account_objects`: Fix issue where invalid marker would not return an error. ([#5046](https://github.com/XRPLF/rippled/pull/5046))
-- `account_objects`: Disallow filtering by ledger entry types that an account cannot hold. ([#5056](https://github.com/XRPLF/rippled/pull/5056))
-- `tx`: Allow lowercase CTID. ([#5049](https://github.com/XRPLF/rippled/pull/5049))
-- `feature`: Better error handling for invalid values of `feature`. ([#5063](https://github.com/XRPLF/rippled/pull/5063))
+- `book_changes`: Returns a `validated` field in its response, which was missing in prior versions.
 
 ## XRP Ledger server version 2.2.0
 
 [Version 2.2.0](https://github.com/XRPLF/rippled/releases/tag/2.2.0) was released on Jun 5, 2024. The following additions are non-breaking (because they are purely additive):
 
-- `feature`: Add a non-admin mode for users. (It was previously only available to admin connections.) The method returns an updated list of amendments, including their names and other information. ([#4781](https://github.com/XRPLF/rippled/pull/4781))
-
-## XRP Ledger server version 2.0.1
-
-[Version 2.0.1](https://github.com/XRPLF/rippled/releases/tag/2.0.1) was released on Jan 29, 2024. The following additions are non-breaking:
-
-- `path_find`: Fixes unbounded memory growth. ([#4822](https://github.com/XRPLF/rippled/pull/4822))
+- The `feature` method now has a non-admin mode for users. (It was previously only available to admin connections.) The method returns an updated list of amendments, including their names and other information. ([#4781](https://github.com/XRPLF/rippled/pull/4781))
 
 ## XRP Ledger server version 2.0.0
 
@@ -156,18 +129,24 @@ This release contains bug fixes only and no API changes.
 
 - `server_definitions`: A new RPC that generates a `definitions.json`-like output that can be used in XRPL libraries.
 - In `Payment` transactions, `DeliverMax` has been added. This is a replacement for the `Amount` field, which should not be used. Typically, the `delivered_amount` (in transaction metadata) should be used. To ease the transition, `DeliverMax` is present regardless of API version, since adding a field is non-breaking.
-- API version 2 has been moved from beta to supported, meaning that it is generally available (regardless of the `beta_rpc_api` setting). The full list of changes is in [API-VERSION-2.md](API-VERSION-2.md).
+- API version 2 has been moved from beta to supported, meaning that it is generally available (regardless of the `beta_rpc_api` setting).
+
+## XRP Ledger server version 2.2.0
+
+The following is a non-breaking addition to the API.
+
+- The `feature` method now has a non-admin mode for users. (It was previously only available to admin connections.) The method returns an updated list of amendments, including their names and other information. ([#4781](https://github.com/XRPLF/rippled/pull/4781))
 
 ## XRP Ledger server version 1.12.0
 
-[Version 1.12.0](https://github.com/XRPLF/rippled/releases/tag/1.12.0) was released on Sep 6, 2023. The following additions are non-breaking (because they are purely additive):
+[Version 1.12.0](https://github.com/XRPLF/rippled/releases/tag/1.12.0) was released on Sep 6, 2023. The following additions are non-breaking (because they are purely additive).
 
-- `server_info`: Added `ports`, an array which advertises the RPC and WebSocket ports. This information is also included in the `/crawl` endpoint (which calls `server_info` internally). `grpc` and `peer` ports are also included. ([#4427](https://github.com/XRPLF/rippled/pull/4427))
+- `server_info`: Added `ports`, an array which advertises the RPC and WebSocket ports. This information is also included in the `/crawl` endpoint (which calls `server_info` internally). `grpc` and `peer` ports are also included. (https://github.com/XRPLF/rippled/pull/4427)
   - `ports` contains objects, each containing a `port` for the listening port (a number string), and a `protocol` array listing the supported protocols on that port.
   - This allows crawlers to build a more detailed topology without needing to port-scan nodes.
   - (For peers and other non-admin clients, the info about admin ports is excluded.)
-- Clawback: The following additions are gated by the Clawback amendment (`featureClawback`). ([#4553](https://github.com/XRPLF/rippled/pull/4553))
-  - Adds an [AccountRoot flag](https://xrpl.org/accountroot.html#accountroot-flags) called `lsfAllowTrustLineClawback`. ([#4617](https://github.com/XRPLF/rippled/pull/4617))
+- Clawback: The following additions are gated by the Clawback amendment (`featureClawback`). (https://github.com/XRPLF/rippled/pull/4553)
+  - Adds an [AccountRoot flag](https://xrpl.org/accountroot.html#accountroot-flags) called `lsfAllowTrustLineClawback` (https://github.com/XRPLF/rippled/pull/4617)
     - Adds the corresponding `asfAllowTrustLineClawback` [AccountSet Flag](https://xrpl.org/accountset.html#accountset-flags) as well.
     - Clawback is disabled by default, so if an issuer desires the ability to claw back funds, they must use an `AccountSet` transaction to set the AllowTrustLineClawback flag. They must do this before creating any trust lines, offers, escrows, payment channels, or checks.
   - Adds the [Clawback transaction type](https://github.com/XRPLF/XRPL-Standards/blob/master/XLS-39d-clawback/README.md#331-clawback-transaction), containing these fields:
@@ -202,16 +181,16 @@ This release contains bug fixes only and no API changes.
 
 ### Breaking changes in 1.11
 
-- Added the ability to mark amendments as obsolete. For the `feature` admin API, there is a new possible value for the `vetoed` field. ([#4291](https://github.com/XRPLF/rippled/pull/4291))
+- Added the ability to mark amendments as obsolete. For the `feature` admin API, there is a new possible value for the `vetoed` field. (https://github.com/XRPLF/rippled/pull/4291)
   - The value of `vetoed` can now be `true`, `false`, or `"Obsolete"`.
-- Removed the acceptance of seeds or public keys in place of account addresses. ([#4404](https://github.com/XRPLF/rippled/pull/4404))
+- Removed the acceptance of seeds or public keys in place of account addresses. (https://github.com/XRPLF/rippled/pull/4404)
   - This simplifies the API and encourages better security practices (i.e. seeds should never be sent over the network).
-- For the `ledger_data` method, when all entries are filtered out, the `state` field of the response is now an empty list (in other words, an empty array, `[]`). (Previously, it would return `null`.) While this is technically a breaking change, the new behavior is consistent with the documentation, so this is considered only a bug fix. ([#4398](https://github.com/XRPLF/rippled/pull/4398))
+- For the `ledger_data` method, when all entries are filtered out, the `state` field of the response is now an empty list (in other words, an empty array, `[]`). (Previously, it would return `null`.) While this is technically a breaking change, the new behavior is consistent with the documentation, so this is considered only a bug fix. (https://github.com/XRPLF/rippled/pull/4398)
 - If and when the `fixNFTokenRemint` amendment activates, there will be a new AccountRoot field, `FirstNFTSequence`. This field is set to the current account sequence when the account issues their first NFT. If an account has not issued any NFTs, then the field is not set. ([#4406](https://github.com/XRPLF/rippled/pull/4406))
   - There is a new account deletion restriction: an account can only be deleted if `FirstNFTSequence` + `MintedNFTokens` + `256` is less than the current ledger sequence.
   - This is potentially a breaking change if clients have logic for determining whether an account can be deleted.
 - NetworkID
-  - For sidechains and networks with a network ID greater than 1024, there is a new [transaction common field](https://xrpl.org/transaction-common-fields.html), `NetworkID`. ([#4370](https://github.com/XRPLF/rippled/pull/4370))
+  - For sidechains and networks with a network ID greater than 1024, there is a new [transaction common field](https://xrpl.org/transaction-common-fields.html), `NetworkID`. (https://github.com/XRPLF/rippled/pull/4370)
     - This field helps to prevent replay attacks and is now required for chains whose network ID is 1025 or higher.
     - The field must be omitted for Mainnet, so there is no change for Mainnet users.
   - There are three new local error codes:
@@ -221,10 +200,10 @@ This release contains bug fixes only and no API changes.
 
 ### Additions and bug fixes in 1.11
 
-- Added `nftoken_id`, `nftoken_ids` and `offer_id` meta fields into NFT `tx` and `account_tx` responses. ([#4447](https://github.com/XRPLF/rippled/pull/4447))
-- Added an `account_flags` object to the `account_info` method response. ([#4459](https://github.com/XRPLF/rippled/pull/4459))
-- Added `NFTokenPages` to the `account_objects` RPC. ([#4352](https://github.com/XRPLF/rippled/pull/4352))
-- Fixed: `marker` returned from the `account_lines` command would not work on subsequent commands. ([#4361](https://github.com/XRPLF/rippled/pull/4361))
+- Added `nftoken_id`, `nftoken_ids` and `offer_id` meta fields into NFT `tx` and `account_tx` responses. (https://github.com/XRPLF/rippled/pull/4447)
+- Added an `account_flags` object to the `account_info` method response. (https://github.com/XRPLF/rippled/pull/4459)
+- Added `NFTokenPages` to the `account_objects` RPC. (https://github.com/XRPLF/rippled/pull/4352)
+- Fixed: `marker` returned from the `account_lines` command would not work on subsequent commands. (https://github.com/XRPLF/rippled/pull/4361)
 
 ## XRP Ledger server version 1.10.0
 

API-VERSION-2.md

@@ -1,66 +0,0 @@
-# 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.
-
-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.
-
-## Removed methods
-
-In API version 2, the following deprecated methods are no longer available: ([#4759](https://github.com/XRPLF/rippled/pull/4759))
-
-- `tx_history` - Instead, use other methods such as `account_tx` or `ledger` with the `transactions` field set to `true`.
-- `ledger_header` - Instead, use the `ledger` method.
-
-## Modifications to JSON transaction element in API version 2
-
-In API version 2, JSON elements for transaction output have been changed and made consistent for all methods which output transactions. ([#4775](https://github.com/XRPLF/rippled/pull/4775))
-This helps to unify the JSON serialization format of transactions. ([clio#722](https://github.com/XRPLF/clio/issues/722), [#4727](https://github.com/XRPLF/rippled/issues/4727))
-
-- JSON transaction element is named `tx_json`
-- Binary transaction element is named `tx_blob`
-- JSON transaction metadata element is named `meta`
-- Binary transaction metadata element is named `meta_blob`
-
-Additionally, these elements are now consistently available next to `tx_json` (i.e. sibling elements), where possible:
-
-- `hash` - Transaction ID. This data was stored inside transaction output in API version 1, but in API version 2 is a sibling element.
-- `ledger_index` - Ledger index (only set on validated ledgers)
-- `ledger_hash` - Ledger hash (only set on closed or validated ledgers)
-- `close_time_iso` - Ledger close time expressed in ISO 8601 time format (only set on validated ledgers)
-- `validated` - Bool element set to `true` if the transaction is in a validated ledger, otherwise `false`
-
-This change affects the following methods:
-
-- `tx` - Transaction data moved into element `tx_json` (was inline inside `result`) or, if binary output was requested, moved from `tx` to `tx_blob`. Renamed binary transaction metadata element (if it was requested) from `meta` to `meta_blob`. Changed location of `hash` and added new elements
-- `account_tx` - Renamed transaction element from `tx` to `tx_json`. Renamed binary transaction metadata element (if it was requested) from `meta` to `meta_blob`. Changed location of `hash` and added new elements
-- `transaction_entry` - Renamed transaction metadata element from `metadata` to `meta`. Changed location of `hash` and added new elements
-- `subscribe` - Renamed transaction element from `transaction` to `tx_json`. Changed location of `hash` and added new elements
-- `sign`, `sign_for`, `submit` and `submit_multisigned` - Changed location of `hash` element.
-
-## Modifications to `Payment` transaction JSON schema
-
-When reading Payments, the `Amount` field should generally **not** be used. Instead, use [delivered_amount](https://xrpl.org/partial-payments.html#the-delivered_amount-field) to see the amount that the Payment delivered. To clarify its meaning, the `Amount` field is being renamed to `DeliverMax`. ([#4733](https://github.com/XRPLF/rippled/pull/4733))
-
-- In `Payment` transaction type, JSON RPC field `Amount` is renamed to `DeliverMax`. To enable smooth client transition, `Amount` is still handled, as described below: ([#4733](https://github.com/XRPLF/rippled/pull/4733))
-  - On JSON RPC input (e.g. `submit_multisigned` etc. methods), `Amount` is recognized as an alias to `DeliverMax` for both API version 1 and version 2 clients.
-  - On JSON RPC input, submitting both `Amount` and `DeliverMax` fields is allowed _only_ if they are identical; otherwise such input is rejected with `rpcINVALID_PARAMS` error.
-  - On JSON RPC output (e.g. `subscribe`, `account_tx` etc. methods), `DeliverMax` is present in both API version 1 and version 2.
-  - On JSON RPC output, `Amount` is only present in API version 1 and _not_ in version 2.
-
-## Modifications to account_info response
-
-- `signer_lists` is returned in the root of the response. (In API version 1, it was nested under `account_data`.) ([#3770](https://github.com/XRPLF/rippled/pull/3770))
-- When using an invalid `signer_lists` value, the API now returns an "invalidParams" error. ([#4585](https://github.com/XRPLF/rippled/pull/4585))
-  - (`signer_lists` must be a boolean. In API version 1, strings were accepted and may return a normal response - i.e. as if `signer_lists` were `true`.)
-
-## Modifications to [account_tx](https://xrpl.org/account_tx.html#account_tx) response
-
-- Using `ledger_index_min`, `ledger_index_max`, and `ledger_index` returns `invalidParams` because if you use `ledger_index_min` or `ledger_index_max`, then it does not make sense to also specify `ledger_index`. In API version 1, no error was returned. ([#4571](https://github.com/XRPLF/rippled/pull/4571))
-  - The same applies for `ledger_index_min`, `ledger_index_max`, and `ledger_hash`. ([#4545](https://github.com/XRPLF/rippled/issues/4545#issuecomment-1565065579))
-- Using a `ledger_index_min` or `ledger_index_max` beyond the range of ledgers that the server has:
-  - returns `lgrIdxMalformed` in API version 2. Previously, in API version 1, no error was returned. ([#4288](https://github.com/XRPLF/rippled/issues/4288))
-- Attempting to use a non-boolean value (such as a string) for the `binary` or `forward` parameters returns `invalidParams` (`rpcINVALID_PARAMS`). Previously, in API version 1, no error was returned. ([#4620](https://github.com/XRPLF/rippled/pull/4620))
-
-## Modifications to [noripple_check](https://xrpl.org/noripple_check.html#noripple_check) response
-
-- Attempting to use a non-boolean value (such as a string) for the `transactions` parameter returns `invalidParams` (`rpcINVALID_PARAMS`). Previously, in API version 1, no error was returned. ([#4620](https://github.com/XRPLF/rippled/pull/4620))

API-VERSION-3.md

@@ -1,27 +0,0 @@
-# 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.
-
-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.
-
-## Breaking Changes
-
-### Modifications to `amm_info`
-
-The order of error checks has been changed to provide more specific error messages. ([#4924](https://github.com/XRPLF/rippled/pull/4924))
-
-- **Before (API v2)**: When sending an invalid account or asset to `amm_info` while other parameters are not set as expected, the method returns a generic `rpcINVALID_PARAMS` error.
-- **After (API v3)**: The same scenario returns a more specific error: `rpcISSUE_MALFORMED` for malformed assets or `rpcACT_MALFORMED` for malformed accounts.
-
-### Modifications to `ledger_entry`
-
-Added support for string shortcuts to look up fixed-location ledger entries using the `"index"` parameter. ([#5644](https://github.com/XRPLF/rippled/pull/5644))
-
-In API version 3, the following string values can be used with the `"index"` parameter:
-
-- `"index": "amendments"` - Returns the `Amendments` ledger entry
-- `"index": "fee"` - Returns the `FeeSettings` ledger entry
-- `"index": "nunl"` - Returns the `NegativeUNL` ledger entry
-- `"index": "hashes"` - Returns the "short" `LedgerHashes` ledger entry (recent ledger hashes)
-
-These shortcuts are only available in API version 3 and later. In API versions 1 and 2, these string values would result in an error.

BUILD.md

@@ -1,5 +1,5 @@
-| :warning: **WARNING** :warning:                                                                                                                                                                                                |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| :warning: **WARNING** :warning:
+|---|
 | These instructions assume you have a C++ development environment ready with Git, Python, Conan, CMake, and a C++ compiler. For help setting one up on Linux, macOS, or Windows, [see this guide](./docs/build/environment.md). |
 
 > These instructions also assume a basic familiarity with Conan and CMake.
@@ -148,8 +148,7 @@ function extract_version {
 }
 
 # Define which recipes to export.
-recipes=('ed25519' 'grpc' 'nudb' 'openssl' 'secp256k1' 'snappy' 'soci')
-folders=('all'     'all'  'all'  '3.x.x'   'all'       'all'    'all')
+recipes=(ed25519 grpc secp256k1 snappy soci)
 
 # Selectively check out the recipes from our CCI fork.
 cd external
@@ -158,24 +157,20 @@ cd conan-center-index
 git init
 git remote add origin git@github.com:XRPLF/conan-center-index.git
 git sparse-checkout init
-for ((index = 1; index <= ${#recipes[@]}; index++)); do
-  recipe=${recipes[index]}
-  folder=${folders[index]}
-  echo "Checking out recipe '${recipe}' from folder '${folder}'..."
-  git sparse-checkout add recipes/${recipe}/${folder}
+for recipe in ${recipes[@]}; do
+  echo "Checking out ${recipe}..."
+  git sparse-checkout add recipes/${recipe}/all
 done
 git fetch origin master
 git checkout master
 cd ../..
 
 # Export the recipes into the local cache.
-for ((index = 1; index <= ${#recipes[@]}; index++)); do
-  recipe=${recipes[index]}
-  folder=${folders[index]}
+for recipe in ${recipes[@]}; do
   version=$(extract_version ${recipe})
-  echo "Exporting '${recipe}/${version}' from '${recipe}/${folder}'..."
+  echo "Exporting ${recipe}/${version}..."
   conan export --version $(extract_version ${recipe}) \
-    external/conan-center-index/recipes/${recipe}/${folder}
+    external/conan-center-index/recipes/${recipe}/all
 done
 ```
 
@@ -368,36 +363,6 @@ The workaround for this error is to add two lines to your profile:
 tools.build:cxxflags=['-DBOOST_ASIO_DISABLE_CONCEPTS']
 ```
 
-### Set Up Ccache
-
-To speed up repeated compilations, we recommend that you install
-[ccache](https://ccache.dev), a tool that wraps your compiler so that it can
-cache build objects locally.
-
-#### Linux
-
-You can install it using the package manager, e.g. `sudo apt install ccache`
-(Ubuntu) or `sudo dnf install ccache` (RHEL).
-
-#### macOS
-
-You can install it using Homebrew, i.e. `brew install ccache`.
-
-#### Windows
-
-You can install it using Chocolatey, i.e. `choco install ccache`. If you already
-have Ccache installed, then `choco upgrade ccache` will update it to the latest
-version. However, if you see an error such as:
-
-```
-terminate called after throwing an instance of 'std::bad_alloc'
-      what():  std::bad_alloc
-C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VC\v170\Microsoft.CppCommon.targets(617,5): error MSB6006: "cl.exe" exited with code 3.
-```
-
-then please install a specific version of Ccache that we know works, via: `choco
-install ccache --version 4.11.3 --allow-downgrade`.
-
 ### Build and Test
 
 1. Create a build directory and move into it.
@@ -553,37 +518,23 @@ stored inside the build directory, as either of:
 - file named `coverage.`_extension_, with a suitable extension for the report format, or
 - directory named `coverage`, with the `index.html` and other files inside, for the `html-details` or `html-nested` report formats.
 
-## Sanitizers
-
-To build dependencies and xrpld with sanitizer instrumentation, set the
-`SANITIZERS` environment variable (only once before running conan and cmake) and use the `sanitizers` profile in conan:
-
-```bash
-export SANITIZERS=address,undefinedbehavior
-
-conan install .. --output-folder . --profile:all sanitizers --build missing --settings build_type=Debug
-
-cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Debug -Dxrpld=ON -Dtests=ON ..
-```
-
-See [Sanitizers docs](./docs/build/sanitizers.md) for more details.
-
 ## Options
 
-| Option     | Default Value | Description                                                    |
-| ---------- | ------------- | -------------------------------------------------------------- |
-| `assert`   | OFF           | Enable assertions.                                             |
-| `coverage` | OFF           | Prepare the coverage report.                                   |
-| `tests`    | OFF           | Build tests.                                                   |
-| `unity`    | OFF           | Configure a unity build.                                       |
-| `xrpld`    | OFF           | Build the xrpld application, and not just the libxrpl library. |
-| `werr`     | OFF           | Treat compilation warnings as errors                           |
-| `wextra`   | OFF           | Enable additional compilation warnings                         |
+| Option     | Default Value | Description                                                        |
+| ---------- | ------------- | ------------------------------------------------------------------ |
+| `assert`   | OFF           | Enable assertions.                                                 |
+| `coverage` | OFF           | Prepare the coverage report.                                       |
+| `san`      | N/A           | Enable a sanitizer with Clang. Choices are `thread` and `address`. |
+| `tests`    | OFF           | Build tests.                                                       |
+| `unity`    | OFF           | Configure a unity build.                                           |
+| `xrpld`    | OFF           | Build the xrpld application, and not just the libxrpl library.     |
+| `werr`     | OFF           | Treat compilation warnings as errors                               |
+| `wextra`   | OFF           | Enable additional compilation warnings                             |
 
-[Unity builds][5] may be faster for the first build (at the cost of much more
-memory) since they concatenate sources into fewer translation units. Non-unity
-builds may be faster for incremental builds, and can be helpful for detecting
-`#include` omissions.
+[Unity builds][5] may be faster for the first build
+(at the cost of much more memory) since they concatenate sources into fewer
+translation units. Non-unity builds may be faster for incremental builds,
+and can be helpful for detecting `#include` omissions.
 
 ## Troubleshooting
 

CMakeLists.txt

@@ -1,153 +1,150 @@
 cmake_minimum_required(VERSION 3.16)
 
 if(POLICY CMP0074)
-    cmake_policy(SET CMP0074 NEW)
+  cmake_policy(SET CMP0074 NEW)
 endif()
 if(POLICY CMP0077)
-    cmake_policy(SET CMP0077 NEW)
+  cmake_policy(SET CMP0077 NEW)
 endif()
 
 # Fix "unrecognized escape" issues when passing CMAKE_MODULE_PATH on Windows.
-if(DEFINED CMAKE_MODULE_PATH)
-    file(TO_CMAKE_PATH "${CMAKE_MODULE_PATH}" CMAKE_MODULE_PATH)
-endif()
+file(TO_CMAKE_PATH "${CMAKE_MODULE_PATH}" CMAKE_MODULE_PATH)
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
 project(xrpl)
 set(CMAKE_CXX_EXTENSIONS OFF)
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
-set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
-include(CompilationEnv)
-
-if(is_gcc)
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU")
     # GCC-specific fixes
     add_compile_options(-Wno-unknown-pragmas -Wno-subobject-linkage)
     # -Wno-subobject-linkage can be removed when we upgrade GCC version to at least 13.3
-elseif(is_clang)
+elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
     # Clang-specific fixes
     add_compile_options(-Wno-unknown-warning-option) # Ignore unknown warning options
-elseif(is_msvc)
+elseif(MSVC)
     # MSVC-specific fixes
     add_compile_options(/wd4068) # Ignore unknown pragmas
 endif()
 
-# Enable ccache to speed up builds.
-include(Ccache)
+# make GIT_COMMIT_HASH define available to all sources
+find_package(Git)
+if(Git_FOUND)
+    execute_process(COMMAND ${GIT_EXECUTABLE} --git-dir=${CMAKE_CURRENT_SOURCE_DIR}/.git rev-parse HEAD
+        OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE gch)
+    if(gch)
+        set(GIT_COMMIT_HASH "${gch}")
+        message(STATUS gch: ${GIT_COMMIT_HASH})
+        add_definitions(-DGIT_COMMIT_HASH="${GIT_COMMIT_HASH}")
+    endif()
+
+    execute_process(COMMAND ${GIT_EXECUTABLE} --git-dir=${CMAKE_CURRENT_SOURCE_DIR}/.git rev-parse --abbrev-ref HEAD
+        OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE gb)
+    if(gb)
+        set(GIT_BRANCH "${gb}")
+        message(STATUS gb: ${GIT_BRANCH})
+        add_definitions(-DGIT_BRANCH="${GIT_BRANCH}")
+    endif()
+endif() #git
 
 if(thread_safety_analysis)
-    add_compile_options(
-        -Wthread-safety
-        -D_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS
-        -DXRPL_ENABLE_THREAD_SAFETY_ANNOTATIONS
-    )
-    add_compile_options("-stdlib=libc++")
-    add_link_options("-stdlib=libc++")
+  add_compile_options(-Wthread-safety -D_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS -DXRPL_ENABLE_THREAD_SAFETY_ANNOTATIONS)
+  add_compile_options("-stdlib=libc++")
+  add_link_options("-stdlib=libc++")
 endif()
 
-include(CheckCXXCompilerFlag)
-include(FetchContent)
-include(ExternalProject)
-include(CMakeFuncs) # must come *after* ExternalProject b/c it overrides one function in EP
-if(target)
-    message(
-        FATAL_ERROR
-        "The target option has been removed - use native cmake options to control build"
-    )
-endif()
+include (CheckCXXCompilerFlag)
+include (FetchContent)
+include (ExternalProject)
+include (CMakeFuncs) # must come *after* ExternalProject b/c it overrides one function in EP
+if (target)
+  message (FATAL_ERROR "The target option has been removed - use native cmake options to control build")
+endif ()
 
 include(XrplSanity)
 include(XrplVersion)
 include(XrplSettings)
-# this check has to remain in the top-level cmake because of the early return statement
-if(packages_only)
-    if(NOT TARGET rpm)
-        message(
-            FATAL_ERROR
-            "packages_only requested, but targets were not created - is docker installed?"
-        )
-    endif()
-    return()
-endif()
+# this check has to remain in the top-level cmake
+# because of the early return statement
+if (packages_only)
+  if (NOT TARGET rpm)
+    message (FATAL_ERROR "packages_only requested, but targets were not created - is docker installed?")
+  endif()
+  return ()
+endif ()
 include(XrplCompiler)
-include(XrplSanitizers)
 include(XrplInterface)
 
 option(only_docs "Include only the docs target?" FALSE)
 include(XrplDocs)
 if(only_docs)
-    return()
+  return()
 endif()
 
+###
+
 include(deps/Boost)
+find_package(OpenSSL 1.1.1 REQUIRED)
+set_target_properties(OpenSSL::SSL PROPERTIES
+  INTERFACE_COMPILE_DEFINITIONS OPENSSL_NO_SSL2
+)
 
 add_subdirectory(external/antithesis-sdk)
-find_package(date REQUIRED)
-find_package(ed25519 REQUIRED)
 find_package(gRPC REQUIRED)
-find_package(LibArchive REQUIRED)
 find_package(lz4 REQUIRED)
-find_package(nudb REQUIRED)
-find_package(OpenSSL REQUIRED)
-find_package(secp256k1 REQUIRED)
+# Target names with :: are not allowed in a generator expression.
+# We need to pull the include directories and imported location properties
+# from separate targets.
+find_package(LibArchive REQUIRED)
 find_package(SOCI REQUIRED)
 find_package(SQLite3 REQUIRED)
-find_package(xxHash REQUIRED)
-
-target_link_libraries(
-    xrpl_libs
-    INTERFACE
-        ed25519::ed25519
-        lz4::lz4
-        OpenSSL::Crypto
-        OpenSSL::SSL
-        secp256k1::secp256k1
-        soci::soci
-        SQLite::SQLite3
-)
 
 option(rocksdb "Enable RocksDB" ON)
 if(rocksdb)
-    find_package(RocksDB REQUIRED)
-    set_target_properties(
-        RocksDB::rocksdb
-        PROPERTIES INTERFACE_COMPILE_DEFINITIONS XRPL_ROCKSDB_AVAILABLE=1
-    )
-    target_link_libraries(xrpl_libs INTERFACE RocksDB::rocksdb)
+  find_package(RocksDB REQUIRED)
+  set_target_properties(RocksDB::rocksdb PROPERTIES
+    INTERFACE_COMPILE_DEFINITIONS XRPL_ROCKSDB_AVAILABLE=1
+  )
+  target_link_libraries(xrpl_libs INTERFACE RocksDB::rocksdb)
 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.
-# 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)
-if(telemetry)
-    find_package(opentelemetry-cpp CONFIG REQUIRED)
-    add_compile_definitions(XRPL_ENABLE_TELEMETRY)
-    message(STATUS "OpenTelemetry tracing enabled")
-endif()
+find_package(date REQUIRED)
+find_package(ed25519 REQUIRED)
+find_package(nudb REQUIRED)
+find_package(secp256k1 REQUIRED)
+find_package(xxHash REQUIRED)
+
+target_link_libraries(xrpl_libs INTERFACE
+  ed25519::ed25519
+  lz4::lz4
+  OpenSSL::Crypto
+  OpenSSL::SSL
+  secp256k1::secp256k1
+  soci::soci
+  SQLite::SQLite3
+)
 
 # Work around changes to Conan recipe for now.
 if(TARGET nudb::core)
-    set(nudb nudb::core)
+  set(nudb nudb::core)
 elseif(TARGET NuDB::nudb)
-    set(nudb NuDB::nudb)
+  set(nudb NuDB::nudb)
 else()
-    message(FATAL_ERROR "unknown nudb target")
+  message(FATAL_ERROR "unknown nudb target")
 endif()
 target_link_libraries(xrpl_libs INTERFACE ${nudb})
 
 if(coverage)
-    include(XrplCov)
+  include(XrplCov)
 endif()
 
+set(PROJECT_EXPORT_SET XrplExports)
 include(XrplCore)
 include(XrplInstall)
 include(XrplValidatorKeys)
 
 if(tests)
-    include(CTest)
-    add_subdirectory(src/tests/libxrpl)
+  include(CTest)
+  add_subdirectory(src/tests/libxrpl)
 endif()

CONTRIBUTING.md

@@ -219,7 +219,7 @@ coherent rather than a set of _thou shalt not_ commandments.
 
 ## Formatting
 
-All code must conform to `clang-format` version 21,
+All code must conform to `clang-format` version 18,
 according to the settings in [`.clang-format`](./.clang-format),
 unless the result would be unreasonably difficult to read or maintain.
 To demarcate lines that should be left as-is, surround them with comments like
@@ -555,16 +555,16 @@ Rippled uses a linear workflow model that can be summarized as:
 git fetch --multiple upstreams user1 user2 user3 [...]
 git checkout -B release-next --no-track upstream/develop
 
-# Only do an ff-only merge if pr-branch1 is either already
+# Only do an ff-only merge if prbranch1 is either already
 # squashed, or needs to be merged with separate commits,
 # and has no merge commits.
-# Use -S on the ff-only merge if pr-branch1 isn't signed.
-git merge [-S] --ff-only user1/pr-branch1
+# Use -S on the ff-only merge if prbranch1 isn't signed.
+git merge [-S] --ff-only user1/prbranch1
 
-git merge --squash user2/pr-branch2
+git merge --squash user2/prbranch2
 git commit -S # Use the commit message provided on the PR
 
-git merge --squash user3/pr-branch3
+git merge --squash user3/prbranch3
 git commit -S # Use the commit message provided on the PR
 
 [...]
@@ -872,12 +872,11 @@ git push --delete upstream-push master-next
 11. [Create a new release on
     Github](https://github.com/XRPLF/rippled/releases). Be sure that
     "Set as the latest release" is checked.
-12. Open a PR to update the [API-CHANGELOG](API-CHANGELOG.md) and `API-VERSION-[n].md` with the changes for this release (if any are missing).
-13. Finally, [reverse merge the release into `develop`](#follow-up-reverse-merge).
+12. Finally [reverse merge the release into `develop`](#follow-up-reverse-merge).
 
 #### Special cases: point releases, hotfixes, etc.
 
-On occasion, a bug or issue is discovered in a version that already
+On occassion, a bug or issue is discovered in a version that already
 had a final release. Most of the time, development will have started
 on the next version, and will usually have changes in `develop`
 and often in `release`.

OpenTelemetryPlan/00-tracing-fundamentals.md

@@ -1,244 +0,0 @@
-# Distributed Tracing Fundamentals
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Next**: [Architecture Analysis](./01-architecture-analysis.md)
-
----
-
-## What is Distributed Tracing?
-
-Distributed tracing is a method for tracking data objects as they flow through distributed systems. In a network like XRP Ledger, a single transaction touches multiple independent nodes—each with no shared memory or logging. Distributed tracing connects these dots.
-
-**Without tracing:** You see isolated logs on each node with no way to correlate them.
-
-**With tracing:** You see the complete journey of a transaction or an event across all nodes it touched.
-
----
-
-## Core Concepts
-
-### 1. Trace
-
-A **trace** represents the entire journey of a request through the system. It has a unique `trace_id` that stays constant across all nodes.
-
-```
-Trace ID: abc123
-├── Node A: received transaction
-├── Node B: relayed transaction
-├── Node C: included in consensus
-└── Node D: applied to ledger
-```
-
-### 2. Span
-
-A **span** represents a single unit of work within a trace. Each span has:
-
-| Attribute        | Description           | Example                    |
-| ---------------- | --------------------- | -------------------------- |
-| `trace_id`       | Links to parent trace | `abc123`                   |
-| `span_id`        | Unique identifier     | `span456`                  |
-| `parent_span_id` | Parent span (if any)  | `p_span123`                |
-| `name`           | Operation name        | `rpc.submit`               |
-| `start_time`     | When work began       | `2024-01-15T10:30:00Z`     |
-| `end_time`       | When work completed   | `2024-01-15T10:30:00.050Z` |
-| `attributes`     | Key-value metadata    | `tx.hash=ABC...`           |
-| `status`         | OK, ERROR MSG         | `OK`                       |
-
-### 3. Trace Context
-
-**Trace context** is the data that propagates between services to link spans together. It contains:
-
-- `trace_id` - The trace this span belongs to
-- `span_id` - The current span (becomes parent for child spans)
-- `trace_flags` - Sampling decisions
-
----
-
-## How Spans Form a Trace
-
-Spans have parent-child relationships forming a tree structure:
-
-```mermaid
-flowchart TB
-    subgraph trace["Trace: abc123"]
-        A["tx.submit<br/>span_id: 001<br/>50ms"] --> B["tx.validate<br/>span_id: 002<br/>5ms"]
-        A --> C["tx.relay<br/>span_id: 003<br/>10ms"]
-        A --> D["tx.apply<br/>span_id: 004<br/>30ms"]
-        D --> E["ledger.update<br/>span_id: 005<br/>20ms"]
-    end
-
-    style A fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style B fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style D fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style E fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-The same trace visualized as a **timeline (Gantt chart)**:
-
-```
-Time →   0ms    10ms    20ms    30ms    40ms    50ms
-         ├───────────────────────────────────────────┤
-tx.submit│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-         ├─────┤
-tx.valid │▓▓▓▓▓│
-         │     ├──────────┤
-tx.relay │     │▓▓▓▓▓▓▓▓▓▓│
-         │               ├────────────────────────────┤
-tx.apply │               │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-         │                         ├──────────────────┤
-ledger   │                         │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-```
-
----
-
-## Distributed Traces Across Nodes
-
-In distributed systems like rippled, traces span **multiple independent nodes**. The trace context must be propagated in network messages:
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant NodeA as Node A
-    participant NodeB as Node B
-    participant NodeC as Node C
-
-    Client->>NodeA: Submit TX<br/>(no trace context)
-
-    Note over NodeA: Creates new trace<br/>trace_id: abc123<br/>span: tx.receive
-
-    NodeA->>NodeB: Relay TX<br/>(trace_id: abc123, parent: 001)
-
-    Note over NodeB: Creates child span<br/>span: tx.relay<br/>parent_span_id: 001
-
-    NodeA->>NodeC: Relay TX<br/>(trace_id: abc123, parent: 001)
-
-    Note over NodeC: Creates child span<br/>span: tx.relay<br/>parent_span_id: 001
-
-    Note over NodeA,NodeC: All spans share trace_id: abc123<br/>enabling correlation across nodes
-```
-
----
-
-## Context Propagation
-
-For traces to work across nodes, **trace context must be propagated** in messages.
-
-### What's in the Context (32 bytes)
-
-| Field         | Size       | Description                                             |
-| ------------- | ---------- | ------------------------------------------------------- |
-| `trace_id`    | 16 bytes   | Identifies the entire trace (constant across all nodes) |
-| `span_id`     | 8 bytes    | The sender's current span (becomes parent on receiver)  |
-| `trace_flags` | 4 bytes    | Sampling decision flags                                 |
-| `trace_state` | ~0-4 bytes | Optional vendor-specific data                           |
-
-### How span_id Changes at Each Hop
-
-Only **one** `span_id` travels in the context - the sender's current span. Each node:
-
-1. Extracts the received `span_id` and uses it as the `parent_span_id`
-2. Creates a **new** `span_id` for its own span
-3. Sends its own `span_id` as the parent when forwarding
-
-```
-Node A                      Node B                      Node C
-──────                      ──────                      ──────
-
-Span AAA                    Span BBB                    Span CCC
-   │                           │                           │
-   ▼                           ▼                           ▼
-Context out:                Context out:                Context out:
-├─ trace_id: abc123         ├─ trace_id: abc123         ├─ trace_id: abc123
-├─ span_id: AAA ──────────► ├─ span_id: BBB ──────────► ├─ span_id: CCC ──────►
-└─ flags: 01                └─ flags: 01                └─ flags: 01
-                               │                           │
-                          parent = AAA               parent = BBB
-```
-
-The `trace_id` stays constant, but `span_id` **changes at every hop** to maintain the parent-child chain.
-
-### Propagation Formats
-
-There are two patterns:
-
-### HTTP/RPC Headers (W3C Trace Context)
-
-```
-traceparent: 00-abc123def456-span789-01
-             │  │             │      │
-             │  │             │      └── Flags (sampled)
-             │  │             └── Parent span ID
-             │  └── Trace ID
-             └── Version
-```
-
-### Protocol Buffers (rippled P2P messages)
-
-```protobuf
-message TMTransaction {
-    bytes rawTransaction = 1;
-    // ... existing fields ...
-
-    // Trace context extension
-    bytes trace_parent = 100;  // W3C traceparent
-    bytes trace_state = 101;   // W3C tracestate
-}
-```
-
----
-
-## Sampling
-
-Not every trace needs to be recorded. **Sampling** reduces overhead:
-
-### Head Sampling (at trace start)
-
-```
-Request arrives → Random 10% chance → Record or skip entire trace
-```
-
-- ✅ Low overhead
-- ❌ May miss interesting traces
-
-### Tail Sampling (after trace completes)
-
-```
-Trace completes → Collector evaluates:
-                  - Error? → KEEP
-                  - Slow? → KEEP
-                  - Normal? → Sample 10%
-```
-
-- ✅ Never loses important traces
-- ❌ Higher memory usage at collector
-
----
-
-## Key Benefits for rippled
-
-| Challenge                          | How Tracing Helps                        |
-| ---------------------------------- | ---------------------------------------- |
-| "Where is my transaction?"         | Follow trace across all nodes it touched |
-| "Why was consensus slow?"          | See timing breakdown of each phase       |
-| "Which node is the bottleneck?"    | Compare span durations across nodes      |
-| "What happened during the outage?" | Correlate errors across the network      |
-
----
-
-## Glossary
-
-| Term                | Definition                                                      |
-| ------------------- | --------------------------------------------------------------- |
-| **Trace**           | Complete journey of a request, identified by `trace_id`         |
-| **Span**            | Single operation within a trace                                 |
-| **Context**         | Data propagated between services (`trace_id`, `span_id`, flags) |
-| **Instrumentation** | Code that creates spans and propagates context                  |
-| **Collector**       | Service that receives, processes, and exports traces            |
-| **Backend**         | Storage/visualization system (Jaeger, Tempo, etc.)              |
-| **Head Sampling**   | Sampling decision at trace start                                |
-| **Tail Sampling**   | Sampling decision after trace completes                         |
-
----
-
-_Next: [Architecture Analysis](./01-architecture-analysis.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/01-architecture-analysis.md

@@ -1,330 +0,0 @@
-# Architecture Analysis
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Design Decisions](./02-design-decisions.md) | [Implementation Strategy](./03-implementation-strategy.md)
-
----
-
-## 1.1 Current rippled Architecture Overview
-
-The rippled node software consists of several interconnected components that need instrumentation for distributed tracing:
-
-```mermaid
-flowchart TB
-    subgraph rippled["rippled Node"]
-        subgraph services["Core Services"]
-            RPC["RPC Server<br/>(HTTP/WS/gRPC)"]
-            Overlay["Overlay<br/>(P2P Network)"]
-            Consensus["Consensus<br/>(RCLConsensus)"]
-        end
-
-        JobQueue["JobQueue<br/>(Thread Pool)"]
-
-        subgraph processing["Processing Layer"]
-            NetworkOPs["NetworkOPs<br/>(Tx Processing)"]
-            LedgerMaster["LedgerMaster<br/>(Ledger Mgmt)"]
-            NodeStore["NodeStore<br/>(Database)"]
-        end
-
-        subgraph observability["Existing Observability"]
-            PerfLog["PerfLog<br/>(JSON)"]
-            Insight["Insight<br/>(StatsD)"]
-            Logging["Logging<br/>(Journal)"]
-        end
-
-        services --> JobQueue
-        JobQueue --> processing
-    end
-
-    style rippled fill:#424242,stroke:#212121,color:#ffffff
-    style services fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style processing fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style observability fill:#e65100,stroke:#bf360c,color:#ffffff
-```
-
----
-
-## 1.2 Key Components for Instrumentation
-
-| Component         | Location                                   | Purpose                  | Trace Value                  |
-| ----------------- | ------------------------------------------ | ------------------------ | ---------------------------- |
-| **Overlay**       | `src/xrpld/overlay/`                       | P2P communication        | Message propagation timing   |
-| **PeerImp**       | `src/xrpld/overlay/detail/PeerImp.cpp`     | Individual peer handling | Per-peer latency             |
-| **RCLConsensus**  | `src/xrpld/app/consensus/RCLConsensus.cpp` | Consensus algorithm      | Round timing, phase analysis |
-| **NetworkOPs**    | `src/xrpld/app/misc/NetworkOPs.cpp`        | Transaction processing   | Tx lifecycle tracking        |
-| **ServerHandler** | `src/xrpld/rpc/detail/ServerHandler.cpp`   | RPC entry point          | Request latency              |
-| **RPCHandler**    | `src/xrpld/rpc/detail/RPCHandler.cpp`      | Command execution        | Per-command timing           |
-| **JobQueue**      | `src/xrpl/core/JobQueue.h`                 | Async task execution     | Queue wait times             |
-
----
-
-## 1.3 Transaction Flow Diagram
-
-Transaction flow spans multiple nodes in the network. Each node creates linked spans to form a distributed trace:
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant PeerA as Peer A (Receive)
-    participant PeerB as Peer B (Relay)
-    participant PeerC as Peer C (Validate)
-
-    Client->>PeerA: 1. Submit TX
-
-    rect rgb(230, 245, 255)
-        Note over PeerA: tx.receive SPAN START
-        PeerA->>PeerA: HashRouter Deduplication
-        PeerA->>PeerA: tx.validate (child span)
-    end
-
-    PeerA->>PeerB: 2. Relay TX (with trace ctx)
-
-    rect rgb(230, 245, 255)
-        Note over PeerB: tx.receive (linked span)
-    end
-
-    PeerB->>PeerC: 3. Relay TX
-
-    rect rgb(230, 245, 255)
-        Note over PeerC: tx.receive (linked span)
-        PeerC->>PeerC: tx.process
-    end
-
-    Note over Client,PeerC: DISTRIBUTED TRACE (same trace_id: abc123)
-```
-
-### Trace Structure
-
-```
-trace_id: abc123
-├── span: tx.receive (Peer A)
-│   ├── span: tx.validate
-│   └── span: tx.relay
-├── span: tx.receive (Peer B) [parent: Peer A]
-│   └── span: tx.relay
-└── span: tx.receive (Peer C) [parent: Peer B]
-    └── span: tx.process
-```
-
----
-
-## 1.4 Consensus Round Flow
-
-Consensus rounds are multi-phase operations that benefit significantly from tracing:
-
-```mermaid
-flowchart TB
-    subgraph round["consensus.round (root span)"]
-        attrs["Attributes:<br/>xrpl.consensus.ledger.seq = 12345678<br/>xrpl.consensus.mode = proposing<br/>xrpl.consensus.proposers = 35"]
-
-        subgraph open["consensus.phase.open"]
-            open_desc["Duration: ~3s<br/>Waiting for transactions"]
-        end
-
-        subgraph establish["consensus.phase.establish"]
-            est_attrs["proposals_received = 28<br/>disputes_resolved = 3"]
-            est_children["├── consensus.proposal.receive (×28)<br/>├── consensus.proposal.send (×1)<br/>└── consensus.dispute.resolve (×3)"]
-        end
-
-        subgraph accept["consensus.phase.accept"]
-            acc_attrs["transactions_applied = 150<br/>ledger.hash = DEF456..."]
-            acc_children["├── ledger.build<br/>└── ledger.validate"]
-        end
-
-        attrs --> open
-        open --> establish
-        establish --> accept
-    end
-
-    style round fill:#f57f17,stroke:#e65100,color:#ffffff
-    style open fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style establish fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style accept fill:#c2185b,stroke:#880e4f,color:#ffffff
-```
-
----
-
-## 1.5 RPC Request Flow
-
-RPC requests support W3C Trace Context headers for distributed tracing across services:
-
-```mermaid
-flowchart TB
-    subgraph request["rpc.request (root span)"]
-        http["HTTP Request<br/>POST /<br/>traceparent: 00-abc123...-def456...-01"]
-
-        attrs["Attributes:<br/>http.method = POST<br/>net.peer.ip = 192.168.1.100<br/>xrpl.rpc.command = submit"]
-
-        subgraph enqueue["jobqueue.enqueue"]
-            job_attr["xrpl.job.type = jtCLIENT_RPC"]
-        end
-
-        subgraph command["rpc.command.submit"]
-            cmd_attrs["xrpl.rpc.version = 2<br/>xrpl.rpc.role = user"]
-            cmd_children["├── tx.deserialize<br/>├── tx.validate_local<br/>└── tx.submit_to_network"]
-        end
-
-        response["Response: 200 OK<br/>Duration: 45ms"]
-
-        http --> attrs
-        attrs --> enqueue
-        enqueue --> command
-        command --> response
-    end
-
-    style request fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style enqueue fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style command fill:#e65100,stroke:#bf360c,color:#ffffff
-```
-
----
-
-## 1.6 Key Trace Points
-
-The following table identifies priority instrumentation points across the codebase:
-
-| Category        | Span Name              | File                 | Method                 | Priority |
-| --------------- | ---------------------- | -------------------- | ---------------------- | -------- |
-| **Transaction** | `tx.receive`           | `PeerImp.cpp`        | `handleTransaction()`  | High     |
-| **Transaction** | `tx.validate`          | `NetworkOPs.cpp`     | `processTransaction()` | High     |
-| **Transaction** | `tx.process`           | `NetworkOPs.cpp`     | `doTransactionSync()`  | High     |
-| **Transaction** | `tx.relay`             | `OverlayImpl.cpp`    | `relay()`              | Medium   |
-| **Consensus**   | `consensus.round`      | `RCLConsensus.cpp`   | `startRound()`         | High     |
-| **Consensus**   | `consensus.phase.*`    | `Consensus.h`        | `timerEntry()`         | High     |
-| **Consensus**   | `consensus.proposal.*` | `RCLConsensus.cpp`   | `peerProposal()`       | Medium   |
-| **RPC**         | `rpc.request`          | `ServerHandler.cpp`  | `onRequest()`          | High     |
-| **RPC**         | `rpc.command.*`        | `RPCHandler.cpp`     | `doCommand()`          | High     |
-| **Peer**        | `peer.connect`         | `OverlayImpl.cpp`    | `onHandoff()`          | Low      |
-| **Peer**        | `peer.message.*`       | `PeerImp.cpp`        | `onMessage()`          | Low      |
-| **Ledger**      | `ledger.acquire`       | `InboundLedgers.cpp` | `acquire()`            | Medium   |
-| **Ledger**      | `ledger.build`         | `RCLConsensus.cpp`   | `buildLCL()`           | High     |
-
----
-
-## 1.7 Instrumentation Priority
-
-```mermaid
-quadrantChart
-    title Instrumentation Priority Matrix
-    x-axis Low Complexity --> High Complexity
-    y-axis Low Value --> High Value
-    quadrant-1 Implement First
-    quadrant-2 Plan Carefully
-    quadrant-3 Quick Wins
-    quadrant-4 Consider Later
-
-    RPC Tracing: [0.3, 0.85]
-    Transaction Tracing: [0.65, 0.92]
-    Consensus Tracing: [0.75, 0.87]
-    Peer Message Tracing: [0.4, 0.3]
-    Ledger Acquisition: [0.5, 0.6]
-    JobQueue Tracing: [0.35, 0.5]
-```
-
----
-
-## 1.8 Observable Outcomes
-
-After implementing OpenTelemetry, operators and developers will gain visibility into the following:
-
-### 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"}`                         |
-
-### 1.8.2 What You Will See: Metrics (Derived from Traces)
-
-| Metric                        | Description                            | Dashboard Panel             |
-| ----------------------------- | -------------------------------------- | --------------------------- |
-| **RPC Latency (p50/p95/p99)** | Response time distribution per command | Heatmap by command          |
-| **Transaction Throughput**    | Transactions processed per second      | Time series graph           |
-| **Consensus Round Duration**  | Time to complete consensus phases      | Histogram                   |
-| **Cross-Node Latency**        | Time for transaction to reach N nodes  | Line chart with percentiles |
-| **Error Rate**                | Failed transactions/RPC calls by type  | Stacked bar chart           |
-
-### 1.8.3 Concrete Dashboard Examples
-
-**Transaction Trace View (Jaeger/Tempo):**
-
-```
-┌────────────────────────────────────────────────────────────────────────────────┐
-│ Trace: abc123... (Transaction Submission)                    Duration: 847ms   │
-├────────────────────────────────────────────────────────────────────────────────┤
-│ ├── rpc.request [ServerHandler]                              ████░░░░░░  45ms  │
-│ │   └── rpc.command.submit [RPCHandler]                      ████░░░░░░  42ms  │
-│ │       └── tx.receive [NetworkOPs]                          ███░░░░░░░  35ms  │
-│ │           ├── tx.validate [TxQ]                            █░░░░░░░░░   8ms  │
-│ │           └── tx.relay [Overlay]                           ██░░░░░░░░  15ms  │
-│ │               ├── tx.receive [Node-B]                      █████░░░░░  52ms  │
-│ │               │   └── tx.relay [Node-B]                    ██░░░░░░░░  18ms  │
-│ │               └── tx.receive [Node-C]                      ██████░░░░  65ms  │
-│ └── consensus.round [RCLConsensus]                           ████████░░ 720ms  │
-│     ├── consensus.phase.open                                 ██░░░░░░░░ 180ms  │
-│     ├── consensus.phase.establish                            █████░░░░░ 480ms  │
-│     └── consensus.phase.accept                               █░░░░░░░░░  60ms  │
-└────────────────────────────────────────────────────────────────────────────────┘
-```
-
-**RPC Performance Dashboard Panel:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ RPC Command Latency (Last 1 Hour)                           │
-├─────────────────────────────────────────────────────────────┤
-│ Command          │ p50    │ p95    │ p99    │ Errors │ Rate │
-│──────────────────┼────────┼────────┼────────┼────────┼──────│
-│ account_info     │  12ms  │  45ms  │  89ms  │  0.1%  │ 150/s│
-│ submit           │  35ms  │ 120ms  │ 250ms  │  2.3%  │  45/s│
-│ ledger           │   8ms  │  25ms  │  55ms  │  0.0%  │  80/s│
-│ tx               │  15ms  │  50ms  │ 100ms  │  0.5%  │  60/s│
-│ server_info      │   5ms  │  12ms  │  20ms  │  0.0%  │ 200/s│
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Consensus Health Dashboard Panel:**
-
-```mermaid
----
-config:
-    xyChart:
-        width: 1200
-        height: 400
-        plotReservedSpacePercent: 50
-        chartOrientation: vertical
-    themeVariables:
-        xyChart:
-            plotColorPalette: "#3498db"
----
-xychart-beta
-    title "Consensus Round Duration (Last 24 Hours)"
-    x-axis "Time of Day (Hours)" [0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24]
-    y-axis "Duration (seconds)" 1 --> 5
-    line [2.1, 2.3, 2.5, 2.4, 2.8, 1.6, 3.2, 3.0, 3.5, 1.3, 3.8, 3.6, 4.0, 3.2, 4.3, 4.1, 4.5, 4.3, 4.2, 2.4, 4.8, 4.6, 4.9, 4.7, 5.0, 4.9, 4.8, 2.6, 4.7, 4.5, 4.2, 4.0, 2.5, 3.7, 3.2, 3.4, 2.9, 3.1, 2.6, 2.8, 2.3, 1.5, 2.7, 2.4, 2.5, 2.3, 2.2, 2.1, 2.0]
-```
-
-### 1.8.4 Operator Actionable Insights
-
-| Scenario              | What You'll See                                                              | Action                           |
-| --------------------- | ---------------------------------------------------------------------------- | -------------------------------- |
-| **Slow RPC**          | Span showing which phase is slow (parsing, execution, serialization)         | Optimize specific code path      |
-| **Transaction Stuck** | Trace stops at validation; error attribute shows reason                      | Fix transaction parameters       |
-| **Consensus Delay**   | Phase.establish taking too long; proposer attribute shows missing validators | Investigate network connectivity |
-| **Memory Spike**      | Large batch of spans correlating with memory increase                        | Tune batch_size or sampling      |
-| **Network Partition** | Traces missing cross-node links for specific peer                            | Check peer connectivity          |
-
-### 1.8.5 Developer Debugging Workflow
-
-1. **Find Transaction**: Query by `xrpl.tx.hash` to get full trace
-2. **Identify Bottleneck**: Look at span durations to find slowest component
-3. **Check Attributes**: Review `xrpl.tx.validity`, `xrpl.rpc.status` for errors
-4. **Correlate Logs**: Use `trace_id` to find related PerfLog entries
-5. **Compare Nodes**: Filter by `service.instance.id` to compare behavior across nodes
-
----
-
-_Next: [Design Decisions](./02-design-decisions.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/02-design-decisions.md

@@ -1,498 +0,0 @@
-# Design Decisions
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Architecture Analysis](./01-architecture-analysis.md) | [Code Samples](./04-code-samples.md)
-
----
-
-## 2.1 OpenTelemetry Components
-
-### 2.1.1 SDK Selection
-
-**Primary Choice**: OpenTelemetry C++ SDK (`opentelemetry-cpp`)
-
-| Component                               | Purpose                | Required    |
-| --------------------------------------- | ---------------------- | ----------- |
-| `opentelemetry-cpp::api`                | Tracing API headers    | Yes         |
-| `opentelemetry-cpp::sdk`                | SDK implementation     | Yes         |
-| `opentelemetry-cpp::ext`                | Extensions (exporters) | Yes         |
-| `opentelemetry-cpp::otlp_grpc_exporter` | OTLP/gRPC export       | Recommended |
-| `opentelemetry-cpp::otlp_http_exporter` | OTLP/HTTP export       | Alternative |
-
-### 2.1.2 Instrumentation Strategy
-
-**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 |
-
----
-
-## 2.2 Exporter Configuration
-
-```mermaid
-flowchart TB
-    subgraph nodes["rippled Nodes"]
-        node1["rippled<br/>Node 1"]
-        node2["rippled<br/>Node 2"]
-        node3["rippled<br/>Node 3"]
-    end
-
-    collector["OpenTelemetry<br/>Collector<br/>(sidecar or standalone)"]
-
-    subgraph backends["Observability Backends"]
-        jaeger["Jaeger<br/>(Dev)"]
-        tempo["Tempo<br/>(Prod)"]
-        elastic["Elastic<br/>APM"]
-    end
-
-    node1 -->|"OTLP/gRPC<br/>:4317"| collector
-    node2 -->|"OTLP/gRPC<br/>:4317"| collector
-    node3 -->|"OTLP/gRPC<br/>:4317"| collector
-
-    collector --> jaeger
-    collector --> tempo
-    collector --> elastic
-
-    style nodes fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style backends fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style collector fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-### 2.2.1 OTLP/gRPC (Recommended)
-
-```cpp
-// Configuration for OTLP over gRPC
-namespace otlp = opentelemetry::exporter::otlp;
-
-otlp::OtlpGrpcExporterOptions opts;
-opts.endpoint = "localhost:4317";
-opts.use_ssl_credentials = true;
-opts.ssl_credentials_cacert_path = "/path/to/ca.crt";
-```
-
-### 2.2.2 OTLP/HTTP (Alternative)
-
-```cpp
-// Configuration for OTLP over HTTP
-namespace otlp = opentelemetry::exporter::otlp;
-
-otlp::OtlpHttpExporterOptions opts;
-opts.url = "http://localhost:4318/v1/traces";
-opts.content_type = otlp::HttpRequestContentType::kJson;  // or kBinary
-```
-
----
-
-## 2.3 Span Naming Conventions
-
-### 2.3.1 Naming Schema
-
-```
-<component>.<operation>[.<sub-operation>]
-```
-
-**Examples**:
-
-- `tx.receive` - Transaction received from peer
-- `consensus.phase.establish` - Consensus establish phase
-- `rpc.command.server_info` - server_info RPC command
-
-### 2.3.2 Complete Span Catalog
-
-```yaml
-# Transaction Spans
-tx:
-  receive: "Transaction received from network"
-  validate: "Transaction signature/format validation"
-  process: "Full transaction processing"
-  relay: "Transaction relay to peers"
-  apply: "Apply transaction to ledger"
-
-# Consensus Spans
-consensus:
-  round: "Complete consensus round"
-  phase:
-    open: "Open phase - collecting transactions"
-    establish: "Establish phase - reaching agreement"
-    accept: "Accept phase - applying consensus"
-  proposal:
-    receive: "Receive peer proposal"
-    send: "Send our proposal"
-  validation:
-    receive: "Receive peer validation"
-    send: "Send our validation"
-
-# RPC Spans
-rpc:
-  request: "HTTP/WebSocket request handling"
-  command:
-    "*": "Specific RPC command (dynamic)"
-
-# Peer Spans
-peer:
-  connect: "Peer connection establishment"
-  disconnect: "Peer disconnection"
-  message:
-    send: "Send protocol message"
-    receive: "Receive protocol message"
-
-# Ledger Spans
-ledger:
-  acquire: "Ledger acquisition from network"
-  build: "Build new ledger"
-  validate: "Ledger validation"
-  close: "Close ledger"
-
-# Job Spans
-job:
-  enqueue: "Job added to queue"
-  execute: "Job execution"
-```
-
----
-
-## 2.4 Attribute Schema
-
-### 2.4.1 Resource Attributes (Set Once at Startup)
-
-```cpp
-// Standard OpenTelemetry semantic conventions
-resource::SemanticConventions::SERVICE_NAME        = "rippled"
-resource::SemanticConventions::SERVICE_VERSION     = BuildInfo::getVersionString()
-resource::SemanticConventions::SERVICE_INSTANCE_ID = <node_public_key_base58>
-
-// Custom rippled attributes
-"xrpl.network.id"      = <network_id>           // e.g., 0 for mainnet
-"xrpl.network.type"    = "mainnet" | "testnet" | "devnet" | "standalone"
-"xrpl.node.type"       = "validator" | "stock" | "reporting"
-"xrpl.node.cluster"    = <cluster_name>         // If clustered
-```
-
-### 2.4.2 Span Attributes by Category
-
-#### Transaction Attributes
-
-```cpp
-"xrpl.tx.hash"         = string   // Transaction hash (hex)
-"xrpl.tx.type"         = string   // "Payment", "OfferCreate", etc.
-"xrpl.tx.account"      = string   // Source account (redacted in prod)
-"xrpl.tx.sequence"     = int64    // Account sequence number
-"xrpl.tx.fee"          = int64    // Fee in drops
-"xrpl.tx.result"       = string   // "tesSUCCESS", "tecPATH_DRY", etc.
-"xrpl.tx.ledger_index" = int64    // Ledger containing transaction
-```
-
-#### Consensus Attributes
-
-```cpp
-"xrpl.consensus.round"          = int64    // Round number
-"xrpl.consensus.phase"          = string   // "open", "establish", "accept"
-"xrpl.consensus.mode"           = string   // "proposing", "observing", etc.
-"xrpl.consensus.proposers"      = int64    // Number of proposers
-"xrpl.consensus.ledger.prev"    = string   // Previous ledger hash
-"xrpl.consensus.ledger.seq"     = int64    // Ledger sequence
-"xrpl.consensus.tx_count"       = int64    // Transactions in consensus set
-"xrpl.consensus.duration_ms"    = float64  // Round duration
-```
-
-#### RPC Attributes
-
-```cpp
-"xrpl.rpc.command"     = string   // Command name
-"xrpl.rpc.version"     = int64    // API version
-"xrpl.rpc.role"        = string   // "admin" or "user"
-"xrpl.rpc.params"      = string   // Sanitized parameters (optional)
-```
-
-#### Peer & Message Attributes
-
-```cpp
-"xrpl.peer.id"            = string   // Peer public key (base58)
-"xrpl.peer.address"       = string   // IP:port
-"xrpl.peer.latency_ms"    = float64  // Measured latency
-"xrpl.peer.cluster"       = string   // Cluster name if clustered
-"xrpl.message.type"       = string   // Protocol message type name
-"xrpl.message.size_bytes" = int64    // Message size
-"xrpl.message.compressed" = bool     // Whether compressed
-```
-
-#### Ledger & Job Attributes
-
-```cpp
-"xrpl.ledger.hash"       = string   // Ledger hash
-"xrpl.ledger.index"      = int64    // Ledger sequence/index
-"xrpl.ledger.close_time" = int64    // Close time (epoch)
-"xrpl.ledger.tx_count"   = int64    // Transaction count
-"xrpl.job.type"          = string   // Job type name
-"xrpl.job.queue_ms"      = float64  // Time spent in queue
-"xrpl.job.worker"        = int64    // Worker thread ID
-```
-
-### 2.4.3 Data Collection Summary
-
-The following table summarizes what data is collected by category:
-
-| Category        | Attributes Collected                                                 | Purpose                     |
-| --------------- | -------------------------------------------------------------------- | --------------------------- |
-| **Transaction** | `tx.hash`, `tx.type`, `tx.result`, `tx.fee`, `ledger_index`          | Trace transaction lifecycle |
-| **Consensus**   | `round`, `phase`, `mode`, `proposers` (public keys), `duration_ms`   | Analyze consensus timing    |
-| **RPC**         | `command`, `version`, `status`, `duration_ms`                        | Monitor RPC performance     |
-| **Peer**        | `peer.id` (public key), `latency_ms`, `message.type`, `message.size` | Network topology analysis   |
-| **Ledger**      | `ledger.hash`, `ledger.index`, `close_time`, `tx_count`              | Ledger progression tracking |
-| **Job**         | `job.type`, `queue_ms`, `worker`                                     | JobQueue performance        |
-
-### 2.4.4 Privacy & Sensitive Data Policy
-
-OpenTelemetry instrumentation is designed to collect **operational metadata only**, never sensitive content.
-
-#### Data NOT Collected
-
-The following data is explicitly **excluded** from telemetry collection:
-
-| Excluded Data           | Reason                                    |
-| ----------------------- | ----------------------------------------- |
-| **Private Keys**        | Never exposed; not relevant to tracing    |
-| **Account Balances**    | Financial data; privacy sensitive         |
-| **Transaction Amounts** | Financial data; privacy sensitive         |
-| **Raw TX Payloads**     | May contain sensitive memo/data fields    |
-| **Personal Data**       | No PII collected                          |
-| **IP Addresses**        | Configurable; excluded by default in prod |
-
-#### Privacy Protection Mechanisms
-
-| Mechanism                     | Description                                                               |
-| ----------------------------- | ------------------------------------------------------------------------- |
-| **Account Hashing**           | `xrpl.tx.account` is hashed at collector level before storage             |
-| **Configurable Redaction**    | Sensitive fields can be excluded via `[telemetry]` config section         |
-| **Sampling**                  | Only 10% of traces recorded by default, reducing data exposure            |
-| **Local Control**             | Node operators have full control over what gets exported                  |
-| **No Raw Payloads**           | Transaction content is never recorded, only metadata (hash, type, result) |
-| **Collector-Level Filtering** | Additional redaction/hashing can be configured at OTel Collector          |
-
-#### Collector-Level Data Protection
-
-The OpenTelemetry Collector can be configured to hash or redact sensitive attributes before export:
-
-```yaml
-processors:
-  attributes:
-    actions:
-      # Hash account addresses before storage
-      - key: xrpl.tx.account
-        action: hash
-      # Remove IP addresses entirely
-      - key: xrpl.peer.address
-        action: delete
-      # Redact specific fields
-      - key: xrpl.rpc.params
-        action: delete
-```
-
-#### Configuration Options for Privacy
-
-In `rippled.cfg`, operators can control data collection granularity:
-
-```ini
-[telemetry]
-enabled=1
-
-# Disable collection of specific components
-trace_transactions=1
-trace_consensus=1
-trace_rpc=1
-trace_peer=0          # Disable peer tracing (high volume, includes addresses)
-
-# Redact specific attributes
-redact_account=1      # Hash account addresses before export
-redact_peer_address=1 # Remove peer IP addresses
-```
-
-> **Key Principle**: Telemetry collects **operational metadata** (timing, counts, hashes) — never **sensitive content** (keys, balances, amounts, raw payloads).
-
----
-
-## 2.5 Context Propagation Design
-
-### 2.5.1 Propagation Boundaries
-
-```mermaid
-flowchart TB
-    subgraph http["HTTP/WebSocket (RPC)"]
-        w3c["W3C Trace Context Headers:<br/>traceparent: 00-{trace_id}-{span_id}-{flags}<br/>tracestate: rippled=<state>"]
-    end
-
-    subgraph protobuf["Protocol Buffers (P2P)"]
-        proto["message TraceContext {<br/>  bytes trace_id = 1;  // 16 bytes<br/>  bytes span_id = 2;   // 8 bytes<br/>  uint32 trace_flags = 3;<br/>  string trace_state = 4;<br/>}"]
-    end
-
-    subgraph jobqueue["JobQueue (Internal Async)"]
-        job["Context captured at job creation,<br/>restored at execution<br/><br/>class Job {<br/>  opentelemetry::context::Context traceContext_;<br/>};"]
-    end
-
-    style http fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style protobuf fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style jobqueue fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
----
-
-## 2.6 Integration with Existing Observability
-
-### 2.6.1 Existing Frameworks Comparison
-
-rippled already has two observability mechanisms. OpenTelemetry complements (not replaces) them:
-
-| Aspect                | PerfLog                       | Beast Insight (StatsD)       | OpenTelemetry             |
-| --------------------- | ----------------------------- | ---------------------------- | ------------------------- |
-| **Type**              | Logging                       | Metrics                      | Distributed Tracing       |
-| **Data**              | JSON log entries              | Counters, gauges, histograms | Spans with context        |
-| **Scope**             | Single node                   | Single node                  | **Cross-node**            |
-| **Output**            | `perf.log` file               | StatsD server                | OTLP Collector            |
-| **Question answered** | "What happened on this node?" | "How many? How fast?"        | "What was the journey?"   |
-| **Correlation**       | By timestamp                  | By metric name               | By `trace_id`             |
-| **Overhead**          | Low (file I/O)                | Low (UDP packets)            | Low-Medium (configurable) |
-
-### 2.6.2 What Each Framework Does Best
-
-#### PerfLog
-
-- **Purpose**: Detailed local event logging for RPC and job execution
-- **Strengths**:
-  - Rich JSON output with timing data
-  - Already integrated in RPC handlers
-  - File-based, no external dependencies
-- **Limitations**:
-  - Single-node only (no cross-node correlation)
-  - No parent-child relationships between events
-  - Manual log parsing required
-
-```json
-// Example PerfLog entry
-{
-  "time": "2024-01-15T10:30:00.123Z",
-  "method": "submit",
-  "duration_us": 1523,
-  "result": "tesSUCCESS"
-}
-```
-
-#### Beast Insight (StatsD)
-
-- **Purpose**: Real-time metrics for monitoring dashboards
-- **Strengths**:
-  - Aggregated metrics (counters, gauges, histograms)
-  - Low overhead (UDP, fire-and-forget)
-  - Good for alerting thresholds
-- **Limitations**:
-  - No request-level detail
-  - No causal relationships
-  - Single-node perspective
-
-```cpp
-// Example StatsD usage in rippled
-insight.increment("rpc.submit.count");
-insight.gauge("ledger.age", age);
-insight.timing("consensus.round", duration);
-```
-
-#### OpenTelemetry (NEW)
-
-- **Purpose**: Distributed request tracing across nodes
-- **Strengths**:
-  - **Cross-node correlation** via `trace_id`
-  - Parent-child span relationships
-  - Rich attributes per span
-  - Industry standard (CNCF)
-- **Limitations**:
-  - Requires collector infrastructure
-  - Higher complexity than logging
-
-```cpp
-// Example OpenTelemetry span
-auto span = telemetry.startSpan("tx.relay");
-span->SetAttribute("tx.hash", hash);
-span->SetAttribute("peer.id", peerId);
-// Span automatically linked to parent via context
-```
-
-### 2.6.3 When to Use Each
-
-| Scenario                                | PerfLog    | StatsD | OpenTelemetry |
-| --------------------------------------- | ---------- | ------ | ------------- |
-| "How many TXs per second?"              | ❌         | ✅     | ❌            |
-| "What's the p99 RPC latency?"           | ❌         | ✅     | ✅            |
-| "Why was this specific TX slow?"        | ⚠️ partial | ❌     | ✅            |
-| "Which node delayed consensus?"         | ❌         | ❌     | ✅            |
-| "What happened on node X at time T?"    | ✅         | ❌     | ✅            |
-| "Show me the TX journey across 5 nodes" | ❌         | ❌     | ✅            |
-
-### 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"]
-        perflog["PerfLog<br/>(JSON to file)"]
-        insight["Beast Insight<br/>(StatsD)"]
-        otel["OpenTelemetry<br/>(Tracing)"]
-    end
-
-    perflog --> perffile["perf.log"]
-    insight --> statsd["StatsD Server"]
-    otel --> collector["OTLP Collector"]
-
-    perffile --> grafana["Grafana<br/>(Unified UI)"]
-    statsd --> grafana
-    collector --> grafana
-
-    style rippled fill:#212121,stroke:#0a0a0a,color:#ffffff
-    style grafana fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**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:
-
-```cpp
-// In RPCHandler.cpp - correlate trace with PerfLog
-Status doCommand(RPC::JsonContext& context, Json::Value& result)
-{
-    // Start OpenTelemetry span
-    auto span = context.app.getTelemetry().startSpan(
-        "rpc.command." + context.method);
-
-    // Get trace ID for correlation
-    auto traceId = span->GetContext().trace_id().IsValid()
-        ? toHex(span->GetContext().trace_id())
-        : "";
-
-    // Use existing PerfLog with trace correlation
-    auto const curId = context.app.getPerfLog().currentId();
-    context.app.getPerfLog().rpcStart(context.method, curId);
-
-    // Future: Add trace ID to PerfLog entry
-    // context.app.getPerfLog().setTraceId(curId, traceId);
-
-    try {
-        auto ret = handler(context, result);
-        context.app.getPerfLog().rpcFinish(context.method, curId);
-        span->SetStatus(opentelemetry::trace::StatusCode::kOk);
-        return ret;
-    } catch (std::exception const& e) {
-        context.app.getPerfLog().rpcError(context.method, curId);
-        span->RecordException(e);
-        span->SetStatus(opentelemetry::trace::StatusCode::kError, e.what());
-        throw;
-    }
-}
-```
-
----
-
-_Previous: [Architecture Analysis](./01-architecture-analysis.md)_ | _Next: [Implementation Strategy](./03-implementation-strategy.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/03-implementation-strategy.md

@@ -1,451 +0,0 @@
-# Implementation Strategy
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Code Samples](./04-code-samples.md) | [Configuration Reference](./05-configuration-reference.md)
-
----
-
-## 3.1 Directory Structure
-
-The telemetry implementation follows rippled's existing code organization pattern:
-
-```
-include/xrpl/
-├── telemetry/
-│   ├── Telemetry.h              # Main telemetry interface
-│   ├── TelemetryConfig.h        # Configuration structures
-│   ├── TraceContext.h           # Context propagation utilities
-│   ├── SpanGuard.h              # RAII span management
-│   └── SpanAttributes.h         # Attribute helper functions
-
-src/libxrpl/
-├── telemetry/
-│   ├── Telemetry.cpp            # Implementation
-│   ├── TelemetryConfig.cpp      # Config parsing
-│   ├── TraceContext.cpp         # Context serialization
-│   └── NullTelemetry.cpp        # No-op implementation
-
-src/xrpld/
-├── telemetry/
-│   ├── TracingInstrumentation.h # Instrumentation macros
-│   └── TracingInstrumentation.cpp
-```
-
----
-
-## 3.2 Implementation Approach
-
-<div align="center">
-
-```mermaid
-%%{init: {'flowchart': {'nodeSpacing': 20, 'rankSpacing': 30}}}%%
-flowchart TB
-    subgraph phase1["Phase 1: Core"]
-        direction LR
-        sdk["SDK Integration"] ~~~ interface["Telemetry Interface"] ~~~ config["Configuration"]
-    end
-
-    subgraph phase2["Phase 2: RPC"]
-        direction LR
-        http["HTTP Context"] ~~~ rpc["RPC Handlers"]
-    end
-
-    subgraph phase3["Phase 3: P2P"]
-        direction LR
-        proto["Protobuf Context"] ~~~ tx["Transaction Relay"]
-    end
-
-    subgraph phase4["Phase 4: Consensus"]
-        direction LR
-        consensus["Consensus Rounds"] ~~~ proposals["Proposals"]
-    end
-
-    phase1 --> phase2 --> phase3 --> phase4
-
-    style phase1 fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style phase2 fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style phase3 fill:#e65100,stroke:#bf360c,color:#ffffff
-    style phase4 fill:#c2185b,stroke:#880e4f,color:#ffffff
-```
-
-</div>
-
-### Key Principles
-
-1. **Minimal Intrusion**: Instrumentation should not alter existing control flow
-2. **Zero-Cost When Disabled**: Use compile-time flags and no-op implementations
-3. **Backward Compatibility**: Protocol Buffer extensions use high field numbers
-4. **Graceful Degradation**: Tracing failures must not affect node operation
-
----
-
-## 3.3 Performance Overhead Summary
-
-| Metric        | Overhead   | Notes                               |
-| ------------- | ---------- | ----------------------------------- |
-| CPU           | 1-3%       | Span creation and attribute setting |
-| Memory        | 2-5 MB     | Batch buffer for pending spans      |
-| Network       | 10-50 KB/s | Compressed OTLP export to collector |
-| Latency (p99) | <2%        | With proper sampling configuration  |
-
----
-
-## 3.4 Detailed CPU Overhead Analysis
-
-### 3.4.1 Per-Operation Costs
-
-| Operation             | Time (ns) | Frequency              | Impact     |
-| --------------------- | --------- | ---------------------- | ---------- |
-| Span creation         | 200-500   | Every traced operation | Low        |
-| Span end              | 100-200   | Every traced operation | Low        |
-| SetAttribute (string) | 80-120    | 3-5 per span           | Low        |
-| SetAttribute (int)    | 40-60     | 2-3 per span           | Negligible |
-| AddEvent              | 50-80     | 0-2 per span           | Negligible |
-| Context injection     | 150-250   | Per outgoing message   | Low        |
-| Context extraction    | 100-180   | Per incoming message   | Low        |
-| GetCurrent context    | 10-20     | Thread-local access    | Negligible |
-
-### 3.4.2 Transaction Processing Overhead
-
-<div align="center">
-
-```mermaid
-%%{init: {'pie': {'textPosition': 0.75}}}%%
-pie showData
-    "tx.receive (800ns)" : 800
-    "tx.validate (500ns)" : 500
-    "tx.relay (500ns)" : 500
-    "Context inject (600ns)" : 600
-```
-
-**Transaction Tracing Overhead (~2.4μs total)**
-
-</div>
-
-**Overhead percentage**: 2.4 μs / 200 μs (avg tx processing) = **~1.2%**
-
-### 3.4.3 Consensus Round Overhead
-
-| Operation              | Count | Cost (ns) | Total      |
-| ---------------------- | ----- | --------- | ---------- |
-| consensus.round span   | 1     | ~1000     | ~1 μs      |
-| consensus.phase spans  | 3     | ~700      | ~2.1 μs    |
-| proposal.receive spans | ~20   | ~600      | ~12 μs     |
-| proposal.send spans    | ~3    | ~600      | ~1.8 μs    |
-| Context operations     | ~30   | ~200      | ~6 μs      |
-| **TOTAL**              |       |           | **~23 μs** |
-
-**Overhead percentage**: 23 μs / 3s (typical round) = **~0.0008%** (negligible)
-
-### 3.4.4 RPC Request Overhead
-
-| Operation        | Cost (ns)    |
-| ---------------- | ------------ |
-| rpc.request span | ~700         |
-| rpc.command span | ~600         |
-| Context extract  | ~250         |
-| Context inject   | ~200         |
-| **TOTAL**        | **~1.75 μs** |
-
-- Fast RPC (1ms): 1.75 μs / 1ms = **~0.175%**
-- Slow RPC (100ms): 1.75 μs / 100ms = **~0.002%**
-
----
-
-## 3.5 Memory Overhead Analysis
-
-### 3.5.1 Static Memory
-
-| Component                | Size        | Allocated  |
-| ------------------------ | ----------- | ---------- |
-| TracerProvider singleton | ~64 KB      | At startup |
-| BatchSpanProcessor       | ~128 KB     | At startup |
-| OTLP exporter            | ~256 KB     | At startup |
-| Propagator registry      | ~8 KB       | At startup |
-| **Total static**         | **~456 KB** |            |
-
-### 3.5.2 Dynamic Memory
-
-| Component            | Size per unit | Max units  | Peak        |
-| -------------------- | ------------- | ---------- | ----------- |
-| Active span          | ~200 bytes    | 1000       | ~200 KB     |
-| Queued span (export) | ~500 bytes    | 2048       | ~1 MB       |
-| Attribute storage    | ~50 bytes     | 5 per span | Included    |
-| Context storage      | ~64 bytes     | Per thread | ~6.4 KB     |
-| **Total dynamic**    |               |            | **~1.2 MB** |
-
-### 3.5.3 Memory Growth Characteristics
-
-```mermaid
----
-config:
-    xyChart:
-        width: 700
-        height: 400
----
-xychart-beta
-    title "Memory Usage vs Span Rate"
-    x-axis "Spans/second" [0, 200, 400, 600, 800, 1000]
-    y-axis "Memory (MB)" 0 --> 6
-    line [1, 1.8, 2.6, 3.4, 4.2, 5]
-```
-
-**Notes**:
-
-- Memory increases linearly with span rate
-- Batch export prevents unbounded growth
-- Queue size is configurable (default 2048 spans)
-- At queue limit, oldest spans are dropped (not blocked)
-
----
-
-## 3.6 Network Overhead Analysis
-
-### 3.6.1 Export Bandwidth
-
-| Sampling Rate | Spans/sec | Bandwidth | Notes            |
-| ------------- | --------- | --------- | ---------------- |
-| 100%          | ~500      | ~250 KB/s | Development only |
-| 10%           | ~50       | ~25 KB/s  | Staging          |
-| 1%            | ~5        | ~2.5 KB/s | Production       |
-| Error-only    | ~1        | ~0.5 KB/s | Minimal overhead |
-
-### 3.6.2 Trace Context Propagation
-
-| Message Type           | Context Size | Messages/sec | Overhead    |
-| ---------------------- | ------------ | ------------ | ----------- |
-| TMTransaction          | 32 bytes     | ~100         | ~3.2 KB/s   |
-| TMProposeSet           | 32 bytes     | ~10          | ~320 B/s    |
-| TMValidation           | 32 bytes     | ~50          | ~1.6 KB/s   |
-| **Total P2P overhead** |              |              | **~5 KB/s** |
-
----
-
-## 3.7 Optimization Strategies
-
-### 3.7.1 Sampling Strategies
-
-```mermaid
-flowchart TD
-    trace["New Trace"]
-
-    trace --> errors{"Is Error?"}
-    errors -->|Yes| sample["SAMPLE"]
-    errors -->|No| consensus{"Is Consensus?"}
-
-    consensus -->|Yes| sample
-    consensus -->|No| slow{"Is Slow?"}
-
-    slow -->|Yes| sample
-    slow -->|No| prob{"Random < 10%?"}
-
-    prob -->|Yes| sample
-    prob -->|No| drop["DROP"]
-
-    style sample fill:#4caf50,stroke:#388e3c,color:#fff
-    style drop fill:#f44336,stroke:#c62828,color:#fff
-```
-
-### 3.7.2 Batch Tuning Recommendations
-
-| Environment        | Batch Size | Batch Delay | Max Queue |
-| ------------------ | ---------- | ----------- | --------- |
-| Low-latency        | 128        | 1000ms      | 512       |
-| High-throughput    | 1024       | 10000ms     | 8192      |
-| Memory-constrained | 256        | 2000ms      | 512       |
-
-### 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
-
-// Runtime component filtering
-if (telemetry.shouldTracePeer())
-{
-    XRPL_TRACE_SPAN(telemetry, "peer.message.receive");
-    // ... instrumentation
-}
-// No overhead when component tracing disabled
-```
-
----
-
-## 3.8 Links to Detailed Documentation
-
-- **[Code Samples](./04-code-samples.md)**: Complete implementation code for all components
-- **[Configuration Reference](./05-configuration-reference.md)**: Configuration options and collector setup
-- **[Implementation Phases](./06-implementation-phases.md)**: Detailed timeline and milestones
-
----
-
-## 3.9 Code Intrusiveness Assessment
-
-This section provides a detailed assessment of how intrusive the OpenTelemetry integration is to the existing rippled 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)    |
-| **Application Init**  | 2 files        | ~30         | ~5            | Minimal              |
-| **RPC Layer**         | 3 files        | ~80         | ~20           | Minimal              |
-| **Transaction Relay** | 4 files        | ~120        | ~40           | Low                  |
-| **Consensus**         | 3 files        | ~100        | ~30           | Low-Medium           |
-| **Protocol Buffers**  | 1 file         | ~25         | 0             | Low                  |
-| **CMake/Build**       | 3 files        | ~50         | ~10           | Minimal              |
-| **Total**             | **~21 files**  | **~1,205**  | **~105**      | **Low**              |
-
-### 3.9.2 Detailed File Impact
-
-```mermaid
-pie title Code Changes by Component
-    "New Telemetry Module" : 800
-    "Transaction Relay" : 160
-    "Consensus" : 130
-    "RPC Layer" : 100
-    "Application Init" : 35
-    "Protocol Buffers" : 25
-    "Build System" : 60
-```
-
-#### 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 |
-
-#### Modified Files (Existing Rippled 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        |
-| `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     |
-| `src/xrpld/overlay/detail/OverlayImpl.cpp`        | ~30         | ~10           | Medium     |
-| `src/xrpld/app/consensus/RCLConsensus.cpp`        | ~50         | ~15           | Medium     |
-| `src/xrpld/app/consensus/RCLConsensusAdaptor.cpp` | ~40         | ~12           | Medium     |
-| `src/xrpld/core/JobQueue.cpp`                     | ~20         | ~5            | Low        |
-| `src/xrpld/overlay/detail/ripple.proto`           | ~25         | 0             | Low        |
-| `CMakeLists.txt`                                  | ~40         | ~8            | Low        |
-| `cmake/FindOpenTelemetry.cmake`                   | ~50         | 0             | None (new) |
-
-### 3.9.3 Risk Assessment by Component
-
-<div align="center">
-
-**Do First** ↖ ↗ **Plan Carefully**
-
-```mermaid
-quadrantChart
-    title Code Intrusiveness Risk Matrix
-    x-axis Low Risk --> High Risk
-    y-axis Low Value --> High Value
-
-    RPC Tracing: [0.2, 0.8]
-    Transaction Relay: [0.5, 0.9]
-    Consensus Tracing: [0.7, 0.95]
-    Peer Message Tracing: [0.8, 0.4]
-    JobQueue Context: [0.4, 0.5]
-    Ledger Acquisition: [0.5, 0.6]
-```
-
-**Optional** ↙ ↘ **Avoid**
-
-</div>
-
-#### Risk Level Definitions
-
-| Risk Level | Definition                                                       | Mitigation                         |
-| ---------- | ---------------------------------------------------------------- | ---------------------------------- |
-| **Low**    | Additive changes only; no modification to existing logic         | Standard code review               |
-| **Medium** | Minor modifications to existing functions; clear boundaries      | Comprehensive unit tests           |
-| **High**   | Changes to core logic or data structures; potential side effects | Integration tests + staged rollout |
-
-### 3.9.4 Architectural Impact Assessment
-
-| Aspect               | Impact  | Justification                                                         |
-| -------------------- | ------- | --------------------------------------------------------------------- |
-| **Data Flow**        | None    | Tracing is purely observational; no business logic changes            |
-| **Threading Model**  | Minimal | Context propagation uses thread-local storage (standard OTel pattern) |
-| **Memory Model**     | Low     | Bounded queues prevent unbounded growth; RAII ensures cleanup         |
-| **Network Protocol** | Low     | Optional fields in protobuf (high field numbers); backward compatible |
-| **Configuration**    | None    | New config section; existing configs unaffected                       |
-| **Build System**     | Low     | Optional CMake flag; builds work without OpenTelemetry                |
-| **Dependencies**     | Low     | OpenTelemetry SDK is optional; null implementation when disabled      |
-
-### 3.9.5 Backward Compatibility
-
-| Compatibility   | Status  | Notes                                                 |
-| --------------- | ------- | ----------------------------------------------------- |
-| **Config File** | ✅ Full | New `[telemetry]` section is optional                 |
-| **Protocol**    | ✅ Full | Optional protobuf fields with high field numbers      |
-| **Build**       | ✅ Full | `XRPL_ENABLE_TELEMETRY=OFF` produces identical binary |
-| **Runtime**     | ✅ Full | `enabled=0` produces zero overhead                    |
-| **API**         | ✅ Full | No changes to public RPC or P2P APIs                  |
-
-### 3.9.6 Rollback Strategy
-
-If issues are discovered after deployment:
-
-1. **Immediate**: Set `enabled=0` in config and restart (zero code change)
-2. **Quick**: Rebuild with `XRPL_ENABLE_TELEMETRY=OFF`
-3. **Complete**: Revert telemetry commits (clean separation makes this easy)
-
-### 3.9.7 Code Change Examples
-
-**Minimal RPC Instrumentation (Low Intrusiveness):**
-
-```cpp
-// Before
-void ServerHandler::onRequest(...) {
-    auto result = processRequest(req);
-    send(result);
-}
-
-// After (only ~10 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 result = processRequest(req);
-
-    XRPL_TRACE_SET_ATTR("xrpl.rpc.status", status);       // +1 line
-    send(result);
-}
-```
-
-**Consensus Instrumentation (Medium Intrusiveness):**
-
-```cpp
-// Before
-void RCLConsensusAdaptor::startRound(...) {
-    // ... existing logic
-}
-
-// After (context storage required)
-void RCLConsensusAdaptor::startRound(...) {
-    XRPL_TRACE_CONSENSUS(app_.getTelemetry(), "consensus.round");
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.ledger.seq", seq);
-
-    // Store context for child spans in phase transitions
-    currentRoundContext_ = _xrpl_guard_->context();  // New member variable
-
-    // ... existing logic unchanged
-}
-```
-
----
-
-_Previous: [Design Decisions](./02-design-decisions.md)_ | _Next: [Code Samples](./04-code-samples.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/04-code-samples.md

@@ -1,982 +0,0 @@
-# Code Samples
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Implementation Strategy](./03-implementation-strategy.md) | [Configuration Reference](./05-configuration-reference.md)
-
----
-
-## 4.1 Core Interfaces
-
-### 4.1.1 Main Telemetry Interface
-
-```cpp
-// include/xrpl/telemetry/Telemetry.h
-#pragma once
-
-#include <xrpl/telemetry/TelemetryConfig.h>
-#include <opentelemetry/trace/tracer.h>
-#include <opentelemetry/trace/span.h>
-#include <opentelemetry/context/context.h>
-
-#include <memory>
-#include <string>
-#include <string_view>
-
-namespace xrpl {
-namespace telemetry {
-
-/**
- * Main telemetry interface for OpenTelemetry integration.
- *
- * This class provides the primary API for distributed tracing in rippled.
- * It manages the OpenTelemetry SDK lifecycle and provides convenience
- * methods for creating spans and propagating context.
- */
-class Telemetry
-{
-public:
-    /**
-     * Configuration for the telemetry system.
-     */
-    struct Setup
-    {
-        bool enabled = false;
-        std::string serviceName = "rippled";
-        std::string serviceVersion;
-        std::string serviceInstanceId;  // Node public key
-
-        // Exporter configuration
-        std::string exporterType = "otlp_grpc";  // "otlp_grpc", "otlp_http", "none"
-        std::string exporterEndpoint = "localhost:4317";
-        bool useTls = false;
-        std::string tlsCertPath;
-
-        // Sampling configuration
-        double samplingRatio = 1.0;  // 1.0 = 100% sampling
-
-        // Batch processor settings
-        std::uint32_t batchSize = 512;
-        std::chrono::milliseconds batchDelay{5000};
-        std::uint32_t maxQueueSize = 2048;
-
-        // Network attributes
-        std::uint32_t networkId = 0;
-        std::string networkType = "mainnet";
-
-        // Component filtering
-        bool traceTransactions = true;
-        bool traceConsensus = true;
-        bool traceRpc = true;
-        bool tracePeer = false;  // High volume, disabled by default
-        bool traceLedger = true;
-    };
-
-    virtual ~Telemetry() = default;
-
-    // ═══════════════════════════════════════════════════════════════════════
-    // LIFECYCLE
-    // ═══════════════════════════════════════════════════════════════════════
-
-    /** Start the telemetry system (call after configuration) */
-    virtual void start() = 0;
-
-    /** Stop the telemetry system (flushes pending spans) */
-    virtual void stop() = 0;
-
-    /** Check if telemetry is enabled */
-    virtual bool isEnabled() const = 0;
-
-    // ═══════════════════════════════════════════════════════════════════════
-    // TRACER ACCESS
-    // ═══════════════════════════════════════════════════════════════════════
-
-    /** Get the tracer for creating spans */
-    virtual opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer>
-    getTracer(std::string_view name = "rippled") = 0;
-
-    // ═══════════════════════════════════════════════════════════════════════
-    // SPAN CREATION (Convenience Methods)
-    // ═══════════════════════════════════════════════════════════════════════
-
-    /** Start a new span with default options */
-    virtual opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span>
-    startSpan(
-        std::string_view name,
-        opentelemetry::trace::SpanKind kind =
-            opentelemetry::trace::SpanKind::kInternal) = 0;
-
-    /** Start a span as child of given context */
-    virtual opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span>
-    startSpan(
-        std::string_view name,
-        opentelemetry::context::Context const& parentContext,
-        opentelemetry::trace::SpanKind kind =
-            opentelemetry::trace::SpanKind::kInternal) = 0;
-
-    // ═══════════════════════════════════════════════════════════════════════
-    // CONTEXT PROPAGATION
-    // ═══════════════════════════════════════════════════════════════════════
-
-    /** Serialize context for network transmission */
-    virtual std::string serializeContext(
-        opentelemetry::context::Context const& ctx) = 0;
-
-    /** Deserialize context from network data */
-    virtual opentelemetry::context::Context deserializeContext(
-        std::string const& serialized) = 0;
-
-    // ═══════════════════════════════════════════════════════════════════════
-    // COMPONENT FILTERING
-    // ═══════════════════════════════════════════════════════════════════════
-
-    /** Check if transaction tracing is enabled */
-    virtual bool shouldTraceTransactions() const = 0;
-
-    /** Check if consensus tracing is enabled */
-    virtual bool shouldTraceConsensus() const = 0;
-
-    /** Check if RPC tracing is enabled */
-    virtual bool shouldTraceRpc() const = 0;
-
-    /** Check if peer message tracing is enabled */
-    virtual bool shouldTracePeer() const = 0;
-};
-
-// Factory functions
-std::unique_ptr<Telemetry>
-make_Telemetry(
-    Telemetry::Setup const& setup,
-    beast::Journal journal);
-
-Telemetry::Setup
-setup_Telemetry(
-    Section const& section,
-    std::string const& nodePublicKey,
-    std::string const& version);
-
-} // namespace telemetry
-} // namespace xrpl
-```
-
----
-
-## 4.2 RAII Span Guard
-
-```cpp
-// include/xrpl/telemetry/SpanGuard.h
-#pragma once
-
-#include <opentelemetry/trace/span.h>
-#include <opentelemetry/trace/scope.h>
-#include <opentelemetry/trace/status.h>
-
-#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.
- */
-class SpanGuard
-{
-    opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span> span_;
-    opentelemetry::trace::Scope scope_;
-
-public:
-    /**
-     * Construct guard with span.
-     * The span becomes the current span in thread-local context.
-     */
-    explicit SpanGuard(
-        opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span> span)
-        : span_(std::move(span))
-        , scope_(span_)
-    {
-    }
-
-    // Non-copyable, non-movable
-    SpanGuard(SpanGuard const&) = delete;
-    SpanGuard& operator=(SpanGuard const&) = delete;
-    SpanGuard(SpanGuard&&) = delete;
-    SpanGuard& operator=(SpanGuard&&) = delete;
-
-    ~SpanGuard()
-    {
-        if (span_)
-            span_->End();
-    }
-
-    /** Access the underlying span */
-    opentelemetry::trace::Span& span() { return *span_; }
-    opentelemetry::trace::Span const& span() const { return *span_; }
-
-    /** 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 */
-    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));
-    }
-
-    /** Add an event to the span */
-    void addEvent(std::string_view name)
-    {
-        span_->AddEvent(std::string(name));
-    }
-
-    /** Record an exception on the span */
-    void recordException(std::exception const& e)
-    {
-        span_->RecordException(e);
-        span_->SetStatus(
-            opentelemetry::trace::StatusCode::kError,
-            e.what());
-    }
-
-    /** Get the current trace context */
-    opentelemetry::context::Context context() const
-    {
-        return opentelemetry::context::RuntimeContext::GetCurrent();
-    }
-};
-
-/**
- * No-op span guard for when tracing is disabled.
- * Provides the same interface but does nothing.
- */
-class NullSpanGuard
-{
-public:
-    NullSpanGuard() = default;
-
-    void setOk() {}
-    void setStatus(opentelemetry::trace::StatusCode, std::string_view = "") {}
-
-    template<typename T>
-    void setAttribute(std::string_view, T&&) {}
-
-    void addEvent(std::string_view) {}
-    void recordException(std::exception const&) {}
-};
-
-} // namespace telemetry
-} // namespace xrpl
-```
-
----
-
-## 4.3 Instrumentation Macros
-
-```cpp
-// src/xrpld/telemetry/TracingInstrumentation.h
-#pragma once
-
-#include <xrpl/telemetry/Telemetry.h>
-#include <xrpl/telemetry/SpanGuard.h>
-
-namespace xrpl {
-namespace telemetry {
-
-// ═══════════════════════════════════════════════════════════════════════════
-// INSTRUMENTATION MACROS
-// ═══════════════════════════════════════════════════════════════════════════
-
-#ifdef XRPL_ENABLE_TELEMETRY
-
-// 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_)
-
-// 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_)
-
-// 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)); \
-    }
-
-#define XRPL_TRACE_CONSENSUS(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceConsensus()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
-
-#define XRPL_TRACE_RPC(telemetry, name) \
-    std::optional<::xrpl::telemetry::SpanGuard> _xrpl_guard_; \
-    if ((telemetry).shouldTraceRpc()) { \
-        _xrpl_guard_.emplace((telemetry).startSpan(name)); \
-    }
-
-// Set attribute on current span (if exists)
-#define XRPL_TRACE_SET_ATTR(key, value) \
-    if (_xrpl_guard_.has_value()) { \
-        _xrpl_guard_->setAttribute(key, value); \
-    }
-
-// Record exception on current span
-#define XRPL_TRACE_EXCEPTION(e) \
-    if (_xrpl_guard_.has_value()) { \
-        _xrpl_guard_->recordException(e); \
-    }
-
-#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_SET_ATTR(key, value) ((void)0)
-#define XRPL_TRACE_EXCEPTION(e) ((void)0)
-
-#endif  // XRPL_ENABLE_TELEMETRY
-
-} // namespace telemetry
-} // namespace xrpl
-```
-
----
-
-## 4.4 Protocol Buffer Extensions
-
-### 4.4.1 TraceContext Message Definition
-
-Add to `src/xrpld/overlay/detail/ripple.proto`:
-
-```protobuf
-// Trace context for distributed tracing across nodes
-// Uses W3C Trace Context format internally
-message TraceContext {
-    // 16-byte trace identifier (required for valid context)
-    bytes trace_id = 1;
-
-    // 8-byte span identifier of parent span
-    bytes span_id = 2;
-
-    // Trace flags (bit 0 = sampled)
-    uint32 trace_flags = 3;
-
-    // W3C tracestate header value for vendor-specific data
-    string trace_state = 4;
-}
-
-// Extend existing messages with optional trace context
-// High field numbers (1000+) to avoid conflicts
-
-message TMTransaction {
-    // ... existing fields ...
-
-    // Optional trace context for distributed tracing
-    optional TraceContext trace_context = 1001;
-}
-
-message TMProposeSet {
-    // ... existing fields ...
-    optional TraceContext trace_context = 1001;
-}
-
-message TMValidation {
-    // ... existing fields ...
-    optional TraceContext trace_context = 1001;
-}
-
-message TMGetLedger {
-    // ... existing fields ...
-    optional TraceContext trace_context = 1001;
-}
-
-message TMLedgerData {
-    // ... existing fields ...
-    optional TraceContext trace_context = 1001;
-}
-```
-
-### 4.4.2 Context Serialization/Deserialization
-
-```cpp
-// include/xrpl/telemetry/TraceContext.h
-#pragma once
-
-#include <opentelemetry/context/context.h>
-#include <opentelemetry/trace/span_context.h>
-#include <protocol/messages.h>  // Generated protobuf
-
-#include <optional>
-#include <string>
-
-namespace xrpl {
-namespace telemetry {
-
-/**
- * Utilities for trace context serialization and propagation.
- */
-class TraceContextPropagator
-{
-public:
-    /**
-     * Extract trace context from Protocol Buffer message.
-     * Returns empty context if no trace info present.
-     */
-    static opentelemetry::context::Context
-    extract(protocol::TraceContext const& proto);
-
-    /**
-     * Inject current trace context into Protocol Buffer message.
-     */
-    static void
-    inject(
-        opentelemetry::context::Context const& ctx,
-        protocol::TraceContext& proto);
-
-    /**
-     * Extract trace context from HTTP headers (for RPC).
-     * Supports W3C Trace Context (traceparent, tracestate).
-     */
-    static opentelemetry::context::Context
-    extractFromHeaders(
-        std::function<std::optional<std::string>(std::string_view)> headerGetter);
-
-    /**
-     * Inject trace context into HTTP headers (for RPC responses).
-     */
-    static void
-    injectToHeaders(
-        opentelemetry::context::Context const& ctx,
-        std::function<void(std::string_view, std::string_view)> headerSetter);
-};
-
-// ═══════════════════════════════════════════════════════════════════════════
-// IMPLEMENTATION
-// ═══════════════════════════════════════════════════════════════════════════
-
-inline opentelemetry::context::Context
-TraceContextPropagator::extract(protocol::TraceContext const& proto)
-{
-    using namespace opentelemetry::trace;
-
-    if (proto.trace_id().size() != 16 || proto.span_id().size() != 8)
-        return opentelemetry::context::Context{};  // Invalid, return empty
-
-    // Construct TraceId and SpanId from bytes
-    TraceId traceId(reinterpret_cast<uint8_t const*>(proto.trace_id().data()));
-    SpanId spanId(reinterpret_cast<uint8_t const*>(proto.span_id().data()));
-    TraceFlags flags(static_cast<uint8_t>(proto.trace_flags()));
-
-    // Create SpanContext from extracted data
-    SpanContext spanContext(traceId, spanId, flags, /* remote = */ true);
-
-    // Create context with extracted span as parent
-    return opentelemetry::context::Context{}.SetValue(
-        opentelemetry::trace::kSpanKey,
-        opentelemetry::nostd::shared_ptr<Span>(
-            new DefaultSpan(spanContext)));
-}
-
-inline void
-TraceContextPropagator::inject(
-    opentelemetry::context::Context const& ctx,
-    protocol::TraceContext& proto)
-{
-    using namespace opentelemetry::trace;
-
-    // Get current span from context
-    auto span = GetSpan(ctx);
-    if (!span)
-        return;
-
-    auto const& spanCtx = span->GetContext();
-    if (!spanCtx.IsValid())
-        return;
-
-    // Serialize trace_id (16 bytes)
-    auto const& traceId = spanCtx.trace_id();
-    proto.set_trace_id(traceId.Id().data(), TraceId::kSize);
-
-    // Serialize span_id (8 bytes)
-    auto const& spanId = spanCtx.span_id();
-    proto.set_span_id(spanId.Id().data(), SpanId::kSize);
-
-    // Serialize flags
-    proto.set_trace_flags(spanCtx.trace_flags().flags());
-
-    // Note: tracestate not implemented yet
-}
-
-} // namespace telemetry
-} // namespace xrpl
-```
-
----
-
-## 4.5 Module-Specific Instrumentation
-
-### 4.5.1 Transaction Relay Instrumentation
-
-```cpp
-// src/xrpld/overlay/detail/PeerImp.cpp (modified)
-
-#include <xrpl/telemetry/TracingInstrumentation.h>
-
-void
-PeerImp::handleTransaction(
-    std::shared_ptr<protocol::TMTransaction> const& m)
-{
-    // Extract trace context from incoming message
-    opentelemetry::context::Context parentCtx;
-    if (m->has_trace_context())
-    {
-        parentCtx = telemetry::TraceContextPropagator::extract(
-            m->trace_context());
-    }
-
-    // Start span as child of remote span (cross-node link)
-    auto span = app_.getTelemetry().startSpan(
-        "tx.receive",
-        parentCtx,
-        opentelemetry::trace::SpanKind::kServer);
-    telemetry::SpanGuard guard(span);
-
-    try
-    {
-        // Parse and validate transaction
-        SerialIter sit(makeSlice(m->rawtransaction()));
-        auto stx = std::make_shared<STTx const>(sit);
-
-        // Add transaction attributes
-        guard.setAttribute("xrpl.tx.hash", to_string(stx->getTransactionID()));
-        guard.setAttribute("xrpl.tx.type", stx->getTxnType());
-        guard.setAttribute("xrpl.peer.id", remote_address_.to_string());
-
-        // Check if we've seen this transaction (HashRouter)
-        auto const [flags, suppressed] =
-            app_.getHashRouter().addSuppressionPeer(
-                stx->getTransactionID(),
-                id_);
-
-        if (suppressed)
-        {
-            guard.setAttribute("xrpl.tx.suppressed", true);
-            guard.addEvent("tx.duplicate");
-            return;  // Already processing this transaction
-        }
-
-        // Create child span for validation
-        {
-            auto validateSpan = app_.getTelemetry().startSpan("tx.validate");
-            telemetry::SpanGuard validateGuard(validateSpan);
-
-            auto [validity, reason] = checkTransaction(stx);
-            validateGuard.setAttribute("xrpl.tx.validity",
-                validity == Validity::Valid ? "valid" : "invalid");
-
-            if (validity != Validity::Valid)
-            {
-                validateGuard.setStatus(
-                    opentelemetry::trace::StatusCode::kError,
-                    reason);
-                return;
-            }
-        }
-
-        // Relay to other peers (capture context for propagation)
-        auto ctx = guard.context();
-
-        // Create child span for relay
-        auto relaySpan = app_.getTelemetry().startSpan(
-            "tx.relay",
-            ctx,
-            opentelemetry::trace::SpanKind::kClient);
-        {
-            telemetry::SpanGuard relayGuard(relaySpan);
-
-            // Inject context into outgoing message
-            protocol::TraceContext protoCtx;
-            telemetry::TraceContextPropagator::inject(
-                relayGuard.context(), protoCtx);
-
-            // Relay to other peers
-            app_.overlay().relay(
-                stx->getTransactionID(),
-                *m,
-                protoCtx,  // Pass trace context
-                exclusions);
-
-            relayGuard.setAttribute("xrpl.tx.relay_count",
-                static_cast<int64_t>(relayCount));
-        }
-
-        guard.setOk();
-    }
-    catch (std::exception const& e)
-    {
-        guard.recordException(e);
-        JLOG(journal_.warn()) << "Transaction handling failed: " << e.what();
-    }
-}
-```
-
-### 4.5.2 Consensus Instrumentation
-
-```cpp
-// src/xrpld/app/consensus/RCLConsensus.cpp (modified)
-
-#include <xrpl/telemetry/TracingInstrumentation.h>
-
-void
-RCLConsensusAdaptor::startRound(
-    NetClock::time_point const& now,
-    RCLCxLedger::ID const& prevLedgerHash,
-    RCLCxLedger const& prevLedger,
-    hash_set<NodeID> const& peers,
-    bool proposing)
-{
-    XRPL_TRACE_CONSENSUS(app_.getTelemetry(), "consensus.round");
-
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.ledger.prev", to_string(prevLedgerHash));
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.ledger.seq",
-        static_cast<int64_t>(prevLedger.seq() + 1));
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.proposers",
-        static_cast<int64_t>(peers.size()));
-    XRPL_TRACE_SET_ATTR("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{};
-
-    // ... existing implementation ...
-}
-
-ConsensusPhase
-RCLConsensusAdaptor::phaseTransition(ConsensusPhase newPhase)
-{
-    // Create span for phase transition
-    auto span = app_.getTelemetry().startSpan(
-        "consensus.phase." + to_string(newPhase),
-        currentRoundContext_);
-    telemetry::SpanGuard guard(span);
-
-    guard.setAttribute("xrpl.consensus.phase", to_string(newPhase));
-    guard.addEvent("phase.enter");
-
-    auto const startTime = std::chrono::steady_clock::now();
-
-    try
-    {
-        auto result = doPhaseTransition(newPhase);
-
-        auto const duration = std::chrono::steady_clock::now() - startTime;
-        guard.setAttribute("xrpl.consensus.phase_duration_ms",
-            std::chrono::duration<double, std::milli>(duration).count());
-
-        guard.setOk();
-        return result;
-    }
-    catch (std::exception const& e)
-    {
-        guard.recordException(e);
-        throw;
-    }
-}
-
-void
-RCLConsensusAdaptor::peerProposal(
-    NetClock::time_point const& now,
-    RCLCxPeerPos const& proposal)
-{
-    // Extract trace context from proposal message
-    opentelemetry::context::Context parentCtx;
-    if (proposal.hasTraceContext())
-    {
-        parentCtx = telemetry::TraceContextPropagator::extract(
-            proposal.traceContext());
-    }
-
-    auto span = app_.getTelemetry().startSpan(
-        "consensus.proposal.receive",
-        parentCtx,
-        opentelemetry::trace::SpanKind::kServer);
-    telemetry::SpanGuard guard(span);
-
-    guard.setAttribute("xrpl.consensus.proposer",
-        toBase58(TokenType::NodePublic, proposal.nodeId()));
-    guard.setAttribute("xrpl.consensus.round",
-        static_cast<int64_t>(proposal.proposal().proposeSeq()));
-
-    // ... existing implementation ...
-
-    guard.setOk();
-}
-```
-
-### 4.5.3 RPC Handler Instrumentation
-
-```cpp
-// src/xrpld/rpc/detail/ServerHandler.cpp (modified)
-
-#include <xrpl/telemetry/TracingInstrumentation.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> {
-            auto it = req.find(boost::beast::http::field{
-                std::string(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);
-
-    // 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",
-        std::string(req[boost::beast::http::field::user_agent]));
-
-    auto const startTime = std::chrono::steady_clock::now();
-
-    try
-    {
-        // Parse and process request
-        auto const& body = req.body();
-        Json::Value jv;
-        Json::Reader reader;
-
-        if (!reader.parse(body, jv))
-        {
-            guard.setStatus(
-                opentelemetry::trace::StatusCode::kError,
-                "Invalid JSON");
-            sendError(send, "Invalid JSON");
-            return;
-        }
-
-        // Extract command name
-        std::string command = jv.isMember("command")
-            ? jv["command"].asString()
-            : jv.isMember("method")
-                ? jv["method"].asString()
-                : "unknown";
-
-        guard.setAttribute("xrpl.rpc.command", command);
-
-        // Create child span for command execution
-        auto cmdSpan = app_.getTelemetry().startSpan(
-            "rpc.command." + command);
-        {
-            telemetry::SpanGuard cmdGuard(cmdSpan);
-
-            // Execute RPC command
-            auto result = processRequest(jv);
-
-            // Record result attributes
-            if (result.isMember("status"))
-            {
-                cmdGuard.setAttribute("xrpl.rpc.status",
-                    result["status"].asString());
-            }
-
-            if (result["status"].asString() == "error")
-            {
-                cmdGuard.setStatus(
-                    opentelemetry::trace::StatusCode::kError,
-                    result.isMember("error_message")
-                        ? result["error_message"].asString()
-                        : "RPC error");
-            }
-            else
-            {
-                cmdGuard.setOk();
-            }
-        }
-
-        auto const duration = std::chrono::steady_clock::now() - startTime;
-        guard.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(),
-            [&resp](std::string_view name, std::string_view value) {
-                resp.set(std::string(name), std::string(value));
-            });
-
-        guard.setOk();
-        send(std::move(resp));
-    }
-    catch (std::exception const& e)
-    {
-        guard.recordException(e);
-        JLOG(journal_.error()) << "RPC request failed: " << e.what();
-        sendError(send, e.what());
-    }
-}
-```
-
-### 4.5.4 JobQueue Context Propagation
-
-```cpp
-// src/xrpld/core/JobQueue.h (modified)
-
-#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)
-
-void
-Worker::run()
-{
-    while (auto job = getJob())
-    {
-        // 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();
-        }
-    }
-}
-```
-
----
-
-## 4.6 Span Flow Visualization
-
-<div align="center">
-
-```mermaid
-flowchart TB
-    subgraph Client["External Client"]
-        submit["Submit TX"]
-    end
-
-    subgraph NodeA["rippled Node A"]
-        rpcA["rpc.request"]
-        cmdA["rpc.command.submit"]
-        txRecvA["tx.receive"]
-        txValA["tx.validate"]
-        txRelayA["tx.relay"]
-    end
-
-    subgraph NodeB["rippled Node B"]
-        txRecvB["tx.receive"]
-        txValB["tx.validate"]
-        txRelayB["tx.relay"]
-    end
-
-    subgraph NodeC["rippled Node C"]
-        txRecvC["tx.receive"]
-        consensusC["consensus.round"]
-        phaseC["consensus.phase.establish"]
-    end
-
-    submit --> rpcA
-    rpcA --> cmdA
-    cmdA --> txRecvA
-    txRecvA --> txValA
-    txValA --> txRelayA
-    txRelayA -.->|"TraceContext"| txRecvB
-    txRecvB --> txValB
-    txValB --> txRelayB
-    txRelayB -.->|"TraceContext"| txRecvC
-    txRecvC --> consensusC
-    consensusC --> phaseC
-
-    style Client fill:#334155,stroke:#1e293b,color:#fff
-    style NodeA fill:#1e3a8a,stroke:#172554,color:#fff
-    style NodeB fill:#064e3b,stroke:#022c22,color:#fff
-    style NodeC fill:#78350f,stroke:#451a03,color:#fff
-    style submit fill:#e2e8f0,stroke:#cbd5e1,color:#1e293b
-    style rpcA fill:#1d4ed8,stroke:#1e40af,color:#fff
-    style cmdA fill:#1d4ed8,stroke:#1e40af,color:#fff
-    style txRecvA fill:#047857,stroke:#064e3b,color:#fff
-    style txValA fill:#047857,stroke:#064e3b,color:#fff
-    style txRelayA fill:#047857,stroke:#064e3b,color:#fff
-    style txRecvB fill:#047857,stroke:#064e3b,color:#fff
-    style txValB fill:#047857,stroke:#064e3b,color:#fff
-    style txRelayB fill:#047857,stroke:#064e3b,color:#fff
-    style txRecvC fill:#047857,stroke:#064e3b,color:#fff
-    style consensusC fill:#fef3c7,stroke:#fde68a,color:#1e293b
-    style phaseC fill:#fef3c7,stroke:#fde68a,color:#1e293b
-```
-
-</div>
-
----
-
-_Previous: [Implementation Strategy](./03-implementation-strategy.md)_ | _Next: [Configuration Reference](./05-configuration-reference.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/05-configuration-reference.md

@@ -1,958 +0,0 @@
-# Configuration Reference
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Code Samples](./04-code-samples.md) | [Implementation Phases](./06-implementation-phases.md)
-
----
-
-## 5.1 rippled Configuration
-
-### 5.1.1 Configuration File Section
-
-Add to `cfg/xrpld-example.cfg`:
-
-```ini
-# ═══════════════════════════════════════════════════════════════════════════════
-# TELEMETRY (OpenTelemetry Distributed Tracing)
-# ═══════════════════════════════════════════════════════════════════════════════
-#
-# Enables distributed tracing for transaction flow, consensus, and RPC calls.
-# Traces are exported to an OpenTelemetry Collector using OTLP protocol.
-#
-# [telemetry]
-#
-# # Enable/disable telemetry (default: 0 = disabled)
-# enabled=1
-#
-# # Exporter type: "otlp_grpc" (default), "otlp_http", or "none"
-# exporter=otlp_grpc
-#
-# # OTLP endpoint (default: localhost:4317 for gRPC, localhost:4318 for HTTP)
-# endpoint=localhost:4317
-#
-# # Use TLS for exporter connection (default: 0)
-# use_tls=0
-#
-# # Path to CA certificate for TLS (optional)
-# # tls_ca_cert=/path/to/ca.crt
-#
-# # Sampling ratio: 0.0-1.0 (default: 1.0 = 100% sampling)
-# # Use lower values in production to reduce overhead
-# sampling_ratio=0.1
-#
-# # Batch processor settings
-# batch_size=512           # Spans per batch (default: 512)
-# batch_delay_ms=5000      # Max delay before sending batch (default: 5000)
-# max_queue_size=2048      # Max queued spans (default: 2048)
-#
-# # Component-specific tracing (default: all enabled except peer)
-# trace_transactions=1     # Transaction relay and processing
-# trace_consensus=1        # Consensus rounds and proposals
-# trace_rpc=1              # RPC request handling
-# trace_peer=0             # Peer messages (high volume, disabled by default)
-# trace_ledger=1           # Ledger acquisition and building
-#
-# # Service identification (automatically detected if not specified)
-# # service_name=rippled
-# # service_instance_id=<node_public_key>
-
-[telemetry]
-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                     |
-| `service_name`        | string | `"rippled"`      | Service name for traces                   |
-| `service_instance_id` | string | `<node_pubkey>`  | Instance identifier                       |
-
----
-
-## 5.2 Configuration Parser
-
-```cpp
-// src/libxrpl/telemetry/TelemetryConfig.cpp
-
-#include <xrpl/telemetry/Telemetry.h>
-#include <xrpl/basics/Log.h>
-
-namespace xrpl {
-namespace telemetry {
-
-Telemetry::Setup
-setup_Telemetry(
-    Section const& section,
-    std::string const& nodePublicKey,
-    std::string const& version)
-{
-    Telemetry::Setup setup;
-
-    // Basic settings
-    setup.enabled = section.value_or("enabled", false);
-    setup.serviceName = section.value_or("service_name", "rippled");
-    setup.serviceVersion = version;
-    setup.serviceInstanceId = section.value_or(
-        "service_instance_id", nodePublicKey);
-
-    // Exporter settings
-    setup.exporterType = section.value_or("exporter", "otlp_grpc");
-
-    if (setup.exporterType == "otlp_grpc")
-        setup.exporterEndpoint = section.value_or("endpoint", "localhost:4317");
-    else if (setup.exporterType == "otlp_http")
-        setup.exporterEndpoint = section.value_or("endpoint", "localhost:4318");
-
-    setup.useTls = section.value_or("use_tls", false);
-    setup.tlsCertPath = section.value_or("tls_ca_cert", "");
-
-    // Sampling
-    setup.samplingRatio = section.value_or("sampling_ratio", 1.0);
-    if (setup.samplingRatio < 0.0 || setup.samplingRatio > 1.0)
-    {
-        Throw<std::runtime_error>(
-            "telemetry.sampling_ratio must be between 0.0 and 1.0");
-    }
-
-    // Batch processor
-    setup.batchSize = section.value_or("batch_size", 512u);
-    setup.batchDelay = std::chrono::milliseconds{
-        section.value_or("batch_delay_ms", 5000u)};
-    setup.maxQueueSize = section.value_or("max_queue_size", 2048u);
-
-    // Component filtering
-    setup.traceTransactions = section.value_or("trace_transactions", true);
-    setup.traceConsensus = section.value_or("trace_consensus", true);
-    setup.traceRpc = section.value_or("trace_rpc", true);
-    setup.tracePeer = section.value_or("trace_peer", false);
-    setup.traceLedger = section.value_or("trace_ledger", true);
-
-    return setup;
-}
-
-} // namespace telemetry
-} // namespace xrpl
-```
-
----
-
-## 5.3 Application Integration
-
-### 5.3.1 ApplicationImp Changes
-
-```cpp
-// src/xrpld/app/main/Application.cpp (modified)
-
-#include <xrpl/telemetry/Telemetry.h>
-
-class ApplicationImp : public Application
-{
-    // ... existing members ...
-
-    // Telemetry (must be constructed early, destroyed late)
-    std::unique_ptr<telemetry::Telemetry> telemetry_;
-
-public:
-    ApplicationImp(...)
-    {
-        // Initialize telemetry early (before other components)
-        auto telemetrySection = config_->section("telemetry");
-        auto telemetrySetup = telemetry::setup_Telemetry(
-            telemetrySection,
-            toBase58(TokenType::NodePublic, nodeIdentity_.publicKey()),
-            BuildInfo::getVersionString());
-
-        // 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";
-        }();
-
-        telemetry_ = telemetry::make_Telemetry(
-            telemetrySetup,
-            logs_->journal("Telemetry"));
-
-        // ... rest of initialization ...
-    }
-
-    void start() override
-    {
-        // Start telemetry first
-        if (telemetry_)
-            telemetry_->start();
-
-        // ... existing start code ...
-    }
-
-    void stop() override
-    {
-        // ... existing stop code ...
-
-        // Stop telemetry last (to capture shutdown spans)
-        if (telemetry_)
-            telemetry_->stop();
-    }
-
-    telemetry::Telemetry& getTelemetry() override
-    {
-        assert(telemetry_);
-        return *telemetry_;
-    }
-};
-```
-
-### 5.3.2 Application Interface Addition
-
-```cpp
-// include/xrpl/app/main/Application.h (modified)
-
-namespace telemetry { class Telemetry; }
-
-class Application
-{
-public:
-    // ... existing virtual methods ...
-
-    /** Get the telemetry system for distributed tracing */
-    virtual telemetry::Telemetry& getTelemetry() = 0;
-};
-```
-
----
-
-## 5.4 CMake Integration
-
-### 5.4.1 Find OpenTelemetry Module
-
-```cmake
-# cmake/FindOpenTelemetry.cmake
-
-# Find OpenTelemetry C++ SDK
-#
-# This module defines:
-#   OpenTelemetry_FOUND - System has OpenTelemetry
-#   OpenTelemetry::api - API library target
-#   OpenTelemetry::sdk - SDK library target
-#   OpenTelemetry::otlp_grpc_exporter - OTLP gRPC exporter target
-#   OpenTelemetry::otlp_http_exporter - OTLP HTTP exporter target
-
-find_package(opentelemetry-cpp CONFIG QUIET)
-
-if(opentelemetry-cpp_FOUND)
-    set(OpenTelemetry_FOUND TRUE)
-
-    # Create imported targets if not already created by config
-    if(NOT TARGET OpenTelemetry::api)
-        add_library(OpenTelemetry::api ALIAS opentelemetry-cpp::api)
-    endif()
-    if(NOT TARGET OpenTelemetry::sdk)
-        add_library(OpenTelemetry::sdk ALIAS opentelemetry-cpp::sdk)
-    endif()
-    if(NOT TARGET OpenTelemetry::otlp_grpc_exporter)
-        add_library(OpenTelemetry::otlp_grpc_exporter ALIAS
-            opentelemetry-cpp::otlp_grpc_exporter)
-    endif()
-else()
-    # Try pkg-config fallback
-    find_package(PkgConfig QUIET)
-    if(PKG_CONFIG_FOUND)
-        pkg_check_modules(OTEL opentelemetry-cpp QUIET)
-        if(OTEL_FOUND)
-            set(OpenTelemetry_FOUND TRUE)
-            # Create imported targets from pkg-config
-            add_library(OpenTelemetry::api INTERFACE IMPORTED)
-            target_include_directories(OpenTelemetry::api INTERFACE
-                ${OTEL_INCLUDE_DIRS})
-        endif()
-    endif()
-endif()
-
-include(FindPackageHandleStandardArgs)
-find_package_handle_standard_args(OpenTelemetry
-    REQUIRED_VARS OpenTelemetry_FOUND)
-```
-
-### 5.4.2 CMakeLists.txt Changes
-
-```cmake
-# CMakeLists.txt (additions)
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# TELEMETRY OPTIONS
-# ═══════════════════════════════════════════════════════════════════════════════
-
-option(XRPL_ENABLE_TELEMETRY
-    "Enable OpenTelemetry distributed tracing support" OFF)
-
-if(XRPL_ENABLE_TELEMETRY)
-    find_package(OpenTelemetry REQUIRED)
-
-    # Define compile-time flag
-    add_compile_definitions(XRPL_ENABLE_TELEMETRY)
-
-    message(STATUS "OpenTelemetry tracing: ENABLED")
-else()
-    message(STATUS "OpenTelemetry tracing: DISABLED")
-endif()
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# TELEMETRY LIBRARY
-# ═══════════════════════════════════════════════════════════════════════════════
-
-if(XRPL_ENABLE_TELEMETRY)
-    add_library(xrpl_telemetry
-        src/libxrpl/telemetry/Telemetry.cpp
-        src/libxrpl/telemetry/TelemetryConfig.cpp
-        src/libxrpl/telemetry/TraceContext.cpp
-    )
-
-    target_include_directories(xrpl_telemetry
-        PUBLIC
-            ${CMAKE_CURRENT_SOURCE_DIR}/include
-    )
-
-    target_link_libraries(xrpl_telemetry
-        PUBLIC
-            OpenTelemetry::api
-            OpenTelemetry::sdk
-            OpenTelemetry::otlp_grpc_exporter
-        PRIVATE
-            xrpl_basics
-    )
-
-    # Add to main library dependencies
-    target_link_libraries(xrpld PRIVATE xrpl_telemetry)
-else()
-    # Create null implementation library
-    add_library(xrpl_telemetry
-        src/libxrpl/telemetry/NullTelemetry.cpp
-    )
-    target_include_directories(xrpl_telemetry
-        PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include
-    )
-endif()
-```
-
----
-
-## 5.5 OpenTelemetry Collector Configuration
-
-### 5.5.1 Development Configuration
-
-```yaml
-# otel-collector-dev.yaml
-# Minimal configuration for local development
-
-receivers:
-  otlp:
-    protocols:
-      grpc:
-        endpoint: 0.0.0.0:4317
-      http:
-        endpoint: 0.0.0.0:4318
-
-processors:
-  batch:
-    timeout: 1s
-    send_batch_size: 100
-
-exporters:
-  # Console output for debugging
-  logging:
-    verbosity: detailed
-    sampling_initial: 5
-    sampling_thereafter: 200
-
-  # Jaeger for trace visualization
-  jaeger:
-    endpoint: jaeger:14250
-    tls:
-      insecure: true
-
-  # Grafana Tempo for trace storage
-  otlp/tempo:
-    endpoint: tempo:4317
-    tls:
-      insecure: true
-
-service:
-  pipelines:
-    traces:
-      receivers: [otlp]
-      processors: [batch]
-      exporters: [logging, jaeger, otlp/tempo]
-```
-
-### 5.5.2 Production Configuration
-
-```yaml
-# otel-collector-prod.yaml
-# Production configuration with filtering, sampling, and multiple backends
-
-receivers:
-  otlp:
-    protocols:
-      grpc:
-        endpoint: 0.0.0.0:4317
-        tls:
-          cert_file: /etc/otel/server.crt
-          key_file: /etc/otel/server.key
-          ca_file: /etc/otel/ca.crt
-
-processors:
-  # Memory limiter to prevent OOM
-  memory_limiter:
-    check_interval: 1s
-    limit_mib: 1000
-    spike_limit_mib: 200
-
-  # Batch processing for efficiency
-  batch:
-    timeout: 5s
-    send_batch_size: 512
-    send_batch_max_size: 1024
-
-  # Tail-based sampling (keep errors and slow traces)
-  tail_sampling:
-    decision_wait: 10s
-    num_traces: 100000
-    expected_new_traces_per_sec: 1000
-    policies:
-      # Always keep error traces
-      - name: errors
-        type: status_code
-        status_code:
-          status_codes: [ERROR]
-      # Keep slow consensus rounds (>5s)
-      - name: slow-consensus
-        type: latency
-        latency:
-          threshold_ms: 5000
-      # Keep slow RPC requests (>1s)
-      - name: slow-rpc
-        type: and
-        and:
-          and_sub_policy:
-            - name: rpc-spans
-              type: string_attribute
-              string_attribute:
-                key: xrpl.rpc.command
-                values: [".*"]
-                enabled_regex_matching: true
-            - name: latency
-              type: latency
-              latency:
-                threshold_ms: 1000
-      # Probabilistic sampling for the rest
-      - name: probabilistic
-        type: probabilistic
-        probabilistic:
-          sampling_percentage: 10
-
-  # Attribute processing
-  attributes:
-    actions:
-      # Hash sensitive data
-      - key: xrpl.tx.account
-        action: hash
-      # Add deployment info
-      - key: deployment.environment
-        value: production
-        action: upsert
-
-exporters:
-  # Grafana Tempo for long-term storage
-  otlp/tempo:
-    endpoint: tempo.monitoring:4317
-    tls:
-      insecure: false
-      ca_file: /etc/otel/tempo-ca.crt
-
-  # Elastic APM for correlation with logs
-  otlp/elastic:
-    endpoint: apm.elastic:8200
-    headers:
-      Authorization: "Bearer ${ELASTIC_APM_TOKEN}"
-
-extensions:
-  health_check:
-    endpoint: 0.0.0.0:13133
-  zpages:
-    endpoint: 0.0.0.0:55679
-
-service:
-  extensions: [health_check, zpages]
-  pipelines:
-    traces:
-      receivers: [otlp]
-      processors: [memory_limiter, tail_sampling, attributes, batch]
-      exporters: [otlp/tempo, otlp/elastic]
-```
-
----
-
-## 5.6 Docker Compose Development Environment
-
-```yaml
-# docker-compose-telemetry.yaml
-version: "3.8"
-
-services:
-  # OpenTelemetry Collector
-  otel-collector:
-    image: otel/opentelemetry-collector-contrib:0.92.0
-    container_name: otel-collector
-    command: ["--config=/etc/otel-collector-config.yaml"]
-    volumes:
-      - ./otel-collector-dev.yaml:/etc/otel-collector-config.yaml:ro
-    ports:
-      - "4317:4317" # OTLP gRPC
-      - "4318:4318" # OTLP HTTP
-      - "13133:13133" # Health check
-    depends_on:
-      - jaeger
-
-  # Jaeger for trace visualization
-  jaeger:
-    image: jaegertracing/all-in-one:1.53
-    container_name: jaeger
-    environment:
-      - COLLECTOR_OTLP_ENABLED=true
-    ports:
-      - "16686:16686" # UI
-      - "14250:14250" # gRPC
-
-  # 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
-    container_name: grafana
-    environment:
-      - GF_AUTH_ANONYMOUS_ENABLED=true
-      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
-    volumes:
-      - ./grafana/provisioning:/etc/grafana/provisioning:ro
-      - ./grafana/dashboards:/var/lib/grafana/dashboards:ro
-    ports:
-      - "3000:3000"
-    depends_on:
-      - jaeger
-      - tempo
-
-  # Prometheus for metrics (optional, for correlation)
-  prometheus:
-    image: prom/prometheus:v2.48.1
-    container_name: prometheus
-    volumes:
-      - ./prometheus.yaml:/etc/prometheus/prometheus.yml:ro
-    ports:
-      - "9090:9090"
-
-networks:
-  default:
-    name: rippled-telemetry
-```
-
----
-
-## 5.7 Configuration Architecture
-
-```mermaid
-flowchart TB
-    subgraph config["Configuration Sources"]
-        cfgFile["xrpld.cfg<br/>[telemetry] section"]
-        cmake["CMake<br/>XRPL_ENABLE_TELEMETRY"]
-    end
-
-    subgraph init["Initialization"]
-        parse["setup_Telemetry()"]
-        factory["make_Telemetry()"]
-    end
-
-    subgraph runtime["Runtime Components"]
-        tracer["TracerProvider"]
-        exporter["OTLP Exporter"]
-        processor["BatchProcessor"]
-    end
-
-    subgraph collector["Collector Pipeline"]
-        recv["Receivers"]
-        proc["Processors"]
-        exp["Exporters"]
-    end
-
-    cfgFile --> parse
-    cmake -->|"compile flag"| parse
-    parse --> factory
-    factory --> tracer
-    tracer --> processor
-    processor --> exporter
-    exporter -->|"OTLP"| recv
-    recv --> proc
-    proc --> exp
-
-    style config fill:#e3f2fd,stroke:#1976d2
-    style runtime fill:#e8f5e9,stroke:#388e3c
-    style collector fill:#fff3e0,stroke:#ff9800
-```
-
----
-
-## 5.8 Grafana Integration
-
-Step-by-step instructions for integrating rippled traces with Grafana.
-
-### 5.8.1 Data Source Configuration
-
-#### Tempo (Recommended)
-
-```yaml
-# grafana/provisioning/datasources/tempo.yaml
-apiVersion: 1
-
-datasources:
-  - name: Tempo
-    type: tempo
-    access: proxy
-    url: http://tempo:3200
-    jsonData:
-      httpMethod: GET
-      tracesToLogs:
-        datasourceUid: loki
-        tags: ["service.name", "xrpl.tx.hash"]
-        mappedTags: [{ key: "trace_id", value: "traceID" }]
-        mapTagNamesEnabled: true
-        filterByTraceID: true
-      serviceMap:
-        datasourceUid: prometheus
-      nodeGraph:
-        enabled: true
-      search:
-        hide: false
-      lokiSearch:
-        datasourceUid: loki
-```
-
-#### Jaeger
-
-```yaml
-# grafana/provisioning/datasources/jaeger.yaml
-apiVersion: 1
-
-datasources:
-  - name: Jaeger
-    type: jaeger
-    access: proxy
-    url: http://jaeger:16686
-    jsonData:
-      tracesToLogs:
-        datasourceUid: loki
-        tags: ["service.name"]
-```
-
-#### Elastic APM
-
-```yaml
-# grafana/provisioning/datasources/elastic-apm.yaml
-apiVersion: 1
-
-datasources:
-  - name: Elasticsearch-APM
-    type: elasticsearch
-    access: proxy
-    url: http://elasticsearch:9200
-    database: "apm-*"
-    jsonData:
-      esVersion: "8.0.0"
-      timeField: "@timestamp"
-      logMessageField: message
-      logLevelField: log.level
-```
-
-### 5.8.2 Dashboard Provisioning
-
-```yaml
-# grafana/provisioning/dashboards/dashboards.yaml
-apiVersion: 1
-
-providers:
-  - name: "rippled-dashboards"
-    orgId: 1
-    folder: "rippled"
-    folderUid: "rippled"
-    type: file
-    disableDeletion: false
-    updateIntervalSeconds: 30
-    options:
-      path: /var/lib/grafana/dashboards/rippled
-```
-
-### 5.8.3 Example Dashboard: RPC Performance
-
-```json
-{
-  "title": "rippled RPC Performance",
-  "uid": "rippled-rpc-performance",
-  "panels": [
-    {
-      "title": "RPC Latency by Command",
-      "type": "heatmap",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && span.xrpl.rpc.command != \"\"} | histogram_over_time(duration) by (span.xrpl.rpc.command)"
-        }
-      ],
-      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 }
-    },
-    {
-      "title": "RPC Error Rate",
-      "type": "timeseries",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && status.code=error} | rate() by (span.xrpl.rpc.command)"
-        }
-      ],
-      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 }
-    },
-    {
-      "title": "Top 10 Slowest RPC Commands",
-      "type": "table",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && span.xrpl.rpc.command != \"\"} | avg(duration) by (span.xrpl.rpc.command) | topk(10)"
-        }
-      ],
-      "gridPos": { "h": 8, "w": 24, "x": 0, "y": 8 }
-    },
-    {
-      "title": "Recent Traces",
-      "type": "table",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\"}"
-        }
-      ],
-      "gridPos": { "h": 8, "w": 24, "x": 0, "y": 16 }
-    }
-  ]
-}
-```
-
-### 5.8.4 Example Dashboard: Transaction Tracing
-
-```json
-{
-  "title": "rippled Transaction Tracing",
-  "uid": "rippled-tx-tracing",
-  "panels": [
-    {
-      "title": "Transaction Throughput",
-      "type": "stat",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.receive\"} | rate()"
-        }
-      ],
-      "gridPos": { "h": 4, "w": 6, "x": 0, "y": 0 }
-    },
-    {
-      "title": "Cross-Node Relay Count",
-      "type": "timeseries",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.relay\"} | avg(span.xrpl.tx.relay_count)"
-        }
-      ],
-      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 4 }
-    },
-    {
-      "title": "Transaction Validation Errors",
-      "type": "table",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.validate\" && status.code=error}"
-        }
-      ],
-      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 4 }
-    }
-  ]
-}
-```
-
-### 5.8.5 TraceQL Query Examples
-
-Common queries for rippled traces:
-
-```
-# Find all traces for a specific transaction hash
-{resource.service.name="rippled" && span.xrpl.tx.hash="ABC123..."}
-
-# Find slow RPC commands (>100ms)
-{resource.service.name="rippled" && name=~"rpc.command.*"} | duration > 100ms
-
-# Find consensus rounds taking >5 seconds
-{resource.service.name="rippled" && name="consensus.round"} | duration > 5s
-
-# Find failed transactions with error details
-{resource.service.name="rippled" && 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
-
-# Compare latency across nodes
-{resource.service.name="rippled" && name="rpc.command.account_info"} | avg(duration) by (resource.service.instance.id)
-```
-
-### 5.8.6 Correlation with PerfLog
-
-To correlate OpenTelemetry traces with existing PerfLog data:
-
-**Step 1: Configure Loki to ingest PerfLog**
-
-```yaml
-# promtail-config.yaml
-scrape_configs:
-  - job_name: rippled-perflog
-    static_configs:
-      - targets:
-          - localhost
-        labels:
-          job: rippled
-          __path__: /var/log/rippled/perf*.log
-    pipeline_stages:
-      - json:
-          expressions:
-            trace_id: trace_id
-            ledger_seq: ledger_seq
-            tx_hash: tx_hash
-      - labels:
-          trace_id:
-          ledger_seq:
-          tx_hash:
-```
-
-**Step 2: Add trace_id to PerfLog entries**
-
-Modify PerfLog to include trace_id when available:
-
-```cpp
-// In PerfLog output, add trace_id from current span context
-void logPerf(Json::Value& entry) {
-    auto span = opentelemetry::trace::GetSpan(
-        opentelemetry::context::RuntimeContext::GetCurrent());
-    if (span && span->GetContext().IsValid()) {
-        char traceIdHex[33];
-        span->GetContext().trace_id().ToLowerBase16(traceIdHex);
-        entry["trace_id"] = std::string(traceIdHex, 32);
-    }
-    // ... existing logging
-}
-```
-
-**Step 3: Configure Grafana trace-to-logs link**
-
-In Tempo data source configuration, set up the derived field:
-
-```yaml
-jsonData:
-  tracesToLogs:
-    datasourceUid: loki
-    tags: ["trace_id", "xrpl.tx.hash"]
-    filterByTraceID: true
-    filterBySpanID: false
-```
-
-### 5.8.7 Correlation with Insight/OTel System Metrics
-
-To correlate traces with Beast Insight system 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
-```
-
-**Step 2: Add exemplars to metrics**
-
-OpenTelemetry SDK automatically adds exemplars (trace IDs) to metrics when using the Prometheus exporter. This links metrics spikes to specific traces.
-
-**Step 3: Configure Grafana metric-to-trace link**
-
-```yaml
-# In Prometheus data source
-jsonData:
-  exemplarTraceIdDestinations:
-    - name: trace_id
-      datasourceUid: tempo
-```
-
-**Step 4: Dashboard panel with exemplars**
-
-```json
-{
-  "title": "RPC Latency with Trace Links",
-  "type": "timeseries",
-  "datasource": "Prometheus",
-  "targets": [
-    {
-      "expr": "histogram_quantile(0.99, rate(rippled_rpc_duration_seconds_bucket[5m]))",
-      "exemplar": true
-    }
-  ]
-}
-```
-
-This allows clicking on metric data points to jump directly to the related trace.
-
----
-
-_Previous: [Code Samples](./04-code-samples.md)_ | _Next: [Implementation Phases](./06-implementation-phases.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/07-observability-backends.md

@@ -1,595 +0,0 @@
-# Observability Backend Recommendations
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Implementation Phases](./06-implementation-phases.md) | [Appendix](./08-appendix.md)
-
----
-
-## 7.1 Development/Testing Backends
-
-| Backend    | Pros                | Cons              | Use Case          |
-| ---------- | ------------------- | ----------------- | ----------------- |
-| **Jaeger** | Easy setup, good UI | Limited retention | Local dev, CI     |
-| **Zipkin** | Simple, lightweight | Basic features    | Quick prototyping |
-
-### Quick Start with Jaeger
-
-```bash
-# Start Jaeger with OTLP support
-docker run -d --name jaeger \
-  -e COLLECTOR_OTLP_ENABLED=true \
-  -p 16686:16686 \
-  -p 4317:4317 \
-  -p 4318:4318 \
-  jaegertracing/all-in-one:latest
-```
-
----
-
-## 7.2 Production Backends
-
-| Backend           | Pros                                      | Cons               | Use Case                    |
-| ----------------- | ----------------------------------------- | ------------------ | --------------------------- |
-| **Grafana Tempo** | Cost-effective, Grafana integration       | Newer project      | Most production deployments |
-| **Elastic APM**   | Full observability stack, log correlation | Resource intensive | Existing Elastic users      |
-| **Honeycomb**     | Excellent query, high cardinality         | SaaS cost          | Deep debugging needs        |
-| **Datadog APM**   | Full platform, easy setup                 | SaaS cost          | Enterprise with budget      |
-
-### Backend Selection Flowchart
-
-```mermaid
-flowchart TD
-    start[Select Backend] --> budget{Budget<br/>Constraints?}
-
-    budget -->|Yes| oss[Open Source]
-    budget -->|No| saas{Prefer<br/>SaaS?}
-
-    oss --> existing{Existing<br/>Stack?}
-    existing -->|Grafana| tempo[Grafana Tempo]
-    existing -->|Elastic| elastic[Elastic APM]
-    existing -->|None| tempo
-
-    saas -->|Yes| enterprise{Enterprise<br/>Support?}
-    saas -->|No| oss
-
-    enterprise -->|Yes| datadog[Datadog APM]
-    enterprise -->|No| honeycomb[Honeycomb]
-
-    tempo --> final[Configure Collector]
-    elastic --> final
-    honeycomb --> final
-    datadog --> final
-
-    style start fill:#0f172a,stroke:#020617,color:#fff
-    style budget fill:#334155,stroke:#1e293b,color:#fff
-    style oss fill:#1e293b,stroke:#0f172a,color:#fff
-    style existing fill:#334155,stroke:#1e293b,color:#fff
-    style saas fill:#334155,stroke:#1e293b,color:#fff
-    style enterprise fill:#334155,stroke:#1e293b,color:#fff
-    style final fill:#0f172a,stroke:#020617,color:#fff
-    style tempo fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style elastic fill:#bf360c,stroke:#8c2809,color:#fff
-    style honeycomb fill:#0d47a1,stroke:#082f6a,color:#fff
-    style datadog fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
----
-
-## 7.3 Recommended Production Architecture
-
-```mermaid
-flowchart TB
-    subgraph validators["Validator Nodes"]
-        v1[rippled<br/>Validator 1]
-        v2[rippled<br/>Validator 2]
-    end
-
-    subgraph stock["Stock Nodes"]
-        s1[rippled<br/>Stock 1]
-        s2[rippled<br/>Stock 2]
-    end
-
-    subgraph collector["OTel Collector Cluster"]
-        c1[Collector<br/>DC1]
-        c2[Collector<br/>DC2]
-    end
-
-    subgraph backends["Storage Backends"]
-        tempo[(Grafana<br/>Tempo)]
-        elastic[(Elastic<br/>APM)]
-        archive[(S3/GCS<br/>Archive)]
-    end
-
-    subgraph ui["Visualization"]
-        grafana[Grafana<br/>Dashboards]
-    end
-
-    v1 -->|OTLP| c1
-    v2 -->|OTLP| c1
-    s1 -->|OTLP| c2
-    s2 -->|OTLP| c2
-
-    c1 --> tempo
-    c1 --> elastic
-    c2 --> tempo
-    c2 --> archive
-
-    tempo --> grafana
-    elastic --> grafana
-
-    style validators fill:#b71c1c,stroke:#7f1d1d,color:#ffffff
-    style stock fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style collector fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style backends fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style ui fill:#4a148c,stroke:#2e0d57,color:#ffffff
-```
-
----
-
-## 7.4 Architecture Considerations
-
-### 7.4.1 Collector Placement
-
-| Strategy      | Description          | Pros                     | Cons                    |
-| ------------- | -------------------- | ------------------------ | ----------------------- |
-| **Sidecar**   | Collector per node   | Isolation, simple config | Resource overhead       |
-| **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:
-
-- One collector cluster per datacenter/region
-- Tail-based sampling at collector level
-- Multiple export destinations for redundancy
-
-### 7.4.2 Sampling Strategy
-
-```mermaid
-flowchart LR
-    subgraph head["Head Sampling (Node)"]
-        hs[10% probabilistic]
-    end
-
-    subgraph tail["Tail Sampling (Collector)"]
-        ts1[Keep all errors]
-        ts2[Keep slow >5s]
-        ts3[Keep 10% rest]
-    end
-
-    head --> tail
-
-    ts1 --> final[Final Traces]
-    ts2 --> final
-    ts3 --> final
-
-    style head fill:#0d47a1,stroke:#082f6a,color:#fff
-    style tail fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style hs fill:#0d47a1,stroke:#082f6a,color:#fff
-    style ts1 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style ts2 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style ts3 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style final fill:#bf360c,stroke:#8c2809,color:#fff
-```
-
-### 7.4.3 Data Retention
-
-| Environment | Hot Storage | Warm Storage | Cold Archive |
-| ----------- | ----------- | ------------ | ------------ |
-| Development | 24 hours    | N/A          | N/A          |
-| Staging     | 7 days      | N/A          | N/A          |
-| Production  | 7 days      | 30 days      | many years   |
-
----
-
-## 7.5 Integration Checklist
-
-- [ ] Choose primary backend (Tempo recommended for cost/features)
-- [ ] Deploy collector cluster with high availability
-- [ ] Configure tail-based sampling for error/latency traces
-- [ ] Set up Grafana dashboards for trace visualization
-- [ ] Configure alerts for trace anomalies
-- [ ] Establish data retention policies
-- [ ] Test trace correlation with logs and metrics
-
----
-
-## 7.6 Grafana Dashboard Examples
-
-Pre-built dashboards for rippled observability.
-
-### 7.6.1 Consensus Health Dashboard
-
-```json
-{
-  "title": "rippled Consensus Health",
-  "uid": "rippled-consensus-health",
-  "tags": ["rippled", "consensus", "tracing"],
-  "panels": [
-    {
-      "title": "Consensus Round Duration",
-      "type": "timeseries",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"consensus.round\"} | avg(duration) by (resource.service.instance.id)"
-        }
-      ],
-      "fieldConfig": {
-        "defaults": {
-          "unit": "ms",
-          "thresholds": {
-            "steps": [
-              { "color": "green", "value": null },
-              { "color": "yellow", "value": 4000 },
-              { "color": "red", "value": 5000 }
-            ]
-          }
-        }
-      },
-      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 }
-    },
-    {
-      "title": "Phase Duration Breakdown",
-      "type": "barchart",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=~\"consensus.phase.*\"} | avg(duration) by (name)"
-        }
-      ],
-      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 }
-    },
-    {
-      "title": "Proposers per Round",
-      "type": "stat",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"consensus.round\"} | avg(span.xrpl.consensus.proposers)"
-        }
-      ],
-      "gridPos": { "h": 4, "w": 6, "x": 0, "y": 8 }
-    },
-    {
-      "title": "Recent Slow Rounds (>5s)",
-      "type": "table",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"consensus.round\"} | duration > 5s"
-        }
-      ],
-      "gridPos": { "h": 8, "w": 24, "x": 0, "y": 12 }
-    }
-  ]
-}
-```
-
-### 7.6.2 Node Overview Dashboard
-
-```json
-{
-  "title": "rippled Node Overview",
-  "uid": "rippled-node-overview",
-  "panels": [
-    {
-      "title": "Active Nodes",
-      "type": "stat",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\"} | count_over_time() by (resource.service.instance.id) | count()"
-        }
-      ],
-      "gridPos": { "h": 4, "w": 4, "x": 0, "y": 0 }
-    },
-    {
-      "title": "Total Transactions (1h)",
-      "type": "stat",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.receive\"} | count()"
-        }
-      ],
-      "gridPos": { "h": 4, "w": 4, "x": 4, "y": 0 }
-    },
-    {
-      "title": "Error Rate",
-      "type": "gauge",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && status.code=error} | rate() / {resource.service.name=\"rippled\"} | rate() * 100"
-        }
-      ],
-      "fieldConfig": {
-        "defaults": {
-          "unit": "percent",
-          "max": 10,
-          "thresholds": {
-            "steps": [
-              { "color": "green", "value": null },
-              { "color": "yellow", "value": 1 },
-              { "color": "red", "value": 5 }
-            ]
-          }
-        }
-      },
-      "gridPos": { "h": 4, "w": 4, "x": 8, "y": 0 }
-    },
-    {
-      "title": "Service Map",
-      "type": "nodeGraph",
-      "datasource": "Tempo",
-      "gridPos": { "h": 12, "w": 12, "x": 12, "y": 0 }
-    }
-  ]
-}
-```
-
-### 7.6.3 Alert Rules
-
-```yaml
-# grafana/provisioning/alerting/rippled-alerts.yaml
-apiVersion: 1
-
-groups:
-  - name: rippled-tracing-alerts
-    folder: rippled
-    interval: 1m
-    rules:
-      - uid: consensus-slow
-        title: Consensus Round Slow
-        condition: A
-        data:
-          - refId: A
-            datasourceUid: tempo
-            model:
-              queryType: traceql
-              query: '{resource.service.name="rippled" && name="consensus.round"} | avg(duration) > 5s'
-        for: 5m
-        annotations:
-          summary: Consensus rounds taking >5 seconds
-          description: "Consensus duration: {{ $value }}ms"
-        labels:
-          severity: warning
-
-      - uid: rpc-error-spike
-        title: RPC Error Rate Spike
-        condition: B
-        data:
-          - refId: B
-            datasourceUid: tempo
-            model:
-              queryType: traceql
-              query: '{resource.service.name="rippled" && name=~"rpc.command.*" && status.code=error} | rate() > 0.05'
-        for: 2m
-        annotations:
-          summary: RPC error rate >5%
-        labels:
-          severity: critical
-
-      - uid: tx-throughput-drop
-        title: Transaction Throughput Drop
-        condition: C
-        data:
-          - refId: C
-            datasourceUid: tempo
-            model:
-              queryType: traceql
-              query: '{resource.service.name="rippled" && name="tx.receive"} | rate() < 10'
-        for: 10m
-        annotations:
-          summary: Transaction throughput below threshold
-        labels:
-          severity: warning
-```
-
----
-
-## 7.7 PerfLog and Insight Correlation
-
-How to correlate OpenTelemetry traces with existing rippled observability.
-
-### 7.7.1 Correlation Architecture
-
-```mermaid
-flowchart TB
-    subgraph rippled["rippled Node"]
-        otel[OpenTelemetry<br/>Spans]
-        perflog[PerfLog<br/>JSON Logs]
-        insight[Beast Insight<br/>StatsD Metrics]
-    end
-
-    subgraph collectors["Data Collection"]
-        otelc[OTel Collector]
-        promtail[Promtail/Fluentd]
-        statsd[StatsD Exporter]
-    end
-
-    subgraph storage["Storage"]
-        tempo[(Tempo)]
-        loki[(Loki)]
-        prom[(Prometheus)]
-    end
-
-    subgraph grafana["Grafana"]
-        traces[Trace View]
-        logs[Log View]
-        metrics[Metrics View]
-        corr[Correlation<br/>Panel]
-    end
-
-    otel -->|OTLP| otelc --> tempo
-    perflog -->|JSON| promtail --> loki
-    insight -->|StatsD| statsd --> prom
-
-    tempo --> traces
-    loki --> logs
-    prom --> metrics
-
-    traces --> corr
-    logs --> corr
-    metrics --> corr
-
-    style rippled 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
-    style otel fill:#0d47a1,stroke:#082f6a,color:#fff
-    style perflog fill:#0d47a1,stroke:#082f6a,color:#fff
-    style insight fill:#0d47a1,stroke:#082f6a,color:#fff
-    style otelc fill:#bf360c,stroke:#8c2809,color:#fff
-    style promtail fill:#bf360c,stroke:#8c2809,color:#fff
-    style statsd fill:#bf360c,stroke:#8c2809,color:#fff
-    style tempo fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style loki fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style prom fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style traces fill:#4a148c,stroke:#2e0d57,color:#fff
-    style logs fill:#4a148c,stroke:#2e0d57,color:#fff
-    style metrics fill:#4a148c,stroke:#2e0d57,color:#fff
-    style corr fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-### 7.7.2 Correlation Fields
-
-| Source      | Field                       | Link To       | Purpose                    |
-| ----------- | --------------------------- | ------------- | -------------------------- |
-| **Trace**   | `trace_id`                  | Logs          | Find log entries for trace |
-| **Trace**   | `xrpl.tx.hash`              | Logs, Metrics | Find TX-related data       |
-| **Trace**   | `xrpl.consensus.ledger.seq` | Logs          | Find ledger-related logs   |
-| **PerfLog** | `trace_id` (new)            | Traces        | Jump to trace from log     |
-| **PerfLog** | `ledger_seq`                | Traces        | Find consensus trace       |
-| **Insight** | `exemplar.trace_id`         | Traces        | Jump from metric spike     |
-
-### 7.7.3 Example: Debugging a Slow Transaction
-
-**Step 1: Find the trace**
-
-```
-# In Grafana Explore with Tempo
-{resource.service.name="rippled" && span.xrpl.tx.hash="ABC123..."}
-```
-
-**Step 2: Get the trace_id from the trace view**
-
-```
-Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736
-```
-
-**Step 3: Find related PerfLog entries**
-
-```
-# In Grafana Explore with Loki
-{job="rippled"} |= "4bf92f3577b34da6a3ce929d0e0e4736"
-```
-
-**Step 4: Check Insight metrics for the time window**
-
-```
-# In Grafana with Prometheus
-rate(rippled_tx_applied_total[1m])
-  @ timestamp_from_trace
-```
-
-### 7.7.4 Unified Dashboard Example
-
-```json
-{
-  "title": "rippled Unified Observability",
-  "uid": "rippled-unified",
-  "panels": [
-    {
-      "title": "Transaction Latency (Traces)",
-      "type": "timeseries",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\" && name=\"tx.receive\"} | histogram_over_time(duration)"
-        }
-      ],
-      "gridPos": { "h": 6, "w": 8, "x": 0, "y": 0 }
-    },
-    {
-      "title": "Transaction Rate (Metrics)",
-      "type": "timeseries",
-      "datasource": "Prometheus",
-      "targets": [
-        {
-          "expr": "rate(rippled_tx_received_total[5m])",
-          "legendFormat": "{{ instance }}"
-        }
-      ],
-      "fieldConfig": {
-        "defaults": {
-          "links": [
-            {
-              "title": "View traces",
-              "url": "/explore?left={\"datasource\":\"Tempo\",\"query\":\"{resource.service.name=\\\"rippled\\\" && name=\\\"tx.receive\\\"}\"}"
-            }
-          ]
-        }
-      },
-      "gridPos": { "h": 6, "w": 8, "x": 8, "y": 0 }
-    },
-    {
-      "title": "Recent Logs",
-      "type": "logs",
-      "datasource": "Loki",
-      "targets": [
-        {
-          "expr": "{job=\"rippled\"} | json"
-        }
-      ],
-      "gridPos": { "h": 6, "w": 8, "x": 16, "y": 0 }
-    },
-    {
-      "title": "Trace Search",
-      "type": "table",
-      "datasource": "Tempo",
-      "targets": [
-        {
-          "queryType": "traceql",
-          "query": "{resource.service.name=\"rippled\"}"
-        }
-      ],
-      "fieldConfig": {
-        "overrides": [
-          {
-            "matcher": { "id": "byName", "options": "traceID" },
-            "properties": [
-              {
-                "id": "links",
-                "value": [
-                  {
-                    "title": "View trace",
-                    "url": "/explore?left={\"datasource\":\"Tempo\",\"query\":\"${__value.raw}\"}"
-                  },
-                  {
-                    "title": "View logs",
-                    "url": "/explore?left={\"datasource\":\"Loki\",\"query\":\"{job=\\\"rippled\\\"} |= \\\"${__value.raw}\\\"\"}"
-                  }
-                ]
-              }
-            ]
-          }
-        ]
-      },
-      "gridPos": { "h": 12, "w": 24, "x": 0, "y": 6 }
-    }
-  ]
-}
-```
-
----
-
-_Previous: [Implementation Phases](./06-implementation-phases.md)_ | _Next: [Appendix](./08-appendix.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/08-appendix.md

@@ -1,231 +0,0 @@
-# Appendix
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Observability Backends](./07-observability-backends.md)
-
----
-
-## 8.1 Glossary
-
-| Term                  | Definition                                                 |
-| --------------------- | ---------------------------------------------------------- |
-| **Span**              | A unit of work with start/end time, name, and attributes   |
-| **Trace**             | A collection of spans representing a complete request flow |
-| **Trace ID**          | 128-bit unique identifier for a trace                      |
-| **Span ID**           | 64-bit unique identifier for a span within a trace         |
-| **Context**           | Carrier for trace/span IDs across boundaries               |
-| **Propagator**        | Component that injects/extracts context                    |
-| **Sampler**           | Decides which traces to record                             |
-| **Exporter**          | Sends spans to backend                                     |
-| **Collector**         | Receives, processes, and forwards telemetry                |
-| **OTLP**              | OpenTelemetry Protocol (wire format)                       |
-| **W3C Trace Context** | Standard HTTP headers for trace propagation                |
-| **Baggage**           | Key-value pairs propagated across service boundaries       |
-| **Resource**          | Entity producing telemetry (service, host, etc.)           |
-| **Instrumentation**   | Code that creates telemetry data                           |
-
-### rippled-Specific Terms
-
-| Term              | Definition                                         |
-| ----------------- | -------------------------------------------------- |
-| **Overlay**       | P2P network layer managing peer connections        |
-| **Consensus**     | XRP Ledger consensus algorithm (RCL)               |
-| **Proposal**      | Validator's suggested transaction set for a ledger |
-| **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              |
-
-### Phase 9–11 Terms
-
-| Term                        | Definition                                                                |
-| --------------------------- | ------------------------------------------------------------------------- |
-| **MetricsRegistry**         | Centralized class for OTel async gauge registrations (Phase 9)            |
-| **ObservableGauge**         | OTel Metrics SDK async instrument polled via callback at fixed intervals  |
-| **PeriodicMetricReader**    | OTel SDK component that invokes gauge callbacks at configurable intervals |
-| **CountedObject**           | rippled template that tracks live instance counts via atomic counters     |
-| **TxQ**                     | Transaction queue managing fee escalation and ordering                    |
-| **Load Factor**             | Combined multiplier affecting transaction cost (local, cluster, network)  |
-| **OTel Collector Receiver** | Custom Go plugin that polls rippled RPC and emits OTel metrics (Phase 11) |
-
----
-
-## 8.2 Span Hierarchy Visualization
-
-```mermaid
-flowchart TB
-    subgraph trace["Trace: Transaction Lifecycle"]
-        rpc["rpc.submit<br/>(entry point)"]
-        validate["tx.validate"]
-        relay["tx.relay<br/>(parent span)"]
-
-        subgraph peers["Peer Spans"]
-            p1["peer.send<br/>Peer A"]
-            p2["peer.send<br/>Peer B"]
-            p3["peer.send<br/>Peer C"]
-        end
-
-        consensus["consensus.round"]
-        apply["tx.apply"]
-    end
-
-    rpc --> validate
-    validate --> relay
-    relay --> p1
-    relay --> p2
-    relay --> p3
-    p1 -.->|"context propagation"| consensus
-    consensus --> apply
-
-    style trace fill:#0f172a,stroke:#020617,color:#fff
-    style peers fill:#1e3a8a,stroke:#172554,color:#fff
-    style rpc fill:#1d4ed8,stroke:#1e40af,color:#fff
-    style validate fill:#047857,stroke:#064e3b,color:#fff
-    style relay fill:#047857,stroke:#064e3b,color:#fff
-    style p1 fill:#0e7490,stroke:#155e75,color:#fff
-    style p2 fill:#0e7490,stroke:#155e75,color:#fff
-    style p3 fill:#0e7490,stroke:#155e75,color:#fff
-    style consensus fill:#fef3c7,stroke:#fde68a,color:#1e293b
-    style apply fill:#047857,stroke:#064e3b,color:#fff
-```
-
----
-
-## 8.3 References
-
-### OpenTelemetry Resources
-
-1. [OpenTelemetry C++ SDK](https://github.com/open-telemetry/opentelemetry-cpp)
-2. [OpenTelemetry Specification](https://opentelemetry.io/docs/specs/otel/)
-3. [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
-4. [OTLP Protocol Specification](https://opentelemetry.io/docs/specs/otlp/)
-
-### Standards
-
-5. [W3C Trace Context](https://www.w3.org/TR/trace-context/)
-6. [W3C Baggage](https://www.w3.org/TR/baggage/)
-7. [Protocol Buffers](https://protobuf.dev/)
-
-### rippled Resources
-
-8. [rippled 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)
-
----
-
-## 8.4 Version History
-
-| Version | Date       | Author | Changes                                      |
-| ------- | ---------- | ------ | -------------------------------------------- |
-| 1.0     | 2026-02-12 | -      | Initial implementation plan                  |
-| 1.1     | 2026-02-13 | -      | Refactored into modular documents            |
-| 1.2     | 2026-03-09 | -      | Added Phases 9–11 (future enhancement plans) |
-
----
-
-## 8.5 Document Index
-
-### Plan Documents
-
-| Document                                                             | Description                                  |
-| -------------------------------------------------------------------- | -------------------------------------------- |
-| [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        |
-| [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     |
-| [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        |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Span/metric/dashboard inventory              |
-| [presentation.md](./presentation.md)                                 | Slide deck for OTel plan overview            |
-
-### Task Lists
-
-| Document                                                                   | Description                                         |
-| -------------------------------------------------------------------------- | --------------------------------------------------- |
-| [POC_taskList.md](./POC_taskList.md)                                       | Proof-of-concept telemetry integration              |
-| [Phase2_taskList.md](./Phase2_taskList.md)                                 | RPC layer trace instrumentation                     |
-| [Phase3_taskList.md](./Phase3_taskList.md)                                 | Peer overlay & consensus tracing                    |
-| [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                       |
-| [Phase8_taskList.md](./Phase8_taskList.md)                                 | Log-trace correlation                               |
-| [Phase9_taskList.md](./Phase9_taskList.md)                                 | Internal metric instrumentation gap fill (future)   |
-| [Phase10_taskList.md](./Phase10_taskList.md)                               | Synthetic workload generation & validation (future) |
-| [Phase11_taskList.md](./Phase11_taskList.md)                               | Third-party data collection pipelines (future)      |
-
-> **Note**: Phases 1 and 6 do not have separate task list files. Phase 1 tasks are documented in [06-implementation-phases.md §6.2](./06-implementation-phases.md). Phase 6 tasks are documented in [06-implementation-phases.md §6.7](./06-implementation-phases.md).
-
----
-
-## 8.6 Phase 9–11 Cross-Reference Guide
-
-This guide maps Phase 9–11 content to its location across the documentation.
-
-### Phase 9: Internal Metric Instrumentation Gap Fill
-
-| Content                         | Location                                                                 |
-| ------------------------------- | ------------------------------------------------------------------------ |
-| Plan & architecture             | [06-implementation-phases.md §6.8.2](./06-implementation-phases.md)      |
-| Task list (10 tasks, 12d)       | [Phase9_taskList.md](./Phase9_taskList.md)                               |
-| Future metric definitions (~50) | [09-data-collection-reference.md §5b](./09-data-collection-reference.md) |
-| New class: `MetricsRegistry`    | `src/xrpld/telemetry/MetricsRegistry.h/.cpp` (planned)                   |
-| New dashboards                  | `rippled-fee-market`, `rippled-job-queue` (planned)                      |
-
-**Metric categories**: NodeStore I/O, Cache Hit Rates, TxQ, PerfLog Per-RPC, PerfLog Per-Job, Counted Objects, Fee Escalation & Load Factors.
-
-### Phase 10: Synthetic Workload Generation & Telemetry Validation
-
-| Content                  | Location                                                                 |
-| ------------------------ | ------------------------------------------------------------------------ |
-| Plan & architecture      | [06-implementation-phases.md §6.8.3](./06-implementation-phases.md)      |
-| Task list (7 tasks, 10d) | [Phase10_taskList.md](./Phase10_taskList.md)                             |
-| Validation inventory     | [09-data-collection-reference.md §5c](./09-data-collection-reference.md) |
-| Test harness             | `docker/telemetry/docker-compose.workload.yaml` (planned)                |
-| CI workflow              | `.github/workflows/telemetry-validation.yml` (planned)                   |
-
-**Validates**: 16 spans, 22 attributes, 300+ metrics, 10 dashboards, log-trace correlation.
-
-### Phase 11: Third-Party Data Collection Pipelines
-
-| Content                           | Location                                                                 |
-| --------------------------------- | ------------------------------------------------------------------------ |
-| Plan & architecture               | [06-implementation-phases.md §6.8.4](./06-implementation-phases.md)      |
-| Task list (11 tasks, 15d)         | [Phase11_taskList.md](./Phase11_taskList.md)                             |
-| External metric definitions (~30) | [09-data-collection-reference.md §5d](./09-data-collection-reference.md) |
-| Custom OTel Collector receiver    | `docker/telemetry/otel-rippled-receiver/` (planned)                      |
-| Prometheus alerting rules (11)    | [09-data-collection-reference.md §5d](./09-data-collection-reference.md) |
-| New dashboards (4)                | Validator Health, Network Topology, Fee Market (External), DEX & AMM     |
-
-**Consumer categories**: Exchanges, Payment Processors, DeFi/AMM, NFT Marketplaces, Analytics Providers, Wallets, Compliance, Academic Researchers, Institutional Custody, CBDC Bridge Operators.
-
----
-
-## 8.7 Effort Summary (All Phases)
-
-| Phase | Description                      | Effort     | Status             |
-| ----- | -------------------------------- | ---------- | ------------------ |
-| 1     | Core SDK integration             | 5d         | Active             |
-| 2     | RPC tracing                      | 5d         | Active             |
-| 3     | Peer & consensus tracing         | 8d         | Active             |
-| 4     | Transaction lifecycle            | 7d         | Active             |
-| 5     | Ledger & advanced                | 7.1d       | Active             |
-| 6     | StatsD → OTel bridge             | 8d         | Active             |
-| 7     | Native OTel metrics              | 15d        | Active             |
-| 8     | Log-trace correlation            | 10d        | Active             |
-| 9     | Internal metric gap fill         | 12d        | Future Enhancement |
-| 10    | Workload generation & validation | 10d        | Future Enhancement |
-| 11    | Third-party data pipelines       | 15d        | Future Enhancement |
-|       | **Total**                        | **102.1d** |                    |
-
----
-
-_Previous: [Observability Backends](./07-observability-backends.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/09-data-collection-reference.md

@@ -1,992 +0,0 @@
-# Observability Data Collection Reference
-
-> **Audience**: Developers and operators. This is the single source of truth for all telemetry data collected by rippled's observability stack.
->
-> **Related docs**: [docs/telemetry-runbook.md](../docs/telemetry-runbook.md) (operator runbook with alerting and troubleshooting) | [03-implementation-strategy.md](./03-implementation-strategy.md) (code structure and performance optimization) | [04-code-samples.md](./04-code-samples.md) (C++ instrumentation examples)
-
-## Data Flow Overview
-
-```mermaid
-graph LR
-    subgraph rippledNode["rippled Node"]
-        A["Trace Macros<br/>XRPL_TRACE_SPAN<br/>(OTLP/HTTP exporter)"]
-        B["beast::insight<br/>OTel native metrics<br/>(OTLP/HTTP exporter)"]
-        C["MetricsRegistry<br/>OTel SDK metrics<br/>(OTLP/HTTP exporter)"]
-    end
-
-    subgraph collector["OTel Collector  :4317 / :4318"]
-        direction TB
-        R1["OTLP Receiver<br/>:4317 gRPC  |  :4318 HTTP<br/>(traces + metrics)"]
-        BP["Batch Processor<br/>timeout 1s, batch 100"]
-        SM["SpanMetrics Connector<br/>derives RED metrics<br/>from trace spans"]
-
-        R1 --> BP
-        BP --> SM
-    end
-
-    subgraph backends["Trace Backends  (choose one or both)"]
-        D["Jaeger  :16686<br/>Trace search &<br/>visualization"]
-        T["Grafana Tempo<br/>(preferred for production)<br/>S3/GCS long-term storage"]
-    end
-
-    subgraph metrics["Metrics Stack"]
-        E["Prometheus  :9090<br/>scrapes :8889<br/>span-derived + system metrics"]
-    end
-
-    subgraph viz["Visualization"]
-        F["Grafana  :3000<br/>13 dashboards"]
-    end
-
-    A -->|"OTLP/HTTP :4318<br/>(traces + attributes)"| R1
-    B -->|"OTLP/HTTP :4318<br/>(gauges, counters, histograms)"| R1
-    C -->|"OTLP/HTTP :4318<br/>(counters, histograms,<br/>observable gauges)"| R1
-
-    BP -->|"OTLP/gRPC :4317"| D
-    BP -->|"OTLP/gRPC"| T
-
-    SM -->|"span_calls_total<br/>span_duration_ms<br/>(6 dimension labels)"| E
-    R1 -->|"rippled_* gauges<br/>rippled_* counters<br/>rippled_* histograms"| E
-
-    E -->|"Prometheus<br/>data source"| F
-    D -->|"Jaeger<br/>data source"| F
-    T -->|"Tempo<br/>data source"| F
-
-    style A fill:#4a90d9,color:#fff,stroke:#2a6db5
-    style B fill:#4a90d9,color:#fff,stroke:#2a6db5
-    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 T fill:#e8953a,color:#000,stroke:#b5732a
-    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
-```
-
-There are two independent telemetry pipelines entering a single **OTel Collector** via the same OTLP receiver:
-
-1. **OpenTelemetry Traces** — Distributed spans with attributes, exported via OTLP/HTTP (:4318) to the collector's **OTLP Receiver**. The **Batch Processor** groups spans (1s timeout, batch size 100) before forwarding to trace backends. The **SpanMetrics Connector** derives RED metrics (rate, errors, duration) from every span and feeds them into the metrics pipeline.
-2. **beast::insight OTel Metrics** — System-level gauges, counters, and histograms exported natively via OTLP/HTTP (:4318) to the same **OTLP Receiver**. These are batched and exported to Prometheus alongside span-derived metrics. The StatsD UDP transport has been replaced by native OTLP; `server=statsd` remains available as a fallback.
-
-**Trace backends** — The collector exports traces via OTLP/gRPC to one or both:
-
-- **Jaeger** (development) — Provides trace search UI at `:16686`. Easy single-binary setup.
-- **Grafana Tempo** (production) — Preferred for production. Supports S3/GCS object storage for cost-effective long-term trace retention and integrates natively with Grafana.
-
-> **Further reading**: [00-tracing-fundamentals.md](./00-tracing-fundamentals.md) for core OpenTelemetry concepts (traces, spans, context propagation, sampling). [07-observability-backends.md](./07-observability-backends.md) for production backend selection, collector placement, and sampling strategies.
-
----
-
-## 1. OpenTelemetry Spans
-
-### 1.1 Complete Span Inventory (16 spans)
-
-> **See also**: [02-design-decisions.md §2.3](./02-design-decisions.md#23-span-naming-conventions) for naming conventions and the full span catalog with rationale. [04-code-samples.md §4.6](./04-code-samples.md#46-span-flow-visualization) for span flow diagrams.
-
-#### RPC Spans
-
-Controlled by `trace_rpc=1` in `[telemetry]` config.
-
-| Span Name            | Parent        | Source File       | Description                                                              |
-| -------------------- | ------------- | ----------------- | ------------------------------------------------------------------------ |
-| `rpc.request`        | —             | ServerHandler.cpp | Top-level HTTP RPC request entry point                                   |
-| `rpc.process`        | `rpc.request` | ServerHandler.cpp | RPC processing pipeline                                                  |
-| `rpc.ws_message`     | —             | ServerHandler.cpp | WebSocket message handling                                               |
-| `rpc.command.<name>` | `rpc.process` | RPCHandler.cpp    | Per-command span (e.g., `rpc.command.server_info`, `rpc.command.ledger`) |
-
-**Where to find**: Jaeger → Service: `rippled` → Operation: `rpc.request` or `rpc.command.*`
-
-**Grafana dashboard**: _RPC Performance_ (`rippled-rpc-perf`)
-
-#### Transaction Spans
-
-Controlled by `trace_transactions=1` in `[telemetry]` config.
-
-| Span Name    | Parent         | Source File     | Description                                                       |
-| ------------ | -------------- | --------------- | ----------------------------------------------------------------- |
-| `tx.process` | —              | NetworkOPs.cpp  | Transaction submission entry point (local or peer-relayed)        |
-| `tx.receive` | —              | PeerImp.cpp     | Raw transaction received from peer overlay (before deduplication) |
-| `tx.apply`   | `ledger.build` | BuildLedger.cpp | Transaction set applied to new ledger during consensus            |
-
-**Where to find**: Jaeger → Operation: `tx.process` or `tx.receive`
-
-**Grafana dashboard**: _Transaction Overview_ (`rippled-transactions`)
-
-#### Consensus Spans
-
-Controlled by `trace_consensus=1` in `[telemetry]` config.
-
-| Span Name                   | Parent | Source File      | Description                                   |
-| --------------------------- | ------ | ---------------- | --------------------------------------------- |
-| `consensus.proposal.send`   | —      | RCLConsensus.cpp | Node broadcasts its transaction set proposal  |
-| `consensus.ledger_close`    | —      | RCLConsensus.cpp | Ledger close event triggered by consensus     |
-| `consensus.accept`          | —      | RCLConsensus.cpp | Consensus accepts a ledger (round complete)   |
-| `consensus.validation.send` | —      | RCLConsensus.cpp | Validation message sent after ledger accepted |
-| `consensus.accept.apply`    | —      | RCLConsensus.cpp | Ledger application with close time details    |
-
-**Where to find**: Jaeger → Operation: `consensus.*`
-
-**Grafana dashboard**: _Consensus Health_ (`rippled-consensus`)
-
-#### Ledger Spans
-
-Controlled by `trace_ledger=1` in `[telemetry]` config.
-
-| Span Name         | Parent | Source File      | Description                                    |
-| ----------------- | ------ | ---------------- | ---------------------------------------------- |
-| `ledger.build`    | —      | BuildLedger.cpp  | Build new ledger from accepted transaction set |
-| `ledger.validate` | —      | LedgerMaster.cpp | Ledger promoted to validated status            |
-| `ledger.store`    | —      | LedgerMaster.cpp | Ledger stored to database/history              |
-
-**Where to find**: Jaeger → Operation: `ledger.*`
-
-**Grafana dashboard**: _Ledger Operations_ (`rippled-ledger-ops`)
-
-#### Peer Spans
-
-Controlled by `trace_peer=1` in `[telemetry]` config. **Disabled by default** (high volume).
-
-| Span Name                 | Parent | Source File | Description                           |
-| ------------------------- | ------ | ----------- | ------------------------------------- |
-| `peer.proposal.receive`   | —      | PeerImp.cpp | Consensus proposal received from peer |
-| `peer.validation.receive` | —      | PeerImp.cpp | Validation message received from peer |
-
-**Where to find**: Jaeger → Operation: `peer.*`
-
-**Grafana dashboard**: _Peer Network_ (`rippled-peer-net`)
-
----
-
-### 1.2 Complete Attribute Inventory (22 attributes)
-
-> **See also**: [02-design-decisions.md §2.4.2](./02-design-decisions.md#242-span-attributes-by-category) for attribute design rationale and privacy considerations.
-
-Every span can carry key-value attributes that provide context for filtering and aggregation.
-
-#### RPC Attributes
-
-| Attribute                | Type   | Set On          | Description                                      |
-| ------------------------ | ------ | --------------- | ------------------------------------------------ |
-| `xrpl.rpc.command`       | string | `rpc.command.*` | RPC command name (e.g., `server_info`, `ledger`) |
-| `xrpl.rpc.version`       | int64  | `rpc.command.*` | API version number                               |
-| `xrpl.rpc.role`          | string | `rpc.command.*` | Caller role: `"admin"` or `"user"`               |
-| `xrpl.rpc.status`        | string | `rpc.command.*` | Result: `"success"` or `"error"`                 |
-| `xrpl.rpc.duration_ms`   | int64  | `rpc.command.*` | Command execution time in milliseconds           |
-| `xrpl.rpc.error_message` | string | `rpc.command.*` | Error details (only set on failure)              |
-
-**Jaeger query**: Tag `xrpl.rpc.command=server_info` to find all `server_info` calls.
-
-**Prometheus label**: `xrpl_rpc_command` (dots converted to underscores by SpanMetrics).
-
-#### Transaction Attributes
-
-| Attribute            | Type    | Set On                     | Description                                          |
-| -------------------- | ------- | -------------------------- | ---------------------------------------------------- |
-| `xrpl.tx.hash`       | string  | `tx.process`, `tx.receive` | Transaction hash (hex-encoded)                       |
-| `xrpl.tx.local`      | boolean | `tx.process`               | `true` if locally submitted, `false` if peer-relayed |
-| `xrpl.tx.path`       | string  | `tx.process`               | Submission path: `"sync"` or `"async"`               |
-| `xrpl.tx.suppressed` | boolean | `tx.receive`               | `true` if transaction was suppressed (duplicate)     |
-| `xrpl.tx.status`     | string  | `tx.receive`               | Transaction status (e.g., `"known_bad"`)             |
-
-**Jaeger query**: Tag `xrpl.tx.hash=<hash>` to trace a specific transaction across nodes.
-
-**Prometheus label**: `xrpl_tx_local` (used as SpanMetrics dimension).
-
-#### Consensus Attributes
-
-| Attribute                            | Type    | Set On                                                                                              | Description                                                   |
-| ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `xrpl.consensus.round`               | int64   | `consensus.proposal.send`                                                                           | Consensus round number                                        |
-| `xrpl.consensus.mode`                | string  | `consensus.proposal.send`, `consensus.ledger_close`                                                 | Node mode: `"syncing"`, `"tracking"`, `"full"`, `"proposing"` |
-| `xrpl.consensus.proposers`           | int64   | `consensus.proposal.send`, `consensus.accept`                                                       | Number of proposers in the round                              |
-| `xrpl.consensus.proposing`           | boolean | `consensus.validation.send`                                                                         | Whether this node was a proposer                              |
-| `xrpl.consensus.ledger.seq`          | int64   | `consensus.ledger_close`, `consensus.accept`, `consensus.validation.send`, `consensus.accept.apply` | Ledger sequence number                                        |
-| `xrpl.consensus.close_time`          | int64   | `consensus.accept.apply`                                                                            | Agreed-upon ledger close time (epoch seconds)                 |
-| `xrpl.consensus.close_time_correct`  | boolean | `consensus.accept.apply`                                                                            | Whether validators reached agreement on close time            |
-| `xrpl.consensus.close_resolution_ms` | int64   | `consensus.accept.apply`                                                                            | Close time rounding granularity in milliseconds               |
-| `xrpl.consensus.state`               | string  | `consensus.accept.apply`                                                                            | Consensus outcome: `"finished"` or `"moved_on"`               |
-| `xrpl.consensus.round_time_ms`       | int64   | `consensus.accept.apply`                                                                            | Total consensus round duration in milliseconds                |
-
-**Jaeger query**: Tag `xrpl.consensus.mode=proposing` to find rounds where node was proposing.
-
-**Prometheus label**: `xrpl_consensus_mode` (used as SpanMetrics dimension).
-
-#### Ledger Attributes
-
-| Attribute                 | Type  | Set On                                                        | Description                                    |
-| ------------------------- | ----- | ------------------------------------------------------------- | ---------------------------------------------- |
-| `xrpl.ledger.seq`         | int64 | `ledger.build`, `ledger.validate`, `ledger.store`, `tx.apply` | Ledger sequence number                         |
-| `xrpl.ledger.validations` | int64 | `ledger.validate`                                             | Number of validations received for this ledger |
-| `xrpl.ledger.tx_count`    | int64 | `ledger.build`, `tx.apply`                                    | Transactions in the ledger                     |
-| `xrpl.ledger.tx_failed`   | int64 | `ledger.build`, `tx.apply`                                    | Failed transactions in the ledger              |
-
-**Jaeger query**: Tag `xrpl.ledger.seq=12345` to find all spans for a specific ledger.
-
-#### Peer Attributes
-
-| Attribute                      | Type    | Set On                                                           | Description                                          |
-| ------------------------------ | ------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
-| `xrpl.peer.id`                 | int64   | `tx.receive`, `peer.proposal.receive`, `peer.validation.receive` | Peer identifier                                      |
-| `xrpl.peer.proposal.trusted`   | boolean | `peer.proposal.receive`                                          | Whether the proposal came from a trusted validator   |
-| `xrpl.peer.validation.trusted` | boolean | `peer.validation.receive`                                        | Whether the validation came from a trusted validator |
-
-**Prometheus labels**: `xrpl_peer_proposal_trusted`, `xrpl_peer_validation_trusted` (SpanMetrics dimensions).
-
----
-
-### 1.3 SpanMetrics — Derived Prometheus Metrics
-
-> **See also**: [01-architecture-analysis.md](./01-architecture-analysis.md) §1.8.2 for how span-derived metrics map to operational insights.
-
-The OTel Collector's SpanMetrics connector automatically generates RED (Rate, Errors, Duration) metrics from every span. No custom metrics code in rippled is needed.
-
-| Prometheus Metric                                  | Type      | Description                                                                    |
-| -------------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
-| `traces_span_metrics_calls_total`                  | Counter   | Total span invocations                                                         |
-| `traces_span_metrics_duration_milliseconds_bucket` | Histogram | Latency distribution (buckets: 1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000 ms) |
-| `traces_span_metrics_duration_milliseconds_count`  | Histogram | Observation count                                                              |
-| `traces_span_metrics_duration_milliseconds_sum`    | Histogram | Cumulative latency                                                             |
-
-**Standard labels on every metric**: `span_name`, `status_code`, `service_name`, `span_kind`
-
-**Additional dimension labels** (configured in `otel-collector-config.yaml`):
-
-| Span Attribute                 | Prometheus Label               | Applies To                |
-| ------------------------------ | ------------------------------ | ------------------------- |
-| `xrpl.rpc.command`             | `xrpl_rpc_command`             | `rpc.command.*`           |
-| `xrpl.rpc.status`              | `xrpl_rpc_status`              | `rpc.command.*`           |
-| `xrpl.consensus.mode`          | `xrpl_consensus_mode`          | `consensus.ledger_close`  |
-| `xrpl.tx.local`                | `xrpl_tx_local`                | `tx.process`              |
-| `xrpl.peer.proposal.trusted`   | `xrpl_peer_proposal_trusted`   | `peer.proposal.receive`   |
-| `xrpl.peer.validation.trusted` | `xrpl_peer_validation_trusted` | `peer.validation.receive` |
-
-**Where to query**: Prometheus → `traces_span_metrics_calls_total{span_name="rpc.command.server_info"}`
-
----
-
-## 2. System Metrics (beast::insight — OTel native)
-
-> **See also**: [02-design-decisions.md](./02-design-decisions.md) for the beast::insight coexistence design. [06-implementation-phases.md](./06-implementation-phases.md) for the Phase 6/7 metric inventory.
->
-> **Migration complete**: Phase 7 replaced the StatsD UDP transport with native OTel Metrics SDK export via OTLP/HTTP. The `beast::insight::Collector` interface and all metric names are preserved — only the wire protocol changed. `[insight] server=statsd` remains as a fallback.
-
-These are system-level metrics emitted by rippled's `beast::insight` framework via OTel OTLP/HTTP. They cover operational data that doesn't map to individual trace spans.
-
-### Configuration
-
-```ini
-# Recommended: native OTel metrics via OTLP/HTTP
-[insight]
-server=otel
-endpoint=http://localhost:4318/v1/metrics
-prefix=rippled
-```
-
-Fallback (StatsD):
-
-```ini
-[insight]
-server=statsd
-address=127.0.0.1:8125
-prefix=rippled
-```
-
-### 2.1 Gauges
-
-| Prometheus Metric                                   | Source File           | Description                              | Typical Range                   |
-| --------------------------------------------------- | --------------------- | ---------------------------------------- | ------------------------------- |
-| `rippled_LedgerMaster_Validated_Ledger_Age`         | LedgerMaster.h        | Seconds since last validated ledger      | 0–10 (healthy), >30 (stale)     |
-| `rippled_LedgerMaster_Published_Ledger_Age`         | LedgerMaster.h        | Seconds since last published ledger      | 0–10 (healthy)                  |
-| `rippled_State_Accounting_Disconnected_duration`    | NetworkOPs.cpp        | Cumulative seconds in Disconnected state | Monotonic                       |
-| `rippled_State_Accounting_Connected_duration`       | NetworkOPs.cpp        | Cumulative seconds in Connected state    | Monotonic                       |
-| `rippled_State_Accounting_Syncing_duration`         | NetworkOPs.cpp        | Cumulative seconds in Syncing state      | Monotonic                       |
-| `rippled_State_Accounting_Tracking_duration`        | NetworkOPs.cpp        | Cumulative seconds in Tracking state     | Monotonic                       |
-| `rippled_State_Accounting_Full_duration`            | NetworkOPs.cpp        | Cumulative seconds in Full state         | Monotonic (should dominate)     |
-| `rippled_State_Accounting_Disconnected_transitions` | NetworkOPs.cpp        | Count of transitions to Disconnected     | Low                             |
-| `rippled_State_Accounting_Connected_transitions`    | NetworkOPs.cpp        | Count of transitions to Connected        | Low                             |
-| `rippled_State_Accounting_Syncing_transitions`      | NetworkOPs.cpp        | Count of transitions to Syncing          | Low                             |
-| `rippled_State_Accounting_Tracking_transitions`     | NetworkOPs.cpp        | Count of transitions to Tracking         | Low                             |
-| `rippled_State_Accounting_Full_transitions`         | NetworkOPs.cpp        | Count of transitions to Full             | Low (should be 1 after startup) |
-| `rippled_Peer_Finder_Active_Inbound_Peers`          | PeerfinderManager.cpp | Active inbound peer connections          | 0–85                            |
-| `rippled_Peer_Finder_Active_Outbound_Peers`         | PeerfinderManager.cpp | Active outbound peer connections         | 10–21                           |
-| `rippled_Overlay_Peer_Disconnects`                  | OverlayImpl.cpp       | Cumulative peer disconnection count      | Low growth                      |
-| `rippled_job_count`                                 | JobQueue.cpp          | Current job queue depth                  | 0–100 (healthy)                 |
-
-**Grafana dashboard**: _Node Health (System Metrics)_ (`rippled-system-node-health`)
-
-### 2.2 Counters
-
-| Prometheus Metric                 | Source File        | Description                                   |
-| --------------------------------- | ------------------ | --------------------------------------------- |
-| `rippled_rpc_requests`            | ServerHandler.cpp  | Total RPC requests received                   |
-| `rippled_ledger_fetches`          | InboundLedgers.cpp | Inbound ledger fetch attempts                 |
-| `rippled_ledger_history_mismatch` | LedgerHistory.cpp  | Ledger hash mismatches detected               |
-| `rippled_warn`                    | Logic.h            | Resource manager warnings issued              |
-| `rippled_drop`                    | Logic.h            | Resource manager drops (connections rejected) |
-
-**Note**: With `server=otel`, `rippled_warn` and `rippled_drop` are properly exported as OTel Counter instruments. The previous StatsD `|m` type limitation no longer applies.
-
-**Grafana dashboard**: _RPC & Pathfinding (System Metrics)_ (`rippled-system-rpc`)
-
-### 2.3 Histograms (Event timers)
-
-| Prometheus Metric       | Source File       | Unit  | Description                    |
-| ----------------------- | ----------------- | ----- | ------------------------------ |
-| `rippled_rpc_time`      | ServerHandler.cpp | ms    | RPC response time distribution |
-| `rippled_rpc_size`      | ServerHandler.cpp | bytes | RPC response size distribution |
-| `rippled_ios_latency`   | Application.cpp   | ms    | I/O service loop latency       |
-| `rippled_pathfind_fast` | PathRequests.h    | ms    | Fast pathfinding duration      |
-| `rippled_pathfind_full` | PathRequests.h    | ms    | Full pathfinding duration      |
-
-Quantiles collected: 0th, 50th, 90th, 95th, 99th, 100th percentile.
-
-**Grafana dashboards**: _Node Health_ (`ios_latency`), _RPC & Pathfinding_ (`rpc_time`, `rpc_size`, `pathfind_*`)
-
-### 2.4 Overlay Traffic Metrics
-
-For each of the 45+ overlay traffic categories (defined in `TrafficCount.h`), four gauges are emitted:
-
-- `rippled_{category}_Bytes_In`
-- `rippled_{category}_Bytes_Out`
-- `rippled_{category}_Messages_In`
-- `rippled_{category}_Messages_Out`
-
-**Key categories**:
-
-| Category                                                          | Description                |
-| ----------------------------------------------------------------- | -------------------------- |
-| `total`                                                           | All traffic aggregated     |
-| `overhead` / `overhead_overlay`                                   | Protocol overhead          |
-| `transactions` / `transactions_duplicate`                         | Transaction relay          |
-| `proposals` / `proposals_untrusted` / `proposals_duplicate`       | Consensus proposals        |
-| `validations` / `validations_untrusted` / `validations_duplicate` | Consensus validations      |
-| `ledger_data_get` / `ledger_data_share`                           | Ledger data exchange       |
-| `ledger_data_Transaction_Node_get/share`                          | Transaction node data      |
-| `ledger_data_Account_State_Node_get/share`                        | Account state node data    |
-| `ledger_data_Transaction_Set_candidate_get/share`                 | Transaction set candidates |
-| `getObject` / `haveTxSet` / `ledgerData`                          | Object requests            |
-| `ping` / `status`                                                 | Keepalive and status       |
-| `set_get`                                                         | Set requests               |
-
-**Grafana dashboards**: _Network Traffic_ (`rippled-system-network`), _Overlay Traffic Detail_ (`rippled-system-overlay-detail`), _Ledger Data & Sync_ (`rippled-system-ledger-sync`)
-
----
-
-## 3. Grafana Dashboard Reference
-
-> **See also**: [05-configuration-reference.md](./05-configuration-reference.md) §5.8 for Grafana data source provisioning (Tempo, Jaeger, Prometheus) and TraceQL query examples.
-
-### 3.1 Span-Derived Dashboards (5)
-
-| Dashboard            | UID                    | Data Source              | Key Panels                                                                         |
-| -------------------- | ---------------------- | ------------------------ | ---------------------------------------------------------------------------------- |
-| RPC Performance      | `rippled-rpc-perf`     | Prometheus (SpanMetrics) | Request rate by command, p95 latency by command, error rate, heatmap, top commands |
-| Transaction Overview | `rippled-transactions` | Prometheus (SpanMetrics) | Processing rate, latency p95/p50, local vs relay split, apply duration, heatmap    |
-| Consensus Health     | `rippled-consensus`    | Prometheus (SpanMetrics) | Round duration p95/p50, proposals rate, close duration, mode timeline, heatmap     |
-| Ledger Operations    | `rippled-ledger-ops`   | Prometheus (SpanMetrics) | Build rate, build duration, validation rate, store rate, build vs close comparison |
-| Peer Network         | `rippled-peer-net`     | Prometheus (SpanMetrics) | Proposal receive rate, validation receive rate, trusted vs untrusted breakdown     |
-
-### 3.2 System Metrics Dashboards (5)
-
-| Dashboard              | UID                             | Data Source       | Key Panels                                                                        |
-| ---------------------- | ------------------------------- | ----------------- | --------------------------------------------------------------------------------- |
-| Node Health            | `rippled-system-node-health`    | Prometheus (OTLP) | Ledger age, operating mode, I/O latency, job queue, fetch rate                    |
-| Network Traffic        | `rippled-system-network`        | Prometheus (OTLP) | Active peers, disconnects, bytes in/out, messages in/out, traffic by category     |
-| RPC & Pathfinding      | `rippled-system-rpc`            | Prometheus (OTLP) | RPC rate, response time/size, pathfinding duration, resource warnings/drops       |
-| Overlay Traffic Detail | `rippled-system-overlay-detail` | Prometheus (OTLP) | Squelch, overhead, validator lists, set get/share, have/requested tx, proof paths |
-| Ledger Data & Sync     | `rippled-system-ledger-sync`    | Prometheus (OTLP) | Ledger data exchange, legacy ledger share/get, getobject by type, traffic heatmap |
-
-### 3.3 Accessing the Dashboards
-
-1. Open Grafana at **http://localhost:3000**
-2. Navigate to **Dashboards → rippled** folder
-3. All 10 dashboards are auto-provisioned from `docker/telemetry/grafana/dashboards/`
-
----
-
-## 4. Jaeger Trace Search Guide
-
-> **See also**: [08-appendix.md](./08-appendix.md) §8.2 for span hierarchy visualizations. [05-configuration-reference.md](./05-configuration-reference.md) §5.8.5 for TraceQL examples when using Grafana Tempo instead of Jaeger.
-
-### Finding Traces by Type
-
-| What to Find             | Jaeger Search Parameters                                   |
-| ------------------------ | ---------------------------------------------------------- |
-| All RPC calls            | Service: `rippled`, Operation: `rpc.request`               |
-| Specific RPC command     | Operation: `rpc.command.server_info` (or any command name) |
-| Slow RPC calls           | Operation: `rpc.command.*`, Min Duration: `100ms`          |
-| Failed RPC calls         | Tag: `xrpl.rpc.status=error`                               |
-| Specific transaction     | Tag: `xrpl.tx.hash=<hex_hash>`                             |
-| Local transactions only  | Tag: `xrpl.tx.local=true`                                  |
-| Consensus rounds         | Operation: `consensus.accept`                              |
-| Rounds by mode           | Tag: `xrpl.consensus.mode=proposing`                       |
-| Specific ledger          | Tag: `xrpl.ledger.seq=12345`                               |
-| Peer proposals (trusted) | Tag: `xrpl.peer.proposal.trusted=true`                     |
-
-### Trace Structure
-
-A typical RPC trace shows the span hierarchy:
-
-```
-rpc.request (ServerHandler)
-  └── rpc.process (ServerHandler)
-       └── rpc.command.server_info (RPCHandler)
-```
-
-A consensus round produces independent spans (not parent-child):
-
-```
-consensus.ledger_close        (close event)
-consensus.proposal.send       (broadcast proposal)
-ledger.build                  (build new ledger)
-  └── tx.apply                (apply transaction set)
-consensus.accept              (accept result)
-consensus.validation.send     (send validation)
-ledger.validate               (promote to validated)
-ledger.store                  (persist to DB)
-```
-
----
-
-## 5. Prometheus Query Examples
-
-> **See also**: [05-configuration-reference.md](./05-configuration-reference.md) §5.8.7 for correlating Prometheus system metrics with trace-derived metrics.
-
-### Span-Derived Metrics
-
-```promql
-# RPC request rate by command (last 5 minutes)
-sum by (xrpl_rpc_command) (rate(traces_span_metrics_calls_total{span_name=~"rpc.command.*"}[5m]))
-
-# RPC p95 latency by command
-histogram_quantile(0.95, sum by (le, xrpl_rpc_command) (rate(traces_span_metrics_duration_milliseconds_bucket{span_name=~"rpc.command.*"}[5m])))
-
-# Consensus round duration p95
-histogram_quantile(0.95, sum by (le) (rate(traces_span_metrics_duration_milliseconds_bucket{span_name="consensus.accept"}[5m])))
-
-# Transaction processing rate (local vs relay)
-sum by (xrpl_tx_local) (rate(traces_span_metrics_calls_total{span_name="tx.process"}[5m]))
-
-# Trusted vs untrusted proposal rate
-sum by (xrpl_peer_proposal_trusted) (rate(traces_span_metrics_calls_total{span_name="peer.proposal.receive"}[5m]))
-```
-
-### StatsD Metrics
-
-```promql
-# Validated ledger age (should be < 10s)
-rippled_LedgerMaster_Validated_Ledger_Age
-
-# Active peer count
-rippled_Peer_Finder_Active_Inbound_Peers + rippled_Peer_Finder_Active_Outbound_Peers
-
-# RPC response time p95
-histogram_quantile(0.95, rippled_rpc_time_bucket)
-
-# Total network bytes in (rate)
-rate(rippled_total_Bytes_In[5m])
-
-# Operating mode (should be "Full" after startup)
-rippled_State_Accounting_Full_duration
-```
-
----
-
-## 5a. Log-Trace Correlation (Phase 8)
-
-> **Plan details**: [06-implementation-phases.md §6.8.1](./06-implementation-phases.md) — motivation, architecture, Mermaid diagrams
-> **Task breakdown**: [Phase8_taskList.md](./Phase8_taskList.md) — per-task implementation details
-
-Phase 8 injects OTel trace context into rippled's `Logs::format()` output, enabling log-trace correlation. When a log line is emitted within an active OTel span, the trace and span identifiers are automatically appended after the severity field:
-
-### Log Format
-
-```
-<timestamp> <partition>:<severity> trace_id=<32hex> span_id=<16hex> <message>
-```
-
-Example:
-
-```
-2024-01-15T10:30:45.123Z LedgerMaster:NFO trace_id=abc123def456789012345678abcdef01 span_id=0123456789abcdef Validated ledger 42
-```
-
-- **`trace_id=<hex32>`** — 32-character lowercase hex trace identifier. Links to the distributed trace in Tempo/Jaeger.
-- **`span_id=<hex16>`** — 16-character lowercase hex span identifier. Identifies the specific span within the trace.
-- **Only present** when the log is emitted within an active OTel span. Log lines outside of traced code paths have no trace context fields.
-
-### Implementation
-
-The trace context injection is implemented in `Logs::format()` (`src/libxrpl/basics/Log.cpp`), guarded by `#ifdef XRPL_ENABLE_TELEMETRY`. It reads the current span from OTel's thread-local runtime context via `opentelemetry::trace::GetSpan()` and `opentelemetry::context::RuntimeContext::GetCurrent()`. Both calls are lock-free thread-local reads measured at <10ns per call.
-
-### Log Ingestion Pipeline
-
-```
-rippled debug.log -> OTel Collector filelog receiver -> regex_parser -> Loki exporter -> Grafana Loki
-```
-
-The OTel Collector's `filelog` receiver tails `debug.log` files and uses a `regex_parser` operator to extract structured fields:
-
-| Field       | Type     | Description                                              |
-| ----------- | -------- | -------------------------------------------------------- |
-| `timestamp` | datetime | Log timestamp                                            |
-| `partition` | string   | Log partition (e.g., `LedgerMaster`, `PeerImp`)          |
-| `severity`  | string   | Severity code (`TRC`, `DBG`, `NFO`, `WRN`, `ERR`, `FTL`) |
-| `trace_id`  | string   | 32-hex trace identifier (optional)                       |
-| `span_id`   | string   | 16-hex span identifier (optional)                        |
-| `message`   | string   | Log message body                                         |
-
-### Grafana Correlation
-
-Bidirectional linking between logs and traces is configured via Grafana datasource provisioning:
-
-- **Tempo -> Loki** (`tracesToLogs`): Clicking "Logs for this trace" on a Tempo trace view filters Loki logs by `trace_id`, showing all log lines from that trace.
-- **Loki -> Tempo** (`derivedFields`): A regex-based derived field on the Loki datasource extracts `trace_id` from log lines and renders it as a clickable link to the corresponding trace in Tempo.
-
-### Loki Backend
-
-Grafana Loki (v2.9.0) serves as the log storage backend. It receives log entries from the OTel Collector's `loki` exporter via the push API at `http://loki:3100/loki/api/v1/push`.
-
-### LogQL Query Examples
-
-```logql
-# Find all logs for a specific trace
-{job="rippled"} |= "trace_id=abc123def456789012345678abcdef01"
-
-# Error logs with trace context
-{job="rippled"} |= "ERR" |= "trace_id="
-
-# Logs from a specific partition with trace context
-{job="rippled"} |= "LedgerMaster" | regexp `trace_id=(?P<trace_id>[a-f0-9]+)` | trace_id != ""
-
-# Count traced log lines over time
-count_over_time({job="rippled"} |= "trace_id=" [5m])
-```
-
----
-
-## 5b. Future: Internal Metric Gap Fill (Phase 9)
-
-> **Status**: Planned, not yet implemented.
-> **Plan details**: [06-implementation-phases.md §6.8.2](./06-implementation-phases.md) — motivation, architecture, third-party context
-> **Task breakdown**: [Phase9_taskList.md](./Phase9_taskList.md) — per-task implementation details
-
-Phase 9 fills ~50+ metrics that exist inside rippled but currently lack time-series export. Uses a hybrid approach: `beast::insight` extensions for NodeStore I/O, OTel `ObservableGauge` async callbacks for new categories.
-
-### New Metric Categories
-
-#### NodeStore I/O (via beast::insight)
-
-| Prometheus Metric                    | Type  | Description                         |
-| ------------------------------------ | ----- | ----------------------------------- |
-| `rippled_nodestore_reads_total`      | Gauge | Cumulative read operations          |
-| `rippled_nodestore_reads_hit`        | Gauge | Cache-served reads                  |
-| `rippled_nodestore_writes`           | Gauge | Cumulative write operations         |
-| `rippled_nodestore_written_bytes`    | Gauge | Cumulative bytes written            |
-| `rippled_nodestore_read_bytes`       | Gauge | Cumulative bytes read               |
-| `rippled_nodestore_read_duration_us` | Gauge | Cumulative read time (microseconds) |
-| `rippled_nodestore_write_load`       | Gauge | Current write load score            |
-| `rippled_nodestore_read_queue`       | Gauge | Items in read queue                 |
-
-#### Cache Hit Rates (via OTel MetricsRegistry)
-
-| Prometheus Metric               | Type  | Description                          |
-| ------------------------------- | ----- | ------------------------------------ |
-| `rippled_cache_SLE_hit_rate`    | Gauge | SLE cache hit rate (0.0-1.0)         |
-| `rippled_cache_ledger_hit_rate` | Gauge | Ledger object cache hit rate         |
-| `rippled_cache_AL_hit_rate`     | Gauge | AcceptedLedger cache hit rate        |
-| `rippled_cache_treenode_size`   | Gauge | SHAMap TreeNode cache size (entries) |
-| `rippled_cache_fullbelow_size`  | Gauge | FullBelow cache size                 |
-
-#### Transaction Queue (via OTel MetricsRegistry)
-
-| Prometheus Metric                      | Type  | Description                      |
-| -------------------------------------- | ----- | -------------------------------- |
-| `rippled_txq_count`                    | Gauge | Current transactions in queue    |
-| `rippled_txq_max_size`                 | Gauge | Maximum queue capacity           |
-| `rippled_txq_in_ledger`                | Gauge | Transactions in open ledger      |
-| `rippled_txq_per_ledger`               | Gauge | Expected transactions per ledger |
-| `rippled_txq_open_ledger_fee_level`    | Gauge | Open ledger fee escalation level |
-| `rippled_txq_med_fee_level`            | Gauge | Median fee level in queue        |
-| `rippled_txq_reference_fee_level`      | Gauge | Reference fee level              |
-| `rippled_txq_min_processing_fee_level` | Gauge | Minimum fee to get processed     |
-
-#### PerfLog Per-RPC Method (via OTel Metrics SDK)
-
-| Prometheus Metric                       | Type      | Labels            | Description                 |
-| --------------------------------------- | --------- | ----------------- | --------------------------- |
-| `rippled_rpc_method_started_total`      | Counter   | `method="<name>"` | RPC calls started           |
-| `rippled_rpc_method_finished_total`     | Counter   | `method="<name>"` | RPC calls completed         |
-| `rippled_rpc_method_errored_total`      | Counter   | `method="<name>"` | RPC calls errored           |
-| `rippled_rpc_method_duration_us_bucket` | Histogram | `method="<name>"` | Execution time distribution |
-
-#### PerfLog Per-Job Type (via OTel Metrics SDK)
-
-| Prometheus Metric                        | Type      | Labels              | Description     |
-| ---------------------------------------- | --------- | ------------------- | --------------- |
-| `rippled_job_queued_total`               | Counter   | `job_type="<name>"` | Jobs queued     |
-| `rippled_job_started_total`              | Counter   | `job_type="<name>"` | Jobs started    |
-| `rippled_job_finished_total`             | Counter   | `job_type="<name>"` | Jobs completed  |
-| `rippled_job_queued_duration_us_bucket`  | Histogram | `job_type="<name>"` | Queue wait time |
-| `rippled_job_running_duration_us_bucket` | Histogram | `job_type="<name>"` | Execution time  |
-
-#### Counted Object Instances (via OTel MetricsRegistry)
-
-| Prometheus Metric      | Type  | Labels          | Description                     |
-| ---------------------- | ----- | --------------- | ------------------------------- |
-| `rippled_object_count` | Gauge | `type="<name>"` | Live instances of internal type |
-
-Tracked types: `Transaction`, `Ledger`, `NodeObject`, `STTx`, `STLedgerEntry`, `InboundLedger`, `Pathfinder`, `PathRequest`, `HashRouterEntry`
-
-#### Fee Escalation & Load Factors (via OTel MetricsRegistry)
-
-| Prometheus Metric                    | Type  | Description                          |
-| ------------------------------------ | ----- | ------------------------------------ |
-| `rippled_load_factor`                | Gauge | Combined transaction cost multiplier |
-| `rippled_load_factor_server`         | Gauge | Server + cluster + network load      |
-| `rippled_load_factor_local`          | Gauge | Local server load only               |
-| `rippled_load_factor_net`            | Gauge | Network-wide load estimate           |
-| `rippled_load_factor_cluster`        | Gauge | Cluster peer load                    |
-| `rippled_load_factor_fee_escalation` | Gauge | Open ledger fee escalation           |
-| `rippled_load_factor_fee_queue`      | Gauge | Queue entry fee level                |
-
-### New Grafana Dashboards (Phase 9)
-
-| Dashboard          | UID                  | Data Source | Key Panels                                                        |
-| ------------------ | -------------------- | ----------- | ----------------------------------------------------------------- |
-| Fee Market & TxQ   | `rippled-fee-market` | Prometheus  | TxQ depth/capacity, fee levels, load factor breakdown, escalation |
-| Job Queue Analysis | `rippled-job-queue`  | Prometheus  | Per-job rates, queue wait times, execution times, queue depth     |
-
----
-
-## 5c. Future: Synthetic Workload Generation & Telemetry Validation (Phase 10)
-
-> **Plan details**: [06-implementation-phases.md §6.8.3](./06-implementation-phases.md) — motivation, architecture
-> **Task breakdown**: [Phase10_taskList.md](./Phase10_taskList.md) — per-task implementation details
-> **Tools**: [docker/telemetry/workload/](../docker/telemetry/workload/) — RPC load generator, transaction submitter, validation suite, benchmarks
-
-Phase 10 builds a 5-node validator docker-compose harness with RPC load generators, transaction submitters, and automated validation scripts that verify all spans, metrics, dashboards, and log-trace correlation work end-to-end. Includes a benchmark suite comparing telemetry-ON vs telemetry-OFF overhead.
-
-### Running the Validation Suite
-
-```bash
-# Full end-to-end validation (start cluster, generate load, validate):
-docker/telemetry/workload/run-full-validation.sh --xrpld .build/xrpld
-
-# Validation only (assumes stack and cluster are already running):
-python3 docker/telemetry/workload/validate_telemetry.py --report /tmp/report.json
-
-# Performance benchmark (baseline vs telemetry):
-docker/telemetry/workload/benchmark.sh --xrpld .build/xrpld --duration 300
-```
-
-### Validated Telemetry Inventory
-
-| Category           | Expected Count | Validation Method                | Config File             |
-| ------------------ | -------------- | -------------------------------- | ----------------------- |
-| Trace spans        | 17             | Jaeger/Tempo API query           | `expected_spans.json`   |
-| Span attributes    | 22             | Per-span attribute assertion     | `expected_spans.json`   |
-| StatsD metrics     | 255+           | Prometheus query                 | `expected_metrics.json` |
-| Phase 9 metrics    | 50+            | Prometheus query                 | `expected_metrics.json` |
-| SpanMetrics RED    | 4 per span     | Prometheus query                 | `expected_metrics.json` |
-| Grafana dashboards | 10             | Dashboard API "no data" check    | `expected_metrics.json` |
-| Log-trace links    | Present        | Loki query + Tempo reverse check | —                       |
-
-### Performance Overhead Targets
-
-| Metric            | Target       | Measurement Method                  |
-| ----------------- | ------------ | ----------------------------------- |
-| CPU overhead      | < 3%         | ps avg CPU% baseline vs telemetry   |
-| Memory overhead   | < 5MB        | ps peak RSS baseline vs telemetry   |
-| RPC p99 latency   | < 2ms impact | server_info round-trip timing       |
-| Throughput impact | < 5%         | Ledger close rate comparison        |
-| Consensus impact  | < 1%         | Consensus round time p95 comparison |
-
----
-
-## 5d. Future: Third-Party Data Collection Pipelines (Phase 11)
-
-> **Status**: Planned, not yet implemented.
-> **Plan details**: [06-implementation-phases.md §6.8.4](./06-implementation-phases.md) — motivation, architecture, consumer gap analysis
-> **Task breakdown**: [Phase11_taskList.md](./Phase11_taskList.md) — per-task implementation details
-
-Phase 11 builds a custom OTel Collector receiver (Go) that polls rippled's admin RPCs and exports `xrpl_*` metrics for external consumers. No rippled code changes.
-
-### Exported Metrics (via Custom OTel Collector Receiver)
-
-#### Node Health (from server_info)
-
-| Prometheus Metric                       | Type  | Description                                     |
-| --------------------------------------- | ----- | ----------------------------------------------- |
-| `xrpl_server_state`                     | Gauge | Operating mode (0=disconnected ... 5=proposing) |
-| `xrpl_server_state_duration_seconds`    | Gauge | Seconds in current state                        |
-| `xrpl_uptime_seconds`                   | Gauge | Consecutive seconds running                     |
-| `xrpl_io_latency_ms`                    | Gauge | I/O subsystem latency                           |
-| `xrpl_amendment_blocked`                | Gauge | 1 if amendment-blocked, 0 otherwise             |
-| `xrpl_peers_count`                      | Gauge | Connected peers                                 |
-| `xrpl_validated_ledger_seq`             | Gauge | Latest validated ledger sequence                |
-| `xrpl_validated_ledger_age_seconds`     | Gauge | Seconds since last validated close              |
-| `xrpl_last_close_proposers`             | Gauge | Proposers in last consensus round               |
-| `xrpl_last_close_converge_time_seconds` | Gauge | Last consensus round duration                   |
-| `xrpl_load_factor`                      | Gauge | Transaction cost multiplier                     |
-| `xrpl_state_duration_seconds`           | Gauge | Per-state duration (`state` label)              |
-| `xrpl_state_transitions_total`          | Gauge | Per-state transition count (`state` label)      |
-
-#### Peer Topology (from peers)
-
-| Prometheus Metric           | Type  | Description                         |
-| --------------------------- | ----- | ----------------------------------- |
-| `xrpl_peers_inbound_count`  | Gauge | Inbound peer connections            |
-| `xrpl_peers_outbound_count` | Gauge | Outbound peer connections           |
-| `xrpl_peer_latency_p50_ms`  | Gauge | Median peer latency                 |
-| `xrpl_peer_latency_p95_ms`  | Gauge | p95 peer latency                    |
-| `xrpl_peer_version_count`   | Gauge | Peers per version (`version` label) |
-| `xrpl_peer_diverged_count`  | Gauge | Peers with diverged tracking status |
-
-#### Validator & Amendment (from validators, feature)
-
-| Prometheus Metric                     | Type  | Description                             |
-| ------------------------------------- | ----- | --------------------------------------- |
-| `xrpl_trusted_validators_count`       | Gauge | UNL validator count                     |
-| `xrpl_amendment_enabled_count`        | Gauge | Enabled amendments                      |
-| `xrpl_amendment_majority_count`       | Gauge | Amendments with majority                |
-| `xrpl_amendment_unsupported_majority` | Gauge | 1 if unsupported amendment has majority |
-| `xrpl_validator_list_active`          | Gauge | 1 if validator list is active           |
-
-#### Fee Market (from fee)
-
-| Prometheus Metric                | Type  | Description                           |
-| -------------------------------- | ----- | ------------------------------------- |
-| `xrpl_fee_open_ledger_fee_drops` | Gauge | Minimum fee for open ledger inclusion |
-| `xrpl_fee_median_fee_drops`      | Gauge | Median fee level                      |
-| `xrpl_fee_queue_size`            | Gauge | Current transaction queue depth       |
-| `xrpl_fee_current_ledger_size`   | Gauge | Transactions in current open ledger   |
-
-#### DEX & AMM (optional, from book_offers, amm_info)
-
-| Prometheus Metric          | Type  | Labels                | Description            |
-| -------------------------- | ----- | --------------------- | ---------------------- |
-| `xrpl_amm_tvl_drops`       | Gauge | `pool="<id>"`         | Total value locked     |
-| `xrpl_amm_trading_fee`     | Gauge | `pool="<id>"`         | Pool trading fee (bps) |
-| `xrpl_orderbook_bid_depth` | Gauge | `pair="<base/quote>"` | Total bid volume       |
-| `xrpl_orderbook_ask_depth` | Gauge | `pair="<base/quote>"` | Total ask volume       |
-| `xrpl_orderbook_spread`    | Gauge | `pair="<base/quote>"` | Best bid-ask spread    |
-
-### Phase 9: OTel SDK-Exported Metrics (MetricsRegistry)
-
-Phase 9 introduces the `MetricsRegistry` class (`src/xrpld/telemetry/MetricsRegistry.h/.cpp`)
-which registers metrics directly with the OpenTelemetry Metrics SDK. These are exported
-via OTLP/HTTP to the OTel Collector and scraped by Prometheus.
-
-#### NodeStore I/O (Observable Gauge — `nodestore_state`)
-
-| Prometheus Metric                                      | Type  | Labels   | Description                          |
-| ------------------------------------------------------ | ----- | -------- | ------------------------------------ |
-| `rippled_nodestore_state{metric="node_reads_total"}`   | Gauge | `metric` | Cumulative NodeStore read operations |
-| `rippled_nodestore_state{metric="node_reads_hit"}`     | Gauge | `metric` | Reads served from cache              |
-| `rippled_nodestore_state{metric="node_writes"}`        | Gauge | `metric` | Cumulative write operations          |
-| `rippled_nodestore_state{metric="node_written_bytes"}` | Gauge | `metric` | Cumulative bytes written             |
-| `rippled_nodestore_state{metric="node_read_bytes"}`    | Gauge | `metric` | Cumulative bytes read                |
-| `rippled_nodestore_state{metric="write_load"}`         | Gauge | `metric` | Current write load score             |
-| `rippled_nodestore_state{metric="read_queue"}`         | Gauge | `metric` | Items in read prefetch queue         |
-
-#### Cache Hit Rates & Sizes (Observable Gauge — `cache_metrics`)
-
-| Prometheus Metric                                     | Type  | Labels   | Description                   |
-| ----------------------------------------------------- | ----- | -------- | ----------------------------- |
-| `rippled_cache_metrics{metric="SLE_hit_rate"}`        | Gauge | `metric` | SLE cache hit rate (0.0-1.0)  |
-| `rippled_cache_metrics{metric="ledger_hit_rate"}`     | Gauge | `metric` | Ledger cache hit rate         |
-| `rippled_cache_metrics{metric="AL_hit_rate"}`         | Gauge | `metric` | AcceptedLedger cache hit rate |
-| `rippled_cache_metrics{metric="treenode_cache_size"}` | Gauge | `metric` | SHAMap TreeNode cache entries |
-| `rippled_cache_metrics{metric="treenode_track_size"}` | Gauge | `metric` | Tracked tree nodes            |
-| `rippled_cache_metrics{metric="fullbelow_size"}`      | Gauge | `metric` | FullBelow cache entries       |
-
-#### Transaction Queue (Observable Gauge — `txq_metrics`)
-
-| Prometheus Metric                                            | Type  | Labels   | Description                      |
-| ------------------------------------------------------------ | ----- | -------- | -------------------------------- |
-| `rippled_txq_metrics{metric="txq_count"}`                    | Gauge | `metric` | Transactions currently in queue  |
-| `rippled_txq_metrics{metric="txq_max_size"}`                 | Gauge | `metric` | Maximum queue capacity           |
-| `rippled_txq_metrics{metric="txq_in_ledger"}`                | Gauge | `metric` | Transactions in open ledger      |
-| `rippled_txq_metrics{metric="txq_per_ledger"}`               | Gauge | `metric` | Expected transactions per ledger |
-| `rippled_txq_metrics{metric="txq_reference_fee_level"}`      | Gauge | `metric` | Reference fee level              |
-| `rippled_txq_metrics{metric="txq_min_processing_fee_level"}` | Gauge | `metric` | Minimum fee to get processed     |
-| `rippled_txq_metrics{metric="txq_med_fee_level"}`            | Gauge | `metric` | Median fee level in queue        |
-| `rippled_txq_metrics{metric="txq_open_ledger_fee_level"}`    | Gauge | `metric` | Open ledger fee escalation level |
-
-#### Per-RPC Method Metrics (Synchronous Counters/Histogram)
-
-| Prometheus Metric                   | Type      | Labels            | Description                      |
-| ----------------------------------- | --------- | ----------------- | -------------------------------- |
-| `rippled_rpc_method_started_total`  | Counter   | `method="<name>"` | RPC calls started                |
-| `rippled_rpc_method_finished_total` | Counter   | `method="<name>"` | RPC calls completed successfully |
-| `rippled_rpc_method_errored_total`  | Counter   | `method="<name>"` | RPC calls that errored           |
-| `rippled_rpc_method_duration_us`    | Histogram | `method="<name>"` | Execution time distribution (us) |
-
-#### Per-Job-Type Metrics (Synchronous Counters/Histogram)
-
-| Prometheus Metric                 | Type      | Labels              | Description                       |
-| --------------------------------- | --------- | ------------------- | --------------------------------- |
-| `rippled_job_queued_total`        | Counter   | `job_type="<name>"` | Jobs enqueued                     |
-| `rippled_job_started_total`       | Counter   | `job_type="<name>"` | Jobs started                      |
-| `rippled_job_finished_total`      | Counter   | `job_type="<name>"` | Jobs completed                    |
-| `rippled_job_queued_duration_us`  | Histogram | `job_type="<name>"` | Queue wait time distribution (us) |
-| `rippled_job_running_duration_us` | Histogram | `job_type="<name>"` | Execution time distribution (us)  |
-
-#### Counted Object Instances (Observable Gauge — `object_count`)
-
-| Prometheus Metric                              | Type  | Labels          | Description                    |
-| ---------------------------------------------- | ----- | --------------- | ------------------------------ |
-| `rippled_object_count{type="Transaction"}`     | Gauge | `type="<name>"` | Live Transaction objects       |
-| `rippled_object_count{type="Ledger"}`          | Gauge | `type="<name>"` | Live Ledger objects            |
-| `rippled_object_count{type="NodeObject"}`      | Gauge | `type="<name>"` | Live NodeObject instances      |
-| `rippled_object_count{type="STTx"}`            | Gauge | `type="<name>"` | Serialized transaction objects |
-| `rippled_object_count{type="STLedgerEntry"}`   | Gauge | `type="<name>"` | Serialized ledger entries      |
-| `rippled_object_count{type="InboundLedger"}`   | Gauge | `type="<name>"` | Ledgers being fetched          |
-| `rippled_object_count{type="Pathfinder"}`      | Gauge | `type="<name>"` | Active pathfinding operations  |
-| `rippled_object_count{type="PathRequest"}`     | Gauge | `type="<name>"` | Active path requests           |
-| `rippled_object_count{type="HashRouterEntry"}` | Gauge | `type="<name>"` | Hash router entries            |
-
-#### Load Factor Breakdown (Observable Gauge — `load_factor_metrics`)
-
-| Prometheus Metric                                                  | Type  | Labels   | Description                             |
-| ------------------------------------------------------------------ | ----- | -------- | --------------------------------------- |
-| `rippled_load_factor_metrics{metric="load_factor"}`                | Gauge | `metric` | Combined transaction cost multiplier    |
-| `rippled_load_factor_metrics{metric="load_factor_server"}`         | Gauge | `metric` | Server + cluster + network contribution |
-| `rippled_load_factor_metrics{metric="load_factor_local"}`          | Gauge | `metric` | Local server load only                  |
-| `rippled_load_factor_metrics{metric="load_factor_net"}`            | Gauge | `metric` | Network-wide load estimate              |
-| `rippled_load_factor_metrics{metric="load_factor_cluster"}`        | Gauge | `metric` | Cluster peer load                       |
-| `rippled_load_factor_metrics{metric="load_factor_fee_escalation"}` | Gauge | `metric` | Open ledger fee escalation              |
-| `rippled_load_factor_metrics{metric="load_factor_fee_queue"}`      | Gauge | `metric` | Queue entry fee level                   |
-
-#### Prometheus Query Examples (Phase 9)
-
-```promql
-# NodeStore cache hit ratio
-rippled_nodestore_state{metric="node_reads_hit"} / rippled_nodestore_state{metric="node_reads_total"}
-
-# RPC error rate for server_info
-rate(rippled_rpc_method_errored_total{method="server_info"}[5m])
-
-# Job queue wait time p95
-histogram_quantile(0.95, sum by (le) (rate(rippled_job_queued_duration_us_bucket[5m])))
-
-# TxQ utilization percentage
-rippled_txq_metrics{metric="txq_count"} / rippled_txq_metrics{metric="txq_max_size"}
-
-# High load factor alert candidate
-rippled_load_factor_metrics{metric="load_factor"} > 5
-```
-
-### New Grafana Dashboards (Phase 9)
-
-| Dashboard              | UID                  | Data Source | Key Panels                                                |
-| ---------------------- | -------------------- | ----------- | --------------------------------------------------------- |
-| Fee Market & TxQ       | `rippled-fee-market` | Prometheus  | TxQ depth/capacity, fee levels, load factor breakdown     |
-| Job Queue Analysis     | `rippled-job-queue`  | Prometheus  | Per-job rates, queue wait times, execution times          |
-| RPC Performance (OTel) | `rippled-rpc-perf`   | Prometheus  | Per-method call rates, error rates, latency distributions |
-
-### Updated Grafana Dashboards (Phase 9)
-
-| Dashboard            | UID                          | New Panels Added                                       |
-| -------------------- | ---------------------------- | ------------------------------------------------------ |
-| Node Health (StatsD) | `rippled-statsd-node-health` | NodeStore I/O, cache hit rates, object instance counts |
-
-### New Grafana Dashboards (Phase 11)
-
-| Dashboard          | UID                           | Data Source | Key Panels                                                             |
-| ------------------ | ----------------------------- | ----------- | ---------------------------------------------------------------------- |
-| Validator Health   | `rippled-validator-health`    | Prometheus  | Server state timeline, proposer count, converge time, amendment voting |
-| Network Topology   | `rippled-network-topology`    | Prometheus  | Peer count, version distribution, latency distribution, diverged peers |
-| Fee Market (Ext)   | `rippled-fee-market-external` | Prometheus  | Fee levels, queue depth, load factor breakdown, escalation timeline    |
-| DEX & AMM Overview | `rippled-dex-amm`             | Prometheus  | AMM TVL, order book depth, spread trends, trading fee revenue          |
-
-### Prometheus Alerting Rules (Phase 11)
-
-| Alert Name                         | Severity | Condition                                                   | For |
-| ---------------------------------- | -------- | ----------------------------------------------------------- | --- |
-| `XRPLServerNotFull`                | Critical | `xrpl_server_state < 4` for 15m                             | 15m |
-| `XRPLAmendmentBlocked`             | Critical | `xrpl_amendment_blocked == 1`                               | 1m  |
-| `XRPLNoPeers`                      | Critical | `xrpl_peers_count == 0`                                     | 5m  |
-| `XRPLLedgerStale`                  | Critical | `xrpl_validated_ledger_age_seconds > 120`                   | 2m  |
-| `XRPLHighIOLatency`                | Critical | `xrpl_io_latency_ms > 100`                                  | 5m  |
-| `XRPLUnsupportedAmendmentMajority` | Critical | `xrpl_amendment_unsupported_majority == 1`                  | 1m  |
-| `XRPLLowPeerCount`                 | Warning  | `xrpl_peers_count < 10`                                     | 15m |
-| `XRPLHighLoadFactor`               | Warning  | `xrpl_load_factor > 10`                                     | 10m |
-| `XRPLSlowConsensus`                | Warning  | `xrpl_last_close_converge_time_seconds > 6`                 | 5m  |
-| `XRPLValidatorListExpiring`        | Warning  | `(xrpl_validator_list_expiration_seconds - time()) < 86400` | 1h  |
-| `XRPLStateFlapping`                | Warning  | `rate(xrpl_state_transitions_total{state="full"}[1h]) > 2`  | 30m |
-
----
-
-## 6. Known Issues
-
-| Issue                                                              | Impact                                           | Status                                                               |
-| ------------------------------------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------- |
-| `warn` and `drop` metrics use non-standard StatsD `\|m` meter type | Metrics silently dropped by OTel StatsD receiver | Phase 6 Task 6.1 — needs `\|m` → `\|c` change in StatsDCollector.cpp |
-| `rippled_job_count` may not emit in standalone mode                | Missing from Prometheus in some test configs     | Requires active job queue activity                                   |
-| `rippled_rpc_requests` depends on `[insight]` config               | Zero series if StatsD not configured             | Requires `[insight] server=statsd` in xrpld.cfg                      |
-| Peer tracing disabled by default                                   | No `peer.*` spans unless `trace_peer=1`          | Intentional — high volume on mainnet                                 |
-
----
-
-## 7. Privacy and Data Collection
-
-The telemetry system is designed with privacy in mind:
-
-- **No private keys** are ever included in spans or metrics
-- **No account balances** or financial data is traced
-- **Transaction hashes** are included (public on-ledger data) but not transaction contents
-- **Peer IDs** are internal identifiers, not IP addresses
-- **All telemetry is opt-in** — disabled by default at build time (`-Dtelemetry=OFF`)
-- **Sampling** reduces data volume — `sampling_ratio=0.01` recommended for production
-- **Data stays local** — the default stack sends data to `localhost` only
-
----
-
-## 8. Configuration Quick Reference
-
-> **Full reference**: [05-configuration-reference.md](./05-configuration-reference.md) §5.1 for all `[telemetry]` options with defaults, the config parser implementation, and collector YAML configurations (dev and production).
-
-### Minimal Setup (development)
-
-```ini
-[telemetry]
-enabled=1
-
-[insight]
-server=statsd
-address=127.0.0.1:8125
-prefix=rippled
-```
-
-### Production Setup
-
-```ini
-[telemetry]
-enabled=1
-endpoint=http://otel-collector:4318/v1/traces
-sampling_ratio=0.01
-trace_peer=0
-batch_size=1024
-max_queue_size=4096
-
-[insight]
-server=statsd
-address=otel-collector:8125
-prefix=rippled
-```
-
-### Trace Category Toggle
-
-| Config Key           | Default | Controls                     |
-| -------------------- | ------- | ---------------------------- |
-| `trace_rpc`          | `1`     | `rpc.*` spans                |
-| `trace_transactions` | `1`     | `tx.*` spans                 |
-| `trace_consensus`    | `1`     | `consensus.*` spans          |
-| `trace_ledger`       | `1`     | `ledger.*` spans             |
-| `trace_peer`         | `0`     | `peer.*` spans (high volume) |

OpenTelemetryPlan/OpenTelemetryPlan.md

@@ -1,205 +0,0 @@
-# [OpenTelemetry](00-tracing-fundamentals.md) Distributed Tracing Implementation Plan for rippled (xrpld)
-
-## Executive Summary
-
-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.
-
-### Key Benefits
-
-- **End-to-end transaction visibility**: Track transactions from submission through consensus to ledger inclusion
-- **Consensus round analysis**: Understand timing and behavior of consensus phases across validators
-- **RPC performance insights**: Identify slow handlers and optimize response times
-- **Network topology understanding**: Visualize message propagation patterns between peers
-- **Incident debugging**: Correlate events across distributed nodes during issues
-
-### Estimated Performance Overhead
-
-| Metric        | Overhead   | Notes                               |
-| ------------- | ---------- | ----------------------------------- |
-| CPU           | 1-3%       | Span creation and attribute setting |
-| Memory        | 2-5 MB     | Batch buffer for pending spans      |
-| Network       | 10-50 KB/s | Compressed OTLP export to collector |
-| Latency (p99) | <2%        | With proper sampling configuration  |
-
----
-
-## Document Structure
-
-This implementation plan is organized into modular documents for easier navigation:
-
-<div align="center">
-
-```mermaid
-flowchart TB
-    overview["📋 OpenTelemetryPlan.md<br/>(This Document)"]
-
-    subgraph analysis["Analysis & Design"]
-        arch["01-architecture-analysis.md"]
-        design["02-design-decisions.md"]
-    end
-
-    subgraph impl["Implementation"]
-        strategy["03-implementation-strategy.md"]
-        code["04-code-samples.md"]
-        config["05-configuration-reference.md"]
-    end
-
-    subgraph deploy["Deployment & Planning"]
-        phases["06-implementation-phases.md"]
-        backends["07-observability-backends.md"]
-        appendix["08-appendix.md"]
-        dataref["09-data-collection-reference.md"]
-    end
-
-    overview --> analysis
-    overview --> impl
-    overview --> deploy
-
-    arch --> design
-    design --> strategy
-    strategy --> code
-    code --> config
-    config --> phases
-    phases --> backends
-    backends --> appendix
-    appendix --> dataref
-
-    style overview fill:#1b5e20,stroke:#0d3d14,color:#fff,stroke-width:2px
-    style analysis fill:#0d47a1,stroke:#082f6a,color:#fff
-    style impl fill:#bf360c,stroke:#8c2809,color:#fff
-    style deploy fill:#4a148c,stroke:#2e0d57,color:#fff
-    style arch fill:#0d47a1,stroke:#082f6a,color:#fff
-    style design fill:#0d47a1,stroke:#082f6a,color:#fff
-    style strategy fill:#bf360c,stroke:#8c2809,color:#fff
-    style code fill:#bf360c,stroke:#8c2809,color:#fff
-    style config fill:#bf360c,stroke:#8c2809,color:#fff
-    style phases fill:#4a148c,stroke:#2e0d57,color:#fff
-    style backends fill:#4a148c,stroke:#2e0d57,color:#fff
-    style appendix fill:#4a148c,stroke:#2e0d57,color:#fff
-    style dataref fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-</div>
-
----
-
-## Table of Contents
-
-| Section | Document                                                       | Description                                                            |
-| ------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| **1**   | [Architecture Analysis](./01-architecture-analysis.md)         | rippled 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)                           | Complete C++ implementation examples for all components                |
-| **5**   | [Configuration Reference](./05-configuration-reference.md)     | rippled 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                                  |
-| **9**   | [Data Collection Reference](./09-data-collection-reference.md) | Complete inventory of spans, attributes, metrics, and dashboards       |
-
----
-
-## 1. Architecture Analysis
-
-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, 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, and ledger building. 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.
-
-➡️ **[Read full Architecture Analysis](./01-architecture-analysis.md)**
-
----
-
-## 2. Design Decisions
-
-The OpenTelemetry C++ SDK is selected for its CNCF backing, active development, and native performance characteristics. Traces are exported via OTLP/gRPC (primary) or OTLP/HTTP (fallback) to an OpenTelemetry Collector, which provides flexible routing and sampling.
-
-Span naming follows a hierarchical `<component>.<operation>` convention (e.g., `rpc.submit`, `tx.relay`, `consensus.round`). Context propagation uses W3C Trace Context headers for HTTP and embedded Protocol Buffer fields for P2P messages. The implementation coexists with existing PerfLog and Insight observability systems through correlation IDs.
-
-**Data Collection & Privacy**: Telemetry collects only operational metadata (timing, counts, hashes) — never sensitive content (private keys, balances, amounts, raw payloads). Privacy protection includes account hashing, configurable redaction, sampling, and collector-level filtering. Node operators retain full control(not penned down in this document yet) over what data is exported.
-
-➡️ **[Read full Design Decisions](./02-design-decisions.md)**
-
----
-
-## 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.
-
-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.
-
-➡️ **[Read full Implementation Strategy](./03-implementation-strategy.md)**
-
----
-
-## 4. Code Samples
-
-Complete C++ implementation examples are provided for all telemetry components:
-
-- `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
-- Protocol Buffer extensions for trace context propagation
-- Module-specific instrumentation (RPC, Consensus, P2P, JobQueue)
-
-➡️ **[View all Code Samples](./04-code-samples.md)**
-
----
-
-## 5. Configuration Reference
-
-Configuration is handled through the `[telemetry]` section in `xrpld.cfg` with options for enabling/disabling, exporter selection, endpoint configuration, sampling ratios, and component-level filtering. CMake integration includes a `XRPL_ENABLE_TELEMETRY` option for compile-time control.
-
-OpenTelemetry Collector configurations are provided for development (with Jaeger) and production (with tail-based sampling, Tempo, and Elastic APM). Docker Compose examples enable quick local development environment setup.
-
-➡️ **[View full Configuration Reference](./05-configuration-reference.md)**
-
----
-
-## 6. Implementation Phases
-
-The implementation spans 13 weeks across 8 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 |
-| 8     | Week 13     | Log-Trace Correlation | trace_id in logs, Loki ingestion, Tempo↔Loki linking        |
-
-**Total Effort**: 65.1 developer-days with 2 developers
-
-➡️ **[View full Implementation Phases](./06-implementation-phases.md)**
-
----
-
-## 7. Observability Backends
-
-For development and testing, Jaeger provides easy setup with a good UI. For production deployments, Grafana Tempo is recommended for its cost-effectiveness and Grafana integration, while Elastic APM is ideal for organizations with existing Elastic infrastructure.
-
-The recommended production architecture uses a gateway collector pattern with regional collectors performing tail-based sampling, routing traces to multiple backends (Tempo for primary storage, Elastic for log correlation, S3/GCS for long-term archive).
-
-➡️ **[View Observability Backend Recommendations](./07-observability-backends.md)**
-
----
-
-## 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.
-
-➡️ **[View Appendix](./08-appendix.md)**
-
----
-
-## 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.
-
-➡️ **[View Data Collection Reference](./09-data-collection-reference.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._

OpenTelemetryPlan/POC_taskList.md

@@ -1,610 +0,0 @@
-# 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 Jaeger, viewable in a browser UI.
->
-> **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)   | Jaeger dev setup (§7.1), Grafana dashboards (§7.6), alert rules (§7.6.3)                                                                                  |
-
----
-
-## Task 0: Docker Observability Stack Setup
-
-**Objective**: Stand up the backend infrastructure to receive, store, and display traces.
-
-**What to do**:
-
-- Create `docker/telemetry/docker-compose.yml` in the repo with three services:
-  1. **OpenTelemetry Collector** (`otel/opentelemetry-collector-contrib:latest`)
-     - Expose ports `4317` (OTLP gRPC) and `4318` (OTLP HTTP)
-     - Expose port `13133` (health check)
-     - Mount a config file `docker/telemetry/otel-collector-config.yaml`
-  2. **Jaeger** (`jaegertracing/all-in-one:latest`)
-     - Expose port `16686` (UI) and `14250` (gRPC collector)
-     - Set env `COLLECTOR_OTLP_ENABLED=true`
-  3. **Grafana** (`grafana/grafana:latest`) — optional but useful
-     - Expose port `3000`
-     - Enable anonymous admin access for local dev (`GF_AUTH_ANONYMOUS_ENABLED=true`, `GF_AUTH_ANONYMOUS_ORG_ROLE=Admin`)
-     - Provision Jaeger as a data source via `docker/telemetry/grafana/provisioning/datasources/jaeger.yaml`
-
-- Create `docker/telemetry/otel-collector-config.yaml`:
-
-  ```yaml
-  receivers:
-    otlp:
-      protocols:
-        grpc:
-          endpoint: 0.0.0.0:4317
-        http:
-          endpoint: 0.0.0.0:4318
-
-  processors:
-    batch:
-      timeout: 1s
-      send_batch_size: 100
-
-  exporters:
-    logging:
-      verbosity: detailed
-    otlp/jaeger:
-      endpoint: jaeger:4317
-      tls:
-        insecure: true
-
-  service:
-    pipelines:
-      traces:
-        receivers: [otlp]
-        processors: [batch]
-        exporters: [logging, otlp/jaeger]
-  ```
-
-- Create Grafana Jaeger datasource provisioning file at `docker/telemetry/grafana/provisioning/datasources/jaeger.yaml`:
-  ```yaml
-  apiVersion: 1
-  datasources:
-    - name: Jaeger
-      type: jaeger
-      access: proxy
-      url: http://jaeger:16686
-  ```
-
-**Verification**: Run `docker compose -f docker/telemetry/docker-compose.yml up -d`, then:
-
-- `curl http://localhost:13133` returns healthy (Collector)
-- `http://localhost:16686` opens Jaeger UI (no traces yet)
-- `http://localhost:3000` opens Grafana (optional)
-
-**Reference**:
-
-- [05-configuration-reference.md §5.5](./05-configuration-reference.md) — Collector config (dev YAML with Jaeger exporter)
-- [05-configuration-reference.md §5.6](./05-configuration-reference.md) — Docker Compose development environment
-- [07-observability-backends.md §7.1](./07-observability-backends.md) — Jaeger quick start and backend selection
-- [05-configuration-reference.md §5.8](./05-configuration-reference.md) — Grafana datasource provisioning and dashboards
-
----
-
-## Task 1: Add OpenTelemetry C++ SDK Dependency
-
-**Objective**: Make `opentelemetry-cpp` available to the build system.
-
-**What to do**:
-
-- Edit `conanfile.py` to add `opentelemetry-cpp` as an **optional** dependency. The gRPC otel plugin flag (`"grpc/*:otel_plugin": False`) in the existing conanfile may need to remain false — we pull the OTel SDK separately.
-  - Add a Conan option: `with_telemetry = [True, False]` defaulting to `False`
-  - When `with_telemetry` is `True`, add `opentelemetry-cpp` to `self.requires()`
-  - Required OTel Conan components: `opentelemetry-cpp` (which bundles api, sdk, and exporters). If the package isn't in Conan Center, consider using `FetchContent` in CMake or building from source as a fallback.
-- Edit `CMakeLists.txt`:
-  - Add option: `option(XRPL_ENABLE_TELEMETRY "Enable OpenTelemetry tracing" OFF)`
-  - When ON, `find_package(opentelemetry-cpp CONFIG REQUIRED)` and add compile definition `XRPL_ENABLE_TELEMETRY`
-  - When OFF, do nothing (zero build impact)
-- Verify the build succeeds with `-DXRPL_ENABLE_TELEMETRY=OFF` (no regressions) and with `-DXRPL_ENABLE_TELEMETRY=ON` (SDK links successfully).
-
-**Key files**:
-
-- `conanfile.py`
-- `CMakeLists.txt`
-
-**Reference**:
-
-- [05-configuration-reference.md §5.4](./05-configuration-reference.md) — CMake integration, `FindOpenTelemetry.cmake`, `XRPL_ENABLE_TELEMETRY` option
-- [03-implementation-strategy.md §3.2](./03-implementation-strategy.md) — Key principle: zero-cost when disabled via compile-time flags
-- [02-design-decisions.md §2.1](./02-design-decisions.md) — SDK selection rationale and required OTel components
-
----
-
-## Task 2: Create Core Telemetry Interface and NullTelemetry
-
-**Objective**: Define the `Telemetry` abstract interface and a no-op implementation so the rest of the codebase can reference telemetry without hard-depending on the OTel SDK.
-
-**What to do**:
-
-- Create `include/xrpl/telemetry/Telemetry.h`:
-  - Define `namespace xrpl::telemetry`
-  - Define `struct Telemetry::Setup` holding: `enabled`, `exporterEndpoint`, `samplingRatio`, `serviceName`, `serviceVersion`, `serviceInstanceId`, `traceRpc`, `traceTransactions`, `traceConsensus`, `tracePeer`
-  - Define abstract `class Telemetry` with:
-    - `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<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;`
-    - `virtual bool shouldTraceTransactions() const = 0;`
-    - `virtual bool shouldTraceConsensus() const = 0;`
-  - Factory: `std::unique_ptr<Telemetry> make_Telemetry(Setup const&, beast::Journal);`
-  - 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.
-
-- Create `src/libxrpl/telemetry/NullTelemetry.cpp`:
-  - Implements `Telemetry` with all no-ops.
-  - `isEnabled()` returns `false`, `startSpan()` returns a noop span.
-  - This is used when `XRPL_ENABLE_TELEMETRY` is OFF or `enabled=0` in config.
-
-- Guard all OTel SDK headers behind `#ifdef XRPL_ENABLE_TELEMETRY`. The `NullTelemetry` implementation should compile without the OTel SDK present.
-
-**Key new files**:
-
-- `include/xrpl/telemetry/Telemetry.h`
-- `include/xrpl/telemetry/SpanGuard.h`
-- `src/libxrpl/telemetry/NullTelemetry.cpp`
-
-**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
-- [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
-
----
-
-## Task 3: Implement OTel-Backed Telemetry
-
-**Objective**: Implement the real `Telemetry` class that initializes the OTel SDK, configures the OTLP exporter and batch processor, and creates tracers/spans.
-
-**What to do**:
-
-- Create `src/libxrpl/telemetry/Telemetry.cpp` (compiled only when `XRPL_ENABLE_TELEMETRY=ON`):
-  - `class TelemetryImpl : public Telemetry` that:
-    - In `start()`: creates a `TracerProvider` with:
-      - Resource attributes: `service.name`, `service.version`, `service.instance.id`
-      - An `OtlpGrpcExporter` pointed at `setup.exporterEndpoint` (default `localhost:4317`)
-      - A `BatchSpanProcessor` with configurable batch size and delay
-      - A `TraceIdRatioBasedSampler` using `setup.samplingRatio`
-    - Sets the global `TracerProvider`
-    - In `stop()`: calls `ForceFlush()` then shuts down the provider
-    - In `startSpan()`: delegates to `getTracer()->StartSpan(name, ...)`
-    - `shouldTraceRpc()` etc. read from `Setup` fields
-
-- Create `src/libxrpl/telemetry/TelemetryConfig.cpp`:
-  - `setup_Telemetry()` parses the `[telemetry]` config section from `xrpld.cfg`
-  - Maps config keys: `enabled`, `exporter`, `endpoint`, `sampling_ratio`, `trace_rpc`, `trace_transactions`, `trace_consensus`, `trace_peer`
-
-- Wire `make_Telemetry()` factory:
-  - If `setup.enabled` is true AND `XRPL_ENABLE_TELEMETRY` is defined: return `TelemetryImpl`
-  - Otherwise: return `NullTelemetry`
-
-- Add telemetry source files to CMake. When `XRPL_ENABLE_TELEMETRY=ON`, compile `Telemetry.cpp` and `TelemetryConfig.cpp` and link against `opentelemetry-cpp::api`, `opentelemetry-cpp::sdk`, `opentelemetry-cpp::otlp_grpc_exporter`. When OFF, compile only `NullTelemetry.cpp`.
-
-**Key new files**:
-
-- `src/libxrpl/telemetry/Telemetry.cpp`
-- `src/libxrpl/telemetry/TelemetryConfig.cpp`
-
-**Key modified files**:
-
-- `CMakeLists.txt` (add telemetry library target)
-
-**Reference**:
-
-- [04-code-samples.md §4.1](./04-code-samples.md) — `Telemetry` interface that `TelemetryImpl` must implement
-- [05-configuration-reference.md §5.2](./05-configuration-reference.md) — `setup_Telemetry()` config parser implementation
-- [02-design-decisions.md §2.2](./02-design-decisions.md) — OTLP/gRPC exporter config (endpoint, TLS options)
-- [02-design-decisions.md §2.4.1](./02-design-decisions.md) — Resource attributes: `service.name`, `service.version`, `service.instance.id`, `xrpl.network.id`
-- [03-implementation-strategy.md §3.4](./03-implementation-strategy.md) — Per-operation CPU costs and overhead budget for span creation
-- [03-implementation-strategy.md §3.5](./03-implementation-strategy.md) — Memory overhead: static (~456 KB) and dynamic (~1.2 MB) budgets
-
----
-
-## Task 4: Integrate Telemetry into Application Lifecycle
-
-**Objective**: Wire the `Telemetry` object into `Application` so all components can access it.
-
-**What to do**:
-
-- Edit `src/xrpld/app/main/Application.h`:
-  - Forward-declare `namespace xrpl::telemetry { class Telemetry; }`
-  - Add pure virtual method: `virtual telemetry::Telemetry& getTelemetry() = 0;`
-
-- 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:
-    ```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"));
-    ```
-  - In `start()`: call `telemetry_->start()` early
-  - In `stop()` or destructor: call `telemetry_->stop()` late (to flush pending spans)
-  - Implement `getTelemetry()` override: return `*telemetry_`
-
-- Add `[telemetry]` section to the example config `cfg/rippled-example.cfg`:
-  ```ini
-  # [telemetry]
-  # enabled=1
-  # endpoint=localhost:4317
-  # sampling_ratio=1.0
-  # trace_rpc=1
-  ```
-
-**Key modified files**:
-
-- `src/xrpld/app/main/Application.h`
-- `src/xrpld/app/main/Application.cpp`
-- `cfg/rippled-example.cfg` (or equivalent example config)
-
-**Reference**:
-
-- [05-configuration-reference.md §5.3](./05-configuration-reference.md) — `ApplicationImp` changes: member declaration, constructor init, `start()`/`stop()` wiring, `getTelemetry()` override
-- [05-configuration-reference.md §5.1](./05-configuration-reference.md) — `[telemetry]` config section format and all option defaults
-- [03-implementation-strategy.md §3.9.2](./03-implementation-strategy.md) — File impact assessment: `Application.cpp` ~15 lines added, ~3 changed (Low risk)
-
----
-
-## Task 5: Create Instrumentation Macros
-
-**Objective**: Define convenience macros that make instrumenting code one-liners, and that compile to zero-cost no-ops when telemetry is disabled.
-
-**What to do**:
-
-- Create `src/xrpld/telemetry/TracingInstrumentation.h`:
-  - When `XRPL_ENABLE_TELEMETRY` is defined:
-
-    ```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); \
-        }
-    ```
-
-  - When `XRPL_ENABLE_TELEMETRY` is NOT defined, all macros expand to `((void)0)`
-
-**Key new file**:
-
-- `src/xrpld/telemetry/TracingInstrumentation.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
-- [03-implementation-strategy.md §3.9.7](./03-implementation-strategy.md) — Before/after code examples showing minimal intrusiveness (~1-3 lines per instrumentation point)
-
----
-
-## Task 6: Instrument RPC ServerHandler
-
-**Objective**: Add tracing to the HTTP RPC entry point so every incoming RPC request creates a span.
-
-**What to do**:
-
-- Edit `src/xrpld/rpc/detail/ServerHandler.cpp`:
-  - `#include` the `TracingInstrumentation.h` header
-  - 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);`
-  - 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);`
-  - In `ServerHandler::onWSMessage(...)` (WebSocket path):
-    - Add: `XRPL_TRACE_RPC(app_.getTelemetry(), "rpc.ws.message");`
-
-- The goal is to see spans like:
-  ```
-  rpc.request
-    └── rpc.process
-  ```
-  in Jaeger for every HTTP RPC call.
-
-**Key modified file**:
-
-- `src/xrpld/rpc/detail/ServerHandler.cpp` (~15-25 lines added)
-
-**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
-- [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.*`
-- [02-design-decisions.md §2.4.2](./02-design-decisions.md) — RPC span attributes: `xrpl.rpc.command`, `xrpl.rpc.version`, `xrpl.rpc.role`, `xrpl.rpc.params`
-- [03-implementation-strategy.md §3.9.2](./03-implementation-strategy.md) — File impact: `ServerHandler.cpp` ~40 lines added, ~10 changed (Low risk)
-
----
-
-## Task 7: Instrument RPC Command Execution
-
-**Objective**: Add per-command tracing inside the RPC handler so each command (e.g., `submit`, `account_info`, `server_info`) gets its own child span.
-
-**What to do**:
-
-- Edit `src/xrpld/rpc/detail/RPCHandler.cpp`:
-  - `#include` the `TracingInstrumentation.h` header
-  - In `doCommand(RPC::JsonContext& context, Json::Value& result)`:
-    - At the top: `XRPL_TRACE_RPC(context.app.getTelemetry(), "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
-
-- After this, traces in Jaeger should look like:
-  ```
-  rpc.request  (xrpl.rpc.command=account_info)
-    └── rpc.process
-          └── rpc.command.account_info  (xrpl.rpc.version=2, xrpl.rpc.role=user, xrpl.rpc.status=success)
-  ```
-
-**Key modified file**:
-
-- `src/xrpld/rpc/detail/RPCHandler.cpp` (~15-20 lines added)
-
-**Reference**:
-
-- [04-code-samples.md §4.5.3](./04-code-samples.md) — `ServerHandler::onRequest()` code sample (includes child span pattern for `rpc.command.*`)
-- [02-design-decisions.md §2.3](./02-design-decisions.md) — Span naming: `rpc.command.*` pattern with dynamic command name (e.g., `rpc.command.server_info`)
-- [02-design-decisions.md §2.4.2](./02-design-decisions.md) — RPC attribute schema: `xrpl.rpc.command`, `xrpl.rpc.version`, `xrpl.rpc.role`, `xrpl.rpc.status`
-- [01-architecture-analysis.md §1.6](./01-architecture-analysis.md) — Key trace points table: `rpc.command.*` in `RPCHandler.cpp::doCommand()` (Priority: High)
-- [02-design-decisions.md §2.6.5](./02-design-decisions.md) — Correlation with PerfLog: how `doCommand()` can link trace_id with existing PerfLog entries
-- [03-implementation-strategy.md §3.4.4](./03-implementation-strategy.md) — RPC request overhead budget: ~1.75 μs total per request
-
----
-
-## Task 8: Build, Run, and Verify End-to-End
-
-**Objective**: Prove the full pipeline works: rippled emits traces -> OTel Collector receives them -> Jaeger displays them.
-
-**What to do**:
-
-1. **Start the Docker stack**:
-
-   ```bash
-   docker compose -f docker/telemetry/docker-compose.yml up -d
-   ```
-
-   Verify Collector health: `curl http://localhost:13133`
-
-2. **Build rippled with telemetry**:
-
-   ```bash
-   # Adjust for your actual build workflow
-   conan install . --build=missing -o with_telemetry=True
-   cmake --preset default -DXRPL_ENABLE_TELEMETRY=ON
-   cmake --build --preset default
-   ```
-
-3. **Configure rippled**:
-   Add to `rippled.cfg` (or your local test config):
-
-   ```ini
-   [telemetry]
-   enabled=1
-   endpoint=localhost:4317
-   sampling_ratio=1.0
-   trace_rpc=1
-   ```
-
-4. **Start rippled** in standalone mode:
-
-   ```bash
-   ./rippled --conf rippled.cfg -a --start
-   ```
-
-5. **Generate RPC traffic**:
-
-   ```bash
-   # server_info
-   curl -s -X POST http://localhost:5005 \
-     -H "Content-Type: application/json" \
-     -d '{"method":"server_info","params":[{}]}'
-
-   # ledger
-   curl -s -X POST http://localhost:5005 \
-     -H "Content-Type: application/json" \
-     -d '{"method":"ledger","params":[{"ledger_index":"current"}]}'
-
-   # account_info (will error in standalone, that's fine — we trace errors too)
-   curl -s -X POST http://localhost:5005 \
-     -H "Content-Type: application/json" \
-     -d '{"method":"account_info","params":[{"account":"rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"}]}'
-   ```
-
-6. **Verify in Jaeger**:
-   - Open `http://localhost:16686`
-   - Select service `rippled` from the dropdown
-   - Click "Find Traces"
-   - 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
-
-**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 Jaeger UI under service "rippled"
-- [ ] 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
-- [ ] Building with `XRPL_ENABLE_TELEMETRY=OFF` produces no regressions
-- [ ] Setting `enabled=0` at runtime produces no traces and no errors
-
-**Reference**:
-
-- [06-implementation-phases.md §6.11.1](./06-implementation-phases.md) — Phase 1 definition of done: SDK compiles, runtime toggle works, span creation verified in Jaeger, config validation passes
-- [06-implementation-phases.md §6.11.2](./06-implementation-phases.md) — Phase 2 definition of done: 100% RPC coverage, traceparent propagation, <1ms p99 overhead, dashboard deployed
-- [06-implementation-phases.md §6.8](./06-implementation-phases.md) — Success metrics: trace coverage >95%, CPU overhead <3%, memory <5 MB, latency impact <2%
-- [03-implementation-strategy.md §3.9.5](./03-implementation-strategy.md) — Backward compatibility: config optional, protocol unchanged, `XRPL_ENABLE_TELEMETRY=OFF` produces identical binary
-- [01-architecture-analysis.md §1.8](./01-architecture-analysis.md) — Observable outcomes: what traces, metrics, and dashboards to expect
-
----
-
-## Task 9: Document POC Results and Next Steps
-
-**Objective**: Capture findings, screenshots, and remaining work for the team.
-
-**What to do**:
-
-- Take screenshots of Jaeger showing:
-  - The service list with "rippled"
-  - 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
-  - **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)
-  - [Phase 3](./06-implementation-phases.md): [Protobuf `TraceContext` message](./04-code-samples.md) (§4.4), [transaction relay tracing](./04-code-samples.md) (§4.5.1) across nodes
-  - [Phase 4](./06-implementation-phases.md): [Consensus round and phase tracing](./04-code-samples.md) (§4.5.2)
-  - [Phase 5](./06-implementation-phases.md): [Production collector config](./05-configuration-reference.md) (§5.5.2), [Grafana dashboards](./07-observability-backends.md) (§7.6), [alerting](./07-observability-backends.md) (§7.6.3)
-
-**Reference**:
-
-- [06-implementation-phases.md §6.1](./06-implementation-phases.md) — Full 5-phase timeline overview and Gantt chart
-- [06-implementation-phases.md §6.10](./06-implementation-phases.md) — Crawl-Walk-Run strategy: POC is the CRAWL phase, next steps are WALK and RUN
-- [06-implementation-phases.md §6.12](./06-implementation-phases.md) — Recommended implementation order (14 steps across 9 weeks)
-- [03-implementation-strategy.md §3.9](./03-implementation-strategy.md) — Code intrusiveness assessment and risk matrix for each remaining component
-- [07-observability-backends.md §7.2](./07-observability-backends.md) — Production backend selection (Tempo, Elastic APM, Honeycomb, Datadog)
-- [02-design-decisions.md §2.5](./02-design-decisions.md) — Context propagation design: W3C HTTP headers, protobuf P2P, JobQueue internal
-- [00-tracing-fundamentals.md](./00-tracing-fundamentals.md) — Reference for team onboarding on distributed tracing concepts
-
----
-
-## Summary
-
-| Task | Description                          | New Files | Modified Files | Depends On |
-| ---- | ------------------------------------ | --------- | -------------- | ---------- |
-| 0    | Docker observability stack           | 4         | 0              | —          |
-| 1    | OTel C++ SDK dependency              | 0         | 2              | —          |
-| 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          |
-| 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        |
-| 9    | Document results and next steps      | 1         | 0              | 8          |
-
-**Parallel work**: Tasks 0 and 1 can run in parallel. Tasks 2 and 5 have no dependency on each other. Tasks 6 and 7 can be done in parallel once Tasks 4 and 5 are complete.
-
----
-
-## Next Steps (Post-POC)
-
-### Metrics Pipeline for Grafana Dashboards
-
-The current POC exports **traces only**. Grafana's Explore view can query Jaeger for individual traces, but time-series charts (latency histograms, request throughput, error rates) require a **metrics pipeline**. To enable this:
-
-1. **Add a `spanmetrics` connector** to the OTel Collector config that derives RED metrics (Rate, Errors, Duration) from trace spans automatically:
-
-   ```yaml
-   connectors:
-     spanmetrics:
-       histogram:
-         explicit:
-           buckets: [1ms, 5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 5s]
-       dimensions:
-         - name: xrpl.rpc.command
-         - name: xrpl.rpc.status
-
-   exporters:
-     prometheus:
-       endpoint: 0.0.0.0:8889
-
-   service:
-     pipelines:
-       traces:
-         receivers: [otlp]
-         processors: [batch]
-         exporters: [debug, otlp/jaeger, spanmetrics]
-       metrics:
-         receivers: [spanmetrics]
-         exporters: [prometheus]
-   ```
-
-2. **Add Prometheus** to the Docker Compose stack to scrape the collector's metrics endpoint.
-
-3. **Add Prometheus as a Grafana datasource** and build dashboards for:
-   - RPC request latency (p50/p95/p99) by command
-   - RPC throughput (requests/sec) by command
-   - Error rate by command
-   - Span duration distribution
-
-### Additional Instrumentation
-
-- **W3C `traceparent` header extraction** in `ServerHandler` to support cross-service context propagation from external callers
-- **WebSocket RPC tracing** in `ServerHandler::onWSMessage()`
-- **Transaction relay tracing** across nodes using protobuf `TraceContext` messages
-- **Consensus round and phase tracing** for validator coordination visibility
-- **Ledger close tracing** to measure close-to-validated latency
-
-### Production Hardening
-
-- **Tail-based sampling** in the OTel Collector to reduce volume while retaining error/slow traces
-- **TLS configuration** for the OTLP exporter in production deployments
-- **Resource limits** on the batch processor queue to prevent unbounded memory growth
-- **Health monitoring** for the telemetry pipeline itself (collector lag, export failures)
-
-### POC Lessons Learned
-
-Issues encountered during POC implementation that inform future work:
-
-| Issue                                                                                              | Resolution                                                                    | Impact on Future Work                                            |
-| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| Conan lockfile rejected `opentelemetry-cpp/1.18.0`                                                 | Used `--lockfile=""` to bypass                                                | Lockfile must be regenerated when adding new dependencies        |
-| 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                      |
-| `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/Phase10_taskList.md

@@ -1,256 +0,0 @@
-# Phase 10: Synthetic Workload Generation & Telemetry Validation — Task List
-
-> **Status**: Future Enhancement
->
-> **Goal**: Build tools that generate realistic XRPL traffic to validate the full Phases 1-9 telemetry stack end-to-end — all spans, attributes, metrics, dashboards, and log-trace correlation — under controlled load.
->
-> **Scope**: Python/shell test harness + multi-node docker-compose environment + automated validation scripts + performance benchmarks.
->
-> **Branch**: `pratik/otel-phase10-workload-validation` (from `pratik/otel-phase9-metric-gap-fill`)
->
-> **Depends on**: Phase 9 (internal metric gap fill) — validates the full metric surface
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 10 plan: motivation, architecture, exit criteria (§6.8.3) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Defines the full inventory of spans/metrics to validate         |
-| [Phase9_taskList.md](./Phase9_taskList.md)                           | Prerequisite — all internal metrics must be emitting            |
-
-### Why This Phase Exists
-
-Before Phases 1-9 can be considered production-ready, we need proof that:
-
-1. All 16 spans fire with correct attributes under real transaction workloads
-2. All 255+ StatsD metrics + ~50 Phase 9 metrics appear in Prometheus with non-zero values
-3. Log-trace correlation (Phase 8) produces clickable trace_id links in Loki
-4. All 10 Grafana dashboards render meaningful data (no empty panels)
-5. Performance overhead stays within bounds (< 3% CPU, < 5MB memory)
-6. The telemetry stack survives sustained load without data loss or queue backpressure
-
----
-
-## Task 10.1: Multi-Node Test Harness
-
-**Objective**: Create a docker-compose environment with 3-5 validator nodes that produces real consensus rounds.
-
-**What to do**:
-
-- Create `docker/telemetry/docker-compose.workload.yaml`:
-  - 5 rippled validator nodes with UNL configured for each other
-  - All telemetry enabled: `[telemetry] enabled=1`, `[insight] server=otel`
-  - Full OTel stack: Collector, Jaeger, Tempo, Prometheus, Loki, Grafana
-  - Shared network with service discovery
-
-- Each node should:
-  - Generate validator keys at startup
-  - Configure all 5 nodes in its UNL
-  - Enable all trace categories including `trace_peer=1`
-  - Write logs to a file tailed by the OTel Collector filelog receiver
-
-- Include a `Makefile` target: `make telemetry-workload-up` / `make telemetry-workload-down`
-
-**Key files**:
-
-- New: `docker/telemetry/docker-compose.workload.yaml`
-- New: `docker/telemetry/workload/generate-validator-keys.sh`
-- New: `docker/telemetry/workload/xrpld-validator.cfg.template`
-
----
-
-## Task 10.2: RPC Load Generator
-
-**Objective**: Configurable tool that fires all traced RPC commands at controlled rates.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/rpc_load_generator.py`:
-  - Connects to one or more rippled WebSocket endpoints
-  - Fires all RPC commands that have trace spans: `server_info`, `ledger`, `tx`, `account_info`, `account_lines`, `fee`, `submit`, etc.
-  - Configurable parameters: rate (RPS), duration, command distribution weights
-  - Injects `traceparent` HTTP headers to test W3C context propagation
-  - Logs progress and errors to stdout
-
-- Command distribution should match realistic production ratios:
-  - 40% `server_info` / `fee` (health checks)
-  - 30% `account_info` / `account_lines` / `account_objects` (wallet queries)
-  - 15% `ledger` / `ledger_data` (explorer queries)
-  - 10% `tx` / `account_tx` (transaction lookups)
-  - 5% `book_offers` / `amm_info` (DEX queries)
-
-**Key files**:
-
-- New: `docker/telemetry/workload/rpc_load_generator.py`
-- New: `docker/telemetry/workload/requirements.txt`
-
----
-
-## Task 10.3: Transaction Submitter
-
-**Objective**: Generate diverse transaction types to exercise `tx.*` and `ledger.*` spans.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/tx_submitter.py`:
-  - Pre-funds test accounts from genesis account
-  - Submits a mix of transaction types:
-    - `Payment` (XRP and issued currencies) — exercises `tx.process`, `tx.apply`
-    - `OfferCreate` / `OfferCancel` — DEX activity
-    - `TrustSet` — trust line creation for issued currencies
-    - `NFTokenMint` / `NFTokenCreateOffer` / `NFTokenAcceptOffer` — NFT activity
-    - `EscrowCreate` / `EscrowFinish` — escrow lifecycle
-    - `AMMCreate` / `AMMDeposit` / `AMMWithdraw` — AMM pool operations (if amendment enabled)
-  - Configurable: TPS target, transaction mix weights, duration
-  - Monitors submission results and tracks success/failure rates
-
-- The transaction mix ensures the telemetry captures the full range of ledger activity that third parties care about.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/tx_submitter.py`
-- New: `docker/telemetry/workload/test_accounts.json` (pre-generated keypairs)
-
----
-
-## Task 10.4: Telemetry Validation Suite
-
-**Objective**: Automated scripts that verify all expected telemetry data exists after a workload run.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/validate_telemetry.py`:
-
-  **Span validation** (queries Jaeger/Tempo API):
-  - Assert all 16 span names appear in traces
-  - Assert each span has its required attributes (22 total attributes across spans)
-  - Assert parent-child relationships are correct (`rpc.request` → `rpc.process` → `rpc.command.*`)
-  - Assert span durations are reasonable (> 0, < 60s)
-
-  **Metric validation** (queries Prometheus API):
-  - Assert all SpanMetrics-derived metrics are non-zero: `traces_span_metrics_calls_total`, `traces_span_metrics_duration_milliseconds_bucket`
-  - Assert all StatsD metrics are non-zero: `rippled_LedgerMaster_Validated_Ledger_Age`, `rippled_Peer_Finder_Active_*`, etc.
-  - Assert all Phase 9 metrics are non-zero: `rippled_nodestore_*`, `rippled_cache_*`, `rippled_txq_*`, `rippled_rpc_method_*`, `rippled_object_count`, `rippled_load_factor*`
-  - Assert metric label cardinality is within bounds
-
-  **Log-trace correlation validation** (queries Loki API):
-  - Assert logs contain `trace_id=` and `span_id=` fields
-  - Pick a random trace_id from Jaeger → query Loki for matching logs → assert results exist
-  - Assert Grafana derived field links are functional
-
-  **Dashboard validation**:
-  - For each of the 10 Grafana dashboards, query the dashboard API and assert no panels show "No data"
-
-- Output: JSON report with pass/fail per check, suitable for CI.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/validate_telemetry.py`
-- New: `docker/telemetry/workload/expected_spans.json` (span inventory for validation)
-- New: `docker/telemetry/workload/expected_metrics.json` (metric inventory for validation)
-
----
-
-## Task 10.5: Performance Benchmark Suite
-
-**Objective**: Measure CPU/memory/latency overhead of the telemetry stack.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/benchmark.sh`:
-  - **Baseline run**: Start cluster with `[telemetry] enabled=0`, run transaction workload for 5 minutes, record metrics
-  - **Telemetry run**: Start cluster with full telemetry enabled, run identical workload, record metrics
-  - **Comparison**: Calculate deltas for:
-    - CPU usage (per-node average)
-    - Memory RSS (per-node peak)
-    - RPC p99 latency
-    - Transaction throughput (TPS)
-    - Consensus round time p95
-    - Ledger close time p95
-
-- Output: Markdown table comparing baseline vs. telemetry, with pass/fail against targets:
-  - CPU overhead < 3%
-  - Memory overhead < 5MB
-  - RPC latency impact < 2ms p99
-  - Throughput impact < 5%
-  - Consensus impact < 1%
-
-- Store results in `docker/telemetry/workload/benchmark-results/` for historical tracking.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/benchmark.sh`
-- New: `docker/telemetry/workload/collect_system_metrics.sh`
-
----
-
-## Task 10.6: CI Integration
-
-**Objective**: Wire the validation suite into CI for regression detection.
-
-**What to do**:
-
-- Create a CI workflow (GitHub Actions or equivalent) that:
-  1. Builds rippled with `-DXRPL_ENABLE_TELEMETRY=ON`
-  2. Starts the multi-node workload harness
-  3. Runs the RPC load generator + transaction submitter for 2 minutes
-  4. Runs the validation suite
-  5. Runs the benchmark suite
-  6. Fails the build if any validation check fails or benchmark exceeds thresholds
-  7. Archives the validation report and benchmark results as artifacts
-
-- This should be a separate workflow (not part of the main CI), triggered manually or on telemetry-related branch changes.
-
-**Key files**:
-
-- New: `.github/workflows/telemetry-validation.yml`
-- New: `docker/telemetry/workload/run-full-validation.sh` (orchestrator script)
-
----
-
-## Task 10.7: Documentation
-
-**Objective**: Document the workload tools and validation process.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/README.md`:
-  - Quick start guide for running workload harness
-  - Configuration options for load generator and tx submitter
-  - How to read validation reports
-  - How to run benchmarks and interpret results
-
-- Update `docs/telemetry-runbook.md`:
-  - Add "Validating Telemetry Stack" section
-  - Add "Performance Benchmarking" section
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add "Validation" section with expected metric/span counts
-
----
-
-## Effort Summary
-
-| Task | Description                 | Effort | Risk   |
-| ---- | --------------------------- | ------ | ------ |
-| 10.1 | Multi-node test harness     | 2d     | Medium |
-| 10.2 | RPC load generator          | 1d     | Low    |
-| 10.3 | Transaction submitter       | 2d     | Medium |
-| 10.4 | Telemetry validation suite  | 2d     | Medium |
-| 10.5 | Performance benchmark suite | 1.5d   | Low    |
-| 10.6 | CI integration              | 1d     | Medium |
-| 10.7 | Documentation               | 0.5d   | Low    |
-
-**Total Effort**: 10 days
-
-## Exit Criteria
-
-- [ ] 5-node validator cluster starts and reaches consensus in docker-compose
-- [ ] RPC load generator fires all traced RPC commands at configurable rates
-- [ ] Transaction submitter generates 6+ transaction types at configurable TPS
-- [ ] Validation suite confirms all 16 spans, 22 attributes, 300+ metrics are present
-- [ ] Log-trace correlation validated end-to-end (Loki ↔ Tempo)
-- [ ] All 10 Grafana dashboards render data (no empty panels)
-- [ ] Benchmark shows < 3% CPU overhead, < 5MB memory overhead
-- [ ] CI workflow runs validation on telemetry branch changes
-- [ ] Validation report output is CI-parseable (JSON with exit codes)

OpenTelemetryPlan/Phase11_taskList.md

@@ -1,471 +0,0 @@
-# Phase 11: Third-Party Data Collection Pipelines — Task List
-
-> **Status**: Future Enhancement
->
-> **Goal**: Build a custom OTel Collector receiver that periodically polls rippled's admin RPCs and exports structured metrics for external consumers — making all XRPL health, validator, peer, fee, and DEX data available as Prometheus/OTLP metrics without rippled code changes.
->
-> **Scope**: Go-based OTel Collector receiver plugin + Grafana dashboards + Prometheus alerting rules.
->
-> **Branch**: `pratik/otel-phase11-third-party-collection` (from `pratik/otel-phase10-workload-validation`)
->
-> **Depends on**: Phase 10 (validation harness for testing the new receiver)
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 11 plan: motivation, architecture, exit criteria (§6.8.4) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Defines full metric inventory including third-party metrics     |
-| [Phase10_taskList.md](./Phase10_taskList.md)                         | Prerequisite — validation harness for testing                   |
-
-### Third-Party Consumer Gap Analysis
-
-This phase addresses the cross-cutting gap identified during research: **rippled has no native Prometheus/OTLP metrics export for data accessible only via RPC**. Every consumer (exchanges, payment processors, analytics providers, validators, researchers, compliance firms, custodians) must build custom JSON-RPC polling and conversion. This receiver centralizes that work.
-
-| Consumer Category          | Data Unlocked by This Phase                                        |
-| -------------------------- | ------------------------------------------------------------------ |
-| **Exchanges**              | Real-time fee estimates, TxQ capacity, server health scores        |
-| **Payment Processors**     | Settlement latency percentiles, corridor health, path availability |
-| **Analytics Providers**    | Validator metrics, network topology, amendment voting status       |
-| **DeFi / AMM**             | AMM pool TVL, DEX order book depth, trade volumes                  |
-| **Validators / Operators** | Per-peer latency, version distribution, UNL health, alerting       |
-| **Compliance**             | Transaction volume trends, network growth metrics                  |
-| **Academic Researchers**   | Consensus performance time-series, decentralization metrics        |
-| **CBDC / Tokenization**    | Token supply tracking, trust line adoption, freeze status          |
-| **Institutional Custody**  | Multi-sig status, escrow tracking, reserve calculations            |
-| **Wallet Providers**       | Server health for node selection, fee prediction data              |
-
----
-
-## Task 11.1: OTel Collector Receiver Scaffold
-
-**Objective**: Create the Go project structure for a custom OTel Collector receiver that polls rippled JSON-RPC.
-
-**What to do**:
-
-- Create `docker/telemetry/otel-rippled-receiver/`:
-  - `receiver.go` — implements `receiver.Metrics` interface
-  - `config.go` — configuration struct (endpoint, poll interval, enabled RPCs)
-  - `factory.go` — receiver factory registration
-  - `go.mod` / `go.sum` — Go module with OTel Collector SDK dependency
-
-- Configuration model:
-
-  ```yaml
-  rippled_receiver:
-    endpoint: "http://localhost:5005" # rippled admin RPC
-    poll_interval: 30s # how often to poll
-    enabled_collectors:
-      - server_info
-      - get_counts
-      - fee
-      - peers
-      - validators
-      - feature
-      - server_state
-    amm_pools: [] # optional: AMM pool IDs to track
-    book_offers_pairs: [] # optional: currency pairs for DEX depth
-  ```
-
-- Build a custom OTel Collector binary that includes this receiver alongside the standard receivers.
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/receiver.go`
-- New: `docker/telemetry/otel-rippled-receiver/config.go`
-- New: `docker/telemetry/otel-rippled-receiver/factory.go`
-- New: `docker/telemetry/otel-rippled-receiver/go.mod`
-- New: `docker/telemetry/otel-rippled-receiver/Dockerfile`
-
----
-
-## Task 11.2: server_info / server_state Collector
-
-**Objective**: Poll `server_info` and `server_state` and export all fields as OTel metrics.
-
-**What to do**:
-
-- Implement `serverInfoCollector` that calls `server_info` (admin) and extracts:
-
-  **Node Health Gauges:**
-  - `xrpl_server_state` (enum → int: disconnected=0, connected=1, syncing=2, tracking=3, full=4, proposing=5)
-  - `xrpl_server_state_duration_seconds`
-  - `xrpl_uptime_seconds`
-  - `xrpl_io_latency_ms`
-  - `xrpl_amendment_blocked` (0 or 1)
-  - `xrpl_peers_count`
-  - `xrpl_peer_disconnects_total`
-  - `xrpl_peer_disconnects_resources_total`
-  - `xrpl_jq_trans_overflow_total`
-
-  **Consensus Gauges:**
-  - `xrpl_last_close_proposers`
-  - `xrpl_last_close_converge_time_seconds`
-  - `xrpl_validation_quorum`
-
-  **Ledger Gauges:**
-  - `xrpl_validated_ledger_seq`
-  - `xrpl_validated_ledger_age_seconds`
-  - `xrpl_validated_ledger_base_fee_drops`
-  - `xrpl_validated_ledger_reserve_base_drops`
-  - `xrpl_validated_ledger_reserve_inc_drops`
-  - `xrpl_close_time_offset_seconds` (0 when absent)
-
-  **Load Factor Gauges:**
-  - `xrpl_load_factor`
-  - `xrpl_load_factor_server`
-  - `xrpl_load_factor_fee_escalation`
-  - `xrpl_load_factor_fee_queue`
-  - `xrpl_load_factor_local`
-  - `xrpl_load_factor_net`
-  - `xrpl_load_factor_cluster`
-
-  **State Accounting Gauges** (per state: disconnected, connected, syncing, tracking, full):
-  - `xrpl_state_duration_seconds{state="<name>"}`
-  - `xrpl_state_transitions_total{state="<name>"}`
-
-  **Validator Info** (when node is a validator):
-  - `xrpl_validator_list_count`
-  - `xrpl_validator_list_expiration_seconds` (epoch)
-  - `xrpl_validator_list_active` (0 or 1)
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/server_info.go`
-
----
-
-## Task 11.3: get_counts Collector
-
-**Objective**: Poll `get_counts` and export internal object counts and NodeStore stats.
-
-**What to do**:
-
-- Implement `getCountsCollector`:
-
-  **Database Gauges:**
-  - `xrpl_db_size_kb{db="total"}`, `xrpl_db_size_kb{db="ledger"}`, `xrpl_db_size_kb{db="transaction"}`
-
-  **NodeStore Gauges:**
-  - `xrpl_nodestore_reads_total`, `xrpl_nodestore_reads_hit`, `xrpl_nodestore_writes_total`
-  - `xrpl_nodestore_read_bytes`, `xrpl_nodestore_written_bytes`
-  - `xrpl_nodestore_read_duration_us`, `xrpl_nodestore_write_load`
-  - `xrpl_nodestore_read_queue`, `xrpl_nodestore_read_threads_running`
-
-  **Cache Gauges:**
-  - `xrpl_cache_hit_rate{cache="SLE"}`, `xrpl_cache_hit_rate{cache="ledger"}`, `xrpl_cache_hit_rate{cache="accepted_ledger"}`
-  - `xrpl_cache_size{cache="treenode"}`, `xrpl_cache_size{cache="fullbelow"}`, `xrpl_cache_size{cache="accepted_ledger"}`
-
-  **Object Count Gauges:**
-  - `xrpl_object_count{type="<name>"}` for each counted object type (Transaction, Ledger, NodeObject, STTx, STLedgerEntry, InboundLedger, Pathfinder, etc.)
-
-  **Rates:**
-  - `xrpl_historical_fetch_per_minute`
-  - `xrpl_local_txs`
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/get_counts.go`
-
----
-
-## Task 11.4: Peer Topology Collector
-
-**Objective**: Poll `peers` and export per-peer and aggregate network metrics.
-
-**What to do**:
-
-- Implement `peersCollector`:
-
-  **Aggregate Gauges:**
-  - `xrpl_peers_inbound_count`
-  - `xrpl_peers_outbound_count`
-  - `xrpl_peers_cluster_count`
-
-  **Per-Peer Gauges** (with labels `peer_key` truncated to 8 chars for cardinality control):
-  - `xrpl_peer_latency_ms{peer="<key>", version="<ver>", inbound="<bool>"}`
-  - `xrpl_peer_uptime_seconds{peer="<key>"}`
-  - `xrpl_peer_load{peer="<key>"}`
-
-  **Distribution Gauges** (aggregated across all peers):
-  - `xrpl_peer_latency_p50_ms`, `xrpl_peer_latency_p95_ms`, `xrpl_peer_latency_p99_ms`
-  - `xrpl_peer_version_count{version="<semver>"}` — count of peers per software version
-
-  **Tracking Status:**
-  - `xrpl_peer_diverged_count` — peers with `track=diverged`
-  - `xrpl_peer_unknown_count` — peers with `track=unknown`
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/peers.go`
-
-**Cardinality note**: Per-peer metrics use truncated keys. For large peer sets (50+), the aggregate distribution gauges are preferred over per-peer labels.
-
----
-
-## Task 11.5: Validator & Amendment Collector
-
-**Objective**: Poll `validators` and `feature` to export validator health and amendment voting status.
-
-**What to do**:
-
-- Implement `validatorCollector`:
-
-  **From `validators` RPC:**
-  - `xrpl_trusted_validators_count`
-  - `xrpl_validator_signing` (0 or 1 — whether local validator is signing)
-
-  **From `feature` RPC:**
-  - `xrpl_amendment_enabled_count` — total enabled amendments
-  - `xrpl_amendment_majority_count` — amendments with majority but not yet enabled
-  - `xrpl_amendment_vetoed_count` — locally vetoed amendments
-  - `xrpl_amendment_unsupported_majority` (0 or 1) — any unsupported amendment has majority (critical alert)
-
-  **Per-amendment with majority** (limited cardinality — only amendments with `majority` set):
-  - `xrpl_amendment_majority_time{name="<amendment>"}` — epoch time when majority was gained
-  - `xrpl_amendment_votes{name="<amendment>"}` — current vote count
-  - `xrpl_amendment_threshold{name="<amendment>"}` — votes needed
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/validators.go`
-
----
-
-## Task 11.6: Fee & TxQ Collector
-
-**Objective**: Poll `fee` RPC and export real-time fee market data.
-
-**What to do**:
-
-- Implement `feeCollector` that calls the public `fee` RPC:
-
-  **Fee Level Gauges:**
-  - `xrpl_fee_current_ledger_size` — transactions in current open ledger
-  - `xrpl_fee_expected_ledger_size` — expected transactions at close
-  - `xrpl_fee_max_queue_size` — maximum transaction queue size
-  - `xrpl_fee_open_ledger_fee_drops` — minimum fee for open ledger inclusion
-  - `xrpl_fee_median_fee_drops` — median fee level
-  - `xrpl_fee_minimum_fee_drops` — base reference fee
-  - `xrpl_fee_queue_size` — current queue depth
-
-- This overlaps with Phase 9's internal TxQ metrics but provides an external-only collection path that doesn't require rippled code changes.
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/fee.go`
-
----
-
-## Task 11.7: DEX & AMM Collector (Optional)
-
-**Objective**: Periodically poll configured AMM pools and order book pairs for DeFi metrics.
-
-**What to do**:
-
-- Implement `dexCollector` (enabled only when `amm_pools` or `book_offers_pairs` are configured):
-
-  **AMM Pool Gauges** (per configured pool):
-  - `xrpl_amm_reserve{pool="<id>", asset="<currency>"}` — pool reserve amount
-  - `xrpl_amm_lp_token_supply{pool="<id>"}` — outstanding LP tokens
-  - `xrpl_amm_trading_fee{pool="<id>"}` — pool trading fee (basis points)
-  - `xrpl_amm_tvl_drops{pool="<id>"}` — total value locked (XRP-denominated)
-
-  **Order Book Gauges** (per configured pair):
-  - `xrpl_orderbook_bid_depth{pair="<base>/<quote>"}` — total bid volume
-  - `xrpl_orderbook_ask_depth{pair="<base>/<quote>"}` — total ask volume
-  - `xrpl_orderbook_spread{pair="<base>/<quote>"}` — best bid-ask spread
-  - `xrpl_orderbook_offer_count{pair="<base>/<quote>", side="bid|ask"}` — number of offers
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/dex.go`
-
-**Note**: This is optional because it requires explicit configuration of which pools/pairs to track. Default configuration tracks no DEX data.
-
----
-
-## Task 11.8: Prometheus Alerting Rules
-
-**Objective**: Create production-ready alerting rules for the metrics exported by this receiver.
-
-**What to do**:
-
-- Create `docker/telemetry/prometheus/rippled-alerts.yml`:
-
-  **Tier 1 — Critical (page immediately):**
-
-  ```yaml
-  - alert: XRPLServerNotFull
-    expr: xrpl_server_state < 4
-    for: 15m
-
-  - alert: XRPLAmendmentBlocked
-    expr: xrpl_amendment_blocked == 1
-    for: 1m
-
-  - alert: XRPLNoPeers
-    expr: xrpl_peers_count == 0
-    for: 5m
-
-  - alert: XRPLLedgerStale
-    expr: xrpl_validated_ledger_age_seconds > 120
-    for: 2m
-
-  - alert: XRPLHighIOLatency
-    expr: xrpl_io_latency_ms > 100
-    for: 5m
-
-  - alert: XRPLUnsupportedAmendmentMajority
-    expr: xrpl_amendment_unsupported_majority == 1
-    for: 1m
-  ```
-
-  **Tier 2 — Warning (investigate within hours):**
-
-  ```yaml
-  - alert: XRPLLowPeerCount
-    expr: xrpl_peers_count < 10
-    for: 15m
-
-  - alert: XRPLHighLoadFactor
-    expr: xrpl_load_factor > 10
-    for: 10m
-
-  - alert: XRPLSlowConsensus
-    expr: xrpl_last_close_converge_time_seconds > 6
-    for: 5m
-
-  - alert: XRPLValidatorListExpiring
-    expr: (xrpl_validator_list_expiration_seconds - time()) < 86400
-    for: 1h
-
-  - alert: XRPLClockDrift
-    expr: xrpl_close_time_offset_seconds > 0
-    for: 5m
-
-  - alert: XRPLStateFlapping
-    expr: rate(xrpl_state_transitions_total{state="full"}[1h]) > 2
-    for: 30m
-  ```
-
-**Key files**:
-
-- New: `docker/telemetry/prometheus/rippled-alerts.yml`
-- Update: `docker/telemetry/prometheus/prometheus.yml` (add rule_files reference)
-
----
-
-## Task 11.9: New Grafana Dashboards
-
-**Objective**: Create 4 new dashboards for the data exported by the receiver.
-
-**What to do**:
-
-- **Validator Health** (`rippled-validator-health`):
-  - Server state timeline, state duration breakdown
-  - Proposer count trend, converge time trend, validation quorum
-  - Validator list expiration countdown
-  - Amendment voting status (majority/enabled/vetoed)
-
-- **Network Topology** (`rippled-network-topology`):
-  - Peer count (inbound/outbound/cluster), peer version distribution
-  - Peer latency distribution (p50/p95/p99), diverged peer count
-  - Geographic distribution (if enriched with GeoIP)
-  - Peer uptime distribution
-
-- **Fee Market** (`rippled-fee-market-external`):
-  - Current fee levels (open ledger, median, minimum), fee escalation timeline
-  - Queue depth vs. capacity, transactions per ledger
-  - Load factor breakdown (server/network/cluster/escalation)
-
-- **DEX & AMM Overview** (`rippled-dex-amm`) (only populated when DEX collectors are configured):
-  - AMM pool TVL, reserve ratios, LP token supply
-  - Order book depth per pair, spread trends
-  - Trading fee revenue estimates
-
-**Key files**:
-
-- New: `docker/telemetry/grafana/dashboards/rippled-validator-health.json`
-- New: `docker/telemetry/grafana/dashboards/rippled-network-topology.json`
-- New: `docker/telemetry/grafana/dashboards/rippled-fee-market-external.json`
-- New: `docker/telemetry/grafana/dashboards/rippled-dex-amm.json`
-
----
-
-## Task 11.10: Integration with Phase 10 Validation
-
-**Objective**: Extend the Phase 10 validation suite to verify this receiver's metrics.
-
-**What to do**:
-
-- Update `docker/telemetry/workload/validate_telemetry.py`:
-  - Add assertions for all `xrpl_*` metrics produced by the receiver
-  - Verify metric labels have expected values
-  - Verify alerting rules fire correctly (inject a "bad" state and check alert)
-
-- Update `docker/telemetry/docker-compose.workload.yaml`:
-  - Add the custom OTel Collector build with the rippled receiver
-  - Configure the receiver to poll one of the test nodes
-
-**Key files**:
-
-- Update: `docker/telemetry/workload/validate_telemetry.py`
-- Update: `docker/telemetry/docker-compose.workload.yaml`
-- Update: `docker/telemetry/workload/expected_metrics.json`
-
----
-
-## Task 11.11: Documentation
-
-**Objective**: Document the receiver, its metrics, deployment, and alerting.
-
-**What to do**:
-
-- Create `docker/telemetry/otel-rippled-receiver/README.md`:
-  - Architecture overview (how the receiver fits into the OTel Collector)
-  - Configuration reference (all config options with defaults)
-  - Metric reference table (all exported metrics with types and labels)
-  - Deployment guide (building custom collector binary, docker-compose integration)
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add "Third-Party Metrics (OTel Collector Receiver)" section
-  - Add new Grafana dashboard reference (4 dashboards)
-  - Add alerting rules reference
-
-- Update `docs/telemetry-runbook.md`:
-  - Add "Third-Party Metrics Receiver" troubleshooting section
-  - Add alerting playbook (what to do for each Tier 1/Tier 2 alert)
-
----
-
-## Effort Summary
-
-| Task  | Description                          | Effort | Risk   |
-| ----- | ------------------------------------ | ------ | ------ |
-| 11.1  | OTel Collector receiver scaffold     | 1.5d   | Medium |
-| 11.2  | server_info / server_state collector | 2d     | Low    |
-| 11.3  | get_counts collector                 | 1.5d   | Low    |
-| 11.4  | Peer topology collector              | 1.5d   | Medium |
-| 11.5  | Validator & amendment collector      | 1d     | Low    |
-| 11.6  | Fee & TxQ collector                  | 0.5d   | Low    |
-| 11.7  | DEX & AMM collector (optional)       | 1.5d   | Medium |
-| 11.8  | Prometheus alerting rules            | 1d     | Low    |
-| 11.9  | New Grafana dashboards (4)           | 2d     | Low    |
-| 11.10 | Integration with Phase 10 validation | 1d     | Low    |
-| 11.11 | Documentation                        | 1d     | Low    |
-
-**Total Effort**: 15 days
-
-## Exit Criteria
-
-- [ ] Custom OTel Collector receiver builds and starts without errors
-- [ ] All `xrpl_*` metrics from server_info, get_counts, peers, validators, fee appear in Prometheus
-- [ ] Metrics update at configured poll interval (default 30s)
-- [ ] 4 new Grafana dashboards operational with data
-- [ ] Prometheus alerting rules fire correctly for simulated failure conditions
-- [ ] DEX/AMM collector works when configured (optional — not required for base exit criteria)
-- [ ] Phase 10 validation suite passes with receiver metrics included
-- [ ] Receiver handles rippled restart/unavailability gracefully (no crash, logs warning, retries)
-- [ ] Documentation complete: receiver README, metric reference, alerting playbook
-- [ ] Go receiver has unit tests with >80% coverage

OpenTelemetryPlan/Phase2_taskList.md

@@ -1,220 +0,0 @@
-# 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.
->
-> **Scope**: W3C header extraction, TraceContext propagation utilities, unit tests for core telemetry, integration tests for RPC tracing, and performance benchmarks.
->
-> **Branch**: `pratik/otel-phase2-rpc-tracing` (from `pratik/OpenTelemetry_and_DistributedTracing_planning`)
-
-### Related Plan Documents
-
-| Document                                                     | Relevance                                                     |
-| ------------------------------------------------------------ | ------------------------------------------------------------- |
-| [04-code-samples.md](./04-code-samples.md)                   | TraceContextPropagator (§4.4.2), RPC instrumentation (§4.5.3) |
-| [02-design-decisions.md](./02-design-decisions.md)           | W3C Trace Context (§2.5), span attributes (§2.4.2)            |
-| [06-implementation-phases.md](./06-implementation-phases.md) | Phase 2 tasks (§6.3), definition of done (§6.11.2)            |
-
----
-
-## Task 2.1: Implement 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.
-
-**What to do**:
-
-- 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
-
----
-
-## Task 2.2: Add XRPL_TRACE_PEER Macro
-
-**Objective**: Add the missing peer-tracing macro for future Phase 3 use and ensure macro completeness.
-
-**What to do**:
-
-- 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`
-
----
-
-## Task 2.3: Add shouldTraceLedger() to Telemetry Interface
-
-**Objective**: The `Setup` struct has a `traceLedger` field but there's no corresponding virtual method. Add it for interface completeness.
-
-**What to do**:
-
-- Edit `include/xrpl/telemetry/Telemetry.h`:
-  - Add `virtual bool shouldTraceLedger() const = 0;`
-
-- Update all implementations:
-  - `src/libxrpl/telemetry/Telemetry.cpp` (TelemetryImpl, NullTelemetryOtel)
-  - `src/libxrpl/telemetry/NullTelemetry.cpp` (NullTelemetry)
-
-**Key modified files**:
-
-- `include/xrpl/telemetry/Telemetry.h`
-- `src/libxrpl/telemetry/Telemetry.cpp`
-- `src/libxrpl/telemetry/NullTelemetry.cpp`
-
----
-
-## Task 2.4: Unit Tests for Core Telemetry Infrastructure
-
-**Objective**: Add unit tests for the core telemetry abstractions to validate correctness and catch regressions.
-
-**What to do**:
-
-- 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
-
-- 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
-
-- 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)
-
----
-
-## Task 2.5: Enhance RPC Span Attributes
-
-**Objective**: Add additional attributes to RPC spans per the semantic conventions defined in the plan.
-
-**What to do**:
-
-- 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)
-
-- 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
-
----
-
-## Task 2.6: Build Verification and Performance Baseline
-
-**Objective**: Verify the build succeeds with and without telemetry, and establish a performance baseline.
-
-**What to do**:
-
-1. Build with `telemetry=ON` and verify no compilation errors
-2. Build with `telemetry=OFF` and verify no regressions
-3. Run existing unit tests to verify no breakage
-4. Document any build issues in lessons.md
-
-**Verification Checklist**:
-
-- [ ] `conan install . --build=missing -o telemetry=True` succeeds
-- [ ] `cmake --preset default -Dtelemetry=ON` configures correctly
-- [ ] Build succeeds with telemetry ON
-- [ ] Build succeeds with telemetry OFF
-- [ ] Existing tests pass with telemetry ON
-- [ ] Existing tests pass with telemetry OFF
-
----
-
-## 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    |
-
-**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.
-
----
-
-## Known Issues / Future Work
-
-### Thread safety of TelemetryImpl::stop() vs startSpan()
-
-`TelemetryImpl::stop()` resets `sdkProvider_` (a `std::shared_ptr`) without
-synchronization. `getTracer()` reads the same member from RPC handler threads.
-This is a data race if any thread calls `startSpan()` concurrently with `stop()`.
-
-**Current mitigation**: `Application::stop()` shuts down `serverHandler_`,
-`overlay_`, and `jobQueue_` before calling `telemetry_->stop()`, so no callers
-remain. See comments in `Telemetry.cpp:stop()` and `Application.cpp`.
-
-**TODO**: Add an `std::atomic<bool> stopped_` flag checked in `getTracer()` to
-make this robust against future shutdown order changes.
-
-### Macro incompatibility: XRPL_TRACE_SPAN vs XRPL_TRACE_SET_ATTR
-
-`XRPL_TRACE_SPAN` and `XRPL_TRACE_SPAN_KIND` declare `_xrpl_guard_` as a bare
-`SpanGuard`, but `XRPL_TRACE_SET_ATTR` and `XRPL_TRACE_EXCEPTION` call
-`_xrpl_guard_.has_value()` which requires `std::optional<SpanGuard>`. Using
-`XRPL_TRACE_SPAN` followed by `XRPL_TRACE_SET_ATTR` in the same scope would
-fail to compile.
-
-**Current mitigation**: No call site currently uses `XRPL_TRACE_SPAN` — all
-production code uses the conditional macros (`XRPL_TRACE_RPC`, `XRPL_TRACE_TX`,
-etc.) which correctly wrap the guard in `std::optional`.
-
-**TODO**: Either make `XRPL_TRACE_SPAN`/`XRPL_TRACE_SPAN_KIND` also wrap in
-`std::optional`, or document that `XRPL_TRACE_SET_ATTR` is only compatible with
-the conditional macros.

OpenTelemetryPlan/Phase3_taskList.md

@@ -1,263 +0,0 @@
-# Phase 3: Transaction Tracing Task List
-
-> **Goal**: Trace the full transaction lifecycle from RPC submission through peer relay, including cross-node context propagation via Protocol Buffer extensions. This is the WALK phase that demonstrates true distributed tracing.
->
-> **Scope**: Protocol Buffer `TraceContext` message, context serialization, PeerImp transaction instrumentation, NetworkOPs processing instrumentation, HashRouter visibility, and multi-node relay context propagation.
->
-> **Branch**: `pratik/otel-phase3-tx-tracing` (from `pratik/otel-phase2-rpc-tracing`)
-
-### Related Plan Documents
-
-| Document                                                     | Relevance                                                                                        |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
-| [04-code-samples.md](./04-code-samples.md)                   | TraceContext protobuf (§4.4.1), PeerImp instrumentation (§4.5.1), context serialization (§4.4.2) |
-| [01-architecture-analysis.md](./01-architecture-analysis.md) | Transaction flow (§1.3), key trace points (§1.6)                                                 |
-| [06-implementation-phases.md](./06-implementation-phases.md) | Phase 3 tasks (§6.4), definition of done (§6.11.3)                                               |
-| [02-design-decisions.md](./02-design-decisions.md)           | Context propagation design (§2.5), attribute schema (§2.4.3)                                     |
-
----
-
-## Task 3.1: Define TraceContext Protocol Buffer Message
-
-**Objective**: Add trace context fields to the P2P protocol messages so trace IDs can propagate across nodes.
-
-**What to do**:
-
-- Edit `include/xrpl/proto/xrpl.proto` (or `src/ripple/proto/ripple.proto`, wherever the proto is):
-  - Add `TraceContext` message definition:
-    ```protobuf
-    message TraceContext {
-        bytes trace_id = 1;      // 16-byte trace identifier
-        bytes span_id = 2;       // 8-byte span identifier
-        uint32 trace_flags = 3;  // bit 0 = sampled
-        string trace_state = 4;  // W3C tracestate value
-    }
-    ```
-  - Add `optional TraceContext trace_context = 1001;` to:
-    - `TMTransaction`
-    - `TMProposeSet` (for Phase 4 use)
-    - `TMValidation` (for Phase 4 use)
-  - Use high field numbers (1001+) to avoid conflicts with existing fields
-
-- Regenerate protobuf C++ code
-
-**Key modified files**:
-
-- `include/xrpl/proto/xrpl.proto` (or equivalent)
-
-**Reference**:
-
-- [04-code-samples.md §4.4.1](./04-code-samples.md) — TraceContext message definition
-- [02-design-decisions.md §2.5.2](./02-design-decisions.md) — Protocol buffer context propagation design
-
----
-
-## Task 3.2: Implement Protobuf Context Serialization
-
-**Objective**: Create utilities to serialize/deserialize OTel trace context to/from protobuf `TraceContext` messages.
-
-**What to do**:
-
-- Create `include/xrpl/telemetry/TraceContextPropagator.h` (extend from Phase 2 if exists, or add protobuf methods):
-  - Add protobuf-specific methods:
-    - `static Context extractFromProtobuf(protocol::TraceContext const& proto)` — reconstruct OTel context from protobuf fields
-    - `static void injectToProtobuf(Context const& ctx, protocol::TraceContext& proto)` — serialize current span context into protobuf fields
-  - Both methods guard behind `#ifdef XRPL_ENABLE_TELEMETRY`
-
-- Create/extend `src/libxrpl/telemetry/TraceContextPropagator.cpp`:
-  - Implement extraction: read trace_id (16 bytes), span_id (8 bytes), trace_flags from protobuf, construct `SpanContext`, wrap in `Context`
-  - Implement injection: get current span from context, serialize its TraceId, SpanId, and TraceFlags into protobuf fields
-
-**Key new/modified files**:
-
-- `include/xrpl/telemetry/TraceContextPropagator.h`
-- `src/libxrpl/telemetry/TraceContextPropagator.cpp`
-
-**Reference**:
-
-- [04-code-samples.md §4.4.2](./04-code-samples.md) — Full extract/inject implementation
-
----
-
-## Task 3.3: Instrument PeerImp Transaction Handling
-
-**Objective**: Add trace spans to the peer-level transaction receive and relay path.
-
-**What to do**:
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp`:
-  - In `onMessage(TMTransaction)` / `handleTransaction()`:
-    - Extract parent trace context from incoming `TMTransaction::trace_context` field (if present)
-    - Create `tx.receive` span as child of extracted context (or new root if none)
-    - Set attributes: `xrpl.tx.hash`, `xrpl.peer.id`, `xrpl.tx.status`
-    - On HashRouter suppression (duplicate): set `xrpl.tx.suppressed=true`, add `tx.duplicate` event
-    - Wrap validation call with child span `tx.validate`
-    - Wrap relay with `tx.relay` span
-  - When relaying to peers:
-    - Inject current trace context into outgoing `TMTransaction::trace_context`
-    - Set `xrpl.tx.relay_count` attribute
-
-- Include `TracingInstrumentation.h` and use `XRPL_TRACE_TX` macro
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-
-**Reference**:
-
-- [04-code-samples.md §4.5.1](./04-code-samples.md) — Full PeerImp instrumentation example
-- [01-architecture-analysis.md §1.3](./01-architecture-analysis.md) — Transaction flow diagram
-- [01-architecture-analysis.md §1.6](./01-architecture-analysis.md) — tx.receive trace point
-
----
-
-## Task 3.4: Instrument NetworkOPs Transaction Processing
-
-**Objective**: Trace the transaction processing pipeline in NetworkOPs, covering both sync and async paths.
-
-**What to do**:
-
-- Edit `src/xrpld/app/misc/NetworkOPs.cpp`:
-  - In `processTransaction()`:
-    - Create `tx.process` span
-    - Set attributes: `xrpl.tx.hash`, `xrpl.tx.type`, `xrpl.tx.local` (whether from RPC or peer)
-    - Record whether sync or async path is taken
-
-  - In `doTransactionAsync()`:
-    - Capture parent context before queuing
-    - Create `tx.queue` span with queue depth attribute
-    - Add event when transaction is dequeued for processing
-
-  - In `doTransactionSync()`:
-    - Create `tx.process_sync` span
-    - Record result (applied, queued, rejected)
-
-**Key modified files**:
-
-- `src/xrpld/app/misc/NetworkOPs.cpp`
-
-**Reference**:
-
-- [01-architecture-analysis.md §1.6](./01-architecture-analysis.md) — tx.validate and tx.process trace points
-- [02-design-decisions.md §2.4.3](./02-design-decisions.md) — Transaction attribute schema
-
----
-
-## Task 3.5: Instrument HashRouter for Dedup Visibility
-
-**Objective**: Make transaction deduplication visible in traces by recording HashRouter decisions as span attributes/events.
-
-**What to do**:
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp` (in handleTransaction):
-  - After calling `HashRouter::shouldProcess()` or `addSuppressionPeer()`:
-    - Record `xrpl.tx.suppressed` attribute (true/false)
-    - Record `xrpl.tx.flags` showing current HashRouter state (SAVED, TRUSTED, etc.)
-    - Add `tx.first_seen` or `tx.duplicate` event
-
-- This is NOT a modification to HashRouter itself — just recording its decisions as span attributes in the existing PeerImp instrumentation from Task 3.3.
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp` (same changes as 3.3, logically grouped)
-
----
-
-## Task 3.6: Context Propagation in Transaction Relay
-
-**Objective**: Ensure trace context flows correctly when transactions are relayed between peers, creating linked spans across nodes.
-
-**What to do**:
-
-- 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
-
-- Test context propagation:
-  - Manually verify with 2+ node setup that trace IDs match across nodes
-  - Confirm parent-child span relationships are correct in Jaeger
-
-- 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
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-- `src/xrpld/overlay/detail/OverlayImpl.cpp` (if relay method needs context param)
-
-**Reference**:
-
-- [02-design-decisions.md §2.5](./02-design-decisions.md) — Context propagation design
-- [04-code-samples.md §4.5.1](./04-code-samples.md) — Relay context injection pattern
-
----
-
-## Task 3.7: Build Verification and Testing
-
-**Objective**: Verify all Phase 3 changes compile and work correctly.
-
-**What to do**:
-
-1. Build with `telemetry=ON` — verify no compilation errors
-2. Build with `telemetry=OFF` — verify no regressions
-3. Run existing unit tests
-4. Verify protobuf regeneration produces correct C++ code
-5. Document any issues encountered
-
-**Verification Checklist**:
-
-- [ ] Protobuf changes generate valid C++
-- [ ] Build succeeds with telemetry ON
-- [ ] Build succeeds with telemetry OFF
-- [ ] Existing tests pass
-- [ ] No undefined symbols from new telemetry calls
-
----
-
-## Summary
-
-| Task | Description                         | New Files | Modified Files | Depends On |
-| ---- | ----------------------------------- | --------- | -------------- | ---------- |
-| 3.1  | TraceContext protobuf message       | 0         | 1              | Phase 2    |
-| 3.2  | Protobuf context serialization      | 1-2       | 0              | 3.1        |
-| 3.3  | PeerImp transaction instrumentation | 0         | 1              | 3.2        |
-| 3.4  | NetworkOPs transaction processing   | 0         | 1              | Phase 2    |
-| 3.5  | HashRouter dedup visibility         | 0         | 1              | 3.3        |
-| 3.6  | Relay context propagation           | 0         | 1-2            | 3.3, 3.5   |
-| 3.7  | Build verification and testing      | 0         | 0              | 3.1-3.6    |
-
-**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.
-
-**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
-- [ ] HashRouter deduplication visible in traces
-- [ ] <5% overhead on transaction throughput
-
----
-
-## 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
-W3C `tracestate` vendor-specific key-value pairs but is not read or written by
-`TraceContextPropagator`. Wire it when cross-vendor trace propagation is needed.
-No wire cost since proto `optional` fields are zero-cost when absent.

OpenTelemetryPlan/Phase4_taskList.md

@@ -1,244 +0,0 @@
-# Phase 4: Consensus Tracing Task List
-
-> **Goal**: Full observability into consensus rounds — track round lifecycle, phase transitions, proposal handling, and validation. This is the RUN phase that completes the distributed tracing story.
->
-> **Scope**: RCLConsensus instrumentation for round starts, phase transitions (open/establish/accept), proposal send/receive, validation handling, and correlation with transaction traces from Phase 3.
->
-> **Branch**: `pratik/otel-phase4-consensus-tracing` (from `pratik/otel-phase3-tx-tracing`)
-
-### Related Plan Documents
-
-| Document                                                     | Relevance                                                   |
-| ------------------------------------------------------------ | ----------------------------------------------------------- |
-| [04-code-samples.md](./04-code-samples.md)                   | Consensus instrumentation (§4.5.2), consensus span patterns |
-| [01-architecture-analysis.md](./01-architecture-analysis.md) | Consensus round flow (§1.4), key trace points (§1.6)        |
-| [06-implementation-phases.md](./06-implementation-phases.md) | Phase 4 tasks (§6.5), definition of done (§6.11.4)          |
-| [02-design-decisions.md](./02-design-decisions.md)           | Consensus attribute schema (§2.4.4)                         |
-
----
-
-## 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**:
-
-- 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
-
-- 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
-
-**Key modified files**:
-
-- `src/xrpld/app/consensus/RCLConsensus.cpp`
-- `src/xrpld/app/consensus/RCLConsensus.h` (add context member)
-
-**Reference**:
-
-- [04-code-samples.md §4.5.2](./04-code-samples.md) — startRound instrumentation example
-- [01-architecture-analysis.md §1.4](./01-architecture-analysis.md) — Consensus round flow
-
----
-
-## Task 4.2: Instrument Phase Transitions
-
-**Objective**: Create child spans for each consensus phase (open, establish, accept) to show timing breakdown.
-
-**What to do**:
-
-- 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
-
-  - In the `onClose` adaptor method:
-    - Create `consensus.ledger_close` span
-    - Set attributes: close_time, mode, transaction count in initial position
-
-  - Note: The Consensus template class in `include/xrpl/consensus/Consensus.h` drives phase transitions — check if instrumentation goes there or in the Adaptor
-
-**Key modified files**:
-
-- `src/xrpld/app/consensus/RCLConsensus.cpp`
-- Possibly `include/xrpl/consensus/Consensus.h` (for template-level phase tracking)
-
-**Reference**:
-
-- [04-code-samples.md §4.5.2](./04-code-samples.md) — phaseTransition instrumentation
-
----
-
-## Task 4.3: Instrument Proposal Handling
-
-**Objective**: Trace proposal send and receive to show validator coordination.
-
-**What to do**:
-
-- 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)
-
-  - 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::share(RCLCxPeerPos)`:
-    - Create `consensus.proposal.relay` span for relaying peer proposals
-
-**Key modified files**:
-
-- `src/xrpld/app/consensus/RCLConsensus.cpp`
-
-**Reference**:
-
-- [04-code-samples.md §4.5.2](./04-code-samples.md) — peerProposal instrumentation
-- [02-design-decisions.md §2.4.4](./02-design-decisions.md) — Consensus attribute schema
-
----
-
-## Task 4.4: Instrument Validation Handling
-
-**Objective**: Trace validation send and receive to show ledger validation flow.
-
-**What to do**:
-
-- 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
-
-  - 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
-
-**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
-
-**Objective**: Enrich consensus spans with detailed attributes for debugging and analysis.
-
-**What to do**:
-
-- 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
-
-**Key modified files**:
-
-- `src/xrpld/app/consensus/RCLConsensus.cpp`
-
----
-
-## 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**:
-
-- 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
-
-- In `processTransactionSet()` (NetworkOPs):
-  - If the consensus round span context is available, create child spans for each transaction applied to the ledger
-
-**Key modified files**:
-
-- `src/xrpld/app/consensus/RCLConsensus.cpp`
-- `src/xrpld/app/misc/NetworkOPs.cpp`
-
----
-
-## Task 4.7: Build Verification and Testing
-
-**Objective**: Verify all Phase 4 changes compile and don't affect consensus timing.
-
-**What to do**:
-
-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
-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
-
----
-
-## 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       |
-
-**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.
-
-### Implemented Spans
-
-| Span Name                   | Method                             | Key Attributes                                                                                                                |
-| --------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `consensus.proposal.send`   | `Adaptor::propose`                 | `xrpl.consensus.round`                                                                                                        |
-| `consensus.ledger_close`    | `Adaptor::onClose`                 | `xrpl.consensus.ledger.seq`, `xrpl.consensus.mode`                                                                            |
-| `consensus.accept`          | `Adaptor::onAccept`                | `xrpl.consensus.proposers`, `xrpl.consensus.round_time_ms`                                                                    |
-| `consensus.accept.apply`    | `Adaptor::doAccept`                | `xrpl.consensus.close_time`, `close_time_correct`, `close_resolution_ms`, `state`, `proposing`, `round_time_ms`, `ledger.seq` |
-| `consensus.validation.send` | `Adaptor::onAccept` (via validate) | `xrpl.consensus.proposing`                                                                                                    |
-
-#### Close Time Attributes (consensus.accept.apply)
-
-The `consensus.accept.apply` span captures ledger close time agreement details
-driven by `avCT_CONSENSUS_PCT` (75% validator agreement threshold):
-
-- **`xrpl.consensus.close_time`** — Agreed-upon ledger close time (epoch seconds). When validators disagree (`consensusCloseTime == epoch`), this is synthetically set to `prevCloseTime + 1s`.
-- **`xrpl.consensus.close_time_correct`** — `true` if validators reached agreement, `false` if they "agreed to disagree" (close time forced to prev+1s).
-- **`xrpl.consensus.close_resolution_ms`** — Rounding granularity for close time (starts at 30s, decreases as ledger interval stabilizes).
-- **`xrpl.consensus.state`** — `"finished"` (normal) or `"moved_on"` (consensus failed, adopted best available).
-- **`xrpl.consensus.proposing`** — Whether this node was proposing.
-- **`xrpl.consensus.round_time_ms`** — Total consensus round duration.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.11.4](./06-implementation-phases.md)):
-
-- [ ] Complete consensus round traces
-- [ ] Phase transitions visible
-- [ ] Proposals and validations traced
-- [ ] Close time agreement tracked (per `avCT_CONSENSUS_PCT`)
-- [ ] No impact on consensus timing

OpenTelemetryPlan/Phase5_IntegrationTest_taskList.md

@@ -1,221 +0,0 @@
-# Phase 5: Integration Test Task List
-
-> **Goal**: End-to-end verification of the complete telemetry pipeline using a
-> 6-node consensus network. Proves that RPC, transaction, and consensus spans
-> flow through the observability stack (otel-collector, Jaeger, Prometheus,
-> Grafana) under realistic conditions.
->
-> **Scope**: Integration test script, manual testing plan, 6-node local network
-> setup, Jaeger/Prometheus/Grafana verification.
->
-> **Branch**: `pratik/otel-phase5-docs-deployment`
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                  |
-| ---------------------------------------------------------------- | ------------------------------------------ |
-| [07-observability-backends.md](./07-observability-backends.md)   | Jaeger, Grafana, Prometheus setup          |
-| [05-configuration-reference.md](./05-configuration-reference.md) | Collector config, Docker Compose           |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 5 tasks, definition of done          |
-| [Phase5_taskList.md](./Phase5_taskList.md)                       | Phase 5 main task list (5.6 = integration) |
-
----
-
-## Task IT.1: Create Integration Test Script
-
-**Objective**: Automated bash script that stands up a 6-node xrpld network
-with telemetry, exercises all span categories, and verifies data in
-Jaeger/Prometheus.
-
-**What to do**:
-
-- Create `docker/telemetry/integration-test.sh`:
-  - Prerequisites check (docker, xrpld binary, curl, jq)
-  - Start observability stack via `docker compose`
-  - Generate 6 validator key pairs via temp standalone xrpld
-  - Generate 6 node configs + shared `validators.txt`
-  - Start 6 xrpld nodes in consensus mode (`--start`, no `-a`)
-  - Wait for all nodes to reach `"proposing"` state (120s timeout)
-
-**Key new file**: `docker/telemetry/integration-test.sh`
-
-**Verification**:
-
-- [ ] Script starts without errors
-- [ ] All 6 nodes reach "proposing" state
-- [ ] Observability stack is healthy (otel-collector, Jaeger, Prometheus, Grafana)
-
----
-
-## Task IT.2: RPC Span Verification (Phase 2)
-
-**Objective**: Verify RPC spans flow through the telemetry pipeline.
-
-**What to do**:
-
-- Send `server_info`, `server_state`, `ledger` RPCs to node1 (port 5005)
-- Wait for batch export (5s)
-- Query Jaeger API for:
-  - `rpc.request` spans (ServerHandler::onRequest)
-  - `rpc.process` spans (ServerHandler::processRequest)
-  - `rpc.command.server_info` spans (callMethod)
-  - `rpc.command.server_state` spans (callMethod)
-  - `rpc.command.ledger` spans (callMethod)
-- Verify `xrpl.rpc.command` attribute present on `rpc.command.*` spans
-
-**Verification**:
-
-- [ ] Jaeger shows `rpc.request` traces
-- [ ] Jaeger shows `rpc.process` traces
-- [ ] Jaeger shows `rpc.command.*` traces with correct attributes
-
----
-
-## Task IT.3: Transaction Span Verification (Phase 3)
-
-**Objective**: Verify transaction spans flow through the telemetry pipeline.
-
-**What to do**:
-
-- Get genesis account sequence via `account_info` RPC
-- Submit Payment transaction using genesis seed (`snoPBrXtMeMyMHUVTgbuqAfg1SUTb`)
-- Wait for consensus inclusion (10s)
-- Query Jaeger API for:
-  - `tx.process` spans (NetworkOPsImp::processTransaction) on submitting node
-  - `tx.receive` spans (PeerImp::handleTransaction) on peer nodes
-- Verify `xrpl.tx.hash` attribute on `tx.process` spans
-- Verify `xrpl.peer.id` attribute on `tx.receive` spans
-
-**Verification**:
-
-- [ ] Jaeger shows `tx.process` traces with `xrpl.tx.hash`
-- [ ] Jaeger shows `tx.receive` traces with `xrpl.peer.id`
-
----
-
-## Task IT.4: Consensus Span Verification (Phase 4)
-
-**Objective**: Verify consensus spans flow through the telemetry pipeline.
-
-**What to do**:
-
-- Consensus runs automatically in 6-node network
-- Query Jaeger API for:
-  - `consensus.proposal.send` (Adaptor::propose)
-  - `consensus.ledger_close` (Adaptor::onClose)
-  - `consensus.accept` (Adaptor::onAccept)
-  - `consensus.validation.send` (Adaptor::validate)
-- Verify attributes:
-  - `xrpl.consensus.mode` on `consensus.ledger_close`
-  - `xrpl.consensus.proposers` on `consensus.accept`
-  - `xrpl.consensus.ledger.seq` on `consensus.validation.send`
-
-**Verification**:
-
-- [ ] Jaeger shows `consensus.ledger_close` traces with `xrpl.consensus.mode`
-- [ ] Jaeger shows `consensus.accept` traces with `xrpl.consensus.proposers`
-- [ ] Jaeger shows `consensus.proposal.send` traces
-- [ ] Jaeger shows `consensus.validation.send` traces
-
----
-
-## Task IT.5: Spanmetrics Verification (Phase 5)
-
-**Objective**: Verify spanmetrics connector derives RED metrics from spans.
-
-**What to do**:
-
-- Query Prometheus for `traces_span_metrics_calls_total`
-- Query Prometheus for `traces_span_metrics_duration_milliseconds_count`
-- Verify Grafana loads at `http://localhost:3000`
-
-**Verification**:
-
-- [ ] Prometheus returns non-empty results for `traces_span_metrics_calls_total`
-- [ ] Prometheus returns non-empty results for duration histogram
-- [ ] Grafana UI accessible with dashboards visible
-
----
-
-## Task IT.6: Manual Testing Plan
-
-**Objective**: Document how to run tests manually for future reference.
-
-**What to do**:
-
-- Create `docker/telemetry/TESTING.md` with:
-  - Prerequisites section
-  - Single-node standalone test (quick verification)
-  - 6-node consensus test (full verification)
-  - Expected span catalog (all 12 span names with attributes)
-  - Verification queries (Jaeger API, Prometheus API)
-  - Troubleshooting guide
-
-**Key new file**: `docker/telemetry/TESTING.md`
-
-**Verification**:
-
-- [ ] Document covers both single-node and multi-node testing
-- [ ] All 12 span names documented with source file and attributes
-- [ ] Troubleshooting section covers common failure modes
-
----
-
-## Task IT.7: Run and Verify
-
-**Objective**: Execute the integration test and validate results.
-
-**What to do**:
-
-- Run `docker/telemetry/integration-test.sh` locally
-- Debug any failures
-- Leave stack running for manual verification
-- Share URLs:
-  - Jaeger: `http://localhost:16686`
-  - Grafana: `http://localhost:3000`
-  - Prometheus: `http://localhost:9090`
-
-**Verification**:
-
-- [ ] Script completes with all checks passing
-- [ ] Jaeger UI shows rippled service with all expected span names
-- [ ] Grafana dashboards load and show data
-
----
-
-## Task IT.8: Commit
-
-**Objective**: Commit all new files to Phase 5 branch.
-
-**What to do**:
-
-- Run `pcc` (pre-commit checks)
-- Commit 3 new files to `pratik/otel-phase5-docs-deployment`
-
-**Verification**:
-
-- [ ] `pcc` passes
-- [ ] Commit created on Phase 5 branch
-
----
-
-## Summary
-
-| Task | Description                   | New Files | Depends On |
-| ---- | ----------------------------- | --------- | ---------- |
-| IT.1 | Integration test script       | 1         | Phase 5    |
-| IT.2 | RPC span verification         | 0         | IT.1       |
-| IT.3 | Transaction span verification | 0         | IT.1       |
-| IT.4 | Consensus span verification   | 0         | IT.1       |
-| IT.5 | Spanmetrics verification      | 0         | IT.1       |
-| IT.6 | Manual testing plan           | 1         | --         |
-| IT.7 | Run and verify                | 0         | IT.1-IT.6  |
-| IT.8 | Commit                        | 0         | IT.7       |
-
-**Exit Criteria**:
-
-- [ ] All 6 xrpld nodes reach "proposing" state
-- [ ] All 11 expected span names visible in Jaeger
-- [ ] Spanmetrics available in Prometheus
-- [ ] Grafana dashboards show data
-- [ ] Manual testing plan document complete

OpenTelemetryPlan/Phase5_taskList.md

@@ -1,241 +0,0 @@
-# Phase 5: Documentation & Deployment Task List
-
-> **Goal**: Production readiness — Grafana dashboards, spanmetrics pipeline, operator runbook, alert definitions, and final integration testing. This phase ensures the telemetry system is useful and maintainable in production.
->
-> **Scope**: Grafana dashboard definitions, OTel Collector spanmetrics connector, Prometheus integration, alert rules, operator documentation, and production-ready Docker Compose stack.
->
-> **Branch**: `pratik/otel-phase5-docs-deployment` (from `pratik/otel-phase4-consensus-tracing`)
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                                                  |
-| ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| [07-observability-backends.md](./07-observability-backends.md)   | Jaeger setup (§7.1), Grafana dashboards (§7.6), alerts (§7.6.3)            |
-| [05-configuration-reference.md](./05-configuration-reference.md) | Collector config (§5.5), production config (§5.5.2), Docker Compose (§5.6) |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 5 tasks (§6.6), definition of done (§6.11.5)                         |
-
----
-
-## Task 5.1: Add Spanmetrics Connector to OTel Collector
-
-**Objective**: Derive RED metrics (Rate, Errors, Duration) from trace spans automatically, enabling Grafana time-series dashboards.
-
-**What to do**:
-
-- Edit `docker/telemetry/otel-collector-config.yaml`:
-  - Add `spanmetrics` connector:
-    ```yaml
-    connectors:
-      spanmetrics:
-        histogram:
-          explicit:
-            buckets: [1ms, 5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 5s]
-        dimensions:
-          - name: xrpl.rpc.command
-          - name: xrpl.rpc.status
-          - name: xrpl.consensus.phase
-          - name: xrpl.tx.type
-    ```
-  - Add `prometheus` exporter:
-    ```yaml
-    exporters:
-      prometheus:
-        endpoint: 0.0.0.0:8889
-    ```
-  - Wire the pipeline:
-    ```yaml
-    service:
-      pipelines:
-        traces:
-          receivers: [otlp]
-          processors: [batch]
-          exporters: [debug, otlp/jaeger, spanmetrics]
-        metrics:
-          receivers: [spanmetrics]
-          exporters: [prometheus]
-    ```
-
-- Edit `docker/telemetry/docker-compose.yml`:
-  - Expose port `8889` on the collector for Prometheus scraping
-  - Add Prometheus service
-  - Add Prometheus as Grafana datasource
-
-**Key modified files**:
-
-- `docker/telemetry/otel-collector-config.yaml`
-- `docker/telemetry/docker-compose.yml`
-
-**Key new files**:
-
-- `docker/telemetry/prometheus.yml` (Prometheus scrape config)
-- `docker/telemetry/grafana/provisioning/datasources/prometheus.yaml`
-
-**Reference**:
-
-- [POC_taskList.md §Next Steps](./POC_taskList.md) — Metrics pipeline for Grafana dashboards
-
----
-
-## Task 5.2: Create Grafana Dashboards
-
-**Objective**: Provide pre-built Grafana dashboards for RPC performance, transaction lifecycle, and consensus health.
-
-**What to do**:
-
-- Create `docker/telemetry/grafana/provisioning/dashboards/dashboards.yaml` (provisioning config)
-- Create dashboard JSON files:
-  1. **RPC Performance Dashboard** (`rpc-performance.json`):
-     - RPC request latency (p50/p95/p99) by command — histogram panel
-     - RPC throughput (requests/sec) by command — time series
-     - RPC error rate by command — bar gauge
-     - Top slowest RPC commands — table
-
-  2. **Transaction Overview Dashboard** (`transaction-overview.json`):
-     - Transaction processing rate — time series
-     - Transaction latency distribution — histogram
-     - Suppression rate (duplicates) — stat panel
-     - Transaction processing path (sync vs async) — pie chart
-
-  3. **Consensus Health Dashboard** (`consensus-health.json`):
-     - Consensus round duration — time series
-     - Phase duration breakdown (open/establish/accept) — stacked bar
-     - Proposals sent/received per round — stat panel
-     - Consensus mode distribution (proposing/observing) — pie chart
-
-- Store dashboards in `docker/telemetry/grafana/dashboards/`
-
-**Key new files**:
-
-- `docker/telemetry/grafana/provisioning/dashboards/dashboards.yaml`
-- `docker/telemetry/grafana/dashboards/rpc-performance.json`
-- `docker/telemetry/grafana/dashboards/transaction-overview.json`
-- `docker/telemetry/grafana/dashboards/consensus-health.json`
-
-**Reference**:
-
-- [07-observability-backends.md §7.6](./07-observability-backends.md) — Grafana dashboard specifications
-- [01-architecture-analysis.md §1.8.3](./01-architecture-analysis.md) — Dashboard panel examples
-
----
-
-## Task 5.3: Define Alert Rules
-
-**Objective**: Create alert definitions for key telemetry anomalies.
-
-**What to do**:
-
-- Create `docker/telemetry/grafana/provisioning/alerting/alerts.yaml`:
-  - **RPC Latency Alert**: p99 latency > 1s for any command over 5 minutes
-  - **RPC Error Rate Alert**: Error rate > 5% for any command over 5 minutes
-  - **Consensus Duration Alert**: Round duration > 10s (warn), > 30s (critical)
-  - **Transaction Processing Alert**: Processing rate drops below threshold
-  - **Telemetry Pipeline Health**: No spans received for > 2 minutes
-
-**Key new files**:
-
-- `docker/telemetry/grafana/provisioning/alerting/alerts.yaml`
-
-**Reference**:
-
-- [07-observability-backends.md §7.6.3](./07-observability-backends.md) — Alert rule definitions
-
----
-
-## Task 5.4: Production Collector Configuration
-
-**Objective**: Create a production-ready OTel Collector configuration with tail-based sampling and resource limits.
-
-**What to do**:
-
-- Create `docker/telemetry/otel-collector-config-production.yaml`:
-  - Tail-based sampling policy:
-    - Always sample errors and slow traces
-    - 10% base sampling rate for normal traces
-    - Always sample first trace for each unique RPC command
-  - Resource limits:
-    - Memory limiter processor (80% of available memory)
-    - Queued retry for export failures
-  - TLS configuration for production endpoints
-  - Health check endpoint
-
-**Key new files**:
-
-- `docker/telemetry/otel-collector-config-production.yaml`
-
-**Reference**:
-
-- [05-configuration-reference.md §5.5.2](./05-configuration-reference.md) — Production collector config
-
----
-
-## Task 5.5: Operator Runbook
-
-**Objective**: Create operator documentation for managing the telemetry system in production.
-
-**What to do**:
-
-- Create `docs/telemetry-runbook.md`:
-  - **Setup**: How to enable telemetry in rippled
-  - **Configuration**: All config options with descriptions
-  - **Collector Deployment**: Docker Compose vs. Kubernetes vs. bare metal
-  - **Troubleshooting**: Common issues and resolutions
-    - No traces appearing
-    - High memory usage from telemetry
-    - Collector connection failures
-    - Sampling configuration tuning
-  - **Performance Tuning**: Batch size, queue size, sampling ratio guidelines
-  - **Upgrading**: How to upgrade OTel SDK and Collector versions
-
-**Key new files**:
-
-- `docs/telemetry-runbook.md`
-
----
-
-## Task 5.6: Final Integration Testing
-
-**Objective**: Validate the complete telemetry stack end-to-end.
-
-**What to do**:
-
-1. Start full Docker stack (Collector, Jaeger, Grafana, Prometheus)
-2. Build rippled with `telemetry=ON`
-3. Run in standalone mode with telemetry enabled
-4. Generate RPC traffic and verify traces in Jaeger
-5. Verify dashboards populate in Grafana
-6. Verify alerts trigger correctly
-7. Test telemetry OFF path (no regressions)
-8. Run full test suite
-
-**Verification Checklist**:
-
-- [ ] Docker stack starts without errors
-- [ ] Traces appear in Jaeger with correct hierarchy
-- [ ] Grafana dashboards show metrics derived from spans
-- [ ] Prometheus scrapes spanmetrics successfully
-- [ ] Alerts can be triggered by simulated conditions
-- [ ] Build succeeds with telemetry ON and OFF
-- [ ] Full test suite passes
-
----
-
-## Summary
-
-| Task | Description                        | New Files | Modified Files | Depends On |
-| ---- | ---------------------------------- | --------- | -------------- | ---------- |
-| 5.1  | Spanmetrics connector + Prometheus | 2         | 2              | Phase 4    |
-| 5.2  | Grafana dashboards                 | 4         | 0              | 5.1        |
-| 5.3  | Alert definitions                  | 1         | 0              | 5.1        |
-| 5.4  | Production collector config        | 1         | 0              | Phase 4    |
-| 5.5  | Operator runbook                   | 1         | 0              | Phase 4    |
-| 5.6  | Final integration testing          | 0         | 0              | 5.1-5.5    |
-
-**Parallel work**: Tasks 5.1, 5.4, and 5.5 can run in parallel. Tasks 5.2 and 5.3 depend on 5.1. Task 5.6 depends on all others.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.11.5](./06-implementation-phases.md)):
-
-- [ ] Dashboards deployed and showing data
-- [ ] Alerts configured and tested
-- [ ] Operator documentation complete
-- [ ] Production collector config ready
-- [ ] Full test suite passes

OpenTelemetryPlan/Phase7_taskList.md

@@ -1,256 +0,0 @@
-# Phase 7: Native OTel Metrics Migration — Task List
-
-> **Goal**: Replace `StatsDCollector` with a native OpenTelemetry Metrics SDK implementation behind the existing `beast::insight::Collector` interface, eliminating the StatsD UDP dependency.
->
-> **Scope**: New `OTelCollectorImpl` class, `CollectorManager` config change, OTel Collector pipeline update, Grafana dashboard metric name migration, integration tests.
->
-> **Branch**: `pratik/otel-phase7-native-metrics` (from `pratik/otel-phase6-statsd`)
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 7 plan: motivation, architecture, exit criteria (§6.8)    |
-| [02-design-decisions.md](./02-design-decisions.md)                   | Collector interface design, beast::insight coexistence strategy |
-| [05-configuration-reference.md](./05-configuration-reference.md)     | `[insight]` and `[telemetry]` config sections                   |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Complete metric inventory that must be preserved                |
-
----
-
-## Task 7.1: Add OTel Metrics SDK to Build Dependencies
-
-**Objective**: Enable the OTel C++ Metrics SDK components in the build system.
-
-**What to do**:
-
-- Edit `conanfile.py`:
-  - Add OTel metrics SDK components to the dependency list when `telemetry=True`
-  - Components needed: `opentelemetry-cpp::metrics`, `opentelemetry-cpp::otlp_http_metric_exporter`
-
-- Edit `CMakeLists.txt` (telemetry section):
-  - Link `opentelemetry::metrics` and `opentelemetry::otlp_http_metric_exporter` targets
-
-**Key modified files**:
-
-- `conanfile.py`
-- `CMakeLists.txt` (or the relevant telemetry cmake target)
-
-**Reference**: [05-configuration-reference.md §5.3](./05-configuration-reference.md) — CMake integration
-
----
-
-## Task 7.2: Implement OTelCollector Class
-
-**Objective**: Create the core `OTelCollector` implementation that maps beast::insight instruments to OTel Metrics SDK instruments.
-
-**What to do**:
-
-- Create `include/xrpl/beast/insight/OTelCollector.h`:
-  - Public factory: `static std::shared_ptr<OTelCollector> New(std::string const& endpoint, std::string const& prefix, beast::Journal journal)`
-  - Derives from `StatsDCollector` (or directly from `Collector` — TBD based on shared code)
-
-- Create `src/libxrpl/beast/insight/OTelCollector.cpp` (~400-500 lines):
-  - **OTelCounterImpl**: Wraps `opentelemetry::metrics::Counter<int64_t>`. `increment(amount)` calls `counter->Add(amount)`.
-  - **OTelGaugeImpl**: Uses `opentelemetry::metrics::ObservableGauge<uint64_t>` with an async callback. `set(value)` stores value atomically; callback reads it during collection.
-  - **OTelMeterImpl**: Wraps `opentelemetry::metrics::Counter<uint64_t>`. `increment(amount)` calls `counter->Add(amount)`. Semantically identical to Counter but unsigned.
-  - **OTelEventImpl**: Wraps `opentelemetry::metrics::Histogram<double>`. `notify(duration)` calls `histogram->Record(duration.count())`. Uses explicit bucket boundaries matching SpanMetrics: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000] ms.
-  - **OTelHookImpl**: Stores handler function. Called during periodic metric collection (same 1s pattern via PeriodicMetricReader).
-  - **OTelCollectorImp**: Main class.
-    - Creates `MeterProvider` with `PeriodicMetricReader` (1s export interval)
-    - Creates `OtlpHttpMetricExporter` pointing to `[telemetry]` endpoint
-    - Sets resource attributes (service.name, service.instance.id) matching trace exporter
-    - Implements all `make_*()` factory methods
-    - Prefixes metric names with `[insight] prefix=` value
-
-- Guard all OTel SDK includes with `#ifdef XRPL_ENABLE_TELEMETRY` to compile to `NullCollector` equivalents when telemetry disabled.
-
-**Key new files**:
-
-- `include/xrpl/beast/insight/OTelCollector.h`
-- `src/libxrpl/beast/insight/OTelCollector.cpp`
-
-**Key patterns to follow**:
-
-- Match `StatsDCollector.cpp` structure: private impl classes, intrusive list for metrics, strand-based thread safety
-- Match existing telemetry code style from `src/libxrpl/telemetry/Telemetry.cpp`
-- Use RAII for MeterProvider lifecycle (shutdown on destructor)
-
-**Reference**: [04-code-samples.md](./04-code-samples.md) — code style and patterns
-
----
-
-## Task 7.3: Update CollectorManager
-
-**Objective**: Add `server=otel` config option to route metric creation to the new OTel backend.
-
-**What to do**:
-
-- Edit `src/xrpld/app/main/CollectorManager.cpp`:
-  - In the constructor, add a third branch after `server == "statsd"`:
-    ```cpp
-    else if (server == "otel")
-    {
-        // Read endpoint from [telemetry] section
-        auto const endpoint = get(telemetryParams, "endpoint",
-            "http://localhost:4318/v1/metrics");
-        std::string const& prefix(get(params, "prefix"));
-        m_collector = beast::insight::OTelCollector::New(
-            endpoint, prefix, journal);
-    }
-    ```
-  - This requires access to the `[telemetry]` config section — may need to pass it as a parameter or read from Application config.
-
-- Edit `src/xrpld/app/main/CollectorManager.h`:
-  - Add `#include <xrpl/beast/insight/OTelCollector.h>`
-
-**Key modified files**:
-
-- `src/xrpld/app/main/CollectorManager.cpp`
-- `src/xrpld/app/main/CollectorManager.h`
-
----
-
-## Task 7.4: Update OTel Collector Configuration
-
-**Objective**: Add a metrics pipeline to the OTLP receiver and remove the StatsD receiver dependency.
-
-**What to do**:
-
-- Edit `docker/telemetry/otel-collector-config.yaml`:
-  - Remove `statsd` receiver (no longer needed when `server=otel`)
-  - Add metrics pipeline under `service.pipelines`:
-    ```yaml
-    metrics:
-      receivers: [otlp, spanmetrics]
-      processors: [batch]
-      exporters: [prometheus]
-    ```
-  - The OTLP receiver already listens on :4318 — it just needs to be added to the metrics pipeline receivers.
-  - Keep `spanmetrics` connector in the metrics pipeline so span-derived RED metrics continue working.
-
-- Edit `docker/telemetry/docker-compose.yml`:
-  - Remove UDP :8125 port mapping from otel-collector service
-  - Update rippled service config: change `[insight] server=statsd` to `server=otel`
-
-**Key modified files**:
-
-- `docker/telemetry/otel-collector-config.yaml`
-- `docker/telemetry/docker-compose.yml`
-
-**Note**: Keep a commented-out `statsd` receiver block for operators who need backward compatibility.
-
----
-
-## Task 7.5: Preserve Metric Names in Prometheus
-
-**Objective**: Ensure existing Grafana dashboards continue working with identical metric names.
-
-**What to do**:
-
-- In `OTelCollector.cpp`, construct OTel instrument names to match existing Prometheus metric names:
-  - beast::insight `make_gauge("LedgerMaster", "Validated_Ledger_Age")` → OTel instrument name: `rippled_LedgerMaster_Validated_Ledger_Age`
-  - The prefix + group + name concatenation must produce the same string as `StatsDCollector`'s format
-  - Use underscores as separators (matching StatsD convention)
-
-- Verify in integration test that key Prometheus queries still return data:
-  - `rippled_LedgerMaster_Validated_Ledger_Age`
-  - `rippled_Peer_Finder_Active_Inbound_Peers`
-  - `rippled_rpc_requests`
-
-**Key consideration**: OTel Prometheus exporter may normalize metric names differently than StatsD receiver. Test this early (Task 7.2) and adjust naming strategy if needed. The OTel SDK's Prometheus exporter adds `_total` suffix to counters and converts dots to underscores — match existing conventions.
-
----
-
-## Task 7.6: Update Grafana Dashboards
-
-**Objective**: Update the 3 StatsD dashboards if any metric names change due to OTLP export format differences.
-
-**What to do**:
-
-- If Task 7.5 confirms metric names are preserved exactly, no dashboard changes needed.
-- If OTLP export produces different names (e.g., `_total` suffix on counters), update:
-  - `docker/telemetry/grafana/dashboards/statsd-node-health.json`
-  - `docker/telemetry/grafana/dashboards/statsd-network-traffic.json`
-  - `docker/telemetry/grafana/dashboards/statsd-rpc-pathfinding.json`
-- Rename dashboard titles from "StatsD" to "System Metrics" or similar (since they're no longer StatsD-sourced).
-
-**Key modified files**:
-
-- `docker/telemetry/grafana/dashboards/statsd-*.json` (3 files, conditionally)
-
----
-
-## Task 7.7: Update Integration Tests
-
-**Objective**: Verify the full OTLP metrics pipeline end-to-end.
-
-**What to do**:
-
-- Edit `docker/telemetry/integration-test.sh`:
-  - Update test config to use `[insight] server=otel`
-  - Verify metrics arrive in Prometheus via OTLP (not StatsD)
-  - Add check that StatsD receiver is no longer required
-  - Preserve all existing metric presence checks
-
-**Key modified files**:
-
-- `docker/telemetry/integration-test.sh`
-
----
-
-## Task 7.8: Update Documentation
-
-**Objective**: Update all plan docs, runbook, and reference docs to reflect the migration.
-
-**What to do**:
-
-- Edit `docs/telemetry-runbook.md`:
-  - Update `[insight]` config examples to show `server=otel`
-  - Update troubleshooting section (no more StatsD UDP debugging)
-
-- Edit `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Update Data Flow Overview diagram (remove StatsD receiver)
-  - Update Section 2 header from "StatsD Metrics" to "System Metrics (OTel native)"
-  - Update config examples
-
-- Edit `OpenTelemetryPlan/05-configuration-reference.md`:
-  - Add `server=otel` option to `[insight]` section docs
-
-- Edit `docker/telemetry/TESTING.md`:
-  - Update setup instructions to use `server=otel`
-
-**Key modified files**:
-
-- `docs/telemetry-runbook.md`
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `OpenTelemetryPlan/05-configuration-reference.md`
-- `docker/telemetry/TESTING.md`
-
----
-
-## Summary Table
-
-| Task | Description                            | New Files | Modified Files | Effort | Risk   | Depends On |
-| ---- | -------------------------------------- | --------- | -------------- | ------ | ------ | ---------- |
-| 7.1  | Add OTel Metrics SDK to build deps     | 0         | 2              | 0.5d   | Low    | —          |
-| 7.2  | Implement OTelCollector class          | 2         | 0              | 3d     | Medium | 7.1        |
-| 7.3  | Update CollectorManager config routing | 0         | 2              | 0.5d   | Low    | 7.2        |
-| 7.4  | Update OTel Collector YAML and Docker  | 0         | 2              | 0.5d   | Low    | 7.3        |
-| 7.5  | Preserve metric names in Prometheus    | 0         | 1              | 1d     | Medium | 7.2        |
-| 7.6  | Update Grafana dashboards (if needed)  | 0         | 3              | 1d     | Low    | 7.5        |
-| 7.7  | Update integration tests               | 0         | 1              | 0.5d   | Low    | 7.4        |
-| 7.8  | Update documentation                   | 0         | 4              | 1d     | Low    | 7.6        |
-
-**Total Effort**: 8 days
-
-**Parallel work**: Tasks 7.4 and 7.5 can run in parallel after 7.2/7.3 complete. Task 7.6 depends on 7.5's findings. Tasks 7.7 and 7.8 can run in parallel after 7.6.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.8](./06-implementation-phases.md)):
-
-- [ ] 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 mapped to OTel Counter

OpenTelemetryPlan/Phase8_taskList.md

@@ -1,234 +0,0 @@
-# Phase 8: Log-Trace Correlation and Centralized Log Ingestion — Task List
-
-> **Goal**: Inject trace context (trace_id, span_id) into rippled's Journal log output for log-trace correlation, and add OTel Collector filelog receiver to ingest logs into Grafana Loki for unified observability.
->
-> **Scope**: Two independent sub-phases — 8a (code change: trace_id in logs) and 8b (infra only: filelog receiver to Loki). No changes to the `beast::Journal` public API.
->
-> **Branch**: `pratik/otel-phase8-log-correlation` (from `pratik/otel-phase7-native-metrics`)
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                                      |
-| ---------------------------------------------------------------- | -------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 8 plan: motivation, architecture, exit criteria (§6.8.1) |
-| [07-observability-backends.md](./07-observability-backends.md)   | Loki backend recommendation, Grafana data source provisioning  |
-| [Phase7_taskList.md](./Phase7_taskList.md)                       | Prerequisite — native OTel metrics pipeline must be working    |
-| [05-configuration-reference.md](./05-configuration-reference.md) | `[telemetry]` config (trace_id injection toggle)               |
-
----
-
-## Task 8.1: Inject trace_id into Logs::format()
-
-**Objective**: Add OTel trace context to every log line that is emitted within an active span.
-
-**What to do**:
-
-- Edit `src/libxrpl/basics/Log.cpp`:
-  - In `Logs::format()` (around line 346), after severity is appended, check for active OTel span:
-    ```cpp
-    #ifdef XRPL_ENABLE_TELEMETRY
-    auto span = opentelemetry::trace::GetSpan(
-        opentelemetry::context::RuntimeContext::GetCurrent());
-    auto ctx = span->GetContext();
-    if (ctx.IsValid())
-    {
-        // Append trace context as structured fields
-        char traceId[33], spanId[17];
-        ctx.trace_id().ToLowerBase16(traceId);
-        ctx.span_id().ToLowerBase16(spanId);
-        output += "trace_id=";
-        output.append(traceId, 32);
-        output += " span_id=";
-        output.append(spanId, 16);
-        output += ' ';
-    }
-    #endif
-    ```
-  - Add `#include` for OTel context headers, guarded by `#ifdef XRPL_ENABLE_TELEMETRY`
-
-- Edit `include/xrpl/basics/Log.h`:
-  - No changes needed — format() signature unchanged
-
-**Key modified files**:
-
-- `src/libxrpl/basics/Log.cpp`
-
-**Performance note**: `GetSpan()` and `GetContext()` are thread-local reads with no locking — measured at <10ns per call. With ~1000 JLOG calls/min, this adds <10us/min of overhead.
-
----
-
-## Task 8.2: Add Loki to Docker Compose Stack
-
-**Objective**: Add Grafana Loki as a log storage backend in the development observability stack.
-
-**What to do**:
-
-- Edit `docker/telemetry/docker-compose.yml`:
-  - Add Loki service:
-    ```yaml
-    loki:
-      image: grafana/loki:2.9.0
-      ports:
-        - "3100:3100"
-      command: -config.file=/etc/loki/local-config.yaml
-    ```
-  - Add Loki as a Grafana data source in provisioning
-
-- Create `docker/telemetry/grafana/provisioning/datasources/loki.yaml`:
-  - Configure Loki data source with derived fields linking `trace_id` to Tempo
-
-**Key new files**:
-
-- `docker/telemetry/grafana/provisioning/datasources/loki.yaml`
-
-**Key modified files**:
-
-- `docker/telemetry/docker-compose.yml`
-
----
-
-## Task 8.3: Add Filelog Receiver to OTel Collector
-
-**Objective**: Configure the OTel Collector to tail rippled's log file and export to Loki.
-
-**What to do**:
-
-- Edit `docker/telemetry/otel-collector-config.yaml`:
-  - Add `filelog` receiver:
-    ```yaml
-    receivers:
-      filelog:
-        include: [/var/log/rippled/debug.log]
-        operators:
-          - type: regex_parser
-            regex: '^(?P<timestamp>\S+)\s+(?P<partition>\S+):(?P<severity>\S+)\s+(?:trace_id=(?P<trace_id>[a-f0-9]+)\s+span_id=(?P<span_id>[a-f0-9]+)\s+)?(?P<message>.*)$'
-            timestamp:
-              parse_from: attributes.timestamp
-              layout: "%Y-%m-%dT%H:%M:%S.%fZ"
-    ```
-  - Add logs pipeline:
-    ```yaml
-    service:
-      pipelines:
-        logs:
-          receivers: [filelog]
-          processors: [batch]
-          exporters: [otlp/loki]
-    ```
-  - Add Loki exporter:
-    ```yaml
-    exporters:
-      otlp/loki:
-        endpoint: loki:3100
-        tls:
-          insecure: true
-    ```
-
-- Mount rippled's log directory into the collector container via docker-compose volume
-
-**Key modified files**:
-
-- `docker/telemetry/otel-collector-config.yaml`
-- `docker/telemetry/docker-compose.yml`
-
----
-
-## Task 8.4: Configure Grafana Trace-to-Log Correlation
-
-**Objective**: Enable one-click navigation from Tempo traces to Loki logs in Grafana.
-
-**What to do**:
-
-- Edit Grafana Tempo data source provisioning to add `tracesToLogs` configuration:
-
-  ```yaml
-  tracesToLogs:
-    datasourceUid: loki
-    filterByTraceID: true
-    filterBySpanID: false
-    tags: ["partition", "severity"]
-  ```
-
-- Edit Grafana Loki data source provisioning to add `derivedFields` linking trace_id back to Tempo:
-  ```yaml
-  derivedFields:
-    - datasourceUid: tempo
-      matcherRegex: "trace_id=(\\w+)"
-      name: TraceID
-      url: "$${__value.raw}"
-  ```
-
-**Key modified files**:
-
-- `docker/telemetry/grafana/provisioning/datasources/loki.yaml`
-- `docker/telemetry/grafana/provisioning/datasources/` (Tempo data source file)
-
----
-
-## Task 8.5: Update Integration Tests
-
-**Objective**: Verify trace_id appears in logs and Loki correlation works.
-
-**What to do**:
-
-- Edit `docker/telemetry/integration-test.sh`:
-  - After sending RPC requests (which create spans), grep rippled's log output for `trace_id=`
-  - Verify trace_id matches a trace visible in Jaeger
-  - Optionally: query Loki via API to confirm log ingestion
-
-**Key modified files**:
-
-- `docker/telemetry/integration-test.sh`
-
----
-
-## Task 8.6: Update Documentation
-
-**Objective**: Document the log correlation feature in runbook and reference docs.
-
-**What to do**:
-
-- Edit `docs/telemetry-runbook.md`:
-  - Add "Log-Trace Correlation" section explaining how to use Grafana Tempo -> Loki linking
-  - Add LogQL query examples for filtering by trace_id
-
-- Edit `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add new section "3. Log Correlation" between SpanMetrics and StatsD sections
-  - Document the log format with trace_id injection
-  - Document Loki as a new backend
-
-- Edit `docker/telemetry/TESTING.md`:
-  - Add log correlation verification steps
-
-**Key modified files**:
-
-- `docs/telemetry-runbook.md`
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `docker/telemetry/TESTING.md`
-
----
-
-## Summary Table
-
-| Task | Description                                | Sub-Phase | New Files | Modified Files | Effort | Risk   | Depends On |
-| ---- | ------------------------------------------ | --------- | --------- | -------------- | ------ | ------ | ---------- |
-| 8.1  | Inject trace_id into Logs::format()        | 8a        | 0         | 1              | 1d     | Low    | Phase 7    |
-| 8.2  | Add Loki to Docker Compose stack           | 8b        | 1         | 1              | 0.5d   | Low    | --         |
-| 8.3  | Add filelog receiver to OTel Collector     | 8b        | 0         | 2              | 1d     | Medium | 8.1, 8.2   |
-| 8.4  | Configure Grafana trace-to-log correlation | 8b        | 0         | 2              | 0.5d   | Low    | 8.3        |
-| 8.5  | Update integration tests                   | 8a + 8b   | 0         | 1              | 0.5d   | Low    | 8.4        |
-| 8.6  | Update documentation                       | 8a + 8b   | 0         | 3              | 1d     | Low    | 8.5        |
-
-**Total Effort**: 4.5 days
-
-**Parallel work**: Task 8.2 (Loki infra) can run in parallel with Task 8.1 (code change). Tasks 8.3-8.6 are sequential.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.8.1](./06-implementation-phases.md)):
-
-- [ ] Log lines within active spans contain `trace_id=<hex> span_id=<hex>`
-- [ ] Log lines outside spans have no trace context (no empty fields)
-- [ ] Loki ingests rippled logs via OTel Collector filelog receiver
-- [ ] Grafana Tempo -> Loki one-click correlation works
-- [ ] Grafana Loki -> Tempo reverse lookup works via derived field
-- [ ] Integration test verifies trace_id presence in logs
-- [ ] No performance regression from trace_id injection (< 0.1% overhead)

OpenTelemetryPlan/Phase9_taskList.md

@@ -1,329 +0,0 @@
-# Phase 9: Internal Metric Instrumentation Gap Fill — Task List
-
-> **Status**: Future Enhancement
->
-> **Goal**: Instrument rippled to emit ~50+ metrics that exist in `get_counts`/`server_info`/TxQ/PerfLog but currently lack time-series export via the OTel or beast::insight pipelines.
->
-> **Scope**: Hybrid approach — extend `beast::insight` for metrics near existing registrations, use OTel Metrics SDK `ObservableGauge` callbacks for new categories (TxQ, PerfLog, CountedObjects).
->
-> **Branch**: `pratik/otel-phase9-metric-gap-fill` (from `pratik/otel-phase8-log-correlation`)
->
-> **Depends on**: Phase 7 (native OTel metrics pipeline) and Phase 8 (log-trace correlation)
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                      |
-| -------------------------------------------------------------------- | -------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 9 plan: motivation, architecture, exit criteria (§6.8.2) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Current metric inventory + future metrics section              |
-| [Phase7_taskList.md](./Phase7_taskList.md)                           | Prerequisite — OTel Metrics SDK and `OTelCollector` class      |
-| [Phase8_taskList.md](./Phase8_taskList.md)                           | Prerequisite — log-trace correlation                           |
-
-### Third-Party Consumer Context
-
-These metrics serve multiple external consumer categories identified during research:
-
-| Consumer Category         | Key Metrics They Need                                           |
-| ------------------------- | --------------------------------------------------------------- |
-| **Exchanges**             | Fee escalation levels, TxQ depth, settlement latency            |
-| **Payment Processors**    | Load factors, io_latency, transaction throughput                |
-| **Analytics Providers**   | NodeStore I/O, cache hit rates, counted objects                 |
-| **Validators/Operators**  | Per-job execution times, PerfLog RPC counters, consensus timing |
-| **Academic Researchers**  | Consensus performance time-series, fee market dynamics          |
-| **Institutional Custody** | Server health scores, reserve calculations, node availability   |
-
----
-
-## Task 9.1: NodeStore I/O Metrics
-
-**Objective**: Export node store read/write performance as time-series metrics.
-
-**What to do**:
-
-- In `src/libxrpl/nodestore/Database.cpp`, extend existing `beast::insight` registrations to add:
-  - Gauge: `node_reads_total` (cumulative read operations)
-  - Gauge: `node_reads_hit` (cache-served reads)
-  - Gauge: `node_writes` (cumulative write operations)
-  - Gauge: `node_written_bytes` (cumulative bytes written)
-  - Gauge: `node_read_bytes` (cumulative bytes read)
-  - Gauge: `node_reads_duration_us` (cumulative read time in microseconds)
-  - Gauge: `write_load` (current write load score)
-  - Gauge: `read_queue` (items in read queue)
-
-- These values are already computed in `Database::getCountsJson()` (line ~236). Wire the same counters to `beast::insight` hooks.
-
-**Key modified files**:
-
-- `src/libxrpl/nodestore/Database.cpp`
-- `src/libxrpl/nodestore/Database.h` (add insight members)
-
-**Derived Prometheus metrics**: `rippled_nodestore_reads_total`, `rippled_nodestore_reads_hit`, `rippled_nodestore_write_load`, etc.
-
-**Grafana dashboard**: Add "NodeStore I/O" panel group to _Node Health_ dashboard.
-
----
-
-## Task 9.2: Cache Hit Rate Metrics
-
-**Objective**: Export SHAMap and ledger cache performance as time-series gauges.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks (via Phase 7's `OTelCollector`) for:
-  - `SLE_hit_rate` — SLE cache hit rate (0.0–1.0)
-  - `ledger_hit_rate` — Ledger object cache hit rate
-  - `AL_hit_rate` — AcceptedLedger cache hit rate
-  - `treenode_cache_size` — SHAMap TreeNode cache size (entries)
-  - `treenode_track_size` — Tracked tree nodes
-  - `fullbelow_size` — FullBelow cache size
-
-- The callback should read from the same sources as `GetCounts.cpp` handler (line ~43).
-
-- Create a centralized `MetricsRegistry` class that holds all OTel async gauge registrations, polled at 10-second intervals by the `PeriodicMetricReader`.
-
-**Key modified files**:
-
-- New: `src/xrpld/telemetry/MetricsRegistry.h` / `.cpp`
-- `src/xrpld/rpc/handlers/GetCounts.cpp` (extract shared access methods)
-- `src/xrpld/app/main/Application.cpp` (register MetricsRegistry at startup)
-
-**Derived Prometheus metrics**: `rippled_cache_SLE_hit_rate`, `rippled_cache_ledger_hit_rate`, `rippled_cache_treenode_size`, etc.
-
----
-
-## Task 9.3: Transaction Queue (TxQ) Metrics
-
-**Objective**: Export TxQ depth, capacity, and fee escalation levels as time-series.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for TxQ state (from `TxQ.h` line ~143):
-  - `txq_count` — Current transactions in queue
-  - `txq_max_size` — Maximum queue capacity
-  - `txq_in_ledger` — Transactions in current open ledger
-  - `txq_per_ledger` — Expected transactions per ledger
-  - `txq_reference_fee_level` — Reference fee level
-  - `txq_min_processing_fee_level` — Minimum fee to get processed
-  - `txq_med_fee_level` — Median fee level in queue
-  - `txq_open_ledger_fee_level` — Open ledger fee escalation level
-
-- Add to the `MetricsRegistry` (Task 9.2).
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (add TxQ callbacks)
-- `src/xrpld/app/tx/detail/TxQ.h` (expose metrics accessor if needed)
-
-**Derived Prometheus metrics**: `rippled_txq_count`, `rippled_txq_max_size`, `rippled_txq_open_ledger_fee_level`, etc.
-
-**Grafana dashboard**: New _Fee Market & TxQ_ dashboard (`rippled-fee-market`).
-
----
-
-## Task 9.4: PerfLog Per-RPC Method Metrics
-
-**Objective**: Export per-RPC-method call counts and latency as OTel metrics.
-
-**What to do**:
-
-- Register OTel instruments for PerfLog RPC counters (from `PerfLogImp.cpp` line ~63):
-  - Counter: `rpc_method_started_total{method="<name>"}` — calls started
-  - Counter: `rpc_method_finished_total{method="<name>"}` — calls completed
-  - Counter: `rpc_method_errored_total{method="<name>"}` — calls errored
-  - Histogram: `rpc_method_duration_us{method="<name>"}` — execution time distribution
-
-- Use OTel `Counter<int64_t>` and `Histogram<double>` instruments with `method` attribute label.
-
-- Hook into the existing PerfLog callback mechanism rather than adding new instrumentation points.
-
-**Key modified files**:
-
-- `src/xrpld/perflog/detail/PerfLogImp.cpp` (add OTel instrument updates alongside existing JSON counters)
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (register instruments)
-
-**Derived Prometheus metrics**: `rippled_rpc_method_started_total{method="server_info"}`, `rippled_rpc_method_duration_us_bucket{method="ledger"}`, etc.
-
-**Grafana dashboard**: Add "Per-Method RPC Breakdown" panel group to _RPC Performance_ dashboard.
-
----
-
-## Task 9.5: PerfLog Per-Job-Type Metrics
-
-**Objective**: Export per-job-type queue and execution metrics.
-
-**What to do**:
-
-- Register OTel instruments for PerfLog job counters:
-  - Counter: `job_queued_total{job_type="<name>"}` — jobs queued
-  - Counter: `job_started_total{job_type="<name>"}` — jobs started
-  - Counter: `job_finished_total{job_type="<name>"}` — jobs completed
-  - Histogram: `job_queued_duration_us{job_type="<name>"}` — time spent waiting in queue
-  - Histogram: `job_running_duration_us{job_type="<name>"}` — execution time distribution
-
-- Hook into PerfLog's existing job tracking alongside Task 9.4.
-
-**Key modified files**:
-
-- `src/xrpld/perflog/detail/PerfLogImp.cpp`
-- `src/xrpld/telemetry/MetricsRegistry.cpp`
-
-**Derived Prometheus metrics**: `rippled_job_queued_total{job_type="ledgerData"}`, `rippled_job_running_duration_us_bucket{job_type="transaction"}`, etc.
-
-**Grafana dashboard**: New _Job Queue Analysis_ dashboard (`rippled-job-queue`).
-
----
-
-## Task 9.6: Counted Object Instance Metrics
-
-**Objective**: Export live instance counts for key internal object types.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for `CountedObject<T>` instance counts:
-  - `object_count{type="Transaction"}` — live Transaction objects
-  - `object_count{type="Ledger"}` — live Ledger objects
-  - `object_count{type="NodeObject"}` — live NodeObject instances
-  - `object_count{type="STTx"}` — serialized transaction objects
-  - `object_count{type="STLedgerEntry"}` — serialized ledger entries
-  - `object_count{type="InboundLedger"}` — ledgers being fetched
-  - `object_count{type="Pathfinder"}` — active pathfinding computations
-  - `object_count{type="PathRequest"}` — active path requests
-  - `object_count{type="HashRouterEntry"}` — hash router entries
-
-- The `CountedObject` template already tracks these via atomic counters. The callback just reads the current counts.
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (add counted object callbacks)
-- `include/xrpl/basics/CountedObject.h` (may need static accessor for iteration)
-
-**Derived Prometheus metrics**: `rippled_object_count{type="Transaction"}`, `rippled_object_count{type="NodeObject"}`, etc.
-
-**Grafana dashboard**: Add "Object Instance Counts" panel to _Node Health_ dashboard.
-
----
-
-## Task 9.7: Fee Escalation & Load Factor Metrics
-
-**Objective**: Export the full load factor breakdown as time-series.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for load factors (from `NetworkOPs.cpp` line ~2694):
-  - `load_factor` — combined transaction cost multiplier
-  - `load_factor_server` — server + cluster + network contribution
-  - `load_factor_local` — local server load only
-  - `load_factor_net` — network-wide load estimate
-  - `load_factor_cluster` — cluster peer load
-  - `load_factor_fee_escalation` — open ledger fee escalation
-  - `load_factor_fee_queue` — queue entry fee level
-
-- These overlap with some existing StatsD metrics but provide finer granularity (individual factor breakdown vs. combined value).
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp`
-- `src/xrpld/app/misc/NetworkOPs.cpp` (expose load factor accessors if needed)
-
-**Derived Prometheus metrics**: `rippled_load_factor`, `rippled_load_factor_fee_escalation`, etc.
-
-**Grafana dashboard**: Add "Load Factor Breakdown" panel to _Fee Market & TxQ_ dashboard.
-
----
-
-## Task 9.8: New Grafana Dashboards
-
-**Objective**: Create Grafana dashboards for the new metric categories.
-
-**What to do**:
-
-- Create 2 new dashboards:
-  1. **Fee Market & TxQ** (`rippled-fee-market`) — TxQ depth/capacity, fee levels, load factor breakdown, fee escalation timeline
-  2. **Job Queue Analysis** (`rippled-job-queue`) — Per-job-type rates, queue wait times, execution times, job queue depth
-
-- Update 2 existing dashboards:
-  1. **Node Health** (`rippled-statsd-node-health`) — Add NodeStore I/O panels, cache hit rate panels, object instance counts
-  2. **RPC Performance** (`rippled-rpc-perf`) — Add per-method RPC breakdown panels
-
-**Key modified files**:
-
-- New: `docker/telemetry/grafana/dashboards/rippled-fee-market.json`
-- New: `docker/telemetry/grafana/dashboards/rippled-job-queue.json`
-- `docker/telemetry/grafana/dashboards/rippled-statsd-node-health.json`
-- `docker/telemetry/grafana/dashboards/rippled-rpc-perf.json`
-
----
-
-## Task 9.9: Update Documentation
-
-**Objective**: Update telemetry reference docs with all new metrics.
-
-**What to do**:
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add new section for OTel SDK-exported metrics (NodeStore, cache, TxQ, PerfLog, CountedObjects, load factors)
-  - Update Grafana dashboard reference table (add 2 new dashboards)
-  - Add Prometheus query examples for new metrics
-
-- Update `docs/telemetry-runbook.md`:
-  - Add alerting rules for new metrics (NodeStore write_load, TxQ capacity, cache hit rate degradation)
-  - Add troubleshooting entries for new metric categories
-
-**Key modified files**:
-
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `docs/telemetry-runbook.md`
-
----
-
-## Task 9.10: Integration Tests
-
-**Objective**: Verify all new metrics appear in Prometheus after a test workload.
-
-**What to do**:
-
-- Extend the existing telemetry integration test:
-  - Start rippled with `[telemetry] enabled=1` and `[insight] server=otel`
-  - Submit a batch of RPC calls and transactions
-  - Query Prometheus for each new metric family
-  - Assert non-zero values for: NodeStore reads, cache hit rates, TxQ count, PerfLog RPC counters, object counts, load factors
-
-- Add unit tests for the `MetricsRegistry` class:
-  - Verify callback registration and deregistration
-  - Verify metric values match `get_counts` JSON output
-  - Verify graceful behavior when telemetry is disabled
-
-**Key modified files**:
-
-- `src/test/telemetry/MetricsRegistry_test.cpp` (new)
-- Existing integration test script (extend assertions)
-
----
-
-## Effort Summary
-
-| Task | Description                              | Effort | Risk   |
-| ---- | ---------------------------------------- | ------ | ------ |
-| 9.1  | NodeStore I/O metrics                    | 1d     | Low    |
-| 9.2  | Cache hit rate metrics + MetricsRegistry | 2d     | Medium |
-| 9.3  | TxQ metrics                              | 1d     | Low    |
-| 9.4  | PerfLog per-RPC metrics                  | 1.5d   | Medium |
-| 9.5  | PerfLog per-job metrics                  | 1d     | Low    |
-| 9.6  | Counted object instance metrics          | 0.5d   | Low    |
-| 9.7  | Fee escalation & load factor metrics     | 0.5d   | Low    |
-| 9.8  | New Grafana dashboards                   | 2d     | Low    |
-| 9.9  | Update documentation                     | 1d     | Low    |
-| 9.10 | Integration tests                        | 1.5d   | Medium |
-
-**Total Effort**: 12 days
-
-## Exit Criteria
-
-- [ ] All ~50 new metrics visible in Prometheus via OTLP pipeline
-- [ ] `MetricsRegistry` class registers/deregisters cleanly with OTel SDK
-- [ ] Async gauge callbacks execute at 10s intervals without performance impact
-- [ ] 2 new Grafana dashboards operational (Fee Market, Job Queue)
-- [ ] 2 existing dashboards updated with new panel groups
-- [ ] Integration test validates all new metric families are non-zero
-- [ ] No performance regression (< 0.5% CPU overhead from new callbacks)
-- [ ] Documentation updated with full new metric inventory

OpenTelemetryPlan/presentation.md

@@ -1,280 +0,0 @@
-# OpenTelemetry Distributed Tracing for rippled
-
----
-
-## Slide 1: Introduction
-
-### What is OpenTelemetry?
-
-OpenTelemetry is an open-source, CNCF-backed observability framework for distributed tracing, metrics, and logs.
-
-### Why OpenTelemetry for rippled?
-
-- **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`
-- **Consensus Round Analysis**: Understand timing and behavior across validators
-- **Incident Debugging**: Correlate events across distributed nodes during issues
-
-```mermaid
-flowchart LR
-    A["Node A<br/>tx.receive<br/>trace_id: abc123"] --> B["Node B<br/>tx.relay<br/>trace_id: abc123"] --> C["Node C<br/>tx.validate<br/>trace_id: abc123"] --> D["Node D<br/>ledger.apply<br/>trace_id: abc123"]
-
-    style A fill:#1565c0,stroke:#0d47a1,color:#fff
-    style B fill:#2e7d32,stroke:#1b5e20,color:#fff
-    style C fill:#2e7d32,stroke:#1b5e20,color:#fff
-    style D fill:#e65100,stroke:#bf360c,color:#fff
-```
-
-> **Trace ID: abc123** — All nodes share the same trace, enabling cross-node correlation.
-
----
-
-## Slide 2: OpenTelemetry vs Open Source Alternatives
-
-| Feature             | OpenTelemetry    | Jaeger           | Zipkin             | SkyWalking | Pinpoint   | Prometheus |
-| ------------------- | ---------------- | ---------------- | ------------------ | ---------- | ---------- | ---------- |
-| **Tracing**         | YES              | YES              | YES                | YES        | YES        | NO         |
-| **Metrics**         | YES              | NO               | NO                 | YES        | YES        | YES        |
-| **Logs**            | YES              | NO               | NO                 | YES        | NO         | NO         |
-| **C++ SDK**         | YES Official     | YES (Deprecated) | YES (Unmaintained) | NO         | NO         | YES        |
-| **Vendor Neutral**  | YES Primary goal | NO               | NO                 | NO         | NO         | NO         |
-| **Instrumentation** | Manual + Auto    | Manual           | Manual             | Auto-first | Auto-first | Manual     |
-| **Backend**         | Any (exporters)  | Self             | Self               | Self       | Self       | Self       |
-| **CNCF Status**     | Incubating       | Graduated        | NO                 | Incubating | NO         | Graduated  |
-
-> **Why OpenTelemetry?** It's the only actively maintained, full-featured C++ option with vendor neutrality — allowing export to Jaeger, Prometheus, Grafana, or any commercial backend without changing instrumentation.
-
----
-
-## Slide 3: Comparison with rippled's Existing Solutions
-
-### Current Observability Stack
-
-| Aspect                | PerfLog (JSON)        | StatsD (Metrics)      | OpenTelemetry (NEW)         |
-| --------------------- | --------------------- | --------------------- | --------------------------- |
-| **Type**              | Logging               | Metrics               | Distributed Tracing         |
-| **Scope**             | Single node           | Single node           | **Cross-node**              |
-| **Data**              | JSON log entries      | Counters, gauges      | Spans with context          |
-| **Correlation**       | By timestamp          | By metric name        | By `trace_id`               |
-| **Overhead**          | Low (file I/O)        | Low (UDP)             | Low-Medium (configurable)   |
-| **Question Answered** | "What happened here?" | "How many? How fast?" | **"What was the journey?"** |
-
-### Use Case Matrix
-
-| Scenario                         | PerfLog | StatsD | OpenTelemetry |
-| -------------------------------- | ------- | ------ | ------------- |
-| "How many TXs per second?"       | ❌      | ✅     | ❌            |
-| "Why was this specific TX slow?" | ⚠️      | ❌     | ✅            |
-| "Which node delayed consensus?"  | ❌      | ❌     | ✅            |
-| "Show TX journey across 5 nodes" | ❌      | ❌     | ✅            |
-
-> **Key Insight**: OpenTelemetry **complements** (not replaces) existing systems.
-
----
-
-## Slide 4: Architecture
-
-### High-Level Integration Architecture
-
-```mermaid
-flowchart TB
-    subgraph rippled["rippled Node"]
-        subgraph services["Core Services"]
-            direction LR
-            RPC["RPC Server<br/>(HTTP/WS)"] ~~~ Overlay["Overlay<br/>(P2P Network)"] ~~~ Consensus["Consensus<br/>(RCLConsensus)"]
-        end
-
-        Telemetry["Telemetry Module<br/>(OpenTelemetry SDK)"]
-
-        services --> Telemetry
-    end
-
-    Telemetry -->|OTLP/gRPC| Collector["OTel Collector"]
-
-    Collector --> Tempo["Grafana Tempo"]
-    Collector --> Jaeger["Jaeger"]
-    Collector --> Elastic["Elastic APM"]
-
-    style rippled 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
-```
-
-### Context Propagation
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant NodeA as Node A
-    participant NodeB as Node B
-
-    Client->>NodeA: Submit TX (no context)
-    Note over NodeA: Creates trace_id: abc123<br/>span: tx.receive
-    NodeA->>NodeB: Relay TX<br/>(traceparent: abc123)
-    Note over NodeB: Links to trace_id: abc123<br/>span: tx.relay
-```
-
-- **HTTP/RPC**: W3C Trace Context headers (`traceparent`)
-- **P2P Messages**: Protocol Buffer extension fields
-
----
-
-## Slide 5: Implementation Plan
-
-### 5-Phase Rollout (9 Weeks)
-
-```mermaid
-gantt
-    title Implementation Timeline
-    dateFormat  YYYY-MM-DD
-    axisFormat  Week %W
-
-    section Phase 1
-    Core Infrastructure    :p1, 2024-01-01, 2w
-
-    section Phase 2
-    RPC Tracing           :p2, after p1, 2w
-
-    section Phase 3
-    Transaction Tracing   :p3, after p2, 2w
-
-    section Phase 4
-    Consensus Tracing     :p4, after p3, 2w
-
-    section Phase 5
-    Documentation         :p5, after p4, 1w
-```
-
-### Phase Details
-
-| Phase | Focus               | Key Deliverables                             | Effort  |
-| ----- | ------------------- | -------------------------------------------- | ------- |
-| 1     | Core Infrastructure | SDK integration, Telemetry interface, Config | 10 days |
-| 2     | RPC Tracing         | HTTP context extraction, Handler spans       | 10 days |
-| 3     | Transaction Tracing | Protobuf context, P2P relay propagation      | 10 days |
-| 4     | Consensus Tracing   | Round spans, Proposal/validation tracing     | 10 days |
-| 5     | Documentation       | Runbook, Dashboards, Training                | 7 days  |
-
-**Total Effort**: ~47 developer-days (2 developers)
-
----
-
-## Slide 6: Performance Overhead
-
-### Estimated System Impact
-
-| Metric            | Overhead   | Notes                               |
-| ----------------- | ---------- | ----------------------------------- |
-| **CPU**           | 1-3%       | Span creation and attribute setting |
-| **Memory**        | 2-5 MB     | Batch buffer for pending spans      |
-| **Network**       | 10-50 KB/s | Compressed OTLP export to collector |
-| **Latency (p99)** | <2%        | With proper sampling configuration  |
-
-### Per-Message Overhead (Context Propagation)
-
-Each P2P message carries trace context with the following overhead:
-
-| Field         | Size          | Description                               |
-| ------------- | ------------- | ----------------------------------------- |
-| `trace_id`    | 16 bytes      | Unique identifier for the entire trace    |
-| `span_id`     | 8 bytes       | Current span (becomes parent on receiver) |
-| `trace_flags` | 4 bytes       | Sampling decision flags                   |
-| `trace_state` | 0-4 bytes     | Optional vendor-specific data             |
-| **Total**     | **~32 bytes** | **Added per traced P2P message**          |
-
-```mermaid
-flowchart LR
-    subgraph msg["P2P Message with Trace Context"]
-        A["Original Message<br/>(variable size)"] --> B["+ TraceContext<br/>(~32 bytes)"]
-    end
-
-    subgraph breakdown["Context Breakdown"]
-        C["trace_id<br/>16 bytes"]
-        D["span_id<br/>8 bytes"]
-        E["flags<br/>4 bytes"]
-        F["state<br/>0-4 bytes"]
-    end
-
-    B --> breakdown
-
-    style A fill:#424242,stroke:#212121,color:#fff
-    style B fill:#2e7d32,stroke:#1b5e20,color:#fff
-    style C fill:#1565c0,stroke:#0d47a1,color:#fff
-    style D fill:#1565c0,stroke:#0d47a1,color:#fff
-    style E fill:#e65100,stroke:#bf360c,color:#fff
-    style F fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-> **Note**: 32 bytes is negligible compared to typical transaction messages (hundreds to thousands of bytes)
-
-### Mitigation Strategies
-
-```mermaid
-flowchart LR
-    A["Head Sampling<br/>10% default"] --> B["Tail Sampling<br/>Keep errors/slow"] --> C["Batch Export<br/>Reduce I/O"] --> D["Conditional Compile<br/>XRPL_ENABLE_TELEMETRY"]
-
-    style A fill:#1565c0,stroke:#0d47a1,color:#fff
-    style B fill:#2e7d32,stroke:#1b5e20,color:#fff
-    style C fill:#e65100,stroke:#bf360c,color:#fff
-    style D fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-### Kill Switches (Rollback Options)
-
-1. **Config Disable**: Set `enabled=0` in config → instant disable, no restart needed for sampling
-2. **Rebuild**: Compile with `XRPL_ENABLE_TELEMETRY=OFF` → zero overhead (no-op)
-3. **Full Revert**: Clean separation allows easy commit reversion
-
----
-
-## Slide 7: Data Collection & Privacy
-
-### What Data is Collected
-
-| Category        | Attributes Collected                                                               | Purpose                     |
-| --------------- | ---------------------------------------------------------------------------------- | --------------------------- |
-| **Transaction** | `tx.hash`, `tx.type`, `tx.result`, `tx.fee`, `ledger_index`                        | Trace transaction lifecycle |
-| **Consensus**   | `round`, `phase`, `mode`, `proposers`(public key or public node id), `duration_ms` | Analyze consensus timing    |
-| **RPC**         | `command`, `version`, `status`, `duration_ms`                                      | Monitor RPC performance     |
-| **Peer**        | `peer.id`(public key), `latency_ms`, `message.type`, `message.size`                | Network topology analysis   |
-| **Ledger**      | `ledger.hash`, `ledger.index`, `close_time`, `tx_count`                            | Ledger progression tracking |
-| **Job**         | `job.type`, `queue_ms`, `worker`                                                   | JobQueue performance        |
-
-### What is NOT Collected (Privacy Guarantees)
-
-```mermaid
-flowchart LR
-    subgraph notCollected["❌ NOT Collected"]
-        direction LR
-        A["Private Keys"] ~~~ B["Account Balances"] ~~~ C["Transaction Amounts"]
-    end
-
-    subgraph alsoNot["❌ Also Excluded"]
-        direction LR
-        D["IP Addresses<br/>(configurable)"] ~~~ E["Personal Data"] ~~~ F["Raw TX Payloads"]
-    end
-
-    style A fill:#c62828,stroke:#8c2809,color:#fff
-    style B fill:#c62828,stroke:#8c2809,color:#fff
-    style C fill:#c62828,stroke:#8c2809,color:#fff
-    style D fill:#c62828,stroke:#8c2809,color:#fff
-    style E fill:#c62828,stroke:#8c2809,color:#fff
-    style F fill:#c62828,stroke:#8c2809,color:#fff
-```
-
-### Privacy Protection Mechanisms
-
-| Mechanism                  | Description                                                   |
-| -------------------------- | ------------------------------------------------------------- |
-| **Account Hashing**        | `xrpl.tx.account` is hashed at collector level before storage |
-| **Configurable Redaction** | Sensitive fields can be excluded via config                   |
-| **Sampling**               | Only 10% of traces recorded by default (reduces exposure)     |
-| **Local Control**          | Node operators control what gets exported                     |
-| **No Raw Payloads**        | Transaction content is never recorded, only metadata          |
-
-> **Key Principle**: Telemetry collects **operational metadata** (timing, counts, hashes) — never **sensitive content** (keys, balances, amounts).
-
----
-
-_End of Presentation_

SECURITY.md

@@ -42,7 +42,7 @@ For more information on responsible disclosure, please read this [Wikipedia arti
 
 ## 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.
+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 precommitment: 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:
 
@@ -78,61 +78,72 @@ 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` |
+| Short Key ID  | `0xC57929BE`                                        |
+|  Long Key ID  | `0xCD49A0AFC57929BE`                                |
+|  Fingerprint  | `24E6 3B02 37E0 FA9C 5E96 8974 CD49 A0AF C579 29BE` |
 
 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
+mQINBFUwGHYBEAC0wpGpBPkd8W1UdQjg9+cEFzeIEJRaoZoeuJD8mofwI5Ejnjdt
+kCpUYEDal0ygkKobu8SzOoATcDl18iCrScX39VpTm96vISFZMhmOryYCIp4QLJNN
+4HKc2ZdBj6W4igNi6vj5Qo6JMyGpLY2mz4CZskbt0TNuUxWrGood+UrCzpY8x7/N
+a93fcvNw+prgCr0rCH3hAPmAFfsOBbtGzNnmq7xf3jg5r4Z4sDiNIF1X1y53DAfV
+rWDx49IKsuCEJfPMp1MnBSvDvLaQ2hKXs+cOpx1BCZgHn3skouEUxxgqbtTzBLt1
+xXpmuijsaltWngPnGO7mOAzbpZSdBm82/Emrk9bPMuD0QaLQjWr7HkTSUs6ZsKt4
+7CLPdWqxyY/QVw9UaxeHEtWGQGMIQGgVJGh1fjtUr5O1sC9z9jXcQ0HuIHnRCTls
+GP7hklJmfH5V4SyAJQ06/hLuEhUJ7dn+BlqCsT0tLmYTgZYNzNcLHcqBFMEZHvHw
+9GENMx/tDXgajKql4bJnzuTK0iGU/YepanANLd1JHECJ4jzTtmKOus9SOGlB2/l1
+0t0ADDYAS3eqOdOcUvo9ElSLCI5vSVHhShSte/n2FMWU+kMUboTUisEG8CgQnrng
+g2CvvQvqDkeOtZeqMcC7HdiZS0q3LJUWtwA/ViwxrVlBDCxiTUXCotyBWwARAQAB
+tDBSaXBwbGUgTGFicyBCdWcgQm91bnR5IFByb2dyYW0gPGJ1Z3NAcmlwcGxlLmNv
+bT6JAjcEEwEKACEFAlUwGHYCGwMFCwkIBwMFFQoJCAsFFgIDAQACHgECF4AACgkQ
+zUmgr8V5Kb6R0g//SwY/mVJY59k87iL26/KayauSoOcz7xjcST26l4ZHVVX85gOY
+HYZl8k0+m8X3zxeYm9a3QAoAml8sfoaFRFQP8ynnefRrLUPaZ2MjbJ0SACMwZNef
+T6o7Mi8LBAaiNZdYVyIfX1oM6YXtqYkuJdav6ZCyvVYqc9OvMJPY2ZzJYuI/ZtvQ
+/lTndxCeg9ALNX/iezOLGdfMpf4HuIFVwcPPlwGi+HDlB9/bggDEHC8z434SXVFc
+aQatXAPcDkjMUweU7y0CZtYEj00HITd4pSX6MqGiHrxlDZTqinCOPs1Ieqp7qufs
+MzlM6irLGucxj1+wa16ieyYvEtGaPIsksUKkywx0O7cf8N2qKg+eIkUk6O0Uc6eO
+CszizmiXIXy4O6OiLlVHGKkXHMSW9Nwe9GE95O8G9WR8OZCEuDv+mHPAutO+IjdP
+PDAAUvy+3XnkceO+HGWRpVvJZfFP2YH4A33InFL5yqlJmSoR/yVingGLxk55bZDM
++HYGR3VeMb8Xj1rf/02qERsZyccMCFdAvKDbTwmvglyHdVLu5sPmktxbBYiemfyJ
+qxMxmYXCc9S0hWrWZW7edktBa9NpE58z1mx+hRIrDNbS2sDHrib9PULYCySyVYcF
+P+PWEe1CAS5jqkR2ker5td2/pHNnJIycynBEs7l6zbc9fu+nktFJz0q2B+GJAhwE
+EAEKAAYFAlUwGaQACgkQ+tiY1qQ2QkjMFw//f2hNY3BPNe+1qbhzumMDCnbTnGif
+kLuAGl9OKt81VHG1f6RnaGiLpR696+6Ja45KzH15cQ5JJl5Bgs1YkR/noTGX8IAD
+c70eNwiFu8JXTaaeeJrsmFkF9Tueufb364risYkvPP8tNUD3InBFEZT3WN7JKwix
+coD4/BwekUwOZVDd/uCFEyhlhZsROxdKNisNo3VtAq2s+3tIBAmTrriFUl0K+ZC5
+zgavcpnPN57zMtW9aK+VO3wXqAKYLYmtgxkVzSLUZt2M7JuwOaAdyuYWAneKZPCu
+1AXkmyo+d84sd5mZaKOr5xArAFiNMWPUcZL4rkS1Fq4dKtGAqzzR7a7hWtA5o27T
+6vynuxZ1n0PPh0er2O/zF4znIjm5RhTlfjp/VmhZdQfpulFEQ/dMxxGkQ9z5IYbX
+mTlSDbCSb+FMsanRBJ7Drp5EmBIudVGY6SHI5Re1RQiEh7GoDfUMUwZO+TVDII5R
+Ra7WyuimYleJgDo/+7HyfuIyGDaUCVj6pwVtYtYIdOI3tTw1R1Mr0V8yaNVnJghL
+CHcEJQL+YHSmiMM3ySil3O6tm1By6lFz8bVe/rgG/5uklQrnjMR37jYboi1orCC4
+yeIoQeV0ItlxeTyBwYIV/o1DBNxDevTZvJabC93WiGLw2XFjpZ0q/9+zI2rJUZJh
+qxmKP+D4e27lCI65Ag0EVTAYdgEQAMvttYNqeRNBRpSX8fk45WVIV8Fb21fWdwk6
+2SkZnJURbiC0LxQnOi7wrtii7DeFZtwM2kFHihS1VHekBnIKKZQSgGoKuFAQMGyu
+a426H4ZsSmA9Ufd7kRbvdtEcp7/RTAanhrSL4lkBhaKJrXlxBJ27o3nd7/rh7r3a
+OszbPY6DJ5bWClX3KooPTDl/RF2lHn+fweFk58UvuunHIyo4BWJUdilSXIjLun+P
+Qaik4ZAsZVwNhdNz05d+vtai4AwbYoO7adboMLRkYaXSQwGytkm+fM6r7OpXHYuS
+cR4zB/OK5hxCVEpWfiwN71N2NMvnEMaWd/9uhqxJzyvYgkVUXV9274TUe16pzXnW
+ZLfmitjwc91e7mJBBfKNenDdhaLEIlDRwKTLj7k58f9srpMnyZFacntu5pUMNblB
+cjXwWxz5ZaQikLnKYhIvrIEwtWPyjqOzNXNvYfZamve/LJ8HmWGCKao3QHoAIDvB
+9XBxrDyTJDpxbog6Qu4SY8AdgVlan6c/PsLDc7EUegeYiNTzsOK+eq3G5/E92eIu
+TsUXlciypFcRm1q8vLRr+HYYe2mJDo4GetB1zLkAFBcYJm/x9iJQbu0hn5NxJvZO
+R0Y5nOJQdyi+muJzKYwhkuzaOlswzqVXkq/7+QCjg7QsycdcwDjiQh3OrsgXHrwl
+M7gyafL9ABEBAAGJAh8EGAEKAAkFAlUwGHYCGwwACgkQzUmgr8V5Kb50BxAAhj9T
+TwmNrgRldTHszj+Qc+v8RWqV6j+R+zc0cn5XlUa6XFaXI1OFFg71H4dhCPEiYeN0
+IrnocyMNvCol+eKIlPKbPTmoixjQ4udPTR1DC1Bx1MyW5FqOrsgBl5t0e1VwEViM
+NspSStxu5Hsr6oWz2GD48lXZWJOgoL1RLs+uxjcyjySD/em2fOKASwchYmI+ezRv
+plfhAFIMKTSCN2pgVTEOaaz13M0U+MoprThqF1LWzkGkkC7n/1V1f5tn83BWiagG
+2N2Q4tHLfyouzMUKnX28kQ9sXfxwmYb2sA9FNIgxy+TdKU2ofLxivoWT8zS189z/
+Yj9fErmiMjns2FzEDX+bipAw55X4D/RsaFgC+2x2PDbxeQh6JalRA2Wjq32Ouubx
+u+I4QhEDJIcVwt9x6LPDuos1F+M5QW0AiUhKrZJ17UrxOtaquh/nPUL9T3l2qPUn
+1ChrZEEEhHO6vA8+jn0+cV9n5xEz30Str9iHnDQ5QyR5LyV4UBPgTdWyQzNVKA69
+KsSr9lbHEtQFRzGuBKwt6UlSFv9vPWWJkJit5XDKAlcKuGXj0J8OlltToocGElkF
++gEBZfoOWi/IBjRLrFW2cT3p36DTR5O1Ud/1DLnWRqgWNBLrbs2/KMKE6EnHttyD
+7Tz8SQkuxltX/yBXMV3Ddy0t6nWV2SZEfuxJAQI=
+=spg4
 -----END PGP PUBLIC KEY BLOCK-----
 ```

cfg/rippled-example.cfg

@@ -29,18 +29,18 @@
 #
 # Purpose
 #
-#   This file documents and provides examples of all xrpld server process
-#   configuration options. When the xrpld server instance is launched, it
+#   This file documents and provides examples of all rippled server process
+#   configuration options. When the rippled server instance is launched, it
 #   looks for a file with the following name:
 #
-#     xrpld.cfg
+#     rippled.cfg
 #
-#   For more information on where the xrpld server instance searches for the
+#   For more information on where the rippled server instance searches for the
 #   file, visit:
 #
 #     https://xrpl.org/commandline-usage.html#generic-options
 #
-#   This file should be named xrpld.cfg. This file is UTF-8 with DOS, UNIX,
+#   This file should be named rippled.cfg. This file is UTF-8 with DOS, UNIX,
 #   or Mac style end of lines. Blank lines and lines beginning with '#' are
 #   ignored. Undefined sections are reserved. No escapes are currently defined.
 #
@@ -89,8 +89,8 @@
 #
 #
 #
-#   xrpld offers various server protocols to clients making inbound
-#   connections. The listening ports xrpld uses are "universal" ports
+#   rippled offers various server protocols to clients making inbound
+#   connections. The listening ports rippled uses are "universal" ports
 #   which may be configured to handshake in one or more of the available
 #   supported protocols. These universal ports simplify administration:
 #   A single open port can be used for multiple protocols.
@@ -103,7 +103,7 @@
 #
 #   A list of port names and key/value pairs. A port name must start with a
 #   letter and contain only letters and numbers. The name is not case-sensitive.
-#   For each name in this list, xrpld will look for a configuration file
+#   For each name in this list, rippled will look for a configuration file
 #   section with the same name and use it to create a listening port. The
 #   name is informational only; the choice of name does not affect the function
 #   of the listening port.
@@ -134,7 +134,7 @@
 #       ip = 127.0.0.1
 #       protocol = http
 #
-#   When xrpld is used as a command line client (for example, issuing a
+#   When rippled is used as a command line client (for example, issuing a
 #   server stop command), the first port advertising the http or https
 #   protocol will be used to make the connection.
 #
@@ -175,7 +175,7 @@
 #       same time. It is possible have both Websockets and Secure Websockets
 #       together in one port.
 #
-#       NOTE    If no ports support the peer protocol, xrpld cannot
+#       NOTE    If no ports support the peer protocol, rippled cannot
 #               receive incoming peer connections or become a superpeer.
 #
 #   limit = <number>
@@ -194,7 +194,7 @@
 #       required. IP address restrictions, if any, will be checked in addition
 #       to the credentials specified here.
 #
-#       When acting in the client role, xrpld will supply these credentials
+#       When acting in the client role, rippled will supply these credentials
 #       using HTTP's Basic Authentication headers when making outbound HTTP/S
 #       requests.
 #
@@ -218,7 +218,7 @@
 #       administrative commands.
 #
 #       NOTE    A common configuration value for the admin field is "localhost".
-#               If you are listening on all IPv4/IPv6 addresses by specifying
+#               If you are listening on all IPv4/IPv6 addresses by specifing
 #               ip = :: then you can use admin = ::ffff:127.0.0.1,::1 to allow
 #               administrative access from both IPv4 and IPv6 localhost
 #               connections.
@@ -237,7 +237,7 @@
 #       WS, or WSS protocol interfaces. If administrative commands are
 #       disabled for a port, these credentials have no effect.
 #
-#       When acting in the client role, xrpld will supply these credentials
+#       When acting in the client role, rippled will supply these credentials
 #       in the submitted JSON for any administrative command requests when
 #       invoking JSON-RPC commands on remote servers.
 #
@@ -258,7 +258,7 @@
 #       resource controls will default to those for non-administrative users.
 #
 #       The secure_gateway IP addresses are intended to represent
-#       proxies. Since xrpld trusts these hosts, they must be
+#       proxies. Since rippled trusts these hosts, they must be
 #       responsible for properly authenticating the remote user.
 #
 #       If some IP addresses are included for both "admin" and
@@ -272,7 +272,7 @@
 #       Use the specified files when configuring SSL on the port.
 #
 #       NOTE    If no files are specified and secure protocols are selected,
-#               xrpld will generate an internal self-signed certificate.
+#               rippled will generate an internal self-signed certificate.
 #
 #       The files have these meanings:
 #
@@ -297,12 +297,12 @@
 #       Control the ciphers which the server will support over SSL on the port,
 #       specified using the OpenSSL "cipher list format".
 #
-#       NOTE    If unspecified, xrpld will automatically configure a modern
+#       NOTE    If unspecified, rippled will automatically configure a modern
 #               cipher suite. This default suite should be widely supported.
 #
 #               You should not modify this string unless you have a specific
 #               reason and cryptographic expertise. Incorrect modification may
-#               keep xrpld from connecting to other instances of xrpld or
+#               keep rippled from connecting to other instances of rippled or
 #               prevent RPC and WebSocket clients from connecting.
 #
 #   send_queue_limit = [1..65535]
@@ -382,7 +382,7 @@
 #-----------------
 #
 #   These settings control security and access attributes of the Peer to Peer
-#   server section of the xrpld process. Peer Protocol implements the
+#   server section of the rippled process. Peer Protocol implements the
 #   Ripple 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.
@@ -396,7 +396,7 @@
 #   true - enables compression
 #   false - disables compression [default].
 #
-#   The xrpld server can save bandwidth by compressing its peer-to-peer communications,
+#   The rippled server can save bandwidth by compressing its peer-to-peer communications,
 #   at a cost of greater CPU usage. If you enable link compression,
 #   the server automatically compresses communications with peer servers
 #   that also have link compression enabled.
@@ -432,7 +432,7 @@
 #
 # [ips_fixed]
 #
-#   List of IP addresses or hostnames to which xrpld should always attempt to
+#   List of IP addresses or hostnames to which rippled 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
@@ -573,7 +573,7 @@
 #
 #   minimum_txn_in_ledger_standalone = <number>
 #
-#       Like minimum_txn_in_ledger when xrpld is running in standalone
+#       Like minimum_txn_in_ledger when rippled is running in standalone
 #       mode. Default: 1000.
 #
 #   target_txn_in_ledger = <number>
@@ -710,7 +710,7 @@
 #
 # [validator_token]
 #
-#   This is an alternative to [validation_seed] that allows xrpld to perform
+#   This is an alternative to [validation_seed] that allows rippled to perform
 #   validation without having to store the validator keys on the network
 #   connected server. The field should contain a single token in the form of a
 #   base64-encoded blob.
@@ -745,7 +745,7 @@
 #
 #   Specify the file by its name or path.
 #   Unless an absolute path is specified, it will be considered relative to
-#   the folder in which the xrpld.cfg file is located.
+#   the folder in which the rippled.cfg file is located.
 #
 #   Examples:
 #    /home/ripple/validators.txt
@@ -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, a rippled 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.
@@ -851,7 +851,7 @@
 #
 #----------------
 #
-#   The xrpld server instance uses HTTPS GET requests in a variety of
+#   The rippled 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
 #   Network address.
@@ -891,7 +891,7 @@
 #
 #------------
 #
-#   xrpld creates 4 SQLite database to hold bookkeeping information
+#   rippled creates 4 SQLite database to hold bookkeeping information
 #   about transactions, local credentials, and various other things.
 #   It also creates the NodeDB, which holds all the objects that
 #   make up the current and historical ledgers.
@@ -902,7 +902,7 @@
 #   the performance of the server.
 #
 #   Partial pathnames will be considered relative to the location of
-#   the xrpld.cfg file.
+#   the rippled.cfg file.
 #
 #   [node_db]               Settings for the Node Database (required)
 #
@@ -920,11 +920,11 @@
 #   type = NuDB
 #
 #       NuDB is a high-performance database written by Ripple Labs and optimized
-#       for xrpld and solid-state drives.
+#       for rippled and solid-state drives.
 #
 #       NuDB maintains its high speed regardless of the amount of history
 #       stored. Online delete may be selected, but is not required. NuDB is
-#       available on all platforms that xrpld runs on.
+#       available on all platforms that rippled runs on.
 #
 #   type = RocksDB
 #
@@ -940,7 +940,23 @@
 #
 #       path                Location to store the database
 #
-#   Optional keys for NuDB and RocksDB:
+#   Optional keys
+#
+#       cache_size          Size of cache for database records. Default is 16384.
+#                           Setting this value to 0 will use the default value.
+#
+#       cache_age           Length of time in minutes to keep database records
+#                           cached. Default is 5 minutes. Setting this value to
+#                           0 will use the default value.
+#
+#                           Note: if neither cache_size nor cache_age is
+#                           specified, the cache for database records will not
+#                           be created. If only one of cache_size or cache_age
+#                           is specified, the cache will be created using the
+#                           default value for the unspecified parameter.
+#
+#                           Note: the cache will not be created if online_delete
+#                           is specified.
 #
 #       fast_load           Boolean. If set, load the last persisted ledger
 #                           from disk upon process start before syncing to
@@ -948,6 +964,8 @@
 #                           if sufficient IOPS capacity is available.
 #                           Default 0.
 #
+#   Optional keys for NuDB or RocksDB:
+#
 #       earliest_seq        The default is 32570 to match the XRP ledger
 #                           network's earliest allowed sequence. Alternate
 #                           networks may set this value. Minimum value of 1.
@@ -1031,7 +1049,7 @@
 #
 #       recovery_wait_seconds
 #                           The online delete process checks periodically
-#                           that xrpld is still in sync with the network,
+#                           that rippled is still in sync with the network,
 #                           and that the validated ledger is less than
 #                           'age_threshold_seconds' old. If not, then continue
 #                           sleeping for this number of seconds and
@@ -1051,8 +1069,8 @@
 #   The server creates and maintains 4 to 5 bookkeeping SQLite databases in
 #   the 'database_path' location. If you omit this configuration setting,
 #   the server creates a directory called "db" located in the same place as
-#   your xrpld.cfg file.
-#   Partial pathnames are relative to the location of the xrpld executable.
+#   your rippled.cfg file.
+#   Partial pathnames are relative to the location of the rippled executable.
 #
 #   [sqlite]       Tuning settings for the SQLite databases (optional)
 #
@@ -1102,7 +1120,7 @@
 #                           The default is "wal", which uses a write-ahead
 #                           log to implement database transactions.
 #                           Alternately, "memory" saves disk I/O, but if
-#                           xrpld crashes during a transaction, the
+#                           rippled crashes during a transaction, the
 #                           database is likely to be corrupted.
 #                           See https://www.sqlite.org/pragma.html#pragma_journal_mode
 #                           for more details about the available options.
@@ -1112,7 +1130,7 @@
 #       synchronous         Valid values: off, normal, full, extra
 #                           The default is "normal", which works well with
 #                           the "wal" journal mode. Alternatively, "off"
-#                           allows xrpld to continue as soon as data is
+#                           allows rippled to continue as soon as data is
 #                           passed to the OS, which can significantly
 #                           increase speed, but risks data corruption if
 #                           the host computer crashes before writing that
@@ -1126,7 +1144,7 @@
 #                           The default is "file", which will use files
 #                           for temporary database tables and indices.
 #                           Alternatively, "memory" may save I/O, but
-#                           xrpld does not currently use many, if any,
+#                           rippled does not currently use many, if any,
 #                           of these temporary objects.
 #                           See https://www.sqlite.org/pragma.html#pragma_temp_store
 #                           for more details about the available options.
@@ -1155,7 +1173,7 @@
 #
 #   These settings are designed to help server administrators diagnose
 #   problems, and obtain detailed information about the activities being
-#   performed by the xrpld process.
+#   performed by the rippled process.
 #
 #
 #
@@ -1172,7 +1190,7 @@
 #
 #   Configuration parameters for the Beast. Insight stats collection module.
 #
-#   Insight is a module that collects information from the areas of xrpld
+#   Insight is a module that collects information from the areas of rippled
 #   that have instrumentation. The configuration parameters control where the
 #   collection metrics are sent. The parameters are expressed as key = value
 #   pairs with no white space. The main parameter is the choice of server:
@@ -1181,7 +1199,7 @@
 #
 #       Choice of server to send metrics to. Currently the only choice is
 #       "statsd" which sends UDP packets to a StatsD daemon, which must be
-#       running while xrpld is running. More information on StatsD is
+#       running while rippled is running. More information on StatsD is
 #       available here:
 #           https://github.com/b/statsd_spec
 #
@@ -1191,7 +1209,7 @@
 #                 in the format, n.n.n.n:port.
 #
 #       "prefix"  A string prepended to each collected metric. This is used
-#                 to distinguish between different running instances of xrpld.
+#                 to distinguish between different running instances of rippled.
 #
 #     If this section is missing, or the server type is unspecified or unknown,
 #     statistics are not collected or reported.
@@ -1218,7 +1236,7 @@
 #
 #   Example:
 #     [perf]
-#     perf_log=/var/log/xrpld/perf.log
+#     perf_log=/var/log/rippled/perf.log
 #     log_interval=2
 #
 #-------------------------------------------------------------------------------
@@ -1228,7 +1246,7 @@
 #----------
 #
 #   The vote settings configure settings for the entire Ripple network.
-#   While a single instance of xrpld cannot unilaterally enforce network-wide
+#   While a single instance of rippled cannot unilaterally enforce network-wide
 #   settings, these choices become part of the instance's vote during the
 #   consensus process for each voting ledger.
 #
@@ -1242,7 +1260,7 @@
 #       The reference transaction is the simplest form of transaction.
 #       It represents an XRP payment between two parties.
 #
-#       If this parameter is unspecified, xrpld will use an internal
+#       If this parameter is unspecified, rippled will use an internal
 #       default. Don't change this without understanding the consequences.
 #
 #       Example:
@@ -1254,7 +1272,7 @@
 #       account's XRP balance that is at or below the reserve may only be
 #       spent on transaction fees, and not transferred out of the account.
 #
-#       If this parameter is unspecified, xrpld will use an internal
+#       If this parameter is unspecified, rippled will use an internal
 #       default. Don't change this without understanding the consequences.
 #
 #       Example:
@@ -1266,7 +1284,7 @@
 #       each ledger item owned by the account. Ledger items an account may
 #       own include trust lines, open orders, and tickets.
 #
-#       If this parameter is unspecified, xrpld will use an internal
+#       If this parameter is unspecified, rippled will use an internal
 #       default. Don't change this without understanding the consequences.
 #
 #       Example:
@@ -1308,7 +1326,7 @@
 #   tool instead.
 #
 #   This flag has no effect on the "sign" and "sign_for" command line options
-#   that xrpld makes available.
+#   that rippled makes available.
 #
 #   The default value of this field is "false"
 #
@@ -1387,7 +1405,7 @@
 #--------------------
 #
 #   Administrators can use these values as a starting point for configuring
-#   their instance of xrpld, but each value should be checked to make sure
+#   their instance of rippled, but each value should be checked to make sure
 #   it meets the business requirements for the organization.
 #
 # Server
@@ -1397,7 +1415,7 @@
 #   "peer"
 #
 #       Peer protocol open to everyone. This is required to accept
-#       incoming xrpld connections. This does not affect automatic
+#       incoming rippled connections. This does not affect automatic
 #       or manual outgoing Peer protocol connections.
 #
 #   "rpc"
@@ -1414,7 +1432,7 @@
 #
 #       ETL commands for Clio. We recommend setting secure_gateway
 #       in this section to a comma-separated list of the addresses
-#       of your Clio servers, in order to bypass xrpld's rate limiting.
+#       of your Clio servers, in order to bypass rippled's rate limiting.
 #
 #   This port is commented out but can be enabled by removing
 #   the '#' from each corresponding line including the entry under [server]
@@ -1431,8 +1449,8 @@
 #   NOTE
 #
 #       To accept connections on well known ports such as 80 (HTTP) or
-#       443 (HTTPS), most operating systems will require xrpld to
-#       run with administrator privileges, or else xrpld will not start.
+#       443 (HTTPS), most operating systems will require rippled to
+#       run with administrator privileges, or else rippled will not start.
 
 [server]
 port_rpc_admin_local
@@ -1478,7 +1496,7 @@ secure_gateway = 127.0.0.1
 
 #-------------------------------------------------------------------------------
 
-# This is primary persistent datastore for xrpld.  This includes transaction
+# This is primary persistent datastore for rippled.  This includes transaction
 # metadata, account states, and ledger headers.  Helpful information can be
 # found at https://xrpl.org/capacity-planning.html#node-db-type
 # type=NuDB is recommended for non-validators with fast SSDs. Validators or
@@ -1493,19 +1511,19 @@ secure_gateway = 127.0.0.1
 #    deletion.
 [node_db]
 type=NuDB
-path=/var/lib/xrpld/db/nudb
+path=/var/lib/rippled/db/nudb
 nudb_block_size=4096
 online_delete=512
 advisory_delete=0
 
 [database_path]
-/var/lib/xrpld/db
+/var/lib/rippled/db
 
 
 # This needs to be an absolute directory reference, not a relative one.
 # Modify this value as required.
 [debug_logfile]
-/var/log/xrpld/debug.log
+/var/log/rippled/debug.log
 
 # To use the XRP test network
 # (see https://xrpl.org/connect-your-rippled-to-the-xrp-test-net.html),
@@ -1515,7 +1533,7 @@ advisory_delete=0
 
 # File containing trusted validator keys or validator list publishers.
 # Unless an absolute path is specified, it will be considered relative to the
-# folder in which the xrpld.cfg file is located.
+# folder in which the rippled.cfg file is located.
 [validators_file]
 validators.txt
 
@@ -1529,46 +1547,3 @@ validators.txt
 # set to ssl_verify to 0.
 [ssl_verify]
 1
-#-------------------------------------------------------------------------------
-#
-# 11. Telemetry (OpenTelemetry Tracing)
-#
-#-------------------------------------------------------------------------------
-#
-# Enables distributed tracing via OpenTelemetry. Requires building with
-# -DXRPL_ENABLE_TELEMETRY=ON (telemetry Conan option).
-#
-# [telemetry]
-#
-# enabled=0
-#
-#   Enable or disable telemetry at runtime. Default: 0 (disabled).
-#
-# endpoint=http://localhost:4318/v1/traces
-#
-#   The OpenTelemetry Collector endpoint (OTLP/HTTP). Default: http://localhost:4318/v1/traces.
-#
-# exporter=otlp_http
-#
-#   Exporter type: otlp_http. Default: otlp_http.
-#
-# sampling_ratio=1.0
-#
-#   Fraction of traces to sample (0.0 to 1.0). Default: 1.0 (all traces).
-#
-# trace_rpc=1
-#
-#   Enable RPC request tracing. Default: 1.
-#
-# trace_transactions=1
-#
-#   Enable transaction lifecycle tracing. Default: 1.
-#
-# trace_consensus=1
-#
-#   Enable consensus round tracing. Default: 1.
-#
-# trace_peer=0
-#
-#   Enable peer message tracing (high volume). Default: 0.
-#

cfg/validators-example.txt

@@ -1,7 +1,7 @@
 #
 # Default validators.txt
 #
-# This file is located in the same folder as your xrpld.cfg file
+# This file is located in the same folder as your rippled.cfg file
 # and defines which validators your server trusts not to collude.
 #
 # This file is UTF-8 with DOS, UNIX, or Mac style line endings.

cmake/CMakeFuncs.cmake

@@ -1,32 +1,30 @@
-macro(exclude_from_default target_)
-    set_target_properties(${target_} PROPERTIES EXCLUDE_FROM_ALL ON)
-    set_target_properties(${target_} PROPERTIES EXCLUDE_FROM_DEFAULT_BUILD ON)
-endmacro()
+macro (exclude_from_default target_)
+  set_target_properties (${target_} PROPERTIES EXCLUDE_FROM_ALL ON)
+  set_target_properties (${target_} PROPERTIES EXCLUDE_FROM_DEFAULT_BUILD ON)
+endmacro ()
 
-macro(exclude_if_included target_)
-    get_directory_property(has_parent PARENT_DIRECTORY)
-    if(has_parent)
-        exclude_from_default(${target_})
-    endif()
-endmacro()
+macro (exclude_if_included target_)
+  get_directory_property(has_parent PARENT_DIRECTORY)
+  if (has_parent)
+    exclude_from_default (${target_})
+  endif ()
+endmacro ()
 
 find_package(Git)
 
-function(git_branch branch_val)
-    if(NOT GIT_FOUND)
-        return()
-    endif()
-    set(_branch "")
-    execute_process(
-        COMMAND ${GIT_EXECUTABLE} "rev-parse" "--abbrev-ref" "HEAD"
-        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-        RESULT_VARIABLE _git_exit_code
-        OUTPUT_VARIABLE _temp_branch
-        OUTPUT_STRIP_TRAILING_WHITESPACE
-        ERROR_QUIET
-    )
-    if(_git_exit_code EQUAL 0)
-        set(_branch ${_temp_branch})
-    endif()
-    set(${branch_val} "${_branch}" PARENT_SCOPE)
-endfunction()
+function (git_branch branch_val)
+  if (NOT GIT_FOUND)
+    return ()
+  endif ()
+  set (_branch "")
+  execute_process (COMMAND ${GIT_EXECUTABLE} "rev-parse" "--abbrev-ref" "HEAD"
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                   RESULT_VARIABLE _git_exit_code
+                   OUTPUT_VARIABLE _temp_branch
+                   OUTPUT_STRIP_TRAILING_WHITESPACE
+                   ERROR_QUIET)
+  if (_git_exit_code EQUAL 0)
+    set (_branch ${_temp_branch})
+  endif ()
+  set (${branch_val} "${_branch}" PARENT_SCOPE)
+endfunction ()

cmake/Ccache.cmake

@@ -1,62 +0,0 @@
-find_program(CCACHE_PATH "ccache")
-if(NOT CCACHE_PATH)
-    return()
-endif()
-
-# For Linux and macOS we can use the ccache binary directly.
-if(NOT MSVC)
-    set(CMAKE_C_COMPILER_LAUNCHER "${CCACHE_PATH}")
-    set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PATH}")
-    message(STATUS "Found ccache: ${CCACHE_PATH}")
-    return()
-endif()
-
-# For Windows more effort is required. The code below is a modified version of
-# https://github.com/ccache/ccache/wiki/MS-Visual-Studio#usage-with-cmake.
-if("${CCACHE_PATH}" MATCHES "chocolatey")
-    message(DEBUG "Ccache path: ${CCACHE_PATH}")
-    # Chocolatey uses a shim executable that we cannot use directly, in which case we have to find the executable it
-    # points to. If we cannot find the target executable then we cannot use ccache.
-    find_program(BASH_PATH "bash")
-    if(NOT BASH_PATH)
-        message(WARNING "Could not find bash.")
-        return()
-    endif()
-
-    execute_process(
-        COMMAND
-            bash -c
-            "export LC_ALL='en_US.UTF-8'; ${CCACHE_PATH} --shimgen-noop | grep -oP 'path to executable: \\K.+' | head -c -1"
-        OUTPUT_VARIABLE CCACHE_PATH
-    )
-
-    if(NOT CCACHE_PATH)
-        message(WARNING "Could not find ccache target.")
-        return()
-    endif()
-    file(TO_CMAKE_PATH "${CCACHE_PATH}" CCACHE_PATH)
-endif()
-message(STATUS "Found ccache: ${CCACHE_PATH}")
-
-# Tell cmake to use ccache for compiling with Visual Studio.
-file(COPY_FILE ${CCACHE_PATH} ${CMAKE_BINARY_DIR}/cl.exe ONLY_IF_DIFFERENT)
-set(CMAKE_VS_GLOBALS
-    "CLToolExe=cl.exe"
-    "CLToolPath=${CMAKE_BINARY_DIR}"
-    "TrackFileAccess=false"
-    "UseMultiToolTask=true"
-)
-
-# By default Visual Studio generators will use /Zi to capture debug information, which is not compatible with ccache, so
-# tell it to use /Z7 instead.
-if(MSVC)
-    foreach(
-        var_
-        CMAKE_C_FLAGS_DEBUG
-        CMAKE_C_FLAGS_RELEASE
-        CMAKE_CXX_FLAGS_DEBUG
-        CMAKE_CXX_FLAGS_RELEASE
-    )
-        string(REPLACE "/Zi" "/Z7" ${var_} "${${var_}}")
-    endforeach()
-endif()

cmake/CodeCoverage.cmake

@@ -172,49 +172,44 @@ include(CMakeParseArguments)
 option(CODE_COVERAGE_VERBOSE "Verbose information" FALSE)
 
 # Check prereqs
-find_program(GCOVR_PATH gcovr PATHS ${CMAKE_SOURCE_DIR}/scripts/test)
+find_program( GCOVR_PATH gcovr PATHS ${CMAKE_SOURCE_DIR}/scripts/test)
 
 if(DEFINED CODE_COVERAGE_GCOV_TOOL)
-    set(GCOV_TOOL "${CODE_COVERAGE_GCOV_TOOL}")
+  set(GCOV_TOOL "${CODE_COVERAGE_GCOV_TOOL}")
 elseif(DEFINED ENV{CODE_COVERAGE_GCOV_TOOL})
-    set(GCOV_TOOL "$ENV{CODE_COVERAGE_GCOV_TOOL}")
+  set(GCOV_TOOL "$ENV{CODE_COVERAGE_GCOV_TOOL}")
 elseif("${CMAKE_CXX_COMPILER_ID}" MATCHES "(Apple)?[Cc]lang")
-    if(APPLE)
-        execute_process(
-            COMMAND xcrun -f llvm-cov
-            OUTPUT_VARIABLE LLVMCOV_PATH
-            OUTPUT_STRIP_TRAILING_WHITESPACE
-        )
-    else()
-        find_program(LLVMCOV_PATH llvm-cov)
-    endif()
-    if(LLVMCOV_PATH)
-        set(GCOV_TOOL "${LLVMCOV_PATH} gcov")
-    endif()
+  if(APPLE)
+    execute_process( COMMAND xcrun -f llvm-cov
+      OUTPUT_VARIABLE LLVMCOV_PATH
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+  else()
+    find_program( LLVMCOV_PATH llvm-cov )
+  endif()
+  if(LLVMCOV_PATH)
+    set(GCOV_TOOL "${LLVMCOV_PATH} gcov")
+  endif()
 elseif("${CMAKE_CXX_COMPILER_ID}" MATCHES "GNU")
-    find_program(GCOV_PATH gcov)
-    set(GCOV_TOOL "${GCOV_PATH}")
+  find_program( GCOV_PATH gcov )
+  set(GCOV_TOOL "${GCOV_PATH}")
 endif()
 
 # Check supported compiler (Clang, GNU and Flang)
 get_property(LANGUAGES GLOBAL PROPERTY ENABLED_LANGUAGES)
 foreach(LANG ${LANGUAGES})
-    if("${CMAKE_${LANG}_COMPILER_ID}" MATCHES "(Apple)?[Cc]lang")
-        if("${CMAKE_${LANG}_COMPILER_VERSION}" VERSION_LESS 3)
-            message(
-                FATAL_ERROR
-                "Clang version must be 3.0.0 or greater! Aborting..."
-            )
-        endif()
-    elseif(
-        NOT "${CMAKE_${LANG}_COMPILER_ID}" MATCHES "GNU"
-        AND NOT "${CMAKE_${LANG}_COMPILER_ID}" MATCHES "(LLVM)?[Ff]lang"
-    )
-        message(FATAL_ERROR "Compiler is not GNU or Flang! Aborting...")
+  if("${CMAKE_${LANG}_COMPILER_ID}" MATCHES "(Apple)?[Cc]lang")
+    if("${CMAKE_${LANG}_COMPILER_VERSION}" VERSION_LESS 3)
+      message(FATAL_ERROR "Clang version must be 3.0.0 or greater! Aborting...")
     endif()
+  elseif(NOT "${CMAKE_${LANG}_COMPILER_ID}" MATCHES "GNU"
+         AND NOT "${CMAKE_${LANG}_COMPILER_ID}" MATCHES "(LLVM)?[Ff]lang")
+    message(FATAL_ERROR "Compiler is not GNU or Flang! Aborting...")
+  endif()
 endforeach()
 
-set(COVERAGE_COMPILER_FLAGS "-g --coverage" CACHE INTERNAL "")
+set(COVERAGE_COMPILER_FLAGS "-g --coverage"
+    CACHE INTERNAL "")
 
 set(COVERAGE_CXX_COMPILER_FLAGS "")
 set(COVERAGE_C_COMPILER_FLAGS "")
@@ -233,75 +228,49 @@ if(CMAKE_CXX_COMPILER_ID MATCHES "(GNU|Clang)")
 
     check_cxx_compiler_flag(-fprofile-abs-path HAVE_cxx_fprofile_abs_path)
     if(HAVE_cxx_fprofile_abs_path)
-        set(COVERAGE_CXX_COMPILER_FLAGS
-            "${COVERAGE_CXX_COMPILER_FLAGS} -fprofile-abs-path"
-        )
+        set(COVERAGE_CXX_COMPILER_FLAGS "${COVERAGE_CXX_COMPILER_FLAGS} -fprofile-abs-path")
     endif()
 
     check_c_compiler_flag(-fprofile-abs-path HAVE_c_fprofile_abs_path)
     if(HAVE_c_fprofile_abs_path)
-        set(COVERAGE_C_COMPILER_FLAGS
-            "${COVERAGE_C_COMPILER_FLAGS} -fprofile-abs-path"
-        )
+        set(COVERAGE_C_COMPILER_FLAGS "${COVERAGE_C_COMPILER_FLAGS} -fprofile-abs-path")
     endif()
 
     check_linker_flag(CXX -fprofile-abs-path HAVE_cxx_linker_fprofile_abs_path)
     if(HAVE_cxx_linker_fprofile_abs_path)
-        set(COVERAGE_CXX_LINKER_FLAGS
-            "${COVERAGE_CXX_LINKER_FLAGS} -fprofile-abs-path"
-        )
+        set(COVERAGE_CXX_LINKER_FLAGS "${COVERAGE_CXX_LINKER_FLAGS} -fprofile-abs-path")
     endif()
 
     check_linker_flag(C -fprofile-abs-path HAVE_c_linker_fprofile_abs_path)
     if(HAVE_c_linker_fprofile_abs_path)
-        set(COVERAGE_C_LINKER_FLAGS
-            "${COVERAGE_C_LINKER_FLAGS} -fprofile-abs-path"
-        )
+        set(COVERAGE_C_LINKER_FLAGS "${COVERAGE_C_LINKER_FLAGS} -fprofile-abs-path")
     endif()
 
     check_cxx_compiler_flag(-fprofile-update=atomic HAVE_cxx_fprofile_update)
     if(HAVE_cxx_fprofile_update)
-        set(COVERAGE_CXX_COMPILER_FLAGS
-            "${COVERAGE_CXX_COMPILER_FLAGS}  -fprofile-update=atomic"
-        )
+        set(COVERAGE_CXX_COMPILER_FLAGS "${COVERAGE_CXX_COMPILER_FLAGS}  -fprofile-update=atomic")
     endif()
 
     check_c_compiler_flag(-fprofile-update=atomic HAVE_c_fprofile_update)
     if(HAVE_c_fprofile_update)
-        set(COVERAGE_C_COMPILER_FLAGS
-            "${COVERAGE_C_COMPILER_FLAGS} -fprofile-update=atomic"
-        )
+        set(COVERAGE_C_COMPILER_FLAGS "${COVERAGE_C_COMPILER_FLAGS} -fprofile-update=atomic")
     endif()
 
-    check_linker_flag(
-        CXX
-        -fprofile-update=atomic
-        HAVE_cxx_linker_fprofile_update
-    )
+    check_linker_flag(CXX -fprofile-update=atomic HAVE_cxx_linker_fprofile_update)
     if(HAVE_cxx_linker_fprofile_update)
-        set(COVERAGE_CXX_LINKER_FLAGS
-            "${COVERAGE_CXX_LINKER_FLAGS} -fprofile-update=atomic"
-        )
+        set(COVERAGE_CXX_LINKER_FLAGS "${COVERAGE_CXX_LINKER_FLAGS} -fprofile-update=atomic")
     endif()
 
     check_linker_flag(C -fprofile-update=atomic HAVE_c_linker_fprofile_update)
     if(HAVE_c_linker_fprofile_update)
-        set(COVERAGE_C_LINKER_FLAGS
-            "${COVERAGE_C_LINKER_FLAGS} -fprofile-update=atomic"
-        )
+        set(COVERAGE_C_LINKER_FLAGS "${COVERAGE_C_LINKER_FLAGS} -fprofile-update=atomic")
     endif()
+
 endif()
 
-get_property(
-    GENERATOR_IS_MULTI_CONFIG
-    GLOBAL
-    PROPERTY GENERATOR_IS_MULTI_CONFIG
-)
+get_property(GENERATOR_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
 if(NOT (CMAKE_BUILD_TYPE STREQUAL "Debug" OR GENERATOR_IS_MULTI_CONFIG))
-    message(
-        WARNING
-        "Code coverage results with an optimised (non-Debug) build may be misleading"
-    )
+    message(WARNING "Code coverage results with an optimised (non-Debug) build may be misleading")
 endif() # NOT (CMAKE_BUILD_TYPE STREQUAL "Debug" OR GENERATOR_IS_MULTI_CONFIG)
 
 # Defines a target for running and collection code coverage information
@@ -330,13 +299,7 @@ function(setup_target_for_coverage_gcovr)
     set(options NONE)
     set(oneValueArgs BASE_DIRECTORY NAME FORMAT)
     set(multiValueArgs EXCLUDE EXECUTABLE EXECUTABLE_ARGS DEPENDENCIES)
-    cmake_parse_arguments(
-        Coverage
-        "${options}"
-        "${oneValueArgs}"
-        "${multiValueArgs}"
-        ${ARGN}
-    )
+    cmake_parse_arguments(Coverage "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
     if(NOT GCOV_TOOL)
         message(FATAL_ERROR "Could not find gcov or llvm-cov tool! Aborting...")
@@ -358,33 +321,21 @@ function(setup_target_for_coverage_gcovr)
     endif()
 
     if(NOT DEFINED Coverage_EXECUTABLE AND DEFINED Coverage_EXECUTABLE_ARGS)
-        message(
-            FATAL_ERROR
-            "EXECUTABLE_ARGS must not be set if EXECUTABLE is not set"
-        )
+        message(FATAL_ERROR "EXECUTABLE_ARGS must not be set if EXECUTABLE is not set")
     endif()
 
     if("--output" IN_LIST GCOVR_ADDITIONAL_ARGS)
-        message(
-            FATAL_ERROR
-            "Unsupported --output option detected in GCOVR_ADDITIONAL_ARGS! Aborting..."
-        )
+        message(FATAL_ERROR "Unsupported --output option detected in GCOVR_ADDITIONAL_ARGS! Aborting...")
     else()
-        if(
-            (Coverage_FORMAT STREQUAL "html-details")
-            OR (Coverage_FORMAT STREQUAL "html-nested")
-        )
-            set(GCOVR_OUTPUT_FILE
-                ${PROJECT_BINARY_DIR}/${Coverage_NAME}/index.html
-            )
+        if((Coverage_FORMAT STREQUAL "html-details")
+            OR (Coverage_FORMAT STREQUAL "html-nested"))
+            set(GCOVR_OUTPUT_FILE ${PROJECT_BINARY_DIR}/${Coverage_NAME}/index.html)
             set(GCOVR_CREATE_FOLDER ${PROJECT_BINARY_DIR}/${Coverage_NAME})
         elseif(Coverage_FORMAT STREQUAL "html-single")
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.html)
-        elseif(
-            (Coverage_FORMAT STREQUAL "json-summary")
+        elseif((Coverage_FORMAT STREQUAL "json-summary")
             OR (Coverage_FORMAT STREQUAL "json-details")
-            OR (Coverage_FORMAT STREQUAL "coveralls")
-        )
+            OR (Coverage_FORMAT STREQUAL "coveralls"))
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.json)
         elseif(Coverage_FORMAT STREQUAL "txt")
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.txt)
@@ -397,65 +348,50 @@ function(setup_target_for_coverage_gcovr)
         endif()
     endif()
 
-    if(
-        (Coverage_FORMAT STREQUAL "cobertura")
-        OR (Coverage_FORMAT STREQUAL "xml")
-    )
-        list(APPEND GCOVR_ADDITIONAL_ARGS --cobertura "${GCOVR_OUTPUT_FILE}")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --cobertura-pretty)
+    if((Coverage_FORMAT STREQUAL "cobertura")
+        OR (Coverage_FORMAT STREQUAL "xml"))
+        list(APPEND GCOVR_ADDITIONAL_ARGS --cobertura "${GCOVR_OUTPUT_FILE}" )
+        list(APPEND GCOVR_ADDITIONAL_ARGS --cobertura-pretty )
         set(Coverage_FORMAT cobertura) # overwrite xml
     elseif(Coverage_FORMAT STREQUAL "sonarqube")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --sonarqube "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --sonarqube "${GCOVR_OUTPUT_FILE}" )
     elseif(Coverage_FORMAT STREQUAL "jacoco")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --jacoco "${GCOVR_OUTPUT_FILE}")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --jacoco-pretty)
+        list(APPEND GCOVR_ADDITIONAL_ARGS --jacoco "${GCOVR_OUTPUT_FILE}" )
+        list(APPEND GCOVR_ADDITIONAL_ARGS --jacoco-pretty )
     elseif(Coverage_FORMAT STREQUAL "clover")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --clover "${GCOVR_OUTPUT_FILE}")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --clover-pretty)
+        list(APPEND GCOVR_ADDITIONAL_ARGS --clover "${GCOVR_OUTPUT_FILE}" )
+        list(APPEND GCOVR_ADDITIONAL_ARGS --clover-pretty )
     elseif(Coverage_FORMAT STREQUAL "lcov")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --lcov "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --lcov "${GCOVR_OUTPUT_FILE}" )
     elseif(Coverage_FORMAT STREQUAL "json-summary")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --json-summary "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --json-summary "${GCOVR_OUTPUT_FILE}" )
         list(APPEND GCOVR_ADDITIONAL_ARGS --json-summary-pretty)
     elseif(Coverage_FORMAT STREQUAL "json-details")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --json "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --json "${GCOVR_OUTPUT_FILE}" )
         list(APPEND GCOVR_ADDITIONAL_ARGS --json-pretty)
     elseif(Coverage_FORMAT STREQUAL "coveralls")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --coveralls "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --coveralls "${GCOVR_OUTPUT_FILE}" )
         list(APPEND GCOVR_ADDITIONAL_ARGS --coveralls-pretty)
     elseif(Coverage_FORMAT STREQUAL "csv")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --csv "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --csv "${GCOVR_OUTPUT_FILE}" )
     elseif(Coverage_FORMAT STREQUAL "txt")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --txt "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --txt "${GCOVR_OUTPUT_FILE}" )
     elseif(Coverage_FORMAT STREQUAL "html-single")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --html "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --html "${GCOVR_OUTPUT_FILE}" )
         list(APPEND GCOVR_ADDITIONAL_ARGS --html-self-contained)
     elseif(Coverage_FORMAT STREQUAL "html-nested")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --html-nested "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --html-nested "${GCOVR_OUTPUT_FILE}" )
     elseif(Coverage_FORMAT STREQUAL "html-details")
-        list(APPEND GCOVR_ADDITIONAL_ARGS --html-details "${GCOVR_OUTPUT_FILE}")
+        list(APPEND GCOVR_ADDITIONAL_ARGS --html-details "${GCOVR_OUTPUT_FILE}" )
     else()
-        message(
-            FATAL_ERROR
-            "Unsupported output style ${Coverage_FORMAT}! Aborting..."
-        )
+        message(FATAL_ERROR "Unsupported output style ${Coverage_FORMAT}! Aborting...")
     endif()
 
     # Collect excludes (CMake 3.4+: Also compute absolute paths)
     set(GCOVR_EXCLUDES "")
-    foreach(
-        EXCLUDE
-        ${Coverage_EXCLUDE}
-        ${COVERAGE_EXCLUDES}
-        ${COVERAGE_GCOVR_EXCLUDES}
-    )
+    foreach(EXCLUDE ${Coverage_EXCLUDE} ${COVERAGE_EXCLUDES} ${COVERAGE_GCOVR_EXCLUDES})
         if(CMAKE_VERSION VERSION_GREATER 3.4)
-            get_filename_component(
-                EXCLUDE
-                ${EXCLUDE}
-                ABSOLUTE
-                BASE_DIR ${BASEDIR}
-            )
+            get_filename_component(EXCLUDE ${EXCLUDE} ABSOLUTE BASE_DIR ${BASEDIR})
         endif()
         list(APPEND GCOVR_EXCLUDES "${EXCLUDE}")
     endforeach()
@@ -473,29 +409,22 @@ function(setup_target_for_coverage_gcovr)
     # before running the coverage target NAME
     if(DEFINED Coverage_EXECUTABLE)
         set(GCOVR_EXEC_TESTS_CMD
-            ${Coverage_EXECUTABLE}
-            ${Coverage_EXECUTABLE_ARGS}
+            ${Coverage_EXECUTABLE} ${Coverage_EXECUTABLE_ARGS}
         )
     endif()
 
     # Create folder
     if(DEFINED GCOVR_CREATE_FOLDER)
         set(GCOVR_FOLDER_CMD
-            ${CMAKE_COMMAND}
-            -E
-            make_directory
-            ${GCOVR_CREATE_FOLDER}
-        )
+            ${CMAKE_COMMAND} -E make_directory ${GCOVR_CREATE_FOLDER})
     endif()
 
     # Running gcovr
     set(GCOVR_CMD
         ${GCOVR_PATH}
-        --gcov-executable
-        ${GCOV_TOOL}
+        --gcov-executable ${GCOV_TOOL}
         --gcov-ignore-parse-errors=negative_hits.warn_once_per_file
-        -r
-        ${BASEDIR}
+        -r ${BASEDIR}
         ${GCOVR_ADDITIONAL_ARGS}
         ${GCOVR_EXCLUDE_ARGS}
         --object-directory=${PROJECT_BINARY_DIR}
@@ -506,23 +435,13 @@ function(setup_target_for_coverage_gcovr)
 
         if(NOT "${GCOVR_EXEC_TESTS_CMD}" STREQUAL "")
             message(STATUS "Command to run tests: ")
-            string(
-                REPLACE ";"
-                " "
-                GCOVR_EXEC_TESTS_CMD_SPACED
-                "${GCOVR_EXEC_TESTS_CMD}"
-            )
+            string(REPLACE ";" " " GCOVR_EXEC_TESTS_CMD_SPACED "${GCOVR_EXEC_TESTS_CMD}")
             message(STATUS "${GCOVR_EXEC_TESTS_CMD_SPACED}")
         endif()
 
         if(NOT "${GCOVR_FOLDER_CMD}" STREQUAL "")
             message(STATUS "Command to create a folder: ")
-            string(
-                REPLACE ";"
-                " "
-                GCOVR_FOLDER_CMD_SPACED
-                "${GCOVR_FOLDER_CMD}"
-            )
+            string(REPLACE ";" " " GCOVR_FOLDER_CMD_SPACED "${GCOVR_FOLDER_CMD}")
             message(STATUS "${GCOVR_FOLDER_CMD_SPACED}")
         endif()
 
@@ -531,11 +450,11 @@ function(setup_target_for_coverage_gcovr)
         message(STATUS "${GCOVR_CMD_SPACED}")
     endif()
 
-    add_custom_target(
-        ${Coverage_NAME}
+    add_custom_target(${Coverage_NAME}
         COMMAND ${GCOVR_EXEC_TESTS_CMD}
         COMMAND ${GCOVR_FOLDER_CMD}
         COMMAND ${GCOVR_CMD}
+
         BYPRODUCTS ${GCOVR_OUTPUT_FILE}
         WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
         DEPENDS ${Coverage_DEPENDENCIES}
@@ -544,49 +463,25 @@ function(setup_target_for_coverage_gcovr)
     )
 
     # Show info where to find the report
-    add_custom_command(
-        TARGET ${Coverage_NAME}
-        POST_BUILD
+    add_custom_command(TARGET ${Coverage_NAME} POST_BUILD
         COMMAND echo
-        COMMENT
-            "Code coverage report saved in ${GCOVR_OUTPUT_FILE} formatted as ${Coverage_FORMAT}"
+        COMMENT "Code coverage report saved in ${GCOVR_OUTPUT_FILE} formatted as ${Coverage_FORMAT}"
     )
 endfunction() # setup_target_for_coverage_gcovr
 
 function(add_code_coverage_to_target name scope)
-    separate_arguments(
-        COVERAGE_CXX_COMPILER_FLAGS
-        NATIVE_COMMAND
-        "${COVERAGE_CXX_COMPILER_FLAGS}"
-    )
-    separate_arguments(
-        COVERAGE_C_COMPILER_FLAGS
-        NATIVE_COMMAND
-        "${COVERAGE_C_COMPILER_FLAGS}"
-    )
-    separate_arguments(
-        COVERAGE_CXX_LINKER_FLAGS
-        NATIVE_COMMAND
-        "${COVERAGE_CXX_LINKER_FLAGS}"
-    )
-    separate_arguments(
-        COVERAGE_C_LINKER_FLAGS
-        NATIVE_COMMAND
-        "${COVERAGE_C_LINKER_FLAGS}"
-    )
+    separate_arguments(COVERAGE_CXX_COMPILER_FLAGS NATIVE_COMMAND "${COVERAGE_CXX_COMPILER_FLAGS}")
+    separate_arguments(COVERAGE_C_COMPILER_FLAGS NATIVE_COMMAND "${COVERAGE_C_COMPILER_FLAGS}")
+    separate_arguments(COVERAGE_CXX_LINKER_FLAGS NATIVE_COMMAND "${COVERAGE_CXX_LINKER_FLAGS}")
+    separate_arguments(COVERAGE_C_LINKER_FLAGS NATIVE_COMMAND "${COVERAGE_C_LINKER_FLAGS}")
 
     # Add compiler options to the target
-    target_compile_options(
-        ${name}
-        ${scope}
-        $<$<COMPILE_LANGUAGE:CXX>:${COVERAGE_CXX_COMPILER_FLAGS}>
-        $<$<COMPILE_LANGUAGE:C>:${COVERAGE_C_COMPILER_FLAGS}>
-    )
+    target_compile_options(${name} ${scope}
+            $<$<COMPILE_LANGUAGE:CXX>:${COVERAGE_CXX_COMPILER_FLAGS}>
+            $<$<COMPILE_LANGUAGE:C>:${COVERAGE_C_COMPILER_FLAGS}>)
 
-    target_link_libraries(
-        ${name}
-        ${scope}
-        $<$<LINK_LANGUAGE:CXX>:${COVERAGE_CXX_LINKER_FLAGS}>
-        $<$<LINK_LANGUAGE:C>:${COVERAGE_C_LINKER_FLAGS}>
+    target_link_libraries (${name} ${scope}
+            $<$<LINK_LANGUAGE:CXX>:${COVERAGE_CXX_LINKER_FLAGS} gcov>
+            $<$<LINK_LANGUAGE:C>:${COVERAGE_C_LINKER_FLAGS} gcov>
     )
 endfunction() # add_code_coverage_to_target

cmake/CompilationEnv.cmake

@@ -1,58 +0,0 @@
-# Shared detection of compiler, operating system, and architecture.
-#
-# This module centralizes environment detection so that other CMake modules can use the same variables instead of
-# repeating checks on CMAKE_* and built-in platform variables.
-
-# Only run once per configure step.
-include_guard(GLOBAL)
-
-# --------------------------------------------------------------------
-# Compiler detection (C++)
-# --------------------------------------------------------------------
-set(is_clang FALSE)
-set(is_gcc FALSE)
-set(is_msvc FALSE)
-set(is_xcode FALSE)
-
-if(CMAKE_CXX_COMPILER_ID MATCHES ".*Clang") # Clang or AppleClang
-    set(is_clang TRUE)
-elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-    set(is_gcc TRUE)
-elseif(MSVC)
-    set(is_msvc TRUE)
-else()
-    message(FATAL_ERROR "Unsupported C++ compiler: ${CMAKE_CXX_COMPILER_ID}")
-endif()
-
-# Xcode generator detection
-if(CMAKE_GENERATOR STREQUAL "Xcode")
-    set(is_xcode TRUE)
-endif()
-
-# --------------------------------------------------------------------
-# Operating system detection
-# --------------------------------------------------------------------
-set(is_linux FALSE)
-set(is_windows FALSE)
-set(is_macos FALSE)
-
-if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
-    set(is_linux TRUE)
-elseif(CMAKE_SYSTEM_NAME STREQUAL "Windows")
-    set(is_windows TRUE)
-elseif(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
-    set(is_macos TRUE)
-endif()
-
-# --------------------------------------------------------------------
-# Architecture
-# --------------------------------------------------------------------
-set(is_amd64 FALSE)
-set(is_arm64 FALSE)
-if(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64")
-    set(is_amd64 TRUE)
-elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64|ARM64")
-    set(is_arm64 TRUE)
-else()
-    message(FATAL_ERROR "Unknown architecture: ${CMAKE_SYSTEM_PROCESSOR}")
-endif()

cmake/GitInfo.cmake

@@ -1,28 +0,0 @@
-include_guard()
-
-set(GIT_BUILD_BRANCH "")
-set(GIT_COMMIT_HASH "")
-
-find_package(Git)
-if(NOT Git_FOUND)
-    message(WARNING "Git not found. Git branch and commit hash will be empty.")
-    return()
-endif()
-
-set(GIT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/.git)
-
-execute_process(
-    COMMAND
-        ${GIT_EXECUTABLE} --git-dir=${GIT_DIRECTORY} rev-parse --abbrev-ref HEAD
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-    OUTPUT_VARIABLE GIT_BUILD_BRANCH
-)
-
-execute_process(
-    COMMAND ${GIT_EXECUTABLE} --git-dir=${GIT_DIRECTORY} rev-parse HEAD
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-    OUTPUT_VARIABLE GIT_COMMIT_HASH
-)
-
-message(STATUS "Git branch: ${GIT_BUILD_BRANCH}")
-message(STATUS "Git commit hash: ${GIT_COMMIT_HASH}")

cmake/XrplAddTest.cmake

@@ -1,22 +1,25 @@
 include(isolate_headers)
 
 function(xrpl_add_test name)
-    set(target ${PROJECT_NAME}.test.${name})
+  set(target ${PROJECT_NAME}.test.${name})
 
-    file(
-        GLOB_RECURSE sources
-        CONFIGURE_DEPENDS
-        "${CMAKE_CURRENT_SOURCE_DIR}/${name}/*.cpp"
-        "${CMAKE_CURRENT_SOURCE_DIR}/${name}.cpp"
-    )
-    add_executable(${target} ${ARGN} ${sources})
+  file(GLOB_RECURSE sources CONFIGURE_DEPENDS
+  "${CMAKE_CURRENT_SOURCE_DIR}/${name}/*.cpp"
+  "${CMAKE_CURRENT_SOURCE_DIR}/${name}.cpp"
+  )
+  add_executable(${target} ${ARGN} ${sources})
 
-    isolate_headers(
-        ${target}
-        "${CMAKE_SOURCE_DIR}"
-        "${CMAKE_SOURCE_DIR}/tests/${name}"
-        PRIVATE
-    )
+  isolate_headers(
+    ${target}
+    "${CMAKE_SOURCE_DIR}"
+    "${CMAKE_SOURCE_DIR}/tests/${name}"
+    PRIVATE
+  )
 
-    add_test(NAME ${target} COMMAND ${target})
+  # Make sure the test isn't optimized away in unity builds
+  set_target_properties(${target} PROPERTIES
+    UNITY_BUILD_MODE GROUP
+    UNITY_BUILD_BATCH_SIZE 0)  # Adjust as needed
+
+  add_test(NAME ${target} COMMAND ${target})
 endfunction()

cmake/XrplCompiler.cmake

@@ -2,201 +2,154 @@
    setup project-wide compiler settings
 #]===================================================================]
 
-include(CompilationEnv)
-
 #[=========================================================[
    TODO some/most of these common settings belong in a
    toolchain file, especially the ABI-impacting ones
 #]=========================================================]
-add_library(common INTERFACE)
-add_library(Xrpl::common ALIAS common)
-include(XrplSanitizers)
+add_library (common INTERFACE)
+add_library (Xrpl::common ALIAS common)
 # add a single global dependency on this interface lib
-link_libraries(Xrpl::common)
-# Respect CMAKE_POSITION_INDEPENDENT_CODE setting (may be set by Conan toolchain)
-if(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
-    set(CMAKE_POSITION_INDEPENDENT_CODE ON)
-endif()
-set_target_properties(
-    common
-    PROPERTIES
-        INTERFACE_POSITION_INDEPENDENT_CODE ${CMAKE_POSITION_INDEPENDENT_CODE}
-)
+link_libraries (Xrpl::common)
+set_target_properties (common
+  PROPERTIES INTERFACE_POSITION_INDEPENDENT_CODE ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
-target_compile_definitions(
-    common
-    INTERFACE
-        $<$<CONFIG:Debug>:DEBUG
-        _DEBUG>
-        #[===[
+target_compile_definitions (common
+  INTERFACE
+    $<$<CONFIG:Debug>:DEBUG _DEBUG>
+    #[===[
     NOTE: CMAKE release builds already have NDEBUG defined, so no need to add it
     explicitly except for the special case of (profile ON) and (assert OFF).
     Presumably this is because we don't want profile builds asserting unless
     asserts were specifically requested.
     ]===]
-        $<$<AND:$<BOOL:${profile}>,$<NOT:$<BOOL:${assert}>>>:NDEBUG>
-        # TODO: Remove once we have migrated functions from OpenSSL 1.x to 3.x.
-        OPENSSL_SUPPRESS_DEPRECATED
+    $<$<AND:$<BOOL:${profile}>,$<NOT:$<BOOL:${assert}>>>:NDEBUG>
+    # TODO: Remove once we have migrated functions from OpenSSL 1.x to 3.x.
+    OPENSSL_SUPPRESS_DEPRECATED
 )
 
-if(MSVC)
-    # remove existing exception flag since we set it to -EHa
-    string(REGEX REPLACE "[-/]EH[a-z]+" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
+if (MSVC)
+  # remove existing exception flag since we set it to -EHa
+  string (REGEX REPLACE "[-/]EH[a-z]+" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
 
-    foreach(
-        var_
-        CMAKE_C_FLAGS_DEBUG
-        CMAKE_C_FLAGS_RELEASE
-        CMAKE_CXX_FLAGS_DEBUG
-        CMAKE_CXX_FLAGS_RELEASE
-    )
-        # also remove dynamic runtime
-        string(REGEX REPLACE "[-/]MD[d]*" " " ${var_} "${${var_}}")
+  foreach (var_
+      CMAKE_C_FLAGS_DEBUG CMAKE_C_FLAGS_RELEASE
+      CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_RELEASE)
 
-        # /ZI (Edit & Continue debugging information) is incompatible with Gy-
-        string(REPLACE "/ZI" "/Zi" ${var_} "${${var_}}")
+    # also remove dynamic runtime
+    string (REGEX REPLACE "[-/]MD[d]*" " " ${var_} "${${var_}}")
 
-        # omit debug info completely under CI (not needed)
-        if(is_ci)
-            string(REPLACE "/Zi" " " ${var_} "${${var_}}")
-            string(REPLACE "/Z7" " " ${var_} "${${var_}}")
-        endif()
-    endforeach()
+    # /ZI (Edit & Continue debugging information) is incompatible with Gy-
+    string (REPLACE "/ZI" "/Zi" ${var_} "${${var_}}")
 
-    target_compile_options(
-        common
-        INTERFACE # Increase object file max size
-            -bigobj
-            # Floating point behavior
-            -fp:precise
-            # __cdecl calling convention
-            -Gd
-            # Minimal rebuild: disabled
-            -Gm-
-            # Function level linking: disabled
-            -Gy-
-            # Multiprocessor compilation
-            -MP
-            # pragma omp: disabled
-            -openmp-
-            # No error reporting to Internet
-            -errorReport:none
-            # Suppress login banner
-            -nologo
-            # Disable signed/unsigned comparison warnings
-            -wd4018
-            # Disable float to int possible loss of data warnings
-            -wd4244
-            # Disable size_t to T possible loss of data warnings
-            -wd4267
-            # Disable C4800(int to bool performance)
-            -wd4800
-            # Decorated name length exceeded, name was truncated
-            -wd4503
-            $<$<COMPILE_LANGUAGE:CXX>:
-            -EHa
-            -GR
-            >
-            $<$<CONFIG:Release>:-Ox>
-            $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>>:
-            -GS
-            -Zc:forScope
-            >
-            # static runtime
-            $<$<CONFIG:Debug>:-MTd>
-            $<$<NOT:$<CONFIG:Debug>>:-MT>
-            $<$<BOOL:${werr}>:-WX>
-    )
-    target_compile_definitions(
-        common
-        INTERFACE
-            _WIN32_WINNT=0x6000
-            _SCL_SECURE_NO_WARNINGS
-            _CRT_SECURE_NO_WARNINGS
-            WIN32_CONSOLE
-            WIN32_LEAN_AND_MEAN
-            NOMINMAX
-            # TODO: Resolve these warnings, don't just silence them
-            _SILENCE_ALL_CXX17_DEPRECATION_WARNINGS
-            $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>>:_CRTDBG_MAP_ALLOC>
-    )
-    target_link_libraries(common INTERFACE -errorreport:none -machine:X64)
-else()
-    target_compile_options(
-        common
-        INTERFACE
-            -Wall
-            -Wdeprecated
-            $<$<BOOL:${is_clang}>:-Wno-deprecated-declarations>
-            $<$<BOOL:${wextra}>:-Wextra
-            -Wno-unused-parameter>
-            $<$<BOOL:${werr}>:-Werror>
-            -fstack-protector
-            -Wno-sign-compare
-            -Wno-unused-but-set-variable
-            $<$<NOT:$<CONFIG:Debug>>:-fno-strict-aliasing>
-            # tweak gcc optimization for debug
-            $<$<AND:$<BOOL:${is_gcc}>,$<CONFIG:Debug>>:-O0>
-            # Add debug symbols to release config
-            $<$<CONFIG:Release>:-g>
-    )
-    target_link_libraries(
-        common
-        INTERFACE
-            -rdynamic
-            $<$<BOOL:${is_linux}>:-Wl,-z,relro,-z,now,--build-id>
-            # link to static libc/c++ iff: * static option set and * NOT APPLE (AppleClang does not support static
-            # libc/c++) and * NOT SANITIZERS (sanitizers typically don't work with static libc/c++)
-            $<$<AND:$<BOOL:${static}>,$<NOT:$<BOOL:${APPLE}>>,$<NOT:$<BOOL:${SANITIZERS_ENABLED}>>>:
-            -static-libstdc++
-            -static-libgcc
-            >
-    )
-endif()
+    # omit debug info completely under CI (not needed)
+    if (is_ci)
+      string (REPLACE "/Zi" " " ${var_} "${${var_}}")
+    endif ()
+  endforeach ()
+
+  target_compile_options (common
+    INTERFACE
+      -bigobj            # Increase object file max size
+      -fp:precise        # Floating point behavior
+      -Gd                # __cdecl calling convention
+      -Gm-               # Minimal rebuild: disabled
+      -Gy-               # Function level linking: disabled
+      -MP                # Multiprocessor compilation
+      -openmp-           # pragma omp: disabled
+      -errorReport:none  # No error reporting to Internet
+      -nologo            # Suppress login banner
+      -wd4018            # Disable signed/unsigned comparison warnings
+      -wd4244            # Disable float to int possible loss of data warnings
+      -wd4267            # Disable size_t to T possible loss of data warnings
+      -wd4800            # Disable C4800(int to bool performance)
+      -wd4503            # Decorated name length exceeded, name was truncated
+      $<$<COMPILE_LANGUAGE:CXX>:
+        -EHa
+        -GR
+      >
+      $<$<CONFIG:Release>:-Ox>
+      $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>>:
+        -GS
+        -Zc:forScope
+      >
+      # static runtime
+      $<$<CONFIG:Debug>:-MTd>
+      $<$<NOT:$<CONFIG:Debug>>:-MT>
+      $<$<BOOL:${werr}>:-WX>
+      )
+  target_compile_definitions (common
+    INTERFACE
+      _WIN32_WINNT=0x6000
+      _SCL_SECURE_NO_WARNINGS
+      _CRT_SECURE_NO_WARNINGS
+      WIN32_CONSOLE
+      WIN32_LEAN_AND_MEAN
+      NOMINMAX
+      # TODO: Resolve these warnings, don't just silence them
+      _SILENCE_ALL_CXX17_DEPRECATION_WARNINGS
+      $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>>:_CRTDBG_MAP_ALLOC>)
+  target_link_libraries (common
+    INTERFACE
+      -errorreport:none
+      -machine:X64)
+else ()
+  target_compile_options (common
+    INTERFACE
+      -Wall
+      -Wdeprecated
+      $<$<BOOL:${is_clang}>:-Wno-deprecated-declarations>
+      $<$<BOOL:${wextra}>:-Wextra -Wno-unused-parameter>
+      $<$<BOOL:${werr}>:-Werror>
+      -fstack-protector
+      -Wno-sign-compare
+      -Wno-unused-but-set-variable
+      $<$<NOT:$<CONFIG:Debug>>:-fno-strict-aliasing>
+      # tweak gcc optimization for debug
+      $<$<AND:$<BOOL:${is_gcc}>,$<CONFIG:Debug>>:-O0>
+      # Add debug symbols to release config
+      $<$<CONFIG:Release>:-g>)
+  target_link_libraries (common
+    INTERFACE
+      -rdynamic
+      $<$<BOOL:${is_linux}>:-Wl,-z,relro,-z,now,--build-id>
+      # link to static libc/c++ iff:
+      #   * static option set and
+      #   * NOT APPLE (AppleClang does not support static libc/c++) and
+      #   * NOT san (sanitizers typically don't work with static libc/c++)
+      $<$<AND:$<BOOL:${static}>,$<NOT:$<BOOL:${APPLE}>>,$<NOT:$<BOOL:${san}>>>:
+      -static-libstdc++
+      -static-libgcc
+      >)
+endif ()
 
 # Antithesis instrumentation will only be built and deployed using machines running Linux.
-if(voidstar)
-    if(NOT CMAKE_BUILD_TYPE STREQUAL "Debug")
-        message(
-            FATAL_ERROR
-            "Antithesis instrumentation requires Debug build type, aborting..."
-        )
-    elseif(NOT is_linux)
-        message(
-            FATAL_ERROR
-            "Antithesis instrumentation requires Linux, aborting..."
-        )
-    elseif(
-        NOT (is_clang AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 16.0)
-    )
-        message(
-            FATAL_ERROR
-            "Antithesis instrumentation requires Clang version 16 or later, aborting..."
-        )
-    endif()
-endif()
+if (voidstar)
+  if (NOT CMAKE_BUILD_TYPE STREQUAL "Debug")
+    message(FATAL_ERROR "Antithesis instrumentation requires Debug build type, aborting...")
+  elseif (NOT is_linux)
+    message(FATAL_ERROR "Antithesis instrumentation requires Linux, aborting...")
+  elseif (NOT (is_clang AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 16.0))
+    message(FATAL_ERROR "Antithesis instrumentation requires Clang version 16 or later, aborting...")
+  endif ()
+endif ()
 
-if(use_mold)
-    # use mold linker if available
-    execute_process(
-        COMMAND ${CMAKE_CXX_COMPILER} -fuse-ld=mold -Wl,--version
-        ERROR_QUIET
-        OUTPUT_VARIABLE LD_VERSION
-    )
-    if("${LD_VERSION}" MATCHES "mold")
-        target_link_libraries(common INTERFACE -fuse-ld=mold)
-    endif()
-    unset(LD_VERSION)
-elseif(use_gold AND is_gcc)
-    # use gold linker if available
-    execute_process(
-        COMMAND ${CMAKE_CXX_COMPILER} -fuse-ld=gold -Wl,--version
-        ERROR_QUIET
-        OUTPUT_VARIABLE LD_VERSION
-    )
+if (use_mold)
+  # use mold linker if available
+  execute_process (
+    COMMAND ${CMAKE_CXX_COMPILER} -fuse-ld=mold -Wl,--version
+    ERROR_QUIET OUTPUT_VARIABLE LD_VERSION)
+  if ("${LD_VERSION}" MATCHES "mold")
+    target_link_libraries (common INTERFACE -fuse-ld=mold)
+  endif ()
+  unset (LD_VERSION)
+elseif (use_gold AND is_gcc)
+  # use gold linker if available
+  execute_process (
+    COMMAND ${CMAKE_CXX_COMPILER} -fuse-ld=gold -Wl,--version
+    ERROR_QUIET OUTPUT_VARIABLE LD_VERSION)
     #[=========================================================[
        NOTE: THE gold linker inserts -rpath as DT_RUNPATH by
-       default instead of DT_RPATH, so you might have slightly
+       default intead of DT_RPATH, so you might have slightly
        unexpected runtime ld behavior if you were expecting
        DT_RPATH.  Specify --disable-new-dtags to gold if you do
        not want the default DT_RUNPATH behavior. This rpath
@@ -207,37 +160,34 @@ elseif(use_gold AND is_gcc)
        disabling would be to figure out all the settings
        required to make gold play nicely with jemalloc.
     #]=========================================================]
-    if(("${LD_VERSION}" MATCHES "GNU gold") AND (NOT jemalloc))
-        target_link_libraries(
-            common
-            INTERFACE
-                -fuse-ld=gold
-                -Wl,--no-as-needed
-                #[=========================================================[
+  if (("${LD_VERSION}" MATCHES "GNU gold") AND (NOT jemalloc))
+    target_link_libraries (common
+      INTERFACE
+        -fuse-ld=gold
+        -Wl,--no-as-needed
+        #[=========================================================[
            see https://bugs.launchpad.net/ubuntu/+source/eglibc/+bug/1253638/comments/5
            DT_RUNPATH does not work great for transitive
            dependencies (of which boost has a few) - so just
            switch to DT_RPATH if doing dynamic linking with gold
         #]=========================================================]
-                $<$<NOT:$<BOOL:${static}>>:-Wl,--disable-new-dtags>
-        )
-    endif()
-    unset(LD_VERSION)
-elseif(use_lld)
-    # use lld linker if available
-    execute_process(
-        COMMAND ${CMAKE_CXX_COMPILER} -fuse-ld=lld -Wl,--version
-        ERROR_QUIET
-        OUTPUT_VARIABLE LD_VERSION
-    )
-    if("${LD_VERSION}" MATCHES "LLD")
-        target_link_libraries(common INTERFACE -fuse-ld=lld)
-    endif()
-    unset(LD_VERSION)
+        $<$<NOT:$<BOOL:${static}>>:-Wl,--disable-new-dtags>)
+  endif ()
+  unset (LD_VERSION)
+elseif (use_lld)
+  # use lld linker if available
+  execute_process (
+    COMMAND ${CMAKE_CXX_COMPILER} -fuse-ld=lld -Wl,--version
+    ERROR_QUIET OUTPUT_VARIABLE LD_VERSION)
+  if ("${LD_VERSION}" MATCHES "LLD")
+    target_link_libraries (common INTERFACE -fuse-ld=lld)
+  endif ()
+  unset (LD_VERSION)
 endif()
 
-if(assert)
-    foreach(var_ CMAKE_C_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELEASE)
-        string(REGEX REPLACE "[-/]DNDEBUG" "" ${var_} "${${var_}}")
-    endforeach()
-endif()
+
+if (assert)
+  foreach (var_ CMAKE_C_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELEASE)
+    STRING (REGEX REPLACE "[-/]DNDEBUG" "" ${var_} "${${var_}}")
+  endforeach ()
+endif ()

cmake/XrplConfig.cmake

@@ -0,0 +1,54 @@
+include (CMakeFindDependencyMacro)
+# need to represent system dependencies of the lib here
+#[=========================================================[
+  Boost
+#]=========================================================]
+if (static OR APPLE OR MSVC)
+  set (Boost_USE_STATIC_LIBS ON)
+endif ()
+set (Boost_USE_MULTITHREADED ON)
+if (static OR MSVC)
+  set (Boost_USE_STATIC_RUNTIME ON)
+else ()
+  set (Boost_USE_STATIC_RUNTIME OFF)
+endif ()
+find_dependency (Boost
+  COMPONENTS
+    chrono
+    container
+    context
+    coroutine
+    date_time
+    filesystem
+    program_options
+    regex
+    system
+    thread)
+#[=========================================================[
+  OpenSSL
+#]=========================================================]
+if (NOT DEFINED OPENSSL_ROOT_DIR)
+  if (DEFINED ENV{OPENSSL_ROOT})
+    set (OPENSSL_ROOT_DIR $ENV{OPENSSL_ROOT})
+  elseif (APPLE)
+    find_program (homebrew brew)
+    if (homebrew)
+      execute_process (COMMAND ${homebrew} --prefix openssl
+        OUTPUT_VARIABLE OPENSSL_ROOT_DIR
+        OUTPUT_STRIP_TRAILING_WHITESPACE)
+    endif ()
+  endif ()
+  file (TO_CMAKE_PATH "${OPENSSL_ROOT_DIR}" OPENSSL_ROOT_DIR)
+endif ()
+
+if (static OR APPLE OR MSVC)
+  set (OPENSSL_USE_STATIC_LIBS ON)
+endif ()
+set (OPENSSL_MSVC_STATIC_RT ON)
+find_dependency (OpenSSL REQUIRED)
+find_dependency (ZLIB)
+find_dependency (date)
+if (TARGET ZLIB::ZLIB)
+  set_target_properties(OpenSSL::Crypto PROPERTIES
+    INTERFACE_LINK_LIBRARIES ZLIB::ZLIB)
+endif ()

cmake/XrplCore.cmake

@@ -10,66 +10,62 @@ include(target_protobuf_sources)
 # so we just build them as a separate library.
 add_library(xrpl.libpb)
 set_target_properties(xrpl.libpb PROPERTIES UNITY_BUILD OFF)
-target_protobuf_sources(
-    xrpl.libpb
-    xrpl/proto
-    LANGUAGE cpp
-    IMPORT_DIRS include/xrpl/proto
-    PROTOS include/xrpl/proto/xrpl.proto
+target_protobuf_sources(xrpl.libpb xrpl/proto
+  LANGUAGE cpp
+  IMPORT_DIRS include/xrpl/proto
+  PROTOS include/xrpl/proto/xrpl.proto
 )
 
 file(GLOB_RECURSE protos "include/xrpl/proto/org/*.proto")
-target_protobuf_sources(
-    xrpl.libpb
-    xrpl/proto
-    LANGUAGE cpp
-    IMPORT_DIRS include/xrpl/proto
-    PROTOS "${protos}"
+target_protobuf_sources(xrpl.libpb xrpl/proto
+  LANGUAGE cpp
+  IMPORT_DIRS include/xrpl/proto
+  PROTOS "${protos}"
 )
-target_protobuf_sources(
-    xrpl.libpb
-    xrpl/proto
-    LANGUAGE grpc
-    IMPORT_DIRS include/xrpl/proto
-    PROTOS "${protos}"
-    PLUGIN protoc-gen-grpc=$<TARGET_FILE:gRPC::grpc_cpp_plugin>
-    GENERATE_EXTENSIONS .grpc.pb.h .grpc.pb.cc
+target_protobuf_sources(xrpl.libpb xrpl/proto
+  LANGUAGE grpc
+  IMPORT_DIRS include/xrpl/proto
+  PROTOS "${protos}"
+  PLUGIN protoc-gen-grpc=$<TARGET_FILE:gRPC::grpc_cpp_plugin>
+  GENERATE_EXTENSIONS .grpc.pb.h .grpc.pb.cc
 )
 
-target_compile_options(
-    xrpl.libpb
-    PUBLIC
-        $<$<BOOL:${is_msvc}>:-wd4996>
-        $<$<BOOL:${is_xcode}>:
-        --system-header-prefix="google/protobuf"
-        -Wno-deprecated-dynamic-exception-spec
-        >
-    PRIVATE
-        $<$<BOOL:${is_msvc}>:-wd4065>
-        $<$<NOT:$<BOOL:${is_msvc}>>:-Wno-deprecated-declarations>
+target_compile_options(xrpl.libpb
+  PUBLIC
+    $<$<BOOL:${MSVC}>:-wd4996>
+    $<$<BOOL:${XCODE}>:
+      --system-header-prefix="google/protobuf"
+      -Wno-deprecated-dynamic-exception-spec
+    >
+  PRIVATE
+    $<$<BOOL:${MSVC}>:-wd4065>
+    $<$<NOT:$<BOOL:${MSVC}>>:-Wno-deprecated-declarations>
 )
 
-target_link_libraries(xrpl.libpb PUBLIC protobuf::libprotobuf gRPC::grpc++)
+target_link_libraries(xrpl.libpb
+  PUBLIC
+    protobuf::libprotobuf
+    gRPC::grpc++
+)
 
 # TODO: Clean up the number of library targets later.
 add_library(xrpl.imports.main INTERFACE)
 
-target_link_libraries(
-    xrpl.imports.main
-    INTERFACE
-        absl::random_random
-        date::date
-        ed25519::ed25519
-        LibArchive::LibArchive
-        OpenSSL::Crypto
-        Xrpl::boost
-        Xrpl::libs
-        Xrpl::opts
-        Xrpl::syslibs
-        secp256k1::secp256k1
-        xrpl.libpb
-        xxHash::xxhash
-        $<$<BOOL:${voidstar}>:antithesis-sdk-cpp>
+target_link_libraries(xrpl.imports.main
+  INTERFACE
+    absl::random_random
+    date::date
+    ed25519::ed25519
+    LibArchive::LibArchive
+    OpenSSL::Crypto
+    Xrpl::boost
+    Xrpl::libs
+    Xrpl::opts
+    Xrpl::syslibs
+    secp256k1::secp256k1
+    xrpl.libpb
+    xxHash::xxhash
+    $<$<BOOL:${voidstar}>:antithesis-sdk-cpp>
 )
 
 include(add_module)
@@ -78,23 +74,6 @@ include(target_link_modules)
 # Level 01
 add_module(xrpl beast)
 target_link_libraries(xrpl.libxrpl.beast PUBLIC xrpl.imports.main)
-# OTelCollector in beast/insight uses OTel Metrics SDK when telemetry is enabled.
-if(telemetry)
-    target_link_libraries(
-        xrpl.libxrpl.beast
-        PUBLIC opentelemetry-cpp::opentelemetry-cpp
-    )
-endif()
-
-include(GitInfo)
-add_module(xrpl git)
-target_compile_definitions(
-    xrpl.libxrpl.git
-    PRIVATE
-        GIT_COMMIT_HASH="${GIT_COMMIT_HASH}"
-        GIT_BUILD_BRANCH="${GIT_BUILD_BRANCH}"
-)
-target_link_libraries(xrpl.libxrpl.git PUBLIC xrpl.imports.main)
 
 # Level 02
 add_module(xrpl basics)
@@ -109,16 +88,17 @@ target_link_libraries(xrpl.libxrpl.crypto PUBLIC xrpl.libxrpl.basics)
 
 # Level 04
 add_module(xrpl protocol)
-target_link_libraries(
-    xrpl.libxrpl.protocol
-    PUBLIC xrpl.libxrpl.crypto xrpl.libxrpl.git xrpl.libxrpl.json
+target_link_libraries(xrpl.libxrpl.protocol PUBLIC
+  xrpl.libxrpl.crypto
+  xrpl.libxrpl.json
 )
 
 # Level 05
 add_module(xrpl core)
-target_link_libraries(
-    xrpl.libxrpl.core
-    PUBLIC xrpl.libxrpl.basics xrpl.libxrpl.json xrpl.libxrpl.protocol
+target_link_libraries(xrpl.libxrpl.core PUBLIC
+  xrpl.libxrpl.basics
+  xrpl.libxrpl.json
+  xrpl.libxrpl.protocol
 )
 
 # Level 06
@@ -127,115 +107,61 @@ target_link_libraries(xrpl.libxrpl.resource PUBLIC xrpl.libxrpl.protocol)
 
 # Level 07
 add_module(xrpl net)
-target_link_libraries(
-    xrpl.libxrpl.net
-    PUBLIC
+target_link_libraries(xrpl.libxrpl.net PUBLIC
+  xrpl.libxrpl.basics
+  xrpl.libxrpl.json
+  xrpl.libxrpl.protocol
+  xrpl.libxrpl.resource
+)
+
+add_module(xrpl server)
+target_link_libraries(xrpl.libxrpl.server PUBLIC xrpl.libxrpl.protocol)
+
+add_module(xrpl nodestore)
+target_link_libraries(xrpl.libxrpl.nodestore PUBLIC
         xrpl.libxrpl.basics
         xrpl.libxrpl.json
         xrpl.libxrpl.protocol
-        xrpl.libxrpl.resource
-)
-
-add_module(xrpl nodestore)
-target_link_libraries(
-    xrpl.libxrpl.nodestore
-    PUBLIC xrpl.libxrpl.basics xrpl.libxrpl.json xrpl.libxrpl.protocol
 )
 
 add_module(xrpl shamap)
-target_link_libraries(
-    xrpl.libxrpl.shamap
-    PUBLIC
+target_link_libraries(xrpl.libxrpl.shamap PUBLIC
         xrpl.libxrpl.basics
         xrpl.libxrpl.crypto
         xrpl.libxrpl.protocol
         xrpl.libxrpl.nodestore
 )
 
-add_module(xrpl rdb)
-target_link_libraries(
-    xrpl.libxrpl.rdb
-    PUBLIC xrpl.libxrpl.basics xrpl.libxrpl.core
-)
-
-add_module(xrpl server)
-target_link_libraries(
-    xrpl.libxrpl.server
-    PUBLIC
-        xrpl.libxrpl.protocol
-        xrpl.libxrpl.core
-        xrpl.libxrpl.rdb
-        xrpl.libxrpl.resource
-)
-
-add_module(xrpl conditions)
-target_link_libraries(xrpl.libxrpl.conditions PUBLIC xrpl.libxrpl.server)
-
 add_module(xrpl ledger)
-target_link_libraries(
-    xrpl.libxrpl.ledger
-    PUBLIC
-        xrpl.libxrpl.basics
-        xrpl.libxrpl.json
-        xrpl.libxrpl.protocol
-        xrpl.libxrpl.rdb
-        xrpl.libxrpl.server
-        xrpl.libxrpl.shamap
-        xrpl.libxrpl.conditions
+target_link_libraries(xrpl.libxrpl.ledger PUBLIC
+  xrpl.libxrpl.basics
+  xrpl.libxrpl.json
+  xrpl.libxrpl.protocol
 )
 
-add_module(xrpl tx)
-target_link_libraries(xrpl.libxrpl.tx PUBLIC xrpl.libxrpl.ledger)
-
-# Telemetry module — OpenTelemetry distributed tracing support.
-# Sources: include/xrpl/telemetry/ (headers), src/libxrpl/telemetry/ (impl).
-# When telemetry=ON, links the Conan-provided umbrella target
-# opentelemetry-cpp::opentelemetry-cpp (individual component targets like
-# ::api, ::sdk are not available in the Conan package).
-add_module(xrpl telemetry)
-target_link_libraries(
-    xrpl.libxrpl.telemetry
-    PUBLIC xrpl.libxrpl.basics xrpl.libxrpl.beast
-)
-if(telemetry)
-    target_link_libraries(
-        xrpl.libxrpl.telemetry
-        PUBLIC opentelemetry-cpp::opentelemetry-cpp
-    )
-endif()
-
 add_library(xrpl.libxrpl)
 set_target_properties(xrpl.libxrpl PROPERTIES OUTPUT_NAME xrpl)
 
 add_library(xrpl::libxrpl ALIAS xrpl.libxrpl)
 
-file(
-    GLOB_RECURSE sources
-    CONFIGURE_DEPENDS
-    "${CMAKE_CURRENT_SOURCE_DIR}/src/libxrpl/*.cpp"
+file(GLOB_RECURSE sources CONFIGURE_DEPENDS
+  "${CMAKE_CURRENT_SOURCE_DIR}/src/libxrpl/*.cpp"
 )
 target_sources(xrpl.libxrpl PRIVATE ${sources})
 
-target_link_modules(
-    xrpl
-    PUBLIC
-    basics
-    beast
-    conditions
-    core
-    crypto
-    git
-    json
-    ledger
-    net
-    nodestore
-    protocol
-    rdb
-    resource
-    server
-    shamap
-    telemetry
-    tx
+target_link_modules(xrpl PUBLIC
+  basics
+  beast
+  core
+  crypto
+  json
+  protocol
+  resource
+  server
+  nodestore
+  shamap
+  net
+  ledger
 )
 
 # All headers in libxrpl are in modules.
@@ -248,50 +174,62 @@ target_link_modules(
 #     $<INSTALL_INTERFACE:include>)
 
 if(xrpld)
-    add_executable(xrpld)
-    if(tests)
-        target_compile_definitions(xrpld PUBLIC ENABLE_TESTS)
-        target_compile_definitions(
-            xrpld
-            PRIVATE UNIT_TEST_REFERENCE_FEE=${UNIT_TEST_REFERENCE_FEE}
-        )
-    endif()
-    target_include_directories(
-        xrpld
-        PRIVATE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
+  add_executable(xrpld)
+  if(tests)
+    target_compile_definitions(xrpld PUBLIC ENABLE_TESTS)
+    target_compile_definitions(xrpld PRIVATE
+                                       UNIT_TEST_REFERENCE_FEE=${UNIT_TEST_REFERENCE_FEE}
     )
+  endif()
+  target_include_directories(xrpld
+    PRIVATE
+      $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
+  )
 
-    file(
-        GLOB_RECURSE sources
-        CONFIGURE_DEPENDS
-        "${CMAKE_CURRENT_SOURCE_DIR}/src/xrpld/*.cpp"
+  file(GLOB_RECURSE sources CONFIGURE_DEPENDS
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/xrpld/*.cpp"
+  )
+  target_sources(xrpld PRIVATE ${sources})
+
+  if(tests)
+    file(GLOB_RECURSE sources CONFIGURE_DEPENDS
+      "${CMAKE_CURRENT_SOURCE_DIR}/src/test/*.cpp"
     )
     target_sources(xrpld PRIVATE ${sources})
+  endif()
 
-    if(tests)
-        file(
-            GLOB_RECURSE sources
-            CONFIGURE_DEPENDS
-            "${CMAKE_CURRENT_SOURCE_DIR}/src/test/*.cpp"
-        )
-        target_sources(xrpld PRIVATE ${sources})
-    endif()
+  target_link_libraries(xrpld
+    Xrpl::boost
+    Xrpl::opts
+    Xrpl::libs
+    xrpl.libxrpl
+  )
+  exclude_if_included(xrpld)
+  # define a macro for tests that might need to
+  # be exluded or run differently in CI environment
+  if(is_ci)
+    target_compile_definitions(xrpld PRIVATE XRPL_RUNNING_IN_CI)
+  endif ()
 
-    target_link_libraries(xrpld Xrpl::boost Xrpl::opts Xrpl::libs xrpl.libxrpl)
-    exclude_if_included(xrpld)
-    # define a macro for tests that might need to
-    # be excluded or run differently in CI environment
-    if(is_ci)
-        target_compile_definitions(xrpld PRIVATE XRPL_RUNNING_IN_CI)
-    endif()
+  if(voidstar)
+    target_compile_options(xrpld
+      PRIVATE
+        -fsanitize-coverage=trace-pc-guard
+    )
+    # xrpld requires access to antithesis-sdk-cpp implementation file
+    # antithesis_instrumentation.h, which is not exported as INTERFACE
+    target_include_directories(xrpld
+      PRIVATE
+        ${CMAKE_SOURCE_DIR}/external/antithesis-sdk
+    )
+  endif()
 
-    if(voidstar)
-        target_compile_options(xrpld PRIVATE -fsanitize-coverage=trace-pc-guard)
-        # xrpld requires access to antithesis-sdk-cpp implementation file
-        # antithesis_instrumentation.h, which is not exported as INTERFACE
-        target_include_directories(
-            xrpld
-            PRIVATE ${CMAKE_SOURCE_DIR}/external/antithesis-sdk
-        )
-    endif()
+  # any files that don't play well with unity should be added here
+  if(tests)
+    set_source_files_properties(
+      # these two seem to produce conflicts in beast teardown template methods
+      src/test/rpc/ValidatorRPC_test.cpp
+      src/test/ledger/Invariants_test.cpp
+      PROPERTIES SKIP_UNITY_BUILD_INCLUSION TRUE)
+  endif()
 endif()

cmake/XrplCov.cmake

@@ -3,15 +3,12 @@
 #]===================================================================]
 
 if(NOT coverage)
-    message(FATAL_ERROR "Code coverage not enabled! Aborting ...")
+  message(FATAL_ERROR "Code coverage not enabled! Aborting ...")
 endif()
 
 if(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
-    message(
-        WARNING
-        "Code coverage on Windows is not supported, ignoring 'coverage' flag"
-    )
-    return()
+  message(WARNING "Code coverage on Windows is not supported, ignoring 'coverage' flag")
+  return()
 endif()
 
 include(ProcessorCount)
@@ -19,35 +16,26 @@ ProcessorCount(PROCESSOR_COUNT)
 
 include(CodeCoverage)
 
-# The instructions for these commands come from the `CodeCoverage` module, which was copied from
-# https://github.com/bilke/cmake-modules, commit fb7d2a3, then locally changed (see CHANGES: section in
-# `CodeCoverage.cmake`)
+# The instructions for these commands come from the `CodeCoverage` module,
+# which was copied from https://github.com/bilke/cmake-modules, commit fb7d2a3,
+# then locally changed (see CHANGES: section in `CodeCoverage.cmake`)
 
 set(GCOVR_ADDITIONAL_ARGS ${coverage_extra_args})
 if(NOT GCOVR_ADDITIONAL_ARGS STREQUAL "")
-    separate_arguments(GCOVR_ADDITIONAL_ARGS)
+  separate_arguments(GCOVR_ADDITIONAL_ARGS)
 endif()
 
-list(
-    APPEND GCOVR_ADDITIONAL_ARGS
-    --exclude-throw-branches
-    --exclude-noncode-lines
-    --exclude-unreachable-branches
-    -s
-    -j
-    ${PROCESSOR_COUNT}
-)
+list(APPEND GCOVR_ADDITIONAL_ARGS
+  --exclude-throw-branches
+  --exclude-noncode-lines
+  --exclude-unreachable-branches -s
+  -j ${PROCESSOR_COUNT})
 
 setup_target_for_coverage_gcovr(
-    NAME coverage
-    FORMAT ${coverage_format}
-    EXCLUDE
-        "src/test"
-        "src/tests"
-        "include/xrpl/beast/test"
-        "include/xrpl/beast/unit_test"
-        "${CMAKE_BINARY_DIR}/pb-xrpl.libpb"
-    DEPENDENCIES xrpld xrpl.tests
+  NAME coverage
+  FORMAT ${coverage_format}
+  EXCLUDE "src/test" "src/tests" "include/xrpl/beast/test" "include/xrpl/beast/unit_test" "${CMAKE_BINARY_DIR}/pb-xrpl.libpb"
+  DEPENDENCIES xrpld xrpl.tests
 )
 
 add_code_coverage_to_target(opts INTERFACE)

cmake/XrplDocs.cmake

@@ -3,13 +3,13 @@
 #]===================================================================]
 
 if(NOT only_docs)
-    return()
+  return()
 endif()
 
 find_package(Doxygen)
 if(NOT TARGET Doxygen::doxygen)
-    message(STATUS "doxygen executable not found -- skipping docs target")
-    return()
+  message(STATUS "doxygen executable not found -- skipping docs target")
+  return()
 endif()
 
 set(doxygen_output_directory "${CMAKE_BINARY_DIR}/docs")
@@ -17,44 +17,40 @@ set(doxygen_include_path "${CMAKE_CURRENT_SOURCE_DIR}/src")
 set(doxygen_index_file "${doxygen_output_directory}/html/index.html")
 set(doxyfile "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile")
 
-file(
-    GLOB_RECURSE doxygen_input
-    docs/*.md
-    include/*.h
-    include/*.cpp
-    include/*.md
-    src/*.h
-    src/*.cpp
-    src/*.md
-    Builds/*.md
-    *.md
-)
-list(APPEND doxygen_input external/README.md)
+file(GLOB_RECURSE doxygen_input
+  docs/*.md
+  include/*.h
+  include/*.cpp
+  include/*.md
+  src/*.h
+  src/*.cpp
+  src/*.md
+  Builds/*.md
+  *.md)
+list(APPEND doxygen_input
+  external/README.md
+  )
 set(dependencies "${doxygen_input}" "${doxyfile}")
 
 function(verbose_find_path variable name)
-    # find_path sets a CACHE variable, so don't try using a "local" variable.
-    find_path(${variable} "${name}" ${ARGN})
-    if(NOT ${variable})
-        message(NOTICE "could not find ${name}")
-    else()
-        message(STATUS "found ${name}: ${${variable}}/${name}")
-    endif()
+  # find_path sets a CACHE variable, so don't try using a "local" variable.
+  find_path(${variable} "${name}" ${ARGN})
+  if(NOT ${variable})
+    message(NOTICE "could not find ${name}")
+  else()
+    message(STATUS "found ${name}: ${${variable}}/${name}")
+  endif()
 endfunction()
 
-verbose_find_path(
-    doxygen_plantuml_jar_path
-    plantuml.jar
-    PATH_SUFFIXES share/plantuml
-)
+verbose_find_path(doxygen_plantuml_jar_path plantuml.jar PATH_SUFFIXES share/plantuml)
 verbose_find_path(doxygen_dot_path dot)
 
 # https://en.cppreference.com/w/Cppreference:Archives
 # https://stackoverflow.com/questions/60822559/how-to-move-a-file-download-from-configure-step-to-build-step
 set(download_script "${CMAKE_BINARY_DIR}/docs/download-cppreference.cmake")
-file(
-    WRITE "${download_script}"
-    "file(DOWNLOAD \
+file(WRITE
+  "${download_script}"
+  "file(DOWNLOAD \
     https://github.com/PeterFeicht/cppreference-doc/releases/download/v20250209/html-book-20250209.zip \
     ${CMAKE_BINARY_DIR}/docs/cppreference.zip \
     EXPECTED_HASH MD5=bda585f72fbca4b817b29a3d5746567b \
@@ -65,27 +61,23 @@ file(
 )
 set(tagfile "${CMAKE_BINARY_DIR}/docs/cppreference-doxygen-web.tag.xml")
 add_custom_command(
-    OUTPUT "${tagfile}"
-    COMMAND "${CMAKE_COMMAND}" -P "${download_script}"
-    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs"
+  OUTPUT "${tagfile}"
+  COMMAND "${CMAKE_COMMAND}" -P "${download_script}"
+  WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs"
 )
 set(doxygen_tagfiles "${tagfile}=http://en.cppreference.com/w/")
 
 add_custom_command(
-    OUTPUT "${doxygen_index_file}"
-    COMMAND
-        "${CMAKE_COMMAND}" -E env
-        "DOXYGEN_OUTPUT_DIRECTORY=${doxygen_output_directory}"
-        "DOXYGEN_INCLUDE_PATH=${doxygen_include_path}"
-        "DOXYGEN_TAGFILES=${doxygen_tagfiles}"
-        "DOXYGEN_PLANTUML_JAR_PATH=${doxygen_plantuml_jar_path}"
-        "DOXYGEN_DOT_PATH=${doxygen_dot_path}" "${DOXYGEN_EXECUTABLE}"
-        "${doxyfile}"
-    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
-    DEPENDS "${dependencies}" "${tagfile}"
-)
-add_custom_target(
-    docs
-    DEPENDS "${doxygen_index_file}"
-    SOURCES "${dependencies}"
-)
+  OUTPUT "${doxygen_index_file}"
+  COMMAND "${CMAKE_COMMAND}" -E env
+    "DOXYGEN_OUTPUT_DIRECTORY=${doxygen_output_directory}"
+    "DOXYGEN_INCLUDE_PATH=${doxygen_include_path}"
+    "DOXYGEN_TAGFILES=${doxygen_tagfiles}"
+    "DOXYGEN_PLANTUML_JAR_PATH=${doxygen_plantuml_jar_path}"
+    "DOXYGEN_DOT_PATH=${doxygen_dot_path}"
+    "${DOXYGEN_EXECUTABLE}" "${doxyfile}"
+  WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+  DEPENDS "${dependencies}" "${tagfile}")
+add_custom_target(docs
+  DEPENDS "${doxygen_index_file}"
+  SOURCES "${dependencies}")