updated config and ordering files

Signed-off-by: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>

.clang-format

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

.clang-tidy

@@ -1,204 +1,191 @@
 ---
 Checks: "-*,
-  bugprone-argument-comment,
-  bugprone-assert-side-effect,
-  bugprone-bad-signal-to-kill-thread,
-  bugprone-bool-pointer-implicit-conversion,
-  bugprone-capturing-this-in-member-variable,
-  bugprone-casting-through-void,
-  bugprone-chained-comparison,
-  bugprone-compare-pointer-to-member-virtual-function,
-  bugprone-copy-constructor-init,
-  bugprone-crtp-constructor-accessibility,
-  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-misleading-setter-of-reference,
-  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-switch-missing-default-case,
-  bugprone-terminating-continue,
-  bugprone-throw-keyword-missing,
-  bugprone-too-small-loop-variable,
-  bugprone-unchecked-optional-access,
-  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-local-non-trivial-variable,
-  bugprone-unused-raii,
-  bugprone-unused-return-value,
-  bugprone-use-after-move,
-  bugprone-virtual-near-miss,
-  cppcoreguidelines-init-variables,
-  cppcoreguidelines-misleading-capture-default-by-value,
-  cppcoreguidelines-no-suspend-with-lock,
-  cppcoreguidelines-pro-type-member-init,
-  cppcoreguidelines-pro-type-static-cast-downcast,
-  cppcoreguidelines-rvalue-reference-param-not-moved,
-  cppcoreguidelines-use-default-member-init,
-  cppcoreguidelines-use-enum-class,
-  cppcoreguidelines-virtual-class-destructor,
-  hicpp-ignored-remove-result,
-  llvm-namespace-comment,
-  misc-const-correctness,
-  misc-definitions-in-headers,
-  misc-header-include-cycle,
-  misc-include-cleaner,
-  misc-misplaced-const,
-  misc-redundant-expression,
-  misc-static-assert,
-  misc-throw-by-value-catch-by-reference,
-  misc-unused-alias-decls,
-  misc-unused-using-decls,
-  modernize-concat-nested-namespaces,
-  modernize-deprecated-headers,
-  modernize-make-shared,
-  modernize-make-unique,
-  modernize-pass-by-value,
-  modernize-type-traits,
-  modernize-use-designated-initializers,
-  modernize-use-emplace,
-  modernize-use-equals-default,
-  modernize-use-equals-delete,
-  modernize-use-nodiscard,
-  modernize-use-override,
-  modernize-use-ranges,
-  modernize-use-scoped-lock,
-  modernize-use-starts-ends-with,
-  modernize-use-std-numbers,
-  modernize-use-using,
-  performance-faster-string-find,
-  performance-for-range-copy,
-  performance-implicit-conversion-in-loop,
-  performance-inefficient-vector-operation,
-  performance-move-const-arg,
-  performance-move-constructor-init,
-  performance-no-automatic-move,
-  performance-trivially-destructible,
-  readability-ambiguous-smartptr-reset-call,
-  readability-avoid-nested-conditional-operator,
-  readability-avoid-return-with-void-value,
-  readability-braces-around-statements,
-  readability-const-return-type,
-  readability-container-contains,
-  readability-container-size-empty,
-  readability-convert-member-functions-to-static,
-  readability-duplicate-include,
-  readability-else-after-return,
-  readability-enum-initial-value,
-  readability-identifier-naming,
-  readability-implicit-bool-conversion,
-  readability-make-member-function-const,
-  readability-math-missing-parentheses,
-  readability-misleading-indentation,
-  readability-non-const-parameter,
-  readability-redundant-casting,
-  readability-redundant-declaration,
-  readability-redundant-inline-specifier,
-  readability-redundant-member-init,
-  readability-redundant-string-init,
-  readability-reference-to-constructed-temporary,
-  readability-simplify-boolean-expr,
-  readability-static-definition-in-anonymous-namespace,
-  readability-suspicious-call-argument,
-  readability-use-std-min-max
+  bugprone-argument-comment
   "
-# ---
-# readability-inconsistent-declaration-parameter-name, # in this codebase this check will break a lot of arg names
-# readability-static-accessed-through-instance,        # this check is probably unnecessary. It makes the code less readable
-# ---
-
-CheckOptions:
-  bugprone-unsafe-functions.ReportMoreUnsafeFunctions: true
-  bugprone-unused-return-value.CheckedReturnTypes: ::std::error_code;::std::error_condition;::std::errc
-
-  misc-include-cleaner.IgnoreHeaders: ".*/(detail|impl)/.*;.*fwd\\.h(pp)?;time.h;stdlib.h;sqlite3.h;netinet/in\\.h;sys/resource\\.h;sys/sysinfo\\.h;linux/sysinfo\\.h;__chrono/.*;bits/.*;_abort\\.h;boost/uuid/uuid_hash.hpp;boost/beast/core/flat_buffer\\.hpp;boost/beast/http/field\\.hpp;boost/beast/http/dynamic_body\\.hpp;boost/beast/http/message\\.hpp;boost/beast/http/read\\.hpp;boost/beast/http/write\\.hpp;openssl/obj_mac\\.h"
-
-  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: CamelCase
-  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: CamelCase
-  readability-identifier-naming.ClassConstantPrefix: "k"
-  readability-identifier-naming.StaticConstantCase: CamelCase
-  readability-identifier-naming.StaticConstantPrefix: "k"
-  readability-identifier-naming.StaticVariableCase: camelBack
-  readability-identifier-naming.ConstexprVariableCase: camelBack
-  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.PrivateMemberCase: camelBack
-  readability-identifier-naming.PrivateMemberSuffix: _
-  readability-identifier-naming.ProtectedMemberCase: camelBack
-  readability-identifier-naming.ProtectedMemberSuffix: _
-  readability-identifier-naming.PublicMemberCase: camelBack
-  readability-identifier-naming.PublicMemberSuffix: ""
-  readability-identifier-naming.GlobalFunctionIgnoredRegexp: "^(to_string|hash_append|tuple_hash)$"
-
-HeaderFilterRegex: '^.*/(tests?|xrpl|xrpld)/.*\.(h|hpp|ipp)$'
-ExcludeHeaderFilterRegex: '^.*/protocol_autogen/.*\.(h|hpp)$'
+# 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-crtp-constructor-accessibility,
+# 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-switch-missing-default-case,
+# 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-local-non-trivial-variable,
+# bugprone-unused-raii,
+# bugprone-unused-return-value,
+# bugprone-use-after-move,
+# bugprone-virtual-near-miss,
+# cppcoreguidelines-init-variables,
+# cppcoreguidelines-misleading-capture-default-by-value,
+# cppcoreguidelines-no-suspend-with-lock,
+# cppcoreguidelines-pro-type-member-init,
+# cppcoreguidelines-pro-type-static-cast-downcast,
+# cppcoreguidelines-rvalue-reference-param-not-moved,
+# cppcoreguidelines-use-default-member-init,
+# cppcoreguidelines-virtual-class-destructor,
+# hicpp-ignored-remove-result,
+# llvm-namespace-comment,
+# misc-const-correctness,
+# misc-definitions-in-headers,
+# misc-header-include-cycle,
+# misc-include-cleaner,
+# misc-misplaced-const,
+# misc-redundant-expression,
+# misc-static-assert,
+# misc-throw-by-value-catch-by-reference,
+# misc-unused-alias-decls,
+# misc-unused-using-decls,
+# modernize-concat-nested-namespaces,
+# modernize-deprecated-headers,
+# modernize-make-shared,
+# modernize-make-unique,
+# modernize-pass-by-value,
+# modernize-type-traits,
+# modernize-use-designated-initializers,
+# modernize-use-emplace,
+# modernize-use-equals-default,
+# modernize-use-equals-delete,
+# modernize-use-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-implicit-conversion-in-loop,
+# performance-inefficient-vector-operation,
+# performance-move-const-arg,
+# performance-move-constructor-init,
+# performance-no-automatic-move,
+# performance-trivially-destructible,
+# readability-avoid-nested-conditional-operator,
+# readability-avoid-return-with-void-value,
+# readability-braces-around-statements,
+# readability-const-return-type,
+# readability-container-contains,
+# readability-container-size-empty,
+# readability-convert-member-functions-to-static,
+# readability-duplicate-include,
+# readability-else-after-return,
+# readability-enum-initial-value,
+# readability-implicit-bool-conversion,
+# readability-inconsistent-declaration-parameter-name,
+# readability-identifier-naming,
+# readability-make-member-function-const,
+# readability-math-missing-parentheses,
+# readability-misleading-indentation,
+# readability-non-const-parameter,
+# readability-redundant-casting,
+# readability-redundant-declaration,
+# readability-redundant-inline-specifier,
+# readability-redundant-member-init,
+# readability-redundant-string-init,
+# readability-reference-to-constructed-temporary,
+# readability-simplify-boolean-expr,
+# readability-static-accessed-through-instance,
+# readability-static-definition-in-anonymous-namespace,
+# readability-suspicious-call-argument,
+# readability-use-std-min-max
+#
+# 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: "*"

.cmake-format.yaml

@@ -0,0 +1,247 @@
+_help_parse: Options affecting listfile parsing
+parse:
+  _help_additional_commands:
+    - Specify structure for custom cmake functions
+  additional_commands:
+    target_protobuf_sources:
+      pargs:
+        - target
+        - prefix
+      kwargs:
+        PROTOS: "*"
+        LANGUAGE: cpp
+        IMPORT_DIRS: "*"
+        GENERATE_EXTENSIONS: "*"
+        PLUGIN: "*"
+  _help_override_spec:
+    - Override configurations per-command where available
+  override_spec: {}
+  _help_vartags:
+    - Specify variable tags.
+  vartags: []
+  _help_proptags:
+    - Specify property tags.
+  proptags: []
+_help_format: Options affecting formatting.
+format:
+  _help_disable:
+    - Disable formatting entirely, making cmake-format a no-op
+  disable: false
+  _help_line_width:
+    - How wide to allow formatted cmake files
+  line_width: 100
+  _help_tab_size:
+    - How many spaces to tab for indent
+  tab_size: 4
+  _help_use_tabchars:
+    - If true, lines are indented using tab characters (utf-8
+    - 0x09) instead of <tab_size> space characters (utf-8 0x20).
+    - In cases where the layout would require a fractional tab
+    - character, the behavior of the  fractional indentation is
+    - governed by <fractional_tab_policy>
+  use_tabchars: false
+  _help_fractional_tab_policy:
+    - If <use_tabchars> is True, then the value of this variable
+    - indicates how fractional indentions are handled during
+    - whitespace replacement. If set to 'use-space', fractional
+    - indentation is left as spaces (utf-8 0x20). If set to
+    - "`round-up` fractional indentation is replaced with a single"
+    - tab character (utf-8 0x09) effectively shifting the column
+    - to the next tabstop
+  fractional_tab_policy: use-space
+  _help_max_subgroups_hwrap:
+    - If an argument group contains more than this many sub-groups
+    - (parg or kwarg groups) then force it to a vertical layout.
+  max_subgroups_hwrap: 4
+  _help_max_pargs_hwrap:
+    - If a positional argument group contains more than this many
+    - arguments, then force it to a vertical layout.
+  max_pargs_hwrap: 5
+  _help_max_rows_cmdline:
+    - If a cmdline positional group consumes more than this many
+    - lines without nesting, then invalidate the layout (and nest)
+  max_rows_cmdline: 2
+  _help_separate_ctrl_name_with_space:
+    - If true, separate flow control names from their parentheses
+    - with a space
+  separate_ctrl_name_with_space: true
+  _help_separate_fn_name_with_space:
+    - If true, separate function names from parentheses with a
+    - space
+  separate_fn_name_with_space: false
+  _help_dangle_parens:
+    - If a statement is wrapped to more than one line, than dangle
+    - the closing parenthesis on its own line.
+  dangle_parens: false
+  _help_dangle_align:
+    - If the trailing parenthesis must be 'dangled' on its on
+    - "line, then align it to this reference: `prefix`: the start"
+    - "of the statement, `prefix-indent`: the start of the"
+    - "statement, plus one indentation level, `child`: align to"
+    - the column of the arguments
+  dangle_align: prefix
+  _help_min_prefix_chars:
+    - If the statement spelling length (including space and
+    - parenthesis) is smaller than this amount, then force reject
+    - nested layouts.
+  min_prefix_chars: 18
+  _help_max_prefix_chars:
+    - If the statement spelling length (including space and
+    - parenthesis) is larger than the tab width by more than this
+    - amount, then force reject un-nested layouts.
+  max_prefix_chars: 10
+  _help_max_lines_hwrap:
+    - If a candidate layout is wrapped horizontally but it exceeds
+    - this many lines, then reject the layout.
+  max_lines_hwrap: 2
+  _help_line_ending:
+    - What style line endings to use in the output.
+  line_ending: unix
+  _help_command_case:
+    - Format command names consistently as 'lower' or 'upper' case
+  command_case: canonical
+  _help_keyword_case:
+    - Format keywords consistently as 'lower' or 'upper' case
+  keyword_case: unchanged
+  _help_always_wrap:
+    - A list of command names which should always be wrapped
+  always_wrap: []
+  _help_enable_sort:
+    - If true, the argument lists which are known to be sortable
+    - will be sorted lexicographicall
+  enable_sort: true
+  _help_autosort:
+    - If true, the parsers may infer whether or not an argument
+    - list is sortable (without annotation).
+  autosort: true
+  _help_require_valid_layout:
+    - By default, if cmake-format cannot successfully fit
+    - everything into the desired linewidth it will apply the
+    - last, most aggressive attempt that it made. If this flag is
+    - True, however, cmake-format will print error, exit with non-
+    - zero status code, and write-out nothing
+  require_valid_layout: false
+  _help_layout_passes:
+    - A dictionary mapping layout nodes to a list of wrap
+    - decisions. See the documentation for more information.
+  layout_passes: {}
+_help_markup: Options affecting comment reflow and formatting.
+markup:
+  _help_bullet_char:
+    - What character to use for bulleted lists
+  bullet_char: "-"
+  _help_enum_char:
+    - What character to use as punctuation after numerals in an
+    - enumerated list
+  enum_char: .
+  _help_first_comment_is_literal:
+    - If comment markup is enabled, don't reflow the first comment
+    - block in each listfile. Use this to preserve formatting of
+    - your copyright/license statements.
+  first_comment_is_literal: false
+  _help_literal_comment_pattern:
+    - If comment markup is enabled, don't reflow any comment block
+    - which matches this (regex) pattern. Default is `None`
+    - (disabled).
+  literal_comment_pattern: null
+  _help_fence_pattern:
+    - Regular expression to match preformat fences in comments
+    - default= ``r'^\s*([`~]{3}[`~]*)(.*)$'``
+  fence_pattern: ^\s*([`~]{3}[`~]*)(.*)$
+  _help_ruler_pattern:
+    - Regular expression to match rulers in comments default=
+    - '``r''^\s*[^\w\s]{3}.*[^\w\s]{3}$''``'
+  ruler_pattern: ^\s*[^\w\s]{3}.*[^\w\s]{3}$
+  _help_explicit_trailing_pattern:
+    - If a comment line matches starts with this pattern then it
+    - is explicitly a trailing comment for the preceding
+    - argument. Default is '#<'
+  explicit_trailing_pattern: "#<"
+  _help_hashruler_min_length:
+    - If a comment line starts with at least this many consecutive
+    - hash characters, then don't lstrip() them off. This allows
+    - for lazy hash rulers where the first hash char is not
+    - separated by space
+  hashruler_min_length: 10
+  _help_canonicalize_hashrulers:
+    - If true, then insert a space between the first hash char and
+    - remaining hash chars in a hash ruler, and normalize its
+    - length to fill the column
+  canonicalize_hashrulers: true
+  _help_enable_markup:
+    - enable comment markup parsing and reflow
+  enable_markup: false
+_help_lint: Options affecting the linter
+lint:
+  _help_disabled_codes:
+    - a list of lint codes to disable
+  disabled_codes: []
+  _help_function_pattern:
+    - regular expression pattern describing valid function names
+  function_pattern: "[0-9a-z_]+"
+  _help_macro_pattern:
+    - regular expression pattern describing valid macro names
+  macro_pattern: "[0-9A-Z_]+"
+  _help_global_var_pattern:
+    - regular expression pattern describing valid names for
+    - variables with global (cache) scope
+  global_var_pattern: "[A-Z][0-9A-Z_]+"
+  _help_internal_var_pattern:
+    - regular expression pattern describing valid names for
+    - variables with global scope (but internal semantic)
+  internal_var_pattern: _[A-Z][0-9A-Z_]+
+  _help_local_var_pattern:
+    - regular expression pattern describing valid names for
+    - variables with local scope
+  local_var_pattern: "[a-z][a-z0-9_]+"
+  _help_private_var_pattern:
+    - regular expression pattern describing valid names for
+    - privatedirectory variables
+  private_var_pattern: _[0-9a-z_]+
+  _help_public_var_pattern:
+    - regular expression pattern describing valid names for public
+    - directory variables
+  public_var_pattern: "[A-Z][0-9A-Z_]+"
+  _help_argument_var_pattern:
+    - regular expression pattern describing valid names for
+    - function/macro arguments and loop variables.
+  argument_var_pattern: "[a-z][a-z0-9_]+"
+  _help_keyword_pattern:
+    - regular expression pattern describing valid names for
+    - keywords used in functions or macros
+  keyword_pattern: "[A-Z][0-9A-Z_]+"
+  _help_max_conditionals_custom_parser:
+    - In the heuristic for C0201, how many conditionals to match
+    - within a loop in before considering the loop a parser.
+  max_conditionals_custom_parser: 2
+  _help_min_statement_spacing:
+    - Require at least this many newlines between statements
+  min_statement_spacing: 1
+  _help_max_statement_spacing:
+    - Require no more than this many newlines between statements
+  max_statement_spacing: 2
+  max_returns: 6
+  max_branches: 12
+  max_arguments: 5
+  max_localvars: 15
+  max_statements: 50
+_help_encode: Options affecting file encoding
+encode:
+  _help_emit_byteorder_mark:
+    - If true, emit the unicode byte-order mark (BOM) at the start
+    - of the file
+  emit_byteorder_mark: false
+  _help_input_encoding:
+    - Specify the encoding of the input file. Defaults to utf-8
+  input_encoding: utf-8
+  _help_output_encoding:
+    - Specify the encoding of the output file. Defaults to utf-8.
+    - Note that cmake only claims to support utf-8 so be careful
+    - when using anything else
+  output_encoding: utf-8
+_help_misc: Miscellaneous configurations options.
+misc:
+  _help_per_command:
+    - A dictionary containing any per-command configuration
+    - overrides. Currently only `command_case` is supported.
+  per_command: {}

.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()
-
-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(setup_protocol_autogen)
-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]

.git-blame-ignore-revs

@@ -1,81 +1,16 @@
 # This feature requires Git >= 2.24
 # To use it by default in git blame:
 # git config blame.ignoreRevsFile .git-blame-ignore-revs
-
-# This file is sorted in reverse chronological order, with the most recent commits at the top.
-# The commits listed here are ignored by git blame, which is useful for formatting-only commits that would otherwise obscure the history of changes to a file.
-
-# refactor: Enable clang-tidy `readability-identifier-naming` check (#6571)
-8995564ed6b9e453e144bb663303072a3c1ba305
-# refactor: Enable remaining clang-tidy `cppcoreguidelines` checks (#6538)
-72f4cb097f626b08b02fc3efcb4aa11cb2e7adb8
-# refactor: Rename system name from 'ripple' to 'xrpld' (#6347)
-ffea3977f0b771fe8e43a8f74e4d393d63a7afd8
-# refactor: Update transaction folder structure (#6483)
-5865bd017f777491b4a956f9210be0c4161f5442
-# chore: Use gersemi instead of ancient cmake-format (#6486)
-0c74270b055133a57a497b5c9fc5a75f7647b1f4
-# chore: Apply clang-format width 100 (#6387)
-2c1fad102353e11293e3edde1c043224e7d3e983
-# chore: Set clang-format width to 100 in config file (#6387)
-25cca465538a56cce501477f9e5e2c1c7ea2d84c
-# chore: Set cmake-format width to 100 (#6386)
-469ce9f291a4480c38d4ee3baca5136b2f053cd0
-# refactor: Modularize app/tx (#6228)
-0976b2b68b64972af8e6e7c497900b5bce9fe22f
-# chore: Update clang-format to 21.1.8 (#6352)
-958d8f375453d80bb1aa4c293b5102c045a3e4b4
-# refactor: Replace include guards by '#pragma once' (#6322)
-34ef577604782ca8d6e1c17df8bd7470990a52ff
-# chore: Format all cmake files without comments (#6294)
-fe9c8d568fcf6ac21483024e01f58962dd5c8260
-# chore: Add cmake-format pre-commit hook (#6279)
-a0e09187b9370805d027c611a7e9ff5a0125282a
-# chore: Set ColumnLimit to 120 in clang-format (#6288)
-5f638f55536def0d88b970d1018a465a238e55f4
-# refactor: Fix typos in comments, configure cspell (#6164)
-3c9f5b62525cb1d6ca1153eeb10433db7d7379fd
-# refactor: Rename `rippled.cfg` to `xrpld.cfg` (#6098)
-3d1b3a49b3601a0a7037fa0b19d5df7b5e0e2fc1
-# refactor: Rename `ripple` namespace to `xrpl` (#5982)
-1eb0fdac6543706b4b9ddca57fd4102928a1f871
-# refactor: Rename `rippled` binary to `xrpld` (#5983)
-9eb84a561ef8bb066d89f098bd9b4ac71baed67c
-# refactor: Replaces secp256k1 source by Conan package (#6089)
-813bc4d9491b078bb950f8255f93b02f71320478
-# refactor: Remove unnecessary copyright notices already covered by LICENSE.md (#5929)
-1d42c4f6de6bf01d1286fc7459b17a37a5189e88
-# refactor: Rename `RIPPLE_` and `RIPPLED_` definitions to `XRPL_` (#5821)
-ada83564d894829424b0f4d922b0e737e07abbf7
-# refactor: Modularize shamap and nodestore (#5668)
-8eb233c2ea8ad5a159be73b77f0f5e1496d547ac
-# refactor: Modularise ledger (#5493)
-dc8b37a52448b005153c13a7f046ad494128cf94
-# chore: Update clang-format and prettier with pre-commit (#5709)
-c14ce956adeabe476ad73c18d73103f347c9c613
-# chore: Fix file formatting (#5718)
-896b8c3b54a22b0497cb0d1ce95e1095f9a227ce
-# chore: Reverts formatting changes to external files, adds formatting changes to proto files (#5711)
-b13370ac0d207217354f1fc1c29aef87769fb8a1
-# chore: Run prettier on all files (#5657)
-97f0747e103f13e26e45b731731059b32f7679ac
-# Reformat code with clang-format-18
-552377c76f55b403a1c876df873a23d780fcc81c
-# Recompute loops (#4997)
-d028005aa6319338b0adae1aebf8abe113162960
-# Rewrite includes (#4997)
-1d23148e6dd53957fcb6205c07a5c6cd7b64d50c
-# Rearrange sources (#4997)
-e416ee72ca26fa0c09d2aee1b68bdfb2b7046eed
-# Move CMake directory (#4997)
-2e902dee53aab2a8f27f32971047bb81e022f94f
-# Rewrite includes
-0eebe6a5f4246fced516d52b83ec4e7f47373edd
-# Format formerly .hpp files
-760f16f56835663d9286bd29294d074de26a7ba6
-# Rename .hpp to .h
-241b9ddde9e11beb7480600fd5ed90e1ef109b21
-# Consolidate external libraries
-e2384885f5f630c8f0ffe4bf21a169b433a16858
-# Format first-party source according to .clang-format
 50760c693510894ca368e90369b0cc2dabfd07f3
+e2384885f5f630c8f0ffe4bf21a169b433a16858
+241b9ddde9e11beb7480600fd5ed90e1ef109b21
+760f16f56835663d9286bd29294d074de26a7ba6
+0eebe6a5f4246fced516d52b83ec4e7f47373edd
+2189cc950c0cebb89e4e2fa3b2d8817205bf7cef
+b9d007813378ad0ff45660dc07285b823c7e9855
+fe9a5365b8a52d4acc42eb27369247e6f238a4f9
+9a93577314e6a8d4b4a8368cc9d2b15a5d8303e8
+552377c76f55b403a1c876df873a23d780fcc81c
+97f0747e103f13e26e45b731731059b32f7679ac
+b13370ac0d207217354f1fc1c29aef87769fb8a1
+896b8c3b54a22b0497cb0d1ce95e1095f9a227ce

.github/ISSUE_TEMPLATE/feature_request.md

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

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

@@ -35,13 +35,14 @@ runs:
         LOG_VERBOSITY: ${{ inputs.log_verbosity }}
         SANITIZERS: ${{ inputs.sanitizers }}
       run: |
+        echo 'Installing dependencies.'
         conan install \
-            --profile:all ci \
-            --build="${BUILD_OPTION}" \
-            --options:host='&:tests=True' \
-            --options:host='&:xrpld=True' \
-            --settings:all build_type="${BUILD_TYPE}" \
-            --conf:all tools.build:jobs=${BUILD_NPROC} \
-            --conf:all tools.build:verbosity="${LOG_VERBOSITY}" \
-            --conf:all tools.compilation:verbosity="${LOG_VERBOSITY}" \
-            .
+          --profile ci \
+          --build="${BUILD_OPTION}" \
+          --options:host='&:tests=True' \
+          --options:host='&:xrpld=True' \
+          --settings:all build_type="${BUILD_TYPE}" \
+          --conf:all tools.build:jobs=${BUILD_NPROC} \
+          --conf:all tools.build:verbosity="${LOG_VERBOSITY}" \
+          --conf:all tools.compilation:verbosity="${LOG_VERBOSITY}" \
+          .

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

@@ -11,34 +11,34 @@ runs:
   steps:
     # When a tag is pushed, the version is used as-is.
     - name: Generate version for tag event
-      if: ${{ startsWith(github.ref, 'refs/tags/') }}
+      if: ${{ github.event_name == 'tag' }}
       shell: bash
       env:
         VERSION: ${{ github.ref_name }}
-      run: echo "VERSION=${VERSION}" >>"${GITHUB_ENV}"
+      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: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      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
+          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}"
+        echo "VERSION=${VERSION}" >> "${GITHUB_ENV}"
 
     - name: Output version
       id: version
       shell: bash
-      run: echo "version=${VERSION}" >>"${GITHUB_OUTPUT}"
+      run: echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"

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

@@ -0,0 +1,43 @@
+name: Print build environment
+description: "Print environment and some tooling versions"
+
+runs:
+  using: composite
+  steps:
+    - name: Check configuration (Windows)
+      if: ${{ runner.os == 'Windows' }}
+      shell: bash
+      run: |
+        echo 'Checking environment variables.'
+        set
+
+    - name: Check configuration (Linux and macOS)
+      if: ${{ runner.os == 'Linux' || runner.os == 'macOS' }}
+      shell: bash
+      run: |
+        echo 'Checking path.'
+        echo ${PATH} | tr ':' '\n'
+
+        echo 'Checking environment variables.'
+        env | sort
+
+        echo 'Checking compiler version.'
+        ${{ runner.os == 'Linux' && '${CC}' || 'clang' }} --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/set-compiler-env/action.yml

@@ -1,34 +0,0 @@
-name: Set compiler environment
-description: "Set CC and CXX environment variables for the given compiler."
-
-inputs:
-  compiler:
-    description: 'The compiler to use ("gcc" or "clang").'
-    required: true
-
-runs:
-  using: composite
-
-  steps:
-    - name: Set CC and CXX for gcc
-      if: ${{ inputs.compiler == 'gcc' }}
-      shell: bash
-      run: |
-        echo "CC=gcc" >>"${GITHUB_ENV}"
-        echo "CXX=g++" >>"${GITHUB_ENV}"
-
-    - name: Set CC and CXX for clang
-      if: ${{ inputs.compiler == 'clang' }}
-      shell: bash
-      run: |
-        echo "CC=clang" >>"${GITHUB_ENV}"
-        echo "CXX=clang++" >>"${GITHUB_ENV}"
-
-    - name: Fail on unknown compiler
-      if: ${{ inputs.compiler != 'gcc' && inputs.compiler != 'clang' }}
-      shell: bash
-      env:
-        COMPILER: ${{ inputs.compiler }}
-      run: |
-        echo "Unknown compiler: $COMPILER" >&2
-        exit 1

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

@@ -15,35 +15,32 @@ runs:
   using: composite
 
   steps:
-    - name: Apply custom configuration to global.conf
+    - name: Set up Conan configuration
       shell: bash
       run: |
+        echo 'Installing configuration.'
         cat conan/global.conf ${{ runner.os == 'Linux' && '>>' || '>' }} $(conan config home)/global.conf
 
-    - name: Show global configuration
-      shell: bash
-      run: |
+        echo 'Conan configuration:'
         conan config show '*'
 
-    - name: Install profiles
+    - name: Set up Conan profile
       shell: bash
       run: |
+        echo 'Installing profile.'
         conan config install conan/profiles/ -tf $(conan config home)/profiles/
 
-    - name: Show CI profile
-      shell: bash
-      run: |
+        echo 'Conan profile:'
         conan profile show --profile ci
 
-    - name: Add a remote
+    - name: Set up Conan remote
       shell: bash
       env:
         REMOTE_NAME: ${{ inputs.remote_name }}
         REMOTE_URL: ${{ inputs.remote_url }}
       run: |
+        echo "Adding Conan remote '${REMOTE_NAME}' at '${REMOTE_URL}'."
         conan remote add --index 0 --force "${REMOTE_NAME}" "${REMOTE_URL}"
 
-    - name: List remotes
-      shell: bash
-      run: |
+        echo 'Listing Conan remotes.'
         conan remote list

.github/dependabot.yml

@@ -1,12 +1,51 @@
 version: 2
 updates:
   - package-ecosystem: github-actions
-    directories:
-      - /
-      - .github/actions/build-deps/
-      - .github/actions/generate-version/
-      - .github/actions/set-compiler-env/
-      - .github/actions/setup-conan/
+    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

.github/pull_request_template.md

@@ -29,6 +29,22 @@ If a refactor, how is this better than the previous implementation?
 If there is a spec or design document for this feature, please link it here.
 -->
 
+### Type of Change
+
+<!--
+Please check [x] relevant options, delete irrelevant ones.
+-->
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Refactor (non-breaking change that only restructures code)
+- [ ] Performance (increase or change in throughput and/or latency)
+- [ ] Tests (you added tests for code that already exists, or your new feature included in this PR)
+- [ ] Documentation update
+- [ ] Chore (no impact to binary, e.g. `.gitignore`, formatting, dropping support for older tooling)
+- [ ] Release
+
 ### API Impact
 
 <!--

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

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

.github/scripts/format-inline-bash.py

@@ -1,403 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-Format embedded shell snippets using the shfmt hook configured in
-.pre-commit-config.yaml.
-
-Two shapes are recognised:
-
-* YAML workflow/action files: literal block-scalar runs (`run: |`) and
-  single-line runs (`run: some command`). A single-line run is upgraded to
-  a `run: |` block scalar if shfmt's output spans multiple lines.
-
-* Markdown files: ``` ```bash ``` fenced code blocks.
-
-Any block that shfmt cannot parse is skipped with a warning on stderr, so
-the file is left untouched and surrounding blocks still get formatted.
-
-For each occurrence the body is dedented, written to a temp .sh file,
-formatted via `pre-commit run shfmt --files <temp>` (falling back to
-`prek`), then re-indented and written back in place.
-
-When invoked without arguments, every .yml/.yaml under .github/ plus every
-.md file in the repo is scanned. When invoked with file arguments (the
-pre-commit case), only those files are processed.
-"""
-
-from __future__ import annotations
-
-import re
-import shutil
-import subprocess
-import sys
-import tempfile
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Union
-
-REPO = Path(__file__).resolve().parents[2]
-
-_HOOK_RUNNER = next((cmd for cmd in ("pre-commit", "prek") if shutil.which(cmd)), None)
-if _HOOK_RUNNER is None:
-    sys.exit("error: neither `pre-commit` nor `prek` found on PATH")
-
-RUN_BLOCK_RE = re.compile(r"^(?P<prefix>[ \t]*(?:- )?)run:[ \t]*\|[+-]?[ \t]*$")
-RUN_INLINE_RE = re.compile(
-    r"^(?P<prefix>[ \t]*(?:- )?)run:[ \t]+" r"(?P<value>(?!\|[+-]?[ \t]*$)\S.*?)[ \t]*$"
-)
-MD_BASH_OPEN_RE = re.compile(r"^(?P<indent>[ ]{0,3})`{3}bash[ \t]*$")
-MD_FENCE_CLOSE_RE = re.compile(r"^[ ]{0,3}`{3,}[ \t]*$")
-
-
-@dataclass(frozen=True)
-class BlockRun:
-    """A `run: |` block scalar; `body_start:body_end` slices into `lines`."""
-
-    body_start: int
-    body_end: int
-    body_indent: int
-
-
-@dataclass(frozen=True)
-class InlineRun:
-    """A single-line `run: value` at `line_idx`."""
-
-    line_idx: int
-    prefix: str
-    value: str
-
-
-@dataclass(frozen=True)
-class MdBashBlock:
-    """A markdown ``` ```bash ``` fenced code block.
-
-    `body_start:body_end` slices into the file's lines; `open_line_idx`
-    points at the opening fence line.
-    """
-
-    open_line_idx: int
-    body_start: int
-    body_end: int
-    body_indent: int
-
-
-RunItem = Union[BlockRun, InlineRun]
-
-
-def _scan_block_body(
-    lines: list[str], body_start: int, run_col: int
-) -> tuple[int | None, int]:
-    """Locate the body of a `run: |` block scalar starting at `body_start`.
-
-    Returns `(body_indent, scan_end)`. `scan_end` is the line index where the
-    outer scanner should resume. `body_indent` is `None` when no body is
-    present (the scalar is empty, or the next non-blank line has indent
-    `<= run_col`).
-    """
-    body_indent: int | None = None
-    scan_end = len(lines)
-    for idx in range(body_start, len(lines)):
-        line = lines[idx]
-        if line.strip() == "":
-            continue
-        indent = len(line) - len(line.lstrip(" "))
-        if body_indent is None:
-            if indent > run_col:
-                body_indent = indent
-            else:
-                scan_end = idx
-                break
-        elif indent < body_indent:
-            scan_end = idx
-            break
-    if body_indent is not None:
-        while scan_end > body_start and lines[scan_end - 1].strip() == "":
-            scan_end -= 1
-        if scan_end <= body_start:
-            body_indent = None
-    return body_indent, scan_end
-
-
-def find_run_blocks(lines: list[str]) -> list[RunItem]:
-    """Return run items in document order."""
-    items: list[RunItem] = []
-    line_idx = 0
-    while line_idx < len(lines):
-        line = lines[line_idx]
-        if block_match := RUN_BLOCK_RE.match(line):
-            run_col = len(block_match.group("prefix"))
-            body_start = line_idx + 1
-            body_indent, scan_end = _scan_block_body(lines, body_start, run_col)
-            if body_indent is not None:
-                items.append(
-                    BlockRun(
-                        body_start=body_start,
-                        body_end=scan_end,
-                        body_indent=body_indent,
-                    )
-                )
-            line_idx = scan_end
-            continue
-        if inline_match := RUN_INLINE_RE.match(line):
-            items.append(
-                InlineRun(
-                    line_idx=line_idx,
-                    prefix=inline_match.group("prefix"),
-                    value=inline_match.group("value"),
-                )
-            )
-        line_idx += 1
-    return items
-
-
-def find_md_bash_blocks(lines: list[str]) -> list[MdBashBlock]:
-    """Return ``` ```bash ``` fenced code blocks in document order."""
-    blocks: list[MdBashBlock] = []
-    line_idx = 0
-    while line_idx < len(lines):
-        open_match = MD_BASH_OPEN_RE.match(lines[line_idx])
-        if not open_match:
-            line_idx += 1
-            continue
-        body_start = line_idx + 1
-        close_idx = next(
-            (
-                j
-                for j in range(body_start, len(lines))
-                if MD_FENCE_CLOSE_RE.match(lines[j])
-            ),
-            None,
-        )
-        if close_idx is None:
-            line_idx = body_start
-            continue
-        body = lines[body_start:close_idx]
-        non_blank = [b for b in body if b.strip()]
-        body_indent = (
-            min(len(b) - len(b.lstrip(" ")) for b in non_blank)
-            if non_blank
-            else len(open_match.group("indent"))
-        )
-        blocks.append(
-            MdBashBlock(
-                open_line_idx=line_idx,
-                body_start=body_start,
-                body_end=close_idx,
-                body_indent=body_indent,
-            )
-        )
-        line_idx = close_idx + 1
-    return blocks
-
-
-def dedent(lines: list[str], n: int) -> list[str]:
-    pad = " " * n
-    return [
-        (
-            ""
-            if line.strip() == ""
-            else (line[n:] if line.startswith(pad) else line.lstrip(" "))
-        )
-        for line in lines
-    ]
-
-
-def reindent(lines: list[str], n: int) -> list[str]:
-    pad = " " * n
-    return [pad + line if line else "" for line in lines]
-
-
-_SHFMT_ERR_RE = re.compile(r"\.sh:\d+:\d+:\s")
-_GHA_EXPR_RE = re.compile(r"\$\{\{.*?\}\}", re.DOTALL)
-_GHA_PLACEHOLDER_RE = re.compile(r"__GHA_EXPR_(\d+)__")
-
-
-def _encode_gha_exprs(text: str) -> tuple[str, list[str]]:
-    """Replace `${{ ... }}` expressions with bash-safe placeholder identifiers."""
-    exprs: list[str] = []
-
-    def repl(match: re.Match[str]) -> str:
-        exprs.append(match.group(0))
-        return f"__GHA_EXPR_{len(exprs) - 1}__"
-
-    return _GHA_EXPR_RE.sub(repl, text), exprs
-
-
-def _decode_gha_exprs(text: str, exprs: list[str]) -> str:
-    """Restore `${{ ... }}` expressions from placeholder identifiers."""
-    return _GHA_PLACEHOLDER_RE.sub(lambda m: exprs[int(m.group(1))], text)
-
-
-def shfmt_via_hook(tmp_path: Path) -> tuple[bool, str]:
-    # `${{ ... }}` is not valid shell, so swap it for a placeholder identifier
-    # that shfmt can parse, then restore it after formatting.
-    encoded, exprs = _encode_gha_exprs(tmp_path.read_text())
-    if exprs:
-        tmp_path.write_text(encoded)
-    res = subprocess.run(
-        [_HOOK_RUNNER, "run", "shfmt", "--files", str(tmp_path)],
-        cwd=REPO,
-        capture_output=True,
-        text=True,
-    )
-    output = res.stdout + res.stderr
-    # shfmt emits parse errors as "<path>:<line>:<col>: <message>".
-    parse_err = bool(_SHFMT_ERR_RE.search(output))
-    # A non-zero exit that is neither a parse error nor pre-commit's "I had
-    # to modify files" signal means the hook itself failed to run (missing
-    # binary, install failure, bad config, ...). Surface that loudly rather
-    # than silently treating it as a no-op.
-    if (
-        res.returncode != 0
-        and not parse_err
-        and "files were modified by this hook" not in output
-    ):
-        sys.exit(
-            f"error: `{_HOOK_RUNNER} run shfmt` failed with exit {res.returncode}:\n{output}"
-        )
-    if exprs and not parse_err:
-        tmp_path.write_text(_decode_gha_exprs(tmp_path.read_text(), exprs))
-    return not parse_err, output
-
-
-def _skip(path: Path, where: int, kind: str, output: str) -> None:
-    print(
-        f"  shfmt could not parse {kind} at {path}:{where + 1} — skipped",
-        file=sys.stderr,
-    )
-    print(f"    {output.strip()}", file=sys.stderr)
-
-
-def process_yaml_file(path: Path, tmp_path: Path) -> int:
-    text = path.read_text()
-    had_nl = text.endswith("\n")
-    lines = text.split("\n")
-    if had_nl:
-        lines = lines[:-1]
-    items = find_run_blocks(lines)
-    if not items:
-        return 0
-    changed = 0
-    # Process in reverse so earlier indices remain valid as we splice.
-    for item in reversed(items):
-        if isinstance(item, BlockRun):
-            body = lines[item.body_start : item.body_end]
-            tmp_path.write_text("\n".join(dedent(body, item.body_indent)) + "\n")
-            ok, output = shfmt_via_hook(tmp_path)
-            if not ok:
-                _skip(path, item.body_start, "block", output)
-                continue
-            formatted = tmp_path.read_text().rstrip("\n")
-            new_body = reindent(formatted.split("\n"), item.body_indent)
-            if new_body != body:
-                lines[item.body_start : item.body_end] = new_body
-                changed += 1
-        else:
-            tmp_path.write_text(item.value + "\n")
-            ok, output = shfmt_via_hook(tmp_path)
-            if not ok:
-                _skip(path, item.line_idx, "inline run", output)
-                continue
-            formatted = tmp_path.read_text().rstrip("\n")
-            if formatted == item.value:
-                continue
-            formatted_lines = formatted.split("\n")
-            if len(formatted_lines) == 1:
-                lines[item.line_idx] = f"{item.prefix}run: {formatted}"
-            else:
-                body_indent = len(item.prefix) + 2
-                lines[item.line_idx : item.line_idx + 1] = [
-                    f"{item.prefix}run: |",
-                    *reindent(formatted_lines, body_indent),
-                ]
-            changed += 1
-    new_text = "\n".join(lines) + ("\n" if had_nl else "")
-    if new_text != text:
-        path.write_text(new_text)
-    return changed
-
-
-def process_md_file(path: Path, tmp_path: Path) -> int:
-    text = path.read_text()
-    had_nl = text.endswith("\n")
-    lines = text.split("\n")
-    if had_nl:
-        lines = lines[:-1]
-    blocks = find_md_bash_blocks(lines)
-    if not blocks:
-        return 0
-    changed = 0
-    for block in reversed(blocks):
-        body = lines[block.body_start : block.body_end]
-        tmp_path.write_text("\n".join(dedent(body, block.body_indent)) + "\n")
-        ok, output = shfmt_via_hook(tmp_path)
-        if not ok:
-            _skip(path, block.open_line_idx, "```bash block", output)
-            continue
-        formatted = tmp_path.read_text().rstrip("\n")
-        formatted_lines = formatted.split("\n") if formatted else []
-        new_body = reindent(formatted_lines, block.body_indent)
-        if new_body != body:
-            lines[block.body_start : block.body_end] = new_body
-            changed += 1
-    new_text = "\n".join(lines) + ("\n" if had_nl else "")
-    if new_text != text:
-        path.write_text(new_text)
-    return changed
-
-
-def process_file(path: Path, tmp_path: Path) -> int:
-    if path.suffix in (".yml", ".yaml"):
-        return process_yaml_file(path, tmp_path)
-    if path.suffix == ".md":
-        return process_md_file(path, tmp_path)
-    return 0
-
-
-def gather_files(argv: list[str]) -> list[Path]:
-    """Return YAML workflow/action files and markdown files that we should
-    process — either the paths in `argv` or, when `argv` is empty, every
-    such file in the repo (skipping `external/`)."""
-    if argv:
-        candidates: list[Path] = [
-            (REPO / a).resolve() if not Path(a).is_absolute() else Path(a) for a in argv
-        ]
-    else:
-        gh = REPO / ".github"
-        candidates = [
-            *gh.rglob("*.yml"),
-            *gh.rglob("*.yaml"),
-            *(
-                p
-                for p in REPO.rglob("*.md")
-                if "external" not in p.relative_to(REPO).parts
-            ),
-        ]
-    return sorted(
-        p
-        for p in candidates
-        if p.exists()
-        and (
-            (p.suffix in (".yml", ".yaml") and ".github" in p.parts)
-            or p.suffix == ".md"
-        )
-    )
-
-
-def main(argv: list[str]) -> int:
-    files = gather_files(argv)
-    if not files:
-        return 0
-    with tempfile.TemporaryDirectory(prefix="format-inline-bash-") as tmpdir:
-        tmp_path = Path(tmpdir) / "shfmt.sh"
-        total = 0
-        for f in files:
-            n = process_file(f, tmp_path)
-            if n:
-                print(f"{f.relative_to(REPO)}: reformatted {n} block(s)")
-                total += n
-        return 1 if total else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))

.github/scripts/levelization/README.md

@@ -1,14 +1,14 @@
 # Levelization
 
-Levelization is the term used to describe efforts to prevent xrpld from
+Levelization is the term used to describe efforts to prevent rippled from
 having or creating cyclic dependencies.
 
-xrpld code is organized into directories under `src/xrpld`, `src/libxrpl` (and
+rippled code is organized into directories under `src/xrpld`, `src/libxrpl` (and
 `src/test`) representing modules. The modules are intended to be
 organized into "tiers" or "levels" such that a module from one level can
 only include code from lower levels. Additionally, a module
 in one level should never include code in an `impl` or `detail` folder of any level
-other than its own.
+other than it's own.
 
 The codebase is split into two main areas:
 
@@ -22,7 +22,7 @@ levelization violations they find (by moving files or individual
 classes). At the very least, don't make things worse.
 
 The table below summarizes the _desired_ division of modules, based on the current
-state of the xrpld code. The levels are numbered from
+state of the rippled code. The levels are numbered from
 the bottom up with the lower level, lower numbered, more independent
 modules listed first, and the higher level, higher numbered modules with
 more dependencies listed later.
@@ -70,12 +70,12 @@ that `test` code should _never_ be included in `xrpl` or `xrpld` code.)
 
 ## Validation
 
-The [levelization](generate.py) script takes no parameters,
+The [levelization](generate.sh) script takes no parameters,
 reads no environment variables, and can be run from any directory,
-as long as it is in the expected location in the xrpld repo.
+as long as it is in the expected location in the rippled repo.
 It can be run at any time from within a checked out repo, and will
 do an analysis of all the `#include`s in
-the xrpld source. The only caveat is that it runs much slower
+the rippled source. The only caveat is that it runs much slower
 under Windows than in Linux. It hasn't yet been tested under MacOS.
 It generates many files of [results](results):
 
@@ -104,7 +104,7 @@ It generates many files of [results](results):
   Github Actions workflow to test that levelization loops haven't
   changed. Unfortunately, if changes are detected, it can't tell if
   they are improvements or not, so if you have resolved any issues or
-  done anything else to improve levelization, run `generate.py`,
+  done anything else to improve levelization, run `levelization.sh`,
   and commit the updated results.
 
 The `loops.txt` and `ordering.txt` files relate the modules
@@ -128,7 +128,7 @@ The committed files hide the detailed values intentionally, to
 prevent false alarms and merging issues, and because it's easy to
 get those details locally.
 
-1. Run `generate.py`
+1. Run `levelization.sh`
 2. Grep the modules in `paths.txt`.
    - For example, if a cycle is found `A ~= B`, simply `grep -w
 A .github/scripts/levelization/results/paths.txt | grep -w B`

.github/scripts/levelization/generate.py

@@ -1,335 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-Usage: generate.py
-This script takes no parameters, and can be called from any directory in the file system.
-"""
-
-import os
-import re
-import subprocess
-import sys
-from collections import defaultdict
-from pathlib import Path
-from typing import Dict, List, Tuple, Set, Optional
-
-# Compile regex patterns once at module level
-INCLUDE_PATTERN = re.compile(r"^\s*#include.*/.*\.h")
-INCLUDE_PATH_PATTERN = re.compile(r'[<"]([^>"]+)[>"]')
-
-
-def dictionary_sort_key(s: str) -> str:
-    """
-    Create a sort key that mimics 'sort -d' (dictionary order).
-    Dictionary order only considers blanks and alphanumeric characters.
-    This means punctuation like '.' is ignored during sorting.
-    """
-    # Keep only alphanumeric characters and spaces
-    return "".join(c for c in s if c.isalnum() or c.isspace())
-
-
-def get_level(file_path: str) -> str:
-    """
-    Extract the level from a file path (second and third directory components).
-    Equivalent to bash: cut -d/ -f 2,3
-
-    Examples:
-        src/xrpld/app/main.cpp -> xrpld.app
-        src/libxrpl/protocol/STObject.cpp -> libxrpl.protocol
-        include/xrpl/basics/base_uint.h -> xrpl.basics
-    """
-    parts = file_path.split("/")
-
-    # Get fields 2 and 3 (indices 1 and 2 in 0-based indexing)
-    if len(parts) >= 3:
-        level = f"{parts[1]}/{parts[2]}"
-    elif len(parts) >= 2:
-        level = f"{parts[1]}/toplevel"
-    else:
-        level = file_path
-
-    # If the "level" indicates a file, cut off the filename
-    if "." in level.split("/")[-1]:  # Avoid Path object creation
-        # Use the "toplevel" label as a workaround for `sort`
-        # inconsistencies between different utility versions
-        level = level.rsplit("/", 1)[0] + "/toplevel"
-
-    return level.replace("/", ".")
-
-
-def extract_include_level(include_line: str) -> Optional[str]:
-    """
-    Extract the include path from an #include directive.
-    Gets the first two directory components from the include path.
-    Equivalent to bash: cut -d/ -f 1,2
-
-    Examples:
-        #include <xrpl/basics/base_uint.h> -> xrpl.basics
-        #include "xrpld/app/main/Application.h" -> xrpld.app
-    """
-    # Remove everything before the quote or angle bracket
-    match = INCLUDE_PATH_PATTERN.search(include_line)
-    if not match:
-        return None
-
-    include_path = match.group(1)
-    parts = include_path.split("/")
-
-    # Get first two fields (indices 0 and 1)
-    if len(parts) >= 2:
-        include_level = f"{parts[0]}/{parts[1]}"
-    else:
-        include_level = include_path
-
-    # If the "includelevel" indicates a file, cut off the filename
-    if "." in include_level.split("/")[-1]:  # Avoid Path object creation
-        include_level = include_level.rsplit("/", 1)[0] + "/toplevel"
-
-    return include_level.replace("/", ".")
-
-
-def find_repository_directories(
-    start_path: Path, depth_limit: int = 10
-) -> Tuple[Path, List[Path]]:
-    """
-    Find the repository root by looking for src or include folders.
-    Walks up the directory tree from the start path.
-    """
-    current = start_path.resolve()
-
-    # Walk up the directory tree
-    for _ in range(depth_limit):  # Limit search depth to prevent infinite loops
-        src_path = current / "src"
-        include_path = current / "include"
-        # Check if this directory has src or include folders
-        has_src = src_path.exists()
-        has_include = include_path.exists()
-
-        if has_src or has_include:
-            return current, [src_path, include_path]
-
-        # Move up one level
-        parent = current.parent
-        if parent == current:  # Reached filesystem root
-            break
-        current = parent
-
-    # If we couldn't find it, raise an error
-    raise RuntimeError(
-        "Could not find repository root. "
-        "Expected to find a directory containing 'src' and/or 'include' folders."
-    )
-
-
-def main():
-    # Change to the script's directory
-    script_dir = Path(__file__).parent.resolve()
-    os.chdir(script_dir)
-
-    # Clean up and create results directory.
-    results_dir = script_dir / "results"
-    if results_dir.exists():
-        import shutil
-
-        shutil.rmtree(results_dir)
-    results_dir.mkdir()
-
-    # Find the repository root by searching for src and include directories.
-    try:
-        repo_root, scan_dirs = find_repository_directories(script_dir)
-
-        print(f"Found repository root: {repo_root}")
-        print(f"Scanning directories:")
-        for scan_dir in scan_dirs:
-            print(f"  - {scan_dir.relative_to(repo_root)}")
-    except RuntimeError as e:
-        print(f"Error: {e}", file=sys.stderr)
-        sys.exit(1)
-
-    print("\nScanning for raw includes...")
-    # Find all #include directives
-    raw_includes: List[Tuple[str, str]] = []
-    rawincludes_file = results_dir / "rawincludes.txt"
-
-    # Write to file as we go to avoid storing everything in memory.
-    with open(rawincludes_file, "w", buffering=8192) as raw_f:
-        for dir_path in scan_dirs:
-            print(f"  Scanning {dir_path.relative_to(repo_root)}...")
-
-            for file_path in dir_path.rglob("*"):
-                if not file_path.is_file():
-                    continue
-
-                try:
-                    rel_path_str = str(file_path.relative_to(repo_root))
-
-                    # Read file with a large buffer for performance.
-                    with open(
-                        file_path,
-                        "r",
-                        encoding="utf-8",
-                        errors="ignore",
-                        buffering=8192,
-                    ) as f:
-                        for line in f:
-                            # Quick check before regex
-                            if "#include" not in line or "boost" in line:
-                                continue
-
-                            if INCLUDE_PATTERN.match(line):
-                                line_stripped = line.strip()
-                                entry = f"{rel_path_str}:{line_stripped}\n"
-                                print(entry, end="")
-                                raw_f.write(entry)
-                                raw_includes.append((rel_path_str, line_stripped))
-                except Exception as e:
-                    print(f"Error reading {file_path}: {e}", file=sys.stderr)
-
-    # Build levelization paths and count directly (no need to sort first).
-    print("Build levelization paths")
-    path_counts: Dict[Tuple[str, str], int] = defaultdict(int)
-
-    for file_path, include_line in raw_includes:
-        include_level = extract_include_level(include_line)
-        if not include_level:
-            continue
-
-        level = get_level(file_path)
-        if level != include_level:
-            path_counts[(level, include_level)] += 1
-
-    # Sort and deduplicate paths (using dictionary order like bash 'sort -d').
-    print("Sort and deduplicate paths")
-
-    paths_file = results_dir / "paths.txt"
-    with open(paths_file, "w") as f:
-        # Sort using dictionary order: only alphanumeric and spaces matter
-        sorted_items = sorted(
-            path_counts.items(),
-            key=lambda x: (dictionary_sort_key(x[0][0]), dictionary_sort_key(x[0][1])),
-        )
-        for (level, include_level), count in sorted_items:
-            line = f"{count:7} {level} {include_level}\n"
-            print(line.rstrip())
-            f.write(line)
-
-    # Split into flat-file database
-    print("Split into flat-file database")
-    includes_dir = results_dir / "includes"
-    included_by_dir = results_dir / "included_by"
-    includes_dir.mkdir()
-    included_by_dir.mkdir()
-
-    # Batch writes by grouping data first to avoid repeated file opens.
-    includes_data: Dict[str, List[Tuple[str, int]]] = defaultdict(list)
-    included_by_data: Dict[str, List[Tuple[str, int]]] = defaultdict(list)
-
-    # Process in sorted order to match bash script behaviour (dictionary order).
-    sorted_items = sorted(
-        path_counts.items(),
-        key=lambda x: (dictionary_sort_key(x[0][0]), dictionary_sort_key(x[0][1])),
-    )
-    for (level, include_level), count in sorted_items:
-        includes_data[level].append((include_level, count))
-        included_by_data[include_level].append((level, count))
-
-    # Write all includes files in sorted order (dictionary order).
-    for level in sorted(includes_data.keys(), key=dictionary_sort_key):
-        entries = includes_data[level]
-        with open(includes_dir / level, "w") as f:
-            for include_level, count in entries:
-                line = f"{include_level} {count}\n"
-                print(line.rstrip())
-                f.write(line)
-
-    # Write all included_by files in sorted order (dictionary order).
-    for include_level in sorted(included_by_data.keys(), key=dictionary_sort_key):
-        entries = included_by_data[include_level]
-        with open(included_by_dir / include_level, "w") as f:
-            for level, count in entries:
-                line = f"{level} {count}\n"
-                print(line.rstrip())
-                f.write(line)
-
-    # Search for loops
-    print("Search for loops")
-    loops_file = results_dir / "loops.txt"
-    ordering_file = results_dir / "ordering.txt"
-
-    loops_found: Set[Tuple[str, str]] = set()
-
-    # Pre-load all include files into memory to avoid repeated I/O.
-    # This is the biggest optimisation - we were reading files repeatedly in nested loops.
-    # Use list of tuples to preserve file order.
-    includes_cache: Dict[str, List[Tuple[str, int]]] = {}
-    includes_lookup: Dict[str, Dict[str, int]] = {}  # For fast lookup
-
-    # Note: bash script uses 'for source in *' which uses standard glob sorting,
-    # NOT dictionary order. So we use standard sorted() here, not dictionary_sort_key.
-    for include_file in sorted(includes_dir.iterdir(), key=lambda p: p.name):
-        if not include_file.is_file():
-            continue
-
-        includes_cache[include_file.name] = []
-        includes_lookup[include_file.name] = {}
-        with open(include_file, "r") as f:
-            for line in f:
-                parts = line.strip().split()
-                if len(parts) >= 2:
-                    include_name = parts[0]
-                    include_count = int(parts[1])
-                    includes_cache[include_file.name].append(
-                        (include_name, include_count)
-                    )
-                    includes_lookup[include_file.name][include_name] = include_count
-
-    with open(loops_file, "w", buffering=8192) as loops_f, open(
-        ordering_file, "w", buffering=8192
-    ) as ordering_f:
-
-        # Use standard sorting to match bash glob expansion 'for source in *'.
-        for source in sorted(includes_cache.keys()):
-            source_includes = includes_cache[source]
-
-            for include, include_freq in source_includes:
-                # Check if include file exists and references source
-                if include not in includes_lookup:
-                    continue
-
-                source_freq = includes_lookup[include].get(source)
-
-                if source_freq is not None:
-                    # Found a loop
-                    loop_key = tuple(sorted([source, include]))
-                    if loop_key in loops_found:
-                        continue
-                    loops_found.add(loop_key)
-
-                    loops_f.write(f"Loop: {source} {include}\n")
-
-                    # If the counts are close, indicate that the two modules are
-                    # on the same level, though they shouldn't be.
-                    diff = include_freq - source_freq
-                    if diff > 3:
-                        loops_f.write(f"  {source} > {include}\n\n")
-                    elif diff < -3:
-                        loops_f.write(f"  {include} > {source}\n\n")
-                    elif source_freq == include_freq:
-                        loops_f.write(f"  {include} == {source}\n\n")
-                    else:
-                        loops_f.write(f"  {include} ~= {source}\n\n")
-                else:
-                    ordering_f.write(f"{source} > {include}\n")
-
-    # Print results
-    print("\nOrdering:")
-    with open(ordering_file, "r") as f:
-        print(f.read(), end="")
-
-    print("\nLoops:")
-    with open(loops_file, "r") as f:
-        print(f.read(), end="")
-
-
-if __name__ == "__main__":
-    main()

.github/scripts/levelization/generate.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+
+# Usage: generate.sh
+# This script takes no parameters, reads no environment variables,
+# and can be run from any directory, as long as it is in the expected
+# location in the repo.
+
+pushd $( dirname $0 )
+
+if [ -v PS1 ]
+then
+  # if the shell is interactive, clean up any flotsam before analyzing
+  git clean -ix
+fi
+
+# Ensure all sorting is ASCII-order consistently across platforms.
+export LANG=C
+
+rm -rfv results
+mkdir results
+includes="$( pwd )/results/rawincludes.txt"
+pushd ../../..
+echo Raw includes:
+grep -r '^[ ]*#include.*/.*\.h' include src | \
+    grep -v boost | tee ${includes}
+popd
+pushd results
+
+oldifs=${IFS}
+IFS=:
+mkdir includes
+mkdir included_by
+echo Build levelization paths
+exec 3< ${includes} # open rawincludes.txt for input
+while read -r -u 3 file include
+do
+    level=$( echo ${file} | cut -d/ -f 2,3 )
+    # If the "level" indicates a file, cut off the filename
+    if [[ "${level##*.}" != "${level}" ]]
+    then
+        # Use the "toplevel" label as a workaround for `sort`
+        # inconsistencies between different utility versions
+        level="$( dirname ${level} )/toplevel"
+    fi
+    level=$( echo ${level} | tr '/' '.' )
+
+    includelevel=$( echo ${include} | sed 's/.*["<]//; s/[">].*//' | \
+        cut -d/ -f 1,2 )
+    if [[ "${includelevel##*.}" != "${includelevel}" ]]
+    then
+        # Use the "toplevel" label as a workaround for `sort`
+        # inconsistencies between different utility versions
+        includelevel="$( dirname ${includelevel} )/toplevel"
+    fi
+    includelevel=$( echo ${includelevel} | tr '/' '.' )
+
+    if [[ "$level" != "$includelevel" ]]
+    then
+        echo $level $includelevel | tee -a paths.txt
+    fi
+done
+echo Sort and deduplicate paths
+sort -ds paths.txt | uniq -c | tee sortedpaths.txt
+mv sortedpaths.txt paths.txt
+exec 3>&- #close fd 3
+IFS=${oldifs}
+unset oldifs
+
+echo Split into flat-file database
+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}
+done
+exec 4>&- #close fd 4
+
+loops="$( pwd )/loops.txt"
+ordering="$( pwd )/ordering.txt"
+pushd includes
+echo Search for loops
+# Redirect stdout to a file
+exec 4>&1
+exec 1>"${loops}"
+for source in *
+do
+  if [[ -f "$source" ]]
+  then
+    exec 5<"${source}" # open for input
+    while read -r -u 5 include includefreq
+    do
+      if [[ -f $include ]]
+      then
+        if grep -q -w $source $include
+        then
+          if grep -q -w "Loop: $include $source" "${loops}"
+          then
+            continue
+          fi
+          sourcefreq=$( grep -w $source $include | cut -d\  -f2 )
+          echo "Loop: $source $include"
+          # If the counts are close, indicate that the two modules are
+          # on the same level, though they shouldn't be
+          if [[ $(( $includefreq - $sourcefreq )) -gt 3 ]]
+          then
+              echo -e "  $source > $include\n"
+          elif [[ $(( $sourcefreq - $includefreq )) -gt 3 ]]
+          then
+              echo -e "  $include > $source\n"
+          elif [[ $sourcefreq -eq $includefreq ]]
+          then
+              echo -e "  $include == $source\n"
+          else
+              echo -e "  $include ~= $source\n"
+          fi
+        else
+          echo "$source > $include" >> "${ordering}"
+        fi
+      fi
+    done
+    exec 5>&- #close fd 5
+  fi
+done
+exec 1>&4 #close fd 1
+exec 4>&- #close fd 4
+cat "${ordering}"
+cat "${loops}"
+popd
+popd
+popd

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

@@ -2,19 +2,19 @@ Loop: test.jtx test.toplevel
   test.toplevel > test.jtx
 
 Loop: test.jtx test.unit_test
-  test.unit_test ~= test.jtx
+  test.unit_test == test.jtx
 
 Loop: xrpld.app xrpld.overlay
-  xrpld.app > xrpld.overlay
+  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
 
 Loop: xrpld.app xrpld.shamap
-  xrpld.shamap > xrpld.app
+  xrpld.shamap ~= xrpld.app
 
 Loop: xrpld.overlay xrpld.rpc
   xrpld.rpc ~= xrpld.overlay

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

@@ -3,17 +3,13 @@ libxrpl.conditions > xrpl.basics
 libxrpl.conditions > xrpl.conditions
 libxrpl.core > xrpl.basics
 libxrpl.core > xrpl.core
-libxrpl.core > xrpl.json
 libxrpl.crypto > xrpl.basics
 libxrpl.json > xrpl.basics
 libxrpl.json > xrpl.json
 libxrpl.ledger > xrpl.basics
 libxrpl.ledger > xrpl.json
 libxrpl.ledger > xrpl.ledger
-libxrpl.ledger > xrpl.nodestore
 libxrpl.ledger > xrpl.protocol
-libxrpl.ledger > xrpl.server
-libxrpl.ledger > xrpl.shamap
 libxrpl.net > xrpl.basics
 libxrpl.net > xrpl.net
 libxrpl.nodestore > xrpl.basics
@@ -24,23 +20,20 @@ libxrpl.protocol > xrpl.basics
 libxrpl.protocol > xrpl.json
 libxrpl.protocol > xrpl.protocol
 libxrpl.rdb > xrpl.basics
-libxrpl.rdb > xrpl.core
 libxrpl.rdb > xrpl.rdb
 libxrpl.resource > xrpl.basics
 libxrpl.resource > xrpl.json
-libxrpl.resource > xrpl.protocol
 libxrpl.resource > xrpl.resource
 libxrpl.server > xrpl.basics
-libxrpl.server > xrpl.core
 libxrpl.server > xrpl.json
 libxrpl.server > xrpl.protocol
 libxrpl.server > xrpl.rdb
-libxrpl.server > xrpl.resource
 libxrpl.server > xrpl.server
 libxrpl.shamap > xrpl.basics
-libxrpl.shamap > xrpl.nodestore
 libxrpl.shamap > xrpl.protocol
 libxrpl.shamap > xrpl.shamap
+libxrpl.telemetry > xrpl.basics
+libxrpl.telemetry > xrpl.telemetry
 libxrpl.tx > xrpl.basics
 libxrpl.tx > xrpl.conditions
 libxrpl.tx > xrpl.core
@@ -50,11 +43,12 @@ libxrpl.tx > xrpl.protocol
 libxrpl.tx > xrpl.server
 libxrpl.tx > xrpl.tx
 test.app > test.jtx
+test.app > test.rpc
+test.app > test.toplevel
 test.app > test.unit_test
 test.app > xrpl.basics
 test.app > xrpl.core
 test.app > xrpld.app
-test.app > xrpld.consensus
 test.app > xrpld.core
 test.app > xrpld.overlay
 test.app > xrpld.rpc
@@ -62,9 +56,9 @@ test.app > xrpl.json
 test.app > xrpl.ledger
 test.app > xrpl.nodestore
 test.app > xrpl.protocol
+test.app > xrpl.rdb
 test.app > xrpl.resource
 test.app > xrpl.server
-test.app > xrpl.shamap
 test.app > xrpl.tx
 test.basics > test.jtx
 test.basics > test.unit_test
@@ -77,29 +71,26 @@ test.beast > xrpl.basics
 test.conditions > xrpl.basics
 test.conditions > xrpl.conditions
 test.consensus > test.csf
-test.consensus > test.jtx
 test.consensus > test.toplevel
 test.consensus > test.unit_test
 test.consensus > xrpl.basics
 test.consensus > xrpld.app
 test.consensus > xrpld.consensus
+test.consensus > xrpl.json
 test.consensus > xrpl.ledger
-test.consensus > xrpl.protocol
-test.consensus > xrpl.shamap
 test.consensus > xrpl.tx
 test.core > test.jtx
+test.core > test.toplevel
 test.core > test.unit_test
 test.core > xrpl.basics
 test.core > xrpl.core
 test.core > xrpld.core
 test.core > xrpl.json
-test.core > xrpl.protocol
 test.core > xrpl.rdb
 test.core > xrpl.server
 test.csf > xrpl.basics
 test.csf > xrpld.consensus
 test.csf > xrpl.json
-test.csf > xrpl.ledger
 test.csf > xrpl.protocol
 test.json > test.jtx
 test.json > xrpl.json
@@ -116,32 +107,27 @@ test.jtx > xrpl.resource
 test.jtx > xrpl.server
 test.jtx > xrpl.tx
 test.ledger > test.jtx
+test.ledger > test.toplevel
 test.ledger > xrpl.basics
-test.ledger > xrpl.core
 test.ledger > xrpld.app
 test.ledger > xrpld.core
-test.ledger > xrpl.json
 test.ledger > xrpl.ledger
 test.ledger > xrpl.protocol
 test.nodestore > test.jtx
+test.nodestore > test.toplevel
 test.nodestore > test.unit_test
 test.nodestore > xrpl.basics
-test.nodestore > xrpld.core
 test.nodestore > xrpl.nodestore
-test.nodestore > xrpl.protocol
 test.nodestore > xrpl.rdb
 test.overlay > test.jtx
+test.overlay > test.toplevel
 test.overlay > test.unit_test
 test.overlay > xrpl.basics
 test.overlay > xrpld.app
-test.overlay > xrpld.core
 test.overlay > xrpld.overlay
 test.overlay > xrpld.peerfinder
-test.overlay > xrpl.json
 test.overlay > xrpl.nodestore
 test.overlay > xrpl.protocol
-test.overlay > xrpl.resource
-test.overlay > xrpl.server
 test.overlay > xrpl.shamap
 test.peerfinder > test.beast
 test.peerfinder > test.unit_test
@@ -149,8 +135,7 @@ test.peerfinder > xrpl.basics
 test.peerfinder > xrpld.core
 test.peerfinder > xrpld.peerfinder
 test.peerfinder > xrpl.protocol
-test.protocol > test.jtx
-test.protocol > test.unit_test
+test.protocol > test.toplevel
 test.protocol > xrpl.basics
 test.protocol > xrpl.json
 test.protocol > xrpl.protocol
@@ -158,6 +143,7 @@ test.resource > test.unit_test
 test.resource > xrpl.basics
 test.resource > xrpl.resource
 test.rpc > test.jtx
+test.rpc > test.toplevel
 test.rpc > xrpl.basics
 test.rpc > xrpl.core
 test.rpc > xrpld.app
@@ -171,12 +157,13 @@ test.rpc > xrpl.resource
 test.rpc > xrpl.server
 test.rpc > xrpl.tx
 test.server > test.jtx
+test.server > test.toplevel
 test.server > test.unit_test
 test.server > xrpl.basics
 test.server > xrpld.app
 test.server > xrpld.core
+test.server > xrpld.rpc
 test.server > xrpl.json
-test.server > xrpl.protocol
 test.server > xrpl.server
 test.shamap > test.unit_test
 test.shamap > xrpl.basics
@@ -186,22 +173,14 @@ test.shamap > xrpl.shamap
 test.toplevel > test.csf
 test.toplevel > xrpl.json
 test.unit_test > xrpl.basics
-test.unit_test > xrpl.protocol
 tests.libxrpl > xrpl.basics
-tests.libxrpl > xrpl.core
 tests.libxrpl > xrpl.json
-tests.libxrpl > xrpl.ledger
 tests.libxrpl > xrpl.net
-tests.libxrpl > xrpl.nodestore
-tests.libxrpl > xrpl.protocol
-tests.libxrpl > xrpl.protocol_autogen
-tests.libxrpl > xrpl.server
-tests.libxrpl > xrpl.shamap
-tests.libxrpl > xrpl.tx
 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
@@ -213,8 +192,6 @@ xrpl.nodestore > xrpl.basics
 xrpl.nodestore > xrpl.protocol
 xrpl.protocol > xrpl.basics
 xrpl.protocol > xrpl.json
-xrpl.protocol_autogen > xrpl.json
-xrpl.protocol_autogen > xrpl.protocol
 xrpl.rdb > xrpl.basics
 xrpl.rdb > xrpl.core
 xrpl.rdb > xrpl.protocol
@@ -231,6 +208,7 @@ 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
@@ -249,27 +227,26 @@ 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.consensus > xrpl.basics
 xrpld.consensus > xrpl.json
-xrpld.consensus > xrpl.ledger
 xrpld.consensus > xrpl.protocol
 xrpld.core > xrpl.basics
 xrpld.core > xrpl.core
+xrpld.core > xrpl.json
 xrpld.core > xrpl.net
 xrpld.core > xrpl.protocol
 xrpld.core > xrpl.rdb
 xrpld.overlay > xrpl.basics
 xrpld.overlay > xrpl.core
-xrpld.overlay > xrpld.consensus
 xrpld.overlay > xrpld.core
 xrpld.overlay > xrpld.peerfinder
 xrpld.overlay > xrpl.json
-xrpld.overlay > xrpl.ledger
 xrpld.overlay > xrpl.protocol
+xrpld.overlay > xrpl.rdb
 xrpld.overlay > xrpl.resource
 xrpld.overlay > xrpl.server
-xrpld.overlay > xrpl.shamap
 xrpld.overlay > xrpl.tx
 xrpld.peerfinder > xrpl.basics
 xrpld.peerfinder > xrpld.core
@@ -279,10 +256,10 @@ xrpld.perflog > xrpl.basics
 xrpld.perflog > xrpl.core
 xrpld.perflog > xrpld.rpc
 xrpld.perflog > xrpl.json
-xrpld.perflog > xrpl.protocol
 xrpld.rpc > xrpl.basics
 xrpld.rpc > xrpl.core
 xrpld.rpc > xrpld.core
+xrpld.rpc > xrpld.telemetry
 xrpld.rpc > xrpl.json
 xrpld.rpc > xrpl.ledger
 xrpld.rpc > xrpl.net
@@ -291,9 +268,6 @@ xrpld.rpc > xrpl.protocol
 xrpld.rpc > xrpl.rdb
 xrpld.rpc > xrpl.resource
 xrpld.rpc > xrpl.server
-xrpld.rpc > xrpl.shamap
 xrpld.rpc > xrpl.tx
-xrpld.shamap > xrpl.basics
-xrpld.shamap > xrpld.core
-xrpld.shamap > xrpl.protocol
 xrpld.shamap > xrpl.shamap
+xrpld.telemetry > xrpl.telemetry

.github/scripts/rename/README.md

@@ -34,8 +34,6 @@ run from the repository root.
 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.
-7. `.github/scripts/rename/docs.sh`: This script will rename any lingering
-   references of `ripple(d)` to `xrpl(d)` in code, comments, and documentation.
 
 You can run all these scripts from the repository root as follows:
 
@@ -46,5 +44,4 @@ You can run all these scripts from the repository root as follows:
 ./.github/scripts/rename/binary.sh .
 ./.github/scripts/rename/namespace.sh .
 ./.github/scripts/rename/config.sh .
-./.github/scripts/rename/docs.sh .
 ```

.github/scripts/rename/binary.sh

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

.github/scripts/rename/cmake.sh

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

.github/scripts/rename/config.sh

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

.github/scripts/rename/copyright.sh

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

.github/scripts/rename/definitions.sh

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

.github/scripts/rename/docs.sh

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

.github/scripts/rename/include.sh

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

.github/scripts/rename/namespace.sh

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

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

@@ -1,281 +1,333 @@
 #!/usr/bin/env python3
 import argparse
-import dataclasses
 import itertools
 import json
+from dataclasses import dataclass
 from pathlib import Path
 
 THIS_DIR = Path(__file__).parent.resolve()
 
-_BASE_CMAKE_ARGS = ["-Dtests=ON", "-Dwerr=ON", "-Dxrpld=ON", "-Dwextra=ON"]
 
-# Maps sanitizer names (as used in cmake) to short config-name suffixes.
-_SANITIZER_SUFFIX: dict[str, str] = {
-    "address": "asan",
-    "undefinedbehavior": "ubsan",
-    "thread": "tsan",
-}
-
-
-def get_cmake_args(build_type: str, extra_args: str) -> str:
-    """Get the full list of CMake arguments for a config."""
-    args = _BASE_CMAKE_ARGS.copy()
-    if build_type == "Release":
-        args.append("-Dassert=ON")
-    if extra_args:
-        args.extend(extra_args.split())
-    return " ".join(args)
-
-
-# ---------------------------------------------------------------------------
-# Input types — shapes of the JSON config files
-# ---------------------------------------------------------------------------
-
-
-@dataclasses.dataclass
-class LinuxConfig:
-    """One entry in linux.json's 'configs' or 'package_configs' arrays."""
-
-    compiler: list[str]
+@dataclass
+class Config:
+    architecture: list[dict]
+    os: list[dict]
     build_type: list[str]
-    arch: list[str]
-    sanitizers: list[str] = dataclasses.field(default_factory=list)
-    suffix: str = ""
-    extra_cmake_args: str = ""
-    image: str = ""  # only used by package_configs entries
+    cmake_args: list[str]
 
 
-@dataclasses.dataclass
-class LinuxFile:
-    """Shape of linux.json."""
+"""
+Generate a strategy matrix for GitHub Actions CI.
 
-    image_tag: str
-    configs: dict[str, list[LinuxConfig]]  # distro → configs
-    package_configs: dict[str, list[LinuxConfig]]  # distro → packaging configs
+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.
 
-    @classmethod
-    def load(cls, path: Path) -> "LinuxFile":
-        data = json.loads(path.read_text())
-
-        def parse(section: dict) -> dict[str, list[LinuxConfig]]:
-            return {
-                distro: [LinuxConfig(**c) for c in cfgs]
-                for distro, cfgs in section.items()
-            }
-
-        return cls(
-            image_tag=data["image_tag"],
-            configs=parse(data["configs"]),
-            package_configs=parse(data.get("package_configs", {})),
-        )
+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.
+"""
 
 
-@dataclasses.dataclass
-class PlatformConfig:
-    """One entry in macos.json's or windows.json's 'configs' array."""
+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"
 
-    build_type: list[str]
-    build_only: bool = False  # if true, skip tests (e.g. macos/Windows Debug)
-    extra_cmake_args: str = ""
+        # 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
 
-    def __post_init__(self) -> None:
-        if isinstance(self.build_type, str):
-            self.build_type = [self.build_type]
+        # 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/arm64, 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/arm64"
+                    ):
+                        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
 
-@dataclasses.dataclass
-class PlatformFile:
-    """Shape of macos.json and windows.json."""
+            # 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
 
-    platform: str  # e.g. "macos/arm64" or "windows/amd64"
-    runner: list[str]  # GitHub Actions runner labels
-    configs: list[PlatformConfig]
-
-    @classmethod
-    def load(cls, path: Path) -> "PlatformFile":
-        data = json.loads(path.read_text())
-        return cls(
-            platform=data["platform"],
-            runner=data["runner"],
-            configs=[PlatformConfig(**c) for c in data["configs"]],
-        )
-
-
-# ---------------------------------------------------------------------------
-# Output types — shapes of the generated GitHub Actions matrix entries
-# ---------------------------------------------------------------------------
-
-
-@dataclasses.dataclass
-class Architecture:
-    platform: str
-    runner: list[str]
-
-
-@dataclasses.dataclass
-class MatrixEntry:
-    """One entry in the generated build/test strategy matrix."""
-
-    config_name: str
-    cmake_args: str
-    cmake_target: str
-    build_only: bool
-    build_type: str
-    architecture: Architecture
-    sanitizers: str
-    image: str = ""  # container image; empty for macOS/Windows (runs natively)
-    compiler: str = ""  # compiler name ("gcc" or "clang"); empty for macOS/Windows
-
-
-@dataclasses.dataclass
-class PackagingEntry:
-    """One entry in the generated packaging strategy matrix."""
-
-    artifact_name: str
-    image: str
-    distro: str  # e.g. "debian" or "rhel"; drives package-format-specific steps
-
-
-# ---------------------------------------------------------------------------
-# Matrix expansion
-# ---------------------------------------------------------------------------
-
-_ARCHS: dict[str, Architecture] = {
-    "amd64": Architecture(
-        platform="linux/amd64", runner=["self-hosted", "Linux", "X64", "heavy"]
-    ),
-    "arm64": Architecture(
-        platform="linux/arm64",
-        runner=["self-hosted", "Linux", "ARM64", "heavy-arm64"],
-    ),
-}
-
-
-def expand_linux_matrix(linux: LinuxFile) -> list[MatrixEntry]:
-    """Expand a LinuxFile into a flat list of matrix entries.
-
-    Each config entry is expanded over the cross-product of its
-    compiler, build_type, sanitizers, and architecture lists.
-    """
-    entries: list[MatrixEntry] = []
-
-    for distro, configs in linux.configs.items():
-        for cfg in configs:
-            # An empty sanitizers list means "one entry with no sanitizer".
-            effective_sanitizers = cfg.sanitizers or [""]
-            effective_archs = {arch: _ARCHS[arch] for arch in cfg.arch}
-
-            for compiler, build_type, sanitizer, (arch, arch_info) in itertools.product(
-                cfg.compiler,
-                cfg.build_type,
-                effective_sanitizers,
-                effective_archs.items(),
+            # MacOS:
+            # - Debug on macos/arm64.
+            if os["distro_name"] == "macos" and not (
+                build_type == "Debug" and architecture["platform"] == "macos/arm64"
             ):
-                name = f"{distro}-{compiler}-{build_type.lower()}-{arch}"
-                suffix_parts = [
-                    s for s in [cfg.suffix, _SANITIZER_SUFFIX.get(sanitizer, "")] if s
-                ]
-                if suffix_parts:
-                    name += "-" + "-".join(suffix_parts)
+                continue
 
-                entries.append(
-                    MatrixEntry(
-                        config_name=name,
-                        image=f"ghcr.io/xrplf/xrpld/nix-{distro}:{linux.image_tag}",
-                        cmake_args=get_cmake_args(build_type, cfg.extra_cmake_args),
-                        cmake_target="all",
-                        build_only=False,
-                        build_type=build_type,
-                        architecture=arch_info,
-                        sanitizers=sanitizer,
-                        compiler=compiler,
-                    )
-                )
+            # Windows:
+            # - Release on windows/amd64.
+            if os["distro_name"] == "windows" and not (
+                build_type == "Release" and architecture["platform"] == "windows/amd64"
+            ):
+                continue
 
-    return entries
+        # 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":
+            continue
 
-def expand_linux_packaging(linux: LinuxFile) -> list[PackagingEntry]:
-    """Generate the packaging matrix from a LinuxFile's package_configs section.
+        # 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
 
-    Packaging uses vanilla distro images (debian:bookworm, ubi9, …) instead of
-    the nix-based build images, because deb/rpm tooling (debhelper, rpm-build)
-    is taken from the distro's archive rather than from nixpkgs. Each config
-    entry carries its own 'image'.
-    """
-    entries = []
-    for distro, configs in linux.package_configs.items():
-        for cfg in configs:
-            for compiler, build_type in itertools.product(cfg.compiler, cfg.build_type):
-                entries.append(
-                    PackagingEntry(
-                        artifact_name=f"xrpld-{distro}-{compiler}-{build_type.lower()}-amd64",
-                        image=cfg.image,
-                        distro=distro,
-                    )
-                )
+        # 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"
 
-    return entries
+        # 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:]}"
+        )
+        config_name += f"-{build_type.lower()}"
+        if "-Dcoverage=ON" in cmake_args:
+            config_name += "-coverage"
+        if "-Dunity=ON" in cmake_args:
+            config_name += "-unity"
 
-def expand_platform_matrix(pf: PlatformFile) -> list[MatrixEntry]:
-    """Expand a PlatformFile (macOS or Windows) into matrix entries."""
-    platform_name, arch = pf.platform.split("/")
-    is_windows = platform_name == "windows"
-
-    entries: list[MatrixEntry] = []
-    for cfg in pf.configs:
-        for build_type in cfg.build_type:
-            entries.append(
-                MatrixEntry(
-                    config_name=f"{platform_name}-{arch}-{build_type.lower()}",
-                    cmake_args=get_cmake_args(build_type, cfg.extra_cmake_args),
-                    cmake_target="install" if is_windows else "all",
-                    build_only=cfg.build_only,
-                    build_type=build_type,
-                    architecture=Architecture(platform=pf.platform, runner=pf.runner),
-                    sanitizers="",
-                )
+        # 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",
+                }
             )
-    return entries
+            # 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
 
 
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
+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
+    ):
+        raise Exception("Invalid configuration file.")
+
+    return Config(**config)
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
-        description="Generate a CI strategy matrix for all platforms or a specific one."
+    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",
     )
     parser.add_argument(
         "-c",
         "--config",
-        help="Platform to generate for ('linux', 'macos', or 'windows'). Defaults to all platforms.",
-        choices=["linux", "macos", "windows"],
-        default=None,
-    )
-    parser.add_argument(
-        "-p",
-        "--packaging",
-        help="Emit the Linux packaging matrix instead of the build/test matrix.",
-        action="store_true",
+        help="Path to the JSON file containing the strategy matrix configurations.",
+        required=False,
+        type=Path,
     )
     args = parser.parse_args()
 
-    matrix: list[MatrixEntry] | list[PackagingEntry] = []
-
-    if args.packaging:
-        matrix = expand_linux_packaging(LinuxFile.load(THIS_DIR / "linux.json"))
+    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:
-        if args.config in ("linux", None):
-            matrix += expand_linux_matrix(LinuxFile.load(THIS_DIR / "linux.json"))
-        if args.config in ("macos", None):
-            matrix += expand_platform_matrix(PlatformFile.load(THIS_DIR / "macos.json"))
-        if args.config in ("windows", None):
-            matrix += expand_platform_matrix(
-                PlatformFile.load(THIS_DIR / "windows.json")
-            )
+        matrix += generate_strategy_matrix(args.all, read_config(args.config))
 
-    print(f"matrix={json.dumps({'include': [dataclasses.asdict(e) for e in matrix]})}")
+    # Generate the strategy matrix.
+    print(f"matrix={json.dumps({'include': matrix})}")

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

@@ -1,83 +1,212 @@
 {
-  "image_tag": "sha-8abe82e",
-  "configs": {
-    "ubuntu": [
-      {
-        "compiler": ["gcc", "clang"],
-        "build_type": ["Debug", "Release"],
-        "arch": ["amd64", "arm64"]
-      },
-
-      {
-        "compiler": ["gcc", "clang"],
-        "build_type": ["Debug"],
-        "arch": ["amd64"],
-        "sanitizers": ["address", "undefinedbehavior"]
-      },
-
-      {
-        "compiler": ["gcc"],
-        "build_type": ["Debug"],
-        "arch": ["amd64"],
-        "suffix": "coverage",
-        "extra_cmake_args": "-DUNIT_TEST_REFERENCE_FEE=500 -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0"
-      },
-      {
-        "compiler": ["clang"],
-        "build_type": ["Debug"],
-        "arch": ["amd64"],
-        "suffix": "voidstar",
-        "extra_cmake_args": "-Dvoidstar=ON"
-      },
-      {
-        "compiler": ["clang"],
-        "build_type": ["Release"],
-        "arch": ["amd64"],
-        "suffix": "reffee",
-        "extra_cmake_args": "-DUNIT_TEST_REFERENCE_FEE=1000"
-      },
-      {
-        "compiler": ["gcc"],
-        "build_type": ["Debug"],
-        "arch": ["amd64"],
-        "suffix": "unity",
-        "extra_cmake_args": "-Dunity=ON"
-      }
-    ],
-
-    "debian": [
-      {
-        "compiler": ["gcc"],
-        "build_type": ["Release"],
-        "arch": ["amd64"]
-      }
-    ],
-
-    "rhel": [
-      {
-        "compiler": ["gcc"],
-        "build_type": ["Release"],
-        "arch": ["amd64"]
-      }
-    ]
-  },
-  "package_configs": {
-    "debian": [
-      {
-        "compiler": ["gcc"],
-        "build_type": ["Release"],
-        "arch": ["amd64"],
-        "image": "debian:bookworm"
-      }
-    ],
-
-    "rhel": [
-      {
-        "compiler": ["gcc"],
-        "build_type": ["Release"],
-        "arch": ["amd64"],
-        "image": "registry.access.redhat.com/ubi9/ubi:latest"
-      }
-    ]
-  }
+  "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/macos.json

@@ -1,15 +1,19 @@
 {
-  "platform": "macos/arm64",
-  "runner": ["self-hosted", "macOS", "ARM64", "mac-runner-m1"],
-  "configs": [
+  "architecture": [
     {
-      "build_type": "Release",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5"
-    },
-    {
-      "build_type": "Debug",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
-      "build_only": true
+      "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/windows.json

@@ -1,8 +1,19 @@
 {
-  "platform": "windows/amd64",
-  "runner": ["self-hosted", "Windows", "devbox"],
-  "configs": [
-    { "build_type": "Release" },
-    { "build_type": "Debug", "build_only": true }
-  ]
+  "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/workflows/build-nix-images.yml

@@ -1,56 +0,0 @@
-name: Build Nix Docker images
-
-on:
-  push:
-    branches:
-      - develop
-    paths:
-      - ".github/workflows/build-nix-images.yml"
-      - ".github/workflows/reusable-build-docker-image.yml"
-      - ".github/workflows/reusable-build-merge-docker-images.yml"
-      - "flake.nix"
-      - "flake.lock"
-      - "nix/**"
-  pull_request:
-    paths:
-      - ".github/workflows/build-nix-images.yml"
-      - ".github/workflows/reusable-build-docker-image.yml"
-      - ".github/workflows/reusable-build-merge-docker-images.yml"
-      - "flake.nix"
-      - "flake.lock"
-      - "nix/**"
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  build-merge:
-    name: Build and push nix-${{ matrix.distro.name }}
-    permissions:
-      contents: read
-      packages: write
-    strategy:
-      fail-fast: false
-      matrix:
-        # The base images are the oldest supported version of each distro
-        # that we want to build images for.
-        distro:
-          - name: nixos
-            base_image: nixos/nix:latest
-          - name: ubuntu
-            base_image: ubuntu:20.04
-          - name: debian
-            base_image: debian:bookworm
-          - name: rhel
-            base_image: registry.access.redhat.com/ubi9/ubi:latest
-    uses: ./.github/workflows/reusable-build-merge-docker-images.yml
-    with:
-      image_name: ghcr.io/xrplf/xrpld/nix-${{ matrix.distro.name }}
-      dockerfile: nix/docker/Dockerfile
-      base_image: ${{ matrix.distro.base_image }}

.github/workflows/build-packaging-images.yml

@@ -1,48 +0,0 @@
-name: Build packaging Docker images
-
-on:
-  push:
-    branches:
-      - develop
-    paths:
-      - ".github/workflows/build-packaging-images.yml"
-      - ".github/workflows/reusable-build-docker-image.yml"
-      - ".github/workflows/reusable-build-merge-docker-images.yml"
-      - "package/Dockerfile"
-      - "package/install-packaging-tools.sh"
-  pull_request:
-    paths:
-      - ".github/workflows/build-packaging-images.yml"
-      - ".github/workflows/reusable-build-docker-image.yml"
-      - ".github/workflows/reusable-build-merge-docker-images.yml"
-      - "package/Dockerfile"
-      - "package/install-packaging-tools.sh"
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  build-merge:
-    name: Build and push packaging-${{ matrix.distro.name }}
-    permissions:
-      contents: read
-      packages: write
-    strategy:
-      fail-fast: false
-      matrix:
-        distro:
-          - name: debian
-            base_image: debian:bookworm
-          - name: rhel
-            base_image: registry.access.redhat.com/ubi9/ubi:latest
-    uses: ./.github/workflows/reusable-build-merge-docker-images.yml
-    with:
-      image_name: ghcr.io/xrplf/xrpld/packaging-${{ matrix.distro.name }}
-      dockerfile: package/Dockerfile
-      base_image: ${{ matrix.distro.base_image }}

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

@@ -1,13 +0,0 @@
-name: Check PR commits
-
-on:
-  pull_request_target:
-
-# The action needs to have write permissions to post comments on the PR.
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  check_commits:
-    uses: XRPLF/actions/.github/workflows/check-pr-commits.yml@e2c7f400d1e85ae65dad552fd425169fbacca4a3

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

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

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

@@ -1,23 +0,0 @@
-name: Check PR title
-
-on:
-  merge_group:
-    types:
-      - checks_requested
-  pull_request:
-    types:
-      - opened
-      - edited
-      - reopened
-      - synchronize
-      - ready_for_review
-    branches:
-      - develop
-      - "release-*"
-      - "release/*"
-      - "staging/*"
-
-jobs:
-  check_title:
-    if: ${{ github.event.pull_request.draft != true }}
-    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@cba1f0891650baf1a9c88624dc2d72573be2eb81

.github/workflows/conflicting-pr.yml

@@ -1,25 +0,0 @@
-name: Label PRs with merge conflicts
-
-on:
-  # So that PRs touching the same files as the push are updated.
-  push:
-  # So that the `dirtyLabel` is removed if conflicts are resolved.
-  # We recommend `pull_request_target` so that github secrets are available.
-  # In `pull_request` we wouldn't be able to change labels of fork PRs.
-  pull_request_target:
-    types: [synchronize]
-
-permissions:
-  pull-requests: write
-
-jobs:
-  main:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check if PRs are dirty
-        uses: eps1lon/actions-label-merge-conflict@0273be72a0bbd58fcd71d0d6c02c209b50d1e5e1 # v3.1.0
-        with:
-          dirtyLabel: "PR: has conflicts"
-          repoToken: "${{ secrets.GITHUB_TOKEN }}"
-          commentOnDirty: "This PR has conflicts, please resolve them in order for the PR to be reviewed."
-          commentOnClean: "All conflicts have been resolved. Assigned reviewers can now start or resume their review."

.github/workflows/on-pr.yml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - 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 +46,7 @@ jobs:
         # that Github considers any skipped jobs to have passed, and in
         # turn the required checks as well.
         id: changes
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
+        uses: tj-actions/changed-files@7dee1b0c1557f278e5c7dc244927139d78c0e22a # v47.0.4
         with:
           files: |
             # These paths are unique to `on-pr.yml`.
@@ -58,19 +58,20 @@ jobs:
 
             # 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-package.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
-            cfg/**
             cmake/**
             conan/**
             external/**
@@ -80,10 +81,6 @@ jobs:
             CMakeLists.txt
             conanfile.py
             conan.lock
-            LICENSE.md
-            package/**
-            README.md
-
       - name: Check whether to run
         # This step determines whether the rest of the workflow should
         # run. The rest of the workflow will run if this job runs AND at
@@ -98,7 +95,7 @@ jobs:
           READY: ${{ contains(github.event.pull_request.labels.*.name, 'Ready to merge') }}
           MERGE: ${{ github.event_name == 'merge_group' }}
         run: |
-          echo "go=${{ (env.DRAFT != 'true' && env.READY == 'true') || env.FILES == 'true' || env.MERGE == 'true' }}" >>"${GITHUB_OUTPUT}"
+          echo "go=${{ (env.DRAFT != 'true' && env.READY == 'true') || env.FILES == 'true' || env.MERGE == 'true' }}" >> "${GITHUB_OUTPUT}"
           cat "${GITHUB_OUTPUT}"
     outputs:
       go: ${{ steps.go.outputs.go == 'true' }}
@@ -140,17 +137,13 @@ jobs:
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-  package:
-    needs: [should-run, build-test]
-    if: ${{ needs.should-run.outputs.go == 'true' }}
-    uses: ./.github/workflows/reusable-package.yml
-
   upload-recipe:
     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') }}
+    # Only run when committing to a PR that targets a release branch in the
+    # XRPLF repository.
+    if: ${{ github.repository_owner == 'XRPLF' && needs.should-run.outputs.go == 'true' && startsWith(github.ref, 'refs/heads/release') }}
     uses: ./.github/workflows/reusable-upload-recipe.yml
     secrets:
       remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
@@ -168,9 +161,9 @@ jobs:
           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}"
+          /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}"
 
   passed:
     if: failure() || cancelled()
@@ -179,10 +172,9 @@ jobs:
       - check-rename
       - clang-tidy
       - build-test
-      - package
       - upload-recipe
       - notify-clio
     runs-on: ubuntu-latest
     steps:
       - name: Fail
-        run: exit 1
+        run: false

.github/workflows/on-tag.yml

@@ -1,11 +1,11 @@
-# This workflow uploads the libxrpl recipe to the Conan remote and builds
-# release packages when a versioned tag is pushed.
+# This workflow uploads the libxrpl recipe to the Conan remote when a versioned
+# tag is pushed.
 name: Tag
 
 on:
   push:
     tags:
-      - "[0-9]+.[0-9]+.[0-9]*"
+      - "v*"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -17,26 +17,9 @@ defaults:
 
 jobs:
   upload-recipe:
-    if: ${{ github.repository == 'XRPLF/rippled' }}
+    # Only run when a tag is pushed to the XRPLF repository.
+    if: ${{ github.repository_owner == 'XRPLF' }}
     uses: ./.github/workflows/reusable-upload-recipe.yml
     secrets:
       remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
       remote_password: ${{ secrets.CONAN_REMOTE_PASSWORD }}
-
-  build-test:
-    if: ${{ github.repository == 'XRPLF/rippled' }}
-    uses: ./.github/workflows/reusable-build-test.yml
-    strategy:
-      fail-fast: true
-      matrix:
-        os: [linux]
-    with:
-      ccache_enabled: false
-      os: ${{ matrix.os }}
-    secrets:
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
-  package:
-    if: ${{ github.repository == 'XRPLF/rippled' }}
-    needs: build-test
-    uses: ./.github/workflows/reusable-package.yml

.github/workflows/on-trigger.yml

@@ -15,19 +15,20 @@ 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-package.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"
-      - "cfg/**"
       - "cmake/**"
       - "conan/**"
       - "external/**"
@@ -37,9 +38,6 @@ on:
       - "CMakeLists.txt"
       - "conanfile.py"
       - "conan.lock"
-      - "LICENSE.md"
-      - "package/**"
-      - "README.md"
 
   # Run at 06:32 UTC on every day of the week from Monday through Friday. This
   # will force all dependencies to be rebuilt, which is useful to verify that
@@ -88,18 +86,15 @@ jobs:
       # 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' }}
     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' }}
+    # Only run when pushing to the develop branch in the XRPLF repository.
+    if: ${{ github.repository_owner == 'XRPLF' && 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 }}
-
-  package:
-    needs: build-test
-    uses: ./.github/workflows/reusable-package.yml

.github/workflows/pre-commit.yml

@@ -1,9 +1,6 @@
 name: Run pre-commit hooks
 
 on:
-  merge_group:
-    types:
-      - checks_requested
   pull_request:
   push:
     branches:
@@ -14,7 +11,7 @@ on:
 jobs:
   # Call the workflow in the XRPLF/actions repo that runs the pre-commit hooks.
   run-hooks:
-    uses: XRPLF/actions/.github/workflows/pre-commit.yml@cba1f0891650baf1a9c88624dc2d72573be2eb81
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@320be44621ca2a080f05aeb15817c44b84518108
     with:
       runs_on: ubuntu-latest
       container: '{ "image": "ghcr.io/xrplf/ci/tools-rippled-pre-commit:sha-41ec7c1" }'

.github/workflows/publish-docs.yml

@@ -6,6 +6,7 @@ on:
   push:
     branches:
       - "develop"
+      - "release*"
     paths:
       - ".github/workflows/publish-docs.yml"
       - "*.md"
@@ -36,20 +37,17 @@ 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.visibility == 'public' && '2' || '1' }}
+  NPROC_SUBTRACT: ${{ github.event.repository.private && '1' || '2' }}
 
 jobs:
-  build:
+  publish:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-8abe82e
+    container: ghcr.io/xrplf/ci/tools-rippled-documentation:sha-a8c7be1
+    permissions:
+      contents: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
-        with:
-          enable_ccache: false
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Get number of processors
         uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
@@ -57,11 +55,19 @@ jobs:
         with:
           subtract: ${{ env.NPROC_SUBTRACT }}
 
-      - name: Print build environment
-        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
+      - name: Check configuration
+        run: |
+          echo 'Checking path.'
+          echo ${PATH} | tr ':' '\n'
 
-      - name: Check Doxygen version
-        run: doxygen --version
+          echo 'Checking environment variables.'
+          env | sort
+
+          echo 'Checking CMake version.'
+          cmake --version
+
+          echo 'Checking Doxygen version.'
+          doxygen --version
 
       - name: Build documentation
         env:
@@ -72,23 +78,9 @@ jobs:
           cmake -Donly_docs=ON ..
           cmake --build . --target docs --parallel ${BUILD_NPROC}
 
-      - name: Create documentation artifact
-        if: ${{ github.event.repository.visibility == 'public' && github.event_name == 'push' }}
-        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+      - name: Publish documentation
+        if: ${{ github.event_name == 'push' }}
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
-          path: ${{ env.BUILD_DIR }}/docs/html
-
-  deploy:
-    if: ${{ github.repository == 'XRPLF/rippled' && 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@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.BUILD_DIR }}/docs/html

.github/workflows/reusable-build-docker-image.yml

@@ -1,89 +0,0 @@
-# Build a single-platform Docker image. On push, the image is pushed to
-# GHCR with arch-suffixed tags (e.g. `:latest-amd64`, `:sha-abc-amd64`)
-# so the calling workflow can stitch per-arch builds into a multi-arch
-# manifest without needing to pass digests around.
-name: Reusable build Docker image (single platform)
-
-on:
-  workflow_call:
-    inputs:
-      image_name:
-        description: "Full image name without tag (e.g. 'ghcr.io/xrplf/xrpld/nix-ubuntu')"
-        required: true
-        type: string
-      dockerfile:
-        description: "Path to the Dockerfile, relative to the repository root"
-        required: true
-        type: string
-      base_image:
-        description: "Value passed to the Dockerfile as the BASE_IMAGE build arg"
-        required: true
-        type: string
-      platform:
-        description: "Docker platform string, e.g. linux/amd64"
-        required: true
-        type: string
-      runner:
-        description: "GitHub Actions runner label to build on"
-        required: true
-        type: string
-      push:
-        description: "Whether to push the image to GHCR"
-        required: true
-        type: boolean
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  build:
-    name: Build ${{ inputs.platform }}
-    runs-on: ${{ inputs.runner }}
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-
-      - name: Determine arch
-        id: vars
-        env:
-          PLATFORM: ${{ inputs.platform }}
-        run: |
-          echo "arch=${PLATFORM##*/}" >>$GITHUB_OUTPUT
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
-
-      - name: Login to GitHub Container Registry
-        if: inputs.push
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Docker metadata
-        id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
-        with:
-          images: ${{ inputs.image_name }}
-          tags: |
-            type=sha,prefix=sha-,format=short
-            type=raw,value=latest
-          flavor: |
-            suffix=-${{ steps.vars.outputs.arch }},onlatest=true
-
-      - name: Build and push
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
-        with:
-          context: .
-          file: ${{ inputs.dockerfile }}
-          platforms: ${{ inputs.platform }}
-          push: ${{ inputs.push }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          build-args: BASE_IMAGE=${{ inputs.base_image }}

.github/workflows/reusable-build-merge-docker-images.yml

@@ -1,89 +0,0 @@
-name: Reusable build and merge Docker image (multi-arch)
-
-on:
-  workflow_call:
-    inputs:
-      image_name:
-        description: "Full image name without tag (e.g. 'ghcr.io/xrplf/xrpld/nix-ubuntu')"
-        required: true
-        type: string
-      dockerfile:
-        description: "Path to the Dockerfile, relative to the repository root"
-        required: true
-        type: string
-      base_image:
-        description: "Value passed to the Dockerfile as the BASE_IMAGE build arg"
-        required: true
-        type: string
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  build:
-    name: Build ${{ inputs.image_name }}
-    permissions:
-      contents: read
-      packages: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        target:
-          - platform: linux/amd64
-            runner: ubuntu-latest
-          - platform: linux/arm64
-            runner: ubuntu-24.04-arm
-
-    uses: ./.github/workflows/reusable-build-docker-image.yml
-    with:
-      image_name: ${{ inputs.image_name }}
-      dockerfile: ${{ inputs.dockerfile }}
-      base_image: ${{ inputs.base_image }}
-      platform: ${{ matrix.target.platform }}
-      runner: ${{ matrix.target.runner }}
-      push: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' }}
-
-  merge:
-    name: Merge ${{ inputs.image_name }}
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
-
-      - name: Docker metadata
-        id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
-        with:
-          images: ${{ inputs.image_name }}
-          tags: |
-            type=sha,prefix=sha-,format=short
-            type=raw,value=latest
-
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create multi-arch manifests
-        if: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' }}
-        run: |
-          for tag in $(jq -cr '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do
-              docker buildx imagetools create -t "$tag" "${tag}-amd64" "${tag}-arm64"
-          done
-
-      - name: Inspect image
-        if: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' }}
-        env:
-          IMAGE_NAME: ${{ inputs.image_name }}
-          IMAGE_VERSION: ${{ steps.meta.outputs.version }}
-        run: |
-          docker buildx imagetools inspect "${IMAGE_NAME}:${IMAGE_VERSION}"

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

@@ -57,12 +57,6 @@ on:
         type: string
         default: ""
 
-      compiler:
-        description: 'The compiler to use ("gcc" or "clang"). Leave empty for macOS/Windows (uses system default).'
-        required: false
-        type: string
-        default: ""
-
     secrets:
       CODECOV_TOKEN:
         description: "The Codecov token to use for uploading coverage reports."
@@ -82,7 +76,7 @@ jobs:
     name: ${{ inputs.config_name }}
     runs-on: ${{ fromJSON(inputs.runs_on) }}
     container: ${{ inputs.image != '' && inputs.image || null }}
-    timeout-minutes: ${{ inputs.sanitizers != '' && 360 || 60 }}
+    timeout-minutes: 60
     env:
       # Use a namespace to keep the objects separate for each configuration.
       CCACHE_NAMESPACE: ${{ inputs.config_name }}
@@ -107,22 +101,22 @@ jobs:
     steps:
       - name: Cleanup workspace (macOS and Windows)
         if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
-        uses: XRPLF/actions/cleanup-workspace@c7d9ce5ebb03c752a354889ecd870cadfc2b1cd4
+        uses: XRPLF/actions/cleanup-workspace@cf0433aa74563aead044a1e395610c96d65a37cf
 
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
+        uses: XRPLF/actions/prepare-runner@2cbf481018d930656e9276fcc20dc0e3a0be5b6d
         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}"
+        run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >> "${GITHUB_ENV}"
 
       - name: Print build environment
-        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
+        uses: ./.github/actions/print-env
 
       - name: Get number of processors
         uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
@@ -130,12 +124,6 @@ jobs:
         with:
           subtract: ${{ inputs.nproc_subtract }}
 
-      - name: Set compiler environment (Linux)
-        if: ${{ runner.os == 'Linux' }}
-        uses: ./.github/actions/set-compiler-env
-        with:
-          compiler: ${{ inputs.compiler }}
-
       - name: Setup Conan
         env:
           SANITIZERS: ${{ inputs.sanitizers }}
@@ -155,40 +143,15 @@ jobs:
         working-directory: ${{ env.BUILD_DIR }}
         env:
           BUILD_TYPE: ${{ inputs.build_type }}
+          SANITIZERS: ${{ inputs.sanitizers }}
           CMAKE_ARGS: ${{ inputs.cmake_args }}
         run: |
           cmake \
-              -G '${{ runner.os == 'Windows' && 'Visual Studio 17 2022' || 'Ninja' }}' \
-              -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-              -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
-              ${CMAKE_ARGS} \
-              ..
-
-      - name: Check protocol autogen files are up-to-date
-        working-directory: ${{ env.BUILD_DIR }}
-        env:
-          MESSAGE: |
-
-            The generated protocol wrapper classes are out of date.
-
-            This typically happens when the macro files or generator scripts
-            have changed but the generated files were not regenerated.
-
-            To fix this:
-              1. Run: cmake --build . --target setup_code_gen
-              2. Run: cmake --build . --target code_gen
-              3. Commit and push the regenerated files
-        run: |
-          set -e
-          cmake --build . --target setup_code_gen
-          cmake --build . --target code_gen
-          DIFF=$(git -C .. status --porcelain -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen)
-          if [ -n "${DIFF}" ]; then
-              echo "::error::Generated protocol files are out of date"
-              git -C .. diff -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen
-              echo "${MESSAGE}"
-              exit 1
-          fi
+            -G '${{ runner.os == 'Windows' && 'Visual Studio 17 2022' || 'Ninja' }}' \
+            -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
+            -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
+            ${CMAKE_ARGS} \
+            ..
 
       - name: Build the binary
         working-directory: ${{ env.BUILD_DIR }}
@@ -198,79 +161,39 @@ jobs:
           CMAKE_TARGET: ${{ inputs.cmake_target }}
         run: |
           cmake \
-              --build . \
-              --config "${BUILD_TYPE}" \
-              --parallel "${BUILD_NPROC}" \
-              --target "${CMAKE_TARGET}"
-
-      # This step is needed to allow running in non-Nix environments
-      - name: Patch binary to use default loader and remove rpath (Linux)
-        if: ${{ runner.os == 'Linux' && env.SANITIZERS_ENABLED == 'false' }}
-        run: |
-          loader="$(/tmp/loader-path.sh)"
-          patchelf --set-interpreter "${loader}" --remove-rpath "${{ env.BUILD_DIR }}/xrpld"
-
-      # We're only running aarch64 Linux builds in Ubuntu-based images, so this is kept simple
-      - name: Install libatomic (Linux aarch64)
-        if: ${{ runner.os == 'Linux' && runner.arch == 'ARM64' }}
-        run: |
-          apt update --yes
-          apt install -y --no-install-recommends \
-              libatomic1
+            --build . \
+            --config "${BUILD_TYPE}" \
+            --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
+            cat "${CCACHE_LOGFILE}"
+            curl ${CCACHE_REMOTE_STORAGE%|*}/status || true
           fi
 
       - name: Upload the binary (Linux)
-        if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: ${{ github.repository_owner == 'XRPLF' && runner.os == 'Linux' }}
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         with:
           name: xrpld-${{ inputs.config_name }}
           path: ${{ env.BUILD_DIR }}/xrpld
           retention-days: 3
           if-no-files-found: error
 
-      - name: Upload the test binary (Linux)
-        if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: xrpl_tests-${{ inputs.config_name }}
-          path: ${{ env.BUILD_DIR }}/xrpl_tests
-          retention-days: 3
-          if-no-files-found: error
-
-      - name: Export server definitions
-        if: ${{ runner.os != 'Windows' && !inputs.build_only && env.VOIDSTAR_ENABLED != 'true' }}
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          set -o pipefail
-          ./xrpld --definitions | python3 -m json.tool >server_definitions.json
-
-      - name: Upload server definitions
-        if: ${{ github.event.repository.visibility == 'public' && inputs.config_name == 'debian-gcc-release-amd64' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: server-definitions
-          path: ${{ env.BUILD_DIR }}/server_definitions.json
-          retention-days: 3
-          if-no-files-found: error
-
       - name: Check linking (Linux)
         if: ${{ runner.os == 'Linux' && env.SANITIZERS_ENABLED == 'false' }}
         working-directory: ${{ env.BUILD_DIR }}
         run: |
           ldd ./xrpld
           if [ "$(ldd ./xrpld | grep -E '(libstdc\+\+|libgcc)' | wc -l)" -eq 0 ]; then
-              echo 'The binary is statically linked.'
+            echo 'The binary is statically linked.'
           else
-              echo 'The binary is dynamically linked.'
-              exit 1
+            echo 'The binary is dynamically linked.'
+            exit 1
           fi
 
       - name: Verify presence of instrumentation (Linux)
@@ -281,22 +204,24 @@ jobs:
 
       - name: Set sanitizer options
         if: ${{ !inputs.build_only && env.SANITIZERS_ENABLED == 'true' }}
-        env:
-          CONFIG_NAME: ${{ inputs.config_name }}
         run: |
-          ASAN_OPTS="include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-asan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/asan.supp"
-          if [[ "${CONFIG_NAME}" == *gcc* ]]; then
-              ASAN_OPTS="${ASAN_OPTS}:alloc_dealloc_mismatch=0"
-          fi
-          echo "ASAN_OPTIONS=${ASAN_OPTS}" >>${GITHUB_ENV}
-          echo "TSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-tsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/tsan.supp" >>${GITHUB_ENV}
-          echo "UBSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-ubsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/ubsan.supp" >>${GITHUB_ENV}
-          echo "LSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-lsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/lsan.supp" >>${GITHUB_ENV}
+          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 }}
-        working-directory: ${{ runner.os == 'Windows' && format('{0}/{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
-        run: ./xrpl_tests
+        working-directory: ${{ env.BUILD_DIR }}
+        # Windows locks some of the build files while running tests, and parallel jobs can collide
+        env:
+          BUILD_TYPE: ${{ inputs.build_type }}
+          PARALLELISM: ${{ runner.os == 'Windows' && '1' || steps.nproc.outputs.nproc }}
+        run: |
+          ctest \
+            --output-on-failure \
+            -C "${BUILD_TYPE}" \
+            -j "${PARALLELISM}"
 
       - name: Run the embedded tests
         if: ${{ !inputs.build_only }}
@@ -304,49 +229,8 @@ jobs:
         env:
           BUILD_NPROC: ${{ steps.nproc.outputs.nproc }}
         run: |
-          set -o pipefail
-          # Coverage builds are slower due to instrumentation; use fewer parallel jobs to avoid flakiness
-          [ "$COVERAGE_ENABLED" = "true" ] && BUILD_NPROC=$((BUILD_NPROC - 2))
+          ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}"
 
-          # The resolver/preload workaround is only correct for the ASan build:
-          # a regular build doesn't hit the __dn_expand interceptor bug, and must
-          # NOT have libasan injected. So only preload when xrpld is ASan-built.
-          #
-          # libresolv hosts getaddrinfo's resolver helpers (dn_expand, res_*). Under ASan
-          # these are intercepted via dlsym(RTLD_NEXT, ...), which yields a NULL pointer
-          # and crashes DNS resolution if libresolv isn't loaded. Linking it guarantees
-          # the symbols are present; it's a harmless no-op on glibc >= 2.34 (merged into
-          # libc) and is what the compiler driver already does for sanitizer builds.
-          #   https://github.com/llvm/llvm-project/issues/59007
-          #   https://github.com/google/sanitizers/issues/1592
-          if ldd ./xrpld | grep -q libasan; then
-              PRELOAD="$(gcc -print-file-name=libasan.so):/usr/lib/x86_64-linux-gnu/libresolv.so.2"
-          else
-              PRELOAD=""
-          fi
-
-          LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee unittest.log
-
-      - name: Show test failure summary
-        if: ${{ failure() && !inputs.build_only }}
-        env:
-          WORKING_DIR: ${{ runner.os == 'Windows' && format('{0}\{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
-        run: |
-          if [ ! -d "${WORKING_DIR}" ]; then
-              echo "Working directory '${WORKING_DIR}' does not exist."
-              exit 0
-          fi
-
-          cd "${WORKING_DIR}"
-
-          if [ ! -f unittest.log ]; then
-              echo "unittest.log not found; embedded tests may not have run."
-              exit 0
-          fi
-
-          if ! grep -E "failed" unittest.log; then
-              echo "Log present but no failure lines found in unittest.log."
-          fi
       - name: Debug failure (Linux)
         if: ${{ failure() && runner.os == 'Linux' && !inputs.build_only }}
         run: |
@@ -363,14 +247,14 @@ jobs:
           BUILD_TYPE: ${{ inputs.build_type }}
         run: |
           cmake \
-              --build . \
-              --config "${BUILD_TYPE}" \
-              --parallel "${BUILD_NPROC}" \
-              --target coverage
+            --build . \
+            --config "${BUILD_TYPE}" \
+            --parallel "${BUILD_NPROC}" \
+            --target coverage
 
       - name: Upload coverage report
-        if: ${{ github.repository == 'XRPLF/rippled' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        if: ${{ github.repository_owner == 'XRPLF' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
         with:
           disable_search: true
           disable_telem: true

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

@@ -19,6 +19,13 @@ on:
         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."
@@ -30,6 +37,7 @@ jobs:
     uses: ./.github/workflows/reusable-strategy-matrix.yml
     with:
       os: ${{ inputs.os }}
+      strategy_matrix: ${{ inputs.strategy_matrix }}
 
   # Build and test the binary for each configuration.
   build-test-config:
@@ -39,6 +47,7 @@ jobs:
     strategy:
       fail-fast: ${{ github.event_name == 'merge_group' }}
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
+      max-parallel: 10
     with:
       build_only: ${{ matrix.build_only }}
       build_type: ${{ matrix.build_type }}
@@ -46,9 +55,8 @@ jobs:
       cmake_args: ${{ matrix.cmake_args }}
       cmake_target: ${{ matrix.cmake_target }}
       runs_on: ${{ toJSON(matrix.architecture.runner) }}
-      image: ${{ matrix.image || '' }}
+      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) || '' }}
       config_name: ${{ matrix.config_name }}
       sanitizers: ${{ matrix.sanitizers }}
-      compiler: ${{ matrix.compiler || '' }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

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

@@ -18,9 +18,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Check levelization
-        run: python .github/scripts/levelization/generate.py
+        run: .github/scripts/levelization/generate.sh
       - name: Check for differences
         env:
           MESSAGE: |
@@ -32,15 +32,15 @@ jobs:
             removed from loops.txt, it's probably an improvement, while if
             something was added, it's probably a regression.
 
-            Run '.github/scripts/levelization/generate.py' in your repo, commit
+            Run '.github/scripts/levelization/generate.sh' in your repo, commit
             and push the changes. See .github/scripts/levelization/README.md for
             more info.
         run: |
           DIFF=$(git status --porcelain)
           if [ -n "${DIFF}" ]; then
-              # Print the differences to give the contributor a hint about what to
-              # expect when running levelization on their own machine.
-              git diff
-              echo "${MESSAGE}"
-              exit 1
+            # Print the differences to give the contributor a hint about what to
+            # expect when running levelization on their own machine.
+            git diff
+            echo "${MESSAGE}"
+            exit 1
           fi

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

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Check definitions
         run: .github/scripts/rename/definitions.sh .
       - name: Check copyright notices
@@ -33,8 +33,6 @@ jobs:
         run: .github/scripts/rename/config.sh .
       - name: Check include guards
         run: .github/scripts/rename/include.sh .
-      - name: Check documentation
-        run: .github/scripts/rename/docs.sh .
       - name: Check for differences
         env:
           MESSAGE: |
@@ -48,9 +46,9 @@ jobs:
         run: |
           DIFF=$(git status --porcelain)
           if [ -n "${DIFF}" ]; then
-              # Print the differences to give the contributor a hint about what to
-              # expect when running the renaming scripts on their own machine.
-              git diff
-              echo "${MESSAGE}"
-              exit 1
+            # Print the differences to give the contributor a hint about what to
+            # expect when running the renaming scripts on their own machine.
+            git diff
+            echo "${MESSAGE}"
+            exit 1
           fi

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

@@ -0,0 +1,162 @@
+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@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.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,4 +1,4 @@
-name: Run clang-tidy on files
+name: Clang-tidy check
 
 on:
   workflow_call:
@@ -16,180 +16,32 @@ defaults:
   run:
     shell: bash
 
-env:
-  BUILD_DIR: build
-  BUILD_TYPE: Debug # Debug so that ASSERTS and such participate in clang-tidy check
-
-  OUTPUT_FILE: clang-tidy-output.txt
-  DIFF_FILE: clang-tidy-git-diff.txt
-  ISSUE_FILE: clang-tidy-issue.md
-
 jobs:
   determine-files:
+    name: Determine files to check
     if: ${{ inputs.check_only_changed }}
-    permissions:
-      contents: read
-    uses: XRPLF/actions/.github/workflows/determine-tidy-files.yml@224f3c48d3014d082a1129237b8291ff0b0a331f
-
-  run-clang-tidy:
-    name: Run clang tidy
-    needs: [determine-files]
-    if: ${{ always() && !cancelled() && (!inputs.check_only_changed || needs.determine-files.outputs.cpp_changed_files != '' || needs.determine-files.outputs.clang_tidy_config_changed == 'true') }}
-    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-8abe82e"
-    permissions:
-      contents: read
-      issues: write
+    runs-on: ubuntu-latest
+    outputs:
+      any_changed: ${{ steps.changed_files.outputs.any_changed }}
+      all_changed_files: ${{ steps.changed_files.outputs.all_changed_files }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
+      - name: Get changed C++ files
+        id: changed_files
+        uses: tj-actions/changed-files@7dee1b0c1557f278e5c7dc244927139d78c0e22a # v47.0.4
         with:
-          enable_ccache: false
+          files: |
+            **/*.cpp
+            **/*.h
+            **/*.ipp
+          separator: " "
 
-      - name: Print build environment
-        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
-
-      - name: Get number of processors
-        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
-        id: nproc
-
-      - name: Set compiler environment
-        uses: ./.github/actions/set-compiler-env
-        with:
-          compiler: clang
-
-      - 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:
-          TARGETS: ${{ (needs.determine-files.outputs.clang_tidy_config_changed != 'true' && inputs.check_only_changed) && needs.determine-files.outputs.cpp_changed_files || 'src tests' }}
-        run: |
-          set -o pipefail
-          run-clang-tidy -j ${{ steps.nproc.outputs.nproc }} -p "${BUILD_DIR}" -quiet -fix -allow-no-checks ${TARGETS} 2>&1 | tee "${OUTPUT_FILE}"
-
-      - name: Print errors
-        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        run: |
-          sed '/error\||/!d' "${OUTPUT_FILE}"
-
-      - name: Upload clang-tidy output
-        if: ${{ github.event.repository.visibility == 'public' && steps.run_clang_tidy.outcome != 'success' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          path: ${{ env.OUTPUT_FILE }}
-          archive: false
-          retention-days: 30
-
-      - name: Check for changes
-        id: files_changed
-        continue-on-error: true
-        run: |
-          git diff --exit-code
-
-      - name: Fix style
-        if: ${{ steps.files_changed.outcome != 'success' }}
-        run: |
-          pre-commit run --all-files || true
-
-      - name: Generate git diff
-        if: ${{ steps.files_changed.outcome != 'success' }}
-        run: |
-          git diff | tee "${DIFF_FILE}"
-
-      - name: Upload clang-tidy diff output
-        if: ${{ github.event.repository.visibility == 'public' && steps.files_changed.outcome != 'success' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          path: ${{ env.DIFF_FILE }}
-          archive: false
-          retention-days: 30
-
-      - name: Write issue header
-        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        run: |
-          cat >"${ISSUE_FILE}" <<EOF
-          ## Clang-tidy Check Failed
-
-          ### Clang-tidy Output:
-          \`\`\`
-          EOF
-
-      - name: Append clang-tidy output to issue body (filter for errors and warnings)
-        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        run: |
-          if [ -f "${OUTPUT_FILE}" ]; then
-              # Extract lines containing 'error:', 'warning:', or 'note:'
-              grep -E '(error:|warning:|note:)' "${OUTPUT_FILE}" >filtered-output.txt || true
-
-              # If filtered output is empty, use original (might be a different error format)
-              if [ ! -s filtered-output.txt ]; then
-                  cp "${OUTPUT_FILE}" filtered-output.txt
-              fi
-
-              # Truncate if too large
-              head -c 60000 filtered-output.txt >>"${ISSUE_FILE}"
-              if [ "$(wc -c <filtered-output.txt)" -gt 60000 ]; then
-                  echo "" >>"${ISSUE_FILE}"
-                  echo "... (output truncated, see artifacts for full output)" >>"${ISSUE_FILE}"
-              fi
-
-              rm filtered-output.txt
-          else
-              echo "No output file found" >>"${ISSUE_FILE}"
-          fi
-
-      - name: Append issue footer
-        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        run: |
-          cat >>"${ISSUE_FILE}" <<EOF
-          \`\`\`
-
-          ---
-          *This issue was automatically created by the clang-tidy workflow.*
-          EOF
-
-      - name: Create issue
-        if: ${{ steps.run_clang_tidy.outcome != 'success' && inputs.create_issue_on_failure }}
-        uses: XRPLF/actions/create-issue@2b8bc36af85b88bca0dd7bfac2e2dc05f94ad712
-        with:
-          title: "Clang-tidy check failed"
-          body_file: ${{ env.ISSUE_FILE }}
-          labels: "Bug,Clang-tidy"
-          assignees: "godexsoft,mathbunnyru"
-
-      - name: Fail if clang-tidy found issues
-        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        run: |
-          echo "Clang-tidy check failed!"
-          exit 1
+  run-clang-tidy:
+    needs: [determine-files]
+    if: ${{ always() && !cancelled() && (!inputs.check_only_changed || needs.determine-files.outputs.any_changed == 'true') }}
+    uses: ./.github/workflows/reusable-clang-tidy-files.yml
+    with:
+      files: ${{ inputs.check_only_changed && needs.determine-files.outputs.all_changed_files || '' }}
+      create_issue_on_failure: ${{ inputs.create_issue_on_failure }}

.github/workflows/reusable-package.yml

@@ -1,122 +0,0 @@
-# Build Linux packages (DEB and RPM) from pre-built binary artifacts.
-# Discovers which configurations to package from linux.json (configs in
-# "package_configs") and fans out one job per distro. Only linux/amd64 is
-# supported; the runner is hardcoded in the job below.
-name: Package
-
-on:
-  workflow_call:
-    inputs:
-      pkg_release:
-        description: "Package release number. Increment when repackaging the same executable."
-        required: false
-        type: string
-        default: "1"
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  BUILD_DIR: build
-
-jobs:
-  generate-matrix:
-    runs-on: ubuntu-latest
-    outputs:
-      matrix: ${{ steps.generate.outputs.matrix }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-
-      - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: "3.13"
-
-      - name: Generate packaging matrix
-        id: generate
-        working-directory: .github/scripts/strategy-matrix
-        run: ./generate.py --packaging >>"${GITHUB_OUTPUT}"
-
-  generate-version:
-    runs-on: ubuntu-latest
-    outputs:
-      version: ${{ steps.version.outputs.version }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          sparse-checkout: |
-            .github/actions/generate-version
-            src/libxrpl/protocol/BuildInfo.cpp
-      - name: Generate version
-        id: version
-        uses: ./.github/actions/generate-version
-
-  package:
-    needs: [generate-matrix, generate-version]
-    if: ${{ github.event.repository.visibility == 'public' }}
-    strategy:
-      fail-fast: false
-      matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
-    name: "${{ matrix.artifact_name }}"
-    permissions:
-      contents: read
-    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: ${{ matrix.image }}
-    timeout-minutes: 30
-
-    steps:
-      # Packaging runs in a vanilla distro image, so the tooling has to come
-      # from the distro's archive: debhelper for deb, rpm-build (and the
-      # systemd / find-debuginfo macros it depends on) for rpm. Run this
-      # before actions/checkout so the latter can use git (real history) for
-      # build_pkg.sh's SOURCE_DATE_EPOCH; otherwise it falls back to a tarball
-      # download and the timestamp comes from wall-clock time.
-      - name: Install packaging tooling (deb)
-        if: ${{ matrix.distro == 'debian' }}
-        run: |
-          export DEBIAN_FRONTEND=noninteractive
-          apt-get update
-          apt-get install -y --no-install-recommends \
-              ca-certificates \
-              debhelper \
-              git
-
-      - name: Install packaging tooling (rpm)
-        if: ${{ matrix.distro == 'rhel' }}
-        run: |
-          dnf install -y --setopt=install_weak_deps=False \
-              git \
-              rpm-build \
-              redhat-rpm-config \
-              systemd-rpm-macros
-
-      - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-
-      - name: Download pre-built binary
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: ${{ matrix.artifact_name }}
-          path: ${{ env.BUILD_DIR }}
-
-      - name: Make binary executable
-        run: chmod +x "${BUILD_DIR}/xrpld"
-
-      - name: Build package
-        env:
-          PKG_VERSION: ${{ needs.generate-version.outputs.version }}
-          PKG_RELEASE: ${{ inputs.pkg_release }}
-        run: ./package/build_pkg.sh
-
-      - name: Upload package artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: ${{ matrix.artifact_name }}-pkg-${{ needs.generate-version.outputs.version }}
-          path: |
-            ${{ env.BUILD_DIR }}/debbuild/*.deb
-            ${{ env.BUILD_DIR }}/debbuild/*.ddeb
-            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/*.rpm
-          if-no-files-found: error

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

@@ -4,9 +4,15 @@ on:
   workflow_call:
     inputs:
       os:
-        description: 'The operating system to use for the build ("linux", "macos", "windows", or empty for all).'
+        description: 'The operating system to use for the build ("linux", "macos", "windows").'
         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
+        type: string
+        default: "minimal"
     outputs:
       matrix:
         description: "The generated strategy matrix."
@@ -23,16 +29,17 @@ jobs:
       matrix: ${{ steps.generate.outputs.matrix }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
-          python-version: "3.13"
+          python-version: 3.13
 
       - name: Generate strategy matrix
         working-directory: .github/scripts/strategy-matrix
         id: generate
         env:
-          GENERATE_CONFIG: ${{ inputs.os != '' && format('--config={0}', inputs.os) || '' }}
-        run: ./generate.py ${GENERATE_CONFIG} >>"${GITHUB_OUTPUT}"
+          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}"

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

@@ -40,10 +40,10 @@ defaults:
 jobs:
   upload:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-8abe82e
+    container: ghcr.io/xrplf/ci/ubuntu-noble:gcc-13-sha-5dd7158
     steps:
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Generate build version number
         id: version
@@ -69,30 +69,24 @@ jobs:
           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' }}
+        if: ${{ github.ref == 'refs/heads/develop' }}
         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' }}
+        if: ${{ startsWith(github.ref, 'refs/heads/release') }}
         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 push event, it will always be when tagging a final
-      # release, see on-tag.yml.
       - name: Upload Conan recipe (release)
-        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        if: ${{ github.event_name == 'tag' }}
         env:
           REMOTE_NAME: ${{ inputs.remote_name }}
         run: |

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

@@ -48,6 +48,8 @@ jobs:
   # Generate the strategy matrix to be used by the following job.
   generate-matrix:
     uses: ./.github/workflows/reusable-strategy-matrix.yml
+    with:
+      strategy_matrix: ${{ github.event_name == 'pull_request' && 'minimal' || 'all' }}
 
   # Build and upload the dependencies for each configuration.
   run-upload-conan-deps:
@@ -56,23 +58,24 @@ jobs:
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
+      max-parallel: 10
     runs-on: ${{ matrix.architecture.runner }}
-    container: ${{ matrix.image || null }}
+    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 }}
     steps:
       - name: Cleanup workspace (macOS and Windows)
         if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
-        uses: XRPLF/actions/cleanup-workspace@c7d9ce5ebb03c752a354889ecd870cadfc2b1cd4
+        uses: XRPLF/actions/cleanup-workspace@cf0433aa74563aead044a1e395610c96d65a37cf
 
       - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
+        uses: XRPLF/actions/prepare-runner@2cbf481018d930656e9276fcc20dc0e3a0be5b6d
         with:
           enable_ccache: false
 
       - name: Print build environment
-        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
+        uses: ./.github/actions/print-env
 
       - name: Get number of processors
         uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
@@ -80,12 +83,6 @@ jobs:
         with:
           subtract: ${{ env.NPROC_SUBTRACT }}
 
-      - name: Set compiler environment (Linux)
-        if: ${{ runner.os == 'Linux' }}
-        uses: ./.github/actions/set-compiler-env
-        with:
-          compiler: ${{ matrix.compiler }}
-
       - name: Setup Conan
         env:
           SANITIZERS: ${{ matrix.sanitizers }}
@@ -106,11 +103,11 @@ jobs:
           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

@@ -13,7 +13,6 @@
 Debug/
 Release/
 /.build/
-/.venv/
 /build/
 /db/
 /out.txt
@@ -72,15 +71,10 @@ DerivedData
 /.zed/
 
 # AI tools.
-/.agent
-/.agents
 /.augment
 /.claude
 /CLAUDE.md
 
-# Python
-__pycache__
-
 # Direnv's directory
 /.direnv
 

.pre-commit-config.yaml

@@ -13,81 +13,40 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # frozen: v6.0.0
     hooks:
-      - id: check-added-large-files
-        args: [--maxkb=400, --enforce-all]
       - id: trailing-whitespace
       - id: end-of-file-fixer
+      - id: mixed-line-ending
       - id: check-merge-conflict
         args: [--assume-in-merge]
 
-  - repo: local
-    hooks:
-      - id: clang-tidy
-        name: "clang-tidy (enable with: TIDY=1)"
-        entry: ./bin/pre-commit/clang_tidy_check.py
-        language: python
-        types_or: [c++, c]
-        exclude: ^include/xrpl/protocol_autogen
-        pass_filenames: false # script determines the staged files itself
-      - id: fix-include-style
-        name: fix include style
-        entry: ./bin/pre-commit/fix_include_style.py
-        language: python
-        types_or: [c++, c]
-        exclude: ^include/xrpl/protocol_autogen/(transactions|ledger_entries)/
-
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: dd18dad857d6133e90bbe478f4f2f22ec0030269 # frozen: v22.1.5
+    rev: 75ca4ad908dc4a99f57921f29b7e6c1521e10b26 # frozen: v21.1.8
     hooks:
       - id: clang-format
         args: [--style=file]
         "types_or": [c++, c, proto]
-        exclude: ^include/xrpl/protocol_autogen/(transactions|ledger_entries)/
 
-  - repo: https://github.com/BlankSpruce/gersemi-pre-commit
-    rev: faadd6a9d852369ca94f4d15b2404c967ba8cb01 # frozen: 0.27.6
+  - repo: https://github.com/cheshirekow/cmake-format-precommit
+    rev: e2c2116d86a80e72e7146a06e68b7c228afc6319 # frozen: v0.6.13
     hooks:
-      - id: gersemi
+      - id: cmake-format
+        additional_dependencies: [PyYAML]
 
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: 515f543f5718ebfd6ce22e16708bb32c68ff96e1 # frozen: v3.8.3
+    rev: 5ba47274f9b181bce26a5150a725577f3c336011 # frozen: v3.6.2
     hooks:
       - id: prettier
-        args: [--end-of-line=auto]
 
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 4160603246a6b365d4a2af661c6d71b0a0f50478 # frozen: 26.5.1
+    rev: 831207fd435b47aeffdf6af853097e64322b4d44 # frozen: v25.12.0
     hooks:
       - id: black
 
-  - repo: https://github.com/scop/pre-commit-shfmt
-    rev: 05c1426671b9237fb5e1444dd63aa5731bec0dfb # frozen: v3.13.1-1
-    hooks:
-      - id: shfmt
-        args: [--write, --indent=4, --case-indent=true]
-
-  - repo: local
-    hooks:
-      - id: format-inline-bash-workflows
-        name: "format `run:` blocks in workflows/actions"
-        entry: ./.github/scripts/format-inline-bash.py
-        language: python
-        files: ^\.github/(workflows|actions)/.*\.ya?ml$
-      - id: format-inline-bash-markdown
-        name: "format ```bash blocks in markdown"
-        entry: ./.github/scripts/format-inline-bash.py
-        language: python
-        files: \.md$
-
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: 4643f154907327ee0a2c7038f0296e0dd77d9776 # frozen: v10.0.0
+    rev: 1cfa010f078c354f3ffb8413616280cc28f5ba21 # frozen: v9.4.0
     hooks:
       - id: cspell # Spell check changed files
-        exclude: |
-          (?x)^(
-              .config/cspell.config.yaml|
-              include/xrpl/protocol_autogen/(transactions|ledger_entries)/.*
-          )$
+        exclude: .config/cspell.config.yaml
       - id: cspell # Spell check the commit message
         name: check commit message spelling
         args:
@@ -102,15 +61,7 @@ repos:
     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
-          ' --
+        entry: nix --extra-experimental-features 'nix-command flakes' fmt
         language: system
         types:
           - nix
@@ -119,6 +70,5 @@ repos:
 exclude: |
   (?x)^(
       external/.*|
-      .github/scripts/levelization/results/.*\.txt|
-      src/tests/libxrpl/protocol_autogen/(transactions|ledger_entries)/.*
+      .github/scripts/levelization/results/.*\.txt
   )$

API-CHANGELOG.md

@@ -4,52 +4,23 @@ This changelog is intended to list all updates to the [public API methods](https
 
 For info about how [API versioning](https://xrpl.org/request-formatting.html#api-versioning) works, including examples, please view the [XLS-22d spec](https://github.com/XRPLF/XRPL-Standards/discussions/54). For details about the implementation of API versioning, view the [implementation PR](https://github.com/XRPLF/rippled/pull/3155). API versioning ensures existing integrations and users continue to receive existing behavior, while those that request a higher API version will experience new behavior.
 
-The API version controls the API behavior you see. This includes what properties you see in responses, what parameters you're permitted to send in requests, and so on. You specify the API version in each of your requests. When a breaking change is introduced to the `xrpld` API, a new version is released. To avoid breaking your code, you should set (or increase) your version when you're ready to upgrade.
+The 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 (`xrpld`) release.
+For a log of breaking changes, see the **API Version [number]** headings. In general, breaking changes are associated with a particular API Version number. For non-breaking changes, scroll to the **XRP Ledger version [x.y.z]** headings. Non-breaking changes are associated with a particular XRP Ledger (`rippled`) release.
 
 ## API Version 3 (Beta)
 
-API version 3 is currently a beta API. It requires enabling `[beta_rpc_api]` in the xrpld configuration to use. See [API-VERSION-3.md](API-VERSION-3.md) for the full list of changes in API version 3.
+API version 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 `xrpld` version 2.0.0 and later. See [API-VERSION-2.md](API-VERSION-2.md) for the full list of changes in API version 2.
+API version 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 1
 
-This version is supported by all `xrpld` versions. For WebSocket and HTTP JSON-RPC requests, it is currently the default API version used when no `api_version` is specified.
-
-## Unreleased
-
-This section contains changes targeting a future version.
-
-### Additions
-
-- `ledger_entry`, `account_objects`: The `Delegate` ledger entry now includes an optional `DestinationNode` field, which stores the index into the authorized account's owner directory. This field is present on entries created after bidirectional directory tracking was introduced and may appear in RPC responses for those entries. ([#6681](https://github.com/XRPLF/rippled/pull/6681))
-
-- `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.
-
-### Bugfixes
-
-- Peer Crawler: The `port` field in `overlay.active[]` now consistently returns an integer instead of a string for outbound peers. [#6318](https://github.com/XRPLF/rippled/pull/6318)
-- `ping`: The `ip` field is no longer returned as an empty string for proxied connections without a forwarded-for header. It is now omitted, consistent with the behavior for identified connections. [#6730](https://github.com/XRPLF/rippled/pull/6730)
-- gRPC `GetLedgerDiff`: Fixed error message that incorrectly said "base ledger not validated" when the desired ledger was not validated. [#6730](https://github.com/XRPLF/rippled/pull/6730)
-- `account_channels`: The `destination_account` field now returns an error if the value is not a string. [#6529](https://github.com/XRPLF/rippled/pull/6529)
-- `subscribe`: The `taker` field in the `books` array now returns an error if the value is not a string. [#6529](https://github.com/XRPLF/rippled/pull/6529)
-- `account_info`: The `urlgravatar` field now uses HTTPS instead of HTTP. [#6529](https://github.com/XRPLF/rippled/pull/6529)
-- `ledger`: The `full`, `accounts`, `transactions`, `expand`, `binary`, `owner_funds`, and `queue` fields now return an error if the value is not a boolean. [#6529](https://github.com/XRPLF/rippled/pull/6529)
-- `ledger_data`: The `binary` field now returns an error if the value is not a boolean. [#6529](https://github.com/XRPLF/rippled/pull/6529)
-- `submit`: The `fail_hard` field now returns an error if the value is not a boolean. [#6529](https://github.com/XRPLF/rippled/pull/6529)
-- `subscribe`: The `taker` field in the `books` array now returns `actMalformed` instead of `badIssuer` if the value is not a valid account. [#6529](https://github.com/XRPLF/rippled/pull/6529)
-- Fixed a bug in `Forwarded` HTTP header parsing where the extracted IP address could be incorrect when no comma or semicolon delimiter follows the address. This could cause the server to misidentify a client's IP address when operating behind a reverse proxy. [#6529](https://github.com/XRPLF/rippled/pull/6529)
+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.
 
 ## XRP Ledger server version 3.1.0
 

API-VERSION-2.md

@@ -1,6 +1,6 @@
 # API Version 2
 
-API version 2 is available in `xrpld` version 2.0.0 and later. To use this API, clients specify `"api_version" : 2` in each request.
+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.
 

API-VERSION-3.md

@@ -1,6 +1,6 @@
 # API Version 3
 
-API version 3 is currently a **beta API**. It requires enabling `[beta_rpc_api]` in the xrpld configuration to use. To use this API, clients specify `"api_version" : 3` in each request.
+API version 3 is currently a **beta API**. It requires enabling `[beta_rpc_api]` in the 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.
 

BUILD.md

@@ -125,9 +125,9 @@ default profile.
 
 ### Patched recipes
 
-Occasionally, we need patched recipes or recipes not present in Conan Center.
-We maintain a fork of the Conan Center Index
-[here](https://github.com/XRPLF/conan-center-index/) containing the modified and newly added recipes.
+The recipes in Conan Center occasionally need to be patched for compatibility
+with the latest version of `xrpld`. We maintain a fork of the Conan Center
+[here](https://github.com/XRPLF/conan-center-index/) containing the patches.
 
 To ensure our patched recipes are used, you must add our Conan remote at a
 higher index than the default Conan Center remote, so it is consulted first. You
@@ -137,11 +137,19 @@ can do this by running:
 conan remote add --index 0 xrplf https://conan.ripplex.io
 ```
 
-Alternatively, you can pull our recipes from the repository and export them locally:
+Alternatively, you can pull the patched recipes into the repository and use them
+locally:
 
 ```bash
+# Extract the version number from the lockfile.
+function extract_version {
+  version=$(cat conan.lock | sed -nE "s@.+${1}/(.+)#.+@\1@p" | head -n1)
+  echo ${version}
+}
+
 # Define which recipes to export.
-recipes=('abseil' 'ed25519' 'mpt-crypto' 'openssl' 'secp256k1' 'snappy' 'soci' 'wasm-xrplf' 'wasmi')
+recipes=('ed25519' 'grpc' 'nudb' 'openssl' 'secp256k1' 'snappy' 'soci')
+folders=('all'     'all'  'all'  '3.x.x'   'all'       'all'    'all')
 
 # Selectively check out the recipes from our CCI fork.
 cd external
@@ -150,19 +158,29 @@ cd conan-center-index
 git init
 git remote add origin git@github.com:XRPLF/conan-center-index.git
 git sparse-checkout init
-for recipe in "${recipes[@]}"; do
-    echo "Checking out recipe '${recipe}'..."
-    git sparse-checkout add recipes/${recipe}
+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}
 done
 git fetch origin master
 git checkout master
+cd ../..
 
-./export_all.sh
-cd ../../
+# Export the recipes into the local cache.
+for ((index = 1; index <= ${#recipes[@]}; index++)); do
+  recipe=${recipes[index]}
+  folder=${folders[index]}
+  version=$(extract_version ${recipe})
+  echo "Exporting '${recipe}/${version}' from '${recipe}/${folder}'..."
+  conan export --version $(extract_version ${recipe}) \
+    external/conan-center-index/recipes/${recipe}/${folder}
+done
 ```
 
 In the case we switch to a newer version of a dependency that still requires a
-patch or add a new dependency, it will be necessary for you to pull in the changes and re-export the
+patch, it will be necessary for you to pull in the changes and re-export the
 updated dependencies with the newer version. However, if we switch to a newer
 version that no longer requires a patch, no action is required on your part, as
 the new recipe will be automatically pulled from the official Conan Center.
@@ -171,8 +189,6 @@ the new recipe will be automatically pulled from the official Conan Center.
 > You might need to add `--lockfile=""` to your `conan install` command
 > to avoid automatic use of the existing `conan.lock` file when you run
 > `conan export` manually on your machine
->
-> This is not recommended though, as you might end up using different revisions of recipes.
 
 ### Conan profile tweaks
 
@@ -180,7 +196,7 @@ the new recipe will be automatically pulled from the official Conan Center.
 
 If you see an error similar to the following after running `conan profile show`:
 
-```text
+```bash
 ERROR: Invalid setting '17' is not a valid 'settings.compiler.version' value.
 Possible values are ['5.0', '5.1', '6.0', '6.1', '7.0', '7.3', '8.0', '8.1',
 '9.0', '9.1', '10.0', '11.0', '12.0', '13', '13.0', '13.1', '14', '14.0', '15',
@@ -188,14 +204,39 @@ Possible values are ['5.0', '5.1', '6.0', '6.1', '7.0', '7.3', '8.0', '8.1',
 Read "http://docs.conan.io/2/knowledge/faq.html#error-invalid-setting"
 ```
 
-you need to add your compiler to the list of compiler versions in
-`$(conan config home)/settings_user.yml`, by adding the required version number(s)
+you need to amend the list of compiler versions in
+`$(conan config home)/settings.yml`, by appending the required version number(s)
 to the `version` array specific for your compiler. For example:
 
 ```yaml
-compiler:
-  apple-clang:
-    version: ["17.0"]
+apple-clang:
+  version:
+    [
+      "5.0",
+      "5.1",
+      "6.0",
+      "6.1",
+      "7.0",
+      "7.3",
+      "8.0",
+      "8.1",
+      "9.0",
+      "9.1",
+      "10.0",
+      "11.0",
+      "12.0",
+      "13",
+      "13.0",
+      "13.1",
+      "14",
+      "14.0",
+      "15",
+      "15.0",
+      "16",
+      "16.0",
+      "17",
+      "17.0",
+    ]
 ```
 
 #### Multiple compilers
@@ -427,19 +468,16 @@ install ccache --version 4.11.3 --allow-downgrade`.
    Single-config generators:
 
    ```
-   cmake --build . --parallel N
+   cmake --build .
    ```
 
    Multi-config generators:
 
    ```
-   cmake --build . --config Release --parallel N
-   cmake --build . --config Debug --parallel N
+   cmake --build . --config Release
+   cmake --build . --config Debug
    ```
 
-   Replace the `--parallel` parameter N with the desired number of parallel jobs. A common starting point is half of the number of available CPU
-   cores.
-
 5. Test xrpld.
 
    Single-config generators:
@@ -462,21 +500,6 @@ install ccache --version 4.11.3 --allow-downgrade`.
    The location of `xrpld` binary in your build directory depends on your
    CMake generator. Pass `--help` to see the rest of the command line options.
 
-## Code generation
-
-The protocol wrapper classes in `include/xrpl/protocol_autogen/` are generated
-from macro definition files in `include/xrpl/protocol/detail/`. If you modify
-the macro files (e.g. `transactions.macro`, `ledger_entries.macro`) or the
-generation scripts/templates in `cmake/scripts/codegen/`, you need to regenerate the
-files:
-
-```
-cmake --build . --target setup_code_gen  # create venv and install dependencies (once)
-cmake --build . --target code_gen        # regenerate code
-```
-
-The regenerated files should be committed alongside your changes.
-
 ## Coverage report
 
 The coverage report is intended for developers using compilers GCC
@@ -533,15 +556,15 @@ stored inside the build directory, as either of:
 ## Sanitizers
 
 To build dependencies and xrpld with sanitizer instrumentation, set the
-`SANITIZERS` environment variable when running `conan install` and use the `sanitizers` profile:
+`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
-```
 
-You can then build and test as usual, with the generated `xrpld` binary containing the sanitizer instrumentation. When you run it, it will report any sanitizer errors it detects in the console output.
+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.
 
@@ -621,8 +644,8 @@ If you want to experiment with a new package, follow these steps:
      `default_options` property (with syntax `'$package:$option': $value`).
 3. Modify [`CMakeLists.txt`](./CMakeLists.txt):
    - Add a call to `find_package($package REQUIRED)`.
-   - Link a library from the package to the target `xrpl_libs`
-     (search for the existing call to `target_link_libraries(xrpl_libs INTERFACE ...)`).
+   - Link a library from the package to the target `ripple_libs`
+     (search for the existing call to `target_link_libraries(ripple_libs INTERFACE ...)`).
 4. Start coding! Don't forget to include whatever headers you need from the package.
 
 [1]: https://github.com/conan-io/conan-center-index/issues/13168

CMakeLists.txt

@@ -1,16 +1,16 @@
 cmake_minimum_required(VERSION 3.16)
 
-if(POLICY CMP0074)
+if (POLICY CMP0074)
     cmake_policy(SET CMP0074 NEW)
-endif()
-if(POLICY CMP0077)
+endif ()
+if (POLICY CMP0077)
     cmake_policy(SET CMP0077 NEW)
-endif()
+endif ()
 
 # Fix "unrecognized escape" issues when passing CMAKE_MODULE_PATH on Windows.
-if(DEFINED CMAKE_MODULE_PATH)
+if (DEFINED CMAKE_MODULE_PATH)
     file(TO_CMAKE_PATH "${CMAKE_MODULE_PATH}" CMAKE_MODULE_PATH)
-endif()
+endif ()
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
 project(xrpl)
@@ -21,64 +21,77 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 include(CompilationEnv)
 
-if(is_gcc)
+if (is_gcc)
     # 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 (is_clang)
     # Clang-specific fixes
     add_compile_options(-Wno-unknown-warning-option) # Ignore unknown warning options
-elseif(is_msvc)
+elseif (is_msvc)
     # MSVC-specific fixes
     add_compile_options(/wd4068) # Ignore unknown pragmas
-endif()
+endif ()
 
 # Enable ccache to speed up builds.
 include(Ccache)
 
-if(thread_safety_analysis)
-    add_compile_options(
-        -Wthread-safety
-        -D_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS
-        -DXRPL_ENABLE_THREAD_SAFETY_ANNOTATIONS
-    )
+# 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++")
-endif()
+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"
+if (target)
+    message(FATAL_ERROR "The target option has been removed - use native cmake options to control build"
     )
-endif()
+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?"
+if (packages_only)
+    if (NOT TARGET rpm)
+        message(FATAL_ERROR "packages_only requested, but targets were not created - is docker installed?"
         )
-    endif()
+    endif ()
     return()
-endif()
+endif ()
 include(XrplCompiler)
 include(XrplSanitizers)
 include(XrplInterface)
 
 option(only_docs "Include only the docs target?" FALSE)
 include(XrplDocs)
-if(only_docs)
+if (only_docs)
     return()
-endif()
+endif ()
 
 include(deps/Boost)
 
@@ -97,47 +110,54 @@ find_package(xxHash REQUIRED)
 
 target_link_libraries(
     xrpl_libs
-    INTERFACE
-        ed25519::ed25519
-        lz4::lz4
-        OpenSSL::Crypto
-        OpenSSL::SSL
-        secp256k1::secp256k1
-        soci::soci
-        SQLite::SQLite3
-)
+    INTERFACE ed25519::ed25519
+              lz4::lz4
+              OpenSSL::Crypto
+              OpenSSL::SSL
+              secp256k1::secp256k1
+              soci::soci
+              SQLite::SQLite3)
 
 option(rocksdb "Enable RocksDB" ON)
-if(rocksdb)
+if (rocksdb)
     find_package(RocksDB REQUIRED)
-    set_target_properties(
-        RocksDB::rocksdb
-        PROPERTIES INTERFACE_COMPILE_DEFINITIONS XRPL_ROCKSDB_AVAILABLE=1
-    )
+    set_target_properties(RocksDB::rocksdb PROPERTIES INTERFACE_COMPILE_DEFINITIONS
+                                                      XRPL_ROCKSDB_AVAILABLE=1)
     target_link_libraries(xrpl_libs INTERFACE RocksDB::rocksdb)
-endif()
+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 ()
 
 # Work around changes to Conan recipe for now.
-if(TARGET nudb::core)
+if (TARGET nudb::core)
     set(nudb nudb::core)
-elseif(TARGET NuDB::nudb)
+elseif (TARGET NuDB::nudb)
     set(nudb NuDB::nudb)
-else()
+else ()
     message(FATAL_ERROR "unknown nudb target")
-endif()
+endif ()
 target_link_libraries(xrpl_libs INTERFACE ${nudb})
 
-if(coverage)
+if (coverage)
     include(XrplCov)
-endif()
+endif ()
 
+set(PROJECT_EXPORT_SET XrplExports)
 include(XrplCore)
-include(XrplProtocolAutogen)
 include(XrplInstall)
-include(XrplPackaging)
 include(XrplValidatorKeys)
 
-if(tests)
+if (tests)
     include(CTest)
     add_subdirectory(src/tests/libxrpl)
-endif()
+endif ()

CONTRIBUTING.md

@@ -127,6 +127,26 @@ tl;dr
 > 6. Wrap the body at 72 characters.
 > 7. Use the body to explain what and why vs. how.
 
+In addition to those guidelines, please add one of the following
+prefixes to the subject line if appropriate.
+
+- `fix:` - The primary purpose is to fix an existing bug.
+- `perf:` - The primary purpose is performance improvements.
+- `refactor:` - The changes refactor code without affecting
+  functionality.
+- `test:` - The changes _only_ affect unit tests.
+- `docs:` - The changes _only_ affect documentation. This can
+  include code comments in addition to `.md` files like this one.
+- `build:` - The changes _only_ affect the build process,
+  including CMake and/or Conan settings.
+- `chore:` - Other tasks that don't affect the binary, but don't fit
+  any of the other cases. e.g. formatting, git settings, updating
+  Github Actions jobs.
+
+Whenever possible, when updating commits after the PR is open, please
+add the PR number to the end of the subject line. e.g. `test: Add
+unit tests for Feature X (#1234)`.
+
 ## Pull requests
 
 In general, pull requests use `develop` as the base branch.
@@ -160,23 +180,6 @@ credibility of the existing approvals is insufficient.
 Pull requests must be merged by [squash-and-merge][squash]
 to preserve a linear history for the `develop` branch.
 
-### Type of Change
-
-In addition to those guidelines, please start your PR title with one of the following:
-
-- `build:` - The changes _only_ affect the build process, including CMake and/or Conan settings.
-- `feat`: New feature (change which adds functionality).
-- `fix:` - The primary purpose is to fix an existing bug.
-- `docs:` - The changes _only_ affect documentation.
-- `test:` - The changes _only_ affect unit tests.
-- `ci`: Continuous Integration (changes to our CI configuration files and scripts).
-- `style`: Code style (formatting).
-- `refactor:` - The changes refactor code without affecting functionality.
-- `perf:` - The primary purpose is performance improvements.
-- `chore:` - Other tasks that don't affect the binary, but don't fit any of the other cases. e.g. `git` settings, `clang-tidy`, removing dead code, dropping support for older tooling.
-
-First letter after the type prefix should be capitalized, and the type prefix should be followed by a colon and a space. e.g. `feat: Add support for Borrowing Protocol`.
-
 ### "Ready to merge"
 
 A pull request should only have the "Ready to merge" label added when it
@@ -248,58 +251,6 @@ pip3 install pre-commit
 pre-commit install
 ```
 
-## Clang-tidy
-
-All code must pass `clang-tidy` checks according to the settings in [`.clang-tidy`](./.clang-tidy).
-
-There is a Continuous Integration job that runs clang-tidy on pull requests. The CI will check:
-
-- All changed C++ files (`.cpp`, `.h`, `.ipp`) when only code files are modified
-- **All files in the repository** when the `.clang-tidy` configuration file is changed
-
-This ensures that configuration changes don't introduce new warnings across the codebase.
-
-### Installing clang-tidy
-
-See the [environment setup guide](./docs/build/environment.md#clang-tidy) for platform-specific installation instructions.
-
-### Running clang-tidy locally
-
-Before running clang-tidy, you must build the project to generate required files (particularly protobuf headers). Refer to [`BUILD.md`](./BUILD.md) for build instructions.
-
-#### Via pre-commit (recommended)
-
-If you have already installed the pre-commit hooks (see above), you can run clang-tidy on your staged files using:
-
-```
-TIDY=1 pre-commit run clang-tidy
-```
-
-This runs clang-tidy locally with the same configuration/flags as CI, scoped to your staged C++ files. The `TIDY=1` environment variable is required to opt in — without it the hook is skipped.
-
-You can also have clang-tidy run automatically on every `git commit` by setting `TIDY=1` in your shell environment:
-
-```
-export TIDY=1
-```
-
-With this set, the hook will run as part of `git commit` alongside the other pre-commit checks.
-
-#### Manually
-
-Then run clang-tidy on your local changes:
-
-```
-run-clang-tidy -p build -allow-no-checks src tests
-```
-
-This will check all source files in the `src`, `include` and `tests` directories using the compile commands from your `build` directory.
-If you wish to automatically fix whatever clang-tidy finds _and_ is capable of fixing, add `-fix` to the above command:
-
-```
-run-clang-tidy -p build -quiet -fix -allow-no-checks src tests
-```
-
 ## Contracts and instrumentation
 
 We are using [Antithesis](https://antithesis.com/) for continuous fuzzing,
@@ -348,8 +299,8 @@ For this reason:
 - Contract description for `UNREACHABLE` should describe the _unexpected_
   situation which caused the line to have been reached.
 - Example good name for an
-  `UNREACHABLE` macro `"json::operator==(Value, Value) : invalid type"`; example
-  good name for an `XRPL_ASSERT` macro `"json::Value::asCString : valid type"`.
+  `UNREACHABLE` macro `"Json::operator==(Value, Value) : invalid type"`; example
+  good name for an `XRPL_ASSERT` macro `"Json::Value::asCString : valid type"`.
 - Example **bad** name
   `"RFC1751::insert(char* s, int x, int start, int length) : length is greater than or equal zero"`
   (missing namespace, unnecessary full function signature, description too verbose).
@@ -553,7 +504,7 @@ All releases, including release candidates and betas, are handled
 differently from typical PRs. Most importantly, never use
 the Github UI to merge a release.
 
-Xrpld uses a linear workflow model that can be summarized as:
+Rippled uses a linear workflow model that can be summarized as:
 
 1. In between releases, developers work against the `develop` branch.
 2. Periodically, a maintainer will build and tag a beta version from

LICENSE.md

@@ -1,7 +1,7 @@
 ISC License
 
 Copyright (c) 2011, Arthur Britto, David Schwartz, Jed McCaleb, Vinnie Falco, Bob Way, Eric Lombrozo, Nikolaos D. Bougalis, Howard Hinnant.
-Copyright (c) 2012-present, the XRP Ledger developers.
+Copyright (c) 2012-2025, the XRP Ledger developers.
 
 Permission to use, copy, modify, and distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

OpenTelemetryPlan/00-tracing-fundamentals.md

@@ -0,0 +1,244 @@
+# 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

@@ -0,0 +1,330 @@
+# 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

@@ -0,0 +1,494 @@
+# 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
+
+```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
+```
+
+### 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

@@ -0,0 +1,451 @@
+# 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

@@ -0,0 +1,982 @@
+# 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

@@ -0,0 +1,936 @@
+# 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
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [logging, jaeger]
+```
+
+### 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 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
+
+  # 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/StatsD Metrics
+
+To correlate traces with existing Beast Insight metrics:
+
+**Step 1: Export Insight metrics to Prometheus**
+
+```yaml
+# prometheus.yaml
+scrape_configs:
+  - job_name: "rippled-statsd"
+    static_configs:
+      - targets: ["statsd-exporter:9102"]
+```
+
+**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/06-implementation-phases.md

@@ -0,0 +1,543 @@
+# Implementation Phases
+
+> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
+> **Related**: [Configuration Reference](./05-configuration-reference.md) | [Observability Backends](./07-observability-backends.md)
+
+---
+
+## 6.1 Phase Overview
+
+```mermaid
+gantt
+    title OpenTelemetry Implementation Timeline
+    dateFormat  YYYY-MM-DD
+    axisFormat  Week %W
+
+    section Phase 1
+    Core Infrastructure        :p1, 2024-01-01, 2w
+    SDK Integration           :p1a, 2024-01-01, 4d
+    Telemetry Interface       :p1b, after p1a, 3d
+    Configuration & CMake     :p1c, after p1b, 3d
+    Unit Tests                :p1d, after p1c, 2d
+
+    section Phase 2
+    RPC Tracing               :p2, after p1, 2w
+    HTTP Context Extraction   :p2a, after p1, 2d
+    RPC Handler Instrumentation :p2b, after p2a, 4d
+    WebSocket Support         :p2c, after p2b, 2d
+    Integration Tests         :p2d, after p2c, 2d
+
+    section Phase 3
+    Transaction Tracing       :p3, after p2, 2w
+    Protocol Buffer Extension :p3a, after p2, 2d
+    PeerImp Instrumentation   :p3b, after p3a, 3d
+    Relay Context Propagation :p3c, after p3b, 3d
+    Multi-node Tests          :p3d, after p3c, 2d
+
+    section Phase 4
+    Consensus Tracing         :p4, after p3, 2w
+    Consensus Round Spans     :p4a, after p3, 3d
+    Proposal Handling         :p4b, after p4a, 3d
+    Validation Tests          :p4c, after p4b, 4d
+
+    section Phase 5
+    Documentation & Deploy    :p5, after p4, 1w
+```
+
+---
+
+## 6.2 Phase 1: Core Infrastructure (Weeks 1-2)
+
+**Objective**: Establish foundational telemetry infrastructure
+
+### Tasks
+
+| Task | Description                                           | Effort | Risk   |
+| ---- | ----------------------------------------------------- | ------ | ------ |
+| 1.1  | Add OpenTelemetry C++ SDK to Conan/CMake              | 2d     | Low    |
+| 1.2  | Implement `Telemetry` interface and factory           | 2d     | Low    |
+| 1.3  | Implement `SpanGuard` RAII wrapper                    | 1d     | Low    |
+| 1.4  | Implement configuration parser                        | 1d     | Low    |
+| 1.5  | Integrate into `ApplicationImp`                       | 1d     | Medium |
+| 1.6  | Add conditional compilation (`XRPL_ENABLE_TELEMETRY`) | 1d     | Low    |
+| 1.7  | Create `NullTelemetry` no-op implementation           | 0.5d   | Low    |
+| 1.8  | Unit tests for core infrastructure                    | 1.5d   | Low    |
+
+**Total Effort**: 10 days (2 developers)
+
+### Exit Criteria
+
+- [ ] OpenTelemetry SDK compiles and links
+- [ ] Telemetry can be enabled/disabled via config
+- [ ] Basic span creation works
+- [ ] No performance regression when disabled
+- [ ] Unit tests passing
+
+---
+
+## 6.3 Phase 2: RPC Tracing (Weeks 3-4)
+
+**Objective**: Complete tracing for all RPC operations
+
+### Tasks
+
+| Task | Description                                        | Effort | Risk   |
+| ---- | -------------------------------------------------- | ------ | ------ |
+| 2.1  | Implement W3C Trace Context HTTP header extraction | 1d     | Low    |
+| 2.2  | Instrument `ServerHandler::onRequest()`            | 1d     | Low    |
+| 2.3  | Instrument `RPCHandler::doCommand()`               | 2d     | Medium |
+| 2.4  | Add RPC-specific attributes                        | 1d     | Low    |
+| 2.5  | Instrument WebSocket handler                       | 1d     | Medium |
+| 2.6  | Integration tests for RPC tracing                  | 2d     | Low    |
+| 2.7  | Performance benchmarks                             | 1d     | Low    |
+| 2.8  | Documentation                                      | 1d     | Low    |
+
+**Total Effort**: 10 days
+
+### Exit Criteria
+
+- [ ] All RPC commands traced
+- [ ] Trace context propagates from HTTP headers
+- [ ] WebSocket and HTTP both instrumented
+- [ ] <1ms overhead per RPC call
+- [ ] Integration tests passing
+
+---
+
+## 6.4 Phase 3: Transaction Tracing (Weeks 5-6)
+
+**Objective**: Trace transaction lifecycle across network
+
+### Tasks
+
+| Task | Description                                   | Effort | Risk   |
+| ---- | --------------------------------------------- | ------ | ------ |
+| 3.1  | Define `TraceContext` Protocol Buffer message | 1d     | Low    |
+| 3.2  | Implement protobuf context serialization      | 1d     | Low    |
+| 3.3  | Instrument `PeerImp::handleTransaction()`     | 2d     | Medium |
+| 3.4  | Instrument `NetworkOPs::submitTransaction()`  | 1d     | Medium |
+| 3.5  | Instrument HashRouter integration             | 1d     | Medium |
+| 3.6  | Implement relay context propagation           | 2d     | High   |
+| 3.7  | Integration tests (multi-node)                | 2d     | Medium |
+| 3.8  | Performance benchmarks                        | 1d     | Low    |
+
+**Total Effort**: 11 days
+
+### Exit Criteria
+
+- [ ] Transaction traces span across nodes
+- [ ] Trace context in Protocol Buffer messages
+- [ ] HashRouter deduplication visible in traces
+- [ ] Multi-node integration tests passing
+- [ ] <5% overhead on transaction throughput
+
+---
+
+## 6.5 Phase 4: Consensus Tracing (Weeks 7-8)
+
+**Objective**: Full observability into consensus rounds
+
+### Tasks
+
+| Task | Description                                    | Effort | Risk   |
+| ---- | ---------------------------------------------- | ------ | ------ |
+| 4.1  | Instrument `RCLConsensusAdaptor::startRound()` | 1d     | Medium |
+| 4.2  | Instrument phase transitions                   | 2d     | Medium |
+| 4.3  | Instrument proposal handling                   | 2d     | High   |
+| 4.4  | Instrument validation handling                 | 1d     | Medium |
+| 4.5  | Add consensus-specific attributes              | 1d     | Low    |
+| 4.6  | Correlate with transaction traces              | 1d     | Medium |
+| 4.7  | Multi-validator integration tests              | 2d     | High   |
+| 4.8  | Performance validation                         | 1d     | Medium |
+
+**Total Effort**: 11 days
+
+### Exit Criteria
+
+- [ ] Complete consensus round traces
+- [ ] Phase transitions visible
+- [ ] Proposals and validations traced
+- [ ] No impact on consensus timing
+- [ ] Multi-validator test network validated
+
+---
+
+## 6.6 Phase 5: Documentation & Deployment (Week 9)
+
+**Objective**: Production readiness
+
+### Tasks
+
+| Task | Description                   | Effort | Risk |
+| ---- | ----------------------------- | ------ | ---- |
+| 5.1  | Operator runbook              | 1d     | Low  |
+| 5.2  | Grafana dashboards            | 1d     | Low  |
+| 5.3  | Alert definitions             | 0.5d   | Low  |
+| 5.4  | Collector deployment examples | 0.5d   | Low  |
+| 5.5  | Developer documentation       | 1d     | Low  |
+| 5.6  | Training materials            | 0.5d   | Low  |
+| 5.7  | Final integration testing     | 0.5d   | Low  |
+
+**Total Effort**: 5 days
+
+---
+
+## 6.7 Risk Assessment
+
+```mermaid
+quadrantChart
+    title Risk Assessment Matrix
+    x-axis Low Impact --> High Impact
+    y-axis Low Likelihood --> High Likelihood
+    quadrant-1 Monitor Closely
+    quadrant-2 Mitigate Immediately
+    quadrant-3 Accept Risk
+    quadrant-4 Plan Mitigation
+
+    SDK Compatibility: [0.25, 0.2]
+    Protocol Changes: [0.75, 0.65]
+    Performance Overhead: [0.65, 0.45]
+    Context Propagation: [0.5, 0.5]
+    Memory Leaks: [0.8, 0.2]
+```
+
+### Risk Details
+
+| Risk                                 | Likelihood | Impact | Mitigation                              |
+| ------------------------------------ | ---------- | ------ | --------------------------------------- |
+| Protocol changes break compatibility | Medium     | High   | Use high field numbers, optional fields |
+| Performance overhead unacceptable    | Medium     | Medium | Sampling, conditional compilation       |
+| Context propagation complexity       | Medium     | Medium | Phased rollout, extensive testing       |
+| SDK compatibility issues             | Low        | Medium | Pin SDK version, fallback to no-op      |
+| Memory leaks in long-running nodes   | Low        | High   | Memory profiling, bounded queues        |
+
+---
+
+## 6.8 Success Metrics
+
+| Metric                   | Target                         | Measurement           |
+| ------------------------ | ------------------------------ | --------------------- |
+| Trace coverage           | >95% of transactions           | Sampling verification |
+| CPU overhead             | <3%                            | Benchmark tests       |
+| Memory overhead          | <5 MB                          | Memory profiling      |
+| Latency impact (p99)     | <2%                            | Performance tests     |
+| Trace completeness       | >99% spans with required attrs | Validation script     |
+| Cross-node trace linkage | >90% of multi-hop transactions | Integration tests     |
+
+---
+
+## 6.9 Effort Summary
+
+<div align="center">
+
+```mermaid
+%%{init: {'pie': {'textPosition': 0.75}}}%%
+pie showData
+    "Phase 1: Core Infrastructure" : 10
+    "Phase 2: RPC Tracing" : 10
+    "Phase 3: Transaction Tracing" : 11
+    "Phase 4: Consensus Tracing" : 11
+    "Phase 5: Documentation" : 5
+```
+
+**Total Effort Distribution (47 developer-days)**
+
+</div>
+
+### Resource Requirements
+
+| Phase     | Developers | Duration    | Total Effort |
+| --------- | ---------- | ----------- | ------------ |
+| 1         | 2          | 2 weeks     | 10 days      |
+| 2         | 1-2        | 2 weeks     | 10 days      |
+| 3         | 2          | 2 weeks     | 11 days      |
+| 4         | 2          | 2 weeks     | 11 days      |
+| 5         | 1          | 1 week      | 5 days       |
+| **Total** | **2**      | **9 weeks** | **47 days**  |
+
+---
+
+## 6.10 Quick Wins and Crawl-Walk-Run Strategy
+
+This section outlines a prioritized approach to maximize ROI with minimal initial investment.
+
+### 6.10.1 Crawl-Walk-Run Overview
+
+<div align="center">
+
+```mermaid
+flowchart TB
+    subgraph crawl["🐢 CRAWL (Week 1-2)"]
+        direction LR
+        c1[Core SDK Setup] ~~~ c2[RPC Tracing Only] ~~~ c3[Single Node]
+    end
+
+    subgraph walk["🚶 WALK (Week 3-5)"]
+        direction LR
+        w1[Transaction Tracing] ~~~ w2[Cross-Node Context] ~~~ w3[Basic Dashboards]
+    end
+
+    subgraph run["🏃 RUN (Week 6-9)"]
+        direction LR
+        r1[Consensus Tracing] ~~~ r2[Full Correlation] ~~~ r3[Production Deploy]
+    end
+
+    crawl --> walk --> run
+
+    style crawl fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style walk fill:#bf360c,stroke:#8c2809,color:#fff
+    style run fill:#0d47a1,stroke:#082f6a,color:#fff
+    style c1 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style c2 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style c3 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style w1 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style w2 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style w3 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style r1 fill:#0d47a1,stroke:#082f6a,color:#fff
+    style r2 fill:#0d47a1,stroke:#082f6a,color:#fff
+    style r3 fill:#0d47a1,stroke:#082f6a,color:#fff
+```
+
+</div>
+
+### 6.10.2 Quick Wins (Immediate Value)
+
+| Quick Win                      | Effort   | Value  | When to Deploy |
+| ------------------------------ | -------- | ------ | -------------- |
+| **RPC Command Tracing**        | 2 days   | High   | Week 2         |
+| **RPC Latency Histograms**     | 0.5 days | High   | Week 2         |
+| **Error Rate Dashboard**       | 0.5 days | Medium | Week 2         |
+| **Transaction Submit Tracing** | 1 day    | High   | Week 3         |
+| **Consensus Round Duration**   | 1 day    | Medium | Week 6         |
+
+### 6.10.3 CRAWL Phase (Weeks 1-2)
+
+**Goal**: Get basic tracing working with minimal code changes.
+
+**What You Get**:
+
+- RPC request/response traces for all commands
+- Latency breakdown per RPC command
+- Error visibility with stack traces
+- Basic Grafana dashboard
+
+**Code Changes**: ~15 lines in `ServerHandler.cpp`, ~40 lines in new telemetry module
+
+**Why Start Here**:
+
+- RPC is the lowest-risk, highest-visibility component
+- Immediate value for debugging client issues
+- No cross-node complexity
+- Single file modification to existing code
+
+### 6.10.4 WALK Phase (Weeks 3-5)
+
+**Goal**: Add transaction lifecycle tracing across nodes.
+
+**What You Get**:
+
+- End-to-end transaction traces from submit to relay
+- Cross-node correlation (see transaction path)
+- HashRouter deduplication visibility
+- Relay latency metrics
+
+**Code Changes**: ~120 lines across 4 files, plus protobuf extension
+
+**Why Do This Second**:
+
+- Builds on RPC tracing (transactions submitted via RPC)
+- Moderate complexity (requires context propagation)
+- High value for debugging transaction issues
+
+### 6.10.5 RUN Phase (Weeks 6-9)
+
+**Goal**: Full observability including consensus.
+
+**What You Get**:
+
+- Complete consensus round visibility
+- Phase transition timing
+- Validator proposal tracking
+- Full end-to-end traces (client → RPC → TX → consensus → ledger)
+
+**Code Changes**: ~100 lines across 3 consensus files
+
+**Why Do This Last**:
+
+- Highest complexity (consensus is critical path)
+- Requires thorough testing
+- Lower relative value (consensus issues are rarer)
+
+### 6.10.6 ROI Prioritization Matrix
+
+```mermaid
+quadrantChart
+    title Implementation ROI Matrix
+    x-axis Low Effort --> High Effort
+    y-axis Low Value --> High Value
+    quadrant-1 Quick Wins - Do First
+    quadrant-2 Major Projects - Plan Carefully
+    quadrant-3 Nice to Have - Optional
+    quadrant-4 Time Sinks - Avoid
+
+    RPC Tracing: [0.15, 0.9]
+    TX Submit Trace: [0.25, 0.85]
+    TX Relay Trace: [0.5, 0.8]
+    Consensus Trace: [0.7, 0.75]
+    Peer Message Trace: [0.85, 0.3]
+    Ledger Acquire: [0.55, 0.5]
+```
+
+---
+
+## 6.11 Definition of Done
+
+Clear, measurable criteria for each phase.
+
+### 6.11.1 Phase 1: Core Infrastructure
+
+| Criterion       | Measurement                                                | Target                       |
+| --------------- | ---------------------------------------------------------- | ---------------------------- |
+| SDK Integration | `cmake --build` succeeds with `-DXRPL_ENABLE_TELEMETRY=ON` | ✅ Compiles                  |
+| Runtime Toggle  | `enabled=0` produces zero overhead                         | <0.1% CPU difference         |
+| Span Creation   | Unit test creates and exports span                         | Span appears in Jaeger       |
+| Configuration   | All config options parsed correctly                        | Config validation tests pass |
+| Documentation   | Developer guide exists                                     | PR approved                  |
+
+**Definition of Done**: All criteria met, PR merged, no regressions in CI.
+
+### 6.11.2 Phase 2: RPC Tracing
+
+| Criterion          | Measurement                        | Target                     |
+| ------------------ | ---------------------------------- | -------------------------- |
+| Coverage           | All RPC commands instrumented      | 100% of commands           |
+| Context Extraction | traceparent header propagates      | Integration test passes    |
+| Attributes         | Command, status, duration recorded | Validation script confirms |
+| Performance        | RPC latency overhead               | <1ms p99                   |
+| Dashboard          | Grafana dashboard deployed         | Screenshot in docs         |
+
+**Definition of Done**: RPC traces visible in Jaeger/Tempo for all commands, dashboard shows latency distribution.
+
+### 6.11.3 Phase 3: Transaction Tracing
+
+| Criterion        | Measurement                     | Target                             |
+| ---------------- | ------------------------------- | ---------------------------------- |
+| Local Trace      | Submit → validate → TxQ traced  | Single-node test passes            |
+| Cross-Node       | Context propagates via protobuf | Multi-node test passes             |
+| Relay Visibility | relay_count attribute correct   | Spot check 100 txs                 |
+| HashRouter       | Deduplication visible in trace  | Duplicate txs show suppressed=true |
+| Performance      | TX throughput overhead          | <5% degradation                    |
+
+**Definition of Done**: Transaction traces span 3+ nodes in test network, performance within bounds.
+
+### 6.11.4 Phase 4: Consensus Tracing
+
+| Criterion            | Measurement                   | Target                    |
+| -------------------- | ----------------------------- | ------------------------- |
+| Round Tracing        | startRound creates root span  | Unit test passes          |
+| Phase Visibility     | All phases have child spans   | Integration test confirms |
+| Proposer Attribution | Proposer ID in attributes     | Spot check 50 rounds      |
+| Timing Accuracy      | Phase durations match PerfLog | <5% variance              |
+| No Consensus Impact  | Round timing unchanged        | Performance test passes   |
+
+**Definition of Done**: Consensus rounds fully traceable, no impact on consensus timing.
+
+### 6.11.5 Phase 5: Production Deployment
+
+| Criterion    | Measurement                  | Target                     |
+| ------------ | ---------------------------- | -------------------------- |
+| Collector HA | Multiple collectors deployed | No single point of failure |
+| Sampling     | Tail sampling configured     | 10% base + errors + slow   |
+| Retention    | Data retained per policy     | 7 days hot, 30 days warm   |
+| Alerting     | Alerts configured            | Error spike, high latency  |
+| Runbook      | Operator documentation       | Approved by ops team       |
+| Training     | Team trained                 | Session completed          |
+
+**Definition of Done**: Telemetry running in production, operators trained, alerts active.
+
+### 6.11.6 Success Metrics Summary
+
+| Phase   | Primary Metric         | Secondary Metric            | Deadline      |
+| ------- | ---------------------- | --------------------------- | ------------- |
+| Phase 1 | SDK compiles and runs  | Zero overhead when disabled | End of Week 2 |
+| Phase 2 | 100% RPC coverage      | <1ms latency overhead       | End of Week 4 |
+| Phase 3 | Cross-node traces work | <5% throughput impact       | End of Week 6 |
+| Phase 4 | Consensus fully traced | No consensus timing impact  | End of Week 8 |
+| Phase 5 | Production deployment  | Operators trained           | End of Week 9 |
+
+---
+
+## 6.12 Recommended Implementation Order
+
+Based on ROI analysis, implement in this exact order:
+
+```mermaid
+flowchart TB
+    subgraph week1["Week 1"]
+        t1[1. OpenTelemetry SDK<br/>Conan/CMake integration]
+        t2[2. Telemetry interface<br/>SpanGuard, config]
+    end
+
+    subgraph week2["Week 2"]
+        t3[3. RPC ServerHandler<br/>instrumentation]
+        t4[4. Basic Jaeger setup<br/>for testing]
+    end
+
+    subgraph week3["Week 3"]
+        t5[5. Transaction submit<br/>tracing]
+        t6[6. Grafana dashboard<br/>v1]
+    end
+
+    subgraph week4["Week 4"]
+        t7[7. Protobuf context<br/>extension]
+        t8[8. PeerImp tx.relay<br/>instrumentation]
+    end
+
+    subgraph week5["Week 5"]
+        t9[9. Multi-node<br/>integration tests]
+        t10[10. Performance<br/>benchmarks]
+    end
+
+    subgraph week6_8["Weeks 6-8"]
+        t11[11. Consensus<br/>instrumentation]
+        t12[12. Full integration<br/>testing]
+    end
+
+    subgraph week9["Week 9"]
+        t13[13. Production<br/>deployment]
+        t14[14. Documentation<br/>& training]
+    end
+
+    t1 --> t2 --> t3 --> t4
+    t4 --> t5 --> t6
+    t6 --> t7 --> t8
+    t8 --> t9 --> t10
+    t10 --> t11 --> t12
+    t12 --> t13 --> t14
+
+    style week1 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style week2 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style week3 fill:#bf360c,stroke:#8c2809,color:#fff
+    style week4 fill:#bf360c,stroke:#8c2809,color:#fff
+    style week5 fill:#bf360c,stroke:#8c2809,color:#fff
+    style week6_8 fill:#0d47a1,stroke:#082f6a,color:#fff
+    style week9 fill:#4a148c,stroke:#2e0d57,color:#fff
+    style t1 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style t2 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style t3 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style t4 fill:#1b5e20,stroke:#0d3d14,color:#fff
+    style t5 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style t6 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style t7 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style t8 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style t9 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style t10 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
+    style t11 fill:#0d47a1,stroke:#082f6a,color:#fff
+    style t12 fill:#0d47a1,stroke:#082f6a,color:#fff
+    style t13 fill:#4a148c,stroke:#2e0d57,color:#fff
+    style t14 fill:#4a148c,stroke:#2e0d57,color:#fff
+```
+
+---
+
+_Previous: [Configuration Reference](./05-configuration-reference.md)_ | _Next: [Observability Backends](./07-observability-backends.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/07-observability-backends.md

@@ -0,0 +1,595 @@
+# 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

@@ -0,0 +1,133 @@
+# 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              |
+
+---
+
+## 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 |
+
+---
+
+## 8.5 Document Index
+
+| Document                                                         | Description                                |
+| ---------------------------------------------------------------- | ------------------------------------------ |
+| [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)                   | Master overview and executive summary      |
+| [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      |
+
+---
+
+_Previous: [Observability Backends](./07-observability-backends.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/OpenTelemetryPlan.md

@@ -0,0 +1,190 @@
+# [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"]
+    end
+
+    overview --> analysis
+    overview --> impl
+    overview --> deploy
+
+    arch --> design
+    design --> strategy
+    strategy --> code
+    code --> config
+    config --> phases
+    phases --> backends
+    backends --> appendix
+
+    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
+```
+
+</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                                  |
+
+---
+
+## 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 9 weeks across 5 phases:
+
+| Phase | Duration  | Focus               | Key Deliverables                                    |
+| ----- | --------- | ------------------- | --------------------------------------------------- |
+| 1     | Weeks 1-2 | Core Infrastructure | SDK integration, Telemetry interface, Configuration |
+| 2     | Weeks 3-4 | RPC Tracing         | HTTP context extraction, Handler instrumentation    |
+| 3     | Weeks 5-6 | Transaction Tracing | Protocol Buffer context, Relay propagation          |
+| 4     | Weeks 7-8 | Consensus Tracing   | Round spans, Proposal/validation tracing            |
+| 5     | Week 9    | Documentation       | Runbook, Dashboards, Training                       |
+
+**Total Effort**: 47 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)**
+
+---
+
+_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

@@ -0,0 +1,610 @@
+# 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     |

README.md

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

SECURITY.md

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

bin/git/setup-upstreams.sh

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

bin/git/squash-branches.sh

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

bin/git/update-version.sh

@@ -1,22 +1,23 @@
 #!/bin/bash
 
-if [[ $# -ne 3 || "$1" == "--help" || "$1" = "-h" ]]; then
-    name=$(basename $0)
-    cat <<-USAGE
-    Usage: $name workbranch base/branch version
+if [[ $# -ne 3 || "$1" == "--help" || "$1" = "-h" ]]
+then
+  name=$( basename $0 )
+  cat <<- USAGE
+  Usage: $name workbranch base/branch version
 
-    * workbranch will be created locally from base/branch. If it exists,
-        it will be reused, so make sure you don't overwrite any work.
-    * base/branch may be specified as user:branch to allow easy copying
-        from Github PRs.
+  * workbranch will be created locally from base/branch. If it exists,
+    it will be reused, so make sure you don't overwrite any work.
+  * base/branch may be specified as user:branch to allow easy copying
+    from Github PRs.
 USAGE
-    exit 0
+exit 0
 fi
 
 work="$1"
 shift
 
-base=$(echo "$1" | sed "s/:/\//")
+base=$( echo "$1" | sed "s/:/\//" )
 shift
 
 version=$1
@@ -28,16 +29,17 @@ git fetch upstreams
 
 git checkout -B "${work}" --no-track "${base}"
 
-push=$(git rev-parse --abbrev-ref --symbolic-full-name '@{push}' \
-    2>/dev/null) || true
-if [[ "${push}" != "" ]]; then
-    echo "Warning: ${push} may already exist."
+push=$( git rev-parse --abbrev-ref --symbolic-full-name '@{push}' \
+              2>/dev/null ) || true
+if [[ "${push}" != "" ]]
+then
+  echo "Warning: ${push} may already exist."
 fi
 
-build=$(find -name BuildInfo.cpp)
-sed 's/\(^.*versionString =\).*$/\1 "'${version}'"/' ${build} >version.cpp &&
-    diff "${build}" version.cpp && exit 1 ||
-    mv -vi version.cpp ${build}
+build=$( find -name BuildInfo.cpp )
+sed 's/\(^.*versionString =\).*$/\1 "'${version}'"/' ${build} > version.cpp && \
+diff "${build}" version.cpp && exit 1 || \
+mv -vi version.cpp ${build}
 
 git diff
 
@@ -47,7 +49,7 @@ git commit -S -m "Set version to ${version}"
 
 git log --oneline --first-parent ${base}^..
 
-cat <<PUSH
+cat << PUSH
 
 -------------------------------------------------------------------
 This script will not push. Verify everything is correct, then push

bin/pre-commit/clang_tidy_check.py

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

bin/pre-commit/fix_include_style.py

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

cfg/validators-example.txt

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

cfg/xrpld-example.cfg

@@ -9,7 +9,7 @@
 #
 #   2. Peer Protocol
 #
-#   3. XRPL protocol
+#   3. Ripple Protocol
 #
 #   4. HTTPS Client
 #
@@ -383,7 +383,7 @@
 #
 #   These settings control security and access attributes of the Peer to Peer
 #   server section of the xrpld process. Peer Protocol implements the
-#   XRPL payment protocol. It is over peer connections that transactions
+#   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.
 #
@@ -406,7 +406,7 @@
 #
 # [ips]
 #
-#   List of hostnames or ips where the XRPL protocol is served.  A default
+#   List of hostnames or ips where the Ripple protocol is served.  A default
 #   starter list is included in the code and used if no other hostnames are
 #   available.
 #
@@ -435,7 +435,7 @@
 #   List of IP addresses or hostnames to which xrpld should always attempt to
 #   maintain peer connections with. This is useful for manually forming private
 #   networks, for example to configure a validation server that connects to the
-#   XRPL network through a public-facing server, or for building a set
+#   Ripple network through a public-facing server, or for building a set
 #   of cluster peers.
 #
 #   One address or domain names per line is allowed. A port must be specified
@@ -527,17 +527,6 @@
 #
 #       The current default (which is subject to change) is 300 seconds.
 #
-#   verify_endpoints = <0 | 1>
-#
-#       If set to 0, the server will skip validation of endpoint
-#       addresses received in TMEndpoints peer protocol messages,
-#       allowing addresses that are not publicly routable or have a
-#       port of 0. The default is 1 (verification enabled).
-#
-#       WARNING: Disabling this option is a security risk and should
-#       only be used for local testing and debugging. Do not disable
-#       on mainnet.
-#
 #
 # [transaction_queue] EXPERIMENTAL
 #
@@ -759,8 +748,8 @@
 #   the folder in which the xrpld.cfg file is located.
 #
 #   Examples:
-#    /home/username/validators.txt
-#    C:/home/username/validators.txt
+#    /home/ripple/validators.txt
+#    C:/home/ripple/validators.txt
 #
 #   Example content:
 #    [validators]
@@ -851,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, an xrpld node only downloads
+#      acquiring a ledger from the network, a xrpld node only downloads
 #      the ledger header and the transactions instead of the whole ledger.
 #      And the ledger is built by applying the transactions to the parent
 #      ledger.
@@ -864,7 +853,7 @@
 #
 #   The xrpld server instance uses HTTPS GET requests in a variety of
 #   circumstances, including but not limited to contacting trusted domains to
-#   fetch information such as mapping an email address to an XRPL payment
+#   fetch information such as mapping an email address to a Ripple Payment
 #   Network address.
 #
 # [ssl_verify]
@@ -953,21 +942,6 @@
 #
 #   Optional keys for NuDB and RocksDB:
 #
-#       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 cache_size or cache_age is not specified,
-#                           default values will be used for the unspecified
-#                           parameter.
-#
-#                           Note: the cache will not be created if online_delete
-#                           is specified, because the rotating NodeStore does
-#                           not use this cache).
-#
 #       fast_load           Boolean. If set, load the last persisted ledger
 #                           from disk upon process start before syncing to
 #                           the network. This is likely to improve performance
@@ -1253,7 +1227,7 @@
 #
 #----------
 #
-#   The vote settings configure settings for the entire XRPL network.
+#   The vote settings configure settings for the entire Ripple network.
 #   While a single instance of xrpld cannot unilaterally enforce network-wide
 #   settings, these choices become part of the instance's vote during the
 #   consensus process for each voting ledger.
@@ -1284,7 +1258,7 @@
 #       default. Don't change this without understanding the consequences.
 #
 #       Example:
-#           account_reserve = 1000000   # 1 XRP
+#           account_reserve = 10000000   # 10 XRP
 #
 #   owner_reserve = <drops>
 #
@@ -1296,7 +1270,7 @@
 #       default. Don't change this without understanding the consequences.
 #
 #       Example:
-#           owner_reserve = 200000      # 0.2 XRP
+#           owner_reserve = 2000000      # 2 XRP
 #
 #-------------------------------------------------------------------------------
 #
@@ -1442,12 +1416,6 @@
 #       in this section to a comma-separated list of the addresses
 #       of your Clio servers, in order to bypass xrpld's rate limiting.
 #
-#       TLS/SSL can be enabled for gRPC by specifying ssl_cert and ssl_key.
-#       Both parameters must be provided together. The ssl_cert_chain parameter
-#       is optional and provides intermediate CA certificates for the certificate
-#       chain. The ssl_client_ca parameter is optional and enables mutual TLS
-#       (client certificate verification).
-#
 #   This port is commented out but can be enabled by removing
 #   the '#' from each corresponding line including the entry under [server]
 #
@@ -1481,7 +1449,10 @@ admin = 127.0.0.1
 protocol = http
 
 [port_peer]
-port = 2459
+# Many servers still use the legacy port of 51235, so for backward-compatibility
+# we maintain that port number here. However, for new servers we recommend
+# changing this to the default port of 2459.
+port = 51235
 ip = 0.0.0.0
 # alternatively, to accept connections on IPv4 + IPv6, use:
 #ip = ::
@@ -1494,74 +1465,11 @@ admin = 127.0.0.1
 protocol = ws
 send_queue_limit = 500
 
-# gRPC TLS/SSL Configuration
-#
-#   The gRPC port supports optional TLS/SSL encryption. When TLS is not
-#   configured, the gRPC server will accept unencrypted connections.
-#
-#   ssl_cert = <filename>
-#   ssl_key = <filename>
-#
-#       To enable TLS for gRPC, both ssl_cert and ssl_key must be specified.
-#       If only one is provided, xrpld will fail to start.
-#
-#       ssl_cert: Path to the server's SSL certificate file in PEM format.
-#       ssl_key:  Path to the server's SSL private key file in PEM format.
-#
-#       When configured, the gRPC server will only accept TLS-encrypted
-#       connections. Clients must use TLS (secure) channel credentials rather
-#       than plaintext / insecure connections.
-#
-#   ssl_cert_chain = <filename>
-#
-#       Optional. Path to intermediate CA certificate(s) in PEM format that
-#       complete the server's certificate chain.
-#
-#       This file should contain the intermediate CA certificate(s) needed
-#       to build a trust chain from the server certificate (ssl_cert) to a
-#       root CA that clients trust. Multiple certificates should be
-#       concatenated in PEM format.
-#
-#       This is needed when your server certificate was signed by an
-#       intermediate CA rather than directly by a root CA. Without this,
-#       clients may fail to verify your server certificate.
-#
-#       If not specified, only the server certificate from ssl_cert will be
-#       presented to clients.
-#
-#   ssl_client_ca = <filename>
-#
-#       Optional. Path to a CA certificate file in PEM format for verifying
-#       client certificates (mutual TLS / mTLS).
-#
-#       When specified, the gRPC server will verify client certificates
-#       against this CA. This enables mutual authentication where both the
-#       server and client verify each other's identity.
-#
-#       This is typically NOT needed for public-facing gRPC servers. Only
-#       use this if you want to restrict access to clients with valid
-#       certificates signed by the specified CA.
-#
-#       If not specified, the server will use one-way TLS (server
-#       authentication only) and will accept connections from any client.
-#
 [port_grpc]
 port = 50051
 ip = 127.0.0.1
 secure_gateway = 127.0.0.1
 
-# Optional TLS/SSL configuration for gRPC
-# To enable TLS, uncomment and configure both ssl_cert and ssl_key:
-#ssl_cert = /etc/ssl/certs/grpc-server.crt
-#ssl_key = /etc/ssl/private/grpc-server.key
-
-# Optional: Include intermediate CA certificates for complete certificate chain
-#ssl_cert_chain = /etc/ssl/certs/grpc-intermediate-ca.crt
-
-# Optional: Enable mutual TLS (client certificate verification)
-# Uncomment to require and verify client certificates:
-#ssl_client_ca = /etc/ssl/certs/grpc-client-ca.crt
-
 #[port_ws_public]
 #port = 6005
 #ip = 127.0.0.1
@@ -1621,3 +1529,46 @@ 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.
+#

cmake/CMakeFuncs.cmake

@@ -1,32 +1,29 @@
-macro(exclude_from_default target_)
+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()
+endmacro ()
 
-macro(exclude_if_included target_)
+macro (exclude_if_included target_)
     get_directory_property(has_parent PARENT_DIRECTORY)
-    if(has_parent)
+    if (has_parent)
         exclude_from_default(${target_})
-    endif()
-endmacro()
+    endif ()
+endmacro ()
 
 find_package(Git)
 
-function(git_branch branch_val)
-    if(NOT GIT_FOUND)
+function (git_branch branch_val)
+    if (NOT GIT_FOUND)
         return()
-    endif()
+    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)
+    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()
+    endif ()
     set(${branch_val} "${_branch}" PARENT_SCOPE)
-endfunction()
+endfunction ()

cmake/Ccache.cmake

@@ -1,62 +1,50 @@
 find_program(CCACHE_PATH "ccache")
-if(NOT CCACHE_PATH)
+if (NOT CCACHE_PATH)
     return()
-endif()
+endif ()
 
 # For Linux and macOS we can use the ccache binary directly.
-if(NOT MSVC)
+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()
+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")
+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)
+    if (NOT BASH_PATH)
         message(WARNING "Could not find bash.")
         return()
-    endif()
+    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
-    )
+    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)
+    if (NOT CCACHE_PATH)
         message(WARNING "Could not find ccache target.")
         return()
-    endif()
+    endif ()
     file(TO_CMAKE_PATH "${CCACHE_PATH}" CCACHE_PATH)
-endif()
+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"
-)
+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
-    )
+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()
+    endforeach ()
+endif ()

cmake/CodeCoverage.cmake

@@ -174,45 +174,37 @@ option(CODE_COVERAGE_VERBOSE "Verbose information" FALSE)
 # Check prereqs
 find_program(GCOVR_PATH gcovr PATHS ${CMAKE_SOURCE_DIR}/scripts/test)
 
-if(DEFINED CODE_COVERAGE_GCOV_TOOL)
+if (DEFINED CODE_COVERAGE_GCOV_TOOL)
     set(GCOV_TOOL "${CODE_COVERAGE_GCOV_TOOL}")
-elseif(DEFINED ENV{CODE_COVERAGE_GCOV_TOOL})
+elseif (DEFINED 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()
+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)
+    endif ()
+    if (LLVMCOV_PATH)
         set(GCOV_TOOL "${LLVMCOV_PATH} gcov")
-    endif()
-elseif("${CMAKE_CXX_COMPILER_ID}" MATCHES "GNU")
+    endif ()
+elseif ("${CMAKE_CXX_COMPILER_ID}" MATCHES "GNU")
     find_program(GCOV_PATH gcov)
     set(GCOV_TOOL "${GCOV_PATH}")
-endif()
+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"
-    )
+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...")
-    endif()
-endforeach()
+    endif ()
+endforeach ()
 
 set(COVERAGE_COMPILER_FLAGS "-g --coverage" CACHE INTERNAL "")
 
@@ -221,7 +213,7 @@ set(COVERAGE_C_COMPILER_FLAGS "")
 set(COVERAGE_CXX_LINKER_FLAGS "")
 set(COVERAGE_C_LINKER_FLAGS "")
 
-if(CMAKE_CXX_COMPILER_ID MATCHES "(GNU|Clang)")
+if (CMAKE_CXX_COMPILER_ID MATCHES "(GNU|Clang)")
     include(CheckCXXCompilerFlag)
     include(CheckCCompilerFlag)
     include(CheckLinkerFlag)
@@ -232,77 +224,51 @@ if(CMAKE_CXX_COMPILER_ID MATCHES "(GNU|Clang)")
     set(COVERAGE_C_LINKER_FLAGS ${COVERAGE_COMPILER_FLAGS})
 
     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"
-        )
-    endif()
+    if (HAVE_cxx_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"
-        )
-    endif()
+    if (HAVE_c_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"
-        )
-    endif()
+    if (HAVE_cxx_linker_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"
-        )
-    endif()
+    if (HAVE_c_linker_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"
-        )
-    endif()
+    if (HAVE_cxx_fprofile_update)
+        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"
-        )
-    endif()
+    if (HAVE_c_fprofile_update)
+        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
-    )
-    if(HAVE_cxx_linker_fprofile_update)
-        set(COVERAGE_CXX_LINKER_FLAGS
-            "${COVERAGE_CXX_LINKER_FLAGS} -fprofile-update=atomic"
-        )
-    endif()
+    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")
+    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"
-        )
-    endif()
-endif()
+    if (HAVE_c_linker_fprofile_update)
+        set(COVERAGE_C_LINKER_FLAGS "${COVERAGE_C_LINKER_FLAGS} -fprofile-update=atomic")
+    endif ()
 
-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"
-    )
-endif() # NOT (CMAKE_BUILD_TYPE STREQUAL "Debug" OR GENERATOR_IS_MULTI_CONFIG)
+endif ()
+
+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")
+endif () # NOT (CMAKE_BUILD_TYPE STREQUAL "Debug" OR GENERATOR_IS_MULTI_CONFIG)
 
 # Defines a target for running and collection code coverage information
 # Builds dependencies, runs the given executable and outputs reports.
@@ -326,167 +292,125 @@ endif() # NOT (CMAKE_BUILD_TYPE STREQUAL "Debug" OR GENERATOR_IS_MULTI_CONFIG)
 # )
 # The user can set the variable GCOVR_ADDITIONAL_ARGS to supply additional flags to the
 # GCVOR command.
-function(setup_target_for_coverage_gcovr)
+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)
+    if (NOT GCOV_TOOL)
         message(FATAL_ERROR "Could not find gcov or llvm-cov tool! Aborting...")
-    endif()
+    endif ()
 
-    if(NOT GCOVR_PATH)
+    if (NOT GCOVR_PATH)
         message(FATAL_ERROR "Could not find gcovr tool! Aborting...")
-    endif()
+    endif ()
 
     # Set base directory (as absolute path), or default to PROJECT_SOURCE_DIR
-    if(DEFINED Coverage_BASE_DIRECTORY)
+    if (DEFINED Coverage_BASE_DIRECTORY)
         get_filename_component(BASEDIR ${Coverage_BASE_DIRECTORY} ABSOLUTE)
-    else()
+    else ()
         set(BASEDIR ${PROJECT_SOURCE_DIR})
-    endif()
+    endif ()
 
-    if(NOT DEFINED Coverage_FORMAT)
+    if (NOT DEFINED Coverage_FORMAT)
         set(Coverage_FORMAT xml)
-    endif()
+    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"
-        )
-    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")
+    endif ()
 
-    if("--output" IN_LIST GCOVR_ADDITIONAL_ARGS)
-        message(
-            FATAL_ERROR
-            "Unsupported --output option detected in GCOVR_ADDITIONAL_ARGS! Aborting..."
+    if ("--output" IN_LIST GCOVR_ADDITIONAL_ARGS)
+        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
-            )
+    else ()
+        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")
+        elseif (Coverage_FORMAT STREQUAL "html-single")
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.html)
-        elseif(
-            (Coverage_FORMAT STREQUAL "json-summary")
-            OR (Coverage_FORMAT STREQUAL "json-details")
-            OR (Coverage_FORMAT STREQUAL "coveralls")
-        )
+        elseif ((Coverage_FORMAT STREQUAL "json-summary") OR (Coverage_FORMAT STREQUAL
+                                                              "json-details")
+                OR (Coverage_FORMAT STREQUAL "coveralls"))
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.json)
-        elseif(Coverage_FORMAT STREQUAL "txt")
+        elseif (Coverage_FORMAT STREQUAL "txt")
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.txt)
-        elseif(Coverage_FORMAT STREQUAL "csv")
+        elseif (Coverage_FORMAT STREQUAL "csv")
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.csv)
-        elseif(Coverage_FORMAT STREQUAL "lcov")
+        elseif (Coverage_FORMAT STREQUAL "lcov")
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.lcov)
-        else()
+        else ()
             set(GCOVR_OUTPUT_FILE ${Coverage_NAME}.xml)
-        endif()
-    endif()
+        endif ()
+    endif ()
 
-    if(
-        (Coverage_FORMAT STREQUAL "cobertura")
-        OR (Coverage_FORMAT STREQUAL "xml")
-    )
+    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")
+    elseif (Coverage_FORMAT STREQUAL "sonarqube")
         list(APPEND GCOVR_ADDITIONAL_ARGS --sonarqube "${GCOVR_OUTPUT_FILE}")
-    elseif(Coverage_FORMAT STREQUAL "jacoco")
+    elseif (Coverage_FORMAT STREQUAL "jacoco")
         list(APPEND GCOVR_ADDITIONAL_ARGS --jacoco "${GCOVR_OUTPUT_FILE}")
         list(APPEND GCOVR_ADDITIONAL_ARGS --jacoco-pretty)
-    elseif(Coverage_FORMAT STREQUAL "clover")
+    elseif (Coverage_FORMAT STREQUAL "clover")
         list(APPEND GCOVR_ADDITIONAL_ARGS --clover "${GCOVR_OUTPUT_FILE}")
         list(APPEND GCOVR_ADDITIONAL_ARGS --clover-pretty)
-    elseif(Coverage_FORMAT STREQUAL "lcov")
+    elseif (Coverage_FORMAT STREQUAL "lcov")
         list(APPEND GCOVR_ADDITIONAL_ARGS --lcov "${GCOVR_OUTPUT_FILE}")
-    elseif(Coverage_FORMAT STREQUAL "json-summary")
+    elseif (Coverage_FORMAT STREQUAL "json-summary")
         list(APPEND GCOVR_ADDITIONAL_ARGS --json-summary "${GCOVR_OUTPUT_FILE}")
         list(APPEND GCOVR_ADDITIONAL_ARGS --json-summary-pretty)
-    elseif(Coverage_FORMAT STREQUAL "json-details")
+    elseif (Coverage_FORMAT STREQUAL "json-details")
         list(APPEND GCOVR_ADDITIONAL_ARGS --json "${GCOVR_OUTPUT_FILE}")
         list(APPEND GCOVR_ADDITIONAL_ARGS --json-pretty)
-    elseif(Coverage_FORMAT STREQUAL "coveralls")
+    elseif (Coverage_FORMAT STREQUAL "coveralls")
         list(APPEND GCOVR_ADDITIONAL_ARGS --coveralls "${GCOVR_OUTPUT_FILE}")
         list(APPEND GCOVR_ADDITIONAL_ARGS --coveralls-pretty)
-    elseif(Coverage_FORMAT STREQUAL "csv")
+    elseif (Coverage_FORMAT STREQUAL "csv")
         list(APPEND GCOVR_ADDITIONAL_ARGS --csv "${GCOVR_OUTPUT_FILE}")
-    elseif(Coverage_FORMAT STREQUAL "txt")
+    elseif (Coverage_FORMAT STREQUAL "txt")
         list(APPEND GCOVR_ADDITIONAL_ARGS --txt "${GCOVR_OUTPUT_FILE}")
-    elseif(Coverage_FORMAT STREQUAL "html-single")
+    elseif (Coverage_FORMAT STREQUAL "html-single")
         list(APPEND GCOVR_ADDITIONAL_ARGS --html "${GCOVR_OUTPUT_FILE}")
         list(APPEND GCOVR_ADDITIONAL_ARGS --html-self-contained)
-    elseif(Coverage_FORMAT STREQUAL "html-nested")
+    elseif (Coverage_FORMAT STREQUAL "html-nested")
         list(APPEND GCOVR_ADDITIONAL_ARGS --html-nested "${GCOVR_OUTPUT_FILE}")
-    elseif(Coverage_FORMAT STREQUAL "html-details")
+    elseif (Coverage_FORMAT STREQUAL "html-details")
         list(APPEND GCOVR_ADDITIONAL_ARGS --html-details "${GCOVR_OUTPUT_FILE}")
-    else()
-        message(
-            FATAL_ERROR
-            "Unsupported output style ${Coverage_FORMAT}! Aborting..."
-        )
-    endif()
+    else ()
+        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}
-    )
-        if(CMAKE_VERSION VERSION_GREATER 3.4)
-            get_filename_component(
-                EXCLUDE
-                ${EXCLUDE}
-                ABSOLUTE
-                BASE_DIR ${BASEDIR}
-            )
-        endif()
+    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})
+        endif ()
         list(APPEND GCOVR_EXCLUDES "${EXCLUDE}")
-    endforeach()
+    endforeach ()
     list(REMOVE_DUPLICATES GCOVR_EXCLUDES)
 
     # Combine excludes to several -e arguments
     set(GCOVR_EXCLUDE_ARGS "")
-    foreach(EXCLUDE ${GCOVR_EXCLUDES})
+    foreach (EXCLUDE ${GCOVR_EXCLUDES})
         list(APPEND GCOVR_EXCLUDE_ARGS "-e")
         list(APPEND GCOVR_EXCLUDE_ARGS "${EXCLUDE}")
-    endforeach()
+    endforeach ()
 
     # Set up commands which will be run to generate coverage data
     # If EXECUTABLE is not set, the user is expected to run the tests manually
     # before running the coverage target NAME
-    if(DEFINED Coverage_EXECUTABLE)
-        set(GCOVR_EXEC_TESTS_CMD
-            ${Coverage_EXECUTABLE}
-            ${Coverage_EXECUTABLE_ARGS}
-        )
-    endif()
+    if (DEFINED Coverage_EXECUTABLE)
+        set(GCOVR_EXEC_TESTS_CMD ${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}
-        )
-    endif()
+    if (DEFINED GCOVR_CREATE_FOLDER)
+        set(GCOVR_FOLDER_CMD ${CMAKE_COMMAND} -E make_directory ${GCOVR_CREATE_FOLDER})
+    endif ()
 
     # Running gcovr
     set(GCOVR_CMD
@@ -498,95 +422,56 @@ function(setup_target_for_coverage_gcovr)
         ${BASEDIR}
         ${GCOVR_ADDITIONAL_ARGS}
         ${GCOVR_EXCLUDE_ARGS}
-        --object-directory=${PROJECT_BINARY_DIR}
-    )
+        --object-directory=${PROJECT_BINARY_DIR})
 
-    if(CODE_COVERAGE_VERBOSE)
+    if (CODE_COVERAGE_VERBOSE)
         message(STATUS "Executed command report")
 
-        if(NOT "${GCOVR_EXEC_TESTS_CMD}" STREQUAL "")
+        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()
+        endif ()
 
-        if(NOT "${GCOVR_FOLDER_CMD}" STREQUAL "")
+        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()
+        endif ()
 
         message(STATUS "Command to generate gcovr coverage data: ")
         string(REPLACE ";" " " GCOVR_CMD_SPACED "${GCOVR_CMD}")
         message(STATUS "${GCOVR_CMD_SPACED}")
-    endif()
+    endif ()
 
-    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}
-        VERBATIM # Protect arguments to commands
-        COMMENT "Running gcovr to produce code coverage report."
-    )
+    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}
+                      VERBATIM # Protect arguments to commands
+                      COMMENT "Running gcovr to produce code coverage report.")
 
     # Show info where to find the report
     add_custom_command(
-        TARGET ${Coverage_NAME}
-        POST_BUILD
-        COMMAND echo
-        COMMENT
-            "Code coverage report saved in ${GCOVR_OUTPUT_FILE} formatted as ${Coverage_FORMAT}"
+        TARGET ${Coverage_NAME} POST_BUILD COMMAND echo
+        COMMENT "Code coverage report saved in ${GCOVR_OUTPUT_FILE} formatted as ${Coverage_FORMAT}"
     )
-endfunction() # setup_target_for_coverage_gcovr
+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}"
-    )
+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}")
 
     # 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}>
-    )
+        ${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}>
-    )
-endfunction() # add_code_coverage_to_target
+    target_link_libraries(${name} ${scope} $<$<LINK_LANGUAGE:CXX>:${COVERAGE_CXX_LINKER_FLAGS}>
+                          $<$<LINK_LANGUAGE:C>:${COVERAGE_C_LINKER_FLAGS}>)
+endfunction () # add_code_coverage_to_target

cmake/CompilationEnv.cmake

@@ -14,20 +14,20 @@ set(is_gcc FALSE)
 set(is_msvc FALSE)
 set(is_xcode FALSE)
 
-if(CMAKE_CXX_COMPILER_ID MATCHES ".*Clang") # Clang or AppleClang
+if (CMAKE_CXX_COMPILER_ID MATCHES ".*Clang") # Clang or AppleClang
     set(is_clang TRUE)
-elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+elseif (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
     set(is_gcc TRUE)
-elseif(MSVC)
+elseif (MSVC)
     set(is_msvc TRUE)
-else()
+else ()
     message(FATAL_ERROR "Unsupported C++ compiler: ${CMAKE_CXX_COMPILER_ID}")
-endif()
+endif ()
 
 # Xcode generator detection
-if(CMAKE_GENERATOR STREQUAL "Xcode")
+if (CMAKE_GENERATOR STREQUAL "Xcode")
     set(is_xcode TRUE)
-endif()
+endif ()
 
 # --------------------------------------------------------------------
 # Operating system detection
@@ -36,23 +36,23 @@ set(is_linux FALSE)
 set(is_windows FALSE)
 set(is_macos FALSE)
 
-if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+if (CMAKE_SYSTEM_NAME STREQUAL "Linux")
     set(is_linux TRUE)
-elseif(CMAKE_SYSTEM_NAME STREQUAL "Windows")
+elseif (CMAKE_SYSTEM_NAME STREQUAL "Windows")
     set(is_windows TRUE)
-elseif(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+elseif (CMAKE_SYSTEM_NAME STREQUAL "Darwin")
     set(is_macos TRUE)
-endif()
+endif ()
 
 # --------------------------------------------------------------------
 # Architecture
 # --------------------------------------------------------------------
 set(is_amd64 FALSE)
 set(is_arm64 FALSE)
-if(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64")
+if (CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64")
     set(is_amd64 TRUE)
-elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64|ARM64")
+elseif (CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64|ARM64")
     set(is_arm64 TRUE)
-else()
+else ()
     message(FATAL_ERROR "Unknown architecture: ${CMAKE_SYSTEM_PROCESSOR}")
-endif()
+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

@@ -0,0 +1,13 @@
+include(isolate_headers)
+
+function (xrpl_add_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})
+
+    isolate_headers(${target} "${CMAKE_SOURCE_DIR}" "${CMAKE_SOURCE_DIR}/tests/${name}" PRIVATE)
+
+    add_test(NAME ${target} COMMAND ${target})
+endfunction ()

cmake/XrplCompiler.cmake

@@ -14,42 +14,33 @@ include(XrplSanitizers)
 # 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)
+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}
-)
+endif ()
+set_target_properties(common PROPERTIES INTERFACE_POSITION_INDEPENDENT_CODE
+                                        ${CMAKE_POSITION_INDEPENDENT_CODE})
 set(CMAKE_CXX_EXTENSIONS OFF)
 target_compile_definitions(
     common
-    INTERFACE
-        $<$<CONFIG:Debug>:DEBUG
-        _DEBUG>
-        #[===[
+    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)
+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
-    )
+    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_}}")
 
@@ -57,169 +48,120 @@ if(MSVC)
         string(REPLACE "/ZI" "/Zi" ${var_} "${${var_}}")
 
         # omit debug info completely under CI (not needed)
-        if(is_ci)
+        if (is_ci)
             string(REPLACE "/Zi" " " ${var_} "${${var_}}")
             string(REPLACE "/Z7" " " ${var_} "${${var_}}")
-        endif()
-    endforeach()
+        endif ()
+    endforeach ()
 
     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>
-    )
+                  -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>
-    )
+        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()
+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>
-    )
+        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++ if:
-            # * static option set and
-            # * NOT APPLE (AppleClang does not support static libc/c++)
-            $<$<AND:$<BOOL:${static}>,$<NOT:$<BOOL:${APPLE}>>>:
-            -static-libstdc++
-            -static-libgcc
-            >
-    )
-
-    # Keep -stdlib=libstdc++ off the compile commands, but preserve it for linking.
-    #
-    # Conan turns `compiler.libcxx=libstdc++` into `-stdlib=libstdc++` and puts it in
-    # CMAKE_CXX_FLAGS, which CMake passes to BOTH compile and link steps. On a normal Clang
-    # the compile step consumes it while choosing the C++ stdlib include paths. The Nixpkgs
-    # Clang wrapper supplies those paths itself (via -nostdinc++), so at compile time the
-    # flag is unused -> Clang errors under our -Werror. At link time the flag IS consumed
-    # (it selects the C++ runtime), so we move it there instead of dropping it entirely.
-    get_filename_component(_cxx_real "${CMAKE_CXX_COMPILER}" REALPATH)
-    if(
-        _cxx_real MATCHES "^/nix/store/"
-        AND is_linux
-        AND is_clang
-        AND CMAKE_CXX_FLAGS MATCHES "stdlib=libstdc"
-    )
-        string(
-            REPLACE "-stdlib=libstdc++"
-            ""
-            CMAKE_CXX_FLAGS
-            "${CMAKE_CXX_FLAGS}"
-        )
-        string(STRIP "${CMAKE_CXX_FLAGS}" CMAKE_CXX_FLAGS)
-        add_link_options($<$<LINK_LANGUAGE:CXX>:-stdlib=libstdc++>)
-    endif()
-endif()
+        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 ()
 
 # 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..."
+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..."
         )
-    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()
+    endif ()
+endif ()
 
-if(use_mold)
+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")
+    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()
+    endif ()
     unset(LD_VERSION)
-elseif(use_gold AND is_gcc)
+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
-    )
+    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
@@ -233,37 +175,32 @@ 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))
+    if (("${LD_VERSION}" MATCHES "GNU gold") AND (NOT jemalloc))
         target_link_libraries(
             common
-            INTERFACE
-                -fuse-ld=gold
-                -Wl,--no-as-needed
-                #[=========================================================[
+            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()
+                      $<$<NOT:$<BOOL:${static}>>:-Wl,--disable-new-dtags>)
+    endif ()
     unset(LD_VERSION)
-elseif(use_lld)
+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")
+    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()
+    endif ()
     unset(LD_VERSION)
-endif()
+endif ()
 
-if(assert)
-    foreach(var_ CMAKE_C_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELEASE)
+if (assert)
+    foreach (var_ CMAKE_C_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELEASE)
         string(REGEX REPLACE "[-/]DNDEBUG" "" ${var_} "${${var_}}")
-    endforeach()
-endif()
+    endforeach ()
+endif ()

cmake/XrplConfig.cmake

@@ -0,0 +1,52 @@
+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,44 +10,25 @@ 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
+    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
-)
+    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>
-)
+    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_link_libraries(xrpl.libpb PUBLIC protobuf::libprotobuf gRPC::grpc++)
 
@@ -56,21 +37,19 @@ 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>
-)
+    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)
 include(target_link_modules)
@@ -79,16 +58,6 @@ include(target_link_modules)
 add_module(xrpl beast)
 target_link_libraries(xrpl.libxrpl.beast PUBLIC xrpl.imports.main)
 
-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)
 target_link_libraries(xrpl.libxrpl.basics PUBLIC xrpl.libxrpl.beast)
@@ -102,75 +71,36 @@ 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 protocol_autogen)
-target_link_libraries(
-    xrpl.libxrpl.protocol_autogen
-    PUBLIC xrpl.libxrpl.protocol
-)
+add_module(xrpl core)
+target_link_libraries(xrpl.libxrpl.core PUBLIC xrpl.libxrpl.basics xrpl.libxrpl.json
+                                               xrpl.libxrpl.protocol)
 
 # Level 06
-add_module(xrpl core)
-target_link_libraries(
-    xrpl.libxrpl.core
-    PUBLIC
-        xrpl.libxrpl.basics
-        xrpl.libxrpl.json
-        xrpl.libxrpl.protocol
-        xrpl.libxrpl.protocol_autogen
-)
-
-# Level 07
 add_module(xrpl resource)
 target_link_libraries(xrpl.libxrpl.resource PUBLIC xrpl.libxrpl.protocol)
 
-# Level 08
+# Level 07
 add_module(xrpl net)
-target_link_libraries(
-    xrpl.libxrpl.net
-    PUBLIC
-        xrpl.libxrpl.basics
-        xrpl.libxrpl.json
-        xrpl.libxrpl.protocol
-        xrpl.libxrpl.resource
-)
+target_link_libraries(xrpl.libxrpl.net 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
-)
+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
-        xrpl.libxrpl.basics
-        xrpl.libxrpl.crypto
-        xrpl.libxrpl.protocol
-        xrpl.libxrpl.nodestore
-)
+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
-)
+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
-)
+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)
@@ -178,30 +108,34 @@ 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.protocol_autogen
-        xrpl.libxrpl.rdb
-        xrpl.libxrpl.server
-        xrpl.libxrpl.shamap
-        xrpl.libxrpl.conditions
-)
+    PUBLIC xrpl.libxrpl.basics
+           xrpl.libxrpl.json
+           xrpl.libxrpl.protocol
+           xrpl.libxrpl.rdb
+           xrpl.libxrpl.server
+           xrpl.libxrpl.shamap
+           xrpl.libxrpl.conditions)
 
 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(
@@ -212,19 +146,17 @@ target_link_modules(
     conditions
     core
     crypto
-    git
     json
     ledger
     net
     nodestore
     protocol
-    protocol_autogen
     rdb
     resource
     server
     shamap
-    tx
-)
+    telemetry
+    tx)
 
 # All headers in libxrpl are in modules.
 # Uncomment this stanza if you have not yet moved new headers into a module.
@@ -235,51 +167,34 @@ target_link_modules(
 #     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
 #     $<INSTALL_INTERFACE:include>)
 
-if(xrpld)
+if (xrpld)
     add_executable(xrpld)
-    if(tests)
+    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>
-    )
+        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"
-        )
+    if (tests)
+        file(GLOB_RECURSE sources CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src/test/*.cpp")
         target_sources(xrpld PRIVATE ${sources})
-    endif()
+    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)
+    if (is_ci)
         target_compile_definitions(xrpld PRIVATE XRPL_RUNNING_IN_CI)
-    endif()
+    endif ()
 
-    if(voidstar)
+    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()
-endif()
+        target_include_directories(xrpld PRIVATE ${CMAKE_SOURCE_DIR}/external/antithesis-sdk)
+    endif ()
+endif ()

cmake/XrplCov.cmake

@@ -2,17 +2,14 @@
    coverage report target
 #]===================================================================]
 
-if(NOT coverage)
+if (NOT coverage)
     message(FATAL_ERROR "Code coverage not enabled! Aborting ...")
-endif()
+endif ()
 
-if(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
-    message(
-        WARNING
-        "Code coverage on Windows is not supported, ignoring 'coverage' flag"
-    )
+if (CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
+    message(WARNING "Code coverage on Windows is not supported, ignoring 'coverage' flag")
     return()
-endif()
+endif ()
 
 include(ProcessorCount)
 ProcessorCount(PROCESSOR_COUNT)
@@ -24,30 +21,32 @@ include(CodeCoverage)
 # `CodeCoverage.cmake`)
 
 set(GCOVR_ADDITIONAL_ARGS ${coverage_extra_args})
-if(NOT GCOVR_ADDITIONAL_ARGS STREQUAL "")
+if (NOT GCOVR_ADDITIONAL_ARGS STREQUAL "")
     separate_arguments(GCOVR_ADDITIONAL_ARGS)
-endif()
+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}
+    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
-)
+    "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

@@ -2,90 +2,71 @@
    docs target (optional)
 #]===================================================================]
 
-if(NOT only_docs)
+if (NOT only_docs)
     return()
-endif()
+endif ()
 
 find_package(Doxygen)
-if(NOT TARGET Doxygen::doxygen)
+if (NOT TARGET Doxygen::doxygen)
     message(STATUS "doxygen executable not found -- skipping docs target")
     return()
-endif()
+endif ()
 
 set(doxygen_output_directory "${CMAKE_BINARY_DIR}/docs")
 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
-)
+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)
+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})
+    if (NOT ${variable})
         message(NOTICE "could not find ${name}")
-    else()
+    else ()
         message(STATUS "found ${name}: ${${variable}}/${name}")
-    endif()
-endfunction()
+    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 \
   )\n \
   execute_process( \
     COMMAND \"${CMAKE_COMMAND}\" -E tar -xf cppreference.zip \
-  )\n"
-)
+  )\n")
 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"
-)
+add_custom_command(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}"
+    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}"
-)
+    DEPENDS "${dependencies}" "${tagfile}")
+add_custom_target(docs DEPENDS "${doxygen_index_file}" SOURCES "${dependencies}")

cmake/XrplInstall.cmake

@@ -2,38 +2,78 @@
    install stuff
 #]===================================================================]
 
-include(GNUInstallDirs)
+include(create_symbolic_link)
 
-if(is_root_project AND TARGET xrpld)
-    install(
-        TARGETS xrpld
-        RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT runtime
-    )
+# If no suffix is defined for executables (e.g. Windows uses .exe but Linux
+# and macOS use none), then explicitly set it to the empty string.
+if (NOT DEFINED suffix)
+    set(suffix "")
+endif ()
 
-    install(
-        FILES "${CMAKE_CURRENT_SOURCE_DIR}/cfg/xrpld-example.cfg"
-        DESTINATION "${CMAKE_INSTALL_SYSCONFDIR}/xrpld"
-        RENAME xrpld.cfg
-        COMPONENT runtime
-    )
+install(TARGETS common
+                opts
+                xrpl_boost
+                xrpl_libs
+                xrpl_syslibs
+                xrpl.imports.main
+                xrpl.libpb
+                xrpl.libxrpl
+                xrpl.libxrpl.basics
+                xrpl.libxrpl.beast
+                xrpl.libxrpl.conditions
+                xrpl.libxrpl.core
+                xrpl.libxrpl.crypto
+                xrpl.libxrpl.json
+                xrpl.libxrpl.rdb
+                xrpl.libxrpl.ledger
+                xrpl.libxrpl.net
+                xrpl.libxrpl.nodestore
+                xrpl.libxrpl.protocol
+                xrpl.libxrpl.resource
+                xrpl.libxrpl.server
+                xrpl.libxrpl.shamap
+                xrpl.libxrpl.telemetry
+                xrpl.libxrpl.tx
+                antithesis-sdk-cpp
+        EXPORT XrplExports
+        LIBRARY DESTINATION lib
+        ARCHIVE DESTINATION lib
+        RUNTIME DESTINATION bin
+        INCLUDES
+        DESTINATION include)
 
-    install(
-        FILES "${CMAKE_CURRENT_SOURCE_DIR}/cfg/validators-example.txt"
-        DESTINATION "${CMAKE_INSTALL_SYSCONFDIR}/xrpld"
-        RENAME validators.txt
-        COMPONENT runtime
-    )
-endif()
+install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/include/xrpl"
+        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
 
-install(
-    TARGETS xrpl.libpb xrpl.libxrpl
-    LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}" COMPONENT development
-    ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}" COMPONENT development
-    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT development
-)
+install(EXPORT XrplExports FILE XrplTargets.cmake NAMESPACE Xrpl:: DESTINATION lib/cmake/xrpl)
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(XrplConfigVersion.cmake VERSION ${xrpld_version}
+                                 COMPATIBILITY SameMajorVersion)
 
-install(
-    DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/include/xrpl"
-    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-    COMPONENT development
-)
+if (is_root_project AND TARGET xrpld)
+    install(TARGETS xrpld RUNTIME DESTINATION bin)
+    set_target_properties(xrpld PROPERTIES INSTALL_RPATH_USE_LINK_PATH ON)
+    # sample configs should not overwrite existing files
+    # install if-not-exists workaround as suggested by
+    # https://cmake.org/Bug/view.php?id=12646
+    install(CODE "
+    macro (copy_if_not_exists SRC DEST NEWNAME)
+      if (NOT EXISTS \"\$ENV{DESTDIR}\${CMAKE_INSTALL_PREFIX}/\${DEST}/\${NEWNAME}\")
+        file (INSTALL FILE_PERMISSIONS OWNER_READ OWNER_WRITE DESTINATION \"\${CMAKE_INSTALL_PREFIX}/\${DEST}\" FILES \"\${SRC}\" RENAME \"\${NEWNAME}\")
+      else ()
+        message (\"-- Skipping : \$ENV{DESTDIR}\${CMAKE_INSTALL_PREFIX}/\${DEST}/\${NEWNAME}\")
+      endif ()
+    endmacro()
+    copy_if_not_exists(\"${CMAKE_CURRENT_SOURCE_DIR}/cfg/xrpld-example.cfg\" etc xrpld.cfg)
+    copy_if_not_exists(\"${CMAKE_CURRENT_SOURCE_DIR}/cfg/validators-example.txt\" etc validators.txt)
+  ")
+    install(CODE "
+    set(CMAKE_MODULE_PATH \"${CMAKE_MODULE_PATH}\")
+    include(create_symbolic_link)
+    create_symbolic_link(xrpld${suffix} \
+       \$ENV{DESTDIR}\${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_BINDIR}/rippled${suffix})
+  ")
+endif ()
+
+install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/cmake/XrplConfig.cmake
+              ${CMAKE_CURRENT_BINARY_DIR}/XrplConfigVersion.cmake DESTINATION lib/cmake/xrpl)

cmake/XrplInterface.cmake

@@ -5,54 +5,47 @@
 include(CompilationEnv)
 
 # Set defaults for optional variables to avoid uninitialized variable warnings
-if(NOT DEFINED voidstar)
+if (NOT DEFINED voidstar)
     set(voidstar OFF)
-endif()
+endif ()
 
 add_library(opts INTERFACE)
 add_library(Xrpl::opts ALIAS opts)
 target_compile_definitions(
     opts
-    INTERFACE
-        BOOST_ASIO_DISABLE_HANDLER_TYPE_REQUIREMENTS
-        BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT
-        BOOST_CONTAINER_FWD_BAD_DEQUE
-        HAS_UNCAUGHT_EXCEPTIONS=1
-        $<$<BOOL:${boost_show_deprecated}>:
-        BOOST_ASIO_NO_DEPRECATED
-        BOOST_FILESYSTEM_NO_DEPRECATED
-        >
-        $<$<NOT:$<BOOL:${boost_show_deprecated}>>:
-        BOOST_BEAST_ALLOW_DEPRECATED
-        BOOST_FILESYSTEM_DEPRECATED
-        >
-        $<$<BOOL:${beast_no_unit_test_inline}>:BEAST_NO_UNIT_TEST_INLINE=1>
-        $<$<BOOL:${beast_disable_autolink}>:BEAST_DONT_AUTOLINK_TO_WIN32_LIBRARIES=1>
-        $<$<BOOL:${single_io_service_thread}>:XRPL_SINGLE_IO_SERVICE_THREAD=1>
-        $<$<BOOL:${voidstar}>:ENABLE_VOIDSTAR>
-)
+    INTERFACE BOOST_ASIO_DISABLE_HANDLER_TYPE_REQUIREMENTS
+              BOOST_ASIO_USE_TS_EXECUTOR_AS_DEFAULT
+              BOOST_CONTAINER_FWD_BAD_DEQUE
+              HAS_UNCAUGHT_EXCEPTIONS=1
+              $<$<BOOL:${boost_show_deprecated}>:
+              BOOST_ASIO_NO_DEPRECATED
+              BOOST_FILESYSTEM_NO_DEPRECATED
+              >
+              $<$<NOT:$<BOOL:${boost_show_deprecated}>>:
+              BOOST_COROUTINES_NO_DEPRECATION_WARNING
+              BOOST_BEAST_ALLOW_DEPRECATED
+              BOOST_FILESYSTEM_DEPRECATED
+              >
+              $<$<BOOL:${beast_no_unit_test_inline}>:BEAST_NO_UNIT_TEST_INLINE=1>
+              $<$<BOOL:${beast_disable_autolink}>:BEAST_DONT_AUTOLINK_TO_WIN32_LIBRARIES=1>
+              $<$<BOOL:${single_io_service_thread}>:XRPL_SINGLE_IO_SERVICE_THREAD=1>
+              $<$<BOOL:${voidstar}>:ENABLE_VOIDSTAR>)
 target_compile_options(
     opts
-    INTERFACE
-        $<$<AND:$<BOOL:${is_gcc}>,$<COMPILE_LANGUAGE:CXX>>:-Wsuggest-override>
-        $<$<BOOL:${is_gcc}>:-Wno-maybe-uninitialized>
-        $<$<BOOL:${perf}>:-fno-omit-frame-pointer>
-        $<$<BOOL:${profile}>:-pg>
-        $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${profile}>>:-p>
-)
+    INTERFACE $<$<AND:$<BOOL:${is_gcc}>,$<COMPILE_LANGUAGE:CXX>>:-Wsuggest-override>
+              $<$<BOOL:${is_gcc}>:-Wno-maybe-uninitialized>
+              $<$<BOOL:${perf}>:-fno-omit-frame-pointer>
+              $<$<BOOL:${profile}>:-pg>
+              $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${profile}>>:-p>)
 
-target_link_libraries(
-    opts
-    INTERFACE
-        $<$<BOOL:${profile}>:-pg>
-        $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${profile}>>:-p>
-)
+target_link_libraries(opts INTERFACE $<$<BOOL:${profile}>:-pg>
+                                     $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${profile}>>:-p>)
 
-if(jemalloc)
+if (jemalloc)
     find_package(jemalloc REQUIRED)
     target_compile_definitions(opts INTERFACE PROFILE_JEMALLOC)
     target_link_libraries(opts INTERFACE jemalloc::jemalloc)
-endif()
+endif ()
 
 #[===================================================================[
    xrpld transitive library deps via an interface library
@@ -62,33 +55,31 @@ add_library(xrpl_syslibs INTERFACE)
 add_library(Xrpl::syslibs ALIAS xrpl_syslibs)
 target_link_libraries(
     xrpl_syslibs
-    INTERFACE
-        $<$<BOOL:${is_msvc}>:
-        legacy_stdio_definitions.lib
-        Shlwapi
-        kernel32
-        user32
-        gdi32
-        winspool
-        comdlg32
-        advapi32
-        shell32
-        ole32
-        oleaut32
-        uuid
-        odbc32
-        odbccp32
-        crypt32
-        >
-        $<$<NOT:$<BOOL:${is_msvc}>>:dl>
-        $<$<NOT:$<OR:$<BOOL:${is_msvc}>,$<BOOL:${is_macos}>>>:rt>
-)
+    INTERFACE $<$<BOOL:${is_msvc}>:
+              legacy_stdio_definitions.lib
+              Shlwapi
+              kernel32
+              user32
+              gdi32
+              winspool
+              comdlg32
+              advapi32
+              shell32
+              ole32
+              oleaut32
+              uuid
+              odbc32
+              odbccp32
+              crypt32
+              >
+              $<$<NOT:$<BOOL:${is_msvc}>>:dl>
+              $<$<NOT:$<OR:$<BOOL:${is_msvc}>,$<BOOL:${is_macos}>>>:rt>)
 
-if(NOT is_msvc)
+if (NOT is_msvc)
     set(THREADS_PREFER_PTHREAD_FLAG ON)
     find_package(Threads)
     target_link_libraries(xrpl_syslibs INTERFACE Threads::Threads)
-endif()
+endif ()
 
 add_library(xrpl_libs INTERFACE)
 add_library(Xrpl::libs ALIAS xrpl_libs)

cmake/XrplPackaging.cmake

@@ -1,44 +0,0 @@
-#[===================================================================[
-   Linux packaging support: 'package' target.
-
-   The packaging script (package/build_pkg.sh) installs to FHS-standard
-   paths (/usr/bin, /etc/xrpld, etc.) regardless of CMAKE_INSTALL_PREFIX,
-   so no prefix guard is needed here.
-#]===================================================================]
-if(NOT is_linux)
-    message(STATUS "Packaging not supported on non-Linux hosts")
-    return()
-endif()
-
-if(NOT DEFINED pkg_release)
-    set(pkg_release 1)
-endif()
-
-find_program(RPMBUILD_EXECUTABLE rpmbuild)
-find_program(DPKG_BUILDPACKAGE_EXECUTABLE dpkg-buildpackage)
-
-if(NOT (RPMBUILD_EXECUTABLE OR DPKG_BUILDPACKAGE_EXECUTABLE))
-    message(
-        STATUS
-        "Neither rpmbuild nor dpkg-buildpackage found; 'package' target not available"
-    )
-    return()
-endif()
-
-set(package_env
-    SRC_DIR=${CMAKE_SOURCE_DIR}
-    BUILD_DIR=${CMAKE_BINARY_DIR}
-    PKG_VERSION=${xrpld_version}
-    PKG_RELEASE=${pkg_release}
-)
-
-add_custom_target(
-    package
-    COMMAND
-        ${CMAKE_COMMAND} -E env ${package_env}
-        ${CMAKE_SOURCE_DIR}/package/build_pkg.sh
-    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
-    DEPENDS xrpld
-    COMMENT "Building Linux package (deb/rpm inferred from host tooling)"
-    VERBATIM
-)